Train folder
A run is a directory with recipe.yaml. Training writes artifacts/. Init scaffolds only that identity — not a skills/tools/jobs/stages forest. Disk is still the source of truth.
aq init [name]
Create a new run folder (default name aq-run, or -newN if taken). Writes recipe.yaml, example.py, and an empty artifacts/ template. Same scaffold: python -m aquin init [name].
| Flag | Description |
|---|---|
| [name] | Folder name. Bare aq init uses aq-run. |
$aq init my-run
$cd my-run
$# edit recipe.yaml → data.path, then:
$python example.py
$# or: aq train && aq eval
Default recipe is tabular/linear. Swap family/method in YAML for LLM, transformers, etc. Paths (data, eval probes, models) are keys in recipe.yaml — relative to the recipe file or absolute. Refuses to init inside the aq package tree.
aq data hash [--snapshot]
Hash recipe.data.path into data/revision.json. Optional --snapshot copies the hashed tree under data/revisions/{digest}/ so run records can answer what data a checkpoint saw.
| Flag | Description |
|---|---|
| --snapshot | Copy the hashed data tree under data/revisions/. |
$aq data hash --snapshot
aq status
Show last run, last eval, and recent metrics for this run.
$aq status
Canonical layout after aq init
Init writes three things. A directory is a run when it has recipe.yaml. Optional experiment.md is a human brief only.
my-run/
recipe.yaml REQUIRED — method, data paths, eval
example.py SDK sample (from init)
artifacts/ runtime — checkpoints, metrics, runs
# optional — you add as needed (not from init)
data.csv / data.jsonl referenced by recipe.data.path
evals/ probes if you use folder-style aq eval
tools/ skills/ packs when you need real code / agent skills
What each piece is for
| Path / key | Who uses it | Notes |
|---|---|---|
| recipe.yaml | kernel / CLI / SDK | Identity. Paths, method, eval gate. |
| example.py | you | Few-line aquin client from init. |
| data.path | kernel | File path in YAML (relative to recipe or absolute). |
| evals/ | aq eval | Optional probes on disk; gate via eval.min_score. |
| skills/ | agent | Optional skill packs — not scaffolded by init. |
| artifacts/ | everything | System output. |
Artifacts after real work
Everything under artifacts/ is system-owned output.
artifacts/
request.json last kernel request (IPC)
result.json last kernel result (IPC)
metrics.jsonl append-only observability stream
checkpoints/
1.json … N.json
last.json always the newest fit
named.json from aq checkpoint --keep
tokenizer.json pinned when model carries a tokenizer
inspect.md human-readable model dump (if method supports it)
runs/
{id}.json / .md
last.json / last.md
eval.json last eval summary
serve.json last serve output
chats/<id>/ agent chat sessions
agents/<id>/ spawned worker agents
jobs/plans/ plan state + run logs
Mental tests
- Can I copy the folder to another machine and run aq status?
- Can I copy the run, change one recipe key, and compare with aq diff?
- Can a stranger read recipe.yaml and know the data path and gate?
- If artifacts/ is deleted, can I retrain from recipe + data alone?