aerograph-sdk 0.2.0__py3-none-any.whl

aerograph_sdk/__init__.py

@@ -0,0 +1,25 @@
+"""
+python/aerograph-sdk/src/aerograph_sdk/__init__.py
+
+Public API for the aerograph-sdk package.
+"""
+
+from aerograph_sdk.recorder import FlightRecorder, EmissionError
+from aerograph_sdk.ids import new_trace_id, new_span_id
+from aerograph_sdk.state_hash import get_deterministic_state_hash, compute_state_diff
+from aerograph_sdk.events import compare_trace_events, sort_trace_events_deterministic
+from aerograph_sdk.contracts import SCHEMA_VERSION
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "FlightRecorder",
+    "EmissionError",
+    "new_trace_id",
+    "new_span_id",
+    "get_deterministic_state_hash",
+    "compute_state_diff",
+    "compare_trace_events",
+    "sort_trace_events_deterministic",
+    "SCHEMA_VERSION",
+]

aerograph_sdk/contracts/__init__.py

@@ -0,0 +1,83 @@
+"""
+python/aerograph-sdk/src/aerograph_sdk/contracts/__init__.py
+
+Public exports from the contracts subpackage.
+"""
+
+from aerograph_sdk.contracts.generated import (
+    SCHEMA_VERSION,
+    TraceEventKind,
+    TraceEventStatus,
+    ActorKind,
+    LinkRel,
+    Actor,
+    AgentActor,
+    ToolActor,
+    SystemActor,
+    TraceLink,
+    StreamingTelemetry,
+    PromptPayload,
+    ResponsePayload,
+    ToolCallPayload,
+    ToolResultPayload,
+    HandoffPayload,
+    ErrorPayload,
+    RetrieverDocument,
+    RetrieverPayload,
+    StateSnapshotPayload,
+    CheckpointPayload,
+    PromptEvent,
+    ResponseEvent,
+    ToolCallEvent,
+    ToolResultEvent,
+    HandoffEvent,
+    ErrorEvent,
+    NoteEvent,
+    StateSnapshotEvent,
+    RetrieverEvent,
+    CheckpointEvent,
+    TraceEvent,
+    TraceMeta,
+    Trace,
+    TraceWithMeta,
+    TraceListResponse,
+)
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "TraceEventKind",
+    "TraceEventStatus",
+    "ActorKind",
+    "LinkRel",
+    "Actor",
+    "AgentActor",
+    "ToolActor",
+    "SystemActor",
+    "TraceLink",
+    "StreamingTelemetry",
+    "PromptPayload",
+    "ResponsePayload",
+    "ToolCallPayload",
+    "ToolResultPayload",
+    "HandoffPayload",
+    "ErrorPayload",
+    "RetrieverDocument",
+    "RetrieverPayload",
+    "StateSnapshotPayload",
+    "CheckpointPayload",
+    "PromptEvent",
+    "ResponseEvent",
+    "ToolCallEvent",
+    "ToolResultEvent",
+    "HandoffEvent",
+    "ErrorEvent",
+    "NoteEvent",
+    "StateSnapshotEvent",
+    "RetrieverEvent",
+    "CheckpointEvent",
+    "TraceEvent",
+    "TraceMeta",
+    "Trace",
+    "TraceWithMeta",
+    "TraceListResponse",
+]

aerograph_sdk/contracts/generated.py

