Architecture

AQIT is a thin public surface over a compute engine. The CLI and SDK call the same functions.

Layers

flowchart TB
  subgraph public [Public: package aqit]
    CLI["cli.py  ·  aqit <verb>"]
    SDKA["__init__.py  ·  import aqit"]
  end

  subgraph engine [Engine: package aquin  <-  interp-engine/]
    SDK["aquin.sdk"]
    Recipe["aquin.recipe"]
    Compute["aquin.compute"]
    Eng["aquin.engine"]
    TUI["aquin.tui"]
    CLI2["aquin.cli + *_cli.py"]
  end

  CLI --> CLI2
  SDKA --> SDK
  CLI2 --> SDK
  SDK --> Recipe
  SDK --> Compute
  SDK --> Eng
  Recipe --> Compute
  Eng --> Compute
  TUI --> CLI2

setup.py is the only package map:

aqit  →  .
aquin →  interp-engine

So from aquin.sdk import train reads interp-engine/sdk/train.py.

Data flow

Every user-facing verb eventually hits one of:

1. Recipe spine: aquin.recipe.train.train_recipe writes under ./aquin_run/.
2. SDK runtime: aquin.sdk._runtime.invoke / invoke_direct (same path the CLI uses).
3. Compute: aquin.compute.* (trace, SAE, evals, steer, diffs, simulate).
4. Engine daemon: aquin.engine.local_server on 127.0.0.1 (default port 17832) so a desktop/web client can call GPU tools without a VM.

sequenceDiagram
  participant User
  participant CLI as aqit CLI
  participant SDK as aquin.sdk
  participant RT as _runtime
  participant Comp as aquin.compute
  participant Disk as ./aquin_run

  User->>CLI: aqit train recipe.yaml
  CLI->>SDK: train.run(...)
  SDK->>Disk: DataRevision + RunRecord
  SDK->>Comp: tabular / LoRA
  Comp-->>Disk: Checkpoint + EvalGate

  User->>CLI: aqit trace --prompt …
  CLI->>SDK: inspect.trace(...)
  SDK->>RT: invoke("run_full_inspection")
  RT->>Comp: causal_trace / SAE
  Comp-->>User: JSON + optional PNG

Directory map

Path	Package	Job
cli.py, __init__.py	aqit	Public CLI + SDK re-exports
interp-engine/sdk/	aquin.sdk	Stable Python API
interp-engine/recipe/	aquin.recipe	YAML Recipe, revisions, gates
interp-engine/compute/	aquin.compute	Models, SAE, evals, steer
interp-engine/engine/	aquin.engine	Daemon, tools, session
interp-engine/tui/	aquin.tui	Textual / Ink bridge
interp-engine/*_cli.py	aquin	One verb per file

Design rules

• One loop. A feature ships if it makes train → gate → (inspect on fail) faster or more trusted.
• Lazy imports. import aquin does not pull torch. GPU stacks load inside the verb.
• CLI is argv/print. Logic lives in SDK and Compute.
• Local first. Cloud tokens are optional. The engine runs on the host GPU.
• Artifacts on disk. Runs, checkpoints, and gates live under ./aquin_run/.