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

# Cirron

> The configuration class every module-level `ci.*` delegates to.

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.

```python theme={null}
from cirron import Cirron
```

## Constructor

```python theme={null}
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

| Name                     | Type                  | Default                    | Purpose                                                    |
| ------------------------ | --------------------- | -------------------------- | ---------------------------------------------------------- |
| `api_key`                | `str?`                | `None` (falls back to env) | Workspace API key; normally read from `CIRRON_API_KEY`     |
| `api_endpoint`           | `str`                 | `"https://app.cirron.com"` | Control-plane base URL; point at a self-hosted install     |
| `workspace_id`           | `str?`                | `None` (falls back to env) | Target workspace; normally read from `CIRRON_WORKSPACE_ID` |
| `output_dir`             | `str`                 | `"./.cirron/"`             | Local spool + snapshots root                               |
| `snapshots`              | `str`                 | `"stats"`                  | Snapshot mode; see [`ci.profile`](/sdk/reference/profile)  |
| `sample_rate`            | `float`               | `0.01`                     | Fraction of epochs to sample in `"sampled"` mode           |
| `flush_interval`         | `float`               | `1.0`                      | Flush-thread wake interval (seconds)                       |
| `spool_max_bytes`        | `int`                 | `1_000_000_000` (1 GB)     | Oldest batch files evicted when the spool exceeds this     |
| `load_warn_bytes`        | `int`                 | `1_000_000_000` (1 GB)     | `ci.load()` logs a WARNING at or above this size           |
| `load_max_bytes`         | `int`                 | `10_000_000_000` (10 GB)   | `ci.load()` raises `CirronDataSizeError` at or above this  |
| `output`                 | `str` or `list[str]?` | `None` (= `"spool"`)       | Default `output=` for `profile()` calls on this instance   |
| `trace_buffer_max_spans` | `int?`                | `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.

| Method                                  | See                                           |
| --------------------------------------- | --------------------------------------------- |
| [`profile`](#profile)                   | [`ci.profile`](/sdk/reference/profile)        |
| [`scope`](#scope)                       | [`ci.scope`](/sdk/reference/scope)            |
| [`mark`](#mark)                         | [`ci.mark`](/sdk/reference/mark)              |
| [`epochs` / `batches`](#epochs-batches) | [Loop wrappers](/sdk/reference/loop-wrappers) |
| [`trace`](#trace)                       | [`ci.trace`](/sdk/reference/trace)            |
| [`load`](#load)                         | [`ci.load`](/sdk/reference/load)              |
| [`inference`](#inference)               | [`ci.inference`](/sdk/reference/inference)    |
| [`wrap`](#wrap)                         | [`ci.wrap`](/sdk/reference/wrap)              |
| [`env`](#env)                           | [`ci.env`](/sdk/reference/env)                |
| [`secret`](#secret)                     | [`ci.secret`](/sdk/reference/secret)          |

<Note>
  `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.
</Note>

### `profile`

```python theme={null}
c.profile(config=None, frameworks=None, snapshots=None,
          sample_rate=None, flush_interval=None, enabled=True,
          path=None, output=None) -> Profiler
```

### `scope`

```python theme={null}
with c.scope(name, index=None, **attrs) as s:
    ...
```

### `mark`

```python theme={null}
c.mark(name, value, *, kind="point", **attrs) -> None
```

### `epochs` / `batches`

```python theme={null}
for epoch in c.epochs(range(20)):
    for batch in c.batches(loader):
        ...
```

### `trace`

```python theme={null}
c.trace(format="tree", name=None, last=None) -> Any
```

Read back the current session's scope tree. See
[`ci.trace`](/sdk/reference/trace) for the full surface.

### `load`

```python theme={null}
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`

```python theme={null}
@c.inference(config=...)
def predict(request):
    ...
```

### `wrap`

```python theme={null}
wrapped = c.wrap(estimator)
```

### `env`

```python theme={null}
value = c.env(key, default=None)
```

### `secret`

```python theme={null}
value = c.secret(name)
```

## `get_default()`

```python theme={null}
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.

```python theme={null}
from cirron import Cirron

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

prod.profile()
custom.profile()
```

Each instance has its own scope stack, mark buffer, spool directory,
and flush thread. Nothing is shared.

## Related

<CardGroup cols={2}>
  <Card title="Configuration guide" icon="gear" href="/sdk/configuration">
    Narrative walk-through of env vars, `config.toml`, and credential resolution.
  </Card>

  <Card title="Core concepts" icon="compass" href="/sdk/core-concepts">
    Scope tree, marks, transport, overhead.
  </Card>
</CardGroup>