callva-livekit 0.1.0__py3-none-any.whl

callva/livekit/config/__init__.py

@@ -0,0 +1,21 @@
+"""Per-call configuration resolution.
+
+Configuration reaches the agent through agent dispatch metadata — ``ctx.job.metadata`` —
+either as a body or as a pointer to an endpoint, or from an endpoint named in the
+environment. Room metadata is deliberately not used: it is broadcast to every participant
+in the room, so a prompt placed there is readable by any connected client.
+"""
+
+from .models import CallConfig, Variables
+from .resolver import ConfigError, as_path, load, request_payload
+from .template import render
+
+__all__ = [
+    "CallConfig",
+    "ConfigError",
+    "Variables",
+    "as_path",
+    "load",
+    "render",
+    "request_payload",
+]

callva/livekit/config/models.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..core.transport import WebhookTarget
+from .template import render
+
+
+class Variables(dict):
+    """The call's variables, with their JSON types intact.
+
+    A number stays a number and a boolean stays a boolean; only substitution into a
+    prompt takes the string form. The typed accessors are for reading a variable in code
+    without re-checking what the producer sent.
+    """
+
+    def get_str(self, name: str, default: str | None = None) -> str | None:
+        value = self.get(name)
+        return default if value is None else str(value)
+
+    def get_int(self, name: str, default: int | None = None) -> int | None:
+        value = self.get(name)
+        if isinstance(value, bool) or value is None:
+            return default
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return default
+
+    def get_float(self, name: str, default: float | None = None) -> float | None:
+        value = self.get(name)
+        if isinstance(value, bool) or value is None:
+            return default
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            return default
+
+    def get_bool(self, name: str, default: bool | None = None) -> bool | None:
+        value = self.get(name)
+        if value is None:
+            return default
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, (int, float)):
+            return bool(value)
+        if isinstance(value, str):
+            lowered = value.strip().lower()
+            if lowered in ("1", "true", "yes", "on"):
+                return True
+            if lowered in ("0", "false", "no", "off"):
+                return False
+        return default
+
+
+@dataclass
+class CallConfig:
+    """The configuration resolved for one call.
+
+    ``prompt`` and ``greeting`` come back rendered. The unrendered forms are kept beside
+    them for callers that need the original.
+    """
+
+    prompt: str | None = None
+    greeting: str | None = None
+    raw_prompt: str | None = None
+    raw_greeting: str | None = None
+    variables: Variables = field(default_factory=Variables)
+    webhook: WebhookTarget | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+    source: str = "none"
+    """Where this came from: ``metadata``, ``file``, ``url``, or ``none``."""
+
+    @property
+    def empty(self) -> bool:
+        return not any((self.prompt, self.greeting, self.variables, self.extra))
+
+    @classmethod
+    def parse(cls, payload: Any, *, source: str) -> CallConfig:
+        """Build a config from a decoded response body. Never raises."""
+        if not isinstance(payload, dict):
+            return cls(source=source)
+
+        variables = payload.get("variables")
+        variables = Variables(variables) if isinstance(variables, dict) else Variables()
+
+        raw_prompt = payload.get("prompt")
+        raw_prompt = raw_prompt if isinstance(raw_prompt, str) else None
+        raw_greeting = payload.get("greeting")
+        raw_greeting = raw_greeting if isinstance(raw_greeting, str) else None
+
+        extra = payload.get("extra")
+
+        return cls(
+            prompt=render(raw_prompt, variables),
+            greeting=render(raw_greeting, variables),
+            raw_prompt=raw_prompt,
+            raw_greeting=raw_greeting,
+            variables=variables,
+            webhook=WebhookTarget.from_dict(payload.get("webhook")),
+            extra=extra if isinstance(extra, dict) else {},
+            source=source,
+        )

