ase-python 0.1.0__py3-none-any.whl

ase/adapters/replay.py

@@ -0,0 +1,261 @@
+"""Convert adapter event streams into ASE-native traces."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ase.adapters.model import AdapterEvent, AdapterEventType
+from ase.trace.builder import TraceBuilder
+from ase.trace.model import (
+    AdapterMetadata,
+    AgentGraphNode,
+    ExternalTraceRef,
+    HandoffEdge,
+    ProtocolEvent,
+    RuntimeProvenance,
+    SessionTraceEvent,
+    ToolCallEvent,
+    ToolCallKind,
+    Trace,
+    TraceStatus,
+)
+
+
+def trace_from_adapter_events(
+    events: list[AdapterEvent],
+    scenario_id: str,
+    scenario_name: str,
+) -> Trace:
+    """Build an ASE trace from a validated adapter event stream."""
+    builder = TraceBuilder(scenario_id=scenario_id, scenario_name=scenario_name)
+    trace = _replay_events(builder, events)
+    _attach_adapter_metadata(trace, events)
+    return trace
+
+
+def _replay_events(builder: TraceBuilder, events: list[AdapterEvent]) -> Trace:
+    """Replay adapter events into trace-level tool calls and protocol blocks."""
+    pending_tools: dict[str, AdapterEvent] = {}
+    status = TraceStatus.PASSED
+    error_message: str | None = None
+    trace = builder.current_trace
+
+    for event in events:
+        _track_agent_node(trace, event)
+        _attach_external_trace_ref(trace, event)
+        if event.event_type == AdapterEventType.APPROVAL:
+            builder.add_approval(approval=_approval_event(event))
+            continue
+        if event.event_type == AdapterEventType.TOOL_START:
+            _append_tool_protocol_event(trace, event)
+            pending_tools[event.span_id or event.event_id] = event
+            continue
+        if event.event_type == AdapterEventType.TOOL_END:
+            _append_tool_call(builder, pending_tools, event)
+            _append_tool_protocol_event(trace, event)
+            if _is_error_status(event.status):
+                status = TraceStatus.FAILED
+                error_message = event.message or error_message
+            continue
+        if event.event_type in {
+            AdapterEventType.SESSION_READ,
+            AdapterEventType.SESSION_WRITE,
+        }:
+            trace.session_events.append(_session_event(event))
+            trace.protocol_events.append(_protocol_event(event))
+            continue
+        if event.event_type == AdapterEventType.HANDOFF:
+            trace.handoff_edges.append(_handoff_edge(event))
+        if event.event_type in {
+            AdapterEventType.HANDOFF,
+            AdapterEventType.GUARDRAIL,
+            AdapterEventType.HUMAN_FEEDBACK,
+            AdapterEventType.STREAM_CHUNK,
+        }:
+            trace.protocol_events.append(_protocol_event(event))
+        if event.event_type == AdapterEventType.AGENT_END and _is_error_status(event.status):
+            status = TraceStatus.FAILED
+            error_message = event.message or error_message
+
+    if pending_tools and status == TraceStatus.PASSED:
+        status = TraceStatus.ERROR
+        error_message = "adapter event stream ended with unfinished tool spans"
+    return builder.finish(status=status, error_message=error_message)
+
+
+def _append_tool_call(
+    builder: TraceBuilder,
+    pending_tools: dict[str, AdapterEvent],
+    event: AdapterEvent,
+) -> None:
+    """Combine tool_start/tool_end events into one ASE tool call record."""
+    span_key = event.span_id or event.event_id
+    start = pending_tools.pop(span_key, event)
+    duration = max(event.timestamp_ms - start.timestamp_ms, 0.0)
+    builder.add_tool_call(
+        ToolCallEvent(
+            kind=_tool_call_kind(event.tool_kind),
+            method=event.method or "UNKNOWN",
+            target=event.target or "unknown",
+            payload=start.data or start.metadata,
+            response_status=_response_status(event),
+            response_body=_response_body(event),
+            duration_ms=duration,
+        )
+    )
+
+
+def _tool_call_kind(raw_kind: str | None) -> ToolCallKind:
+    """Map adapter tool kinds onto ASE's native tool-call taxonomy."""
+    try:
+        return ToolCallKind(raw_kind or ToolCallKind.UNKNOWN.value)
+    except ValueError:
+        return ToolCallKind.UNKNOWN
+
+
+def _track_agent_node(trace: Trace, event: AdapterEvent) -> None:
+    """Register agent identities for multi-agent traces."""
+    if not event.agent_id:
+        return
+    existing = {node.agent_id for node in trace.agent_graph.nodes}
+    if event.agent_id in existing:
+        return
+    trace.agent_graph.nodes.append(
+        AgentGraphNode(
+            agent_id=event.agent_id,
+            name=event.name,
+            parent_agent_id=event.parent_agent_id,
+            metadata=event.metadata,
+        )
+    )
+
+
+def _attach_adapter_metadata(trace: Trace, events: list[AdapterEvent]) -> None:
+    """Lift adapter metadata from the stream onto the trace root."""
+    metadata = _first_metadata(events)
+    adapter_name = str(metadata.get("adapter_name", "external-adapter"))
+    transport = str(metadata.get("transport", "jsonl-stdio"))
+    trace.adapter_metadata = AdapterMetadata(
+        name=adapter_name,
+        transport=transport,
+        framework=_optional_str(metadata.get("framework")),
+        language=_optional_str(metadata.get("language")),
+        version=_optional_str(metadata.get("adapter_version")),
+        source="adapter",
+        metadata=dict(metadata),
+    )
+    trace.runtime_provenance = RuntimeProvenance(
+        mode="adapter",
+        framework=_optional_str(metadata.get("framework")),
+        framework_version=_optional_str(metadata.get("framework_version")),
+        adapter_name=adapter_name,
+        adapter_version=_optional_str(metadata.get("adapter_version")),
+        event_source=_optional_str(metadata.get("event_source")),
+        metadata=dict(metadata),
+    )
+
+
+def _attach_external_trace_ref(trace: Trace, event: AdapterEvent) -> None:
+    """Preserve references to external tracing systems when provided."""
+    external = event.metadata.get("external_trace")
+    if not isinstance(external, dict):
+        return
+    if not external.get("system") or not external.get("trace_id"):
+        return
+    trace.external_trace_refs.append(
+        ExternalTraceRef(
+            system=str(external["system"]),
+            trace_id=str(external["trace_id"]),
+            url=_optional_str(external.get("url")),
+            metadata={
+                key: value
+                for key, value in external.items()
+                if key not in {"system", "trace_id", "url"}
+            },
+        )
+    )
+
+
+def _session_event(event: AdapterEvent) -> SessionTraceEvent:
+    """Translate adapter session activity into ASE session events."""
+    return SessionTraceEvent(
+        session_id=event.session_id or "unknown",
+        operation=event.event_type.value,
+        timestamp_ms=event.timestamp_ms,
+        agent_id=event.agent_id,
+        key=_optional_str(event.data.get("key")),
+        metadata=dict(event.data),
+    )
+
+
+def _handoff_edge(event: AdapterEvent) -> HandoffEdge:
+    """Translate adapter handoff events into ASE handoff edges."""
+    return HandoffEdge(
+        from_agent_id=event.agent_id or "unknown",
+        to_agent_id=event.target_agent_id or "unknown",
+        timestamp_ms=event.timestamp_ms,
+        label=event.name,
+        metadata=dict(event.data),
+    )
+
+
+def _protocol_event(event: AdapterEvent) -> ProtocolEvent:
+    """Preserve non-tool protocol events for replay and certification."""
+    return ProtocolEvent(
+        protocol=event.protocol or "adapter",
+        event_type=event.event_type.value,
+        timestamp_ms=event.timestamp_ms,
+        agent_id=event.agent_id,
+        metadata={"data": dict(event.data), "message": event.message, **event.metadata},
+    )
+
+
+def _approval_event(event: AdapterEvent) -> Any:
+    """Build an approval event compatible with TraceBuilder's API."""
+    from ase.trace.model import ApprovalEvent
+
+    return ApprovalEvent(
+        approval_id=event.approval_id or "approval",
+        actor=event.agent_id or "adapter",
+        granted=bool(event.granted if event.granted is not None else True),
+    )
+
+
+def _response_status(event: AdapterEvent) -> int | None:
+    """Extract a response status code from adapter data when present."""
+    raw_status = event.data.get("response_status") or event.data.get("status_code")
+    return raw_status if isinstance(raw_status, int) else None
+
+
+def _response_body(event: AdapterEvent) -> dict[str, Any] | None:
+    """Preserve tool-end payloads and protocol hints for imported traces."""
+    body = dict(event.data or {})
+    if event.protocol is not None:
+        body.setdefault("protocol", event.protocol)
+    return body or None
+
+
+def _append_tool_protocol_event(trace: Trace, event: AdapterEvent) -> None:
+    """Preserve non-default tool protocols such as MCP alongside tool calls."""
+    if event.protocol is not None:
+        trace.protocol_events.append(_protocol_event(event))
+
+
+def _is_error_status(status: str | None) -> bool:
+    """Treat explicit error-like statuses as failed execution outcomes."""
+    return (status or "").lower() in {"error", "failed", "failure", "timeout"}
+
+
+def _first_metadata(events: list[AdapterEvent]) -> dict[str, Any]:
+    """Return the first non-empty metadata mapping from the stream."""
+    for event in events:
+        if event.metadata:
+            return dict(event.metadata)
+    return {}
+
+
+def _optional_str(value: Any) -> str | None:
+    """Convert optional values to strings when present."""
+    if value is None:
+        return None
+    return str(value)

