Configuration - Cirron Documentation

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.

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:

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.

Resolution order

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

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

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

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

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. For platform-mounted secrets, see ci.secret.

Error types

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

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 for the full hierarchy and example handlers.

Cirron class reference

Full constructor and method signatures.

Schemas

The spool JSON layout and snapshot layout.

​Resolution order

​cirron.yaml project config

​Example

​Platform context env vars

​Error types

​Next