Train folder

A train is a directory. If it has instructions.md and recipe.yaml, aq treats it as a real unit of work. aq init scaffolds the layout; disk is the source of truth.

Prerequisiteaq installed · run aq init from a writable directory (not inside the aq package tree)

aq init [dir]

Create a skeleton train from aq/templates/. Writes instructions.md, recipe.yaml, optional train.ts, and empty slots (data, evals, methods, tools, skills, memory, sandbox, connections, schedules, stages, jobs, artifacts) with .keep files.

Flag	Description
[dir]	Target directory. Defaults to cwd.

example

$aq init my-train

example

$cd my-train

Creates instructions.md, recipe.yaml, optional train.ts, and empty slots (data, evals, methods, tools, skills, memory, sandbox, connections, schedules, stages, jobs, artifacts) with .keep files. Default template recipe is LLM LoRA. Change recipe.yaml for tabular or transformers. Refuses to init inside the aq package tree.

aq fork <dest>

Copy a train to try a variant. Skips jobs/ and artifacts/, then recreates empty ones so the child starts clean.

Flag	Description
aq fork <src> <dest>	Copy a train that is not cwd.

example

$aq fork ../clinic-ridge

example

$cd ../clinic-ridge

example

$aq train

example

$aq eval

aq checkout <id> [dest]

Restore a job's captured tree/ into cwd (or a new dest). Time-travel a workspace snapshotted at enqueue.

example

$aq job run --cpu 4 --ram 8G -- aq train

example

$aq checkout <job-id> recovered-train

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

example

$aq data hash --snapshot

aq status

Show jobs, last run, last eval, recent metrics, and schedules for this train.

example

$aq status

Canonical layout after aq init

aq init copies templates and creates optional slots with .keep files. A directory is a train when it has both instructions.md and recipe.yaml.

layout

my-train/  instructions.md          REQUIRED - what this train is for  recipe.yaml              REQUIRED - kernel spec (aq does not override)  train.ts                 OPTIONAL - placeholder; aq does not read yet   data/                    your datasets (path from recipe)  evals/                   user probes (.csv / .jsonl) - no bundled zoo  methods/                 optional train-local fit adapters (override kernel)  tools/                   scripts: tools/<name>.{py,ts,js,sh}  skills/                  agent skills (+ optional MCP)  memory/                  agent memory markdown  sandbox/                 scratch for agent / tools  connections/             connection defs (slot)  schedules/               yaml/json schedules  stages/                  nested trains (each is itself a train)  jobs/                    SYSTEM - process queue state  artifacts/               SYSTEM - checkpoints, metrics, runs, chats, …

What each slot is for

Slot	Who uses it	Notes
instructions.md	human / agent	Brief: what this train proves and what success looks like.
recipe.yaml	kernel	Full train API for built-ins. CLI does not invent hyperparameters.
data/	kernel	Datasets; recipe.data.path often points here.
evals/	aq eval	One file per probe. Gate via eval.min_score.
methods/	kernel loader	{name}.py wins over kernel/methods/{name}.py.
tools/	aq tool / agent	Executable helpers with AQ_TRAIN set.
skills/	agent	SKILL.md / run scripts / mcp.json.
memory/	agent	Searchable markdown notes.
schedules/	aq schedule	cron, sweep, resume, pipeline, agents.
stages/	aq stage	Nested full trains.
jobs/	job system	Do not hand-edit casually. Fork skips this.
artifacts/	everything	System output. Fork skips this; regenerable but valuable.

Artifacts after real work

Everything under artifacts/ is system-owned output. Forking skips jobs/ and artifacts/ so the child starts clean. If artifacts/ is deleted, you can retrain from recipe + data alone.

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  schedules/               schedule run logs

Mental tests

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