Quickstart - Cirron Documentation

1. Zero-touch training

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

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

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

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:

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:

ci.profile(output="stdout")

See ci.trace and output= 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.

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:

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.

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 and is stable within a major SDK version. Any tool that reads JSON and safetensors can consume it.

Next steps

Core concepts

Scope tree model, marks, transport selection, framework hook priority.

Profiling

The full training instrumentation surface.

Inference

@ci.inference in depth, LLM detection, config-driven capture.

Data loading

ci.load(): unified data access across local, cloud, and SQL.

​1. Zero-touch training

​2. Custom PyTorch loop

​3. Inference

​Where to look

​Next steps