CognitionFrameの構築¶

Pythonレコードから作成する¶

from_records()には、マッピングまたは既存のContextItemオブジェクトを渡せます。構築時にはペイロードの不変条件を検証し、遅延操作を追加する前に正規コンテンツハッシュを計算します。

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

標準フィールド¶

フィールド	レコードに指定できる値	v0.1系列の既定値と注意事項
`id`	文字列	省略するとUUIDが生成されます。再現性が必要な場合は指定してください。
`payload`	文字列、バイト列、JSON互換値、ペイロードのマッピング、または`Payload`	v0.1系列では、省略したペイロードは空のTextになります。明示的に指定することを強く推奨します。
`mime_type`	文字列	ペイロードの種類から決まります。
`role`	`system`、`developer`、`user`、`assistant`、`tool`	`user`
`sources`	URI文字列、出所のマッピング、`SourceRef`、またはこれらのシーケンス	空。外部向けパックでは、出所のない項目が拒否されます。
`content_hash`	SHA-256の16進文字列	自動計算されます。指定した値が一致しない場合は`SchemaError`が発生します。
`trust`	`trusted`、`untrusted`、`quarantined`	`untrusted`
`sensitivity`	`public`、`internal`、`confidential`、`restricted`	`public`
`retention`	`required`、`preferred`、`optional`	`optional`
`priority`	数値	`0.0`
`created_at`	ISO 8601形式の文字列、またはタイムゾーン情報を持つ`datetime`	現在のUTC時刻。再現性が必要な場合は指定してください。
`expires_at`	ISO 8601形式の文字列、またはタイムゾーン情報を持つ`datetime`	有効期限なし
`parent_ids`	文字列のシーケンス	空
`merged_from_ids`	文字列のシーケンス	空
`metadata`	マッピング	空。アンダースコアで始まるキーは実装の詳細として予約されています。
`truncatable`	真偽値	`False`
`min_tokens`	0以上の整数	`0`。明示的に有効化したTextの切り詰めに適用されます。

from_records()へタイムゾーン情報のない日時文字列を渡すと、UTCとして解釈されます。ContextItemを直接構築する場合は、タイムゾーン情報を持つdatetimeオブジェクトが必要です。

ペイロードの形式¶

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のハッシュ計算では、UnicodeをNFCへ、改行を\nへ正規化します。
JSONはキーを並べ替えた正規形式でシリアライズしてから、ハッシュを計算します。
Binaryは生のバイト列からハッシュを計算します。
Referenceはダイジェストがあればその値を、なければ正規化したURIをハッシュ化します。
ペイロードの種類とMIMEタイプもハッシュの一部です。

Binaryペイロードは書き出しと復元ができますが、v0.1系列のContextPackには含められません。現状と拘束力を持たないロードマップを参照してください。

ファイルとArrow互換入力¶

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)

逆方向の変換には、write_jsonl()、write_ipc()、write_parquet()を使用します。Arrow IPC、Parquet、to_arrow()、from_arrow()にはarrow追加機能が必要です。Arrowのペイロードは、NULL許容のtext、JSON、binary、referenceの子要素と、NULLを許容しない種類判別子を含む構造体です。

`Source`プラグイン¶

Sourceは、レコードを返すload()メソッドを提供します。

class StaticSource:
    id = "static-v1"

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

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

外部レコードの既定値はuntrusted（未信頼）です。trusted（信頼済み）に設定するのは、アプリケーションが出所を認証し、信頼済みであると表明する権限を持つ場合だけにしてください。