sopops 0.1.0__py3-none-any.whl

sopops/__init__.py

@@ -0,0 +1,11 @@
+"""sopops client: fetch an agent's instructions at call start, and send each finished session back.
+
+Framework adapters live in their own modules and import their framework lazily: `sopops.livekit`.
+`SessionStream` optionally sends a session's events while the call runs.
+"""
+
+from .client import Instructions, Sopops, SopopsError, SopopsUnavailable, fetch, release_pin
+from .stream import SessionStream
+
+__version__ = "0.1.0"
+__all__ = ["Instructions", "SessionStream", "Sopops", "SopopsError", "SopopsUnavailable", "fetch", "release_pin"]

sopops/client.py

@@ -0,0 +1,300 @@
+"""The framework-agnostic client: instructions at call start (with a disk cache, so a sopops outage never
+blocks a call) and canonical sessions at call end."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+import os
+import re
+import tempfile
+from dataclasses import asdict, dataclass, field, replace
+from pathlib import Path
+from typing import Any, Literal, Mapping, Sequence
+from urllib.parse import quote
+
+import httpx
+
+log = logging.getLogger("sopops")
+
+Source = Literal["live", "cache", "fallback"]
+
+
+class SopopsError(Exception):
+    """sopops answered with an error, or couldn't be reached."""
+
+
+class SopopsUnavailable(SopopsError):
+    """No instructions: sopops failed, nothing was cached for this agent, and no fallback was given."""
+
+
+@dataclass(frozen=True)
+class Instructions:
+    """An agent's compiled instructions, and what they were built from."""
+
+    text: str
+    release: int | None
+    agent: str
+    blocks: list[dict[str, Any]] = field(default_factory=list)
+    """Each file the prompt was built from, in prompt order: {kind, id, path, version}."""
+    hash: str | None = None
+    platform_ref: str | None = None
+    """`livekit:tonys-pizza`, `elevenlabs:<agent id>`, `vapi:<assistant id>`."""
+    tools: list[str] = field(default_factory=list)
+    tool_sops: list[str] = field(default_factory=list)
+    source: Source = "live"
+    """`live` from sopops, `cache` the last good copy on disk (sopops failed), `fallback` the text you passed."""
+    unfilled: tuple[str, ...] = ()
+    """Placeholders still in `text`: ones you passed no value for. Empty unless you passed `variables`."""
+
+
+PLACEHOLDER = re.compile(r"\{\{\s*([A-Za-z0-9_]+)\s*\}\}")
+
+
+def fill(text: str, variables: Mapping[str, Any]) -> str:
+    """`{{placeholders}}` replaced with your values. One with no value is left as it is, the way sopops leaves a
+    placeholder it has no value for, so a missing value never mangles the instructions."""
+    return PLACEHOLDER.sub(lambda m: str(variables[m.group(1)]) if m.group(1) in variables else m.group(0), text)
+
+
+def unfilled(text: str) -> tuple[str, ...]:
+    """The placeholders still in the text, in order, without repeats."""
+    return tuple(dict.fromkeys(PLACEHOLDER.findall(text)))
+
+
+def _filled(got: Instructions, variables: Mapping[str, Any] | None) -> Instructions:
+    """Fill what this call knows, and say what didn't line up. A mismatch is never fatal: the call goes on with the
+    placeholder as it is, which is what sopops serves anyway."""
+    if not variables:
+        return got
+    wanted = set(unfilled(got.text))
+    text = fill(got.text, variables)
+    left = unfilled(text)
+    if left:
+        log.warning("sopops: no value for %s in %s's instructions; it stays as a placeholder", _names(left), got.agent)
+    spare = [k for k in variables if k not in wanted]
+    if spare:
+        log.warning("sopops: %s has no placeholder in %s's instructions; check the spelling", _names(spare), got.agent)
+    return replace(got, text=text, unfilled=left)
+
+
+def _names(names: Sequence[str]) -> str:
+    return ", ".join(f"{{{{{n}}}}}" for n in names)
+
+
+def release_pin(metadata: str | Mapping[str, Any] | None) -> int | None:
+    """A release pinned for this call (A/B tests) in job or room metadata: `{"sopops_release": 3}` or
+    `{"sopops": {"release": 3}}`, as a JSON string or a dict. None if there's none."""
+    if not metadata:
+        return None
+    if isinstance(metadata, str):
+        try:
+            metadata = json.loads(metadata)
+        except ValueError:
+            return None
+    if not isinstance(metadata, Mapping):
+        return None
+    nested = metadata.get("sopops")
+    value = metadata.get("sopops_release", nested.get("release") if isinstance(nested, Mapping) else None)
+    try:
+        return int(value) if value is not None and not isinstance(value, bool) else None
+    except (TypeError, ValueError):
+        return None
+
+
+def fetch(
+    agent: str,
+    release: int | None = None,
+    *,
+    fallback: str | None = None,
+    variables: Mapping[str, Any] | None = None,
+    url: str | None = None,
+    token: str | None = None,
+    timeout: float = 2.0,
+    cache_dir: str | os.PathLike[str] | None = None,
+) -> Instructions:
+    """The agent's instructions, blocking: one call for code that isn't async.
+
+    `agent` is the sopc agent id or its platform ref (`livekit:tonys-pizza`). `release` pins one; without it you get
+    the live release. `url` and `token` default to `SOPOPS_URL` and `SOPOPS_TOKEN`, as `Sopops` reads them.
+
+    Falls back the same way `Sopops.fetch_instructions` does: the last good copy on disk, then `fallback`, else
+    `SopopsUnavailable`. Inside async code, await that method on a `Sopops` you keep, so the client is reused.
+
+        ins = sopops.fetch("tonys-pizza")           # the live release
+        ins = sopops.fetch("tonys-pizza", 14)       # pinned, e.g. one arm of an A/B test
+        ins = sopops.fetch("tonys-pizza", variables={"now": "7:15pm", "caller": "Sam"})   # filled here, not in sopops
+        prompt = ins.text
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        pass
+    else:
+        raise RuntimeError("sopops.fetch blocks: in async code use `await Sopops(...).fetch_instructions(agent, release)`")
+    client = Sopops(url, token, timeout=timeout, cache_dir=cache_dir)
+    return asyncio.run(client.fetch_instructions(agent, release, fallback=fallback, variables=variables))
+
+
+class Sopops:
+    """A sopops workspace.
+
+    `url` is the workspace's API URL (`http://sopops.internal:8484/v1/workspaces/prod`), default `SOPOPS_URL`.
+    `token` is a workspace token (Settings → Tokens; scope `runtime` to fetch, `ingest` to send sessions), default
+    `SOPOPS_TOKEN` (or `SOPOPS_INGEST_TOKEN`).
+    `timeout` bounds the fetch at call start; on any failure the last good copy on disk is used
+    (`cache_dir`, default `SOPOPS_CACHE_DIR` or `~/.cache/sopops`).
+    """
+
+    def __init__(
+        self,
+        url: str | None = None,
+        token: str | None = None,
+        *,
+        timeout: float = 2.0,
+        cache_dir: str | os.PathLike[str] | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        url = url or os.environ.get("SOPOPS_URL")
+        if not url:
+            raise ValueError("pass url= or set SOPOPS_URL to the workspace's API URL, e.g. http://sopops:8484/v1/workspaces/prod")
+        self.url = url.rstrip("/")
+        self.token = token if token is not None else (os.environ.get("SOPOPS_TOKEN") or os.environ.get("SOPOPS_INGEST_TOKEN"))
+        self.timeout = timeout
+        self.cache_dir = Path(cache_dir or os.environ.get("SOPOPS_CACHE_DIR") or Path.home() / ".cache" / "sopops")
+        self._transport = transport
+
+    def _client(self, timeout: float) -> httpx.AsyncClient:
+        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
+        return httpx.AsyncClient(base_url=self.url, headers=headers, timeout=timeout, transport=self._transport)
+
+    # --- call start ------------------------------------------------------------------------
+
+    async def fetch_instructions(self, agent: str, release: int | None = None, *, fallback: str | None = None,
+                                 variables: Mapping[str, Any] | None = None) -> Instructions:
+        """The agent's instructions in the live release, or in `release` if pinned. `agent` is the sopc agent id
+        or its platform ref (`livekit:tonys-pizza`).
+
+        `variables` fills `{{placeholders}}` this call knows and sopops can't: the time, the caller, anything your
+        code works out per call. It happens here, in your process, so those values never reach sopops. A placeholder
+        you pass no value for is left as it is and listed in `ins.unfilled`. The cache keeps the unfilled text, so a
+        cached copy still fills with this call's values.
+
+        Never waits longer than `timeout`. If sopops fails, returns the last good copy from disk (`source="cache"`),
+        else `fallback` (`source="fallback"`), else raises SopopsUnavailable."""
+        params = {"release": str(release)} if release is not None else None
+        try:
+            async with self._client(self.timeout) as http:
+                res = await asyncio.wait_for(http.get(f"/agents/{agent}", params=params), self.timeout + 0.5)
+            if res.status_code >= 400:
+                raise SopopsError(f"sopops answered {res.status_code} for agent '{agent}': {_detail(res)}")
+            body = res.json()
+            got = Instructions(
+                text=body["prompt"], release=body["release"], agent=body["agent"], blocks=body.get("components", []),
+                hash=body.get("hash"), platform_ref=body.get("platform_ref"), tools=body.get("tools", []), tool_sops=body.get("tool_sops", []),
+            )
+        except (httpx.HTTPError, asyncio.TimeoutError, SopopsError, ValueError, KeyError) as e:
+            reason = str(e) or type(e).__name__
+            cached = self._read_cache(agent, release)
+            if cached is not None:
+                log.warning("sopops: using the cached instructions for %s (release %s): %s", agent, cached.release, reason)
+                return _filled(cached, variables)
+            if fallback is not None:
+                log.error("sopops: using the fallback instructions for %s, nothing cached: %s", agent, reason)
+                return _filled(Instructions(text=fallback, release=None, agent=agent, source="fallback"), variables)
+            raise SopopsUnavailable(f"no instructions for '{agent}': {reason}") from e
+        self._write_cache(agent, release, got)   # unfilled, so the next call fills it with its own values
+        return _filled(got, variables)
+
+    def _cache_file(self, agent: str, release: int | None) -> Path:
+        key = hashlib.sha256(f"{self.url}\n{agent}\n{release if release is not None else 'live'}".encode()).hexdigest()[:24]
+        return self.cache_dir / f"{key}.json"
+
+    def _read_cache(self, agent: str, release: int | None) -> Instructions | None:
+        try:
+            data = json.loads(self._cache_file(agent, release).read_text())
+            return Instructions(**{**data, "source": "cache"})
+        except (OSError, ValueError, TypeError):
+            return None
+
+    def _write_cache(self, agent: str, release: int | None, got: Instructions) -> None:
+        """Atomically, so a crash mid-write never leaves a broken copy. Failures only log: the call goes on."""
+        path = self._cache_file(agent, release)
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".tmp-")
+            with os.fdopen(fd, "w") as f:
+                json.dump(asdict(got), f)
+            os.replace(tmp, path)
+        except OSError as e:
+            log.warning("sopops: couldn't cache instructions for %s: %s", agent, e)
+
+    async def record_served(self, platform: str, call_id: str, agent: str, release: int, *, timeout: float = 3.0) -> None:
+        """Tell sopops which release a call ran on once the platform's id for it is known (an ElevenLabs
+        conversation id, a Vapi call id), so the session its post-call webhook sends links to that release."""
+        async with self._client(timeout) as http:
+            res = await http.post("/runtime/served", json={"platform": platform, "call_id": call_id, "agent": agent, "release": release})
+        if res.status_code >= 400:
+            raise SopopsError(f"sopops answered {res.status_code}: {_detail(res)}")
+
+    # --- call end ----------------------------------------------------------------------------
+
+    async def post_session(self, session: Mapping[str, Any], *, retries: int = 2, timeout: float = 5.0) -> dict[str, Any]:
+        """Send one finished session in sopops's canonical format (`platform`, `external_id`, `turns`, ...).
+        Safe to repeat: sopops upserts on (platform, external_id). Retries connection errors, 429 and 5xx."""
+        last: Exception | None = None
+        async with self._client(timeout) as http:
+            for attempt in range(retries + 1):
+                if attempt:
+                    await asyncio.sleep(0.5 * 2 ** (attempt - 1))
+                try:
+                    res = await http.post("/sessions", json=dict(session))
+                except httpx.HTTPError as e:
+                    last = SopopsError(f"couldn't reach sopops: {type(e).__name__}")
+                    continue
+                if res.status_code == 429 or res.status_code >= 500:
+                    last = SopopsError(f"sopops answered {res.status_code}: {_detail(res)}")
+                    continue
+                if res.status_code >= 400:
+                    raise SopopsError(f"sopops refused the session ({res.status_code}): {_detail(res)}")
+                out: dict[str, Any] = res.json()
+                return out
+        assert last is not None
+        raise last
+
+    # --- during the call (optional: see SessionStream) ------------------------------------------------
+
+    async def open_session(self, session: Mapping[str, Any], *, timeout: float = 3.0) -> dict[str, Any]:
+        """Open a session while the call runs, so its events can be sent as they happen: `platform`,
+        `external_id` and optionally `channel`, `agent`, `release`, `version_ref`, `started_at`, `metadata`.
+        Returns `{id, created}`. Safe to repeat: keyed by (platform, external_id), like `post_session`."""
+        return await self._post("/sessions/open", dict(session), timeout)
+
+    async def append_events(self, platform: str, external_id: str, events: Sequence[Mapping[str, Any]], *, timeout: float = 3.0) -> dict[str, Any]:
+        """Add events to an open session: `{seq, type: "turn" | "tool_call", turn | tool_call}`, with `seq` counting
+        from 0 per session. Order doesn't matter and a resent `seq` is ignored. Returns `{accepted, duplicates}`.
+        The full session sent with `post_session` at the end replaces what was streamed."""
+        path = f"/sessions/{quote(platform, safe='')}/{quote(external_id, safe='')}/events"
+        return await self._post(path, {"events": [dict(e) for e in events]}, timeout)
+
+    async def _post(self, path: str, body: dict[str, Any], timeout: float) -> dict[str, Any]:
+        """One POST, no retries."""
+        try:
+            async with self._client(timeout) as http:
+                res = await http.post(path, json=body)
+        except httpx.HTTPError as e:
+            raise SopopsError(f"couldn't reach sopops: {type(e).__name__}") from e
+        if res.status_code >= 400:
+            raise SopopsError(f"sopops answered {res.status_code}: {_detail(res)}")
+        out: dict[str, Any] = res.json()
+        return out
+
+
+def _detail(res: httpx.Response) -> str:
+    try:
+        detail = res.json().get("detail")
+    except (ValueError, AttributeError):
+        detail = None
+    return str(detail) if detail else res.text[:200]

sopops/livekit.py

@@ -0,0 +1,284 @@
+"""LiveKit Agents adapter (`pip install "sopops[livekit]"`).
+
+    from sopops.livekit import attach
+
+    async def entrypoint(ctx: JobContext):
+        await ctx.connect()
+        session = AgentSession(...)
+        ins = await attach(ctx, session, agent="tonys-pizza")
+        await session.start(room=ctx.room, agent=Agent(instructions=ins.text))
+
+`attach` fetches the instructions (honoring a release pinned in job or room metadata), keeps the release in
+`session.userdata`, and at shutdown posts the session (`session.history` with timestamps and tool calls) to
+sopops, with what it ran with: the session's LLM, STT and TTS models and voice (`agent_config`), so sopops can
+compare an agent's versions with no extra setup. `test=` names an A/B test and `config=` adds settings. With `stream=True` it also sends each turn and tool call as it happens. Nothing here imports livekit at
+import time; the objects are used through their documented attributes and events.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Callable, Mapping
+
+from .client import Instructions, Sopops, release_pin
+from .stream import SessionStream
+
+if TYPE_CHECKING:  # only for type checkers: the adapter needs no livekit import at runtime
+    from livekit.agents import AgentSession, JobContext
+
+log = logging.getLogger("sopops.livekit")
+
+RELEASE_KEY = "sopops_release"
+AGENT_KEY = "sopops_agent"
+
+
+def from_livekit(history: Any) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Map a LiveKit `ChatContext` (`session.history`), or its `to_dict(exclude_timestamp=False)`, to sopops
+    `(turns, tool_calls)`. Times are Unix seconds (`at`). A message that repeats the one before it is dropped
+    (LiveKit can add a user transcript twice)."""
+    data = history.to_dict(exclude_timestamp=False) if hasattr(history, "to_dict") else history
+    turns: list[dict[str, Any]] = []
+    tools: dict[str, dict[str, Any]] = {}
+    for item in data.get("items", []):
+        kind, at = item.get("type"), item.get("created_at")
+        if kind == "message":
+            turn = _message_turn(item.get("role"), item.get("content", []), at, item.get("interrupted", False))
+            if not _repeats(turns[-1] if turns else None, turn):
+                turns.append(turn)
+        elif kind == "function_call":
+            name, call_id = item.get("name"), item.get("call_id")
+            turns.append(_tool_turn(name, item.get("arguments"), at))
+            tools[call_id] = {"name": name, "arguments": item.get("arguments"), "call_id": call_id, "at": at}
+        elif kind == "function_call_output" and item.get("call_id") in tools:
+            tools[item["call_id"]].update(result=item.get("output"), is_error=bool(item.get("is_error", False)))
+    return turns, list(tools.values())
+
+
+def _message_turn(role: Any, content: Any, at: Any, interrupted: Any) -> dict[str, Any]:
+    text = " ".join(c for c in content or [] if isinstance(c, str)).strip()
+    return {"role": role, "text": text, "at": at, "interrupted": bool(interrupted)}
+
+
+def _tool_turn(name: Any, arguments: Any, at: Any) -> dict[str, Any]:
+    return {"role": "tool", "text": f"{name}({arguments if arguments is not None else ''})", "name": name, "at": at}
+
+
+def _repeats(prev: Mapping[str, Any] | None, turn: Mapping[str, Any]) -> bool:
+    """LiveKit can add a user transcript twice."""
+    return prev is not None and prev["role"] == turn["role"] and prev["text"] == turn["text"] and prev.get("name") is None
+
+
+def pinned_release(ctx: JobContext) -> int | None:
+    """A release pinned for this call in the job's dispatch metadata, else the room's metadata."""
+    job = getattr(ctx, "job", None)
+    room = getattr(ctx, "room", None)
+    return release_pin(getattr(job, "metadata", None)) or release_pin(getattr(room, "metadata", None))
+
+
+async def attach(
+    ctx: JobContext,
+    session: AgentSession[Any],
+    agent: str | None = None,
+    *,
+    client: Sopops | None = None,
+    release: int | None = None,
+    fallback: str | None = None,
+    stream: bool = False,
+    test: str | None = None,
+    config: Mapping[str, Any] | None = None,
+    variables: Mapping[str, Any] | None = None,
+    on_guidance: Callable[[Mapping[str, Any]], Any] | None = None,
+) -> Instructions:
+    """Fetch the agent's instructions, note the release in `session.userdata`, and post the session at shutdown.
+
+    `agent`: the sopc agent id or platform ref; default `livekit:<the job's agent name>`. `release` pins one;
+    default: a pin in job or room metadata, else the live release. `fallback`: text to use if sopops is down and
+    nothing is cached (see `Sopops.fetch_instructions`). Call it after `ctx.connect()` for room metadata.
+
+    `stream=True` also sends each turn and tool call while the call runs (see `record_session`).
+    `test`: an A/B test this call is part of. `config`: settings to report beyond the models `agent_config` reads
+    (`{"version": "v2", "turn_detection": "eou"}`); they win over what's read.
+    `variables`: values for `{{placeholders}}` only this call knows, like the time or the caller. They're filled
+    here, in your process, so they never reach sopops. A placeholder you pass no value for is left as it is and
+    listed in `ins.unfilled`, so you can log one that shouldn't be there.
+    `on_guidance`: not yet used: reserved for runtime guidance in a later version."""
+    client = client or Sopops()
+    agent = agent or f"livekit:{ctx.job.agent_name}"
+    pin = release if release is not None else pinned_release(ctx)
+    ins = await client.fetch_instructions(agent, pin, fallback=fallback, variables=variables)
+    _remember(session, ins)
+    record_session(ctx, session, client=client, agent=ins.agent, stream=stream, test=test, config=config, on_guidance=on_guidance)
+    return ins
+
+
+def record_session(
+    ctx: JobContext,
+    session: AgentSession[Any],
+    *,
+    client: Sopops | None = None,
+    agent: str | None = None,
+    stream: bool = False,
+    test: str | None = None,
+    config: Mapping[str, Any] | None = None,
+    on_guidance: Callable[[Mapping[str, Any]], Any] | None = None,
+) -> None:
+    """Post `session.history` to sopops when the job shuts down, keyed by the job id (rooms get reused), with the
+    release from `session.userdata`. Errors are logged, never raised into shutdown.
+
+    `stream=True` also opens the session now and sends each turn and tool call as it happens, in batches from a
+    background task (see `SessionStream`); it never blocks or raises into the agent. The full post at shutdown
+    still happens and replaces what was streamed. `test` and `config`: see `attach`. `on_guidance`: not yet used: reserved for runtime guidance in
+    a later version."""
+    client = client or Sopops()
+    started = datetime.now(timezone.utc)
+    live = _stream(ctx, session, client, agent, started, on_guidance, test, config) if stream else None
+
+    async def send(reason: str = "") -> None:
+        if live is not None:
+            await live.aclose()
+        try:
+            turns, tool_calls = from_livekit(session.history)
+            userdata = _userdata(session)
+            body = {
+                "platform": "livekit",
+                "external_id": ctx.job.id,
+                "agent": agent or _get(userdata, AGENT_KEY) or ctx.job.agent_name or None,
+                "release": _get(userdata, RELEASE_KEY),
+                "started_at": started.isoformat(),
+                "ended_at": datetime.now(timezone.utc).isoformat(),
+                "turns": turns,
+                "tool_calls": tool_calls,
+                "metadata": {"room": ctx.room.name, "shutdown_reason": reason},
+                "test": test,
+                "config": {**agent_config(session), **dict(config or {})},
+            }
+            # stay inside the job's shutdown budget (LiveKit's graceful shutdown is 10s by default)
+            await client.post_session(body, retries=1, timeout=3.0)
+        except Exception as e:  # noqa: BLE001 - a failed post must not break shutdown
+            log.error("sopops: couldn't send session %s: %s", getattr(ctx.job, "id", "?"), e)
+
+    ctx.add_shutdown_callback(send)
+
+
+def _stream(
+    ctx: JobContext, session: AgentSession[Any], client: Sopops, agent: str | None, started: datetime, on_guidance: Callable[[Mapping[str, Any]], Any] | None,
+    test: str | None = None, config: Mapping[str, Any] | None = None,
+) -> SessionStream:
+    """Open a SessionStream for the job and feed it from the session's `conversation_item_added` and
+    `function_tools_executed` events."""
+    userdata = _userdata(session)
+    live = SessionStream(
+        client,
+        {
+            "platform": "livekit",
+            "external_id": ctx.job.id,
+            "channel": "voice",
+            "agent": agent or _get(userdata, AGENT_KEY) or ctx.job.agent_name or None,
+            "release": _get(userdata, RELEASE_KEY),
+            "started_at": started.isoformat(),
+            "metadata": {"room": ctx.room.name},
+            "test": test,
+            "config": {**agent_config(session), **dict(config or {})},
+        },
+        on_guidance=on_guidance,
+    )
+    last: list[dict[str, Any]] = []  # the last turn sent, to drop repeats like from_livekit does
+
+    def on_item(event: Any) -> None:
+        try:
+            item = event.item
+            if getattr(item, "type", "message") != "message":
+                return
+            turn = _message_turn(item.role, item.content, getattr(item, "created_at", None), getattr(item, "interrupted", False))
+            if not _repeats(last[0] if last else None, turn):
+                last[:] = [turn]
+                live.turn(turn)
+        except Exception as e:  # noqa: BLE001 - never raise into the agent
+            log.warning("sopops: couldn't stream a conversation item: %s", e)
+
+    def on_tools(event: Any) -> None:
+        try:
+            outputs = list(getattr(event, "function_call_outputs", None) or [])
+            for i, call in enumerate(event.function_calls):
+                out = outputs[i] if i < len(outputs) else None
+                at = getattr(call, "created_at", None)
+                turn = _tool_turn(call.name, call.arguments, at)
+                last[:] = [turn]
+                live.turn(turn)
+                tool_call = {"name": call.name, "arguments": call.arguments, "call_id": call.call_id, "at": at}
+                if out is not None:
+                    tool_call.update(result=out.output, is_error=bool(getattr(out, "is_error", False)))
+                live.tool_call(tool_call)
+        except Exception as e:  # noqa: BLE001 - never raise into the agent
+            log.warning("sopops: couldn't stream a tool call: %s", e)
+
+    session.on("conversation_item_added", on_item)
+    session.on("function_tools_executed", on_tools)
+    live.start()
+    return live
+
+
+def agent_config(session: Any) -> dict[str, Any]:
+    """What an `AgentSession` runs with: `llm`, `stt`, `tts` as `<provider>/<model>` (LiveKit Inference models are
+    already written that way), and `voice` when the TTS keeps one. Whatever a plugin doesn't say is left out."""
+    out: dict[str, Any] = {}
+    for role in ("llm", "stt", "tts"):
+        try:
+            part = getattr(session, role, None)
+        except Exception:  # noqa: BLE001 - a property that can't answer leaves the setting out
+            part = None
+        if part is None:
+            continue
+        name = _model_name(getattr(part, "provider", None), getattr(part, "model", None))
+        if name:
+            out[role] = name
+        if role == "tts":
+            opts = getattr(part, "_opts", None)
+            voice = getattr(part, "voice", None) or getattr(opts, "voice", None) or getattr(opts, "voice_id", None)
+            if isinstance(voice, str) and voice:
+                out["voice"] = voice
+    return out
+
+
+def _model_name(provider: Any, model: Any) -> str | None:
+    model = model if isinstance(model, str) and model.lower() not in ("", "unknown") else None
+    provider = provider if isinstance(provider, str) and provider.lower() not in ("", "unknown", "livekit") else None
+    if not model:
+        return None
+    return model if "/" in model or not provider else f"{_provider_name(provider)}/{model}"
+
+
+def _provider_name(provider: str) -> str:
+    """Some plugins report their API host as the provider (`api.anthropic.com`): keep the company's name."""
+    host = provider.lower().split("://")[-1].split("/")[0]
+    labels = [p for p in host.split(".") if p]
+    return labels[-2] if len(labels) >= 2 else host
+
+
+def _userdata(session: Any) -> Any:
+    try:
+        return session.userdata
+    except (ValueError, AttributeError):  # LiveKit raises ValueError when no userdata was set
+        return None
+
+
+def _get(userdata: Any, key: str) -> Any:
+    return userdata.get(key) if isinstance(userdata, Mapping) else getattr(userdata, key, None)
+
+
+def _remember(session: Any, ins: Instructions) -> None:
+    userdata = _userdata(session)
+    if userdata is None:
+        session.userdata = {RELEASE_KEY: ins.release, AGENT_KEY: ins.agent}
+    elif isinstance(userdata, dict):
+        userdata[RELEASE_KEY], userdata[AGENT_KEY] = ins.release, ins.agent
+    else:
+        try:
+            setattr(userdata, RELEASE_KEY, ins.release)
+            setattr(userdata, AGENT_KEY, ins.agent)
+        except AttributeError:
+            log.warning("sopops: can't note the release on %s; add a %s field to it", type(userdata).__name__, RELEASE_KEY)
+
+
+__all__ = ["agent_config", "attach", "from_livekit", "pinned_release", "record_session"]