Skip to main content

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.

Module-level functions (ci.profile(), ci.load(), ci.mark(), …) are sugar over a process-wide default Cirron instance. Instantiate the class directly when you need a self-hosted endpoint, a custom spool directory, multi-workspace routing, or an isolated instance for tests. 
from cirron import Cirron

​
Constructor

class Cirron:
    def __init__(
        self,
        api_key: str | None = None,
        api_endpoint: str = "https://app.cirron.com",
        workspace_id: str | None = None,
        output_dir: str = "./.cirron/",
        snapshots: Literal["stats", "sampled", "full"] = "stats",
        sample_rate: float = 0.01,
        flush_interval: float = 1.0,
        spool_max_bytes: int = 1_000_000_000,
        load_warn_bytes: int = 1_000_000_000,
        load_max_bytes: int = 10_000_000_000,
        output: str | list[str] | None = None,
        trace_buffer_max_spans: int | None = None,
    ): ...

​
Parameters

NameTypeDefaultPurpose
api_keystr?None (falls back to env)Workspace API key; normally read from CIRRON_API_KEY
api_endpointstr"https://app.cirron.com"Control-plane base URL; point at a self-hosted install
workspace_idstr?None (falls back to env)Target workspace; normally read from CIRRON_WORKSPACE_ID
output_dirstr"./.cirron/"Local spool + snapshots root
snapshotsstr"stats"Snapshot mode; see ci.profile
sample_ratefloat0.01Fraction of epochs to sample in "sampled" mode
flush_intervalfloat1.0Flush-thread wake interval (seconds)
spool_max_bytesint1_000_000_000 (1 GB)Oldest batch files evicted when the spool exceeds this
load_warn_bytesint1_000_000_000 (1 GB)ci.load() logs a WARNING at or above this size
load_max_bytesint10_000_000_000 (10 GB)ci.load() raises CirronDataSizeError at or above this
outputstr or list[str]?None (= "spool")Default output= for profile() calls on this instance
trace_buffer_max_spansint?None (= 100_000)Cap on retained spans in the in-memory ci.trace() buffer
Config resolution order: explicit argument → CIRRON_* env var → ~/.cirron/config.toml → default.

​
Methods

Every method mirrors its module-level counterpart; the module-level function just calls get_default().method(...). Linked pages are the source of truth for each method.
MethodSee
profileci.profile
scopeci.scope
markci.mark
epochs / batchesLoop wrappers
traceci.trace
loadci.load
inferenceci.inference
wrapci.wrap
envci.env
secretci.secret
ci.watch, ci.flush, ci.health, and ci.shutdown are module-level only: they operate on the active profiler singleton rather than on a Cirron instance. Use them as cirron.watch(model) / cirron.flush() etc. even when you’ve built an explicit Cirron instance.

​
profile

c.profile(config=None, frameworks=None, snapshots=None,
          sample_rate=None, flush_interval=None, enabled=True,
          path=None, output=None) -> Profiler

​
scope

with c.scope(name, index=None, **attrs) as s:
    ...

​
mark

c.mark(name, value, *, kind="point", **attrs) -> None

​
epochs / batches

for epoch in c.epochs(range(20)):
    for batch in c.batches(loader):
        ...

​
trace

c.trace(format="tree", name=None, last=None) -> Any
Read back the current session’s scope tree. See ci.trace for the full surface.

​
load

c.load(name, *, source="local", match=None, ext=None, columns=None,
       map=None, where=None, as_="pandas", lazy=False,
       batch_size=10_000, confirm_large=False) -> Any

​
inference

@c.inference(config=...)
def predict(request):
    ...

​
wrap

wrapped = c.wrap(estimator)

​
env

value = c.env(key, default=None)

​
secret

value = c.secret(name)

​
get_default()

from cirron import get_default

c = get_default()    # the process-wide singleton module-level ci.* uses
Returns the lazy-initialized default Cirron instance. Rarely needed directly; reach for it only when you want to inspect or mutate the instance that the module-level functions are delegating to.

​
Multi-instance use

Independent Cirron instances coexist in one process without interfering. Useful for self-hosted-plus-cloud comparisons, for driving two workspaces from one script, or for test harnesses. 
from cirron import Cirron

prod = Cirron(api_endpoint="https://app.cirron.com")
gov  = Cirron(api_endpoint="https://cirron.internal.mil",
              output_dir="./.cirron-gov/")

prod.profile()
gov.profile()
Each instance has its own scope stack, mark buffer, spool directory, and flush thread. Nothing is shared.

Configuration guide

Narrative walk-through of env vars, config.toml, and credential resolution.

Core concepts

Scope tree, marks, transport, overhead.