Skip to main content

kazen-event-schema

PyPI Python 3.10+ License

The shared event contract for KazenAI. One schema so Agent FinOps, its run receipts, 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

Hard spending limits only work if every part of the stack agrees on what an “event” is:

  • SDKs emit what happened (model calls, denials, settlements)
  • FinOps accounts for spend and policy decisions
  • Run receipts explain each run and decision 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

Area Examples
Model invocation model.call (legacy llm.call normalizes at ingest)
Human gates gate.decision, human_gate
FinOps / control finops.budget.reserve, finops.budget.denied, finops.trajectory, finops.loop.anomaly, finops.circuit_breaker.opened, finops.pause, finops.resumed
Run lifecycle run.started, run.finished, run.failed

Core fields

Field Required Purpose
schema_version yes 1.0, 1.1, or 1.2
event_id yes Stable id for idempotent ingest
ts_ms yes Unix milliseconds
event_type yes Dotted lowercase type
org_id yes Tenant
workspace_id / project_id yes Workspace scope
run_id recommended Correlates steps in a run
step_id / parent_step_id recommended / optional Step tree for multi-agent runs
tokens / tokens_used / cost_usd optional Usage and spend; token aliases normalize to the same count and conflicting values are rejected
payload optional Model id, tool names, refs

Used by

Package / service Role
kazenai / kazenai-finops SDK emit path
Agent FinOps Accounting + ingest
Agent FinOps run receipts Run timelines + decision evidence

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

Metadata

Release files for kazen-event-schema 0.6.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kazen-event-schema 0.6.6
File Size Uploaded Provenance Actions
kazen_event_schema-0.6.6.tar.gz 16.7 kB With provenance Details for kazen_event_schema-0.6.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kazen-event-schema 0.6.6
File Interpreter ABI Platform Actions
kazen_event_schema-0.6.6-py3-none-any.whl Python 3 none any Details for kazen_event_schema-0.6.6-py3-none-any.whl

Total release size: 33.1 kB

Release files / kazen_event_schema-0.6.6.tar.gz

Download URL kazen_event_schema-0.6.6.tar.gz
Size 16.7 kB
Tags Source
SHA-256 checksum
How to use checksums
933e3bc45b8eeba85dad951eb4e6f983159344260c7db42f2faea771fd8a5e10
BLAKE2b-256 checksum
How to use checksums
514a44a72a255a22daf0cd37bc98c383bed2dd8f21315aea4316302108df0adb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / kazen_event_schema-0.6.6-py3-none-any.whl

Download URL kazen_event_schema-0.6.6-py3-none-any.whl
Size 16.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
288855a8d4ab654d430635231af0093d63579daf19ad3d226d436438063ee50f
BLAKE2b-256 checksum
How to use checksums
4ab56d8fe25761d0762d526dfd2a36ac9b466d7a4d777f4aec25657dfd4db102
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for kazen-event-schema 0.6.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for kazen_event_schema-0.6.6.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page