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

fi/simulate/endpoints/livekit.py

@@ -0,0 +1,138 @@
+"""LiveKit target-agent adapter.
+
+Thin adapter around the existing ``LiveKitEngine`` that lets hosted +
+matrix runners see a LiveKit target through the ``AgentEndpoint``
+contract. The actual media/lifecycle work still lives inside the
+engine's per-case runner; this class exposes a stable seam so a full
+``endpoints/livekit.py`` rewrite can land later without breaking
+callers.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator
+from datetime import datetime, timezone
+
+from fi.simulate.agent.definition import AgentDefinition, TelephonyTransport
+from fi.simulate.realtime.events import RealtimeEvent
+from fi.simulate.realtime.media import AudioFrame
+from fi.simulate.runtime.capabilities import EndpointCapabilities
+
+from .base import (
+    AgentEndpointManifest,
+    DiscoveryRequest,
+    DiscoverySnapshot,
+    EndpointHandle,
+    ReadinessResult,
+    ReconciliationResult,
+)
+
+
+def _capabilities_for(agent_definition: AgentDefinition) -> EndpointCapabilities:
+    transport = agent_definition.transport or TelephonyTransport()
+    kind = transport.kind
+    return EndpointCapabilities(
+        audio=True,
+        text=True,
+        streaming=True,
+        interruption=True,
+        dtmf=kind in {"sip_inbound", "sip_outbound"},
+        transfer=kind in {"sip_inbound", "sip_outbound"},
+        transcript_events=True,
+        tool_events=False,
+        usage_events=True,
+        internal_metrics=True,
+        recording=True,
+        web_rtc=kind == "webrtc",
+        sip=kind in {"sip_inbound", "sip_outbound"},
+    )
+
+
+class LiveKitAgentEndpoint:
+    """Spec-level LiveKit endpoint. Engine still owns the media path."""
+
+    def __init__(self, agent_definition: AgentDefinition, *, name: str | None = None) -> None:
+        self._agent_definition = agent_definition
+        self.manifest = AgentEndpointManifest(
+            name=name or agent_definition.name,
+            provider="livekit",
+            world_kinds=["voice"],
+            capabilities=_capabilities_for(agent_definition),
+            metadata={
+                "url": str(agent_definition.url),
+                "room_name_template": agent_definition.room_name,
+                "room_mode": agent_definition.room_mode,
+                "transport": (
+                    agent_definition.transport.kind
+                    if agent_definition.transport
+                    else "webrtc"
+                ),
+            },
+        )
+        self.capabilities = self.manifest.capabilities
+
+    @property
+    def agent_definition(self) -> AgentDefinition:
+        return self._agent_definition
+
+    async def discover(self, request: DiscoveryRequest) -> DiscoverySnapshot:
+        supported = self.capabilities.supported()
+        missing = [
+            cap for cap in request.required_capabilities if cap not in supported
+        ]
+        return DiscoverySnapshot(
+            capabilities=self.capabilities,
+            supported=not missing,
+            reasons=[f"unsupported:{cap}" for cap in missing],
+        )
+
+    async def prepare(self, plan) -> EndpointHandle:  # noqa: ANN001
+        return EndpointHandle(
+            handle_id=f"lk-{uuid.uuid4().hex[:12]}",
+            endpoint_name=self.manifest.name,
+            created_at=datetime.now(timezone.utc),
+            metadata={
+                "plan_id": getattr(plan, "plan_id", None),
+                "transport": (
+                    self._agent_definition.transport.kind
+                    if self._agent_definition.transport
+                    else "webrtc"
+                ),
+            },
+        )
+
+    async def wait_ready(self, handle: EndpointHandle) -> ReadinessResult:
+        del handle
+        # Real readiness is driven inside LiveKitEngine per case today.
+        # This adapter reports ready=True optimistically; hosted callers
+        # observe actual readiness through emitted CanonicalEvents.
+        return ReadinessResult(ready=True)
+
+    async def send(
+        self, handle: EndpointHandle, event: RealtimeEvent | AudioFrame
+    ) -> None:
+        raise NotImplementedError(
+            "LiveKitAgentEndpoint.send belongs to the future realtime router"
+        )
+
+    async def receive(
+        self, handle: EndpointHandle
+    ) -> AsyncIterator[RealtimeEvent | AudioFrame]:
+        raise NotImplementedError(
+            "LiveKitAgentEndpoint.receive belongs to the future realtime router"
+        )
+        yield  # type: ignore[unreachable]
+
+    async def stop(self, handle: EndpointHandle) -> None:
+        del handle
+
+    async def cleanup(self, handle: EndpointHandle) -> None:
+        del handle
+
+    async def reconcile(self, handle: EndpointHandle) -> ReconciliationResult:
+        del handle
+        return ReconciliationResult(reconciled=True)
+
+
+__all__ = ["LiveKitAgentEndpoint"]

fi/simulate/endpoints/originators.py

@@ -0,0 +1,132 @@
+"""Provider-neutral call-origination surface — factory + cleanup helper.
+
+Lives outside ``simulation/engines/livekit.py`` on purpose: that module
+raises ``ImportError`` without the optional ``livekit`` extra (which this
+SDK's dev venv lacks), so nothing inside it can be exercised by tests here;
+this module has no such dependency, so it is fully testable (C3/C6).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Protocol
+
+from .retell import RetellCallOriginator
+from .vapi import VapiCallOriginator
+
+
+class CallOriginator(Protocol):
+    """The lifecycle every provider originator satisfies (C2/C3)."""
+
+    async def start(self) -> Any: ...
+
+    async def stop(self, call_id: str) -> None: ...
+
+    async def reconcile_and_stop(
+        self, *, started_after_ms: int, ended_before_ms: int
+    ) -> list[str]: ...
+
+    async def close(self) -> None: ...
+
+
+def build_call_originator(transport: Any) -> CallOriginator:
+    """Construct the originator named by ``transport.inbound_call_originator``.
+
+    This is the one place a provider name is compared to select a class;
+    construction, start, stop and cleanup afterward stay provider-neutral.
+    """
+    name = transport.inbound_call_originator
+    if name == "vapi":
+        return VapiCallOriginator.from_env()
+    if name == "retell":
+        return RetellCallOriginator.from_env(transport)
+    raise ValueError(f"unsupported_inbound_call_originator: {name}")
+
+
+@dataclass(frozen=True)
+class OriginatorFinalizeResult:
+    """What cleanup did, so the engine can adapt it without deciding anything."""
+
+    termination_source: str | None
+    reconciled_call_ids: list[str]
+    cleanup_errors: list[tuple[str, Exception]]
+
+
+async def finalize_originator(
+    originator: CallOriginator,
+    *,
+    provider_call_id: str | None,
+    originator_name: str,
+    case_started_at: datetime,
+    cleanup_timeout: float,
+    now: Callable[[], datetime] = lambda: datetime.now(timezone.utc),
+) -> OriginatorFinalizeResult:
+    """Best-effort originator cleanup: never raises (C3).
+
+    ``stop()`` ends the call we know about; with no call id in hand (a
+    cancelled ``asyncio.wait_for`` can still leave a live, billed call on
+    the provider's side) ``reconcile_and_stop`` hunts for the orphan instead.
+    ``close()`` always runs, even when the above raised.
+    """
+    termination_source: str | None = None
+    reconciled_call_ids: list[str] = []
+    cleanup_errors: list[tuple[str, Exception]] = []
+    try:
+        if provider_call_id is not None:
+            try:
+                await asyncio.wait_for(
+                    originator.stop(provider_call_id), timeout=cleanup_timeout
+                )
+                termination_source = "sdk_originator_cleanup"
+            except Exception as exc:  # noqa: BLE001 - best-effort cleanup, never raises
+                cleanup_errors.append((f"{originator_name}_call_stop", exc))
+        else:
+            # A naive datetime is read as local time by .timestamp(), silently
+            # widening the blast-radius window; treat it as UTC instead.
+            started = (
+                case_started_at
+                if case_started_at.tzinfo is not None
+                else case_started_at.replace(tzinfo=timezone.utc)
+            )
+            started_after_ms = int(started.timestamp() * 1000)
+            ended_before_ms = int(now().timestamp() * 1000)
+            try:
+                reconciled_call_ids = await asyncio.wait_for(
+                    originator.reconcile_and_stop(
+                        started_after_ms=started_after_ms,
+                        ended_before_ms=ended_before_ms,
+                    ),
+                    timeout=cleanup_timeout,
+                )
+                if reconciled_call_ids:
+                    termination_source = "sdk_originator_cleanup"
+            except TypeError as exc:
+                # A wrong call site (non-int epoch ms) fails loudly and
+                # distinguishably from a swallowed HTTP failure.
+                cleanup_errors.append(
+                    (f"{originator_name}_call_reconcile_bad_arguments", exc)
+                )
+            except Exception as exc:  # noqa: BLE001 - best-effort cleanup, never raises
+                cleanup_errors.append((f"{originator_name}_call_reconcile", exc))
+    finally:
+        try:
+            # Bounded like every other cleanup step, so a slow client can't
+            # stall this case past its cleanup budget.
+            await asyncio.wait_for(originator.close(), cleanup_timeout)
+        except Exception as exc:  # noqa: BLE001 - best-effort cleanup, never raises
+            cleanup_errors.append((f"{originator_name}_call_close", exc))
+    return OriginatorFinalizeResult(
+        termination_source=termination_source,
+        reconciled_call_ids=reconciled_call_ids,
+        cleanup_errors=cleanup_errors,
+    )
+
+
+__all__ = [
+    "CallOriginator",
+    "OriginatorFinalizeResult",
+    "build_call_originator",
+    "finalize_originator",
+]

fi/simulate/endpoints/profiles.py

@@ -0,0 +1,348 @@
+"""Target-endpoint profiles (canonical plan §4.1) — the factory that retires the
+hardcoded ``transport.kind`` branches.
+
+A profile is the single declarative record for one target adapter: its capability
+manifest plus the *decisions* the voice engine used to make with ``if
+transport.kind == ...`` chains — whether the leg is SIP, whether it places an
+outbound call, whether it needs a web audio bridge, which provider evidence to
+collect, and which connector to build. The engine keeps its session/audio
+*mechanics*; it just asks the profile instead of branching on strings.
+
+Adding a provider = registering one profile here (or via the
+``fi.simulate.endpoints`` entry-point group) with **zero engine edits**.
+
+Import weight: connector / ``livekit.rtc`` imports are deferred into
+``build_connector`` so the planner can read ``profile.manifest.capabilities``
+without pulling the optional voice stack.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from fi.simulate.endpoints.actor_sources import (
+    resolve_factory,
+    resolve_framework,
+    resolve_http,
+    resolve_import_object,
+    resolve_python_callable,
+    resolve_system_prompt,
+)
+from fi.simulate.endpoints.base import AgentEndpointManifest
+from fi.simulate.registry import register_endpoint
+from fi.simulate.runtime.capabilities import EndpointCapabilities
+
+
+class EndpointProfile:
+    """One target adapter's manifest + provider decisions."""
+
+    def __init__(
+        self,
+        manifest: AgentEndpointManifest,
+        *,
+        is_sip: bool = False,
+        places_outbound_call: bool = False,
+        receives_inbound_call: bool = False,
+        uses_web_audio_bridge: bool = False,
+        bridge_provider: Optional[str] = None,
+        evidence_provider: Optional[str] = None,
+        required_env_rule: Optional[Callable[[Any], list[str]]] = None,
+        connector_builder: Optional[Callable[..., Any]] = None,
+        target_resolver: Optional[Callable[..., Any]] = None,
+        runs_caller_code: bool = True,
+    ) -> None:
+        self.manifest = manifest
+        self.is_sip = is_sip
+        self.places_outbound_call = places_outbound_call
+        self.receives_inbound_call = receives_inbound_call
+        self.uses_web_audio_bridge = uses_web_audio_bridge
+        self.bridge_provider = bridge_provider
+        self.evidence_provider = evidence_provider
+        self._required_env_rule = required_env_rule
+        self._connector_builder = connector_builder
+        self._target_resolver = target_resolver
+        # Deny-by-default: a turn-based target executes caller-supplied Python
+        # unless it explicitly declares otherwise (http/system_prompt/deployed
+        # endpoints). An undeclared third-party kind is treated as unsafe. The
+        # hosted gate (resolve_chat_target) reads this, not a module denylist.
+        self.runs_caller_code = runs_caller_code
+
+    @property
+    def is_turn_based_target(self) -> bool:
+        """This adapter resolves to a turn-based agent (chat) rather than a
+        realtime/voice endpoint."""
+        return self._target_resolver is not None
+
+    def resolve_target(
+        self, config: Any = None, secret_refs: Any = None, *, hosted: bool = False
+    ) -> Any:
+        """Resolve this actor-source to a runnable turn-based agent (plan §4.1).
+
+        Raises for realtime/voice adapters, which are reached through
+        ``build_connector`` + the engine instead. ``hosted`` restricts env reads
+        to job-provisioned secrets (see resolvers)."""
+        if self._target_resolver is None:
+            raise ValueError(
+                f"target_adapter_not_turn_based: {self.manifest.name!r}"
+            )
+        return self._target_resolver(config or {}, secret_refs, hosted=hosted)
+
+    @property
+    def joins_as_sip_participant(self) -> bool:
+        """The target joins the room as a SIP participant — true for real SIP
+        legs and for the web providers reached through the LiveKit audio bridge."""
+        return self.is_sip or self.uses_web_audio_bridge
+
+    @property
+    def uses_external_room(self) -> bool:
+        """Only plain WebRTC targets run in an external (non-managed) room."""
+        return not self.joins_as_sip_participant
+
+    @property
+    def name(self) -> str:
+        return self.manifest.name
+
+    def required_env(self, agent_definition: Any) -> list[str]:
+        """Transport-specific env var *names* this adapter needs (the branch that
+        used to live in ``voice._voice_required_env``). Base adapters need none."""
+        if self._required_env_rule is None:
+            return []
+        return list(self._required_env_rule(agent_definition))
+
+    def build_connector(
+        self, provider_target: Any, *, conversation_direction: str
+    ) -> Any:
+        """Provider connector for web-bridged targets; ``None`` for webrtc/sip."""
+        if self._connector_builder is None:
+            return None
+        return self._connector_builder(
+            provider_target, conversation_direction=conversation_direction
+        )
+
+
+# --------------------------------------------------------------------------- #
+# required-env rules (parity with the old voice._voice_required_env branches)
+# --------------------------------------------------------------------------- #
+def _vapi_web_required_env(agent_definition: Any) -> list[str]:
+    if agent_definition.target is None:
+        return ["VAPI_API_KEY", "VAPI_ASSISTANT_ID"]
+    return []
+
+
+def _retell_web_required_env(agent_definition: Any) -> list[str]:
+    if agent_definition.target is None:
+        return ["RETELL_API_KEY", "RETELL_AGENT_ID"]
+    return []
+
+
+def _sip_inbound_required_env(agent_definition: Any) -> list[str]:
+    transport = agent_definition.transport
+    target = agent_definition.target
+    names: list[str] = []
+    if transport is not None and not transport.dispatch_rule_name:
+        names.append("LIVEKIT_INBOUND_TRUNK_ID")
+    if transport is not None and transport.inbound_call_originator == "vapi":
+        # Same conditional-append idiom as the Retell branch below; behaviour
+        # identical (the consumer already dropped blanks from the old tuple).
+        names.append(
+            target.api_key_env
+            if target is not None and target.provider == "vapi"
+            else "VAPI_API_KEY"
+        )
+        if target is None or target.provider != "vapi":
+            names.append("VAPI_ASSISTANT_ID")
+        names.append("VAPI_PHONE_NUMBER_ID")
+        names.append("LIVEKIT_INBOUND_DID")
+    if transport is not None and transport.inbound_call_originator == "retell":
+        # Parity-only rule (CLI/manifest path); the job carries these fields directly.
+        names.append("RETELL_API_KEY")
+        if not transport.originator_agent_id:
+            names.append("RETELL_AGENT_ID")
+        if not transport.originator_from_number:
+            names.append("RETELL_FROM_NUMBER")
+        names.append("LIVEKIT_INBOUND_DID")
+    return names
+
+
+# --------------------------------------------------------------------------- #
+# connector builders (lazy imports keep the voice stack off the planner path)
+# --------------------------------------------------------------------------- #
+def _build_vapi_connector(provider_target: Any, *, conversation_direction: str) -> Any:
+    from fi.simulate.agent.definition import VapiTargetConfig
+    from fi.simulate.simulation.bridge import VapiWebSocketConnector
+
+    if isinstance(provider_target, VapiTargetConfig):
+        return VapiWebSocketConnector.from_target(
+            provider_target,
+            first_message_mode=(
+                "assistant-waits-for-user"
+                if conversation_direction == "simulator_first"
+                else "assistant-speaks-first"
+            ),
+        )
+    return VapiWebSocketConnector.from_env()
+
+
+def _build_retell_connector(
+    provider_target: Any, *, conversation_direction: str
+) -> Any:
+    from fi.simulate.agent.definition import RetellTargetConfig
+    from fi.simulate.simulation.bridge import RetellWebCallConnector
+
+    if isinstance(provider_target, RetellTargetConfig):
+        return RetellWebCallConnector.from_target(provider_target)
+    return RetellWebCallConnector.from_env()
+
+
+# --------------------------------------------------------------------------- #
+# built-in profiles
+# --------------------------------------------------------------------------- #
+_CHAT_CAPS = EndpointCapabilities(text=True, transcript_events=True, tool_events=True)
+_WEBRTC_CAPS = EndpointCapabilities(
+    audio=True,
+    streaming=True,
+    interruption=True,
+    recording=True,
+    transcript_events=True,
+    web_rtc=True,
+)
+_SIP_CAPS = EndpointCapabilities(
+    audio=True,
+    streaming=True,
+    interruption=True,
+    recording=True,
+    transcript_events=True,
+    sip=True,
+)
+
+_PROFILES: list[EndpointProfile] = [
+    # chat-era + actor-source target adapters ("drop in any agent", plan §4.1).
+    # config keys mirror the manifest agent: block (target/factory/args/kwargs/
+    # method/input_mode/system_prompt/...).
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="callable", provider="callable",
+            world_kinds=["chat", "text"], capabilities=_CHAT_CAPS,
+        ),
+        target_resolver=resolve_python_callable,
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="python_callable", provider="callable",
+            world_kinds=["chat", "text"], capabilities=_CHAT_CAPS,
+        ),
+        target_resolver=resolve_python_callable,
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="import_object", provider="python",
+            world_kinds=["chat", "text"], capabilities=_CHAT_CAPS,
+        ),
+        target_resolver=resolve_import_object,
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="factory", provider="python",
+            world_kinds=["chat", "text"], capabilities=_CHAT_CAPS,
+        ),
+        target_resolver=resolve_factory,
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="framework", provider="framework",
+            world_kinds=["chat", "text"], capabilities=_CHAT_CAPS,
+        ),
+        target_resolver=resolve_framework,
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="system_prompt", provider="llm",
+            world_kinds=["chat", "text"], capabilities=_CHAT_CAPS,
+        ),
+        target_resolver=resolve_system_prompt,
+        runs_caller_code=False,
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="http", provider="http",
+            world_kinds=["chat", "text"], capabilities=_CHAT_CAPS,
+        ),
+        target_resolver=resolve_http,
+        runs_caller_code=False,
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="websocket", provider="websocket",
+            world_kinds=["chat", "text"],
+            capabilities=EndpointCapabilities(
+                text=True, streaming=True, transcript_events=True, tool_events=True
+            ),
+        )
+    ),
+    # voice target adapters (keyed by transport.kind)
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="webrtc", provider="livekit",
+            world_kinds=["voice"], capabilities=_WEBRTC_CAPS,
+        )
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="livekit", provider="livekit",
+            world_kinds=["voice"], capabilities=_WEBRTC_CAPS,
+        )
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="vapi_websocket", provider="vapi",
+            world_kinds=["voice"], capabilities=_WEBRTC_CAPS,
+        ),
+        uses_web_audio_bridge=True,
+        bridge_provider="vapi",
+        evidence_provider="vapi",
+        required_env_rule=_vapi_web_required_env,
+        connector_builder=_build_vapi_connector,
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="retell_webcall", provider="retell",
+            world_kinds=["voice"], capabilities=_WEBRTC_CAPS,
+        ),
+        uses_web_audio_bridge=True,
+        bridge_provider="retell",
+        evidence_provider="retell",
+        required_env_rule=_retell_web_required_env,
+        connector_builder=_build_retell_connector,
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="sip_outbound", provider="sip",
+            world_kinds=["voice"], capabilities=_SIP_CAPS,
+        ),
+        is_sip=True,
+        places_outbound_call=True,
+    ),
+    EndpointProfile(
+        AgentEndpointManifest(
+            name="sip_inbound", provider="sip",
+            world_kinds=["voice"], capabilities=_SIP_CAPS,
+        ),
+        is_sip=True,
+        receives_inbound_call=True,
+        required_env_rule=_sip_inbound_required_env,
+    ),
+]
+
+for _profile in _PROFILES:
+    register_endpoint(_profile.name, _profile)
+
+
+def get_profile(name: str) -> Optional[EndpointProfile]:
+    """Return the registered profile for a target adapter name, or ``None``."""
+    from fi.simulate.registry import endpoint_registry
+
+    value = endpoint_registry.get_or_none(name)
+    return value if isinstance(value, EndpointProfile) else None
+
+
+__all__ = ["EndpointProfile", "get_profile"]