Building a CognitionFrame

From Python records

from_records() accepts mappings or existing ContextItem objects. Construction validates payload invariants and computes a canonical content hash before any lazy operation is added.

import cognoxium as cx

frame = cx.CognitionFrame.from_records([
    {
        "id": "document-42",
        "payload": {"kind": "json", "json": {"answer": 42, "ok": True}},
        "mime_type": "application/json",
        "sources": [{"uri": "db://documents/42", "kind": "database"}],
        "created_at": "2026-01-01T00:00:00Z",
    }
])

item = frame.collect()[0]
print(item.id, item.payload.kind.value, item.trust.value, item.retention.value)
print(len(item.content_hash))

document-42 json untrusted optional
64

Standard fields

Field	Accepted record value	v0.1-series default and notes
id	String	Generated UUID when omitted. Supply one for reproducibility.
payload	String, bytes, JSON-compatible value, payload mapping, or Payload	Missing payload becomes empty Text in the 0.1 series; explicit input is strongly recommended.
mime_type	String	Derived from payload kind.
role	system, developer, user, assistant, tool	user
sources	URI string, source mapping, SourceRef, or sequence	Empty. External packs reject provenance-free items.
content_hash	SHA-256 hex string	Computed. A supplied mismatch raises SchemaError.
trust	trusted, untrusted, quarantined	untrusted
sensitivity	public, internal, confidential, restricted	public
retention	required, preferred, optional	optional
priority	Number	0.0
created_at	ISO-8601 string or timezone-aware datetime	Current UTC time. Supply one for reproducibility.
expires_at	ISO-8601 string or timezone-aware datetime	No expiry
parent_ids	Sequence of strings	Empty
merged_from_ids	Sequence of strings	Empty
metadata	Mapping	Empty; underscore-prefixed keys are reserved for implementation details.
truncatable	Boolean	False
min_tokens	Non-negative integer	0; applies to opt-in Text truncation.

Naive datetime strings passed through from_records() are interpreted as UTC. Constructing ContextItem directly requires timezone-aware datetime objects.

Payload forms

text = cx.Payload.text("hello")
json_payload = cx.Payload.json({"b": 2, "a": 1})
binary = cx.Payload.binary(b"\x00\x01")
reference = cx.Payload.reference(
    "s3://bucket/object",
    digest="sha256:abc",
    size=123,
)

• Text hashing normalizes Unicode to NFC and line endings to \n.

• JSON is serialized canonically with sorted keys before hashing.

• Binary hashes raw bytes.

• Reference hashes its digest when present, otherwise a normalized URI.

• Payload kind and MIME type are part of the hash.

Binary payloads can be written and restored, but cannot enter a 0.1-series ContextPack. See Status and non-binding roadmap.

Files and Arrow-compatible input

frame = cx.CognitionFrame.read_jsonl("context.jsonl")
frame = cx.CognitionFrame.read_ipc("context.arrow")
frame = cx.CognitionFrame.read_parquet("context.parquet")
frame = cx.CognitionFrame.from_arrow(table)

Use write_jsonl(), write_ipc(), and write_parquet() for the inverse operations. Arrow IPC, Parquet, to_arrow(), and from_arrow() require the arrow extra. The Arrow payload is a struct containing nullable text, JSON, binary, and reference children plus a non-null kind discriminator.

Source plugins

A Source provides a load() method returning records:

class StaticSource:
    id = "static-v1"

    def load(self):
        return [{"id": "one", "payload": "hello", "sources": ["app://static"]}]

frame = cx.CognitionFrame.from_source(StaticSource())

External records default to untrusted. Set trusted only after the application has authenticated the source and is authorized to make that assertion.