Cognoxium for pandas users¶

CognitionFrame borrows pandas’ composable, tabular style, but its rows are not arbitrary business data. Every row represents one unit of AI context with provenance, trust, retention, and lineage.

A practical mapping¶

pandas idea	Cognoxium equivalent	Important difference
`DataFrame`	`CognitionFrame`	Immutable plan over `ContextItem` records
Boolean mask	`frame.filter(cx.col(...) > ...)`	Expressions operate on context fields
`assign`	`with_columns`	AI operations still require `id` and `payload`
`sort_values`	`sort`	`rank()` stores relevance without reordering conversation order
`drop_duplicates`	`dedupe`	Canonical payload hash plus conservative lineage merge
`groupby().agg()`	`group_by().agg()`	0.1-series aggregation is for tabular exploration and evaluates immediately
`to_dict("records")`	`to_records()`	Preserves the typed context schema
I/O methods	JSONL, Arrow IPC, Parquet	Arrow/Parquet require the `arrow` extra

Familiar operations¶

import cognoxium as cx

frame = cx.CognitionFrame.from_records([
    {"id": "a", "payload": "Rust tokenizer", "priority": 2,
     "sources": ["app://a"], "created_at": "2026-01-01T00:00:00Z"},
    {"id": "b", "payload": "Python fallback", "priority": 1,
     "sources": ["app://b"], "created_at": "2026-01-01T00:01:00Z"},
])

active = frame.filter(cx.col("priority") >= 2).sort("priority", descending=True)
print([item.id for item in active.collect()])
print(active.explain())

['a']
Scan[context records] -> Filter -> Sort[priority]

Deliberate differences from pandas¶

There is no in-place mutation. Every transformation returns a new frame.
rank() is not sort(): ranking affects budget allocation, while selected output retains original order.
required is a contract. Packing never silently drops or demotes it.
select() can produce an exploratory table without id or payload; collect(), dedupe(), rank(), and pack() then raise SchemaError. Use collect_records() for such tables.
GroupedCognitionFrame.agg() is eager in the 0.1 series even though ordinary frame plans are lazy.
Cognoxium is not a pandas replacement and does not implement generic indexing, statistical analysis, or arbitrary I/O formats.

The stable user-facing namespace is the set of names exported from cognoxium. Underscore-prefixed metadata such as _rank_score and _cognoxium_dedupe is an implementation detail; use PackManifest for durable audit records.