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

fi/simulate/endpoints/__init__.py

@@ -0,0 +1,45 @@
+"""Agent endpoint adapter tree (plan §4.1 + §13).
+
+Each adapter conforms to ``AgentEndpoint``. Existing runtime paths keep
+running through ``LiveKitEngine`` — the adapters here give hosted-runner
+and matrix-runner callers a stable spec-level surface without waiting
+for a full engine rewrite.
+"""
+
+from __future__ import annotations
+
+from .base import (
+    AgentEndpoint,
+    AgentEndpointManifest,
+    DiscoveryRequest,
+    DiscoverySnapshot,
+    EndpointHandle,
+    ReadinessResult,
+    ReconciliationResult,
+)
+from .callable import CallableAgentEndpoint
+from .http import HttpAgentEndpoint
+from .livekit import LiveKitAgentEndpoint
+from .retell import RetellAgentEndpoint, RetellCall, RetellCallOriginator
+from .vapi import VapiAgentEndpoint, VapiCall, VapiCallOriginator
+from .websocket import WebSocketAgentEndpoint
+
+__all__ = [
+    "AgentEndpoint",
+    "AgentEndpointManifest",
+    "CallableAgentEndpoint",
+    "DiscoveryRequest",
+    "DiscoverySnapshot",
+    "EndpointHandle",
+    "HttpAgentEndpoint",
+    "LiveKitAgentEndpoint",
+    "ReadinessResult",
+    "ReconciliationResult",
+    "RetellAgentEndpoint",
+    "RetellCall",
+    "RetellCallOriginator",
+    "VapiAgentEndpoint",
+    "VapiCall",
+    "VapiCallOriginator",
+    "WebSocketAgentEndpoint",
+]

fi/simulate/endpoints/_http_actor.py

