Recipe loop

The spine of AQIT is five objects: Recipe, DataRevision, Run, Checkpoint, EvalGate. They are the same in YAML, on disk, in the CLI, and in the SDK.

Objects

Object	Meaning
Recipe	YAML/JSON: name, family (tabular | llm), data, train, eval
DataRevision	Content hash of the data file, optional snapshot under aquin_run/revisions/
Run	One attempt: ./aquin_run/runs/<id>/
Checkpoint	Weights from that run (sklearn joblib, LoRA adapter, …)
EvalGate	Pass or fail on a metric / probe set

flowchart LR
  YAML[recipe.yaml] --> Load[load_recipe]
  Load --> Rev[capture_revision]
  Rev --> Train{family}
  Train -->|tabular| Tab[linear / boosting]
  Train -->|llm| LoRA[LoRA / QLoRA]
  Tab --> CK[Checkpoint]
  LoRA --> CK
  CK --> Gate[EvalGate]
  Gate --> Rec[RunRecord]

Families and methods

Validated in aquin.recipe.schema:

Family	train.method	Extra requirements
tabular	linear, boosting	data.target, train.task ∈ {classification, regression}
llm	lora	train.base (Hugging Face id)

On-disk layout

Root: ./aquin_run/ (aquin.recipe.store.RUN_ROOT_NAME).

aquin_run/
  revisions/<rev_id>/     DataRevision + optional snapshot
  runs/<run_id>/          RunRecord JSON, metrics, checkpoint
  checkpoints/            Used by aquin.init() recorder

Tabular Recipe

name: churn-v3
family: tabular
data:
  path: data/churn.csv
  target: churned
  snapshot: true
train:
  method: boosting
  task: classification
eval:
  metric: f1
  min_score: 0.82

LLM LoRA Recipe

name: llama-adapter
family: llm
data:
  path: data/sft.jsonl
train:
  method: lora
  base: meta-llama/Llama-3.2-1B-Instruct
eval:
  metric: custom

Paths in the Recipe are resolved relative to the YAML file (aquin.recipe.load).

Train

aqit train recipe.yaml
aqit train recipe.yaml --dry-run

import aqit
record = aqit.train.run("recipe.yaml")
print(record["gate"]["passed"], record["run_id"])

aquin.recipe.train.train_recipe:

1. Load + validate Recipe.
2. Hash (and optionally snapshot) the data file → DataRevision.
3. Allocate runs/<id>/ and a RunRecord.
4. Dispatch train_tabular or train_llm.
5. Write checkpoint + EvalGate; status becomes passed / failed / failed with error.

Manual recorder

If you already have a training loop, wrap it:

import aquin
 
run = aquin.init(
    base_model="meta-llama/Llama-3.2-1B-Instruct",
    run_name="my-run",
    config={"lr": 2e-4, "epochs": 3},
)
for step, batch in enumerate(dataloader):
    loss = train_step(batch)
    run.log(step, loss=loss.item())
run.checkpoint(model, step=step)
run.finish()

That writes the same ./aquin_run/ tree the Recipe path uses.

After a failed gate

aqit eval custom --prompts probes.jsonl
aqit trace --prompt "the failing case" --layer 8
aqit diff weight --checkpoint ./aquin_run/runs/<id>/checkpoint
aqit steer --feature_idx 42 --strength 2.0

Inspect is for failed gates. A passing gate is the product; a trace is the debug tool.