ase-python 0.1.0__py3-none-any.whl

ase/__init__.py

@@ -0,0 +1,21 @@
+"""ASE — Agent Simulation Engine.
+
+Public API surface. Import from here, not from internal modules.
+"""
+
+from __future__ import annotations
+
+import os
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)
+
+# ASE does not rely on third-party Pydantic plugins. Disabling plugin auto-load
+# keeps CLI startup deterministic even when unrelated plugins are installed in
+# the active environment.
+os.environ.setdefault("PYDANTIC_DISABLE_PLUGINS", "1")
+
+from ase.errors import ASEError
+
+__version__ = "0.1.0"
+__all__ = ["ASEError", "__version__"]

ase/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""Public adapter SDK exports."""
+
+from __future__ import annotations
+
+from ase.adapters.io import InMemoryEventSink, JsonlFileEventSink
+from ase.adapters.model import AdapterEvent, AdapterEventType, AdapterVerificationResult
+
+__all__ = [
+    "AdapterEvent",
+    "AdapterEventType",
+    "AdapterVerificationResult",
+    "InMemoryEventSink",
+    "JsonlFileEventSink",
+]

ase/adapters/contract.py

@@ -0,0 +1,28 @@
+"""Adapter contract shared by official ASE framework integrations."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ase.adapters.model import AdapterEvent
+
+
+class AdapterContract(Protocol):
+    """Define the stable surface ASE adapters expose to frameworks and tests."""
+
+    @property
+    def name(self) -> str:
+        """Return the stable adapter identifier used in traces and reports."""
+
+    @property
+    def transport(self) -> str:
+        """Return the transport used to emit adapter events."""
+
+    def emit(self, event: AdapterEvent) -> None:
+        """Persist one normalized ASE adapter event."""
+
+    def enrich_policy_context(self, context: dict[str, object]) -> dict[str, object]:
+        """Attach adapter metadata used by evaluators and reporters."""
+
+    def inject_determinism(self, fixtures: dict[str, object]) -> dict[str, object]:
+        """Expose deterministic fixtures to the framework runtime."""

ase/adapters/frameworks/__init__.py

@@ -0,0 +1,17 @@
+"""Official framework adapter SDK exports."""
+
+from __future__ import annotations
+
+from ase.adapters.frameworks.base import FrameworkAdapterBase
+from ase.adapters.frameworks.langgraph import LangGraphAdapter
+from ase.adapters.frameworks.mcp import MCPAdapter
+from ase.adapters.frameworks.openai_agents import OpenAIAgentsAdapter
+from ase.adapters.frameworks.pydantic_ai import PydanticAIAdapter
+
+__all__ = [
+    "FrameworkAdapterBase",
+    "LangGraphAdapter",
+    "MCPAdapter",
+    "OpenAIAgentsAdapter",
+    "PydanticAIAdapter",
+]

ase/adapters/frameworks/base.py

