Metadata-Version: 2.4
Name: outfigure
Version: 0.2.0
Summary: Python client for the OutFigure API: send learning events and outcomes, read evidence, states and receipts.
Author: Manik Maurya
License-Expression: MIT
Project-URL: Homepage, https://outfigure.in
Project-URL: Documentation, https://outfigure.in/developers/
Keywords: outfigure,learning,assessment,evidence,api-client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# outfigure

The Python client for the [OutFigure](https://outfigure.in) API.

OutFigure keeps three things apart for a learning platform: what a learner did
with help, what they did without it, and whether a change to the teaching moved
the second. This package sends your learning events and outcomes to the API and
reads back evidence, learner states and Outcome Receipts.

The hosted API is a sandbox for invited partners, with test data only. To ask
about a pilot, write to hello@outfigure.in.

## Install

```sh
pip install outfigure
```

Python 3.11 or later. The client uses the standard library only, so it brings
no other packages with it. Use it on your server: an API key never belongs in a
browser.

## Send an event and read the evidence

```python
import os
from datetime import datetime, timezone

from outfigure import OutFigure

client = OutFigure(
    api_key=os.environ["OUTFIGURE_API_KEY"],
    base_url="https://console.outfigure.in",
)

receipt = client.events.send(
    {
        "schema_version": "1.0",
        "event_id": "evt_demo_0001",
        "event_type": "response",
        "learner_id": "learner_demo_01",
        "occurred_at": datetime.now(timezone.utc).isoformat(),
        "source": "partner_backend",
        "session_id": "session_demo_01",
        "item_id": "question_012",
        "item_version": "1",
        "attempt_id": "attempt_demo_01",
        "attempt_number": 1,
        "response_kind": "binary",
        "correct": True,
        "assistance": "none",
        "hint_count": 0,
        "feedback_seen": False,
    },
    idempotency_key="demo-send-0001",
)

client.jobs.wait(receipt["job_ids"], timeout=15)
state = client.learners.state("learner_demo_01")
```

One response is thin evidence. A learner's state on a concept stays
`insufficient_evidence` until it has at least five eligible attempts across two
sessions, and missing data is never turned into a score.

## How it behaves

- Fields use the API's own names (`learner_id`, `item_version`), and requests
  and responses are typed as `TypedDict`s in `outfigure.types`.
- Network failures and 429, 502, 503 and 504 are retried at most three times,
  with the same body and idempotency key, honouring `Retry-After`. Other errors
  are raised as `ApiError` with the code, status and request ID.
- No telemetry, no background work, no local copy of learner data.

The full reference, with every route and scope, is at
[outfigure.in/developers](https://outfigure.in/developers/).

## Licence

MIT. This covers the client only; the OutFigure service is not open source.
