callva-livekit 0.1.0__tar.gz

callva_livekit-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+.DS_Store

callva_livekit-0.1.0/DESIGN.md

@@ -0,0 +1,346 @@
+# Design
+
+Decided contracts for `callva-livekit`. This is the reference the implementation
+follows; every number and API name here was verified against `livekit-agents` 1.5.7,
+`livekit-protocol` 1.1.7 and the `livekit/livekit` server sources.
+
+## 1. Scope
+
+Two independent capabilities that any LiveKit agent can opt into:
+
+- **Webhook** — emit a `call.started` webhook when the call goes live and a `call.ended`
+  webhook when it finishes, carrying the transcript, usage, recording and session data.
+- **Config** — resolve per-call configuration (prompt, greeting, variables) before the
+  session starts, from agent dispatch metadata or from an external endpoint.
+
+Each is armed by its own call. Installing the package activates nothing.
+
+### Non-goals
+
+- **Dispatch.** Placing a call is a server-API conversation between the platform and
+  LiveKit, and it happens before the agent process exists. Out of scope by construction.
+- **Provider configuration.** The public config schema carries no speech-stack, model or
+  voice settings. Vendor-specific material travels in the opaque `extra` field.
+- **Call lifecycle management** (duration caps, reminder prompts, transfer). A later
+  module; see §13.
+
+## 2. Names
+
+The distribution is `callva-livekit` and it imports as `callva.livekit`, following the
+convention LiveKit itself uses: `livekit-agents` imports as `livekit.agents`,
+`livekit-plugins-openai` as `livekit.plugins.openai`. The distribution name is the import
+path with dashes, so `pip install` and `import` never disagree. A later split keeps the
+property: `callva-livekit-webhook` would import as `callva.livekit.webhook`.
+
+Environment variables carry no vendor prefix — `WEBHOOK_URL`, `CONFIG_URL`,
+`RECORDING_S3_BUCKET`. This is an extension to the Agents SDK; that a URL points at CallVA
+is configuration, not identity. The same reasoning applies to the delivery headers
+(`X-Webhook-Signature`, `X-Webhook-Event`) and to the event names themselves
+(`call.started`, `call.ended`).
+
+The one deliberate exception is the `callva` key inside `ctx.job.metadata`. That key exists
+to keep our block from colliding with the host application's own metadata, and being
+distinctive is the entire job it does. A generic name there would defeat it.
+
+## 3. Layout
+
+```
+callva/                     PEP 420 namespace, no __init__.py
+  livekit/                  PEP 420 namespace, no __init__.py
+    core/                   identity, per-job state, HTTP transport, logging
+    config/                 config resolution and templating
+    webhook/                event delivery, recording upload
+```
+
+One distribution, three modules. Because `callva` and `callva.livekit` are namespace
+packages, a module can later be split into its own distribution without changing a single
+user-facing import. That makes the single-distribution choice reversible; starting with
+three and merging would not be.
+
+`core` holds what more than one module needs: the resolved call identity, the resolved
+config, the HTTP client and the logger. Modules never import each other — they read and
+write the per-job state that `core` owns, keyed off the ambient `JobContext`. This is how
+configuration reaches future modules without being passed by hand.
+
+## 4. Integration surface
+
+Primary form, documented first:
+
+```python
+from livekit.agents import AgentServer, AgentSession
+from callva.livekit import config as callva_config
+from callva.livekit import webhook as callva_webhook
+
+server = AgentServer()
+
+@server.rtc_session(on_session_end=callva_webhook.on_session_end)
+async def entrypoint(ctx):
+    await ctx.connect()
+    cfg = await callva_config.load()
+    session = AgentSession(...)
+    callva_webhook.attach(session)
+    await session.start(agent=Agent(instructions=cfg.prompt), room=ctx.room)
+```
+
+No monkey-patching. Neither call takes a `JobContext`: both resolve it through the public
+`livekit.agents.get_job_context()`, a contextvar set for the duration of the job.
+
+Minimal form, for agents still built on `WorkerOptions`, where `on_session_end` is not
+reachable:
+
+```python
+cfg = await callva_config.load()
+callva_webhook.attach(session)
+```
+
+`attach()` falls back to `ctx.add_shutdown_callback()`. That path works, but see §5 for
+why it is the secondary recommendation.
+
+Nothing is substituted behind the caller's back. `load()` returns an object; using the
+prompt is the caller's decision.
+
+## 5. Lifecycle and ordering
+
+Verified in `livekit/agents/ipc/job_proc_lazy_main.py:360-411`:
+
+```
+shutdown signalled
+entrypoint task finishes                 (15s grace, then cancelled)
+session.aclose()                         RecorderIO finalizes the OGG
+on_session_end(ctx)                      ← primary hook, budget = session_end_timeout (300s)
+ctx._on_session_end()                    SDK uploads its own report to LiveKit Cloud
+room.disconnect()
+shutdown callbacks                       ← fallback hook, gathered concurrently
+_on_cleanup()                            session directory deleted
+```
+
+The end webhook and the recording upload run in `on_session_end`. Reasons:
+
+- **Budget.** `session_end_timeout` defaults to 300s. Shutdown callbacks are bounded by
+  `shutdown_process_timeout` (default **10s**), after which the supervisor sends a dump
+  signal and kills the process (`ipc/supervised_proc.py:279-301`). A recording upload does
+  not reliably fit in 10s.
+- **Ordering.** It runs before `room.disconnect()`, so room and participant state are
+  still readable.
+- `shutdown_process_timeout` is set by the host application when it builds the worker. The
+  plugin runs inside the job process and cannot raise it.
+
+When `attach()` has to use the fallback path it logs one warning at WARNING level naming
+the risk and both fixes. Silent truncation is not acceptable here.
+
+`ctx.make_session_report()` raises if `RecorderIO` is still recording. Both hook points sit
+after `session.aclose()`, so both are safe.
+
+## 6. Call identity
+
+Derived by the package, not supplied by the config.
+
+- **`call_id`** — assigned by the package as a UUID, stable across both webhooks, and used
+  as the object key for the recording and transcript. Overridable through the dispatch
+  metadata envelope when the platform wants to pin its own identifier.
+- **`direction`** — resolved as: the dispatch metadata envelope → an explicit argument or
+  environment variable → `"inbound"`. The default is sound rather than a guess: an outbound
+  call is always dispatched by someone, so it always carries metadata. Never inferred from
+  participant state.
+- **`from` / `to`** — read from the SIP participant attributes: `sip.phoneNumber` is the
+  remote party, `sip.trunkPhoneNumber` the local one, swapped by direction. Absent for
+  non-SIP sessions.
+
+The full `sip.*` attribute set is forwarded verbatim; it is never reshaped.
+
+## 7. Config
+
+### Channel
+
+**Agent dispatch metadata only**, read as `ctx.job.metadata`. Room metadata is not used.
+
+`job.metadata` is available in the entrypoint before `ctx.connect()`, is addressed to one
+specific dispatch rather than shared across the room, is capped at 512 KiB, and — unlike
+room metadata and participant attributes — is delivered over the worker's own websocket and
+is **not broadcast to other participants**. Putting a prompt in room metadata exposes it to
+every client in the room, including browsers.
+
+Requires explicit dispatch: the worker must have `agent_name` set. With automatic dispatch
+`job.metadata` arrives empty.
+
+### Envelope
+
+Job metadata is a free-form string the host application may already be using. The envelope
+is therefore looked for under a ``callva`` key, and a top-level object is only claimed when
+it carries keys that are unambiguously ours:
+
+```json
+{ "callva": { "call_id": "…", "direction": "outbound",
+              "config": { }, "config_url": "…", "webhook": { } } }
+```
+
+Metadata that is not JSON, or is JSON that belongs to someone else, is left alone and
+forwarded to a configuration endpoint unchanged.
+
+### Resolution order
+
+```
+job.metadata carries a body      → use it, returns before connect()
+job.metadata carries a pointer   → follow it
+job.metadata empty, env URL set  → follow that
+otherwise                        → no config
+```
+
+A pointer is an endpoint, or a local file: `file://…` or a plain path, distinguished by the
+absence of a scheme. A file is read as it is — no request, no waiting — which makes it the
+shortest development loop. It cannot answer per caller, so it is not the production channel.
+
+Only the endpoint path needs the SIP envelope to build its request, so only it awaits the
+participant. `load()` returns immediately for a body in metadata and for a file, and after
+participant join for an endpoint. Documented, not hidden.
+
+### Request payload
+
+The request is itself the question — the responder decides what to return from it. This is
+the main inbound scenario: choose the agent by the number that was dialled.
+
+```json
+{
+  "room": "...", "job_id": "...", "dispatch_id": "...", "agent_name": "...",
+  "direction": "inbound",
+  "from": { "number": "..." }, "to": { "number": "..." },
+  "sip": { ... },
+  "participant_identity": "...",
+  "metadata": "<raw job.metadata, if any>"
+}
+```
+
+### Response
+
+```json
+{
+  "prompt":    "...",
+  "greeting":  "...",
+  "variables": { "name": "Anna", "attempt": 2, "vip": true },
+  "webhook":   { "url": "...", "secret": "..." },
+  "extra":     { }
+}
+```
+
+Five fields, deliberately. `language` is a variable. Duration caps and voice belong to
+other concerns. Call identity is derived, not declared.
+
+`webhook` here overrides the environment, because multi-tenancy is resolved per call while
+the environment is a deployment default.
+
+`extra` is opaque and never interpreted.
+
+### Templating
+
+`{{ name }}` placeholders are substituted into **both** `prompt` and `greeting` from
+`variables`. A missing key is left in place verbatim and logged at WARNING. Rendering never
+raises and never evaluates code. The object exposes the raw and the rendered form of each.
+
+JSON types in `variables` are preserved — a number stays a number — and typed accessors are
+provided. Substitution uses the string form at render time.
+
+### Failure
+
+A failed or non-2xx config request **terminates the call** with the reason logged. An agent
+without its prompt is a broken call either way; failing loudly beats failing quietly. The
+response status and body are logged. Overridable for callers who prefer to continue.
+
+## 8. Webhooks
+
+One thin envelope; everything LiveKit produces is nested verbatim so that new SDK fields
+reach consumers without a release here.
+
+```json
+{
+  "event": "call.started",
+  "id": "<idempotency key>",
+  "timestamp": 0,
+  "call": {
+    "id": "...", "direction": "inbound",
+    "from": { "number": "..." }, "to": { "number": "..." },
+    "started_at": 0, "ended_at": 0, "duration": 0, "status": "..."
+  },
+  "livekit": {
+    "room": {}, "job": {}, "participant": {}, "sip": {},
+    "session_report": {}
+  },
+  "recording": {},
+  "tags": {}
+}
+```
+
+`livekit.session_report` is `ctx.make_session_report().to_dict()` unmodified — chat history
+with timestamps, per-provider usage, recorded events, session options, SDK version. The key
+is present on every `call.ended`, null when the report could not be built, so a consumer
+never has to handle two shapes of the same event. It is absent from `call.started`.
+
+`tags` carries `ctx.tagger` outcome and tags.
+
+Delivery: `POST`, HMAC signature over timestamp and body when a secret is configured, an
+idempotency key per event, retries on 5xx and network errors with backoff, fail-fast on 4xx.
+
+## 9. Recording
+
+The SDK records locally to OGG/Opus, stereo, via PyAV, then reads the whole file into memory
+and sends it to LiveKit Cloud in a single multipart POST with no chunking and no size guard
+(`telemetry/traces.py:406`). Roughly 700 KB per minute at the default bitrate.
+
+This package:
+
+- **Default: object storage.** One S3-compatible client, configurable endpoint, so S3 and
+  R2 are the same path. Recording and transcript are written under the same `call_id`.
+  Requires the `s3` extra.
+- **Fallback: multipart to the webhook endpoint**, for zero-configuration use. No size
+  ceiling, matching the SDK's own behaviour.
+- The webhook is posted before the upload, so the call is closed out with a terminal status
+  even if the process dies mid-upload.
+
+## 10. Logging
+
+Module-named loggers obtained from `logging.getLogger`. The package never sets a level,
+never attaches a handler and never configures the root logger. Whatever the host has
+configured is what applies.
+
+## 11. Constraints worth knowing
+
+- **Metadata limits** are server config, not constants: 512 KiB for metadata, 64 KiB for
+  attributes summed across keys and values. Servers older than 2026-06-17 cap both at
+  64000 bytes. SIP dispatch rules are not size-checked at all — an oversized rule saves
+  silently and fails later when the participant joins.
+- **`room_config`** on a SIP dispatch rule applies only when the SIP participant creates the
+  room. Against an existing room it is silently ignored. Use a unique room per call or an
+  explicit `CreateAgentDispatch`.
+- **`AgentServer.update_options()`** declares `shutdown_process_timeout` and
+  `session_end_timeout` with plain defaults instead of sentinels while testing them with
+  `is_given`, so any call to it silently resets both to 10s and 300s.
+- **`RoomAgentDispatch.attributes`** exists in the protocol on main but not in 1.1.7. Only
+  `metadata` is safe to rely on.
+- **`core.state` must stay bound to the submodule.** Re-exporting `state()` from
+  `core/__init__.py` under that name shadows it, and every internal
+  `from ..core import state` then binds a function instead — a failure that only surfaces
+  at call time. The public alias is `core.call_state`.
+- **Shutdown callbacks are gathered concurrently**, not run in registration order. Nothing
+  may depend on one running before another.
+- **A simulated job — console mode — has a mock room nobody joins**, so the participant
+  entrypoint never fires. `attach()` detects it through `ctx.is_fake_job()` and reports the
+  call as started when the session starts instead. Such a call has no parties and no SIP
+  envelope.
+
+## 12. Versioning
+
+Semantic versioning, not CalVer. A date says when a release happened; it says nothing about
+whether a receiver written against the last one still parses this one, and that question is
+the entire product here. LiveKit itself is on SemVer, and this package declares a range
+against it, so the schemes match.
+
+The bump follows a rule rather than taste: additive payload fields and fixes are patches,
+anything a receiver could choke on is a minor. In `0.x` the minor is the breaking position —
+`^0.1.0` admits `0.1.x` and not `0.2.0` — so `0.2.0` is not a big release, it is one the
+consumers need to hear about.
+
+## 13. Later
+
+- Call lifecycle management — duration caps, reminder prompts, transfer — as a fourth
+  module reading the same `core` state.
+- Splitting a module into its own distribution, if dependencies diverge. Import paths are
+  already shaped for it.

