Core concepts

Context items

A ContextItem is one typed unit of model input. It combines content with the information needed to make a packing decision: identity, role, provenance, trust, sensitivity, retention, priority, time bounds, and lineage.

Its payload can be Text, canonical JSON, Binary, or Reference. Text, JSON, and Reference are packable in the 0.1 series. Binary is storage and round-trip only.

Frame, pack, and manifest

  • CognitionFrame holds context records and an immutable transformation plan.

  • ContextPack contains the items selected for one model call.

  • PackManifest explains that decision in machine-readable form.

Calling filter(), select(), with_columns(), join(), sort(), limit(), dedupe(), rank(), redact(), quarantine(), or demote() returns a new frame. Call collect(), to_records(), or pack() to execute an ordinary frame plan. In the 0.1 series, group_by().agg() is the exception and evaluates immediately.

Provenance, trust, and sensitivity

sources records where content came from. Trust and sensitivity are separate assertions: a trusted internal policy can still be restricted, while public web content can be untrusted but non-sensitive.

untrusted does not mean automatically blocked. It means the application has not asserted that the content is trusted. Use a boundary policy, quarantine(), or a custom Policy when untrusted content must be rejected.

Retention

required items cannot be dropped, preferred items are considered before optional items, and optional items compete by rank, priority, token cost, and a deterministic ID tie-break. Marking an item required is a contract, not a ranking hint.

Lineage

Transformations preserve content hashes and parent identifiers. Exact deduplication aggregates sources and applies conservative trust, sensitivity, retention, and expiry rules. The resulting manifest records merge decisions and metadata conflicts.

Determinism

Cognoxium is reproducible for the same ordered records, explicit values, settings, token-profile fingerprint, and plugin fingerprints. Selection preserves original conversational order. Reordering the input can therefore reorder the pack.

For strict reproducibility, provide stable id and created_at values. Constructor defaults use a random UUID and the current time when those fields are absent.