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

# Configuration

> The `Cirron` class, `ci.env`, `ci.secret`, resolution order.

Module-level functions (`ci.profile()`, `ci.load()`, etc.) delegate to a
process-wide default `Cirron` instance. Instantiate the class directly
for self-hosted endpoints, multi-workspace setups, custom spool
directories, or test harnesses.

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

c = Cirron(api_endpoint="https://cirron.internal.example", output_dir="./.cirron-custom/")
c.profile()
df = c.load("training-data")
```

Two independent instances coexist in one process, useful for
self-hosted + cloud comparisons or for driving traces into two
workspaces from the same script:

```python theme={null}
prod = Cirron(api_endpoint="https://app.cirron.com")
custom = Cirron(api_endpoint="https://cirron.internal.example", output_dir="./.cirron-custom/")

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

For the full constructor signature and per-method docs, see
[`Cirron`](/sdk/reference/cirron).

## Resolution order

Every config value resolves in this order, first match wins:

1. **Explicit constructor argument** (or explicit function argument)
2. **`CIRRON_*` environment variables** (`CIRRON_API_KEY`,
   `CIRRON_API_ENDPOINT`, `CIRRON_WORKSPACE_ID`, ...)
3. **`~/.cirron/config.toml`**: written by `cirron login` (planned) or
   by hand
4. **SDK defaults**

`~/.cirron/config.toml` is a plain TOML file:

```toml theme={null}
api_key = "..."
api_endpoint = "https://app.cirron.com"
workspace_id = "ws_..."
```

## `cirron.yaml` project config

`cirron.yaml` is the project-level configuration file, shared across the
Cirron CLI, the SDK, and the platform. It lives at the project root.
`cirron.yml` and `cirron.json` are also accepted. The CLI, SDK, and
platform resolve them in that order, picking the first one they find.
The schema is identical across formats.

The full schema covers build, deploy, and serving metadata used by the
CLI and platform. See [the CLI docs](/cli/commands/config) for the full
surface. The SDK itself reads a narrower subset:

| Section           | Used by the SDK for                                                                  |
| ----------------- | ------------------------------------------------------------------------------------ |
| `name`, `version` | Identity: stamped onto traces, shown in the dashboard                                |
| `framework`       | One of `pytorch`, `tensorflow`, `sklearn`, `onnx`; narrows hook autodetect           |
| `type`            | One of `classification`, `regression`, `time-series`, `embedding`, `computer-vision` |
| `profiling`       | Defaults for `ci.profile()`: snapshot mode, sample rate, flush interval              |
| `servingConfig`   | Runtime, input/output JSON schemas, class labels, feature order                      |
| `env`             | Environment variables merged into the container at build time                        |
| `secrets`         | Secret names the project declares (platform validates they're configured)            |
| `data`            | Dataset registrations: aliases `ci.load()` resolves when `source="platform"`         |

Extra fields (e.g. the CLI's `build`, `deploy`, `environments` sections)
are tolerated. The SDK's Pydantic model uses `extra="allow"` so the same
`cirron.yaml` feeds all three tools.

`name`, `version`, `framework`, and `type` are required; `description`,
`profiling`, `servingConfig`, `env`, `secrets`, and `data` are optional
and fall back to SDK defaults when omitted.

The SDK accepts both `servingConfig` (camelCase, matches the CLI/platform
convention) and `serving_config` (snake\_case, matches Pydantic). They're
interchangeable.

### Example

```yaml theme={null}
name: sentiment-classifier
version: 1.0.0
framework: pytorch
type: classification

profiling:
  snapshots: stats
  sample_rate: 0.01

servingConfig:
  runtime: onnx
  class_labels: [negative, neutral, positive]
  feature_order: [text]

env:
  MODEL_PATH: /models/sentiment-v2

secrets:
  - openai-api-key

data:
  training: training-data-v2
  validation: validation-data-v2
```

## Platform context env vars

When running inside a Cirron pipeline or deployment, the runner injects
these automatically. `ci.profile()` reads them to set span attribution
and pick the transport:

| Variable               | Purpose                                     |
| ---------------------- | ------------------------------------------- |
| `CIRRON_RUN_ID`        | Run this process belongs to                 |
| `CIRRON_PIPELINE_ID`   | Pipeline this run executed as (if any)      |
| `CIRRON_DEPLOYMENT_ID` | Deployment this process is part of (if any) |
| `CIRRON_WORKSPACE_ID`  | Owning workspace                            |

For reading your own variables, see [`ci.env`](/sdk/reference/env). For
platform-mounted secrets, see [`ci.secret`](/sdk/reference/secret).

## Error types

The top-level `cirron` package exposes the SDK-wide error types:

```python theme={null}
from cirron import (
    CirronError,              # base class
    CirronDependencyError,    # optional extra not installed
    CirronSecretNotFound,     # ci.secret, neither env var nor file mount
    CirronYamlError,          # cirron.yaml parse / validation failure
)
```

Data-loader errors live in `cirron.core.errors` (not re-exported yet):
`CirronDatasetNotFound`, `CirronPlatformRequired`, `CirronDataSizeError`.
See [Errors](/sdk/errors) for the full hierarchy and example handlers.

## Next

<CardGroup cols={2}>
  <Card title="Cirron class reference" icon="code" href="/sdk/reference/cirron">
    Full constructor and method signatures.
  </Card>

  <Card title="Schemas" icon="database" href="/sdk/schemas">
    The spool JSON layout and snapshot layout.
  </Card>
</CardGroup>