agent-learning-kit 0.1.0__py3-none-any.whl

fi/simulate/matrix_cli.py

@@ -0,0 +1,165 @@
+"""``python -m fi.simulate.matrix_cli`` — run a provider-matrix manifest.
+
+The matrix manifest references a base SDK simulation manifest and a list
+of provider × channel legs (see ``simulation.matrix.MatrixLeg``). Each
+non-skipped leg is executed by delegating to the existing SDK ``run``
+command surface via ``fi.simulate.manifest.run_manifest``. Skipped legs
+emit ``TestCaseStatus.UNSUPPORTED`` rows explicitly.
+
+The CLI is intentionally thin: it exists so pipelines and acceptance
+runs can execute the matrix without also depending on the wider
+``agent-learn simulate`` argparse tree. Programmatic callers should use
+``fi.simulate.simulation.matrix.run_matrix`` directly.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from fi.simulate.manifest import ManifestError, ManifestRunOptions, run_manifest
+from fi.simulate.simulation.matrix import (
+    MatrixLeg,
+    MatrixLegResult,
+    run_matrix,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _resolve_base(manifest_dir: Path, matrix: dict[str, Any]) -> tuple[dict[str, Any], Path]:
+    base = matrix.get("base")
+    if isinstance(base, str):
+        base_path = (manifest_dir / base).resolve()
+        return _load_json(base_path), base_path
+    if isinstance(base, dict):
+        return dict(base), manifest_dir / "matrix-inline.json"
+    raise ManifestError("matrix manifest requires 'base' as path or object")
+
+
+async def _default_run_leg(
+    *,
+    manifest: dict[str, Any],
+    manifest_path: Path,
+    leg: MatrixLeg,
+    max_concurrent_calls: int,
+) -> Any:
+    del max_concurrent_calls  # concurrency is engine-side today
+    return await run_manifest(
+        manifest=manifest,
+        manifest_path=manifest_path,
+        options=ManifestRunOptions(name=f"matrix:{leg.label}", no_eval=False),
+    )
+
+
+def _report_status(report: Any) -> str | None:
+    if not isinstance(report, dict):
+        return None
+    status = report.get("status")
+    return str(status) if status is not None else None
+
+
+def _leg_succeeded(result: MatrixLegResult) -> bool:
+    return result.skipped or (
+        result.error is None and _report_status(result.report) == "passed"
+    )
+
+
+def _summary(results: list[MatrixLegResult]) -> dict[str, Any]:
+    return {
+        "schema_version": "agent-learning.matrix.v1",
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "legs": [
+            {
+                "leg": item.leg.label,
+                "provider": item.leg.provider,
+                "channel": item.leg.channel,
+                "status": (
+                    "unsupported"
+                    if item.skipped
+                    else "error"
+                    if item.error is not None
+                    else _report_status(item.report)
+                    or "unknown"
+                ),
+                "started_at": item.started_at.isoformat(),
+                "ended_at": item.ended_at.isoformat() if item.ended_at else None,
+                "skipped": item.skipped,
+                "skip_reason": item.leg.skip_reason,
+                "error": item.error,
+                "skipped_cases": item.skipped_cases,
+                "manifest_name": item.manifest.get("name"),
+                "summary": (
+                    item.report.get("summary")
+                    if isinstance(item.report, dict)
+                    else None
+                ),
+            }
+            for item in results
+        ],
+    }
+
+
+def _write(path: Path, payload: dict[str, Any]) -> None:
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _parse_legs(raw: Any) -> list[MatrixLeg]:
+    if not isinstance(raw, list):
+        raise ManifestError("matrix manifest 'legs' must be a list")
+    try:
+        return [MatrixLeg.model_validate(item) for item in raw]
+    except ValidationError as exc:
+        raise ManifestError(f"invalid matrix leg: {exc}") from exc
+
+
+async def _run(args: argparse.Namespace) -> int:
+    manifest_path = Path(args.manifest).expanduser().resolve()
+    matrix = _load_json(manifest_path)
+    base, base_path = _resolve_base(manifest_path.parent, matrix)
+    legs = _parse_legs(matrix.get("legs"))
+    results = await run_matrix(
+        base,
+        legs,
+        manifest_path=base_path,
+        max_concurrent_calls=int(matrix.get("max_concurrent_calls", 1)),
+        run_leg=_default_run_leg,
+    )
+    payload = _summary(results)
+    if args.output:
+        _write(Path(args.output).expanduser().resolve(), payload)
+    if not args.quiet:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    return 0 if all(_leg_succeeded(result) for result in results) else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m fi.simulate.matrix_cli",
+        description="Run a provider × channel matrix against an SDK base manifest.",
+    )
+    parser.add_argument("manifest")
+    parser.add_argument("-o", "--output", default=None)
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        return asyncio.run(_run(args))
+    except ManifestError as exc:
+        print(f"matrix: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

fi/simulate/realtime/__init__.py

@@ -0,0 +1,40 @@
+"""Provider-neutral realtime session primitives (plan §5).
+
+These are contracts, not yet a full router. ``LiveKitEngine`` keeps
+owning the actual media path today; the classes here give Stage 6/7
+callers a stable seam for adding a real router, evidence tap, and
+alternate provider backends without rewriting engine internals.
+"""
+
+from __future__ import annotations
+
+from .events import (
+    CANONICAL_EVENT_TYPES,
+    CANONICAL_MEDIA_EVENTS,
+    CANONICAL_TOOL_EVENTS,
+    RealtimeEvent,
+)
+from .media import DEFAULT_AUDIO_PROFILE, AudioFrame, AudioProfile, MediaDirection
+from .session import (
+    BridgeResult,
+    CloseReason,
+    EndpointSession,
+    RealtimeBridgeSession,
+    RealtimeEndpoint,
+)
+
+__all__ = [
+    "AudioFrame",
+    "AudioProfile",
+    "BridgeResult",
+    "CANONICAL_EVENT_TYPES",
+    "CANONICAL_MEDIA_EVENTS",
+    "CANONICAL_TOOL_EVENTS",
+    "CloseReason",
+    "DEFAULT_AUDIO_PROFILE",
+    "EndpointSession",
+    "MediaDirection",
+    "RealtimeBridgeSession",
+    "RealtimeEndpoint",
+    "RealtimeEvent",
+]

fi/simulate/realtime/events.py

@@ -0,0 +1,107 @@
+"""Canonical realtime event vocabulary (plan §5.2).
+
+Event *names* freeze here so any future router, provider adapter, or
+evidence source can emit ``CanonicalEvent(type=...)`` with a name the
+platform recognizes. The vocabulary is deliberately open: additional
+provider-specific types stay under the ``provider.raw`` umbrella and
+must carry a ``provider_raw_ref`` before they can be persisted.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field, JsonValue
+
+
+CANONICAL_LIFECYCLE_EVENTS: tuple[str, ...] = (
+    "session.started",
+    "session.ready",
+    "session.ended",
+    "session.error",
+    "endpoint.connected",
+    "endpoint.ready",
+    "endpoint.disconnected",
+    "participant.joined",
+    "participant.left",
+    "track.published",
+    "track.unpublished",
+)
+
+CANONICAL_MEDIA_EVENTS: tuple[str, ...] = (
+    "audio.frame",
+    "speech.started",
+    "speech.stopped",
+    "playback.started",
+    "playback.ended",
+    "playback.clear",
+    "interruption",
+    "transcript.partial",
+    "transcript.final",
+)
+
+CANONICAL_TOOL_EVENTS: tuple[str, ...] = (
+    "tool.started",
+    "tool.completed",
+    "tool.failed",
+)
+
+CANONICAL_TELEPHONY_EVENTS: tuple[str, ...] = (
+    "dtmf.sent",
+    "dtmf.received",
+    "transfer.started",
+    "transfer.completed",
+)
+
+CANONICAL_TELEMETRY_EVENTS: tuple[str, ...] = (
+    "usage.updated",
+    "metric.observed",
+    "provider.raw",
+)
+
+CANONICAL_EVENT_TYPES: tuple[str, ...] = (
+    *CANONICAL_LIFECYCLE_EVENTS,
+    *CANONICAL_MEDIA_EVENTS,
+    *CANONICAL_TOOL_EVENTS,
+    *CANONICAL_TELEPHONY_EVENTS,
+    *CANONICAL_TELEMETRY_EVENTS,
+)
+
+
+class RealtimeEvent(BaseModel):
+    """Envelope emitted by a ``RealtimeEndpoint``.
+
+    Adapters wrap provider payloads into this shape rather than exposing
+    provider SDK objects across the SDK boundary.
+    """
+
+    event_id: str
+    session_id: str
+    leg_id: str | None = None
+    type: str
+    source: str
+    wall_time: datetime
+    monotonic_ns: int
+    sequence: int = Field(ge=0)
+    payload: dict[str, JsonValue] = Field(default_factory=dict)
+    provider: str | None = None
+    provider_raw_ref: str | None = None
+    correlation_id: str | None = None
+    trace_id: str | None = None
+
+    def with_payload(self, **overrides: Any) -> "RealtimeEvent":
+        merged = dict(self.payload)
+        merged.update(overrides)
+        return self.model_copy(update={"payload": merged})
+
+
+__all__ = [
+    "CANONICAL_EVENT_TYPES",
+    "CANONICAL_LIFECYCLE_EVENTS",
+    "CANONICAL_MEDIA_EVENTS",
+    "CANONICAL_TELEMETRY_EVENTS",
+    "CANONICAL_TELEPHONY_EVENTS",
+    "CANONICAL_TOOL_EVENTS",
+    "RealtimeEvent",
+]

