kurrent-agent-schema 0.1.0__py3-none-any.whl

kurrent_agent_schema/__init__.py

@@ -0,0 +1,78 @@
+"""Canonical event schema for Kurrent agent integrations.
+
+See ``schema/SCHEMA_v2.md`` at the repo root for the prose specification.
+This package is the Python mirror; ``Kurrent.Agent.Schema`` is the .NET mirror.
+"""
+
+from kurrent_agent_schema.events import (
+    AgentConfig,
+    ArtifactVersionCreated,
+    AssistantTextGenerated,
+    AssistantThinkingGenerated,
+    AssistantToolCallsGenerated,
+    EvalRunCompleted,
+    EvalRunStarted,
+    FactRetained,
+    InterruptIssued,
+    InterruptResolved,
+    SessionContinuedAs,
+    SessionEnded,
+    SessionStarted,
+    SubagentCompleted,
+    SubagentStarted,
+    ToolCallInfo,
+    ToolResultReceived,
+    ToolSpec,
+    TurnScored,
+    UserMessageReceived,
+)
+from kurrent_agent_schema.streams import (
+    agent_artifact_stream,
+    agent_memory_stream,
+    agent_session_stream,
+    agent_subsession_stream,
+    eval_run_stream,
+)
+from kurrent_agent_schema.usage import TokenUsage, USAGE_METADATA_KEY
+from kurrent_agent_schema.version import SCHEMA_VERSION
+
+__all__ = [
+    # Value types
+    "AgentConfig",
+    "ToolSpec",
+    "ToolCallInfo",
+    "TokenUsage",
+    # Session lifecycle
+    "SessionStarted",
+    "SessionEnded",
+    "SessionContinuedAs",
+    # Conversation
+    "UserMessageReceived",
+    "AssistantTextGenerated",
+    "AssistantToolCallsGenerated",
+    "AssistantThinkingGenerated",
+    "ToolResultReceived",
+    # Interrupts
+    "InterruptIssued",
+    "InterruptResolved",
+    # Subagents
+    "SubagentStarted",
+    "SubagentCompleted",
+    # Memory
+    "FactRetained",
+    # Artifacts
+    "ArtifactVersionCreated",
+    # Evaluation
+    "EvalRunStarted",
+    "TurnScored",
+    "EvalRunCompleted",
+    # Stream builders
+    "agent_session_stream",
+    "agent_subsession_stream",
+    "agent_memory_stream",
+    "agent_artifact_stream",
+    "eval_run_stream",
+    # Constants
+    "USAGE_METADATA_KEY",
+    "SCHEMA_VERSION",
+]

kurrent_agent_schema/events.py