callva/livekit/config/resolver.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any, Literal
+from urllib.parse import urlparse
+from urllib.request import url2pathname
+
+from ..core import env, transport
+from ..core import state as _state
+from ..core.log import logger
+from .models import CallConfig
+
+OnError = Literal["terminate", "continue"]
+
+
+class ConfigError(RuntimeError):
+    """Configuration for this call could not be resolved."""
+
+
+def as_path(endpoint: str) -> Path | None:
+    """A local file, or ``None`` if this names a remote endpoint.
+
+    ``file:///etc/agent.json`` and a bare ``./agent.json`` both mean the same thing. A
+    file answers instantly and needs no participant, which makes it the shortest possible
+    development loop; it cannot answer per caller, which is why it is not the production
+    channel.
+    """
+    if endpoint.startswith("file://"):
+        return Path(url2pathname(urlparse(endpoint).path))
+    if "://" in endpoint:
+        return None
+    return Path(endpoint).expanduser()
+
+
+async def _read_file(path: Path) -> Any:
+    text = await asyncio.get_running_loop().run_in_executor(None, path.read_text)
+    return json.loads(text)
+
+
+async def load(
+    *,
+    url: str | None = None,
+    api_key: str | None = None,
+    direction: str | None = None,
+    on_error: OnError = "terminate",
+    timeout: float | None = None,
+) -> CallConfig:
+    """Resolve the configuration for this call.
+
+    Resolution order:
+
+    1. a body inside ``ctx.job.metadata`` — returns immediately, before anyone has joined
+    2. a pointer inside ``ctx.job.metadata`` — followed
+    3. ``CONFIG_URL`` (or the ``url`` argument) — followed
+
+    A pointer is either an endpoint, asked with the call's own context as the request body
+    so the responder can answer "who called which number", or a local file — ``file://…``
+    or a plain path — read as it is.
+
+    Only the endpoint path needs the SIP envelope to build its request, so only it waits
+    for the participant to join. A body in metadata and a file both answer immediately.
+
+    When configuration cannot be resolved the call is terminated and the reason logged: an
+    agent without its prompt is a broken call either way, and failing quietly hides it.
+    Pass ``on_error="continue"`` to receive an empty config instead.
+    """
+    st = _state.state()
+
+    if st.config is not None:
+        return st.config
+
+    envelope = st.envelope
+
+    if envelope.config is not None:
+        return _store(st, CallConfig.parse(envelope.config, source="metadata"))
+
+    endpoint = envelope.config_url or url or env.get("CONFIG_URL")
+    if not endpoint:
+        logger.debug("no configuration source: job metadata carries none and no URL is set")
+        return _store(st, CallConfig(source="none"))
+
+    path = as_path(endpoint)
+    if path is not None:
+        try:
+            body = await _read_file(path)
+        except (OSError, ValueError) as exc:
+            return _fail(st, on_error, f"could not read configuration from {path}: {exc}")
+
+        config = CallConfig.parse(body, source="file")
+        if config.empty:
+            return _fail(st, on_error, f"configuration file {path} carried nothing usable")
+
+        logger.debug("resolved configuration from %s", path)
+        return _store(st, config)
+
+    try:
+        participant = await st.ctx.wait_for_participant()
+    except Exception as exc:
+        return _fail(st, on_error, f"no participant joined, cannot request configuration: {exc}")
+
+    identity = _state.ensure_identity(st, participant=participant, direction=direction)
+
+    try:
+        body = await transport.fetch_json(
+            endpoint,
+            payload=request_payload(st, participant),
+            api_key=api_key or env.get("CONFIG_API_KEY"),
+            timeout=timeout,
+        )
+    except transport.FetchError as exc:
+        return _fail(st, on_error, f"configuration request to {endpoint} failed: {exc}")
+
+    config = CallConfig.parse(body, source="url")
+    if config.empty:
+        return _fail(st, on_error, f"configuration response from {endpoint} carried nothing usable")
+
+    logger.debug("resolved configuration for call %s from %s", identity.id, endpoint)
+    return _store(st, config)
+
+
+def request_payload(st: _state.CallState, participant: Any) -> dict[str, Any]:
+    """The body of a configuration request.
+
+    The request is the question: it carries who is calling, which number they reached and
+    how the call arrived, so the responder can decide what to send back.
+    """
+    identity = _state.ensure_identity(st, participant=participant)
+    job = st.ctx.job
+
+    return {
+        "room": getattr(job.room, "name", None),
+        "job_id": job.id,
+        "dispatch_id": getattr(job, "dispatch_id", None) or None,
+        "agent_name": getattr(job, "agent_name", None) or None,
+        "direction": identity.direction,
+        "from": identity.from_party.to_dict(),
+        "to": identity.to_party.to_dict(),
+        "sip": identity.sip,
+        "participant_identity": getattr(participant, "identity", None),
+        "metadata": st.envelope.raw,
+    }
+
+
+def _store(st: _state.CallState, config: CallConfig) -> CallConfig:
+    st.config = config
+    if config.webhook is not None:
+        st.webhook = config.webhook
+    return config
+
+
+def _fail(st: _state.CallState, on_error: OnError, reason: str) -> CallConfig:
+    if on_error == "continue":
+        logger.error("%s; continuing without configuration", reason)
+        return _store(st, CallConfig(source="none"))
+
+    logger.error("%s; terminating the call", reason)
+    try:
+        st.ctx.shutdown(reason="callva: configuration unavailable")
+    except Exception:
+        logger.debug("could not request shutdown", exc_info=True)
+    raise ConfigError(reason)