fi/simulate/realtime/media.py

@@ -0,0 +1,61 @@
+"""Canonical audio media frame (plan §5.1).
+
+One media router will eventually own resampling and pacing; provider
+adapters must not reintroduce ad-hoc resampling. This module gives that
+future router — and any evidence source that wants to inspect frames —
+a single frame type to depend on.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class MediaDirection(str, Enum):
+    INBOUND = "inbound"
+    OUTBOUND = "outbound"
+
+
+class AudioProfile(BaseModel):
+    encoding: str = "pcm_s16le"
+    channels: int = Field(1, gt=0)
+    sample_rate: int = Field(16_000, gt=0)
+    frame_duration_ms: int = Field(20, gt=0)
+
+    @property
+    def samples_per_frame(self) -> int:
+        return self.sample_rate * self.frame_duration_ms // 1000
+
+
+DEFAULT_AUDIO_PROFILE = AudioProfile()
+
+
+class AudioFrame(BaseModel):
+    """Immutable audio frame carried by ``RealtimeEndpoint``.
+
+    Provider adapters preserve ``provider_stream_id``, ``ssrc``, and
+    original ``media_timestamp`` values instead of overwriting them so
+    downstream evidence can correlate to provider-side artifacts.
+    """
+
+    event_id: str
+    session_id: str
+    leg_id: str
+    sequence: int = Field(ge=0)
+    timestamp_ns: int
+    media_timestamp: int | None = None
+    direction: MediaDirection
+    encoding: str = "pcm_s16le"
+    sample_rate: int = Field(gt=0)
+    channels: int = Field(default=1, gt=0)
+    samples_per_channel: int = Field(gt=0)
+    payload_size_bytes: int = Field(ge=0)
+    provider_stream_id: str | None = None
+    provider_sequence: int | None = None
+    ssrc: int | None = None
+    discontinuity: bool = False
+
+
+__all__ = ["AudioFrame", "AudioProfile", "DEFAULT_AUDIO_PROFILE", "MediaDirection"]

fi/simulate/realtime/session.py

@@ -0,0 +1,91 @@
+"""RealtimeEndpoint + RealtimeBridgeSession contracts (plan §5).
+
+Only Protocol/data shapes here — the media router, backpressure, and
+provider-pair bridge live in follow-up work. Adding these gives the
+existing ``LiveKitEngine`` a stable seam it can be adapted onto and
+gives future adapters (Pipecat, alternative LiveKit backends, direct
+SIP shims) a target contract.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from enum import Enum
+from typing import Protocol
+
+from pydantic import BaseModel, Field, JsonValue
+
+from .events import RealtimeEvent
+from .media import AudioFrame
+from fi.simulate.runtime.capabilities import EndpointCapabilities
+
+
+class CloseReason(str, Enum):
+    NORMAL = "normal"
+    INTERRUPTED = "interrupted"
+    CANCELED = "canceled"
+    ERROR = "error"
+    TIMEOUT = "timeout"
+
+
+class EndpointSession(BaseModel):
+    session_id: str
+    leg_id: str
+    capabilities: EndpointCapabilities
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class BridgeResult(BaseModel):
+    session_id: str
+    close_reason: CloseReason
+    left_events: int = 0
+    right_events: int = 0
+    audio_frames: int = 0
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class RealtimeEndpoint(Protocol):
+    """One side of a realtime bridge (customer agent OR simulator)."""
+
+    capabilities: EndpointCapabilities
+
+    async def connect(self) -> EndpointSession: ...
+
+    async def receive(self) -> AsyncIterator[RealtimeEvent | AudioFrame]:  # noqa: D401
+        """Yield events + audio frames until the endpoint closes."""
+        ...
+
+    async def send(self, event: RealtimeEvent | AudioFrame) -> None: ...
+
+    async def close(self, reason: CloseReason) -> None: ...
+
+
+@dataclass
+class RealtimeBridgeSession:
+    """Neutral bridge between two ``RealtimeEndpoint`` implementations.
+
+    The real router (pacing, backpressure, playback-clear on
+    interruption, evidence taps) lands under §5.3. This dataclass gives
+    that router a stable public constructor today so the rest of the
+    SDK can start referencing bridge shape without waiting for that
+    implementation.
+    """
+
+    left: RealtimeEndpoint
+    right: RealtimeEndpoint
+    session_id: str
+
+    async def run(self) -> BridgeResult:
+        raise NotImplementedError(
+            "RealtimeBridgeSession.run is a seam; implement per plan §5.3."
+        )
+
+
+__all__ = [
+    "BridgeResult",
+    "CloseReason",
+    "EndpointSession",
+    "RealtimeBridgeSession",
+    "RealtimeEndpoint",
+]

fi/simulate/recording/__init__.py

@@ -0,0 +1,5 @@
+from .room_recorder import RoomRecorder
+
+__all__ = ["RoomRecorder"]
+
+