ase/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Source-backed CLI package that composes with recovery overlays."""
+
+from __future__ import annotations
+
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)

ase/cli/_trace_outputs.py

@@ -0,0 +1,40 @@
+"""Shared helpers for writing native traces and rendered outputs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ase.config.model import OutputFormat
+from ase.reporting import json_report, markdown
+from ase.trace.model import Trace
+from ase.trace.otel_export import to_otel_dict
+from ase.trace.serializer import write_to_file
+
+
+def write_trace_artifacts(
+    trace: Trace,
+    *,
+    trace_out: Path | None = None,
+    output: OutputFormat | None = None,
+    out_file: Path | None = None,
+) -> None:
+    """Write native traces and optional rendered outputs for CLI workflows."""
+    if trace_out is not None:
+        write_to_file(trace, trace_out)
+    if output is None or out_file is None:
+        return
+    rendered = render_trace(trace, output)
+    out_file.write_text(rendered + "\n", encoding="utf-8")
+
+
+def render_trace(trace: Trace, output: OutputFormat) -> str:
+    """Render one trace using the requested public output format."""
+    if output == OutputFormat.JSON:
+        return json_report.to_string(trace=trace)
+    if output == OutputFormat.MARKDOWN:
+        return markdown.to_string(trace=trace)
+    if output == OutputFormat.OTEL_JSON:
+        import json
+
+        return json.dumps(to_otel_dict(trace), indent=2)
+    return json_report.to_string(trace=trace)

