Metadata-Version: 2.4
Name: cognoxium
Version: 0.1.1
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Typing :: Typed
Requires-Dist: pyarrow>=25.0.0 ; extra == 'arrow'
Requires-Dist: pytz>=2026.3.post1 ; extra == 'arrow'
Requires-Dist: maturin>=1.14.1,<2 ; extra == 'dev'
Requires-Dist: pyarrow>=25.0.0 ; extra == 'dev'
Requires-Dist: pytz>=2026.3.post1 ; extra == 'dev'
Requires-Dist: pandas>=3.0.5 ; python_full_version >= '3.11' and extra == 'dev'
Requires-Dist: pandas>=2,<3 ; python_full_version < '3.11' and extra == 'dev'
Requires-Dist: polars>=1.43.2 ; extra == 'dev'
Requires-Dist: tiktoken>=0.13.0 ; extra == 'dev'
Requires-Dist: tokenizers>=0.23.1 ; extra == 'dev'
Requires-Dist: pytest>=9.1.1 ; extra == 'dev'
Requires-Dist: hypothesis>=6.165.0 ; extra == 'dev'
Requires-Dist: mypy>=2.3.0 ; extra == 'dev'
Requires-Dist: ruff>=0.16.1 ; extra == 'dev'
Requires-Dist: sphinx>=9.1.0 ; python_full_version >= '3.12' and extra == 'dev'
Requires-Dist: sphinx>=8,<9 ; python_full_version < '3.12' and extra == 'dev'
Requires-Dist: myst-parser>=5.1.0 ; python_full_version >= '3.11' and extra == 'dev'
Requires-Dist: myst-parser>=4,<5 ; python_full_version < '3.11' and extra == 'dev'
Requires-Dist: sphinx-intl>=2.3.2 ; extra == 'dev'
Requires-Dist: furo>=2025.12.19 ; extra == 'dev'
Requires-Dist: sphinx>=9.1.0 ; python_full_version >= '3.12' and extra == 'docs'
Requires-Dist: sphinx>=8,<9 ; python_full_version < '3.12' and extra == 'docs'
Requires-Dist: myst-parser>=5.1.0 ; python_full_version >= '3.11' and extra == 'docs'
Requires-Dist: myst-parser>=4,<5 ; python_full_version < '3.11' and extra == 'docs'
Requires-Dist: sphinx-intl>=2.3.2 ; extra == 'docs'
Requires-Dist: furo>=2025.12.19 ; extra == 'docs'
Requires-Dist: pandas>=3.0.5 ; python_full_version >= '3.11' and extra == 'pandas'
Requires-Dist: pandas>=2,<3 ; python_full_version < '3.11' and extra == 'pandas'
Requires-Dist: polars>=1.43.2 ; extra == 'polars'
Requires-Dist: pytest>=9.1.1 ; extra == 'test'
Requires-Dist: hypothesis>=6.165.0 ; extra == 'test'
Requires-Dist: mypy>=2.3.0 ; extra == 'test'
Requires-Dist: ruff>=0.16.1 ; extra == 'test'
Requires-Dist: tiktoken>=0.13.0 ; extra == 'tokenizers'
Requires-Dist: tokenizers>=0.23.1 ; extra == 'tokenizers'
Provides-Extra: arrow
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: pandas
Provides-Extra: polars
Provides-Extra: test
Provides-Extra: tokenizers
License-File: LICENSE
Summary: A trustworthy context DataFrame for AI applications, powered by Rust.
Keywords: ai,llm,context,dataframe,rust,security
Author: Cognoxium contributors
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://nue-japan.github.io/cognoxium/en/latest/
Project-URL: Issues, https://github.com/Nue-Japan/cognoxium/issues
Project-URL: Repository, https://github.com/Nue-Japan/cognoxium

# Cognoxium

[日本語](README.ja.md) · [Documentation](https://nue-japan.github.io/cognoxium/en/latest/) · [Security](SECURITY.md) · [PyPI](https://pypi.org/project/cognoxium/)

**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](https://nue-japan.github.io/cognoxium/en/latest/roadmap.html).

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

```bash
uv add cognoxium
```

`pip` remains supported:

```bash
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](https://nue-japan.github.io/cognoxium/en/latest/installation.html) for every extra and source-build requirements.

## Quickstart

```python
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:

```text
[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](https://nue-japan.github.io/cognoxium/en/latest/pandas-users.html).

## 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](https://nue-japan.github.io/cognoxium/en/latest/security.html) before packing sensitive data.

## Development

```bash
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](CONTRIBUTING.md) and the [contributor documentation](https://nue-japan.github.io/cognoxium/en/latest/contributing.html).

## License

Licensed under the [Apache License 2.0](LICENSE).

