# Python API reference

The stable user-facing Python namespace is the set of names exported from `cognoxium`. Import public types from the top level:

```python
import cognoxium as cx

frame = cx.CognitionFrame.from_records(records)
profile = cx.profiles.openai("o200k_base")
```

Modules such as `cognoxium.frame` and helper functions not exported at the top level are implementation details in 0.x releases. Underscore-prefixed attributes and metadata keys are private.

## Where to look

| Task | Principal API |
| --- | --- |
| Build or load context | `CognitionFrame.from_records`, `from_source`, `from_arrow`, `read_jsonl`, `read_ipc`, `read_parquet` |
| Execute or export | `collect`, `collect_records`, `to_records`, `to_arrow`, `to_pandas`, `to_polars` |
| Tabular planning | `filter`, `select`, `with_columns`, `join`, `group_by`, `sort`, `limit` |
| AI context planning | `dedupe`, `rank`, `redact`, `quarantine`, `demote`, `pack` |
| Expressions | `col`, `lit`, `now`, `Expr` |
| Schema | `ContextItem`, `Payload`, `SourceRef`, enums |
| Budget and output | `Boundary`, `Overflow`, `ContextPack`, `PackManifest`, `ItemCost` |
| Token accounting | `TokenProfile`, `profiles.approximate`, `profiles.openai`, `profiles.huggingface` |
| Recovery | `BudgetExceeded`, `PolicyViolation`, `SchemaError`, `UnsupportedContent`, `PluginError` |
| Extension points | `Source`, `Ranker`, `Policy`, `Renderer`, `PythonTokenizer` |
| Localization | `locale`, `get_locale`, `set_default_locale`, `Diagnostic.render` |

Do not instantiate `CognitionFrame` with its `_rows` and `_plan` dataclass fields. Use a `from_*` classmethod. `GroupedCognitionFrame` is returned by `group_by()` and normally is not instantiated directly.

```{eval-rst}
.. automodule:: cognoxium
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: cognoxium.profiles
   :members: approximate, openai, huggingface
```

## Rust API

The public Rust API is generated with `cargo doc --workspace --no-deps` and published under [`rust/latest`](https://nue-japan.github.io/cognoxium/rust/latest/cognoxium_core/). See {doc}`rust-api` for local generation, release-specific auditing, and scope.