> ## 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.

# Quickstart

> Three 5-minute paths: PyTorch training, sklearn, inference.

## 1. Zero-touch training

`ci.profile()` alone auto-detects Keras or HuggingFace `Trainer` and
produces the full scope tree without any loop changes.

<CodeGroup>
  ```python Keras theme={null}
  import cirron as ci
  import tensorflow as tf

  ci.profile()

  model = tf.keras.Sequential([...])
  model.compile(optimizer="adam", loss="mse")
  model.fit(X, y, epochs=20)   # epoch / batch scopes + metric marks, automatic
  ```

  ```python HuggingFace theme={null}
  import cirron as ci
  from transformers import Trainer, TrainingArguments

  ci.profile()

  trainer = Trainer(model=model, args=TrainingArguments(...), train_dataset=ds)
  trainer.train()              # epoch / step scopes + logged metrics, automatic
  ```
</CodeGroup>

When running disconnected, traces land at `./.cirron/spool/*.json`. When
a `CIRRON_API_KEY` is set (or you're running inside a Cirron pipeline),
they stream to the platform in parallel.

To inspect traces inline without leaving Python:

```python theme={null}
ci.trace()                # text scope tree
ci.trace(format="df")     # one row per span (requires pandas)
```

To stream a live `[cirron]` line per closed span to your terminal:

```python theme={null}
ci.profile(output="stdout")
```

See [`ci.trace`](/sdk/reference/trace) and
[`output=`](/sdk/reference/profile#output-sinks) for the full
surface.

## 2. Custom PyTorch loop

If your loop is hand-rolled (no Keras, no `Trainer`), wrap the iterables
with `ci.epochs()` and `ci.batches()`: they yield exactly what the
inner iterable yields but add indexed `epoch` / `batch` scopes around
each iteration.

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

ci.profile()
ci.watch(model)   # bare PyTorch loops only, Keras / HF Trainer skip this

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

Torch forward / backward / optimizer\_step hooks still fire underneath,
so `epoch → step → {data_load, forward, backward, optimizer_step}` is
produced automatically. `ci.batches(loader)` additionally measures
DataLoader stall time when `loader` is a `torch.utils.data.DataLoader`.

Use `ci.scope` for regions the hooks don't cover, and `ci.mark` to log
scalar values into the innermost open scope:

```python theme={null}
with ci.scope("augmentation"):
    batch = augment(batch)

ci.mark("grad_norm", compute_grad_norm(model))
ci.mark("learning_rate", scheduler.get_last_lr()[0])
```

## 3. Inference

`@ci.inference` binds your serving function to a deployment record.
Per-request scope isolation uses `contextvars`, so FastAPI, Flask, ASGI,
and plain threaded servers all work.

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

@ci.inference
def predict(request):
    with ci.scope("preprocess"):
        x = preprocess(request)
    with ci.scope("model"):
        y = model(x)
    with ci.scope("postprocess"):
        return format_response(y)
```

For LLMs, the SDK detects OpenAI-compatible clients and HuggingFace
`generate()` automatically: token counts, time-to-first-token, and
throughput marks appear without extra code.

## Where to look

All three paths write to the same place:

```
./.cirron/
  spool/
    <created_ns>-<batch_id>.json  # one batch per flush
  snapshots/
    <span_id>/
      weights.safetensors         # sampled / full snapshots, when enabled
```

The schema is documented in [Schemas](/sdk/schemas) and is stable
within a major SDK version. Any tool that reads JSON and safetensors
can consume it.

## Next steps

<CardGroup cols={2}>
  <Card title="Core concepts" icon="compass" href="/sdk/core-concepts">
    Scope tree model, marks, transport selection, framework hook
    priority.
  </Card>

  <Card title="Profiling" icon="chart-line" href="/sdk/profiling">
    The full training instrumentation surface.
  </Card>

  <Card title="Inference" icon="server" href="/sdk/inference">
    `@ci.inference` in depth, LLM detection, config-driven capture.
  </Card>

  <Card title="Data loading" icon="database" href="/sdk/data-loading">
    `ci.load()`: unified data access across local, cloud, and SQL.
  </Card>
</CardGroup>