Getting started
Aquin is a developer environment and framework for building and checking models. The shape is SDK + recipe.yaml + artifacts/. Paths to data and evals live in the YAML. You run aquin or aq against that folder and keep enough on disk to resume and audit. Disk is the source of truth. The UI is a view.
How the pieces fit
| Name | What it is |
|---|---|
| Aquin | The product: developer environment and framework. |
| aquin | Python SDK (pip install -e ./aq). Few-line client over the same kernel. |
| aq | The CLI you type (TypeScript). Quiet, cwd-based, like git. |
| Kernel | Python under aq/kernel/. Fit, eval, serve, hash. Talks through files. |
| Run | A directory with recipe.yaml (+ artifacts/ once you train). Optional brief: experiment.md. |
| axi | The agent (separate package). Same train cwd/files/verbs via the aq CLI. Not a side chat FS. |
Flow: edit the recipe (and data paths), train/eval via SDK or CLI, artifacts land on disk. Accounts live at aquin.app/login/ — identity and tokens only. Sign in.
SDK (few lines)
YAML and SDK are both optional authoring surfaces for the same path map. Edit recipe.yaml by hand, or use Aquin.define / Run (which rewrite that file). artifacts/ is always runtime.
$python -m aquin init my-run
$cd my-run && python example.py
$# or: aq train && aq eval
from aquin import Aquin
aq = Aquin(".") # reads recipe.yaml
aq.train()
aq.eval()
from aquin import Aquin
aq = Aquin.define(
family="tabular", method="linear",
data={"path": "data.csv", "target": "y"},
eval={"metric": "mse"},
config_path="recipe.yaml",
)
aq.train()
Same path map either way — edit YAML by hand or author with Aquin.define / Run.
What init creates
aq init / python -m aquin init scaffolds a seed path map + sample. Author by editing YAML, using the SDK, or both.
my-run/
recipe.yaml path map — edit by hand and/or via SDK
example.py opens YAML by default; define path commented
artifacts/ runtime (checkpoints, metrics, …)
Optional later: your own data file, eval probes, skills packs. Full layout: Train folder.
CLI
aq is the face. Cwd is the workspace. Verbs compose: aq train, aq eval, aq serve, aq status. Reference: CLI.
Kernel (Python)
TypeScript and Python talk through files:
- CLI writes
artifacts/request.json - Spawns
kernel/run.pyon the run path - Kernel runs the op (
hash,train,eval,checkpoint,serve) - Writes
artifacts/result.jsonand appendsmetrics.jsonl
For built-ins you do not write Python. recipe.yaml is the API. See Recipe.
What “working” means
A stranger should point data.path at their file, set the gate, run train then eval, fail, inspect, edit one key, and run again. No preset eval zoo — you write the probes.
SSH fleet
Same folder on remote boxes: register a place, launch or aq jobs … --on, then scale with a pool. Walkthrough: SSH fleet.
$aq add ssh temp
$aq launch --on temp
$aq jobs train --on temp
$aq add pool gpus temp other
$aq jobs train --on gpus