@@ -0,0 +1,564 @@
+# generated by datamodel-codegen:
+#   filename:  trace-event.schema.json
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any, Literal
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, RootModel
+
+
+class Model(RootModel[Any]):
+    root: Any
+
+
+class TraceEventKind(Enum):
+    prompt = "prompt"
+    response = "response"
+    tool_call = "tool_call"
+    tool_result = "tool_result"
+    handoff = "handoff"
+    error = "error"
+    note = "note"
+    state_snapshot = "state_snapshot"
+    retriever = "retriever"
+    checkpoint = "checkpoint"
+
+
+class TraceEventStatus(Enum):
+    ok = "ok"
+    error = "error"
+
+
+class ActorKind(Enum):
+    agent = "agent"
+    tool = "tool"
+    system = "system"
+
+
+class LinkRel(Enum):
+    follows = "follows"
+    caused_by = "caused_by"
+    handoff_to = "handoff_to"
+
+
+class PromptPayload(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    text: str
+
+
+class StreamingTelemetry(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    timeToFirstTokenMs: float
+    totalDurationMs: float
+    tokensPerSecond: float
+    tokenCount: float
+
+
+class ToolCallPayload(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    input: dict[str, Any]
+
+
+class ToolResultPayload(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    output: dict[str, Any]
+
+
+class HandoffPayload(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    fromAgentId: Annotated[str, Field(min_length=1)]
+    toAgentId: Annotated[str, Field(min_length=1)]
+    reason: str | None = None
+
+
+class ErrorPayload(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    message: Annotated[str, Field(min_length=1)]
+    details: dict[str, Any] = {}
+
+
+class StateSnapshotPayload(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    nodeName: str
+    stateHash: str
+    stateDiff: dict[str, Any]
+    removedKeys: list[str] | None = None
+    fullState: dict[str, Any]
+
+
+class RetrieverDocument(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    pageContent: str
+    metadata: dict[str, Any]
+    score: float | None = None
+
+
+class CheckpointPayload(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    checkpointId: str
+    reason: str
+    state: dict[str, Any]
+
+
+class ParentSpanId(RootModel[str]):
+    root: Annotated[str, Field(min_length=1)]
+
+
+class RootSpanId(RootModel[str]):
+    root: Annotated[str, Field(min_length=1)]
+
+
+class DerivedFrom(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    baseTraceId: Annotated[str, Field(min_length=1)]
+    forkedFromSpanId: Annotated[str, Field(min_length=1)]
+
+
+class TraceMeta(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    traceId: Annotated[str, Field(min_length=1)]
+    createdAt: AwareDatetime
+    updatedAt: AwareDatetime
+    eventCount: Annotated[int, Field(ge=0)]
+    rootSpanId: RootSpanId | None
+    derivedFrom: DerivedFrom | None = None
+
+
+class Id(RootModel[str]):
+    root: Annotated[str, Field(min_length=1)]
+
+
+class Name(RootModel[str]):
+    root: Annotated[str, Field(min_length=1)]
+
+
+class AgentActor(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    kind: Literal["agent"]
+    id: Annotated[str, Field(min_length=1)]
+    name: Annotated[str | None, Field(min_length=1)] = None
+
+
+class OccurredAt(RootModel[AwareDatetime]):
+    root: AwareDatetime
+
+
+class ParentSpanIdModel(RootModel[ParentSpanId | None]):
+    root: ParentSpanId | None
+
+
+class SchemaVersion(RootModel[Literal["1.0.0"]]):
+    root: Literal["1.0.0"]
+
+
+class SpanId(RootModel[str]):
+    root: Annotated[str, Field(min_length=1)]
+
+
+class Title(RootModel[str]):
+    root: Annotated[str, Field(min_length=1)]
+
+
+class TraceId(RootModel[str]):
+    root: Annotated[str, Field(min_length=1)]
+
+
+class RetrieverPayload(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    query: str
+    documents: list[RetrieverDocument]
+
+
+class SystemActor(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    kind: Literal["system"]
+    id: Annotated[str, Field(min_length=1)]
+    name: Annotated[str | None, Field(min_length=1)] = None
+
+
+class ToolActor(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    kind: Literal["tool"]
+    id: Annotated[str, Field(min_length=1)]
+    name: Annotated[str | None, Field(min_length=1)] = None
+
+
+class TraceLink(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    rel: LinkRel
+    spanId: Annotated[str, Field(min_length=1)]
+
+
+class TraceMetaModel(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    traceId: Annotated[str, Field(min_length=1)]
+    createdAt: AwareDatetime
+    updatedAt: AwareDatetime
+    eventCount: Annotated[int, Field(ge=0)]
+    rootSpanId: RootSpanId | None
+    derivedFrom: DerivedFrom | None = None
+
+
+class Actor(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    kind: ActorKind
+    id: Annotated[str, Field(min_length=1)]
+    name: Annotated[str | None, Field(min_length=1)] = None
+
+
+class ResponsePayload(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    text: str
+    streamingTelemetry: StreamingTelemetry | None = None
+
+
+class PromptEvent(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    schemaVersion: Literal["1.0.0"]
+    traceId: Annotated[str, Field(min_length=1)]
+    spanId: Annotated[str, Field(min_length=1)]
+    parentSpanId: ParentSpanId | None
+    occurredAt: AwareDatetime
+    actor: AgentActor
+    status: TraceEventStatus
+    title: Annotated[str | None, Field(min_length=1)] = None
+    links: Annotated[list[TraceLink], Field(validate_default=True)] = []
+    kind: Literal["prompt"]
+    payload: PromptPayload
+
+
+class TraceListResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    traces: list[TraceMetaModel]
+
+
+class PromptEventModel(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    schemaVersion: Literal["1.0.0"]
+    traceId: Annotated[str, Field(min_length=1)]
+    spanId: Annotated[str, Field(min_length=1)]
+    parentSpanId: ParentSpanId | None
+    occurredAt: AwareDatetime
+    actor: AgentActor
+    status: TraceEventStatus
+    title: Annotated[str | None, Field(min_length=1)] = None
+    links: Annotated[list[TraceLink], Field(validate_default=True)] = []
+    kind: Literal["prompt"]
+    payload: PromptPayload
+
+
+class Links(RootModel[list[TraceLink] | None]):
+    root: Annotated[list[TraceLink] | None, Field(validate_default=True)] = []
+
+
+class RetrieverEvent(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    schemaVersion: Literal["1.0.0"]
+    traceId: Annotated[str, Field(min_length=1)]
+    spanId: Annotated[str, Field(min_length=1)]
+    parentSpanId: ParentSpanId | None
+    occurredAt: AwareDatetime
+    actor: ToolActor
+    status: TraceEventStatus
+    title: Annotated[str | None, Field(min_length=1)] = None
+    links: list[TraceLink] | None = None
+    kind: Literal["retriever"]
+    payload: RetrieverPayload
+
+
+class StateSnapshotEvent(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    schemaVersion: Literal["1.0.0"]
+    traceId: Annotated[str, Field(min_length=1)]
+    spanId: Annotated[str, Field(min_length=1)]
+    parentSpanId: ParentSpanId | None
+    occurredAt: AwareDatetime
+    actor: SystemActor
+    status: TraceEventStatus
+    title: Annotated[str | None, Field(min_length=1)] = None
+    links: list[TraceLink] | None = None
+    kind: Literal["state_snapshot"]
+    payload: StateSnapshotPayload
+
+
+class ToolCallEvent(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    schemaVersion: Literal["1.0.0"]
+    traceId: Annotated[str, Field(min_length=1)]
+    spanId: Annotated[str, Field(min_length=1)]
+    parentSpanId: ParentSpanId | None
+    occurredAt: AwareDatetime
+    actor: ToolActor
+    status: TraceEventStatus
+    title: Annotated[str | None, Field(min_length=1)] = None
+    links: list[TraceLink] | None = None
+    kind: Literal["tool_call"]
+    payload: ToolCallPayload
+
+
+class ToolResultEvent(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    schemaVersion: Literal["1.0.0"]
+    traceId: Annotated[str, Field(min_length=1)]
+    spanId: Annotated[str, Field(min_length=1)]
+    parentSpanId: ParentSpanId | None
+    occurredAt: AwareDatetime
+    actor: ToolActor
+    status: TraceEventStatus
+    title: Annotated[str | None, Field(min_length=1)] = None
+    links: list[TraceLink] | None = None
+    kind: Literal["tool_result"]
+    payload: ToolResultPayload
+
+
+class ResponseEvent(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    schemaVersion: Literal["1.0.0"]
+    traceId: Annotated[str, Field(min_length=1)]
+    spanId: Annotated[str, Field(min_length=1)]
+    parentSpanId: ParentSpanId | None
+    occurredAt: AwareDatetime
+    actor: AgentActor
+    status: TraceEventStatus
+    title: Annotated[str | None, Field(min_length=1)] = None
+    links: list[TraceLink] | None = None
+    kind: Literal["response"]
+    payload: ResponsePayload
+
+
+class HandoffEvent(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    schemaVersion: Literal["1.0.0"]
+    traceId: Annotated[str, Field(min_length=1)]
+    spanId: Annotated[str, Field(min_length=1)]
+    parentSpanId: ParentSpanId | None
+    occurredAt: AwareDatetime
+    actor: SystemActor
+    status: TraceEventStatus
+    title: Annotated[str | None, Field(min_length=1)] = None
+    links: list[TraceLink] | None = None
+    kind: Literal["handoff"]
+    payload: HandoffPayload
+
+
+class ErrorEvent(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    schemaVersion: Literal["1.0.0"]
+    traceId: Annotated[str, Field(min_length=1)]
+    spanId: Annotated[str, Field(min_length=1)]
+    parentSpanId: ParentSpanId | None
+    occurredAt: AwareDatetime
+    actor: Actor
+    status: TraceEventStatus
+    title: Annotated[str | None, Field(min_length=1)] = None
+    links: list[TraceLink] | None = None
+    kind: Literal["error"]
+    payload: ErrorPayload
+
+
+class NoteEvent(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    schemaVersion: Literal["1.0.0"]
+    traceId: Annotated[str, Field(min_length=1)]
+    spanId: Annotated[str, Field(min_length=1)]
+    parentSpanId: ParentSpanId | None
+    occurredAt: AwareDatetime
+    actor: Actor
+    status: TraceEventStatus
+    title: Annotated[str | None, Field(min_length=1)] = None
+    links: list[TraceLink] | None = None
+    kind: Literal["note"]
+    payload: dict[str, Any]
+
+
+class CheckpointEvent(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    schemaVersion: Literal["1.0.0"]
+    traceId: Annotated[str, Field(min_length=1)]
+    spanId: Annotated[str, Field(min_length=1)]
+    parentSpanId: ParentSpanId | None
+    occurredAt: AwareDatetime
+    actor: SystemActor
+    status: TraceEventStatus
+    title: Annotated[str | None, Field(min_length=1)] = None
+    links: list[TraceLink] | None = None
+    kind: Literal["checkpoint"]
+    payload: CheckpointPayload
+
+
+class Trace(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    traceId: Annotated[str, Field(min_length=1)]
+    createdAt: AwareDatetime
+    rootSpanId: RootSpanId | None
+    events: list[
+        PromptEventModel
+        | ResponseEvent
+        | ToolCallEvent
+        | ToolResultEvent
+        | HandoffEvent
+        | ErrorEvent
+        | NoteEvent
+        | StateSnapshotEvent
+        | RetrieverEvent
+        | CheckpointEvent
+    ]
+
+
+class TraceWithMeta(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    meta: TraceMetaModel
+    events: list[
+        PromptEventModel
+        | ResponseEvent
+        | ToolCallEvent
+        | ToolResultEvent
+        | HandoffEvent
+        | ErrorEvent
+        | NoteEvent
+        | StateSnapshotEvent
+        | RetrieverEvent
+        | CheckpointEvent
+    ]
+
+
+class AeroGraph(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    TraceEventKind_1: Annotated[TraceEventKind, Field(alias="TraceEventKind")]
+    TraceEventStatus_1: Annotated[TraceEventStatus, Field(alias="TraceEventStatus")]
+    ActorKind_1: Annotated[ActorKind, Field(alias="ActorKind")]
+    Actor_1: Annotated[Actor, Field(alias="Actor")]
+    AgentActor_1: Annotated[AgentActor, Field(alias="AgentActor")]
+    ToolActor_1: Annotated[ToolActor, Field(alias="ToolActor")]
+    SystemActor_1: Annotated[SystemActor, Field(alias="SystemActor")]
+    LinkRel_1: Annotated[LinkRel, Field(alias="LinkRel")]
+    TraceLink_1: Annotated[TraceLink, Field(alias="TraceLink")]
+    PromptPayload_1: Annotated[PromptPayload, Field(alias="PromptPayload")]
+    StreamingTelemetry_1: Annotated[
+        StreamingTelemetry, Field(alias="StreamingTelemetry")
+    ]
+    ResponsePayload_1: Annotated[ResponsePayload, Field(alias="ResponsePayload")]
+    ToolCallPayload_1: Annotated[ToolCallPayload, Field(alias="ToolCallPayload")]
+    ToolResultPayload_1: Annotated[ToolResultPayload, Field(alias="ToolResultPayload")]
+    HandoffPayload_1: Annotated[HandoffPayload, Field(alias="HandoffPayload")]
+    ErrorPayload_1: Annotated[ErrorPayload, Field(alias="ErrorPayload")]
+    StateSnapshotPayload_1: Annotated[
+        StateSnapshotPayload, Field(alias="StateSnapshotPayload")
+    ]
+    RetrieverDocument_1: Annotated[RetrieverDocument, Field(alias="RetrieverDocument")]
+    RetrieverPayload_1: Annotated[RetrieverPayload, Field(alias="RetrieverPayload")]
+    CheckpointPayload_1: Annotated[CheckpointPayload, Field(alias="CheckpointPayload")]
+    PromptEvent_1: Annotated[PromptEvent, Field(alias="PromptEvent")]
+    ResponseEvent_1: Annotated[ResponseEvent, Field(alias="ResponseEvent")]
+    ToolCallEvent_1: Annotated[ToolCallEvent, Field(alias="ToolCallEvent")]
+    ToolResultEvent_1: Annotated[ToolResultEvent, Field(alias="ToolResultEvent")]
+    HandoffEvent_1: Annotated[HandoffEvent, Field(alias="HandoffEvent")]
+    ErrorEvent_1: Annotated[ErrorEvent, Field(alias="ErrorEvent")]
+    NoteEvent_1: Annotated[NoteEvent, Field(alias="NoteEvent")]
+    StateSnapshotEvent_1: Annotated[
+        StateSnapshotEvent, Field(alias="StateSnapshotEvent")
+    ]
+    RetrieverEvent_1: Annotated[RetrieverEvent, Field(alias="RetrieverEvent")]
+    CheckpointEvent_1: Annotated[CheckpointEvent, Field(alias="CheckpointEvent")]
+    TraceEvent: (
+        PromptEventModel
+        | ResponseEvent
+        | ToolCallEvent
+        | ToolResultEvent
+        | HandoffEvent
+        | ErrorEvent
+        | NoteEvent
+        | StateSnapshotEvent
+        | RetrieverEvent
+        | CheckpointEvent
+    )
+    Trace_1: Annotated[Trace, Field(alias="Trace")]
+    TraceMeta_1: Annotated[TraceMeta, Field(alias="TraceMeta")]
+    TraceWithMeta_1: Annotated[TraceWithMeta, Field(alias="TraceWithMeta")]
+    TraceListResponse_1: Annotated[TraceListResponse, Field(alias="TraceListResponse")]
+
+
+# Injected by generate_contracts.py
+SCHEMA_VERSION = "1.0.0"
+TraceEvent = (
+    PromptEvent
+    | ResponseEvent
+    | ToolCallEvent
+    | ToolResultEvent
+    | HandoffEvent
+    | ErrorEvent
+    | NoteEvent
+    | StateSnapshotEvent
+    | RetrieverEvent
+    | CheckpointEvent
+)