aquin 0.2.3

Aquin CLI. Run GPU inspection, steering, simulation, and evals locally with aquin connect, aquin load, aquin chat, and aquin inspect.

Aquin SDK

Record your training runs locally and observe them with Aquin — loss curves, learning rate, grad norm, epoch summaries, and web mirror sync via aquin connect + aquin watch.

Install

pip install aquin

Quickstart

import aquin

run = aquin.init(
    base_model="meta-llama/Llama-3.2-1B-Instruct",
    run_name="my-lora-run",
    config={
        "lr": 2e-4, "epochs": 3, "rank": 16, "lora_alpha": 32,
        "method": "qlora", "per_device_train_batch_size": 2,
        "gradient_accumulation_steps": 8, "dataset": "data.jsonl",
    },
)

for epoch in range(3):
    for step, batch in enumerate(dataloader):
        loss = train_step(batch)
        grad_norm = torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0).item()
        run.log(
            step,
            loss=loss.item(),
            learning_rate=scheduler.get_last_lr()[0],
            grad_norm=grad_norm,
            epoch=epoch,
        )

run.checkpoint(model, step=step)
run.finish()

Then replay or sync to the web mirror:

aquin watch <run_id>              # local replay / live tail
aquin connect                     # register engine + session
aquin watch ingest --run <run_id> --file aquin_run/metrics.jsonl

With an active session, watch events appear on the Aquin web mirror in real time.

Post-training SAE (checkpoint diff, temp train, align)

After run.checkpoint() saves aquin_run/checkpoints/checkpoint.pt, run SAE tools on the real merged weights (not simulate's synthetic checkpoint):

aquin connect --device my-gpu --name my-run
aquin load --model llama-3.2-1b
aquin pull sae llama-3.2-1b-l8

aquin sae diff --model llama-3.2-1b \
  --checkpoint aquin_run/checkpoints/checkpoint.pt \
  --prompts probes.jsonl --name my-run

aquin sae train --model llama-3.2-1b --layer 8 \
  --checkpoint aquin_run/checkpoints/checkpoint.pt \
  --quick --name my-run

aquin sae align \
  --sae-a ~/.aquin/sae/llama-3.2-1b/sae_layer8.pt \
  --sae-b ~/.aquin/sae/user/llama-3.2-1b/my-run/sae_layer8.pt

Docs: Checkpoint SAE. Watch ingests metrics only; simulate diffs a synthetic NTK checkpoint at forecast end.

API

aquin.init(base_model, run_name, config)

Starts a new run. Creates aquin_run/ in the current directory.

Param	Description
base_model	HuggingFace model ID, e.g. "meta-llama/Llama-3.2-1B-Instruct"
run_name	Display name for the run
config	Dict of training hyperparameters (optional, can also pass to finish())

run.log(step, *, loss, ...)

Record metrics for one training step. Call every step inside your loop.

Param	Description
step	Global training step (required)
loss	Scalar training loss (required)
learning_rate	Current LR — enables LR chart
grad_norm	Gradient norm — enables grad norm chart
epoch	Current epoch — enables epoch summary table
momentum_norm	Optimizer momentum norm — enables momentum chart
step_ms	Wall-clock time for this step in ms

run.checkpoint(model, step)

Saves the model checkpoint locally. One checkpoint per run — always replaces the previous save. Call once at the end of training. Stored under aquin_run/checkpoints/ for local analysis.

run.finish(config)

Flushes all metrics to disk. Pass config here if you didn't pass it to aquin.init().

CLI

aquin login       # save your API key
aquin connect     # connect engine for web sync
aquin watch list  # list observed training runs
aquin sae help    # checkpoint SAE diff / train / align
aquin help        # full command list (mode-filtered)
aquin whoami      # check which account you're logged in as

Using with HuggingFace Trainer / TRL

Use a TrainerCallback to hook into the training loop:

import time
from transformers import TrainerCallback

class AquinCallback(TrainerCallback):
    def __init__(self, run):
        self.run = run
        self._step_start = 0.0

    def on_step_begin(self, args, state, control, **kwargs):
        self._step_start = time.time()

    def on_log(self, args, state, control, logs=None, **kwargs):
        if not logs or "loss" not in logs:
            return
        self.run.log(
            step=state.global_step,
            loss=float(logs["loss"]),
            learning_rate=float(logs["learning_rate"]) if "learning_rate" in logs else None,
            grad_norm=float(logs["grad_norm"]) if "grad_norm" in logs else None,
            epoch=int(state.epoch) if state.epoch is not None else None,
            step_ms=round((time.time() - self._step_start) * 1000),
        )

    def on_train_end(self, args, state, control, **kwargs):
        model = kwargs.get("model")
        if model:
            self.run.checkpoint(model, step=state.global_step)

---

Building and publishing a new release

Prerequisites: Python 3.13, Nuitka, MSVC (Visual Studio Build Tools with Desktop C++ workload).

1. Compile to native extensions

cd cli
python scripts/build_nuitka.py
# Compiles engine/ + compute/ to .pyd, removes .py source, audits on finish

2. Build the wheel

python -m build --wheel
# Output: dist/aquin-<version>-py3-none-any.whl

3. Audit — confirm no source leaked

python scripts/build_nuitka.py --check
# Must print: Audit passed

4. Bump version before releasing Edit version in pyproject.toml, then repeat steps 1–3.

5. Distribute Send the wheel directly to users (pip install aquin-*.whl) or upload to R2 and share a signed link.

Notes:

• .pyd files and dist/ are gitignored — never commit compiled artifacts
• After building, engine/ and compute/ have no .py source locally either — keep a clean git working tree by running builds in a separate branch or restoring source from git after building
• To rebuild from scratch: git restore cli/aquin/engine cli/aquin/compute then repeat from step 1