Installation - Cirron Documentation

Requirements

Python 3.11 or newer. The SDK uses tomllib from the standard library.

Core install

pip install cirron-sdk

The core install is minimal: no pandas, no polars, no ML framework dependency. It gives you the profiler, scope tree, marks, loop wrappers, flush thread + local spool, @ci.inference, ci.env, ci.secret, and the Cirron configuration class.

Extras

Framework hooks and data-loader backends are opt-in extras so you only pull what you use.

Extra	Adds
`pandas`	pandas backend for `ci.load()` (the default return type)
`polars`	polars backend for `ci.load(as_="polars")`
`arrow`	PyArrow, faster Parquet reads for any filesystem source
`hf`	`datasets.Dataset` return type for `ci.load(as_="hf")`
`torch`	PyTorch profiling hooks (forward / backward / optimizer / DataLoader)
`tensorflow`	TensorFlow / Keras profiling hooks (Callback-based)
`transformers`	HuggingFace `Trainer` callback hooks + LLM detectors
`sklearn`	Version floor for `ci.wrap()` (`scikit-learn >= 1.3`)
`image`	Pillow, image decode for `ci.load()` image sources
`s3`	`ci.load("s3://...")` via boto3
`gcs`	`ci.load("gs://...")` via `google-cloud-storage`
`azure`	`ci.load("azure://...")` via `azure-storage-blob`
`postgres`	`ci.load("postgres://...")`
`mysql`	`ci.load("mysql://...")`
`databricks`	`ci.load("databricks://...")`
`snowflake`	`ci.load("snowflake://...")`
`sql`	All four SQL drivers
`dotenv`	`python-dotenv`: `.env` loading in `ci.env()`
`safetensors`	safetensors reader, inspect snapshot blobs locally
`all`	Every extra above

pip install "cirron-sdk[torch,pandas]"
pip install "cirron-sdk[transformers]"
pip install "cirron-sdk[sql]"
pip install "cirron-sdk[all]"

uv add "cirron-sdk[torch,pandas]"
uv add "cirron-sdk[transformers]"
uv add "cirron-sdk[sql]"
uv add "cirron-sdk[all]"

Install multiple extras at once by comma-separating them inside the brackets.

Authentication

Authentication is optional; the SDK runs standalone without it. To sync traces to the Cirron platform, set an API key:

export CIRRON_API_KEY=...
export CIRRON_API_ENDPOINT=https://app.cirron.com   # optional; default shown

Inside a Cirron pipeline or deployment, the CIRRON_RUN_ID / CIRRON_PIPELINE_ID / CIRRON_DEPLOYMENT_ID / CIRRON_WORKSPACE_ID context is injected by the runner. You do not set these yourself. See Configuration for the full resolution order (explicit args → env vars → ~/.cirron/config.toml → defaults) and self-hosted endpoints.

Verify

import cirron as ci

p = ci.profile()
print(p.health())
ci.shutdown()

You should see a dict roughly like this (exact keys and values depend on what’s installed and whether you have a CIRRON_API_KEY set):

{
    "enabled": True,
    "frameworks_installed": [],            # ["torch"] / ["transformers", "torch"] / ...
    "transport": "file_only",              # or "http" / "event_stream"
    "scope_depth": 1,                      # the cirron.session root scope
    "mark_drop_count": 0,
    "spool_drop_count": 0,
    "spool_bytes": 0,
    "flush_latency_ns": 0,                 # 0 on the first call is expected; filled after the first flush
}

A file will also appear under ./.cirron/spool/ containing the cirron.session root span.

Check which extras are installed

ci.deps() reports which optional extras the current environment has. Call it with no arguments for a full report, or with required names to fail fast at script startup if any are missing:

import cirron as ci

# Report everything
ci.deps()
# {'pandas': '2.3.3', 'polars': None, 'torch': '2.6.0', ...}

# Require specific extras. Raises CirronDependencyError with a
# combined pip install command if any are missing.
ci.deps("torch", "pandas")

See ci.deps for the full surface.

Next step

Quickstart

Three 5-minute paths: zero-touch training, custom PyTorch loop, and inference.

​Requirements

​Core install

​Extras

​Authentication

​Verify

​Check which extras are installed

​Next step

Quickstart

Requirements

Core install

Extras

Authentication

Verify

Check which extras are installed

Next step