Quickstart¶
Three ways to use Kwan: from Python, from the command line, and over a REST API.
Install¶
Kwan needs Python 3.11, 3.12 or 3.13. The core needs only the standard library and networkx.
uv add kwan # the engine
uv add 'kwan[api]' # plus the REST API
From source:
git clone https://github.com/rofyray/kwan.git
cd kwan
uv sync --extra api --extra demo --extra eval --extra curriculum --extra gradio
The bundle¶
Everything Kwan needs for a subject is in one file, the bundle: the skill map, the model parameters, the practice settings and the text templates. For maths it is kwan-bundle.math.json. You can download it from a Kwan release or build it yourself (see Command line).
The bundle for maths ships inside the package, so Kwan.from_bundle() with no path just works. It also holds the learner-model parameters and a record of the datasets they were chosen on (see the Model card), and it refuses to carry parameters fitted on a non-commercial dataset. A bundle comes in one of two text modes:
labels: skills are shown with Kwan's own short labels. This mode needs nothing from NaCCA, and it is the one the project publishes.full: skills also carry the NaCCA descriptions and exemplars.kwan bundlebuilds it only whendata/curriculum/permissions.jsonrecords NaCCA's written permission. See Governance.
Python¶
Load Kwan and record an answer¶
from kwan import Kwan, LearnerState
kwan = Kwan.from_bundle() # the bundle shipped with the package; pass a path to use another one
# The learner id is any opaque string you choose. Never use a name or a phone number.
state = kwan.new_state("pupil-0042")
# The pupil answered a question on skill B1.1.1.1.1 and got it right.
kwan.update(state, "math:B1.1.1.1.1", correct=True)
new_state gives a LearnerState, plain data that records which bundle it was built with. update returns the probability the model gave the answer before seeing it, and takes two optional arguments:
item: the id of the question, if you have an item bank with its difficulty;at: when the answer was given. Pass it if you want forgetting to work.
from datetime import datetime, timezone
kwan.update(
state,
"math:B1.1.1.1.2",
correct=False,
item="q-17",
at=datetime(2026, 11, 10, 9, 30, tzinfo=timezone.utc),
)
Plain codes such as B1.1.1.1.2 are accepted as well as math:B1.1.1.1.2.
Ask what to learn next¶
recommendations = kwan.recommend(
state,
k=3, # how many skills to return
goal="math:B4.1.1.1.2", # optional: a skill to work towards
grade_max=4, # optional: nothing above Basic 4
goal_mode="strict", # "strict" (default) or "soft"
now=datetime.now(timezone.utc), # optional: needed for forgetting and review
)
for rec in recommendations:
print(rec.code, rec.short_label)
print("Why:", rec.rationale)
print("Try it in Ghana:", rec.ghana_context)
Each recommendation carries the skill (indicator is the canonical id math:B1.1.1.1.2, code the bare code), a score, the pupil's current mastery of it, the short label, a reason (rationale), the same reason as translatable parts (rationale_parts), a practice setting (ghana_context), and is_review, which is true for a skill learned before that is starting to fade. rec.to_dict() gives plain data.
With goal_mode="strict", skills on the path to the goal come first. With "soft", the goal is one signal among several.
See the whole picture¶
mastery = kwan.mastery_map(state) # {canonical indicator id: estimated mastery from 0 to 1}
print(mastery["math:B1.1.1.1.1"])
Save and load a learner¶
Learner state is plain data. Keep it wherever you like.
import json
saved = json.dumps(state.to_dict())
state = LearnerState.from_dict(json.loads(saved))
Kwan also comes with two ready-made stores, one in memory and one on SQLite. Every store has a delete operation.
Kwan gives the same output for the same bundle, the same answers and the same now.
Command line¶
Installing Kwan adds the kwan command.
kwan --version
# Curriculum: download the official PDFs, parse them, write the QA report
kwan curriculum fetch
kwan curriculum parse
kwan curriculum qa
# Skill map: build it, suggest extra links, and exchange review sheets with teachers
kwan graph build
kwan graph augment --dry-run
kwan graph review-export
kwan graph review-import
# Evidence: evaluate on a dataset, run the simulator, time the recommender
kwan eval <dataset>
kwan sim --out data/eval_results.json
kwan bench
# Bundle: write kwan-bundle.math.json
kwan bundle --subject math --text labels --out build/bundles/
Some commands need extra packages: kwan curriculum needs kwan[curriculum], and kwan eval needs kwan[eval]. The command tells you what to install if something is missing. Run kwan <command> --help for the options of each command.
There are a few more: kwan graph validate checks the map and writes the skill map report, kwan fit chooses the forgetting time, the step sizes and the item banks on the public datasets, and kwan context runs the checks on practice settings, writes and imports teacher review sheets, and reports coverage. kwan --help lists them all. After any command that changes data/eval_results.json, uv run scripts/fill_docs.py refreshes the result tables in the README and the docs.
kwan curriculum fetch downloads the NaCCA PDFs to your machine. They are © NaCCA, Ministry of Education. Do not commit them or text taken from them.
REST API¶
The API is an optional extra. It keeps learner state in a SQLite file by default (kwan.sqlite3 in the working directory; set KWAN_STORE=sqlite:///path/to/file or KWAN_STORE=memory to change that).
Start the server¶
uv add 'kwan[api]'
export KWAN_API_KEYS="change-me-to-a-long-random-string"
uv run uvicorn kwan.api.app:app --port 8000
Every request except /v1/health must carry one of the keys in KWAN_API_KEYS in the X-API-Key header. When KWAN_API_KEYS is not set the API logs a warning and accepts every request, which is fine on your own machine only.
Routes¶
| Method | Path | What it does |
|---|---|---|
GET |
/v1/health |
Says the service is up |
GET |
/v1/skills |
Every skill with a short label, for goal pickers and search |
POST |
/v1/attempts |
Records one answer |
GET |
/v1/learners/{id}/recommendations |
The next skills for a learner |
GET |
/v1/learners/{id}/mastery |
The estimated mastery of every skill |
DELETE |
/v1/learners/{id} |
Forgets a learner |
Example¶
KEY="change-me-to-a-long-random-string"
curl -s localhost:8000/v1/health
curl -s -H "X-API-Key: $KEY" "localhost:8000/v1/skills?grade=4&q=fractions%20order"
curl -s -X POST localhost:8000/v1/attempts \
-H "X-API-Key: $KEY" -H "content-type: application/json" \
-d '{"learner_id": "pupil-0042", "indicator": "math:B1.1.1.1.1", "correct": true}'
curl -s -H "X-API-Key: $KEY" \
"localhost:8000/v1/learners/pupil-0042/recommendations?k=3&goal=math:B4.1.3.2.1"
curl -s -H "X-API-Key: $KEY" localhost:8000/v1/learners/pupil-0042/mastery
curl -s -X DELETE -H "X-API-Key: $KEY" localhost:8000/v1/learners/pupil-0042
Goals for people¶
People never type a skill code. GET /v1/skills returns every skill with a short label (filter with grade, strand and q, e.g. ?grade=4&q=fractions order); show the short_label in a dropdown or search box and send the id as goal. Each recommendations response echoes the goal with its label. In Python, engine.skills(grade=4, q="fractions order") and engine.label(id) do the same.
A learner id needs no registration. A pupil the API has never seen gets starting recommendations. Send an idempotency_key with each attempt (or an Idempotency-Key header) and a retried request is applied once. Interactive documentation is served at /docs while the server runs. The Round 1 routes (/attempt, /recommend/{id}, ...) still answer, with a Deprecation header and a Link to the v1 route that replaces them.
Keep pupils safe¶
- Use learner ids that mean nothing outside your system. Never a name, a phone number or an index number.
- Kwan stores no names, emails or free text. Do not add them to requests.
- Delete a learner's state when it is no longer needed.
More on this in the Model card.
Next steps¶
- Method: how the map, the learner model and the recommender work.
- Evidence: how well it works.
- Context style guide: how practice settings are written.
- CONTRIBUTING.md: how to help.