ase-python 0.1.0__py3-none-any.whl

ase/trace/builder.py

@@ -0,0 +1,175 @@
+"""Helpers for incrementally constructing ASE traces."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from typing import Any
+
+import ulid
+
+from ase.errors import TraceError
+from ase.trace.model import (
+    ApprovalEvent,
+    DeterminismMetadata,
+    LLMRequestEvent,
+    LLMResponseEvent,
+    RuntimeProvenance,
+    ToolCallEvent,
+    Trace,
+    TraceEvent,
+    TraceEventKind,
+    TraceMetrics,
+    TraceStatus,
+)
+
+
+class TraceBuilder:
+    """Build one append-only trace from runtime events."""
+
+    def __init__(
+        self,
+        scenario_id: str,
+        scenario_name: str,
+        tags: dict[str, str] | None = None,
+    ) -> None:
+        self._trace = Trace(
+            trace_id=str(ulid.new()),
+            scenario_id=scenario_id,
+            scenario_name=scenario_name,
+            tags=dict(tags or {}),
+        )
+
+    @property
+    def current_trace(self) -> Trace:
+        """Expose the in-progress trace for replay helpers."""
+        return self._trace
+
+    def add_tool_call(self, tool_call: ToolCallEvent) -> TraceBuilder:
+        """Append one tool-call event to the trace."""
+        self._trace.events.append(
+            TraceEvent(
+                event_id=str(ulid.new()),
+                kind=TraceEventKind.TOOL_CALL,
+                tool_call=tool_call,
+            )
+        )
+        return self
+
+    def add_approval(self, approval: ApprovalEvent) -> TraceBuilder:
+        """Append one approval event to the trace."""
+        self._trace.events.append(
+            TraceEvent(
+                event_id=str(ulid.new()),
+                kind=TraceEventKind.APPROVAL,
+                approval=approval,
+            )
+        )
+        return self
+
+    def add_llm_request(self, llm_request: LLMRequestEvent) -> TraceBuilder:
+        """Append one LLM request event to the trace."""
+        self._trace.events.append(
+            TraceEvent(
+                event_id=str(ulid.new()),
+                kind=TraceEventKind.LLM_REQUEST,
+                llm_request=llm_request,
+            )
+        )
+        return self
+
+    def add_llm_response(self, llm_response: LLMResponseEvent) -> TraceBuilder:
+        """Append one LLM response event to the trace."""
+        self._trace.events.append(
+            TraceEvent(
+                event_id=str(ulid.new()),
+                kind=TraceEventKind.LLM_RESPONSE,
+                llm_response=llm_response,
+            )
+        )
+        return self
+
+    def add_raw_event(self, event: TraceEvent) -> TraceBuilder:
+        """Append one fully formed trace event."""
+        self._trace.events.append(event)
+        return self
+
+    def set_runtime_provenance(
+        self,
+        mode: str,
+        framework: str | None = None,
+        framework_version: str | None = None,
+        adapter_name: str | None = None,
+        adapter_version: str | None = None,
+        conformance_bundle_version: str | None = None,
+        event_source: str | None = None,
+        metadata: dict[str, object] | None = None,
+    ) -> TraceBuilder:
+        """Persist runtime provenance on the trace root."""
+        self._trace.runtime_provenance = RuntimeProvenance(
+            mode=mode,
+            framework=framework,
+            framework_version=framework_version,
+            adapter_name=adapter_name,
+            adapter_version=adapter_version,
+            conformance_bundle_version=conformance_bundle_version,
+            event_source=event_source,
+            metadata=dict(metadata or {}),
+        )
+        return self
+
+    def set_determinism(
+        self,
+        fixture_hash: str | None = None,
+        replay_key: str | None = None,
+        baseline_trace_id: str | None = None,
+    ) -> TraceBuilder:
+        """Persist deterministic replay metadata on the trace root."""
+        self._trace.determinism = DeterminismMetadata(
+            fixture_hash=fixture_hash,
+            replay_key=replay_key,
+            baseline_trace_id=baseline_trace_id,
+        )
+        return self
+
+    def finish(
+        self,
+        status: TraceStatus = TraceStatus.PASSED,
+        error_message: str | None = None,
+    ) -> Trace:
+        """Finalize the trace and compute aggregate metrics."""
+        if self._trace.status != TraceStatus.RUNNING and self._trace.ended_at_ms is not None:
+            raise TraceError(f"trace already finished: {self._trace.trace_id}")
+        self._trace.status = status
+        self._trace.ended_at_ms = time.time() * 1000
+        self._trace.error_message = error_message
+        self._trace.metrics = _compute_metrics(self._trace)
+        return self._trace
+
+
+def _compute_metrics(trace: Trace) -> TraceMetrics:
+    """Compute aggregate metrics from the trace event stream."""
+    metrics = TraceMetrics()
+    metrics.total_duration_ms = max(
+        (trace.ended_at_ms or trace.started_at_ms) - trace.started_at_ms,
+        0.0,
+    )
+    for event in trace.events:
+        if event.kind == TraceEventKind.TOOL_CALL and event.tool_call is not None:
+            metrics.total_tool_calls += 1
+            key = event.tool_call.kind.value
+            metrics.tool_call_breakdown[key] = metrics.tool_call_breakdown.get(key, 0) + 1
+        if event.kind == TraceEventKind.LLM_REQUEST:
+            metrics.total_llm_calls += 1
+            if event.llm_request and event.llm_request.token_count_estimate:
+                metrics.total_tokens_used += event.llm_request.token_count_estimate
+        if event.kind == TraceEventKind.LLM_RESPONSE and event.llm_response is not None:
+            metrics.total_tokens_used += event.llm_response.output_tokens
+    return metrics
+
+
+def fixture_hash(payload: dict[str, Any]) -> str:
+    """Compute a stable content hash for deterministic fixture payloads."""
+    raw = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()

ase/trace/model.py

@@ -0,0 +1,264 @@
+"""Trace data model — the append-only record of a single agent run.
+
+CRITICAL: This schema is append-only. Fields are NEVER removed or renamed.
+New optional fields may be added with a default. Bump TRACE_SCHEMA_VERSION
+when adding fields. Never change the meaning of an existing field.
+"""
+
+from __future__ import annotations
+
+import time
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+TRACE_SCHEMA_VERSION = 7
+
+
+class ToolCallKind(StrEnum):
+    """Classify what kind of backend a tool call targeted."""
+
+    DATABASE = "database"
+    HTTP_API = "http_api"
+    EMAIL = "email"
+    FILESYSTEM = "filesystem"
+    QUEUE = "queue"
+    UNKNOWN = "unknown"
+
+
+class TraceEventKind(StrEnum):
+    """Represent the type of event recorded in a trace."""
+
+    TOOL_CALL = "tool_call"
+    TOOL_RESPONSE = "tool_response"
+    LLM_REQUEST = "llm_request"
+    LLM_RESPONSE = "llm_response"
+    APPROVAL = "approval"
+    SCENARIO_START = "scenario_start"
+    SCENARIO_END = "scenario_end"
+
+
+class TraceStatus(StrEnum):
+    """Describe the overall outcome of one trace."""
+
+    RUNNING = "running"
+    PASSED = "passed"
+    FAILED = "failed"
+    ERROR = "error"
+
+
+class ToolCallEvent(BaseModel):
+    """Capture one outbound tool call made by the agent."""
+
+    kind: ToolCallKind
+    method: str = Field(description="HTTP method or SQL verb")
+    target: str = Field(description="URL, table name, or address")
+    payload: dict[str, Any] = Field(default_factory=dict)
+    response_status: int | None = None
+    response_body: dict[str, Any] | None = None
+    duration_ms: float | None = None
+
+
+class LLMRequestEvent(BaseModel):
+    """Capture one model request without storing raw prompt text."""
+
+    model: str
+    prompt_hash: str = Field(description="SHA-256 of the full prompt")
+    token_count_estimate: int | None = None
+
+
+class LLMResponseEvent(BaseModel):
+    """Capture one model response summary."""
+
+    model: str
+    output_tokens: int
+    finish_reason: str
+
+
+class ApprovalEvent(BaseModel):
+    """Capture one approval signal attached to the scenario or runtime."""
+
+    approval_id: str
+    actor: str
+    granted: bool = True
+
+
+class TraceEvent(BaseModel):
+    """Represent one timestamped event in the trace timeline."""
+
+    event_id: str
+    kind: TraceEventKind
+    timestamp_ms: float = Field(default_factory=lambda: time.time() * 1000)
+    parent_event_id: str | None = None
+    tool_call: ToolCallEvent | None = None
+    llm_request: LLMRequestEvent | None = None
+    llm_response: LLMResponseEvent | None = None
+    approval: ApprovalEvent | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class TraceMetrics(BaseModel):
+    """Store aggregate metrics computed from all trace events."""
+
+    total_tool_calls: int = 0
+    total_llm_calls: int = 0
+    total_tokens_used: int = 0
+    total_duration_ms: float = 0.0
+    tool_call_breakdown: dict[str, int] = Field(default_factory=dict)
+
+
+class PolicyResult(BaseModel):
+    """Persist the outcome of one policy assertion on the trace."""
+
+    policy_id: str
+    evaluator: str
+    passed: bool
+    message: str = ""
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class MutationSummary(BaseModel):
+    """Summarize mutating tool calls across the run."""
+
+    total_mutations: int = 0
+    by_target: dict[str, int] = Field(default_factory=dict)
+
+
+class DeterminismMetadata(BaseModel):
+    """Record replay-related metadata used for deterministic comparison."""
+
+    fixture_hash: str | None = None
+    replay_key: str | None = None
+    baseline_trace_id: str | None = None
+
+
+class TraceEvaluation(BaseModel):
+    """Persist the final evaluation outcome for one trace."""
+
+    passed: bool
+    ase_score: float
+    total: int
+    passed_count: int
+    failed_count: int
+    failing_evaluators: list[str] = Field(default_factory=list)
+
+
+class RuntimeProvenance(BaseModel):
+    """Describe which ASE execution path produced the trace."""
+
+    mode: str
+    framework: str | None = None
+    framework_version: str | None = None
+    adapter_name: str | None = None
+    adapter_version: str | None = None
+    conformance_bundle_version: str | None = None
+    event_source: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AdapterMetadata(BaseModel):
+    """Describe the adapter or external runtime that produced the trace."""
+
+    name: str
+    transport: str
+    framework: str | None = None
+    language: str | None = None
+    version: str | None = None
+    source: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentGraphNode(BaseModel):
+    """Represent one node in a multi-agent execution graph."""
+
+    agent_id: str
+    name: str | None = None
+    role: str | None = None
+    parent_agent_id: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentGraph(BaseModel):
+    """Store graph metadata for multi-agent runs."""
+
+    nodes: list[AgentGraphNode] = Field(default_factory=list)
+
+
+class SessionTraceEvent(BaseModel):
+    """Capture one session read or write checkpoint."""
+
+    session_id: str
+    operation: str
+    timestamp_ms: float = Field(default_factory=lambda: time.time() * 1000)
+    agent_id: str | None = None
+    key: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class HandoffEdge(BaseModel):
+    """Capture one delegation edge between two agents."""
+
+    from_agent_id: str
+    to_agent_id: str
+    timestamp_ms: float = Field(default_factory=lambda: time.time() * 1000)
+    label: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ExternalTraceRef(BaseModel):
+    """Reference an external trace in another system."""
+
+    system: str
+    trace_id: str
+    url: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ProtocolEvent(BaseModel):
+    """Preserve protocol-level events outside the tool timeline."""
+
+    protocol: str
+    event_type: str
+    timestamp_ms: float = Field(default_factory=lambda: time.time() * 1000)
+    agent_id: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class TraceCertificationLevel(StrEnum):
+    """Represent the capability tier granted to a certified trace."""
+
+    CORE = "core"
+    STATEFUL = "stateful"
+    MULTI_AGENT = "multi_agent"
+    MCP = "mcp"
+    REALTIME = "realtime"
+
+
+class Trace(BaseModel):
+    """Complete record of a single agent scenario run."""
+
+    schema_version: int = TRACE_SCHEMA_VERSION
+    trace_id: str
+    scenario_id: str
+    scenario_name: str
+    started_at_ms: float = Field(default_factory=lambda: time.time() * 1000)
+    ended_at_ms: float | None = None
+    status: TraceStatus = TraceStatus.RUNNING
+    events: list[TraceEvent] = Field(default_factory=list)
+    metrics: TraceMetrics = Field(default_factory=TraceMetrics)
+    tags: dict[str, str] = Field(default_factory=dict)
+    mutation_summary: MutationSummary = Field(default_factory=MutationSummary)
+    policy_results: list[PolicyResult] = Field(default_factory=list)
+    determinism: DeterminismMetadata = Field(default_factory=DeterminismMetadata)
+    evaluation: TraceEvaluation | None = None
+    runtime_provenance: RuntimeProvenance | None = None
+    adapter_metadata: AdapterMetadata | None = None
+    agent_graph: AgentGraph = Field(default_factory=AgentGraph)
+    session_events: list[SessionTraceEvent] = Field(default_factory=list)
+    handoff_edges: list[HandoffEdge] = Field(default_factory=list)
+    external_trace_refs: list[ExternalTraceRef] = Field(default_factory=list)
+    protocol_events: list[ProtocolEvent] = Field(default_factory=list)
+    certification_level: TraceCertificationLevel | None = None
+    error_message: str | None = None
+    stderr_output: str | None = None

ase/trace/otel_export.py

@@ -0,0 +1,75 @@
+"""OTEL-like export helpers for ASE traces."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from ase.trace.model import Trace, TraceEventKind
+
+
+def to_otel_dict(trace: Trace) -> dict[str, Any]:
+    """Export one ASE trace into a compact OTEL-like JSON structure."""
+    runtime = trace.runtime_provenance
+    attributes = {
+        "ase.trace_id": trace.trace_id,
+        "ase.scenario_id": trace.scenario_id,
+        "ase.status": trace.status.value,
+        "ase.runtime_mode": runtime.mode if runtime else "unknown",
+        "ase.framework": runtime.framework if runtime and runtime.framework else "",
+    }
+    if trace.evaluation is not None:
+        attributes["ase.evaluation.passed"] = trace.evaluation.passed
+        attributes["ase.evaluation.score"] = trace.evaluation.ase_score
+    spans = [_span_from_event(trace.trace_id, event) for event in trace.events]
+    return {
+        "resourceSpans": [
+            {
+                "resource": {"attributes": _kv(attributes)},
+                "scopeSpans": [{"scope": {"name": "ase"}, "spans": spans}],
+            }
+        ]
+    }
+
+
+def _span_from_event(trace_id: str, event: object) -> dict[str, Any]:
+    """Convert one ASE event into an OTEL-like span."""
+    from ase.trace.model import TraceEvent
+
+    assert isinstance(event, TraceEvent)
+    span_name = event.kind.value
+    attributes: dict[str, Any] = {"ase.event_id": event.event_id}
+    if event.tool_call is not None:
+        attributes.update(
+            {
+                "ase.tool.kind": event.tool_call.kind.value,
+                "ase.tool.method": event.tool_call.method,
+                "ase.tool.target": event.tool_call.target,
+            }
+        )
+    return {
+        "traceId": _hash_hex(trace_id, 32),
+        "spanId": _hash_hex(event.event_id, 16),
+        "name": span_name,
+        "kind": _otel_kind(event.kind),
+        "startTimeUnixNano": int(event.timestamp_ms * 1_000_000),
+        "endTimeUnixNano": int(event.timestamp_ms * 1_000_000),
+        "attributes": _kv(attributes),
+    }
+
+
+def _otel_kind(kind: TraceEventKind) -> int:
+    """Map ASE event kinds onto OTEL span kinds."""
+    if kind == TraceEventKind.TOOL_CALL:
+        return 3
+    return 1
+
+
+def _hash_hex(value: str, length: int) -> str:
+    """Generate a deterministic hex identifier of the requested length."""
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length]
+
+
+def _kv(values: dict[str, Any]) -> list[dict[str, Any]]:
+    """Convert a flat mapping into OTEL-like key/value attributes."""
+    return [{"key": key, "value": {"stringValue": str(value)}} for key, value in values.items()]

