livekit-msteams-bridge 0.1.0__tar.gz

livekit_msteams_bridge-0.1.0/.env.example

@@ -0,0 +1,35 @@
+# --- required ---
+WORKER_SHARED_SECRET=shared-secret-from-standin-pairing
+LIVEKIT_URL=wss://your-project.livekit.cloud
+LIVEKIT_API_KEY=API...
+LIVEKIT_API_SECRET=...
+
+# --- agent dispatch ---
+# Named agent for explicit dispatch (recommended). Must equal the agent_name
+# your worker registers with. Unset = automatic dispatch (prototype-only).
+LIVEKIT_AGENT_NAME=teams-voice-agent
+#LIVEKIT_ROOM_PREFIX=msteams-
+#LIVEKIT_DELETE_ROOM_ON_END=true
+
+# --- listener ---
+#PORT=8080
+#BIND=0.0.0.0
+# Native TLS (wss). Leave unset when a tunnel/ingress terminates TLS for you.
+#TLS_CERT_PATH=/path/cert.pem
+#TLS_KEY_PATH=/path/key.pem
+
+# --- call governor ---
+#MAX_CALL_MINUTES=10
+#GOODBYE_TEXT=I'm sorry, we've reached the time limit for this call. Thank you for calling, goodbye!
+#GOODBYE_GRACE_MS=8000
+
+# --- hardening ---
+#HMAC_FRESHNESS_MS=60000
+#MAX_CONNECTIONS=64
+#MAX_CONNECTIONS_PER_IP=
+#PRE_START_TIMEOUT_MS=10000
+#WORKER_IDLE_TIMEOUT_MS=90000
+#TRUST_PROXY_XFF=false
+
+# --- logging ---
+#LOG_LEVEL=info

livekit_msteams_bridge-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.env
+.pytest_cache/
+.ruff_cache/
+.coverage

livekit_msteams_bridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alaaeldin Elhenawy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