callva/livekit/config/template.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any
+
+from ..core.log import logger
+
+PLACEHOLDER = re.compile(
+    r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\s*\}\}"
+)
+
+_MISSING = object()
+
+
+def _lookup(variables: Mapping[str, Any], path: str) -> Any:
+    cursor: Any = variables
+    for part in path.split("."):
+        if not isinstance(cursor, Mapping) or part not in cursor:
+            return _MISSING
+        cursor = cursor[part]
+    return cursor
+
+
+def _stringify(value: Any) -> str:
+    """Render a value the way its producer wrote it.
+
+    Booleans come back as ``true``/``false`` rather than Python's capitalised form, and a
+    null renders as nothing at all, because both end up inside a prompt a model reads.
+    """
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def render(text: str | None, variables: Mapping[str, Any] | None) -> str | None:
+    """Substitute ``{{ name }}`` placeholders from ``variables``.
+
+    A placeholder with no matching variable is left exactly as it was and logged at
+    warning level. Rendering never raises and never evaluates anything: one missing key
+    must not take down a call that is already ringing.
+    """
+    if not text or not variables:
+        return text
+
+    missing: list[str] = []
+
+    def substitute(match: re.Match[str]) -> str:
+        path = match.group(1)
+        value = _lookup(variables, path)
+        if value is _MISSING:
+            missing.append(path)
+            return match.group(0)
+        return _stringify(value)
+
+    rendered = PLACEHOLDER.sub(substitute, text)
+
+    if missing:
+        logger.warning(
+            "left %s unresolved placeholder(s) in place: %s",
+            len(missing),
+            ", ".join(sorted(set(missing))),
+        )
+
+    return rendered

callva/livekit/core/__init__.py

@@ -0,0 +1,40 @@
+"""Shared call identity, per-job state, transport and logging.
+
+Modules in this package never import one another. They read and write the
+:class:`CallState` that lives here, keyed off the ambient LiveKit job, which is how
+configuration resolved by one module reaches another.
+"""
+
+from .envelope import ENVELOPE_KEY, DispatchEnvelope, parse
+from .identity import INBOUND, OUTBOUND, CallIdentity, Party, resolve, resolve_direction
+from .log import logger
+from .state import CallState, NoJobContext, context, ensure_identity
+from .state import state as call_state
+from .transport import WebhookTarget, post_file, post_json
+from .version import __version__
+
+# `state` deliberately stays bound to the submodule: re-exporting the function under that
+# name would shadow it, and every internal `from ..core import state` would silently get a
+# function instead of the module.
+
+__all__ = [
+    "ENVELOPE_KEY",
+    "INBOUND",
+    "OUTBOUND",
+    "CallIdentity",
+    "CallState",
+    "DispatchEnvelope",
+    "NoJobContext",
+    "Party",
+    "WebhookTarget",
+    "__version__",
+    "call_state",
+    "context",
+    "ensure_identity",
+    "logger",
+    "parse",
+    "post_file",
+    "post_json",
+    "resolve",
+    "resolve_direction",
+]