ase/trace/otel_import.py

@@ -0,0 +1,96 @@
+"""OTEL-like import helpers for ASE traces."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ase.errors import OTelImportError
+from ase.trace.builder import TraceBuilder
+from ase.trace.model import AdapterMetadata, RuntimeProvenance, ToolCallEvent, ToolCallKind, Trace
+
+
+def read_otel_trace(path: Path) -> Trace:
+    """Read one OTEL-like JSON trace and convert it into ASE format."""
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise OTelImportError(f"failed to read OTEL trace {path}: {exc}") from exc
+    return trace_from_otel_dict(payload)
+
+
+def trace_from_otel_dict(data: dict[str, Any]) -> Trace:
+    """Convert OTEL-like JSON into a native ASE trace."""
+    try:
+        resource_span = data["resourceSpans"][0]
+        scope_span = resource_span["scopeSpans"][0]
+        spans = scope_span.get("spans", [])
+    except (KeyError, IndexError, TypeError) as exc:
+        raise OTelImportError(f"invalid OTEL payload: {exc}") from exc
+    attrs = _attr_map(resource_span.get("resource", {}).get("attributes", []))
+    builder = TraceBuilder(
+        scenario_id=attrs.get("ase.scenario_id", "otel-import"),
+        scenario_name=attrs.get("ase.scenario_id", "otel-import"),
+    )
+    builder.set_runtime_provenance(
+        mode=attrs.get("ase.runtime_mode", "imported"),
+        framework=attrs.get("ase.framework") or None,
+    )
+    trace = builder.current_trace
+    trace.adapter_metadata = AdapterMetadata(
+        name="otel-import",
+        transport="otel-json",
+        framework=attrs.get("ase.framework") or None,
+        source="otel-import",
+    )
+    trace.runtime_provenance = RuntimeProvenance(
+        mode=attrs.get("ase.runtime_mode", "imported"),
+        framework=attrs.get("ase.framework") or None,
+        event_source="otel-json",
+    )
+    for span in spans:
+        span_attrs = _attr_map(span.get("attributes", []))
+        if "ase.tool.kind" not in span_attrs:
+            continue
+        builder.add_tool_call(
+            ToolCallEvent(
+                kind=_tool_kind(span_attrs.get("ase.tool.kind")),
+                method=span_attrs.get("ase.tool.method", "UNKNOWN"),
+                target=span_attrs.get("ase.tool.target", "unknown"),
+            )
+        )
+    return builder.finish()
+
+
+def _attr_map(attributes: list[dict[str, Any]]) -> dict[str, str]:
+    """Convert OTEL-like key/value attributes into a plain mapping."""
+    values: dict[str, str] = {}
+    for item in attributes:
+        key = item.get("key")
+        value = item.get("value", {})
+        if key is None:
+            continue
+        values[str(key)] = _attribute_value(value)
+    return values
+
+
+def _tool_kind(value: str | None) -> ToolCallKind:
+    """Parse imported tool kinds without crashing the full import."""
+    try:
+        return ToolCallKind(value or ToolCallKind.UNKNOWN.value)
+    except ValueError:
+        return ToolCallKind.UNKNOWN
+
+
+def _attribute_value(value: dict[str, Any]) -> str:
+    """Read OTEL-like scalar values without losing string attributes."""
+    if "stringValue" in value:
+        return str(value["stringValue"])
+    if "boolValue" in value:
+        return str(value["boolValue"])
+    if "intValue" in value:
+        return str(value["intValue"])
+    if "doubleValue" in value:
+        return str(value["doubleValue"])
+    return ""

ase/trace/redaction.py

@@ -0,0 +1,10 @@
+"""No-op redaction helpers for persisted traces."""
+
+from __future__ import annotations
+
+from ase.trace.model import Trace
+
+
+def redact_trace(trace: Trace) -> Trace:
+    """Return the trace unchanged until a richer redaction layer is restored."""
+    return trace

ase/trace/serializer.py

@@ -0,0 +1,50 @@
+"""JSON serialization helpers for native ASE traces."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ase.errors import TraceSchemaMigrationError, TraceSerializationError
+from ase.trace.model import TRACE_SCHEMA_VERSION, Trace
+
+
+def serialize(trace: Trace) -> str:
+    """Serialize one trace to stable JSON."""
+    try:
+        return json.dumps(trace.model_dump(mode="json"), indent=2)
+    except Exception as exc:  # noqa: BLE001
+        raise TraceSerializationError(f"failed to serialize trace {trace.trace_id}: {exc}") from exc
+
+
+def deserialize(raw: str) -> Trace:
+    """Parse one trace from native JSON."""
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise TraceSerializationError(f"failed to parse trace JSON: {exc}") from exc
+    schema_version = payload.get("schema_version", TRACE_SCHEMA_VERSION)
+    if schema_version > TRACE_SCHEMA_VERSION:
+        raise TraceSchemaMigrationError(
+            f"trace schema {schema_version} is newer than supported {TRACE_SCHEMA_VERSION}"
+        )
+    try:
+        return Trace.model_validate(payload)
+    except Exception as exc:  # noqa: BLE001
+        raise TraceSerializationError(f"failed to validate trace payload: {exc}") from exc
+
+
+def read_from_file(path: Path) -> Trace:
+    """Read one native trace from disk."""
+    try:
+        return deserialize(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise TraceSerializationError(f"failed to read trace file {path}: {exc}") from exc
+
+
+def write_to_file(trace: Trace, path: Path) -> None:
+    """Write one native trace to disk."""
+    try:
+        path.write_text(serialize(trace) + "\n", encoding="utf-8")
+    except OSError as exc:
+        raise TraceSerializationError(f"failed to write trace file {path}: {exc}") from exc