@@ -0,0 +1,304 @@
+"""Canonical event models (schema v2).
+
+See ``schema/SCHEMA_v2.md`` at the repo root for the prose specification.
+
+All events inherit from ``_EventBase``, which carries the ``extensions``
+envelope and the shared Pydantic configuration (``extra="ignore"`` for
+forward-compatibility, frozen for hashability, snake_case JSON).
+
+Stream placement and semantic conventions live in ``streams.py`` and the
+schema doc — this module is strictly the type shapes.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class _EventBase(BaseModel):
+    """Shared configuration for every canonical event.
+
+    ``extra="ignore"`` preserves forward-compatibility: unknown fields added
+    in a later minor version are dropped on read, not raised.
+
+    ``ser_json_bytes="base64"`` / ``val_json_bytes="base64"`` round-trip
+    ``bytes`` fields through JSON for ``ArtifactVersionCreated.inline_bytes``.
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="ignore",
+        frozen=True,
+        ser_json_bytes="base64",
+        val_json_bytes="base64",
+    )
+
+    extensions: dict[str, dict[str, Any]] | None = None
+    """Framework-specific extension envelope keyed by slug (``adk``, ``afw``,
+    ``strands``, ``openai``, ``claude_sdk``, ``claude_code``, …).
+    See ``schema/SCHEMA_v2.md §5``."""
+
+
+# --- Value types -------------------------------------------------------------
+
+
+class ToolSpec(BaseModel):
+    """Tool description captured in ``AgentConfig.tools``."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore", frozen=True)
+
+    name: str
+    description: str | None = None
+    input_schema: dict[str, Any] | None = None
+    source: str | None = None
+
+
+class AgentConfig(BaseModel):
+    """Informational snapshot of the agent configuration at session start.
+
+    All fields optional. Not a contract — readers use this for context, not
+    to reproduce the writer's agent.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore", frozen=True)
+
+    tools: list[ToolSpec] | None = None
+    plugins: list[str] | None = None
+    conversation_manager: dict[str, Any] | None = None
+    model_parameters: dict[str, Any] | None = None
+
+
+class ToolCallInfo(BaseModel):
+    """One tool call within ``AssistantToolCallsGenerated.tool_calls``."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore", frozen=True)
+
+    call_id: str
+    tool_name: str
+    arguments: dict[str, Any] | None = None
+
+
+# --- Session lifecycle (SCHEMA_v2.md §3.1) -----------------------------------
+
+
+class SessionStarted(_EventBase):
+    app_name: str | None = None
+    agent_name: str | None = None
+    model: str | None = None
+    tenant_id: str | None = None
+    user_id: str | None = None
+    agent_config: AgentConfig | None = None
+    previous_session_id: str | None = None
+    """Prior session this one resumes or forks from. New in v2."""
+    timestamp: datetime
+
+
+class SessionEnded(_EventBase):
+    reason: str | None = None
+    timestamp: datetime
+
+
+class SessionContinuedAs(_EventBase):
+    """Written to the predecessor session pointing forward to its successor.
+
+    Paired with ``SessionStarted.previous_session_id`` on the successor, this
+    forms a bidirectional chain. New in v2.
+    """
+
+    next_session_id: str
+    reason: str | None = None
+    timestamp: datetime
+
+
+# --- Conversation events (SCHEMA_v2.md §3.4) ---------------------------------
+
+
+class UserMessageReceived(_EventBase):
+    content: str | None = None
+    message_id: str | None = None
+    author_name: str | None = None
+    created_at: datetime | None = None
+    message_index: int
+    timestamp: datetime
+
+
+class AssistantTextGenerated(_EventBase):
+    content: str | None = None
+    message_id: str | None = None
+    author_name: str | None = None
+    created_at: datetime | None = None
+    message_index: int
+    timestamp: datetime
+
+
+class AssistantToolCallsGenerated(_EventBase):
+    tool_calls: list[ToolCallInfo]
+    content: str | None = None
+    message_id: str | None = None
+    author_name: str | None = None
+    created_at: datetime | None = None
+    message_index: int
+    timestamp: datetime
+
+
+class AssistantThinkingGenerated(_EventBase):
+    """Assistant reasoning output (extended thinking / o-series / Gemini thinking).
+
+    Plaintext reasoning in ``content`` for Claude and Gemini; encrypted blobs
+    from OpenAI o-series have ``encrypted=True`` with the opaque value in
+    ``extensions.openai.thinking.raw`` and the provider signature on
+    ``signature``. New in v2 (SCHEMA_v2.md §3.2).
+    """
+
+    content: str | None = None
+    encrypted: bool = False
+    signature: str | None = None
+    message_id: str | None = None
+    author_name: str | None = None
+    created_at: datetime | None = None
+    message_index: int
+    timestamp: datetime
+
+
+class ToolResultReceived(_EventBase):
+    call_id: str
+    tool_name: str | None = None
+    result: str | None = None
+    message_id: str | None = None
+    author_name: str | None = None
+    created_at: datetime | None = None
+    message_index: int
+    timestamp: datetime
+
+
+# --- Interrupts (SCHEMA_v2.md §3.3) ------------------------------------------
+
+
+class InterruptIssued(_EventBase):
+    """Mid-turn human-in-the-loop pause (permission prompt, approval, input, auth).
+
+    ``kind`` is an open string; the documented set is
+    ``permission | approval | input | auth``, readers must tolerate unknowns.
+    Framework-specific details (tool_input, auth challenge) go in
+    ``extensions.{framework}.interrupt``. New in v2.
+    """
+
+    request_id: str
+    kind: str
+    tool_name: str | None = None
+    prompt: str | None = None
+    timestamp: datetime
+
+
+class InterruptResolved(_EventBase):
+    """Resolution of an ``InterruptIssued``, keyed by the same ``request_id``.
+
+    ``outcome`` documented set: ``allow | allow_once | allow_always | deny |
+    cancel | answered | timeout``. Open string; readers tolerate unknowns.
+    New in v2.
+    """
+
+    request_id: str
+    outcome: str
+    response: str | None = None
+    timestamp: datetime
+
+
+# --- Subagents (SCHEMA_v2.md §3.5) -------------------------------------------
+# Written to the PARENT session stream to record subagent lifecycle; the
+# subagent's own conversation lives in AgentSubsession-{parent}-{agent_id}.
+
+
+class SubagentStarted(_EventBase):
+    agent_id: str
+    agent_type: str | None = None
+    prompt: str | None = None
+    subsession_stream: str | None = None
+    timestamp: datetime
+
+
+class SubagentCompleted(_EventBase):
+    agent_id: str
+    outcome: str | None = None
+    summary: str | None = None
+    timestamp: datetime
+
+
+# --- Memory (SCHEMA_v2.md §3.7) ----------------------------------------------
+
+
+class FactRetained(_EventBase):
+    fact: str
+    retained_at: datetime
+
+
+# --- Artifacts (SCHEMA_v2.md §3.7) -------------------------------------------
+
+
+class ArtifactVersionCreated(_EventBase):
+    version: int
+    mime_type: str | None = None
+    inline_bytes: bytes | None = None
+    canonical_uri: str | None = None
+    custom_metadata: dict[str, Any] | None = None
+    created_at: datetime
+
+
+# --- Evaluation (SCHEMA_v2.md §3.7) ------------------------------------------
+
+
+class EvalRunStarted(_EventBase):
+    session_id: str
+    scorer: str
+    criteria: str
+    timestamp: datetime
+
+
+class TurnScored(_EventBase):
+    session_id: str
+    turn_index: int
+    input: str | None = None
+    output: str | None = None
+    score: float
+    score_label: str | None = None
+    reason: str | None = None
+    timestamp: datetime
+
+
+class EvalRunCompleted(_EventBase):
+    session_id: str
+    turns_scored: int
+    average_score: float
+    total_cost: float | None = None
+    timestamp: datetime
+
+
+# --- Event type name registry -------------------------------------------------
+
+EVENT_TYPE_NAMES: dict[type[_EventBase], str] = {
+    SessionStarted: "SessionStarted",
+    SessionEnded: "SessionEnded",
+    SessionContinuedAs: "SessionContinuedAs",
+    UserMessageReceived: "UserMessageReceived",
+    AssistantTextGenerated: "AssistantTextGenerated",
+    AssistantToolCallsGenerated: "AssistantToolCallsGenerated",
+    AssistantThinkingGenerated: "AssistantThinkingGenerated",
+    ToolResultReceived: "ToolResultReceived",
+    InterruptIssued: "InterruptIssued",
+    InterruptResolved: "InterruptResolved",
+    SubagentStarted: "SubagentStarted",
+    SubagentCompleted: "SubagentCompleted",
+    FactRetained: "FactRetained",
+    ArtifactVersionCreated: "ArtifactVersionCreated",
+    EvalRunStarted: "EvalRunStarted",
+    TurnScored: "TurnScored",
+    EvalRunCompleted: "EvalRunCompleted",
+}
+"""Canonical event type name on the wire (KurrentDB ``event_type``)
+for each model class. Integration writers use this to stamp events;
+readers use the inverse lookup."""
+
+EVENT_TYPE_BY_NAME: dict[str, type[_EventBase]] = {v: k for k, v in EVENT_TYPE_NAMES.items()}

kurrent_agent_schema/streams.py

@@ -0,0 +1,43 @@
+"""Canonical stream-name builders.
+
+See ``schema/SCHEMA_v2.md §2`` for the full stream taxonomy.
+"""
+
+from __future__ import annotations
+
+AGENT_SESSION_PREFIX: str = "AgentSession-"
+AGENT_SUBSESSION_PREFIX: str = "AgentSubsession-"
+AGENT_MEMORY_PREFIX: str = "AgentMemory-"
+AGENT_ARTIFACT_PREFIX: str = "AgentArtifact-"
+EVAL_RUN_PREFIX: str = "EvalRun-"
+
+
+def agent_session_stream(session_id: str) -> str:
+    """Primary conversation stream for a session."""
+    return f"{AGENT_SESSION_PREFIX}{session_id}"
+
+
+def agent_subsession_stream(parent_session_id: str, agent_id: str) -> str:
+    """Subagent conversation stream, scoped under a parent session.
+
+    See ``schema/SCHEMA_v2.md §3.5``.
+    """
+    return f"{AGENT_SUBSESSION_PREFIX}{parent_session_id}-{agent_id}"
+
+
+def agent_memory_stream(app_name: str, user_id: str) -> str:
+    """Per-app, per-user retained facts. v1 default scope.
+
+    See ``schema/SCHEMA_v2.md §3.7`` (inherited from v1 §3.6).
+    """
+    return f"{AGENT_MEMORY_PREFIX}{app_name}-{user_id}"
+
+
+def agent_artifact_stream(scope: str, filename: str) -> str:
+    """Binary artifact versions. ``scope`` is integration-defined."""
+    return f"{AGENT_ARTIFACT_PREFIX}{scope}-{filename}"
+
+
+def eval_run_stream(run_id: str) -> str:
+    """Eval run events."""
+    return f"{EVAL_RUN_PREFIX}{run_id}"

kurrent_agent_schema/usage.py

@@ -0,0 +1,32 @@
+"""Token usage metadata model.
+
+Usage rides on KurrentDB event metadata under the ``$usage`` key, on every
+assistant event (``AssistantTextGenerated``, ``AssistantToolCallsGenerated``,
+``AssistantThinkingGenerated``). It is *not* a canonical event payload.
+
+See ``schema/SCHEMA_v2.md §3.6``.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+USAGE_METADATA_KEY: str = "$usage"
+"""KurrentDB metadata key under which ``TokenUsage`` is written."""
+
+
+class TokenUsage(BaseModel):
+    """Token counts reported by the model provider for one assistant event.
+
+    All fields optional — providers differ in which counts they return.
+    For ``AssistantThinkingGenerated``, populate ``reasoning_tokens``.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore", frozen=True)
+
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    total_tokens: int | None = None
+    cached_input_tokens: int | None = None
+    reasoning_tokens: int | None = None
+    model: str | None = None

kurrent_agent_schema/version.py

@@ -0,0 +1,9 @@
+"""Schema version constant.
+
+Stamped on event metadata under ``$schema_version``. Writers set this to
+``SCHEMA_VERSION``; readers that encounter a higher version should either
+reject the event or degrade gracefully via ``extra="ignore"`` semantics.
+"""
+
+SCHEMA_VERSION: int = 2
+"""Kurrent agent event schema version. See ``schema/SCHEMA_v2.md``."""

kurrent_agent_schema-0.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: kurrent-agent-schema
+Version: 0.1.0
+Summary: Canonical event schema for Kurrent agent integrations (schema v2)
+Author: Kurrent, Inc.
+License: Apache-2.0
+Keywords: agents,eventsourcing,kurrentdb,llm,schema
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kurrent-agent-schema
+
+Canonical event schema types for Kurrent agent integrations — schema version **2**.
+
+This package is the Python mirror of the canonical agent event schema shared across Kurrent's agent-framework integrations (Google ADK, Microsoft Agent Framework, Strands, OpenAI Agents, Claude Agent SDK) and Capacitor. The prose specification lives in [`schema/SCHEMA_v2.md`](../SCHEMA_v2.md); the .NET mirror is [`Kurrent.Agent.Schema`](../dotnet/Kurrent.Agent.Schema/).
+
+## What's here
+
+- **Canonical event models** (Pydantic v2): `SessionStarted`, `SessionEnded`, `SessionContinuedAs`, `UserMessageReceived`, `AssistantTextGenerated`, `AssistantToolCallsGenerated`, `AssistantThinkingGenerated`, `ToolResultReceived`, `InterruptIssued`, `InterruptResolved`, `SubagentStarted`, `SubagentCompleted`, `FactRetained`, `ArtifactVersionCreated`, `EvalRunStarted`, `TurnScored`, `EvalRunCompleted`.
+- **Value types**: `AgentConfig`, `ToolSpec`, `ToolCallInfo`.
+- **Usage metadata**: `TokenUsage` (carried on KurrentDB event metadata under the `$usage` key, not as a standalone event).
+- **Stream-name builders**: `agent_session_stream`, `agent_subsession_stream`, `agent_memory_stream`, `agent_artifact_stream`, `eval_run_stream`.
+- **Type-name registry**: `EVENT_TYPE_NAMES` / `EVENT_TYPE_BY_NAME` for wiring up KurrentDB event-type to/from CLR-type conversion.
+
+## What's not here
+
+- **Framework-specific events and extension shapes.** ADK's `AgentTransferred`/`Rewind`, AFW's workflow checkpoints, Capacitor's `AgentRunStarted`/visibility events, coding-agent fields under `extensions.claude_code.*`, etc. Those live in their owning integration packages — this package deliberately carries only the portable vocabulary.
+
+## Usage
+
+```python
+from datetime import datetime, timezone
+from kurrent_agent_schema import (
+    SessionStarted, UserMessageReceived, AssistantTextGenerated,
+    TokenUsage, USAGE_METADATA_KEY, agent_session_stream,
+)
+
+stream = agent_session_stream("sess-0001")  # "AgentSession-sess-0001"
+
+event = UserMessageReceived(
+    content="hello",
+    message_index=0,
+    timestamp=datetime.now(tz=timezone.utc),
+    extensions={"adk": {"invocation_id": "inv_abc"}},
+)
+
+# $usage goes on KurrentDB metadata, not the payload
+usage = TokenUsage(input_tokens=1507, output_tokens=203, model="claude-sonnet-4-6")
+```
+
+## Drift guard
+
+Every canonical event has a JSON fixture under [`schema/fixtures/events/`](../fixtures/events/). The test suite here runs a round-trip assertion per fixture; an equivalent suite in the .NET package runs against the same fixtures. Adding or modifying a canonical field requires a coordinated PR: update the model **and** the fixture, in both Python and .NET packages. CI fails otherwise.
+
+```bash
+cd schema/python
+uv pip install -e ".[dev]"
+pytest
+```
+
+## Version
+
+- Package: `0.1.0` (initial pre-1.0 release carrying schema v2).
+- Schema: `SCHEMA_VERSION = 2`, stamped on KurrentDB metadata under `$schema_version` by integration writers.

kurrent_agent_schema-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+kurrent_agent_schema/__init__.py,sha256=jPsSBDr8T74aR9bLH8NMcZ5W_3q6WJbbvphPyiEdMOk,1888
+kurrent_agent_schema/events.py,sha256=Co_5lGNoJ90QY6WQHqnRpfezLJf8sKRoOmthxq8CLGg,8949
+kurrent_agent_schema/streams.py,sha256=MEsLd4XdcxHOXi7VM-o4LV-BzWZId8671iDj3-VQWN0,1323
+kurrent_agent_schema/usage.py,sha256=QNJlH_65j3LdsEQeks6q7O292FhKtKZ2AVptVqlTEiM,1047
+kurrent_agent_schema/version.py,sha256=qcn69p4vcDIlm3IMouUYhBhxLY7AqyQiEyy-hk5_upo,349
+kurrent_agent_schema-0.1.0.dist-info/METADATA,sha256=IiBDcdPLGrJQbtP2qjP4ZR4oGOk4D507gVaddSkKELM,3426
+kurrent_agent_schema-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+kurrent_agent_schema-0.1.0.dist-info/RECORD,,

kurrent_agent_schema-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any