10分で始めるCognoxium¶

このチュートリアルでは、通常のPythonレコードから始め、特定のプロバイダーに依存しないコンテキストパックを作成します。対応するどの環境でも結果を再現できるよう、概算トークンプロファイルを使用します。

コンテキストを構築・変換してパックする¶

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

選択結果の理由を確認する¶

policyはrequired（必須）なので、Cognoxiumは他の項目を検討する前に、その分の予算を確保します。
ci-resultはpreferred（優先）なので、任意の項目より先に検討されます。
old-resultは有効期限が切れているため、どの境界も越えられません。
secretは保守的な機密情報パターンに一致するため、外部向けのこのパックから除外されます。
概算プロファイルではestimated=Trueと報告されます。32は選択に用いる予算であり、プロバイダーが保証する厳密な上限ではありません。
untrusted（未信頼）は既定のラベルですが、それだけで自動的に拒否されるわけではありません。ci-resultには出所情報があるため、引き続き選択対象になります。信頼境界とポリシーも参照してください。

SDKとの境界でのみレンダリングする¶

ContextPackは不変で、特定のプロバイダーに依存しません。

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

v0.1系列のレンダラーによる対応付けは、意図的に単純なものに限定されています。ツールロールやプロバイダー固有のメッセージ機能を使う前に、OpenAI、Anthropic、テキストへのレンダリングを確認してください。

監査記録を保存する¶

保持ポリシーで許可されている場合は、pack.manifest.to_dict()をモデルへのリクエストと一緒に保存してください。マニフェストには、予算、プロファイルのフィンガープリント、選択された項目、除外理由、重複排除グループ、切り詰めの内容が記録されます。翻訳されたログを解析する必要はありません。

再現可能なマニフェストを得るには、固定したidとcreated_atを指定してください。省略すると、UUIDと現在時刻が生成されます。