> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cirron.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ci.watch

> Register a model for weight and gradient snapshots.

Register a model so that framework hooks can capture weight and
gradient snapshots at epoch boundaries. Only needed for **bare PyTorch
loops** (Keras and HuggingFace `Trainer` discover the model from their
callback kwargs automatically).

## Signature

```python theme={null}
def watch(model: Any) -> None
```

## Parameters

| Name    | Type | Purpose                                                      |
| ------- | ---- | ------------------------------------------------------------ |
| `model` | any  | The model to snapshot. Typically an `nn.Module` for PyTorch. |

## When to call

Call **once, before training starts**, after `ci.profile()`:

```python theme={null}
import cirron as ci

ci.profile(snapshots="stats")
ci.watch(model)

for epoch in ci.epochs(range(20)):
    for batch in ci.batches(loader):
        loss = train_step(batch)
```

## When not to call

Skip `ci.watch` when:

* You're using **Keras**: the hook reads `self.model` inside
  `on_epoch_end`.
* You're using **HuggingFace `Trainer`**: the callback receives the
  model via `Trainer.model`.
* You're not capturing snapshots (`ci.profile(enabled=False)`, or
  you simply don't read the snapshot records).

## What it does

Stores a reference to the model on the active profiler. At each
detected epoch boundary (DataLoader iterator exhaustion, `ci.epochs()`
iteration, or callback-reported epoch end), the snapshot subsystem
walks `model.named_parameters()` and writes per-tensor records to the
spool (see [Snapshot schema](/sdk/schemas#snapshots)).

In `snapshots="sampled"` or `"full"` mode, raw tensor values
additionally serialize to
`./.cirron/snapshots/<span_id>/weights.safetensors`.

## Module-level only

`ci.watch` is a **module-level function** only. There is no
`Cirron.watch()` method. If you're working with an explicit `Cirron`
instance, call `cirron.watch(model)` from the module top-level. The
registered model is held on the active profiler singleton.

## Multiple models

Call `ci.watch` multiple times to capture snapshots from more than one
model (e.g. GAN generator + discriminator). Each registered model
contributes its own parameter namespace to the snapshot records.

## Related

<CardGroup cols={2}>
  <Card title="ci.profile" icon="chart-line" href="/sdk/reference/profile">
    The `snapshots=` parameter that controls what watch produces.
  </Card>

  <Card title="Snapshot schema" icon="code" href="/sdk/schemas#snapshots">
    On-disk format for weight and gradient captures.
  </Card>
</CardGroup>