Maintainer tasks¶
The jobs only a maintainer can do because they need an account, a secret or a person: releasing, the demo
Space, teacher review, and the decision model for extra skill links. The first two are one-time set-up;
the last two are ongoing work with no deadline. Every command runs from a source checkout after
uv sync --extra api --extra demo --extra eval --extra curriculum --extra gradio.
| Task | When | Needs |
|---|---|---|
| Release to PyPI | each release | the pypi trusted publisher (set up once) |
| Demo Space | set up once, then automatic | a Hugging Face account and token |
| Teacher review | ongoing, before the drafts can show by default | teachers who review sheets |
| Decision model | later, when a provider is chosen | an API key for a chat model |
| NaCCA permission | once | the letter in Governance |
Release to PyPI¶
Set up once: on pypi.org, add a pending trusted publisher with project kwan, owner rofyray, repository
kwan, workflow release.yml and environment pypi; on GitHub, create the environment pypi (Settings,
Environments).
For each release:
-
Set the version in
src/kwan/_version.py(for example1.0.0). Then rebuild the bundle so itsbundle_versionmatches, refresh the docs, and run the checks:make bundle fill-docs test lint -
Move the
Unreleasednotes inCHANGELOG.mdunder the new version and date, updateversioninCITATION.cff, commit and push tomain, and wait for CI to pass. -
Tag the commit and push the tag:
git tag v1.0.0 && git push origin v1.0.0
release.yml checks that the tag matches the package version, runs the tests, builds with uv build,
publishes to PyPI, creates the GitHub release with the bundle and eval_results.json attached, and then
starts space-deploy.yml. If the Space is not set up yet, that last step says so and stops without failing.
Demo Space on Hugging Face¶
The public demo is a Gradio Space, which runs on the free plan (Docker Spaces are paid). The app is
demo/gradio_app.py; the Streamlit app with demo/Dockerfile stays for anyone who hosts it in Docker.
Set up once:
- On huggingface.co, choose New Space: owner
rofyray, namekwan, SDK Gradio, template Blank, hardware CPU Basic (free; Kwan needs no GPU, and the free ZeroGPU option also works), visibility Public. Create it empty: the workflow uploads every file. - Under Settings, Access Tokens, create a fine-grained token with write access to the Space
rofyray/kwan(nothing else). - In the GitHub repository, open Settings, Secrets and variables, Actions. Add the repository secret
HF_TOKEN(the token) and, on the Variables tab, the variableHF_SPACE=rofyray/kwan. - Open Actions, space-deploy, Run workflow on
main. It builds the wheel, uploadsapp.py, thekwanpackage, the results file,README.md(the Space settings) andrequirements.txt, waits up to ten minutes for the Space to answer, and runsdemo/gradio_smoke_test.pyagainst it in a browser.
After that, every published release deploys the Space again. To try the Gradio app on your machine:
make app-gradio
Documentation site¶
The site at https://rofyray.github.io/kwan/ is built from docs/ by docs.yml on every push and published
on every push to main (or by hand: Actions, docs, Run workflow). Pages must use the source
GitHub Actions (Settings, Pages); it was switched on once with:
gh api -X POST repos/rofyray/kwan/pages -f build_type=workflow
Teacher review¶
Ongoing. The 828 practice settings and 276 short labels are drafts written for Kwan; until a teacher approves one, Kwan shows the general setting for the strand and class band, and the demo shows drafts only behind a labelled switch. The Teacher review guide is what you send to reviewers; this is the maintainer's side.
-
Write a review sheet (100 settings and labels per sheet;
--grade 4for one class,--batch 2for the next sheet,--allfor every sheet):uv run kwan context review-export --out-dir build/review -
Send the CSV to a teacher. They fill in the decision and note columns and send it back.
-
Check what the sheet would change, then apply it:
uv run kwan context review-import build/review/filled.csv --dry-run uv run kwan context review-import build/review/filled.csv -
Rebuild the bundle, refresh the docs and commit the changed files under
data/contexts/, the bundle and the docs:make bundle fill-docs -
Credit the reviewer in
CONTRIBUTORS.mdif they agree to be named.
Skill links proposed by the decision model are reviewed the same way, with
uv run kwan graph review-export and uv run kwan graph review-import <sheet> --reviewer <id>. Today
there are 4 proposed links, none reviewed. Translations (Twi, Ewe, Ga) use
uv run kwan context review-export --lang tw; none are drafted yet.
uv run kwan context coverage shows how much is drafted, checked, reviewed and translated.
Decision model for extra skill links¶
Later, once you choose a provider. The rule-based skill map is complete and is what Kwan ships. A decision model can propose extra links between strands (for example, a measurement skill that needs a fractions skill). The only model that runs without a key, a local sentence encoder, reached 0.31 precision on the Junyi benchmark, below the 0.80 bar, so nothing it proposed ships.
-
Choose any service with an OpenAI-style chat completions endpoint (a hosted model, or a local server such as Ollama). Set three environment variables; the key stays on your machine:
export KWAN_LLM_ENDPOINT="https://example.com/v1/chat/completions" export KWAN_LLM_MODEL="model-id" export KWAN_LLM_API_KEY="your-key" -
Download the Junyi benchmark and the curriculum PDFs, and parse the full curriculum text. The full text stays in the git-ignored
build/folder:bash scripts/download_data.sh junyi uv run kwan curriculum fetch && uv run kwan curriculum parse -
Measure the model on Junyi first. It must reach 0.80 precision:
uv run kwan graph augment --provider llm-json --junyi raw/junyi --results data/eval_results.json -
If it passes, propose links on the NaCCA curriculum. They are written to
data/graph/math.augmented.jsonas pending and do not reach learners until a reviewer accepts them:uv run kwan graph augment --provider llm-json --results data/eval_results.json -
Review the proposed links with teachers (see Teacher review), then run
make graph bundle fill-docsand commit.
Calls are cached in build/augment/cache.jsonl, so a rerun costs nothing for pairs already asked.