aerograph-sdk 0.2.0__tar.gz

aerograph_sdk-0.2.0/.gitignore

@@ -0,0 +1,37 @@
+node_modules/
+dist/
+build/
+.vite/
+coverage/
+*.log
+.env*
+.specify/
+apps/collector/data/
+.DS_Store
+.github/agents
+.github/prompts
+.github/copilot-instructions.md
+Thumbs.db
+.agents/
+apps/collector/data/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+Thumbs.db
+*.tmp
+*.swp
+.vscode/
+.idea/
+specs/
+docs/architecture
+.vscode/
+AGENTS.md
+uv.lock

aerograph_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: aerograph-sdk
+Version: 0.2.0
+Summary: Python SDK for AeroGraph — emit trace events from Python agent workflows.
+Project-URL: Homepage, https://github.com/SGcpu/AeroGraph
+Project-URL: Repository, https://github.com/SGcpu/AeroGraph
+Project-URL: Issues, https://github.com/SGcpu/AeroGraph/issues
+License: Apache-2.0
+Keywords: aerograph,agent,ai,observability,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.25.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aerograph-sdk
+
+Python SDK for [AeroGraph](https://github.com/SGcpu/AeroGraph) — the open-source flight recorder for AI agent workflows.
+
+## Installation
+
+```bash
+pip install aerograph-sdk
+```
+
+## Quickstart
+
+```python
+from aerograph_sdk import FlightRecorder
+
+recorder = FlightRecorder(
+    endpoint="http://localhost:4317",
+    actor={"id": "my-agent", "name": "My Agent"},
+)
+
+# Emit events
+prompt_event = recorder.prompt(parent_span_id=None, text="What is AeroGraph?")
+recorder.response(parent_span_id=prompt_event.spanId, text="AeroGraph records agent traces.")
+```
+
+## Features
+
+- Emit 10 event kinds: `prompt`, `response`, `tool_call`, `tool_result`, `handoff`, `error`, `note`, `state_snapshot`, `retriever`, `checkpoint`
+- Sync and async emission via `httpx`
+- Batch emission with deterministic event ordering
+- Cross-language hash compatibility with the TypeScript SDK
+- Pydantic v2 contract validation
+
+## License
+
+Apache-2.0

aerograph_sdk-0.2.0/README.md

@@ -0,0 +1,36 @@
+# aerograph-sdk
+
+Python SDK for [AeroGraph](https://github.com/SGcpu/AeroGraph) — the open-source flight recorder for AI agent workflows.
+
+## Installation
+
+```bash
+pip install aerograph-sdk
+```
+
+## Quickstart
+
+```python
+from aerograph_sdk import FlightRecorder
+
+recorder = FlightRecorder(
+    endpoint="http://localhost:4317",
+    actor={"id": "my-agent", "name": "My Agent"},
+)
+
+# Emit events
+prompt_event = recorder.prompt(parent_span_id=None, text="What is AeroGraph?")
+recorder.response(parent_span_id=prompt_event.spanId, text="AeroGraph records agent traces.")
+```
+
+## Features
+
+- Emit 10 event kinds: `prompt`, `response`, `tool_call`, `tool_result`, `handoff`, `error`, `note`, `state_snapshot`, `retriever`, `checkpoint`
+- Sync and async emission via `httpx`
+- Batch emission with deterministic event ordering
+- Cross-language hash compatibility with the TypeScript SDK
+- Pydantic v2 contract validation
+
+## License
+
+Apache-2.0

aerograph_sdk-0.2.0/examples/minimal_trace.py

@@ -0,0 +1,108 @@
+"""
+python/aerograph-sdk/examples/minimal_trace.py
+
+Minimal runnable example demonstrating the AeroGraph Python SDK.
+
+Usage:
+    # Start the collector first:
+    #   npm run dev -w apps-collector (from repo root)
+
+    cd python/aerograph-sdk
+    pip install -e .
+    python examples/minimal_trace.py
+
+Expected output:
+    [AeroGraph] Trace ID: t_...
+    [AeroGraph] Emitted prompt   → s_...
+    [AeroGraph] Emitted response → s_...
+    [AeroGraph] Done. View trace at: http://localhost:5173/traces/t_...
+"""
+
+from __future__ import annotations
+
+import sys
+
+from aerograph_sdk import FlightRecorder
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+COLLECTOR_URL = "http://localhost:4317"
+ACTOR = {"id": "demo-agent", "name": "Demo Agent"}
+
+
+def run() -> None:
+    recorder = FlightRecorder(
+        endpoint=COLLECTOR_URL,
+        actor=ACTOR,
+    )
+    print(f"[AeroGraph] Trace ID: {recorder.trace_id}")
+
+    # --- Emit a minimal prompt/response trace ---
+    root_span = recorder.new_span_id()
+
+    try:
+        prompt_event = recorder.prompt(
+            parent_span_id=None,
+            span_id=root_span,
+            text="What is AeroGraph?",
+            title="User query",
+        )
+        print(f"[AeroGraph] Emitted prompt   → {prompt_event.spanId}")
+
+        response_event = recorder.response(
+            parent_span_id=root_span,
+            text=(
+                "AeroGraph is an open-source flight recorder for AI agent workflows. "
+                "It captures every prompt, response, tool call, and handoff as a "
+                "structured trace you can visualize and inspect."
+            ),
+            title="Agent response",
+        )
+        print(f"[AeroGraph] Emitted response → {response_event.spanId}")
+
+        # --- Emit a tool call + result ---
+        tool_call_event = recorder.tool_call(
+            parent_span_id=root_span,
+            tool_id="search-tool",
+            tool_name="SearchTool",
+            input={"query": "AeroGraph observability"},
+        )
+        print(f"[AeroGraph] Emitted tool_call → {tool_call_event.spanId}")
+
+        recorder.tool_result(
+            parent_span_id=tool_call_event.spanId,
+            tool_id="search-tool",
+            tool_name="SearchTool",
+            output={"results": ["result1", "result2"]},
+        )
+        print("[AeroGraph] Emitted tool_result")
+
+        # --- Emit a state snapshot with hash ---
+        full_state = {"question": "What is AeroGraph?", "step": 1, "complete": True}
+        snap_event = recorder.state_snapshot(
+            parent_span_id=root_span,
+            node_name="answerNode",
+            full_state=full_state,
+        )
+        print(
+            f"[AeroGraph] Emitted state_snapshot (hash={snap_event.payload.stateHash})"
+        )
+
+        print(
+            f"\n[AeroGraph] Done. View trace at: http://localhost:5173/traces/{recorder.trace_id}"
+        )
+
+    except Exception as e:
+        print(f"[AeroGraph] Error: {e}", file=sys.stderr)
+        print(
+            "[AeroGraph] Is the collector running? "
+            "Start it with: npm run dev -w apps-collector",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run()

aerograph_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aerograph-sdk"
+version = "0.2.0"
+description = "Python SDK for AeroGraph — emit trace events from Python agent workflows."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+keywords = ["ai", "agent", "tracing", "observability", "aerograph"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "httpx>=0.27.0",
+  "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.24.0",
+  "pytest-httpx>=0.30.0",
+  "datamodel-code-generator>=0.25.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/SGcpu/AeroGraph"
+Repository = "https://github.com/SGcpu/AeroGraph"
+Issues = "https://github.com/SGcpu/AeroGraph/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aerograph_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "integration: marks tests as integration tests (requires external services)",
+]
+
+[tool.hatch.metadata]
+allow-direct-references = true

aerograph_sdk-0.2.0/src/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-0.2.0/src/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",
+]