@@ -0,0 +1,73 @@
+"""Turn-based HTTP target agent (used by the ``http`` actor source).
+
+Lifted out of ``hosted/targets.py`` so ``endpoints`` can own it without a cycle
+(``targets`` now dispatches through the endpoint registry).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+import httpx
+
+from fi.simulate.agent.wrapper import AgentInput, AgentWrapper
+
+_HTTP_TIMEOUT_SECONDS = 60.0
+
+
+class HttpChatAgent(AgentWrapper):
+    """Turn-based target that relays each turn to an HTTP chat endpoint."""
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        auth_header: str = "Authorization",
+        auth_env: Optional[str] = None,
+        extra_headers: Optional[dict[str, str]] = None,
+    ) -> None:
+        self._url = url
+        self._auth_header = auth_header
+        self._auth_env = auth_env
+        self._extra_headers = extra_headers or {}
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Content-Type": "application/json", **self._extra_headers}
+        if self._auth_env:
+            token = os.environ.get(self._auth_env)
+            if token:
+                headers[self._auth_header] = token
+        return headers
+
+    async def call(self, input: AgentInput) -> str:
+        payload = {
+            "thread_id": input.thread_id,
+            "messages": input.messages,
+            "new_message": input.new_message,
+        }
+        async with httpx.AsyncClient(timeout=_HTTP_TIMEOUT_SECONDS) as client:
+            response = await client.post(
+                self._url, json=payload, headers=self._headers()
+            )
+            response.raise_for_status()
+            return _extract_reply(response.json())
+
+
+def _extract_reply(body: Any) -> str:
+    if isinstance(body, str):
+        return body
+    if isinstance(body, dict):
+        for key in ("content", "reply", "message", "response", "output", "text"):
+            value = body.get(key)
+            if isinstance(value, str) and value:
+                return value
+        choices = body.get("choices")
+        if isinstance(choices, list) and choices:
+            message = choices[0].get("message") if isinstance(choices[0], dict) else None
+            if isinstance(message, dict) and isinstance(message.get("content"), str):
+                return message["content"]
+    return ""
+
+
+__all__ = ["HttpChatAgent"]

fi/simulate/endpoints/actor_sources.py

@@ -0,0 +1,243 @@
+"""Actor-source resolvers (canonical plan §4.1) — the "drop in any agent" surface.
+
+A turn-based target agent can be declared as any of several *kinds*, resolved to
+a runnable ``AgentWrapper`` / callable the environment drives. The kinds and their
+config keys are the pydantic-schema twin of the manifest ``agent:`` block
+(``target`` / ``factory`` / ``args`` / ``kwargs`` / ``method`` / ``input_mode`` /
+``system_prompt`` / …), so a manifest agent and a spec ActorSource are the same
+declaration in two encodings — no third vocabulary.
+
+Each resolver is attached to an ``EndpointProfile`` in ``profiles.py`` and reached
+through the one ``endpoint_registry``. Heavy imports (``wrap_agent``, LLM clients,
+``httpx``) are deferred into the resolver bodies so the planner/registry stay light.
+
+Security (hosted runs execute *customer-supplied* config on our infra):
+
+* Kinds that import + call caller-named Python (``python_callable`` /
+  ``import_object`` / ``factory`` / ``framework``) are **rejected in hosted runs**
+  — the gate lives in ``resolve_chat_target`` and reads ``EndpointProfile.
+  runs_caller_code`` (deny-by-default), not a denylist. In-process execution of
+  customer code belongs in the sandboxed runtime (``RuntimeIsolation`` above
+  ``shared_runner_process``), not the runner process. A single explicit,
+  scarily-named escape (``ALK_UNSAFE_INPROCESS_CODE_ACTORS``) exists only for a
+  trusted operator-configured default target and tests — never set it in prod.
+* Env reads by ``system_prompt`` / ``http`` are restricted in hosted runs to the
+  keys the job itself provisioned (``secret_refs``), so a job cannot name an
+  arbitrary env var (e.g. another tenant's secret) to exfiltrate.
+* Local (developer) runs resolve with ``hosted=False`` and stay permissive — the
+  developer is running their own code on their own machine.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from typing import Any, Callable, Mapping, Optional
+
+_UNSAFE_INPROCESS_ENV = "ALK_UNSAFE_INPROCESS_CODE_ACTORS"
+
+_WRAP_KEYS = (
+    "method",
+    "input_mode",
+    "input_key",
+    "input_kwargs",
+    "output_key",
+    "system_prompt",
+    "metadata",
+)
+
+
+class ActorSourceError(ValueError):
+    """Raised when an actor-source config cannot be resolved to a runnable agent."""
+
+
+def inprocess_code_allowed() -> bool:
+    """Whether in-process execution of caller code is explicitly permitted (the
+    trusted operator-default target / tests). Deny by default."""
+    return os.environ.get(_UNSAFE_INPROCESS_ENV, "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+    )
+
+
+def _allowed_env_keys(secret_refs: Optional[Mapping[str, Any]]) -> set[str]:
+    keys: set[str] = set()
+    for name, ref in (secret_refs or {}).items():
+        ref_key = getattr(ref, "key", None)
+        keys.add(str(ref_key if ref_key is not None else name))
+    return keys
+
+
+def _require_env_allowed(
+    env_key: str, secret_refs: Optional[Mapping[str, Any]], *, hosted: bool
+) -> None:
+    if not hosted:
+        return
+    if env_key not in _allowed_env_keys(secret_refs):
+        raise ActorSourceError(
+            f"env_not_provisioned: hosted actor may only read job-provisioned "
+            f"secrets; {env_key!r} is not in the job's secret_env"
+        )
+
+
+def _load_attr(ref: Any) -> Any:
+    if not isinstance(ref, str) or ":" not in ref:
+        raise ActorSourceError("actor target requires 'module:attribute'")
+    module_name, _, attr = ref.partition(":")
+    if not module_name or not attr:
+        raise ActorSourceError(f"actor target malformed: {ref!r}")
+    module = importlib.import_module(module_name)
+    obj = getattr(module, attr, None)
+    if obj is None:
+        raise ActorSourceError(f"actor target not found: {ref!r}")
+    return obj
+
+
+def _wrap_opts(config: Mapping[str, Any]) -> dict[str, Any]:
+    return {key: config[key] for key in _WRAP_KEYS if config.get(key) is not None}
+
+
+def _instantiate_if_factory(loaded: Any, config: Mapping[str, Any]) -> Any:
+    if not (config.get("factory") or config.get("instantiate")):
+        return loaded
+    args = config.get("args") or config.get("factory_args") or []
+    kwargs = config.get("kwargs") or config.get("factory_kwargs") or {}
+    return loaded(*list(args), **dict(kwargs))
+
+
+# --------------------------------------------------------------------------- #
+# resolvers — (config, secret_refs, *, hosted) -> AgentWrapper | Callable
+# The code-loading kinds are rejected in hosted runs by resolve_chat_target
+# (profile.runs_caller_code) before they are ever called; ``hosted`` is accepted
+# here for a uniform signature and defensive checks.
+# --------------------------------------------------------------------------- #
+def resolve_python_callable(
+    config: Mapping[str, Any],
+    secret_refs: Optional[Mapping[str, Any]] = None,
+    *,
+    hosted: bool = False,
+) -> Callable[..., Any]:
+    ref = config.get("target") or config.get("callable")
+    target = _load_attr(ref)
+    if not callable(target):
+        raise ActorSourceError(f"actor target is not callable: {ref!r}")
+    return target
+
+
+def resolve_import_object(
+    config: Mapping[str, Any],
+    secret_refs: Optional[Mapping[str, Any]] = None,
+    *,
+    hosted: bool = False,
+) -> Any:
+    from fi.simulate.agent.generic import wrap_agent
+
+    obj = _load_attr(config.get("target"))
+    return wrap_agent(obj, **_wrap_opts(config))
+
+
+def resolve_factory(
+    config: Mapping[str, Any],
+    secret_refs: Optional[Mapping[str, Any]] = None,
+    *,
+    hosted: bool = False,
+) -> Any:
+    from fi.simulate.agent.generic import wrap_agent
+
+    cls = _load_attr(config.get("target"))
+    instance = _instantiate_if_factory(cls, {**config, "factory": True})
+    return wrap_agent(instance, **_wrap_opts(config))
+
+
+def resolve_framework(
+    config: Mapping[str, Any],
+    secret_refs: Optional[Mapping[str, Any]] = None,
+    *,
+    hosted: bool = False,
+) -> Any:
+    from fi.simulate.agent.generic import wrap_agent
+
+    loaded = _instantiate_if_factory(_load_attr(config.get("target")), config)
+    return wrap_agent(loaded, **_wrap_opts(config))
+
+
+def resolve_system_prompt(
+    config: Mapping[str, Any],
+    secret_refs: Optional[Mapping[str, Any]] = None,
+    *,
+    hosted: bool = False,
+) -> Any:
+    from fi.simulate.agent.wrappers import OpenAIAgentWrapper
+
+    prompt = config.get("system_prompt") or config.get("prompt")
+    if not prompt:
+        raise ActorSourceError("system_prompt actor requires 'system_prompt'")
+    api_key_env = str(config.get("api_key_env", "OPENAI_API_KEY"))
+    _require_env_allowed(api_key_env, secret_refs, hosted=hosted)
+    api_key = os.environ.get(api_key_env)
+    if not api_key:
+        raise ActorSourceError(f"system_prompt actor needs {api_key_env} in the env")
+    try:
+        import openai
+    except ImportError as exc:  # pragma: no cover - optional dep
+        raise ActorSourceError("system_prompt actor requires the openai package") from exc
+    client_kwargs: dict[str, Any] = {"api_key": api_key}
+    base_url = config.get("base_url")
+    if base_url:
+        client_kwargs["base_url"] = str(base_url)
+    client = openai.AsyncOpenAI(**client_kwargs)
+    return OpenAIAgentWrapper(
+        client, model=str(config.get("model", "gpt-4-turbo")), system_prompt=str(prompt)
+    )
+
+
+def resolve_http(
+    config: Mapping[str, Any],
+    secret_refs: Optional[Mapping[str, Any]] = None,
+    *,
+    hosted: bool = False,
+) -> Any:
+    from fi.simulate.endpoints._http_actor import HttpChatAgent
+
+    url = config.get("url")
+    if not isinstance(url, str) or not url:
+        raise ActorSourceError("http actor requires config.url")
+    # auth_env is derived from the job's own secret_refs, so it is provisioned by
+    # construction — no arbitrary env read.
+    return HttpChatAgent(
+        url=url,
+        auth_header=str(config.get("auth_header") or "Authorization"),
+        auth_env=_auth_env_from_refs(secret_refs),
+        extra_headers=_string_map(config.get("headers")),
+    )
+
+
+def _auth_env_from_refs(secret_refs: Optional[Mapping[str, Any]]) -> Optional[str]:
+    if not secret_refs:
+        return None
+    for purpose in ("api_key", "authorization", "token"):
+        for name, ref in secret_refs.items():
+            ref_purpose = getattr(ref, "purpose", None)
+            ref_key = getattr(ref, "key", None)
+            if ref_purpose == purpose or name == purpose:
+                return ref_key
+    return None
+
+
+def _string_map(value: Any) -> dict[str, str]:
+    if not isinstance(value, dict):
+        return {}
+    return {str(k): str(v) for k, v in value.items()}
+
+
+__all__ = [
+    "ActorSourceError",
+    "inprocess_code_allowed",
+    "resolve_factory",
+    "resolve_framework",
+    "resolve_http",
+    "resolve_import_object",
+    "resolve_python_callable",
+    "resolve_system_prompt",
+]

fi/simulate/endpoints/base.py

@@ -0,0 +1,107 @@
+"""AgentEndpoint Protocol + shared data types (plan §4.1)."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from datetime import datetime
+from typing import Protocol
+
+from pydantic import BaseModel, Field, JsonValue
+
+from fi.simulate.realtime.events import RealtimeEvent
+from fi.simulate.realtime.media import AudioFrame
+from fi.simulate.runtime.capabilities import EndpointCapabilities
+
+
+class AgentEndpointManifest(BaseModel):
+    """Static declaration of an endpoint adapter's identity + shape.
+
+    The planner records the manifest on the plan so hosted runs can
+    reconstruct which adapter (name + version) executed a case.
+    """
+
+    name: str
+    version: str = "1"
+    provider: str
+    world_kinds: list[str] = Field(default_factory=lambda: ["voice"])
+    capabilities: EndpointCapabilities = Field(default_factory=EndpointCapabilities)
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class DiscoveryRequest(BaseModel):
+    run_id: str
+    test_case_id: str
+    required_capabilities: list[str] = Field(default_factory=list)
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class DiscoverySnapshot(BaseModel):
+    capabilities: EndpointCapabilities
+    supported: bool = True
+    reasons: list[str] = Field(default_factory=list)
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class EndpointHandle(BaseModel):
+    """Opaque adapter handle returned by ``prepare`` and reused for the case."""
+
+    handle_id: str
+    endpoint_name: str
+    created_at: datetime
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class ReadinessResult(BaseModel):
+    ready: bool
+    latency_ms: float | None = None
+    reason: str | None = None
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class ReconciliationResult(BaseModel):
+    reconciled: bool
+    orphan_ids: list[str] = Field(default_factory=list)
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class AgentEndpoint(Protocol):
+    """Session-oriented target-agent adapter contract (plan §4.1).
+
+    Turn-based agents can still use the legacy ``AgentWrapper.call``
+    surface; this Protocol is the target for realtime/voice/session
+    agents where the engine needs prepare/wait_ready/stop lifecycle.
+    """
+
+    manifest: AgentEndpointManifest
+    capabilities: EndpointCapabilities
+
+    async def discover(self, request: DiscoveryRequest) -> DiscoverySnapshot: ...
+
+    async def prepare(self, plan) -> EndpointHandle: ...  # SimulationPlan
+
+    async def wait_ready(self, handle: EndpointHandle) -> ReadinessResult: ...
+
+    async def send(
+        self, handle: EndpointHandle, event: RealtimeEvent | AudioFrame
+    ) -> None: ...
+
+    async def receive(
+        self, handle: EndpointHandle
+    ) -> AsyncIterator[RealtimeEvent | AudioFrame]: ...
+
+    async def stop(self, handle: EndpointHandle) -> None: ...
+
+    async def cleanup(self, handle: EndpointHandle) -> None: ...
+
+    async def reconcile(self, handle: EndpointHandle) -> ReconciliationResult: ...
+
+
+__all__ = [
+    "AgentEndpoint",
+    "AgentEndpointManifest",
+    "DiscoveryRequest",
+    "DiscoverySnapshot",
+    "EndpointHandle",
+    "ReadinessResult",
+    "ReconciliationResult",
+]

fi/simulate/endpoints/builtins.py

@@ -0,0 +1,10 @@
+"""Back-compat shim. Builtin endpoint registrations moved to
+``fi.simulate.endpoints.profiles`` (slice 3) — importing this module still
+triggers registration via that module's import side effect.
+"""
+
+from __future__ import annotations
+
+from fi.simulate.endpoints import profiles as _profiles  # noqa: F401
+
+__all__: list[str] = []

fi/simulate/endpoints/callable.py

@@ -0,0 +1,95 @@
+"""Callable target-agent adapter for turn-based chat runs."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator, Callable
+from datetime import datetime, timezone
+from typing import Any
+
+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,
+)
+
+
+class CallableAgentEndpoint:
+    """Wraps a plain callable/coroutine target agent."""
+
+    def __init__(
+        self,
+        agent_callable: Callable[..., Any],
+        *,
+        name: str = "callable-agent",
+    ) -> None:
+        self._callable = agent_callable
+        self.manifest = AgentEndpointManifest(
+            name=name,
+            provider="callable",
+            world_kinds=["chat"],
+            capabilities=EndpointCapabilities(text=True, streaming=False),
+        )
+        self.capabilities = self.manifest.capabilities
+
+    async def discover(self, request: DiscoveryRequest) -> DiscoverySnapshot:
+        missing = [
+            cap
+            for cap in request.required_capabilities
+            if cap not in self.capabilities.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"cb-{uuid.uuid4().hex[:12]}",
+            endpoint_name=self.manifest.name,
+            created_at=datetime.now(timezone.utc),
+            metadata={"plan_id": getattr(plan, "plan_id", None)},
+        )
+
+    async def wait_ready(self, handle: EndpointHandle) -> ReadinessResult:
+        del handle
+        return ReadinessResult(ready=True)
+
+    async def send(
+        self, handle: EndpointHandle, event: RealtimeEvent | AudioFrame
+    ) -> None:
+        raise NotImplementedError("CallableAgentEndpoint is turn-based; use invoke()")
+
+    async def receive(
+        self, handle: EndpointHandle
+    ) -> AsyncIterator[RealtimeEvent | AudioFrame]:
+        raise NotImplementedError("CallableAgentEndpoint is turn-based; use invoke()")
+        # unreachable, kept for Protocol conformance
+        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)
+
+    async def invoke(self, *args: Any, **kwargs: Any) -> Any:
+        result = self._callable(*args, **kwargs)
+        if hasattr(result, "__await__"):
+            return await result
+        return result
+
+
+__all__ = ["CallableAgentEndpoint"]

