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

# Introduction

> Deep instrumentation for ML training and inference.

# Cirron SDK

The Cirron SDK is the Python-side profiler and data loader for the
Cirron platform. It attaches to your training or serving process and
records what's happening inside it: per-epoch and per-batch timing,
weight and gradient statistics, DataLoader stalls, GPU utilization, and
cost attribution.

It is **not** a model framework, a tracking dashboard, or a registration
client. It is a profiler, plus a thin unified data loader.

## Standalone-usable, platform-amplified

The SDK works on a disconnected laptop, in an air-gapped cluster, or
connected to the Cirron platform. In all three modes it produces the
same artifacts in the same open formats. The relationship to the
platform is the same as `git` to GitHub: Git works without GitHub, the
repo is a portable local artifact, and nobody calls that a lock-in play.

* **Local (SDK alone)**: inspect + export. `ci.profile()` with no
  credentials writes structured JSON span records and safetensors
  snapshots to `./.cirron/`. No proprietary format. Downstream tools
  and the platform ingestion worker both consume this format.
* **Connected (SDK + platform)**: visualize + analyze + collaborate
  * attribute cost. The platform stores, aggregates across runs,
    diffs epoch-over-epoch, attributes dollar cost from the instance
    type it already knows about, streams traces live to the dashboard,
    and gates on team access.

If you stop using Cirron, the `./.cirron/` directory is yours. It's
documented, versioned, and already compatible with any analytics or
observability tool that reads Parquet or OpenTelemetry.

## The wedge

You're 10 epochs into a training run. Loss spikes. Throughput halves.
You want to know why, and you want to know it against every other run
you've done.

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

ci.profile()  # attaches to the process, detects torch, installs hooks

for epoch in range(20):
    for batch in loader:          # DataLoader iteration → batch scopes, automatic
        loss = train_step(batch)  # forward / backward / optimizer_step → scopes, automatic
        ci.mark("loss", loss.item())
```

One line of setup. No scope wrapping, no callbacks, no manual
instrumentation. With no other changes you now get wall time, GPU
seconds, memory peak, per-layer weight and gradient statistics,
DataLoader stall time. When connected to the platform, you also get dollar
cost and epoch-over-epoch diffs against prior runs of the same
pipeline.

## What ships today

* `ci.profile()`: config resolution, framework autodetection, flush
  thread, `cirron.session` root scope
* `ci.scope` / `ci.mark`: lock-free thread-local scope stack + mark
  buffer, `kind="point" | "summary"`
* `ci.epochs` / `ci.batches`: loop wrappers
* Framework hooks: PyTorch, TensorFlow / Keras, HuggingFace
  `transformers`, and opt-in scikit-learn via `ci.wrap()`
* Snapshots: `snapshots="stats" | "sampled" | "full"` with safetensors
  blob writes
* `@ci.inference`: sync and async, per-request `ContextVar` isolation,
  OpenAI / HF LLM detectors (TTFT, throughput, token counts)
* `ci.load()`: local-first dispatcher, scheme routing for
  `s3://` / `gs://` / `azure://` / `file://`, SQL sources for
  `postgres://` / `mysql://` / `databricks://` / `snowflake://`,
  `where=` pushdown, `match=` / `ext=` / `columns=` / `map=`,
  multi-source concat, `lazy=True`, five `as_=` return types
  (`pandas`, `polars`, `iter`, `tensor`, `hf`)
* `ci.env` / `ci.secret` / the `Cirron` configuration class
* `ci.deps`: in-process extras check. Reports installed versions, or
  raises `CirronDependencyError` listing every missing dep with a
  combined `pip install` command

## Start here

<CardGroup cols={3}>
  <Card title="Installation" icon="download" href="/sdk/installation">
    Install the core package and the extras you need.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/sdk/quickstart">
    Three 5-minute paths: zero-touch training, custom loop, inference.
  </Card>

  <Card title="Core concepts" icon="compass" href="/sdk/core-concepts">
    Scope tree, marks, transport, and the local-first spool.
  </Card>
</CardGroup>