@@ -0,0 +1,259 @@
+"""Shared adapter SDK primitives for framework-specific integrations."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import ulid
+
+from ase.adapters.contract import AdapterContract
+from ase.adapters.io import AdapterEventSink
+from ase.adapters.model import AdapterEvent, AdapterEventType
+
+
+class FrameworkAdapterBase(AdapterContract):
+    """Common event-emission helpers shared across official adapters."""
+
+    def __init__(
+        self,
+        sink: AdapterEventSink,
+        *,
+        name: str,
+        framework: str,
+        language: str,
+        transport: str = "jsonl-stdio",
+        version: str | None = None,
+    ) -> None:
+        self._sink = sink
+        self._name = name
+        self._framework = framework
+        self._language = language
+        self._transport = transport
+        self._version = version
+
+    @property
+    def name(self) -> str:
+        """Return the stable adapter name for certification output."""
+        return self._name
+
+    @property
+    def transport(self) -> str:
+        """Return the transport used for emitted adapter events."""
+        return self._transport
+
+    def emit(self, event: AdapterEvent) -> None:
+        """Write a fully formed event to the configured sink."""
+        self._sink.write(event)
+
+    def enrich_policy_context(self, context: dict[str, object]) -> dict[str, object]:
+        """Attach framework metadata used by policy evaluators and reporters."""
+        return {
+            **context,
+            "adapter_name": self._name,
+            "framework": self._framework,
+            "language": self._language,
+        }
+
+    def inject_determinism(self, fixtures: dict[str, object]) -> dict[str, object]:
+        """Expose fixtures unchanged as adapter runtime inputs by default."""
+        return dict(fixtures)
+
+    def agent_start(self, agent_id: str, name: str, **metadata: object) -> None:
+        """Emit an agent_start event with framework metadata attached."""
+        self.emit(
+            self._event(
+                AdapterEventType.AGENT_START,
+                agent_id=agent_id,
+                name=name,
+                metadata=metadata,
+            )
+        )
+
+    def agent_end(
+        self,
+        agent_id: str,
+        *,
+        status: str = "passed",
+        message: str | None = None,
+        **metadata: object,
+    ) -> None:
+        """Emit an agent_end event for the active framework run."""
+        self.emit(
+            self._event(
+                AdapterEventType.AGENT_END,
+                agent_id=agent_id,
+                status=status,
+                message=message,
+                metadata=metadata,
+            )
+        )
+
+    def tool_start(
+        self,
+        agent_id: str,
+        *,
+        span_id: str,
+        tool_kind: str,
+        method: str,
+        target: str,
+        name: str | None = None,
+        protocol: str | None = None,
+        data: dict[str, object] | None = None,
+    ) -> None:
+        """Emit a tool_start event for a framework tool call."""
+        self.emit(
+            self._event(
+                AdapterEventType.TOOL_START,
+                agent_id=agent_id,
+                span_id=span_id,
+                tool_kind=tool_kind,
+                method=method,
+                target=target,
+                name=name,
+                protocol=protocol,
+                data=data,
+            )
+        )
+
+    def tool_end(
+        self,
+        agent_id: str,
+        *,
+        span_id: str,
+        tool_kind: str,
+        method: str,
+        target: str,
+        status: str = "passed",
+        protocol: str | None = None,
+        data: dict[str, object] | None = None,
+        message: str | None = None,
+    ) -> None:
+        """Emit a tool_end event for a framework tool call."""
+        self.emit(
+            self._event(
+                AdapterEventType.TOOL_END,
+                agent_id=agent_id,
+                span_id=span_id,
+                tool_kind=tool_kind,
+                method=method,
+                target=target,
+                status=status,
+                protocol=protocol,
+                data=data,
+                message=message,
+            )
+        )
+
+    def session_write(
+        self,
+        agent_id: str,
+        session_id: str,
+        *,
+        key: str,
+        value: object,
+    ) -> None:
+        """Emit a session_write event for stateful frameworks."""
+        self.emit(
+            self._event(
+                AdapterEventType.SESSION_WRITE,
+                agent_id=agent_id,
+                session_id=session_id,
+                data={"key": key, "value": value},
+            )
+        )
+
+    def session_read(
+        self,
+        agent_id: str,
+        session_id: str,
+        *,
+        key: str,
+        value: object,
+    ) -> None:
+        """Emit a session_read event for frameworks that expose state reads."""
+        self.emit(
+            self._event(
+                AdapterEventType.SESSION_READ,
+                agent_id=agent_id,
+                session_id=session_id,
+                data={"key": key, "value": value},
+            )
+        )
+
+    def handoff(
+        self,
+        agent_id: str,
+        target_agent_id: str,
+        *,
+        name: str,
+        protocol: str = "adapter",
+        data: dict[str, object] | None = None,
+    ) -> None:
+        """Emit a handoff event between two agents."""
+        self.emit(
+            self._event(
+                AdapterEventType.HANDOFF,
+                agent_id=agent_id,
+                target_agent_id=target_agent_id,
+                name=name,
+                protocol=protocol,
+                data=data,
+            )
+        )
+
+    def approval(
+        self,
+        agent_id: str,
+        approval_id: str,
+        *,
+        granted: bool = True,
+    ) -> None:
+        """Emit an approval event used by policy-aware flows."""
+        self.emit(
+            self._event(
+                AdapterEventType.APPROVAL,
+                agent_id=agent_id,
+                approval_id=approval_id,
+                granted=granted,
+            )
+        )
+
+    def stream_chunk(
+        self,
+        agent_id: str,
+        *,
+        chunk_index: int,
+        content: str,
+        protocol: str = "stream",
+    ) -> None:
+        """Emit a streaming chunk event for realtime-style frameworks."""
+        self.emit(
+            self._event(
+                AdapterEventType.STREAM_CHUNK,
+                agent_id=agent_id,
+                protocol=protocol,
+                data={"chunk_index": chunk_index, "content": content},
+            )
+        )
+
+    def _event(self, event_type: AdapterEventType, **kwargs: object) -> AdapterEvent:
+        """Build a framework event with standard adapter metadata attached."""
+        raw_metadata = kwargs.pop("metadata", None)
+        metadata = cast(dict[str, Any], raw_metadata or {})
+        if kwargs.get("data") is None:
+            kwargs.pop("data", None)
+        if kwargs.get("message") is None:
+            kwargs.pop("message", None)
+        metadata.setdefault("adapter_name", self._name)
+        metadata.setdefault("framework", self._framework)
+        metadata.setdefault("language", self._language)
+        if self._version is not None:
+            metadata.setdefault("adapter_version", self._version)
+        metadata.setdefault("transport", self._transport)
+        event_kwargs = cast(dict[str, Any], kwargs)
+        return AdapterEvent(
+            event_type=event_type,
+            event_id=str(ulid.new()),
+            metadata=metadata,
+            **event_kwargs,
+        )

ase/adapters/frameworks/langgraph.py

@@ -0,0 +1,19 @@
+"""LangGraph adapter helpers for ASE's neutral event protocol."""
+
+from __future__ import annotations
+
+from ase.adapters.frameworks.base import FrameworkAdapterBase
+from ase.adapters.io import AdapterEventSink
+
+
+class LangGraphAdapter(FrameworkAdapterBase):
+    """Bind the generic adapter protocol to LangGraph metadata."""
+
+    def __init__(self, sink: AdapterEventSink, *, version: str | None = None) -> None:
+        super().__init__(
+            sink,
+            name="langgraph-python",
+            framework="langgraph",
+            language="python",
+            version=version,
+        )

