Types - Cirron Documentation

Non-error types exported from the cirron package.

`Profiler`

Returned by ci.profile(). Most callers ignore the return value; reach for it when you want to flush, inspect health, or shut down without going through the module-level functions.

from cirron import Profiler

Instance attributes

Attribute	Type	Purpose
`enabled`	`bool`	`False` if created with `enabled=False`
`cirron`	`Cirron`	The owning configuration instance
`installed_hooks`	`list[str]`	Framework hooks that installed successfully
`hook_handles`	`list[HookHandle]`	Internal handles used for uninstall on shutdown
`platform_context`	`dict[str, str]`	Resolved `CIRRON_RUN_ID` / `PIPELINE_ID` / etc.

Methods

Method	See
`flush()`	`ci.flush`
`health()`	`ci.health`
`trace(format=..., name=..., last=...)`	`ci.trace`
`shutdown()`	`ci.shutdown`

Usage

import cirron as ci

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

# later
p.flush()
p.shutdown()

`Cirron`

The configuration class. Covered on its own page; see Cirron.

`CirronYaml`

Pydantic model for the cirron.yaml project configuration file.

from cirron import CirronYaml, find_cirron_yaml, load_cirron_yaml

path = find_cirron_yaml()          # walks parents looking for cirron.yaml
config: CirronYaml = load_cirron_yaml(path)

Fields

Field	Type	Purpose
`name`	`str` (required)	Model / project identifier
`framework`	enum (required)	`pytorch`, `tensorflow`, `sklearn`, or `onnx`
`type`	enum (required)	`classification`, `regression`, `time-series`, `embedding`, `computer-vision`
`version`	`str` (required)	Semantic version
`description`	`str?`	Free-form description
`profiling`	`ProfilingConfig?`	SDK profiling defaults (see below)
`serving_config`	`ServingConfig?`	Deployment serving contract. YAML alias: `servingConfig`
`env`	`dict[str, str]`	Build / runtime env vars (default `{}`)
`secrets`	`list[str]`	Declared secret names (default `[]`)
`data`	`dict[str, str]`	Dataset aliases for `ci.load(source="platform")` (default `{}`)

When profiling or serving_config is omitted entirely, the SDK falls back to its own defaults (not to a Pydantic-default instance of the sub-model). See Configuration, cirron.yaml for the narrative and example. Parse failures raise CirronYamlError. Unknown keys are tolerated (extra="allow") so CLI-owned sections like build / deploy / environments don’t fail SDK validation.

`ProfilingConfig`

Pydantic model for the profiling: section of cirron.yaml.

Field	Type	Default	Purpose
`snapshots`	`"stats" \| "sampled" \| "full"`	`"stats"`	Default snapshot mode
`sample_rate`	`float` (0.0–1.0)	`0.01`	Default `sample_rate` for `"sampled"` mode
`flush_interval`	`float` (> 0)	`1.0`	Flush thread wake interval (seconds)
`frameworks`	`list[str]?`	`None`	Override framework autodetect

`ServingConfig`

Pydantic model for the servingConfig: section of cirron.yaml. Describes how the Cirron platform should serve the model after it’s deployed.

Field	Type	Purpose
`runtime`	`"onnx" \| "sklearn-joblib" \| "pytorch" \| "tensorflow-serving"`	Serving runtime on the platform
`class_labels`	`list[str]?`	Class labels for classification outputs
`feature_order`	`list[str]?`	Input feature order for tabular models
`input_schema`	`dict?` (flat JSON Schema)	Input payload contract
`output_schema`	`dict?` (flat JSON Schema)	Output payload contract

Extra fields are allowed (extra="allow") for platform-version-specific settings.

File and URL inputs

Each input_schema property is a flat JSON Schema entry (string, number, integer or boolean with a title). A string property can also declare a format:

`format`	Extra fields	What the cockpit renders
`binary`	`contentType` (required: `image/`, `audio/`, or a concrete type in either family), `maxSizeMB` (optional; at most 10 for images, 25 for audio)	A file upload: images get a thumbnail, audio gets a player and, where the browser allows, microphone recording. Small files are sent inline; larger ones upload to storage first.
`uri`		A URL field, passed to the model as the string

servingConfig:
  runtime: custom
  input_schema:
    type: object
    properties:
      image:
        type: string
        format: binary
        contentType: image/*
        maxSizeMB: 2
        title: Input Image
      prompt:
        type: string
        title: Text Prompt
    required: [image]
  output_schema:
    type: object
    properties:
      mask:
        type: string
        format: binary
        contentType: image/png
        title: Mask

The model receives each file as an object with source: "upload" and a data field holding a data URL, next to the scalar fields. An output_schema property declared format: binary renders inline when the model returns a base64 string or data URL for it: as an image for an image contentType, as a player for an audio one. Output properties can also be array or object, for values such as class probabilities or embedding vectors. Input properties stay scalar. The platform checks servingConfig when a model is registered. A config that does not match this shape is refused, and the error names each property at fault (for example input_schema.properties.image: format 'binary' requires a contentType such as image/*).

`LazyHandle`

Returned by ci.load(..., lazy=True). Call .collect() to materialize.

handle = ci.load("./events.parquet", as_="polars", lazy=True)
df = handle.collect()

Behavior depends on the backend:

as_="polars": returns a polars.LazyFrame directly; .collect() is Polars’ native method.
Other backends: LazyHandle defers the I/O and the .collect() call does the full load.

`Scope`

Yielded by the ci.scope() context manager. Most callers ignore it; ci.mark attaches by thread-local lookup, not by Scope reference.

Attribute	Type	Purpose
`id`	`str`	32-char hex span ID
`name`	`str`	Scope name
`start_ns`	`int`	Wall time at open
`parent_id`	`str?`	Parent span ID, or `None` for session root
`attrs`	`dict`	Attribute key-values

Errors

Exception hierarchy.

Schemas

How these types serialize on disk and over the wire.

​Profiler

​Instance attributes

​Methods

​Usage

​Cirron

​CirronYaml

​Fields

​ProfilingConfig

​ServingConfig

​File and URL inputs

​LazyHandle

​Scope

​Related