saa-livekit-client 0.3.0__py3-none-any.whl

saa_livekit_client/__init__.py

@@ -0,0 +1,52 @@
+"""saa-livekit-client — consume saa events inside a LiveKit voice agent.
+
+Public exports:
+
+    AttentionEngine          - listens to the hidden hosted agent's data
+                               channel events and fires typed callbacks.
+    start_attention_session  - summons the hosted agent into your room.
+    attention_agent_token    - issues the hidden-participant token the
+                               hosted agent uses to connect.
+    build_attention_entrypoint - factory that composes the above into a
+                                 ready-to-go entrypoint(ctx) function.
+
+Event types:
+    PredictionEvent, VADEvent, TurnReadyEvent, TurnFrame,
+    InterruptEvent, InterjectionEvent, ErrorEvent
+"""
+from .api import (
+    AttentionAPIError,
+    SessionHandle,
+    start_attention_session,
+)
+from .engine import AttentionEngine, DATA_TOPIC
+from .factory import build_attention_entrypoint
+from .tokens import DEFAULT_AGENT_IDENTITY, attention_agent_token
+from .types import (
+    ErrorEvent,
+    InterjectionEvent,
+    InterruptEvent,
+    PredictionEvent,
+    TurnFrame,
+    TurnReadyEvent,
+    VADEvent,
+)
+
+
+__version__ = "0.3.0"
+
+__all__ = [
+    # Engine
+    "AttentionEngine", "DATA_TOPIC",
+    # REST client
+    "start_attention_session", "SessionHandle", "AttentionAPIError",
+    # Tokens
+    "attention_agent_token", "DEFAULT_AGENT_IDENTITY",
+    # Factory
+    "build_attention_entrypoint",
+    # Event types
+    "PredictionEvent", "VADEvent", "TurnReadyEvent", "TurnFrame",
+    "InterruptEvent", "InterjectionEvent", "ErrorEvent",
+    # Version
+    "__version__",
+]

saa_livekit_client/_wire.py

@@ -0,0 +1,84 @@
+"""Binary turn payload codec (parser side).
+
+Wire format (`application/x-saa-turn`), little-endian throughout:
+
+    [4-byte uint32: pcm_byte_len]
+    [pcm_byte_len bytes: int16 LE PCM @ 16 kHz mono]
+    [for each frame:
+        [4-byte float32: ts_offset_s]
+        [4-byte uint32:  jpeg_byte_len]
+        [jpeg_byte_len bytes: raw JPEG]
+    ]
+"""
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from .types import TurnFrame
+
+
+_HEADER = struct.Struct("<I")              # pcm_byte_len
+_FRAME_HEADER = struct.Struct("<fI")       # ts_offset_s, jpeg_byte_len
+
+
+class TurnPayloadError(ValueError):
+    """Raised when the binary buffer does not match the wire format."""
+
+
+@dataclass(frozen=True)
+class ParsedTurnPayload:
+    pcm16: bytes
+    frames: list[TurnFrame]
+
+
+def parse_turn_payload(buf: bytes) -> ParsedTurnPayload:
+    """Decode a turn payload received via LiveKit byte stream.
+
+    Raises TurnPayloadError on truncation or invalid length fields.
+    """
+    if len(buf) < _HEADER.size:
+        raise TurnPayloadError(
+            f"buffer too short for header: {len(buf)} < {_HEADER.size}"
+        )
+
+    (pcm_len,) = _HEADER.unpack_from(buf, 0)
+    pcm_start = _HEADER.size
+    pcm_end = pcm_start + pcm_len
+    if pcm_end > len(buf):
+        raise TurnPayloadError(
+            f"pcm length {pcm_len} exceeds buffer ({len(buf) - pcm_start} remaining)"
+        )
+
+    pcm16 = bytes(buf[pcm_start:pcm_end])
+
+    frames: list[TurnFrame] = []
+    cursor = pcm_end
+    while cursor < len(buf):
+        if cursor + _FRAME_HEADER.size > len(buf):
+            raise TurnPayloadError(
+                f"truncated frame header at offset {cursor} "
+                f"({len(buf) - cursor} bytes remaining, need {_FRAME_HEADER.size})"
+            )
+        ts_offset_s, jpeg_len = _FRAME_HEADER.unpack_from(buf, cursor)
+        cursor += _FRAME_HEADER.size
+        if cursor + jpeg_len > len(buf):
+            raise TurnPayloadError(
+                f"truncated frame JPEG at offset {cursor} "
+                f"(need {jpeg_len}, have {len(buf) - cursor})"
+            )
+        frames.append(TurnFrame(
+            ts_offset_s=float(ts_offset_s),
+            jpeg_bytes=bytes(buf[cursor:cursor + jpeg_len]),
+        ))
+        cursor += jpeg_len
+
+    return ParsedTurnPayload(pcm16=pcm16, frames=frames)
+
+
+def encode_turn_payload(pcm16: bytes, frames: list[TurnFrame]) -> bytes:
+    parts: list[bytes] = [_HEADER.pack(len(pcm16)), pcm16]
+    for f in frames:
+        parts.append(_FRAME_HEADER.pack(f.ts_offset_s, len(f.jpeg_bytes)))
+        parts.append(f.jpeg_bytes)
+    return b"".join(parts)

saa_livekit_client/api.py