callva/livekit/core/env.py

@@ -0,0 +1,35 @@
+"""Environment variables.
+
+Names describe the job, not the vendor. This is an extension to the LiveKit Agents SDK;
+that a URL happens to point at CallVA is configuration, not identity.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def get(name: str, default: str | None = None) -> str | None:
+    """Read an environment variable, treating a blank value as unset."""
+    value = os.environ.get(name)
+    if value is None:
+        return default
+    value = value.strip()
+    return value or default
+
+
+def get_bool(name: str, default: bool = False) -> bool:
+    value = get(name)
+    if value is None:
+        return default
+    return value.lower() in ("1", "true", "yes", "on")
+
+
+def get_float(name: str, default: float | None = None) -> float | None:
+    value = get(name)
+    if value is None:
+        return default
+    try:
+        return float(value)
+    except ValueError:
+        return default

callva/livekit/core/envelope.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from .log import logger
+
+ENVELOPE_KEY = "callva"
+
+_OWN_KEYS = frozenset({"call_id", "direction", "config", "config_url", "webhook"})
+
+
+@dataclass
+class DispatchEnvelope:
+    """What the dispatcher said about this call, read from ``ctx.job.metadata``.
+
+    Job metadata is a free-form string that the host application may already be using for
+    its own purposes, so the envelope is looked for under a ``callva`` key first. A
+    top-level object is only claimed when it carries keys that are unambiguously ours.
+    """
+
+    call_id: str | None = None
+    direction: str | None = None
+    config: dict[str, Any] | None = None
+    config_url: str | None = None
+    webhook: dict[str, Any] | None = None
+    raw: str | None = None
+    """The original metadata string, forwarded to a config endpoint unchanged."""
+
+    extra: dict[str, Any] = field(default_factory=dict)
+    """Everything else found alongside our keys."""
+
+    @property
+    def empty(self) -> bool:
+        return not any((self.call_id, self.direction, self.config, self.config_url, self.webhook))
+
+
+def parse(metadata: str | None) -> DispatchEnvelope:
+    """Parse job metadata into an envelope. Never raises."""
+    if not metadata or not metadata.strip():
+        return DispatchEnvelope()
+
+    try:
+        decoded = json.loads(metadata)
+    except (ValueError, TypeError):
+        logger.debug("job metadata is not JSON, no dispatch envelope taken from it")
+        return DispatchEnvelope(raw=metadata)
+
+    if not isinstance(decoded, dict):
+        return DispatchEnvelope(raw=metadata)
+
+    scoped = decoded.get(ENVELOPE_KEY)
+    if isinstance(scoped, dict):
+        body = scoped
+    elif _OWN_KEYS & decoded.keys():
+        body = decoded
+    else:
+        return DispatchEnvelope(raw=metadata)
+
+    def _dict(key: str) -> dict[str, Any] | None:
+        value = body.get(key)
+        return value if isinstance(value, dict) else None
+
+    def _str(key: str) -> str | None:
+        value = body.get(key)
+        return value.strip() or None if isinstance(value, str) else None
+
+    return DispatchEnvelope(
+        call_id=_str("call_id"),
+        direction=_str("direction"),
+        config=_dict("config"),
+        config_url=_str("config_url"),
+        webhook=_dict("webhook"),
+        raw=metadata,
+        extra={k: v for k, v in body.items() if k not in _OWN_KEYS},
+    )

callva/livekit/core/identity.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from . import env
+from .envelope import DispatchEnvelope
+from .log import logger
+
+INBOUND = "inbound"
+OUTBOUND = "outbound"
+
+SIP_PREFIX = "sip."
+
+_REMOTE_NUMBER_KEYS = ("phoneNumber", "phone_number")
+_LOCAL_NUMBER_KEYS = ("trunkPhoneNumber", "trunk_phone_number")
+
+
+@dataclass(frozen=True)
+class Party:
+    """One end of the call."""
+
+    number: str | None = None
+    identity: str | None = None
+    name: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"number": self.number, "identity": self.identity, "name": self.name}
+
+
+@dataclass
+class CallIdentity:
+    """Who is on this call, which way it goes, and what to call it.
+
+    Derived by the package. Nothing here is taken from the call's configuration: an
+    inbound call is described by the SIP envelope it arrived in, and a dispatched call by
+    what the dispatcher declared.
+    """
+
+    id: str
+    direction: str
+    from_party: Party
+    to_party: Party
+    sip: dict[str, Any] | None = None
+    started_at: float = 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "direction": self.direction,
+            "from": self.from_party.to_dict(),
+            "to": self.to_party.to_dict(),
+        }
+
+
+def sip_attributes(attributes: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    """Collect the ``sip.*`` participant attributes into a nested dict, unchanged.
+
+    ``sip.twilio.callSid`` becomes ``{"twilio": {"callSid": ...}}``. Keys are never
+    renamed and nothing is dropped, so attributes LiveKit adds later flow through without
+    a release here.
+    """
+    if not attributes:
+        return None
+
+    tree: dict[str, Any] = {}
+    for key, value in attributes.items():
+        if not key.startswith(SIP_PREFIX):
+            continue
+        parts = key[len(SIP_PREFIX) :].split(".")
+        cursor = tree
+        for part in parts[:-1]:
+            existing = cursor.get(part)
+            if not isinstance(existing, dict):
+                existing = {}
+                cursor[part] = existing
+            cursor = existing
+        cursor[parts[-1]] = value
+
+    return tree or None
+
+
+def _first(source: Mapping[str, Any], keys: tuple[str, ...]) -> str | None:
+    for key in keys:
+        value = source.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def resolve_direction(envelope: DispatchEnvelope, override: str | None = None) -> str:
+    """Resolve the call direction. Never inferred from participant state.
+
+    The dispatcher's declaration wins, then an explicit override or ``CALL_DIRECTION``,
+    then inbound. The default is sound rather than a guess: an outbound call is always
+    placed by someone, so it always arrives with dispatch metadata.
+    """
+    for candidate in (envelope.direction, override, env.get("CALL_DIRECTION")):
+        if not candidate:
+            continue
+        value = candidate.strip().lower()
+        if value in (INBOUND, OUTBOUND):
+            return value
+        logger.warning(
+            "ignoring unknown call direction %r, expected inbound or outbound", candidate
+        )
+
+    return INBOUND
+
+
+def resolve(
+    *,
+    envelope: DispatchEnvelope,
+    participant: Any | None = None,
+    direction: str | None = None,
+    started_at: float | None = None,
+) -> CallIdentity:
+    """Build the call identity from the dispatch envelope and the SIP envelope."""
+    resolved_direction = resolve_direction(envelope, direction)
+
+    attributes = getattr(participant, "attributes", None) or {}
+    sip = sip_attributes(attributes)
+
+    remote = Party(
+        number=_first(sip, _REMOTE_NUMBER_KEYS) if sip else None,
+        identity=getattr(participant, "identity", None) or None,
+        name=getattr(participant, "name", None) or None,
+    )
+    local = Party(number=_first(sip, _LOCAL_NUMBER_KEYS) if sip else None)
+
+    if resolved_direction == OUTBOUND:
+        from_party, to_party = local, remote
+    else:
+        from_party, to_party = remote, local
+
+    return CallIdentity(
+        id=envelope.call_id or uuid.uuid4().hex,
+        direction=resolved_direction,
+        from_party=from_party,
+        to_party=to_party,
+        sip=sip,
+        started_at=started_at if started_at is not None else time.time(),
+    )

callva/livekit/core/log.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("callva.livekit")
+"""The package logger.
+
+The package never sets a level, never attaches a handler and never touches the root
+logger. Whatever the host application has configured is what applies.
+"""