ase/adapters/frameworks/mcp.py

@@ -0,0 +1,68 @@
+"""Official adapter SDK surface for MCP-backed runtimes."""
+
+from __future__ import annotations
+
+from ase.adapters.frameworks.base import FrameworkAdapterBase
+from ase.adapters.io import AdapterEventSink
+
+
+class MCPAdapter(FrameworkAdapterBase):
+    """Emit ASE adapter events for MCP tools and resource access flows."""
+
+    def __init__(
+        self,
+        sink: AdapterEventSink,
+        *,
+        version: str | None = None,
+    ) -> None:
+        super().__init__(
+            sink,
+            name="mcp-python",
+            framework="mcp",
+            language="python",
+            version=version,
+        )
+
+    def resource_read(
+        self,
+        agent_id: str,
+        *,
+        session_id: str,
+        target: str,
+        value: object,
+    ) -> None:
+        """Emit MCP resource-read state without inflating tool-call metrics."""
+        self.session_read(agent_id, session_id, key=target, value=value)
+
+    def resource_write(
+        self,
+        agent_id: str,
+        *,
+        span_id: str,
+        target: str,
+        approval_id: str,
+        session_id: str | None = None,
+    ) -> None:
+        """Emit an approval-backed MCP resource write tool flow."""
+        self.approval(agent_id, approval_id, granted=True)
+        if session_id is not None:
+            self.session_write(agent_id, session_id, key="mcp_target", value=target)
+        self.tool_start(
+            agent_id,
+            span_id=span_id,
+            tool_kind="filesystem",
+            method="WRITE",
+            target=target,
+            name="mcp_resource_write",
+            protocol="mcp",
+        )
+        self.tool_end(
+            agent_id,
+            span_id=span_id,
+            tool_kind="filesystem",
+            method="WRITE",
+            target=target,
+            protocol="mcp",
+            data={"status_code": 200, "resource": target},
+            message="mcp write completed",
+        )

ase/adapters/frameworks/openai_agents.py

