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

Consuming events safely

If you ingest KazenEvents in your own service:

• Validate each event with KazenEvent before reading fields; unknown top-level fields are rejected.
• Treat tokens and tokens_used (and the timestamp aliases) as the same value — the model normalizes them and rejects conflicting values.
• Use event_id for idempotent ingest: a repeated event with the same content is a duplicate, a repeated id with different content is a conflict.
• Pin a compatible range (kazen-event-schema>=0.6,<0.7) and run your ingest-to-storage tests when you upgrade.

License

Apache License 2.0. See LICENSE and NOTICE.

Products: kazenai.com · founder@kazenai.com