kazen-event-schema

The shared event contract for KazenAI. One schema so Agent FinOps, Agent Lens, and the SDKs speak the same language about cost, runs, and control decisions.

Install: PyPI · kazen-event-schema · Docs: Event reference · Products: kazenai.com

Source: github.com/kazenai-ai/kazen-event-schema

Why it exists

Economic control only works if every surface agrees on what an “event” is:

• SDKs emit what happened (model calls, denials, settlements)
• FinOps accounts for spend and policy decisions
• Lens investigates failures with the same identifiers

kazen-event-schema is that contract — a small, versioned Pydantic model used across the stack.

Install

python -m pip install kazen-event-schema

Requires Python 3.10+. Pulled in automatically when you install kazenai or kazenai-finops.

Quick start

from kazen_event_schema import KazenEvent, normalize_event_type, is_model_call

assert normalize_event_type("llm.call") == "model.call"
assert is_model_call("model.call")

event = KazenEvent(
    schema_version="1.2",
    event_id="evt_…",
    ts_ms=1_700_000_000_000,
    event_type="model.call",
    org_id="org-a",
    workspace_id="prod",
    project_id="prod",
    surface="sdk",
    agent_id="support-agent",
    agent_role="agent",
    run_id="run-1",
    cost_usd=0.0042,
)

Common event types

Core fields

Used by

Consumer synchronization

FINAL_1_b_final uses manual schema synchronization. Consumers must validate the canonical model before projecting fields, reject unknown top-level fields, and test tokens/tokens_used, timestamp aliases, duplicate/conflict behavior, and producer-to-persistence round trips. Exporting JSON Schema without checking for a repository diff is not sufficient drift protection.

License

Apache License 2.0. See LICENSE and NOTICE.

Products: kazenai.com · founder@kazenai.com