10 minutes to Cognoxium

This tutorial starts with ordinary Python records and ends with a provider-neutral context pack. It uses the approximate token profile so the result is deterministic on every supported installation.

Build, transform, and pack context

import cognoxium as cx

records = [
    {
        "id": "policy",
        "payload": "Never disclose credentials.",
        "role": "system",
        "sources": [{"uri": "app://policy", "kind": "application"}],
        "trust": "trusted",
        "retention": "required",
        "created_at": "2026-01-01T00:00:00Z",
    },
    {
        "id": "ci-result",
        "payload": "The build passed.",
        "role": "tool",
        "sources": [{"uri": "tool://ci", "kind": "tool"}],
        "retention": "preferred",
        "created_at": "2026-01-01T00:01:00Z",
    },
    {
        "id": "old-result",
        "payload": "Old result",
        "sources": ["tool://ci"],
        "expires_at": "2000-01-01T00:00:00Z",
        "created_at": "2026-01-01T00:02:00Z",
    },
    {
        "id": "secret",
        "payload": "api_key=abcdefghijklmnop",
        "sources": ["tool://config"],
        "created_at": "2026-01-01T00:03:00Z",
    },
]

frame = cx.CognitionFrame.from_records(records)
pack = frame.dedupe().rank("build status").pack(
    budget=32,
    token_profile=cx.profiles.approximate(),
    boundary=cx.Boundary.external("openai"),
)

print(pack.to_text())
print("selected:", [item["id"] for item in pack.manifest.selected])
print("excluded:", [
    (item["id"], item["reason"])
    for item in pack.manifest.excluded
])
print("tokens:", pack.manifest.total_tokens, "estimated:", pack.manifest.estimated)

[system] Never disclose credentials.

[tool] The build passed.
selected: ['policy', 'ci-result']
excluded: [('old-result', 'expired'), ('secret', 'secret_detected')]
tokens: 12 estimated: True

Understand the decision

• policy is required, so Cognoxium reserves it before considering other items.

• ci-result is preferred, so it is considered before optional items.

• old-result is expired and cannot cross any boundary.

• secret matches a conservative secret pattern and is excluded from this external pack.

• The approximate profile reports estimated=True; 32 is a selection budget, not a provider-certified hard limit.

• untrusted is the default label, but it is not an automatic block. ci-result has provenance and therefore remains eligible. See Trust boundaries and policies.

Render only at the SDK boundary

ContextPack is immutable and provider neutral:

openai_input = pack.to_openai()
anthropic_arguments = pack.to_anthropic()
plain_text = pack.to_text()

The renderer mappings are intentionally simple in the 0.1 series. Read OpenAI, Anthropic, and text rendering before using tool roles or provider-specific message features.

Keep the audit record

Persist pack.manifest.to_dict() beside the model request when your retention policy permits it. The manifest records the budget, profile fingerprint, selected items, exclusion reasons, dedupe groups, and truncations without requiring translated log parsing.

For reproducible manifests, supply stable id and created_at values. Omitting them generates a UUID and the current time.