AquinLabs

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.

Prerequisiteaq installed · run aq init (or python -m aquin init) from a writable directory (not inside the aq package tree)

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].

FlagDescription
[name] Folder name. Bare aq init uses aq-run.
example
$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.

FlagDescription
--snapshot Copy the hashed data tree under data/revisions/.
example
$aq data hash --snapshot

aq status

Show last run, last eval, and recent metrics for this run.

example
$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.

layout
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 / keyWho uses itNotes
recipe.yamlkernel / CLI / SDKIdentity. Paths, method, eval gate.
example.pyyouFew-line aquin client from init.
data.pathkernelFile path in YAML (relative to recipe or absolute).
evals/aq evalOptional probes on disk; gate via eval.min_score.
skills/agentOptional skill packs — not scaffolded by init.
artifacts/everythingSystem output.

Artifacts after real work

Everything under artifacts/ is system-owned output.

artifacts
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

  1. Can I copy the folder to another machine and run aq status?
  2. Can I copy the run, change one recipe key, and compare with aq diff?
  3. Can a stranger read recipe.yaml and know the data path and gate?
  4. If artifacts/ is deleted, can I retrain from recipe + data alone?