@@ -0,0 +1,168 @@
+"""REST client for the saa hosted bridge.
+
+Wraps `POST /v1/sessions/livekit` (and the GET / DELETE companions) into a
+single `start_attention_session(...)` call returning a `SessionHandle`.
+
+The consumer only needs to call this once per LiveKit session;
+the actual saa agent joins their room asynchronously and starts
+publishing events on the `"saa"` topic shortly after.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+
+logger = logging.getLogger("saa_livekit_client.api")
+
+DEFAULT_API_BASE = "https://broker.attentionlabs.ai"
+
+
+class AttentionAPIError(RuntimeError):
+    """Raised when the hosted bridge rejects the request or returns a non-2xx
+    response. `.status_code` exposes the HTTP code; `.body` carries the
+    server's JSON error payload (or raw text if non-JSON).
+    """
+
+    def __init__(self, status_code: int, body: Any, message: str | None = None):
+        super().__init__(message or f"hosted bridge error: {status_code} {body!r}")
+        self.status_code = status_code
+        self.body = body
+
+
+@dataclass
+class SessionHandle:
+    """Reference to an active hosted-bridge session.
+
+    `agent_identity` is the LiveKit participant identity the hosted agent
+    joined under — use it when constructing `AttentionEngine` and when
+    sending upstream actions so they're scoped to the right participant.
+
+    `stop()` is idempotent: calling it twice (e.g. via an explicit cleanup
+    AND a `ctx.add_shutdown_callback` registration) won't raise on the
+    second call. The underlying httpx client is closed exactly once.
+    """
+
+    session_id: str
+    agent_identity: str
+    _api_base: str
+    _api_key: str
+    _client: httpx.AsyncClient
+    _closed: bool = field(default=False, repr=False)
+
+    async def stop(self) -> None:
+        """Signal the hosted agent to disconnect and tear down the session."""
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            resp = await self._client.delete(
+                f"{self._api_base}/v1/sessions/{self.session_id}",
+                headers={"Authorization": f"Bearer {self._api_key}"},
+            )
+            if resp.status_code >= 400 and resp.status_code != 404:
+                # 404 = already gone, treat as success
+                raise AttentionAPIError(resp.status_code, _safe_json(resp))
+        finally:
+            await self._client.aclose()
+
+    async def status(self) -> dict[str, Any]:
+        """Fetch current session status (uptime, last_prediction, error_count)."""
+        if self._closed:
+            raise AttentionAPIError(
+                0, None, "SessionHandle.status() called after stop()",
+            )
+        resp = await self._client.get(
+            f"{self._api_base}/v1/sessions/{self.session_id}",
+            headers={"Authorization": f"Bearer {self._api_key}"},
+        )
+        if resp.status_code >= 400:
+            raise AttentionAPIError(resp.status_code, _safe_json(resp))
+        return resp.json()
+
+
+async def start_attention_session(
+    *,
+    api_key: str,
+    livekit_url: str,
+    agent_token: str,
+    room_name: str,
+    participant_identity: str,
+    attention_config: dict[str, Any] | None = None,
+    api_base: str = DEFAULT_API_BASE,
+    timeout: float = 30.0,
+) -> SessionHandle:
+    """Summon the saa hosted agent into the customer's LiveKit room.
+
+    The call returns once the hosted bridge accepts the request (HTTP 200);
+    the hidden agent participant joins the room asynchronously shortly after.
+    Wait on `AttentionEngine.is_ready` (or the `"started"` event) before
+    relying on inference output.
+
+    Args:
+        api_key:              SAA_API_KEY — customer's saa API key.
+        livekit_url:          Customer's LiveKit URL (e.g. wss://x.livekit.cloud).
+                              Must be publicly reachable from our cloud.
+        agent_token:          Hidden-participant JWT, issued via
+                              `attention_agent_token(...)`.
+        room_name:            Room name the agent should join. Must match the
+                              room scope on `agent_token`.
+        participant_identity: Identity of the human user whose tracks the
+                              agent should analyze.
+        attention_config:     Optional config overrides (vetted subset only).
+                              See https://attentionlabs.ai/docs/livekit for the
+                              public field list. Unknown fields are silently ignored.
+        api_base:             Override the API base URL (testing / private envs).
+        timeout:              HTTP timeout for the POST call.
+    """
+    api_base = api_base.rstrip("/")
+
+    body: dict[str, Any] = {
+        "livekit_url": livekit_url,
+        "agent_token": agent_token,
+        "room_name": room_name,
+        "participant_identity": participant_identity,
+    }
+    if attention_config:
+        body["attention_config"] = attention_config
+
+    # Keep the httpx client open for the lifetime of the handle so
+    # subsequent .stop() / .status() calls reuse the same connection pool.
+    client = httpx.AsyncClient(timeout=timeout)
+    try:
+        resp = await client.post(
+            f"{api_base}/v1/sessions/livekit",
+            json=body,
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+    except Exception:
+        await client.aclose()
+        raise
+
+    if resp.status_code >= 400:
+        body_text = _safe_json(resp)
+        await client.aclose()
+        raise AttentionAPIError(resp.status_code, body_text)
+
+    data = resp.json()
+    logger.info(
+        "started attention session %s (agent_identity=%s)",
+        data.get("session_id"), data.get("agent_identity"),
+    )
+    return SessionHandle(
+        session_id=data["session_id"],
+        agent_identity=data["agent_identity"],
+        _api_base=api_base,
+        _api_key=api_key,
+        _client=client,
+    )
+
+
+def _safe_json(resp: httpx.Response) -> Any:
+    try:
+        return resp.json()
+    except Exception:
+        return resp.text