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

# Types

> Data types the SDK returns and Pydantic config models.

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.

```python theme={null}
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`](/sdk/reference/lifecycle#flush)       |
| `health()`                              | [`ci.health`](/sdk/reference/lifecycle#health)     |
| `trace(format=..., name=..., last=...)` | [`ci.trace`](/sdk/reference/trace)                 |
| `shutdown()`                            | [`ci.shutdown`](/sdk/reference/lifecycle#shutdown) |

### Usage

```python theme={null}
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`](/sdk/reference/cirron).

## `CirronYaml`

Pydantic model for the `cirron.yaml` project configuration file.

```python theme={null}
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`](/sdk/configuration#cirron-yaml-project-config)
for the narrative and example.

Parse failures raise [`CirronYamlError`](/sdk/errors#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.

## `LazyHandle`

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

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

## Related

<CardGroup cols={2}>
  <Card title="Errors" icon="triangle-exclamation" href="/sdk/errors">
    Exception hierarchy.
  </Card>

  <Card title="Schemas" icon="code" href="/sdk/schemas">
    How these types serialize on disk and over the wire.
  </Card>
</CardGroup>