# 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

```{testcode}
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())
```

```{testoutput}
['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.