fi/simulate/endpoints/http.py

@@ -0,0 +1,76 @@
+"""HTTP target-agent adapter — capability declaration + Stage-6 seam."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator
+from datetime import datetime, timezone
+
+from pydantic import AnyHttpUrl
+
+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,
+)
+
+
+class HttpAgentEndpoint:
+    """Points at an HTTP agent surface. Wire-up lands in Stage 6."""
+
+    def __init__(self, *, name: str, url: AnyHttpUrl | str) -> None:
+        self.manifest = AgentEndpointManifest(
+            name=name,
+            provider="http",
+            world_kinds=["chat"],
+            capabilities=EndpointCapabilities(text=True, tool_events=True),
+            metadata={"url": str(url)},
+        )
+        self.capabilities = self.manifest.capabilities
+
+    async def discover(self, request: DiscoveryRequest) -> DiscoverySnapshot:
+        del request
+        return DiscoverySnapshot(capabilities=self.capabilities)
+
+    async def prepare(self, plan) -> EndpointHandle:  # noqa: ANN001
+        return EndpointHandle(
+            handle_id=f"http-{uuid.uuid4().hex[:12]}",
+            endpoint_name=self.manifest.name,
+            created_at=datetime.now(timezone.utc),
+            metadata={"plan_id": getattr(plan, "plan_id", None)},
+        )
+
+    async def wait_ready(self, handle: EndpointHandle) -> ReadinessResult:
+        del handle
+        raise NotImplementedError("HttpAgentEndpoint readiness lands in Stage 6")
+
+    async def send(
+        self, handle: EndpointHandle, event: RealtimeEvent | AudioFrame
+    ) -> None:
+        raise NotImplementedError("HttpAgentEndpoint send lands in Stage 6")
+
+    async def receive(
+        self, handle: EndpointHandle
+    ) -> AsyncIterator[RealtimeEvent | AudioFrame]:
+        raise NotImplementedError("HttpAgentEndpoint receive lands in Stage 6")
+        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__ = ["HttpAgentEndpoint"]