@@ -0,0 +1,19 @@
+"""OpenAI Agents adapter helpers for ASE's neutral event protocol."""
+
+from __future__ import annotations
+
+from ase.adapters.frameworks.base import FrameworkAdapterBase
+from ase.adapters.io import AdapterEventSink
+
+
+class OpenAIAgentsAdapter(FrameworkAdapterBase):
+    """Bind the generic adapter protocol to OpenAI Agents metadata."""
+
+    def __init__(self, sink: AdapterEventSink, *, version: str | None = None) -> None:
+        super().__init__(
+            sink,
+            name="openai-agents-python",
+            framework="openai-agents",
+            language="python",
+            version=version,
+        )

ase/adapters/frameworks/pydantic_ai.py

@@ -0,0 +1,19 @@
+"""PydanticAI adapter helpers for ASE's neutral event protocol."""
+
+from __future__ import annotations
+
+from ase.adapters.frameworks.base import FrameworkAdapterBase
+from ase.adapters.io import AdapterEventSink
+
+
+class PydanticAIAdapter(FrameworkAdapterBase):
+    """Bind the generic adapter protocol to PydanticAI metadata."""
+
+    def __init__(self, sink: AdapterEventSink, *, version: str | None = None) -> None:
+        super().__init__(
+            sink,
+            name="pydantic-ai-python",
+            framework="pydantic-ai",
+            language="python",
+            version=version,
+        )

ase/adapters/io.py

