Metadata-Version: 2.4
Name: aquin
Version: 0.7.9
Summary: Aquin SDK — stream training metrics and upload checkpoints for analysis
License: MIT
Project-URL: Homepage, https://aquin.app
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# Aquin SDK

Stream training metrics and upload checkpoints for automatic analysis.

## Install

```bash
pip install aquin
```

## Usage

```python
import aquin

run = aquin.Run(
    api_key="aq-...",          # or set AQUIN_API_KEY env var
    run_name="my-lora-run",
    base_model_id="meta-llama/Llama-3.2-1B-Instruct",
)

for step, batch in enumerate(dataloader):
    loss = train_step(batch)
    run.log(step=step, loss=loss.item(), learning_rate=scheduler.get_last_lr()[0])

# Upload checkpoint — triggers SAE diff, model diff, evals on the Aquin VM
run.upload_checkpoint(model, step=step)

run.finish(config={
    "lr": 2e-4,
    "epochs": 3,
    "rank": 8,
    "method": "lora",
})
```

Results appear in the **SDK runs** panel in the Aquin dashboard automatically.

## API

### `aquin.Run(api_key, run_name, base_model_id, base_url)`

Creates a new run. Contacts Aquin to register the run and returns immediately.

### `run.log(step, **metrics)`

Log any scalar metrics for a step. Batched and flushed every 2 seconds in a background thread. Safe to call inside a tight training loop.

### `run.upload_checkpoint(model, step)`

Saves the model state dict and streams it to the Aquin VM. The VM then runs:
- SAE diff (feature activation changes vs. base model)
- Model diff (consistency, suppression, robustness evals)
- Causal tracing

Results are surfaced in the dashboard once analysis completes.

### `run.finish(config, status)`

Marks the run complete and attaches the final config dict. Call once at the end of training.