ase/cli/adapter_cmd.py

@@ -0,0 +1,38 @@
+"""Adapter protocol CLI commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from ase.adapters.protocol import read_and_verify
+from ase.errors import AdapterProtocolError
+
+app = typer.Typer(help="Validate ASE adapter event streams.")
+_console = Console()
+
+
+@app.command("verify")
+def verify(
+    event_file: Annotated[Path, typer.Argument(help="JSONL adapter event file to validate.")],
+) -> None:
+    """Validate an adapter event file and print its event-family counts."""
+    try:
+        _events, result = read_and_verify(event_file)
+    except AdapterProtocolError as exc:
+        _console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1) from exc
+    _console.print(f"events: {result.total_events}")
+    for event_type, count in sorted(result.event_type_counts.items()):
+        _console.print(f"  {event_type}: {count}")
+    for warning in result.warnings:
+        _console.print(f"[yellow]{warning}[/yellow]")
+    if result.passed:
+        _console.print("[green]adapter event stream passed[/green]")
+        return
+    for error in result.errors:
+        _console.print(f"[red]{error}[/red]")
+    raise typer.Exit(code=1)

ase/cli/certify_cmd.py

@@ -0,0 +1,74 @@
+"""ase certify — validate a manifest and emit certification output."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ase.conformance.service import certify_manifest, load_manifest, sign_result
+from ase.errors import ConformanceError
+
+_console = Console()
+
+
+def run(
+    manifest: Annotated[Path, typer.Argument(help="Conformance manifest to certify.")],
+    out_file: Annotated[
+        Path | None,
+        typer.Option("--out-file", "-f", help="Write certification JSON to this file."),
+    ] = None,
+    signing_key_env: Annotated[
+        str | None,
+        typer.Option("--signing-key-env", help="Env var containing the HMAC signing key."),
+    ] = None,
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose", help="Render all certification checks."),
+    ] = False,
+) -> None:
+    """Run a conformance manifest and emit a certification result."""
+    try:
+        loaded = load_manifest(manifest)
+        result = sign_result(certify_manifest(loaded, manifest), signing_key_env=signing_key_env)
+    except ConformanceError as exc:
+        _console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1) from exc
+
+    if out_file is not None:
+        out_file.write_text(json.dumps(result.model_dump(), indent=2) + "\n", encoding="utf-8")
+    _render_result(result, verbose)
+    if not result.passed:
+        raise typer.Exit(code=1)
+
+
+def _render_result(result: object, verbose: bool) -> None:
+    """Render a compact certification summary with optional detailed checks."""
+    from ase.conformance.model import ConformanceResult
+
+    assert isinstance(result, ConformanceResult)
+    status = "[green]passed[/green]" if result.passed else "[red]failed[/red]"
+    _console.print(f"framework: {result.framework or 'unknown'}")
+    _console.print(f"adapter:   {result.adapter_name}")
+    _console.print(f"bundle:    {result.bundle_family}@{result.bundle_version}")
+    _console.print(f"level:     {result.certification_level.value}")
+    _console.print(f"status:    {status}")
+    if not verbose and result.passed:
+        return
+    table = Table(title="Certification Checks")
+    table.add_column("Case")
+    table.add_column("Check")
+    table.add_column("Status")
+    table.add_column("Message")
+    for check in result.checks:
+        table.add_row(
+            check.case_id,
+            check.check_id,
+            "passed" if check.passed else "failed",
+            check.message,
+        )
+    _console.print(table)