@@ -0,0 +1,50 @@
+"""Event sinks for official ASE adapter SDKs."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Protocol
+
+from ase.adapters.model import AdapterEvent
+from ase.errors import AdapterError
+
+
+class AdapterEventSink(Protocol):
+    """Define the minimal write surface required by adapter SDKs."""
+
+    def write(self, event: AdapterEvent) -> None:
+        """Persist one adapter event."""
+
+
+class JsonlFileEventSink:
+    """Append adapter events to disk for replay and certification."""
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+
+    def write(self, event: AdapterEvent) -> None:
+        """Write one JSONL adapter event with contextual file errors."""
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with self._path.open("a", encoding="utf-8") as handle:
+                handle.write(json.dumps(event.model_dump(), separators=(",", ":")))
+                handle.write("\n")
+        except OSError as exc:
+            raise AdapterError(f"failed to write adapter event sink {self._path}: {exc}") from exc
+
+
+class InMemoryEventSink:
+    """Retain adapter events in memory for tests and local examples."""
+
+    def __init__(self) -> None:
+        self._events: list[AdapterEvent] = []
+
+    def write(self, event: AdapterEvent) -> None:
+        """Append one event to the in-memory sink."""
+        self._events.append(event)
+
+    @property
+    def events(self) -> list[AdapterEvent]:
+        """Return a snapshot of all emitted events."""
+        return list(self._events)

ase/adapters/model.py

@@ -0,0 +1,89 @@
+"""Adapter protocol models for ingesting external agent runtimes into ASE."""
+
+from __future__ import annotations
+
+import time
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+ADAPTER_PROTOCOL_VERSION = 1
+
+
+class AdapterTransport(StrEnum):
+    """Describe how an external runtime sends adapter events to ASE."""
+
+    JSONL_STDIO = "jsonl-stdio"
+    HTTP = "http"
+
+
+class AdapterEventType(StrEnum):
+    """Enumerate normalized lifecycle and protocol events for adapters."""
+
+    AGENT_START = "agent_start"
+    AGENT_END = "agent_end"
+    TOOL_START = "tool_start"
+    TOOL_END = "tool_end"
+    HANDOFF = "handoff"
+    GUARDRAIL = "guardrail"
+    APPROVAL = "approval"
+    SESSION_READ = "session_read"
+    SESSION_WRITE = "session_write"
+    HUMAN_FEEDBACK = "human_feedback"
+    STREAM_CHUNK = "stream_chunk"
+
+
+class AdapterEvent(BaseModel):
+    """Represent one normalized adapter event emitted by a framework runtime."""
+
+    protocol_version: int = ADAPTER_PROTOCOL_VERSION
+    event_type: AdapterEventType
+    timestamp_ms: float = Field(default_factory=lambda: time.time() * 1000)
+    event_id: str
+    span_id: str | None = None
+    run_id: str | None = None
+    agent_id: str | None = None
+    parent_agent_id: str | None = None
+    target_agent_id: str | None = None
+    name: str | None = None
+    tool_kind: str | None = None
+    method: str | None = None
+    target: str | None = None
+    session_id: str | None = None
+    approval_id: str | None = None
+    granted: bool | None = None
+    status: str | None = None
+    protocol: str | None = None
+    message: str | None = None
+    data: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def validate_required_fields(self) -> AdapterEvent:
+        """Enforce event-specific fields so replay remains deterministic."""
+        if (
+            self.event_type in {AdapterEventType.TOOL_START, AdapterEventType.TOOL_END}
+            and (not self.tool_kind or not self.method or not self.target)
+        ):
+            raise ValueError("tool_start/tool_end require tool_kind, method, and target")
+        if self.event_type == AdapterEventType.APPROVAL and not self.approval_id:
+            raise ValueError("approval requires approval_id")
+        if self.event_type in {
+            AdapterEventType.SESSION_READ,
+            AdapterEventType.SESSION_WRITE,
+        } and not self.session_id:
+            raise ValueError("session_read/session_write require session_id")
+        if self.event_type == AdapterEventType.HANDOFF and not self.target_agent_id:
+            raise ValueError("handoff requires target_agent_id")
+        return self
+
+
+class AdapterVerificationResult(BaseModel):
+    """Capture pass/fail validation results for an adapter event stream."""
+
+    passed: bool
+    total_events: int
+    event_type_counts: dict[str, int] = Field(default_factory=dict)
+    errors: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)

ase/adapters/protocol.py

@@ -0,0 +1,72 @@
+"""Read and verify adapter JSONL event streams."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from pathlib import Path
+
+from ase.adapters.model import AdapterEvent, AdapterEventType, AdapterVerificationResult
+from ase.errors import AdapterProtocolError
+
+
+def read_jsonl_events(path: Path) -> list[AdapterEvent]:
+    """Load a JSONL adapter event file with contextual parse errors."""
+    if not path.exists():
+        raise AdapterProtocolError(f"adapter event file not found: {path}")
+    events: list[AdapterEvent] = []
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError as exc:
+        raise AdapterProtocolError(f"failed to read adapter event file {path}: {exc}") from exc
+    for index, line in enumerate(lines, start=1):
+        if not line.strip():
+            continue
+        try:
+            payload = json.loads(line)
+            events.append(AdapterEvent.model_validate(payload))
+        except Exception as exc:
+            raise AdapterProtocolError(
+                f"invalid adapter event at {path}:{index}: {exc}"
+            ) from exc
+    return events
+
+
+def verify_events(events: list[AdapterEvent]) -> AdapterVerificationResult:
+    """Validate event ordering and structural invariants for replay safety."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    counts = Counter(event.event_type.value for event in events)
+    if not events:
+        errors.append("adapter event stream is empty")
+    if counts[AdapterEventType.AGENT_START.value] == 0:
+        errors.append("missing agent_start event")
+    if counts[AdapterEventType.AGENT_END.value] == 0:
+        errors.append("missing agent_end event")
+
+    open_spans: set[str] = set()
+    for event in events:
+        if event.event_type == AdapterEventType.TOOL_START:
+            open_spans.add(event.span_id or event.event_id)
+        if event.event_type == AdapterEventType.TOOL_END:
+            span_id = event.span_id or event.event_id
+            if span_id not in open_spans:
+                errors.append(f"tool_end missing matching tool_start for span {span_id}")
+            else:
+                open_spans.remove(span_id)
+    if open_spans:
+        warnings.append("adapter event stream ended with open tool spans")
+
+    return AdapterVerificationResult(
+        passed=not errors,
+        total_events=len(events),
+        event_type_counts=dict(counts),
+        errors=errors,
+        warnings=warnings,
+    )
+
+
+def read_and_verify(path: Path) -> tuple[list[AdapterEvent], AdapterVerificationResult]:
+    """Load one adapter event file and return both events and verification."""
+    events = read_jsonl_events(path)
+    return events, verify_events(events)