cognoxium 0.1.1

A trustworthy context DataFrame for AI applications, powered by Rust.

Cognoxium

日本語 · Documentation · Security · PyPI

Cognoxium is a local-first, Rust-powered DataFrame for building trustworthy AI context.

LLM applications usually concatenate messages, retrieved documents, and tool results just before a model call. That makes provenance, retention requirements, token-budget decisions, and exclusions difficult to inspect. Cognoxium turns those inputs into typed ContextItem records, applies immutable transformations, and produces a provider-neutral ContextPack with a machine-readable manifest.

Status: alpha (0.1.1). The public Python API is usable today. Rust powers canonical hashing and native tokenization in binary wheels; frame planning currently runs in Python. Serialized compatibility is not guaranteed before 1.0. See the current limitations.

Install

The recommended project workflow uses uv 0.12.1. The documented uv workflow requires that version; use the pip path below if uv is not available:

uv add cognoxium

pip remains supported:

python -m pip install cognoxium

Optional integrations are installed separately, for example uv add "cognoxium[arrow]" or python -m pip install "cognoxium[arrow]". See the installation guide for every extra and source-build requirements.

Quickstart

import cognoxium as cx

frame = cx.CognitionFrame.from_records([
    {"id": "policy", "payload": "Never disclose credentials.", "role": "system",
     "sources": ["app://policy"], "trust": "trusted", "retention": "required",
     "created_at": "2026-01-01T00:00:00Z"},
    {"id": "result", "payload": "The build passed.", "role": "tool",
     "sources": ["tool://ci"], "retention": "preferred",
     "created_at": "2026-01-01T00:01:00Z"},
])

pack = frame.dedupe().rank("build status").pack(
    budget=512,
    token_profile=cx.profiles.approximate(),
    boundary=cx.Boundary.external("openai"),
)
print(pack.to_text())
print([item["id"] for item in pack.manifest.selected])

Output:

[system] Never disclose credentials.

[tool] The build passed.
['policy', 'result']

The selected items can be rendered with pack.to_openai(), pack.to_anthropic(), or pack.to_text(). Inspect pack.manifest to learn exactly what was selected, excluded, merged, or truncated.

Why Cognoxium?

• DataFrame ergonomics: immutable filtering, projection, joins, grouping, ranking, and exact deduplication.
• Budget contracts: required, preferred, and optional retention with explicit overflow recovery.
• Trust boundaries: provenance, quarantine, sensitivity, expiry, and conservative secret-pattern checks before external packing.
• Auditable lineage: selections, exclusions, dedupe decisions, metadata conflicts, token costs, and truncations are recorded.
• Provider-neutral output: make selection and policy decisions before choosing an SDK renderer.
• Local by default: no network client, model call, API-key handling, account, or telemetry in the core library.

Cognoxium complements rather than replaces a retriever, vector database, agent framework, authorization layer, or model SDK. If you already use pandas, start with Cognoxium for pandas users.

Security scope

Cognoxium enforces deterministic information-flow rules; it does not prove content is truthful, authorize tool calls, or guarantee prompt-injection prevention. In particular, untrusted content is labeled but is not automatically blocked when it has provenance. Use quarantine() or a custom Policy when your application must reject it. Read the security model before packing sensitive data.

Development

uv sync --extra dev
uv run maturin develop
uv run pytest
cargo test --workspace --locked

Development commands are validated with uv 0.12.1. See CONTRIBUTING.md and the contributor documentation.

License

Licensed under the Apache License 2.0.