ase/cli/compare.py

@@ -0,0 +1,145 @@
+"""ase compare — diff two saved ASE traces."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+from ase.config.model import OutputFormat
+from ase.errors import CLIError, TraceSerializationError
+from ase.trace.model import Trace
+
+_console = Console()
+
+
+def run(
+    baseline: Annotated[Path, typer.Argument(help="Baseline native ASE trace JSON file.")],
+    candidate: Annotated[Path, typer.Argument(help="Candidate native ASE trace JSON file.")],
+    output: Annotated[
+        OutputFormat,
+        typer.Option("--output", "-o", help="Output format."),
+    ] = OutputFormat.TERMINAL,
+) -> None:
+    """Compare two traces by stable runtime, evaluation, and metric fields."""
+    baseline_trace = _load_trace(baseline)
+    candidate_trace = _load_trace(candidate)
+    diff = _build_diff(baseline_trace, candidate_trace)
+    if output == OutputFormat.JSON:
+        _console.print(json.dumps(diff, indent=2))
+        return
+    if output == OutputFormat.MARKDOWN:
+        _console.print(_to_markdown(diff))
+        return
+    if output != OutputFormat.TERMINAL:
+        raise CLIError(f"unsupported compare output format: {output}")
+    _console.print(_to_terminal_text(diff))
+
+
+def _load_trace(path: Path) -> Trace:
+    """Load one native ASE trace with contextual parse errors."""
+    try:
+        return Trace.model_validate_json(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise TraceSerializationError(f"failed to read trace file {path}: {exc}") from exc
+    except Exception as exc:  # noqa: BLE001
+        raise TraceSerializationError(f"failed to parse trace file {path}: {exc}") from exc
+
+
+def _build_diff(baseline: Trace, candidate: Trace) -> dict[str, Any]:
+    """Produce a small, stable diff for operator comparison workflows."""
+    base_eval = baseline.evaluation
+    cand_eval = candidate.evaluation
+    base_runtime = baseline.runtime_provenance
+    cand_runtime = candidate.runtime_provenance
+    added = sorted(
+        set(cand_eval.failing_evaluators if cand_eval else [])
+        - set(base_eval.failing_evaluators if base_eval else [])
+    )
+    removed = sorted(
+        set(base_eval.failing_evaluators if base_eval else [])
+        - set(cand_eval.failing_evaluators if cand_eval else [])
+    )
+    return {
+        "baseline_trace_id": baseline.trace_id,
+        "candidate_trace_id": candidate.trace_id,
+        "scenario_ids": [baseline.scenario_id, candidate.scenario_id],
+        "runtime_mode": [
+            base_runtime.mode if base_runtime else None,
+            cand_runtime.mode if cand_runtime else None,
+        ],
+        "framework": [
+            base_runtime.framework if base_runtime else None,
+            cand_runtime.framework if cand_runtime else None,
+        ],
+        "status": [baseline.status, candidate.status],
+        "evaluation_passed": [
+            base_eval.passed if base_eval else None,
+            cand_eval.passed if cand_eval else None,
+        ],
+        "ase_score_delta": (cand_eval.ase_score if cand_eval else 0.0)
+        - (base_eval.ase_score if base_eval else 0.0),
+        "failing_evaluators_added": added,
+        "failing_evaluators_removed": removed,
+        "metrics": {
+            "tool_calls": [
+                baseline.metrics.total_tool_calls,
+                candidate.metrics.total_tool_calls,
+            ],
+            "llm_calls": [
+                baseline.metrics.total_llm_calls,
+                candidate.metrics.total_llm_calls,
+            ],
+            "tokens": [
+                baseline.metrics.total_tokens_used,
+                candidate.metrics.total_tokens_used,
+            ],
+            "duration_ms": [
+                baseline.metrics.total_duration_ms,
+                candidate.metrics.total_duration_ms,
+            ],
+            "tool_breakdown": [
+                baseline.metrics.tool_call_breakdown,
+                candidate.metrics.tool_call_breakdown,
+            ],
+        },
+    }
+
+
+def _to_terminal_text(diff: dict[str, Any]) -> str:
+    """Render a compact diff for direct terminal use."""
+    metrics = diff["metrics"]
+    return "\n".join(
+        [
+            f"baseline: {diff['baseline_trace_id']}",
+            f"candidate: {diff['candidate_trace_id']}",
+            f"scenario_ids: {diff['scenario_ids'][0]} -> {diff['scenario_ids'][1]}",
+            f"runtime_mode: {diff['runtime_mode'][0]} -> {diff['runtime_mode'][1]}",
+            f"framework: {diff['framework'][0]} -> {diff['framework'][1]}",
+            f"status: {diff['status'][0]} -> {diff['status'][1]}",
+            f"evaluation: {diff['evaluation_passed'][0]} -> {diff['evaluation_passed'][1]}",
+            f"ase_score_delta: {diff['ase_score_delta']:.2f}",
+            f"tool_calls: {metrics['tool_calls'][0]} -> {metrics['tool_calls'][1]}",
+            f"tokens: {metrics['tokens'][0]} -> {metrics['tokens'][1]}",
+        ]
+    )
+
+
+def _to_markdown(diff: dict[str, Any]) -> str:
+    """Render a short Markdown diff for CI and review surfaces."""
+    metrics = diff["metrics"]
+    return "\n".join(
+        [
+            "# ASE Trace Diff",
+            "",
+            f"- Baseline: `{diff['baseline_trace_id']}`",
+            f"- Candidate: `{diff['candidate_trace_id']}`",
+            f"- Status: `{diff['status'][0]}` -> `{diff['status'][1]}`",
+            f"- Evaluation: `{diff['evaluation_passed'][0]}` -> `{diff['evaluation_passed'][1]}`",
+            f"- ASE score delta: `{diff['ase_score_delta']:.2f}`",
+            f"- Tool calls: `{metrics['tool_calls'][0]}` -> `{metrics['tool_calls'][1]}`",
+        ]
+    )

ase/cli/doctor_cmd.py

@@ -0,0 +1,45 @@
+"""ase doctor — lightweight environment sanity checks.
+
+This command exists to give operators a neutral boot-health signal without
+requiring a full scenario run.
+"""
+
+from __future__ import annotations
+
+import platform
+
+from rich.console import Console
+from rich.table import Table
+
+_console = Console()
+
+
+def run() -> None:
+    """Show whether ASE's core imports and runtime prerequisites are available."""
+    table = Table(title="ASE Doctor", expand=False)
+    table.add_column("Check", style="bold")
+    table.add_column("Status")
+    table.add_column("Details")
+    for row in _rows():
+        table.add_row(*row)
+    _console.print(table)
+
+
+def _rows() -> list[tuple[str, str, str]]:
+    """Keep doctor output deterministic and safe for clean environment checks."""
+    return [
+        ("python", "ok", platform.python_version()),
+        ("trace_model", *_import_status("ase.trace.model", "Trace")),
+        ("config_loader", *_import_status("ase.config.loader", "load_config")),
+        ("evaluation_engine", *_import_status("ase.evaluation.engine", "EvaluationEngine")),
+    ]
+
+
+def _import_status(module_name: str, attr_name: str) -> tuple[str, str]:
+    """Convert importability into simple operator-facing status strings."""
+    try:
+        module = __import__(module_name, fromlist=[attr_name])
+        getattr(module, attr_name)
+    except (AttributeError, ImportError, ModuleNotFoundError) as exc:
+        return ("fail", str(exc))
+    return ("ok", "available")

ase/cli/examples_cmd.py

@@ -0,0 +1,27 @@
+"""Public example-matrix CLI commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from ase.examples_matrix import run_examples
+
+app = typer.Typer(help="Run ASE's public example matrix.")
+_console = Console()
+
+
+@app.command("run")
+def run(
+    example: Annotated[
+        list[str] | None,
+        typer.Option("--example", help="Run only the named example(s)."),
+    ] = None,
+) -> None:
+    """Run the supported example matrix with the same commands users run."""
+    results = run_examples(example)
+    for result in results:
+        status = "[green]passed[/green]" if result.passed else "[red]failed[/red]"
+        _console.print(f"{result.example_name}: {status}")