callva_livekit-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.5
+Name: callva-livekit
+Version: 0.1.0
+Summary: Drop-in call webhooks and per-call configuration for any LiveKit agent.
+Project-URL: Homepage, https://github.com/callva-io/callva-livekit
+Project-URL: Source, https://github.com/callva-io/callva-livekit
+Author: CallVA
+License-Expression: Apache-2.0
+Keywords: agents,livekit,sip,telephony,voice,webhook
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: livekit-agents>=1.5.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == 's3'
+Description-Content-Type: text/markdown
+
+# callva-livekit
+
+Drop-in call webhooks and per-call configuration for any LiveKit agent.
+
+Two things most voice agents need and the LiveKit SDK does not provide: a webhook when a
+call starts and ends, and a way to get the prompt for *this* call from somewhere other than
+your source code.
+
+Both are opt-in. Installing the package activates nothing, patches nothing, and changes
+nothing about how your session behaves.
+
+## Install
+
+```bash
+pip install callva-livekit          # webhooks + config
+pip install callva-livekit[s3]      # + recording upload to S3 or R2
+```
+
+## Use
+
+```python
+from livekit.agents import Agent, AgentServer, AgentSession
+from callva.livekit import config as callva_config
+from callva.livekit import webhook as callva_webhook
+
+server = AgentServer()
+
+@server.rtc_session(agent_name="my-agent", on_session_end=callva_webhook.on_session_end)
+async def entrypoint(ctx):
+    await ctx.connect()
+
+    config = await callva_config.load()
+
+    session = AgentSession(...)
+    callva_webhook.attach(session)
+
+    await session.start(agent=Agent(instructions=config.prompt), room=ctx.room, record=True)
+    await session.generate_reply(instructions=config.greeting)
+```
+
+Neither call takes a `JobContext` — it comes from the SDK's own contextvar. `load()` hands
+you an object; what you do with the prompt is your decision.
+
+A complete runnable agent is in [examples/agent.py](examples/agent.py), with a local
+receiver that prints what arrives in [examples/receiver.py](examples/receiver.py).
+
+## What arrives
+
+`call.started` when someone is on the other end, `call.ended` when it is over.
+
+```json
+{
+  "event": "call.ended",
+  "id": "8f1c…:call.ended:1757...",
+  "timestamp": 1757600000.12,
+  "call": {
+    "id": "8f1c…",
+    "direction": "inbound",
+    "from": { "number": "+37255512345", "identity": "sip_+37255512345", "name": null },
+    "to":   { "number": "+3726001234", "identity": null, "name": null },
+    "started_at": 1757599940.5, "ended_at": 1757600000.1, "duration": 59.6,
+    "status": "completed"
+  },
+  "livekit": {
+    "room": { "name": "call-1", "sid": "RM_…", "metadata": null },
+    "job":  { "id": "AJ_…", "dispatch_id": "AD_…", "agent_name": "my-agent", "…": "…" },
+    "participant": { "identity": "sip_…", "attributes": { "sip.callID": "…" } },
+    "sip":  { "callID": "…", "phoneNumber": "…", "twilio": { "callSid": "…" } },
+    "session_report": { "chat_history": {}, "usage": [], "options": {}, "…": "…" }
+  },
+  "recording": { "url": "https://cdn.example/8f1c….ogg" },
+  "tags": { "tags": ["lk.success"], "outcome": "success", "reason": null }
+}
+```
+
+Everything LiveKit produces is nested under `livekit` **verbatim** — including
+`session_report`, which is `ctx.make_session_report().to_dict()` untouched: full chat
+history with timestamps, per-provider token usage, recorded events, session options. A
+field the SDK adds tomorrow reaches you without a release here.
+
+The `call` block is the only thing reshaped, because it is the only thing LiveKit does not
+model: a stable id across both events, a direction, and a `from` and a `to`.
+
+Requests carry `X-Webhook-Idempotency-Key`, and `X-Webhook-Signature` when a secret is set —
+`sha256` HMAC over `{timestamp}.{body}`, with `X-Webhook-Timestamp` alongside. Delivery
+retries on 5xx and network errors and fails fast on 4xx.
+
+## Configuration for a call
+
+Configuration reaches the agent through **agent dispatch metadata**, read as
+`ctx.job.metadata`:
+
+```json
+{ "callva": { "call_id": "…", "direction": "outbound", "config": { "prompt": "…" } } }
+```
+
+Put a `config_url` there instead of a `config`, or set `CONFIG_URL`, and the agent
+follows that instead. The request is the question — it carries who is calling, which number
+they reached and the whole SIP envelope — so the endpoint can answer "this number belongs to
+that customer, here is their prompt". That is the inbound case in one hop.
+
+A pointer can also be a local file — `file:///etc/agent.json` or a plain `./agent.json`. It
+is read as it is, with no request and no waiting for anyone to join, which makes it the
+shortest development loop there is. It cannot answer per caller, so it is not the production
+channel.
+
+The response:
+
+```json
+{
+  "prompt":    "You are speaking with {{ name }}.",
+  "greeting":  "Hi {{ name }}, how can I help?",
+  "variables": { "name": "Anna", "attempt": 2, "vip": true },
+  "webhook":   { "url": "https://tenant.example/hook", "secret": "…" },
+  "extra":     { "anything": "you like" }
+}
+```
+
+`{{ name }}` is substituted into both `prompt` and `greeting`. A placeholder with no
+variable is left exactly as it was and logged — one missing key must not take down a call
+that is already ringing. JSON types survive: `config.variables.get_int("attempt")` is `2`.
+`extra` is never interpreted.
+
+`webhook` in the response overrides the environment, which is what lets one worker serve
+many tenants.
+
+When configuration cannot be resolved the call is **terminated** and the reason logged. An
+agent without its prompt is a broken call either way. Pass `on_error="continue"` if you
+would rather carry on.
+
+Room metadata is deliberately not used as a channel: it is broadcast to every participant
+in the room, so a prompt placed there is readable by any connected client.
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `WEBHOOK_URL` | Where call events are sent |
+| `WEBHOOK_SECRET` | HMAC signing secret |
+| `WEBHOOK_TIMEOUT` | Per-attempt timeout, seconds (default 30) |
+| `CONFIG_URL` | Endpoint asked for per-call configuration |
+| `CONFIG_API_KEY` | Sent to it as a bearer token |
+| `CONFIG_TIMEOUT` | Per-attempt timeout, seconds (default 10) |
+| `CALL_DIRECTION` | Default direction when nothing declares one |
+| `RECORDING_S3_BUCKET` | Enables recording upload |
+| `RECORDING_S3_ENDPOINT_URL` | Set this for R2 or any S3-compatible store |
+| `RECORDING_S3_REGION`, `RECORDING_S3_ACCESS_KEY_ID`, `RECORDING_S3_SECRET_ACCESS_KEY` | Credentials |
+| `RECORDING_S3_PUBLIC_BASE_URL` | Turns the object key into the URL sent in the webhook |
+| `RECORDING_S3_PREFIX` | Key prefix inside the bucket |
+
+Every value has a constructor argument that takes precedence.
+
+## Recording
+
+With a bucket configured, the recording and the session report are written under the same
+call id — `<call_id>.ogg` and `<call_id>.json` — and the webhook carries the URL, which is
+known before the bytes move. Needs `record=True` on `session.start()` and the codecs extra
+(`pip install "livekit-agents[codecs]"`).
+
+Without a bucket, and only if a webhook target is set, the recording follows the webhook as
+a multipart `call.recording` request. Convenient for getting started; object storage is the
+answer for long calls.
+
+The `call.ended` webhook is always sent **before** the upload, so a call is closed out with
+a terminal status even if the process does not survive the transfer.
+
+## Versioning
+
+Semantic versioning, and the compatibility promise is about **what a receiver has to
+parse**, not about the size of the diff:
+
+- **0.1.x** — fixes, and fields *added* to a payload. Adding is not breaking: a receiver
+  ignores keys it does not know, and because everything LiveKit produces is nested verbatim,
+  fields the SDK adds arrive without a release here at all.
+- **0.2.0** — anything a receiver could choke on: a field renamed or removed, an event name
+  changed, a header changed, an environment variable renamed, a public function changed.
+- **1.0.0** — when the contract is worth freezing.
+
+In `0.x` the digits are shifted one place: the middle number is the breaking one, which is
+what `^0.1.0` means to every resolver. So a `0.2.0` here is not a large release — it is a
+release that someone's receiver has to be told about.
+
+## Two things worth knowing
+
+**Your agent needs `agent_name` set and explicit dispatch.** With automatic dispatch
+`job.metadata` arrives empty, and nothing can be addressed to this call.
+
+**If you cannot use `on_session_end`** — you are still on `WorkerOptions` — `attach()` falls
+back to a shutdown callback and says so in the log. That path is bounded by
+`shutdown_process_timeout`, 10 seconds by default, after which the worker kills the
+process mid-upload. Raise it, or move to `AgentServer`.
+
+## License
+
+Apache-2.0