sopops 0.1.0__tar.gz

sopops-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.db
+dist/
+node_modules/
+web/dist/
+src/sopops_server/static/
+*.tsbuildinfo
+.env
+.taste-skill/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+sdks/node/*.tgz
+sdks/python/dist/

sopops-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: sopops
+Version: 0.1.0
+Summary: Fetch your agent's instructions from sopops at call start, and send each finished session back.
+Project-URL: Homepage, https://sopops.dev
+Project-URL: Documentation, https://docs.sopops.dev
+Project-URL: Repository, https://github.com/amanmibra/sopops
+License-Expression: Apache-2.0
+Keywords: livekit,mcp,prompts,sopc,sopops,voice agents
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: livekit
+Requires-Dist: livekit-agents>=1.0; extra == 'livekit'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# sopops
+
+The Python client for [sopops](../../README.md): fetch an agent's instructions when a call starts, and send each finished session back.
+
+```sh
+pip install "sopops[livekit]"     # or plain sopops without the LiveKit adapter
+pip install "sopops[mcp]"         # sopops-mcp, the onboarding MCP server for Claude Code or Codex
+```
+
+It's not on PyPI yet; install from a clone with `pip install "./sdks/python[livekit]"`. The server is a separate package, `sopops-server`.
+
+## LiveKit
+
+```python
+from livekit.agents import Agent, AgentSession, JobContext
+from sopops.livekit import attach
+
+async def entrypoint(ctx: JobContext):
+    await ctx.connect()
+    session = AgentSession(...)                                   # your STT, LLM, TTS
+    ins = await attach(ctx, session, agent="tonys-pizza")         # SOPOPS_URL, SOPOPS_TOKEN
+    await session.start(room=ctx.room, agent=Agent(instructions=ins.text))
+```
+
+`attach` fetches the instructions, notes the release in `session.userdata` (`sopops_release`), and at shutdown posts the session to sopops: `session.history` with timestamps and tool calls, keyed by the job id. To pin a release for a call (A/B tests), put `{"sopops_release": 3}` in the job's dispatch metadata or the room's metadata.
+
+## Any framework
+
+```python
+from sopops import Sopops
+
+sopops = Sopops()                                    # SOPOPS_URL, SOPOPS_TOKEN
+ins = await sopops.fetch_instructions("tonys-pizza", release=None, fallback="You are a helpful host.")
+ins.text, ins.release, ins.blocks                    # the instructions, their release, the files they were built from
+
+await sopops.post_session({"platform": "api", "external_id": call_id, "agent": "tonys-pizza", "release": ins.release,
+                           "turns": [{"role": "user", "text": "Hi", "offset_s": 0.4}]})
+```
+
+| | |
+|---|---|
+| `SOPOPS_URL` | The workspace's API URL, e.g. `http://sopops.internal:8484/v1/workspaces/prod`. |
+| `SOPOPS_TOKEN` | A workspace token (sopops Settings → Tokens) with the scopes the agent needs: `runtime` to fetch instructions, `ingest` to send sessions. `SOPOPS_INGEST_TOKEN` is read too. A workspace without a runtime token serves instructions without one. |
+| `SOPOPS_CACHE_DIR` | Where the last good instructions are kept, default `~/.cache/sopops`. |
+
+**Values only the call knows** (`{{placeholders}}` for the time, the caller, anything your code works out) are
+filled in your process, so they never reach sopops:
+
+```python
+ins = await sopops.fetch_instructions("tonys-pizza", variables={"now": "7:15pm", "caller": "Sam"})
+ins.unfilled                                         # placeholders nobody filled, e.g. ("special",)
+```
+
+A placeholder with no value is left as it is, and a value with no placeholder is ignored. Both log a warning and
+neither stops the call. `attach` takes `variables` too.
+
+Outside async code, one call does the same:
+
+```python
+import sopops
+
+ins = sopops.fetch("tonys-pizza")          # the live release
+ins = sopops.fetch("tonys-pizza", 14)      # pinned, e.g. one arm of an A/B test
+prompt = ins.text
+```
+
+It reads the same environment variables, caches and falls back the same way, and builds a client per call, so inside
+async code keep a `Sopops` and await `fetch_instructions` instead.
+
+**A sopops outage never blocks a call.** The fetch gives up after `timeout` (2s by default). Then it returns the last good copy for that agent and release from disk (`ins.source == "cache"`), else your `fallback` (`"fallback"`), else raises `SopopsUnavailable`. Sessions are retried on connection errors, 429 and 5xx; sending the same session again is safe.
+
+## Streaming (optional)
+
+```python
+ins = await attach(ctx, session, agent="tonys-pizza", stream=True)
+```
+
+With `stream=True`, `attach` opens the session when the call starts and sends each turn and tool call as it happens (LiveKit's `conversation_item_added` and `function_tools_executed` events), in batches from a background task. It never blocks the agent and never raises into it: if sopops is slow or down, or the queue fills, events are logged and dropped. At shutdown it still posts the full session, which replaces what was streamed, so the default (`stream=False`, one post at the end) loses nothing. `on_guidance=` is accepted but not yet used: it's reserved for runtime guidance in a later version.
+
+Outside LiveKit, use `SessionStream` directly:
+
+```python
+from sopops import SessionStream
+
+stream = SessionStream(sopops, {"platform": "api", "external_id": call_id, "agent": "tonys-pizza", "release": ins.release})
+stream.start()
+stream.turn({"role": "user", "text": "Delivery please.", "at": time.time()})
+stream.tool_call({"name": "check_delivery_zone", "arguments": {"address": "221 Mercer St"}, "result": {"in_zone": True}})
+await stream.aclose()                                # sends what's queued (at most 1s), then stops
+await sopops.post_session(full_session)
+```
+
+`Sopops.open_session` and `Sopops.append_events` are the two requests underneath (`POST …/sessions/open`, `POST …/sessions/<platform>/<id>/events`). Streaming needs the `ingest` scope, like posting.
+
+The session format is in [API reference](../../docs/api/sessions.md#the-canonical-format). Adapters for other frameworks go in their own modules next to `sopops.livekit`, each importing its framework only when used. The TypeScript client is in [sdks/node](../node). A complete LiveKit agent is in [examples/livekit-restaurant](../../examples/livekit-restaurant).
+
+## sopops-mcp (onboarding)
+
+`sopops-mcp` is the MCP server a coding agent (Claude Code, Codex) runs to onboard existing agents into sopops. The sopops Import page gives you the command, with your server and a 2-hour onboarding token filled in:
+
+```sh
+claude mcp add sopops --env SOPOPS_URL=http://127.0.0.1:8484 --env SOPOPS_TOKEN=sopops_onb_... \
+  -- uvx --from 'sopops[mcp] @ git+https://github.com/amanmibra/sopops@main#subdirectory=sdks/python' sopops-mcp
+```
+
+It reads ElevenLabs and Vapi agents locally (`ELEVENLABS_API_KEY`, `VAPI_API_KEY`, read-only) and writes the sopc project into the repo; everything else (the kickoff, the extraction guide, compiling, fidelity, pushing) goes to the sopops server's `/v1/onboarding` endpoints with `SOPOPS_URL` and `SOPOPS_TOKEN`. `sopops-mcp install-skill --url URL` copies the server's sopops-onboard skill into the repo (`--claude`, `--codex`).
+
+## Development
+
+```sh
+cd sdks/python && uv run pytest
+```

sopops-0.1.0/README.md

@@ -0,0 +1,112 @@
+# sopops
+
+The Python client for [sopops](../../README.md): fetch an agent's instructions when a call starts, and send each finished session back.
+
+```sh
+pip install "sopops[livekit]"     # or plain sopops without the LiveKit adapter
+pip install "sopops[mcp]"         # sopops-mcp, the onboarding MCP server for Claude Code or Codex
+```
+
+It's not on PyPI yet; install from a clone with `pip install "./sdks/python[livekit]"`. The server is a separate package, `sopops-server`.
+
+## LiveKit
+
+```python
+from livekit.agents import Agent, AgentSession, JobContext
+from sopops.livekit import attach
+
+async def entrypoint(ctx: JobContext):
+    await ctx.connect()
+    session = AgentSession(...)                                   # your STT, LLM, TTS
+    ins = await attach(ctx, session, agent="tonys-pizza")         # SOPOPS_URL, SOPOPS_TOKEN
+    await session.start(room=ctx.room, agent=Agent(instructions=ins.text))
+```
+
+`attach` fetches the instructions, notes the release in `session.userdata` (`sopops_release`), and at shutdown posts the session to sopops: `session.history` with timestamps and tool calls, keyed by the job id. To pin a release for a call (A/B tests), put `{"sopops_release": 3}` in the job's dispatch metadata or the room's metadata.
+
+## Any framework
+
+```python
+from sopops import Sopops
+
+sopops = Sopops()                                    # SOPOPS_URL, SOPOPS_TOKEN
+ins = await sopops.fetch_instructions("tonys-pizza", release=None, fallback="You are a helpful host.")
+ins.text, ins.release, ins.blocks                    # the instructions, their release, the files they were built from
+
+await sopops.post_session({"platform": "api", "external_id": call_id, "agent": "tonys-pizza", "release": ins.release,
+                           "turns": [{"role": "user", "text": "Hi", "offset_s": 0.4}]})
+```
+
+| | |
+|---|---|
+| `SOPOPS_URL` | The workspace's API URL, e.g. `http://sopops.internal:8484/v1/workspaces/prod`. |
+| `SOPOPS_TOKEN` | A workspace token (sopops Settings → Tokens) with the scopes the agent needs: `runtime` to fetch instructions, `ingest` to send sessions. `SOPOPS_INGEST_TOKEN` is read too. A workspace without a runtime token serves instructions without one. |
+| `SOPOPS_CACHE_DIR` | Where the last good instructions are kept, default `~/.cache/sopops`. |
+
+**Values only the call knows** (`{{placeholders}}` for the time, the caller, anything your code works out) are
+filled in your process, so they never reach sopops:
+
+```python
+ins = await sopops.fetch_instructions("tonys-pizza", variables={"now": "7:15pm", "caller": "Sam"})
+ins.unfilled                                         # placeholders nobody filled, e.g. ("special",)
+```
+
+A placeholder with no value is left as it is, and a value with no placeholder is ignored. Both log a warning and
+neither stops the call. `attach` takes `variables` too.
+
+Outside async code, one call does the same:
+
+```python
+import sopops
+
+ins = sopops.fetch("tonys-pizza")          # the live release
+ins = sopops.fetch("tonys-pizza", 14)      # pinned, e.g. one arm of an A/B test
+prompt = ins.text
+```
+
+It reads the same environment variables, caches and falls back the same way, and builds a client per call, so inside
+async code keep a `Sopops` and await `fetch_instructions` instead.
+
+**A sopops outage never blocks a call.** The fetch gives up after `timeout` (2s by default). Then it returns the last good copy for that agent and release from disk (`ins.source == "cache"`), else your `fallback` (`"fallback"`), else raises `SopopsUnavailable`. Sessions are retried on connection errors, 429 and 5xx; sending the same session again is safe.
+
+## Streaming (optional)
+
+```python
+ins = await attach(ctx, session, agent="tonys-pizza", stream=True)
+```
+
+With `stream=True`, `attach` opens the session when the call starts and sends each turn and tool call as it happens (LiveKit's `conversation_item_added` and `function_tools_executed` events), in batches from a background task. It never blocks the agent and never raises into it: if sopops is slow or down, or the queue fills, events are logged and dropped. At shutdown it still posts the full session, which replaces what was streamed, so the default (`stream=False`, one post at the end) loses nothing. `on_guidance=` is accepted but not yet used: it's reserved for runtime guidance in a later version.
+
+Outside LiveKit, use `SessionStream` directly:
+
+```python
+from sopops import SessionStream
+
+stream = SessionStream(sopops, {"platform": "api", "external_id": call_id, "agent": "tonys-pizza", "release": ins.release})
+stream.start()
+stream.turn({"role": "user", "text": "Delivery please.", "at": time.time()})
+stream.tool_call({"name": "check_delivery_zone", "arguments": {"address": "221 Mercer St"}, "result": {"in_zone": True}})
+await stream.aclose()                                # sends what's queued (at most 1s), then stops
+await sopops.post_session(full_session)
+```
+
+`Sopops.open_session` and `Sopops.append_events` are the two requests underneath (`POST …/sessions/open`, `POST …/sessions/<platform>/<id>/events`). Streaming needs the `ingest` scope, like posting.
+
+The session format is in [API reference](../../docs/api/sessions.md#the-canonical-format). Adapters for other frameworks go in their own modules next to `sopops.livekit`, each importing its framework only when used. The TypeScript client is in [sdks/node](../node). A complete LiveKit agent is in [examples/livekit-restaurant](../../examples/livekit-restaurant).
+
+## sopops-mcp (onboarding)
+
+`sopops-mcp` is the MCP server a coding agent (Claude Code, Codex) runs to onboard existing agents into sopops. The sopops Import page gives you the command, with your server and a 2-hour onboarding token filled in:
+
+```sh
+claude mcp add sopops --env SOPOPS_URL=http://127.0.0.1:8484 --env SOPOPS_TOKEN=sopops_onb_... \
+  -- uvx --from 'sopops[mcp] @ git+https://github.com/amanmibra/sopops@main#subdirectory=sdks/python' sopops-mcp
+```
+
+It reads ElevenLabs and Vapi agents locally (`ELEVENLABS_API_KEY`, `VAPI_API_KEY`, read-only) and writes the sopc project into the repo; everything else (the kickoff, the extraction guide, compiling, fidelity, pushing) goes to the sopops server's `/v1/onboarding` endpoints with `SOPOPS_URL` and `SOPOPS_TOKEN`. `sopops-mcp install-skill --url URL` copies the server's sopops-onboard skill into the repo (`--claude`, `--codex`).
+
+## Development
+
+```sh
+cd sdks/python && uv run pytest
+```

sopops-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "sopops"
+version = "0.1.0"
+description = "Fetch your agent's instructions from sopops at call start, and send each finished session back."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27"]
+keywords = ["sopops", "sopc", "voice agents", "livekit", "prompts", "mcp"]
+classifiers = ["Typing :: Typed"]
+
+[project.urls]
+Homepage = "https://sopops.dev"
+Documentation = "https://docs.sopops.dev"
+Repository = "https://github.com/amanmibra/sopops"
+
+[project.optional-dependencies]
+livekit = ["livekit-agents>=1.0"]
+# sopops-mcp: the onboarding MCP server a coding agent (Claude Code, Codex) runs, talking to sopops over HTTP.
+mcp = ["mcp>=2.3,<3"]
+
+[project.scripts]
+sopops-mcp = "sopops.mcp:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "respx>=0.22", "mcp>=2.3,<3"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sopops"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sopops-0.1.0/src/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-0.1.0/src/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]