livekit_msteams_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: livekit-msteams-bridge
+Version: 0.1.0
+Summary: Put a LiveKit Agent on Microsoft Teams voice/video calls. Terminates the StandIn media bridge wire protocol on one side and a LiveKit room on the other: per-call rooms, explicit agent dispatch, 16 kHz PCM relay, data-topic context, call governors.
+Project-URL: Homepage, https://komaa-com.github.io/livekit-msteams-bridge-py/
+Project-URL: Documentation, https://komaa-com.github.io/livekit-msteams-bridge-py/
+Project-URL: StandIn docs, https://docs.komaa.com/livekit/installation
+Project-URL: Repository, https://github.com/komaa-com/livekit-msteams-bridge-py
+Project-URL: Issues, https://github.com/komaa-com/livekit-msteams-bridge-py/issues
+Author-email: Alaaeldin Elhenawy <alaamh@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,avatar,bridge,livekit,microsoft-teams,telephony,voice,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.10
+Requires-Dist: aiohttp<4,>=3.9
+Requires-Dist: livekit-api<2,>=1.2
+Requires-Dist: livekit<2,>=1.1
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# livekit-msteams-bridge (Python)
+
+Put a **LiveKit Agent** - including avatar agents - on **Microsoft Teams voice/video calls**.
+
+> PyPI package: **`livekit-msteams-bridge`** - the `-py` suffix is only in this repository's
+> name, to distinguish it from the [Node.js sibling repo](https://github.com/komaa-com/livekit-msteams-bridge).
+
+This is the Python sibling of [`@komaa/livekit-msteams-bridge`](https://www.npmjs.com/package/@komaa/livekit-msteams-bridge)
+(Node.js) - same wire contract, same environment variables, drop-in interchangeable behind the same
+`.env` file. It terminates the StandIn media bridge wire protocol on one side and a LiveKit room on
+the other:
+
+- **One room per call**: the bridge creates a fresh room, joins as a participant, and dispatches
+  your agent into it (explicit dispatch by `agent_name` - LiveKit's recommended model).
+- **No transcoding on our side**: the worker speaks 16 kHz mono PCM16 natively; the room side uses
+  the SDK's resampling `AudioSource`/`AudioStream`, so the bridge itself never transcodes.
+- **Agent integration without Teams code**: per-call metadata (`ctx.job.metadata` - caller name,
+  tenant, direction, AAD id when known) plus two data topics: `teams.context` (participants, DTMF,
+  recording state) and `teams.goodbye` (the governor's goodbye line to speak).
+- **Call governors**: a bridge-side hard time cap (the agent speaks the goodbye), plus the
+  StandIn-side governor.
+- **Hardened**: HMAC-signed upgrades with replay guard, connection caps, dead-peer detection,
+  graceful SIGTERM drain, Prometheus `/metrics`.
+
+[StandIn](https://standin.komaa.com) is the hosted media bridge that joins the Teams call and dials
+this bridge - you run no Teams media stack yourself.
+
+**Documentation**: [komaa-com.github.io/livekit-msteams-bridge-py](https://komaa-com.github.io/livekit-msteams-bridge-py/)
+(getting started, example walkthrough, agents and dispatch, configuration and library reference,
+wire protocol). Teams/StandIn setup lives at [docs.komaa.com](https://docs.komaa.com/livekit/installation).
+
+## Install
+
+```bash
+pip install livekit-msteams-bridge
+```
+
+Requires Python 3.10+.
+
+## Run
+
+```bash
+LIVEKIT_URL=wss://your-project.livekit.cloud \
+LIVEKIT_API_KEY=API... \
+LIVEKIT_API_SECRET=... \
+LIVEKIT_AGENT_NAME=teams-voice-agent \
+WORKER_SHARED_SECRET=... \
+livekit-msteams-bridge
+```
+
+A `.env` file in the working directory is loaded automatically (existing environment wins). The
+bridge listens on `ws://0.0.0.0:8080/voice/msteams/stream` by default; StandIn appends `/{callId}`
+per call. Expose the port with a tunnel and register the `wss://` URL as your identity's
+**Agent voice URL** in the StandIn dashboard.
+
+`LIVEKIT_AGENT_NAME` must equal the `agent_name` your worker registers with
+(`WorkerOptions(entrypoint_fnc=..., agent_name="teams-voice-agent")`). A mismatch is the classic
+silent failure: the room is created, the caller hears nothing, and the worker never gets a job.
+
+## Embed
+
+```python
+import asyncio
+from livekit_msteams_bridge import load_config, start_server
+
+async def main():
+    server = await start_server(load_config())
+    await asyncio.Event().wait()  # run until cancelled
+
+asyncio.run(main())
+```
+
+Tests can inject a fake room with the `connect_room` argument - see the test suite's
+`FakeRoomPort` for the shape.
+
+## Configuration
+
+Everything is environment variables; names are identical to the Node package.
+
+| Variable | Required | Default | Meaning |
+|---|---|---|---|
+| `WORKER_SHARED_SECRET` | yes | - | Must equal the shared secret from StandIn pairing (HMAC upgrade check). |
+| `LIVEKIT_URL` | yes | - | LiveKit server URL (`wss://<project>.livekit.cloud` or self-hosted). |
+| `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` | yes | - | Mint join tokens, dispatch agents, delete rooms. Server-side only. |
+| `LIVEKIT_AGENT_NAME` | no | - | Named agent for explicit dispatch (recommended). Unset = automatic dispatch (prototype-only). |
+| `LIVEKIT_ROOM_PREFIX` | no | `msteams-` | Room name prefix; the room is `{prefix}{callId}` (sanitized). |
+| `LIVEKIT_DELETE_ROOM_ON_END` | no | `true` | Delete the room at teardown so the agent job ends immediately (billing hygiene). |
+| `MAX_CALL_MINUTES` | no | `0` (off) | Bridge-side hard cap per call; on expiry the agent is asked to say goodbye, then the call ends. |
+| `GOODBYE_TEXT` / `GOODBYE_GRACE_MS` | no | (default line) / `8000` | Goodbye wording (sent on `teams.goodbye`) and playout grace. The call ends `GOODBYE_GRACE_MS` + a fixed 500 ms scheduling buffer after the goodbye request. |
+| `PORT` / `BIND` | no | `8080` / `0.0.0.0` | Listen port / bind address. |
+| `HMAC_FRESHNESS_MS` | no | `60000` | Two-sided freshness window: a timestamp up to 60 s in the past OR the future is accepted, and the replay guard holds a used handshake until the timestamp ages out. |
+| `MAX_CONNECTIONS` / `MAX_CONNECTIONS_PER_IP` | no | `64` / = total | Connection caps. |
+| `PRE_START_TIMEOUT_MS` | no | `10000` | Drop a worker that authenticates but never sends `session.start`. |
+| `WORKER_IDLE_TIMEOUT_MS` | no | `90000` | Dead-peer window (the worker heartbeats every 30 s). |
+| `TRUST_PROXY_XFF` | no | `false` | Trust the first `X-Forwarded-For` hop for the per-IP cap. |
+| `TLS_CERT_PATH` / `TLS_KEY_PATH` | no | - | Serve native TLS (`wss`). Otherwise front the plain WS with a TLS terminator. |
+| `LOG_LEVEL` | no | `info` | `debug` / `info` / `warn` / `error`. |
+
+## Endpoints
+
+- `GET /healthz` - liveness.
+- `GET /metrics` - Prometheus counters (calls, rejections, relayed/dropped frames).
+- `GET /{...}/{callId}` + WebSocket upgrade - the worker wire, HMAC-signed with
+  `X-OpenClawTeamsBridge-Timestamp` / `X-OpenClawTeamsBridge-Signature` over
+  `"{timestampMs}.{callId}"`.
+
+Notes for operators:
+
+- `/healthz` and `/metrics` are **unauthenticated** (only the WebSocket upgrade is HMAC-gated).
+  They expose no call content - just liveness and counters - but if you would rather not leak call
+  volumes, keep the port behind your ingress/tunnel rules.
+- Barge-in: interruption handling lives **inside your LiveKit agent session** (VAD, turn-taking),
+  exactly as for WebRTC callers; the room transport gives the bridge no interruption event to relay,
+  so the worker's own flush-on-silence smooths the tail end.
+- The bridge participant's join token has a fixed **6 h TTL**. Calls that should be allowed to run
+  longer than that need a re-join strategy; in practice set `MAX_CALL_MINUTES` well below it.
+- Inbound Teams **video** (`video.frame`) is not forwarded to the room in this version - the bot's
+  tile is rendered by the worker's own avatar. Publishing caller video as a room track is on the
+  roadmap.
+- The Docker image exposes port **8080** and does not remap `PORT`/`BIND` at the Docker layer; use
+  `-e PORT=... -p <host>:<port>` together if you change them.
+
+## Agent integration points
+
+Your agent needs no Teams-specific code, but three integration points are available:
+
+- **`agent_name`** in `WorkerOptions` - must match `LIVEKIT_AGENT_NAME` for explicit dispatch.
+- **`ctx.job.metadata`** (JSON) - per-call context: `source`, `caller_name`, `tenant_id`,
+  `call_direction`, and `user_id` (AAD id when Teams provides one).
+- **Data topics** - `teams.context` (participant count, DTMF, recording state) and `teams.goodbye`
+  (the governor's goodbye line; have your handler speak it and interrupt the current turn).
+
+## License
+
+MIT (c) Alaaeldin Elhenawy

livekit_msteams_bridge-0.1.0/README.md

@@ -0,0 +1,135 @@
+# livekit-msteams-bridge (Python)
+
+Put a **LiveKit Agent** - including avatar agents - on **Microsoft Teams voice/video calls**.
+
+> PyPI package: **`livekit-msteams-bridge`** - the `-py` suffix is only in this repository's
+> name, to distinguish it from the [Node.js sibling repo](https://github.com/komaa-com/livekit-msteams-bridge).
+
+This is the Python sibling of [`@komaa/livekit-msteams-bridge`](https://www.npmjs.com/package/@komaa/livekit-msteams-bridge)
+(Node.js) - same wire contract, same environment variables, drop-in interchangeable behind the same
+`.env` file. It terminates the StandIn media bridge wire protocol on one side and a LiveKit room on
+the other:
+
+- **One room per call**: the bridge creates a fresh room, joins as a participant, and dispatches
+  your agent into it (explicit dispatch by `agent_name` - LiveKit's recommended model).
+- **No transcoding on our side**: the worker speaks 16 kHz mono PCM16 natively; the room side uses
+  the SDK's resampling `AudioSource`/`AudioStream`, so the bridge itself never transcodes.
+- **Agent integration without Teams code**: per-call metadata (`ctx.job.metadata` - caller name,
+  tenant, direction, AAD id when known) plus two data topics: `teams.context` (participants, DTMF,
+  recording state) and `teams.goodbye` (the governor's goodbye line to speak).
+- **Call governors**: a bridge-side hard time cap (the agent speaks the goodbye), plus the
+  StandIn-side governor.
+- **Hardened**: HMAC-signed upgrades with replay guard, connection caps, dead-peer detection,
+  graceful SIGTERM drain, Prometheus `/metrics`.
+
+[StandIn](https://standin.komaa.com) is the hosted media bridge that joins the Teams call and dials
+this bridge - you run no Teams media stack yourself.
+
+**Documentation**: [komaa-com.github.io/livekit-msteams-bridge-py](https://komaa-com.github.io/livekit-msteams-bridge-py/)
+(getting started, example walkthrough, agents and dispatch, configuration and library reference,
+wire protocol). Teams/StandIn setup lives at [docs.komaa.com](https://docs.komaa.com/livekit/installation).
+
+## Install
+
+```bash
+pip install livekit-msteams-bridge
+```
+
+Requires Python 3.10+.
+
+## Run
+
+```bash
+LIVEKIT_URL=wss://your-project.livekit.cloud \
+LIVEKIT_API_KEY=API... \
+LIVEKIT_API_SECRET=... \
+LIVEKIT_AGENT_NAME=teams-voice-agent \
+WORKER_SHARED_SECRET=... \
+livekit-msteams-bridge
+```
+
+A `.env` file in the working directory is loaded automatically (existing environment wins). The
+bridge listens on `ws://0.0.0.0:8080/voice/msteams/stream` by default; StandIn appends `/{callId}`
+per call. Expose the port with a tunnel and register the `wss://` URL as your identity's
+**Agent voice URL** in the StandIn dashboard.
+
+`LIVEKIT_AGENT_NAME` must equal the `agent_name` your worker registers with
+(`WorkerOptions(entrypoint_fnc=..., agent_name="teams-voice-agent")`). A mismatch is the classic
+silent failure: the room is created, the caller hears nothing, and the worker never gets a job.
+
+## Embed
+
+```python
+import asyncio
+from livekit_msteams_bridge import load_config, start_server
+
+async def main():
+    server = await start_server(load_config())
+    await asyncio.Event().wait()  # run until cancelled
+
+asyncio.run(main())
+```
+
+Tests can inject a fake room with the `connect_room` argument - see the test suite's
+`FakeRoomPort` for the shape.
+
+## Configuration
+
+Everything is environment variables; names are identical to the Node package.
+
+| Variable | Required | Default | Meaning |
+|---|---|---|---|
+| `WORKER_SHARED_SECRET` | yes | - | Must equal the shared secret from StandIn pairing (HMAC upgrade check). |
+| `LIVEKIT_URL` | yes | - | LiveKit server URL (`wss://<project>.livekit.cloud` or self-hosted). |
+| `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` | yes | - | Mint join tokens, dispatch agents, delete rooms. Server-side only. |
+| `LIVEKIT_AGENT_NAME` | no | - | Named agent for explicit dispatch (recommended). Unset = automatic dispatch (prototype-only). |
+| `LIVEKIT_ROOM_PREFIX` | no | `msteams-` | Room name prefix; the room is `{prefix}{callId}` (sanitized). |
+| `LIVEKIT_DELETE_ROOM_ON_END` | no | `true` | Delete the room at teardown so the agent job ends immediately (billing hygiene). |
+| `MAX_CALL_MINUTES` | no | `0` (off) | Bridge-side hard cap per call; on expiry the agent is asked to say goodbye, then the call ends. |
+| `GOODBYE_TEXT` / `GOODBYE_GRACE_MS` | no | (default line) / `8000` | Goodbye wording (sent on `teams.goodbye`) and playout grace. The call ends `GOODBYE_GRACE_MS` + a fixed 500 ms scheduling buffer after the goodbye request. |
+| `PORT` / `BIND` | no | `8080` / `0.0.0.0` | Listen port / bind address. |
+| `HMAC_FRESHNESS_MS` | no | `60000` | Two-sided freshness window: a timestamp up to 60 s in the past OR the future is accepted, and the replay guard holds a used handshake until the timestamp ages out. |
+| `MAX_CONNECTIONS` / `MAX_CONNECTIONS_PER_IP` | no | `64` / = total | Connection caps. |
+| `PRE_START_TIMEOUT_MS` | no | `10000` | Drop a worker that authenticates but never sends `session.start`. |
+| `WORKER_IDLE_TIMEOUT_MS` | no | `90000` | Dead-peer window (the worker heartbeats every 30 s). |
+| `TRUST_PROXY_XFF` | no | `false` | Trust the first `X-Forwarded-For` hop for the per-IP cap. |
+| `TLS_CERT_PATH` / `TLS_KEY_PATH` | no | - | Serve native TLS (`wss`). Otherwise front the plain WS with a TLS terminator. |
+| `LOG_LEVEL` | no | `info` | `debug` / `info` / `warn` / `error`. |
+
+## Endpoints
+
+- `GET /healthz` - liveness.
+- `GET /metrics` - Prometheus counters (calls, rejections, relayed/dropped frames).
+- `GET /{...}/{callId}` + WebSocket upgrade - the worker wire, HMAC-signed with
+  `X-OpenClawTeamsBridge-Timestamp` / `X-OpenClawTeamsBridge-Signature` over
+  `"{timestampMs}.{callId}"`.
+
+Notes for operators:
+
+- `/healthz` and `/metrics` are **unauthenticated** (only the WebSocket upgrade is HMAC-gated).
+  They expose no call content - just liveness and counters - but if you would rather not leak call
+  volumes, keep the port behind your ingress/tunnel rules.
+- Barge-in: interruption handling lives **inside your LiveKit agent session** (VAD, turn-taking),
+  exactly as for WebRTC callers; the room transport gives the bridge no interruption event to relay,
+  so the worker's own flush-on-silence smooths the tail end.
+- The bridge participant's join token has a fixed **6 h TTL**. Calls that should be allowed to run
+  longer than that need a re-join strategy; in practice set `MAX_CALL_MINUTES` well below it.
+- Inbound Teams **video** (`video.frame`) is not forwarded to the room in this version - the bot's
+  tile is rendered by the worker's own avatar. Publishing caller video as a room track is on the
+  roadmap.
+- The Docker image exposes port **8080** and does not remap `PORT`/`BIND` at the Docker layer; use
+  `-e PORT=... -p <host>:<port>` together if you change them.
+
+## Agent integration points
+
+Your agent needs no Teams-specific code, but three integration points are available:
+
+- **`agent_name`** in `WorkerOptions` - must match `LIVEKIT_AGENT_NAME` for explicit dispatch.
+- **`ctx.job.metadata`** (JSON) - per-call context: `source`, `caller_name`, `tenant_id`,
+  `call_direction`, and `user_id` (AAD id when Teams provides one).
+- **Data topics** - `teams.context` (participant count, DTMF, recording state) and `teams.goodbye`
+  (the governor's goodbye line; have your handler speak it and interrupt the current turn).
+
+## License
+
+MIT (c) Alaaeldin Elhenawy

livekit_msteams_bridge-0.1.0/examples/basic-bridge/.env.example

@@ -0,0 +1,35 @@
+# --- required ---
+WORKER_SHARED_SECRET=shared-secret-from-standin-pairing
+LIVEKIT_URL=wss://your-project.livekit.cloud
+LIVEKIT_API_KEY=API...
+LIVEKIT_API_SECRET=...
+
+# --- agent dispatch ---
+# Named agent for explicit dispatch (recommended). Must equal the agent_name
+# your worker registers with. Unset = automatic dispatch (prototype-only).
+LIVEKIT_AGENT_NAME=teams-voice-agent
+#LIVEKIT_ROOM_PREFIX=msteams-
+#LIVEKIT_DELETE_ROOM_ON_END=true
+
+# --- listener ---
+#PORT=8080
+#BIND=0.0.0.0
+# Native TLS (wss). Leave unset when a tunnel/ingress terminates TLS for you.
+#TLS_CERT_PATH=/path/cert.pem
+#TLS_KEY_PATH=/path/key.pem
+
+# --- call governor ---
+#MAX_CALL_MINUTES=10
+#GOODBYE_TEXT=I'm sorry, we've reached the time limit for this call. Thank you for calling, goodbye!
+#GOODBYE_GRACE_MS=8000
+
+# --- hardening ---
+#HMAC_FRESHNESS_MS=60000
+#MAX_CONNECTIONS=64
+#MAX_CONNECTIONS_PER_IP=
+#PRE_START_TIMEOUT_MS=10000
+#WORKER_IDLE_TIMEOUT_MS=90000
+#TRUST_PROXY_XFF=false
+
+# --- logging ---
+#LOG_LEVEL=info

livekit_msteams_bridge-0.1.0/examples/basic-bridge/README.md

@@ -0,0 +1,20 @@
+# basic-bridge (Python)
+
+Minimal, working embedding of `livekit-msteams-bridge`: `load_config()` + `start_server()`.
+
+## Run
+
+```bash
+pip install livekit-msteams-bridge
+cp .env.example .env   # fill in LIVEKIT_URL/KEY/SECRET, LIVEKIT_AGENT_NAME, WORKER_SHARED_SECRET
+python main.py
+```
+
+A LiveKit call needs **two** processes: your agent runs as a worker (registered under the same
+`agent_name` as `LIVEKIT_AGENT_NAME`), and this bridge dispatches it into a per-call room.
+
+It prints the WebSocket URL to give StandIn. Expose port 8080 with a tunnel (Tailscale Funnel,
+cloudflared, ngrok, ...), set your StandIn identity's **Agent voice URL** to the `wss://` URL, and
+place a Teams call - the bridge creates a room, dispatches your agent, and the agent answers.
+
+Full setup walkthrough (including ready-to-run example agents): https://docs.komaa.com/livekit/example

livekit_msteams_bridge-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "livekit-msteams-bridge"
+version = "0.1.0"
+description = "Put a LiveKit Agent on Microsoft Teams voice/video calls. Terminates the StandIn media bridge wire protocol on one side and a LiveKit room on the other: per-call rooms, explicit agent dispatch, 16 kHz PCM relay, data-topic context, call governors."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Alaaeldin Elhenawy", email = "alaamh@outlook.com" }]
+requires-python = ">=3.10"
+# livekit pins: tested against livekit 1.1.x / livekit-api 1.2.x; the rtc API
+# surface is verified by tests/test_livekit_sdk_surface.py on every CI run.
+dependencies = ["aiohttp>=3.9,<4", "livekit>=1.1,<2", "livekit-api>=1.2,<2"]
+keywords = [
+  "livekit",
+  "microsoft-teams",
+  "voice",
+  "agent",
+  "websocket",
+  "bridge",
+  "telephony",
+  "avatar",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Telephony",
+  "Topic :: Multimedia :: Sound/Audio",
+  "Framework :: AsyncIO",
+]
+
+[project.urls]
+Homepage = "https://komaa-com.github.io/livekit-msteams-bridge-py/"
+Documentation = "https://komaa-com.github.io/livekit-msteams-bridge-py/"
+"StandIn docs" = "https://docs.komaa.com/livekit/installation"
+Repository = "https://github.com/komaa-com/livekit-msteams-bridge-py"
+Issues = "https://github.com/komaa-com/livekit-msteams-bridge-py/issues"
+
+[project.scripts]
+livekit-msteams-bridge = "livekit_msteams_bridge.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "ruff>=0.4"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE", ".env.example"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/livekit_msteams_bridge"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"

livekit_msteams_bridge-0.1.0/src/livekit_msteams_bridge/__init__.py

@@ -0,0 +1,58 @@
+"""livekit-msteams-bridge - public API.
+
+Typical embedding:
+
+    from livekit_msteams_bridge import load_config, start_server
+
+    server = await start_server(load_config())
+
+Or run the CLI: `livekit-msteams-bridge` (env-configured, see .env.example).
+"""
+
+from .cli import load_dotenv
+from .config import BridgeConfig, load_config
+from .hmac_auth import SIGNATURE_HEADER, TIMESTAMP_HEADER, is_fresh, sign, verify
+from .log import Logger, logger
+from .metrics import render_metrics, reset_metrics
+from .protocol import parse_worker_message, pcm16k_bytes_to_ms
+from .server import BridgeServer, ReplayGuard, authorize_upgrade, call_id_from_path, start_server
+from .session import AgentRoomPort, CallSession, RoomConnector, RoomHandlers, WorkerPort
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentRoomPort",
+    "BridgeConfig",
+    "BridgeServer",
+    "CallSession",
+    "Logger",
+    "ReplayGuard",
+    "RoomConnector",
+    "RoomHandlers",
+    "SIGNATURE_HEADER",
+    "TIMESTAMP_HEADER",
+    "WorkerPort",
+    "__version__",
+    "authorize_upgrade",
+    "call_id_from_path",
+    "is_fresh",
+    "load_config",
+    "load_dotenv",
+    "logger",
+    "parse_worker_message",
+    "pcm16k_bytes_to_ms",
+    "render_metrics",
+    "reset_metrics",
+    "sign",
+    "start_server",
+    "verify",
+]
+
+from .livekit_room import (  # noqa: E402  (after __all__ on purpose)
+    TOPIC_CONTEXT,
+    TOPIC_GOODBYE,
+    LiveKitRoomPort,
+    connect_livekit_room,
+)
+
+__all__ += ["TOPIC_CONTEXT", "TOPIC_GOODBYE", "LiveKitRoomPort", "connect_livekit_room"]

livekit_msteams_bridge-0.1.0/src/livekit_msteams_bridge/cli.py

@@ -0,0 +1,85 @@
+"""CLI entry point: `livekit-msteams-bridge`.
+
+Entirely env-configured - see .env.example in the package root. A `.env` file
+in the working directory is loaded automatically (existing environment wins).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import signal
+import sys
+
+from .config import load_config
+from .server import start_server
+
+
+def load_dotenv(path: str = ".env") -> None:
+    """Tiny .env loader so the CLI matches the Node package's
+    `node --env-file=.env` convenience without a dependency. Supports
+    `KEY=VALUE`, an optional `export ` prefix (files shared with `source`),
+    quoted values, and inline ` # comments` on unquoted values. Single-line
+    values only. Existing environment variables are never overwritten."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                if line.startswith("export "):
+                    line = line[len("export ") :].lstrip()
+                key, _, value = line.partition("=")
+                key = key.strip()
+                value = value.strip()
+                if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+                    value = value[1:-1]  # quoted: keep content verbatim (incl. '#')
+                else:
+                    value = re.sub(r"\s+#.*$", "", value).strip()
+                if key and key not in os.environ:
+                    os.environ[key] = value
+    except OSError:
+        pass  # no .env is fine
+
+
+async def _run() -> None:
+    cfg = load_config()
+    server = await start_server(cfg)
+
+    # SIGTERM/SIGINT drain: gracefully end every live call instead of
+    # hard-dropping calls on a redeploy.
+    loop = asyncio.get_running_loop()
+    stop = asyncio.Event()
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        try:
+            loop.add_signal_handler(sig, stop.set)
+        except NotImplementedError:  # pragma: no cover - non-POSIX platforms
+            pass
+    await stop.wait()
+    await server.close()
+
+
+def main() -> None:
+    load_dotenv()
+    try:
+        asyncio.run(_run())
+    except ValueError as err:  # config errors (missing/invalid env vars)
+        print(f"livekit-msteams-bridge: {err}", file=sys.stderr)
+        print(
+            "Required env: LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET, WORKER_SHARED_SECRET (see .env.example).",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    except OSError as err:
+        if getattr(err, "errno", None) == 48 or "address already in use" in str(err).lower():
+            print(f"livekit-msteams-bridge: port already in use ({err}). Set PORT to a free port.", file=sys.stderr)
+        else:
+            print(f"livekit-msteams-bridge: server error: {err}", file=sys.stderr)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()