roomkit 0.1.1__tar.gz → 0.2.1__tar.gz

{roomkit-0.1.1 → roomkit-0.2.1}/AGENTS.md

@@ -44,6 +44,7 @@ src/roomkit/
 │   ├── base.py          # Channel ABC
 │   ├── transport.py     # TransportChannel (SMS, Email, etc.)
 │   ├── ai.py            # AIChannel (intelligence layer)
+│   ├── voice.py         # VoiceChannel (real-time audio)
 │   └── websocket.py     # WebSocketChannel
 ├── providers/
 │   ├── ai/base.py       # AIProvider ABC, AIContext, AIResponse
@@ -66,6 +67,22 @@ src/roomkit/
 ├── realtime/
 │   ├── base.py          # RealtimeBackend ABC, EphemeralEvent
 │   └── memory.py        # InMemoryRealtime
+├── voice/
+│   ├── __init__.py      # Voice subsystem exports
+│   ├── base.py          # Shared types (AudioChunk, VoiceSession, callbacks)
+│   ├── events.py        # Voice-specific events
+│   ├── stt/             # Speech-to-text providers
+│   │   ├── base.py      # STTProvider ABC
+│   │   ├── mock.py      # MockSTTProvider
+│   │   └── deepgram.py  # DeepgramSTTProvider
+│   ├── tts/             # Text-to-speech providers
+│   │   ├── base.py      # TTSProvider ABC
+│   │   ├── mock.py      # MockTTSProvider
+│   │   └── elevenlabs.py # ElevenLabsTTSProvider
+│   └── backends/        # Voice transport backends
+│       ├── base.py      # VoiceBackend ABC
+│       ├── mock.py      # MockVoiceBackend, MockVoiceCall
+│       └── fastrtc.py   # FastRTCVoiceBackend (WebRTC)
 └── identity/
     ├── base.py          # IdentityResolver ABC
     └── mock.py          # MockIdentityResolver

{roomkit-0.1.1 → roomkit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roomkit
-Version: 0.1.1
+Version: 0.2.1
 Summary: Pure async Python library for multi-channel conversations
 Project-URL: Homepage, https://roomkit.live
 Project-URL: Repository, https://github.com/sboily/roomkit
@@ -30,6 +30,7 @@ Requires-Dist: anthropic>=0.30; extra == 'anthropic'
 Provides-Extra: dev
 Requires-Dist: anthropic>=0.30; extra == 'dev'
 Requires-Dist: google-genai>=1.0.0; extra == 'dev'
+Requires-Dist: httpx-sse>=0.4; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
 Requires-Dist: mkdocs>=1.6; extra == 'dev'
@@ -49,6 +50,9 @@ Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocs>=1.6; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
+Provides-Extra: fastrtc
+Requires-Dist: fastrtc; extra == 'fastrtc'
+Requires-Dist: numpy; extra == 'fastrtc'
 Provides-Extra: gemini
 Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
 Provides-Extra: httpx
@@ -68,7 +72,12 @@ Requires-Dist: pydantic-ai>=0.1; extra == 'pydantic-ai'
 Provides-Extra: pynacl
 Requires-Dist: pynacl>=1.5; extra == 'pynacl'
 Provides-Extra: sources
+Requires-Dist: httpx-sse>=0.4; extra == 'sources'
+Requires-Dist: httpx>=0.27; extra == 'sources'
 Requires-Dist: websockets>=13.0; extra == 'sources'
+Provides-Extra: sse
+Requires-Dist: httpx-sse>=0.4; extra == 'sse'
+Requires-Dist: httpx>=0.27; extra == 'sse'
 Provides-Extra: twilio
 Requires-Dist: twilio>=9.0; extra == 'twilio'
 Provides-Extra: websocket
@@ -83,14 +92,14 @@ Description-Content-Type: text/markdown
 
 Pure async Python 3.12+ library for multi-channel conversations.
 
-RoomKit gives you a single abstraction — the **room** — to orchestrate messages across SMS, RCS, Email, WhatsApp, Messenger, WebSocket, HTTP webhooks, and AI channels. Events flow in through any channel, get validated by hooks, and broadcast to every other channel in the room with automatic content transcoding.
+RoomKit gives you a single abstraction — the **room** — to orchestrate messages across SMS, RCS, Email, WhatsApp, Messenger, Voice, WebSocket, HTTP webhooks, and AI channels. Events flow in through any channel, get validated by hooks, and broadcast to every other channel in the room with automatic content transcoding.
 
 ```
 Inbound ──► Hook pipeline ──► Store ──► Broadcast to all channels
                                              │
-              ┌──────────┬──────────┬────────┼────────┬────────┐
-              ▼          ▼          ▼        ▼        ▼        ▼
-           SMS/RCS   WebSocket   Email   Messenger   AI    Webhook
+              ┌──────────┬──────────┬────────┼────────┬────────┬────────┐
+              ▼          ▼          ▼        ▼        ▼        ▼        ▼
+           SMS/RCS   WebSocket   Email   Messenger  Voice     AI    Webhook
 ```
 
 **Website:** [www.roomkit.live](https://www.roomkit.live) | **Docs:** [www.roomkit.live/docs](https://www.roomkit.live/docs/)
@@ -157,6 +166,7 @@ pip install roomkit[websocket]         # WebSocket event source
 pip install roomkit[anthropic]         # Anthropic Claude AI
 pip install roomkit[openai]            # OpenAI GPT
 pip install roomkit[gemini]            # Google Gemini AI
+pip install roomkit[fastrtc]           # FastRTC voice backend
 pip install roomkit[providers]         # all transport providers
 pip install roomkit[all]               # everything
 ```
@@ -184,10 +194,11 @@ Each channel is a thin adapter between the room and an external transport. All c
 | **WebSocket** | `websocket` | text, rich, media | Real-time with typing, reactions |
 | **Messenger** | `messenger` | text, rich, media, template | Buttons, quick replies |
 | **WhatsApp** | `whatsapp` | text, rich, media, location, template | Buttons, templates |
+| **Voice** | `voice` | audio, text | STT/TTS, barge-in, FastRTC streaming |
 | **HTTP** | `webhook` | text, rich | Generic webhook for any system |
 | **AI** | `ai` | text, rich | Intelligence layer (not transport) |
 
-Channels have two categories: **transport** (delivers to external systems) and **intelligence** (generates content, like AI).
+Channels have two categories: **transport** (delivers to external systems) and **intelligence** (generates content, like AI). The Voice channel bridges real-time audio with the room-based conversation model.
 
 ## Providers
 
@@ -217,6 +228,14 @@ Providers handle the actual API calls. Every provider has a mock counterpart for
 | `OpenAIAIProvider` | GPT-4, vision, tools | `roomkit[openai]` |
 | `GeminiAIProvider` | Gemini, vision, tools | `roomkit[gemini]` |
 
+### Voice Providers
+
+| Provider | Role | Dependency |
+|----------|------|------------|
+| `DeepgramSTTProvider` | Speech-to-text | `roomkit[httpx]` |
+| `ElevenLabsTTSProvider` | Text-to-speech | `roomkit[httpx]` |
+| `FastRTCVoiceBackend` | WebRTC audio transport | `roomkit[fastrtc]` |
+
 ### Other Providers
 
 | Provider | Channel | Dependency |
@@ -542,6 +561,7 @@ src/roomkit/
   realtime/        Ephemeral events (typing, presence, read receipts)
   sources/         Event-driven sources (WebSocket, custom)
   store/           Storage abstraction and in-memory implementation
+  voice/           Voice subsystem (stt/, tts/, backends/)
 ```
 
 ## Documentation

{roomkit-0.1.1 → roomkit-0.2.1}/README.md

@@ -6,14 +6,14 @@
 
 Pure async Python 3.12+ library for multi-channel conversations.
 
-RoomKit gives you a single abstraction — the **room** — to orchestrate messages across SMS, RCS, Email, WhatsApp, Messenger, WebSocket, HTTP webhooks, and AI channels. Events flow in through any channel, get validated by hooks, and broadcast to every other channel in the room with automatic content transcoding.
+RoomKit gives you a single abstraction — the **room** — to orchestrate messages across SMS, RCS, Email, WhatsApp, Messenger, Voice, WebSocket, HTTP webhooks, and AI channels. Events flow in through any channel, get validated by hooks, and broadcast to every other channel in the room with automatic content transcoding.
 
 ```
 Inbound ──► Hook pipeline ──► Store ──► Broadcast to all channels
                                              │
-              ┌──────────┬──────────┬────────┼────────┬────────┐
-              ▼          ▼          ▼        ▼        ▼        ▼
-           SMS/RCS   WebSocket   Email   Messenger   AI    Webhook
+              ┌──────────┬──────────┬────────┼────────┬────────┬────────┐
+              ▼          ▼          ▼        ▼        ▼        ▼        ▼
+           SMS/RCS   WebSocket   Email   Messenger  Voice     AI    Webhook
 ```
 
 **Website:** [www.roomkit.live](https://www.roomkit.live) | **Docs:** [www.roomkit.live/docs](https://www.roomkit.live/docs/)
@@ -80,6 +80,7 @@ pip install roomkit[websocket]         # WebSocket event source
 pip install roomkit[anthropic]         # Anthropic Claude AI
 pip install roomkit[openai]            # OpenAI GPT
 pip install roomkit[gemini]            # Google Gemini AI
+pip install roomkit[fastrtc]           # FastRTC voice backend
 pip install roomkit[providers]         # all transport providers
 pip install roomkit[all]               # everything
 ```
@@ -107,10 +108,11 @@ Each channel is a thin adapter between the room and an external transport. All c
 | **WebSocket** | `websocket` | text, rich, media | Real-time with typing, reactions |
 | **Messenger** | `messenger` | text, rich, media, template | Buttons, quick replies |
 | **WhatsApp** | `whatsapp` | text, rich, media, location, template | Buttons, templates |
+| **Voice** | `voice` | audio, text | STT/TTS, barge-in, FastRTC streaming |
 | **HTTP** | `webhook` | text, rich | Generic webhook for any system |
 | **AI** | `ai` | text, rich | Intelligence layer (not transport) |
 
-Channels have two categories: **transport** (delivers to external systems) and **intelligence** (generates content, like AI).
+Channels have two categories: **transport** (delivers to external systems) and **intelligence** (generates content, like AI). The Voice channel bridges real-time audio with the room-based conversation model.
 
 ## Providers
 
@@ -140,6 +142,14 @@ Providers handle the actual API calls. Every provider has a mock counterpart for
 | `OpenAIAIProvider` | GPT-4, vision, tools | `roomkit[openai]` |
 | `GeminiAIProvider` | Gemini, vision, tools | `roomkit[gemini]` |
 
+### Voice Providers
+
+| Provider | Role | Dependency |
+|----------|------|------------|
+| `DeepgramSTTProvider` | Speech-to-text | `roomkit[httpx]` |
+| `ElevenLabsTTSProvider` | Text-to-speech | `roomkit[httpx]` |
+| `FastRTCVoiceBackend` | WebRTC audio transport | `roomkit[fastrtc]` |
+
 ### Other Providers
 
 | Provider | Channel | Dependency |
@@ -465,6 +475,7 @@ src/roomkit/
   realtime/        Ephemeral events (typing, presence, read receipts)
   sources/         Event-driven sources (WebSocket, custom)
   store/           Storage abstraction and in-memory implementation
+  voice/           Voice subsystem (stt/, tts/, backends/)
 ```
 
 ## Documentation

{roomkit-0.1.1 → roomkit-0.2.1}/docs/api/channels.md

@@ -2,12 +2,16 @@
 
 ::: roomkit.SMSChannel
 
+::: roomkit.RCSChannel
+
 ::: roomkit.EmailChannel
 
 ::: roomkit.AIChannel
 
 ::: roomkit.WebSocketChannel
 
+::: roomkit.VoiceChannel
+
 ::: roomkit.WhatsAppChannel
 
 ::: roomkit.MessengerChannel

{roomkit-0.1.1 → roomkit-0.2.1}/docs/api/index.md

@@ -14,7 +14,8 @@ Full auto-generated reference for the `roomkit` public API.
 ## Channels
 
 - **[Channel ABC](channel.md)** — Base class for all channels
-- **[Built-in Channels](channels.md)** — SMS, Email, AI, WebSocket, WhatsApp, Messenger, HTTP
+- **[Built-in Channels](channels.md)** — SMS, RCS, Email, AI, WebSocket, Voice, WhatsApp, Messenger, HTTP
+- **[Voice Channel](providers-voice.md)** — VoiceBackend, STTProvider, TTSProvider, voice events
 
 ## Models
 
@@ -29,8 +30,9 @@ Full auto-generated reference for the `roomkit` public API.
 ## Providers
 
 - **[AI](providers-ai.md)** — AIProvider, AIContext, AIResponse
-- **[SMS](providers-sms.md)** — SMSProvider
-- **[Email](providers-email.md)** — EmailProvider
+- **[SMS](providers-sms.md)** — SMSProvider, Sinch, Telnyx, Twilio, VoiceMeUp
+- **[RCS](providers-rcs.md)** — RCSProvider, Telnyx RCS, Twilio RCS
+- **[Email](providers-email.md)** — EmailProvider, ElasticEmail
 - **[WhatsApp](providers-whatsapp.md)** — WhatsAppProvider
-- **[Messenger](providers-messenger.md)** — MessengerProvider
-- **[HTTP](providers-http.md)** — HTTPProvider
+- **[Messenger](providers-messenger.md)** — MessengerProvider, Facebook
+- **[HTTP](providers-http.md)** — HTTPProvider, Webhook

roomkit-0.2.1/docs/api/providers-rcs.md

@@ -0,0 +1,25 @@
+# RCS Providers
+
+## Base Classes
+
+::: roomkit.RCSProvider
+
+::: roomkit.RCSDeliveryResult
+
+::: roomkit.MockRCSProvider
+
+## Telnyx
+
+::: roomkit.TelnyxRCSProvider
+
+::: roomkit.TelnyxRCSConfig
+
+::: roomkit.parse_telnyx_rcs_webhook
+
+## Twilio
+
+::: roomkit.TwilioRCSProvider
+
+::: roomkit.TwilioRCSConfig
+
+::: roomkit.parse_twilio_rcs_webhook

roomkit-0.2.1/docs/api/providers-voice.md

@@ -0,0 +1,56 @@
+# Voice Providers
+
+## Voice Backend
+
+::: roomkit.voice.backends.base.VoiceBackend
+
+::: roomkit.VoiceCapability
+
+::: roomkit.VoiceSession
+
+::: roomkit.VoiceSessionState
+
+::: roomkit.AudioChunk
+
+::: roomkit.TranscriptionResult
+
+## STT (Speech-to-Text)
+
+::: roomkit.voice.stt.base.STTProvider
+
+::: roomkit.voice.stt.mock.MockSTTProvider
+
+## TTS (Text-to-Speech)
+
+::: roomkit.voice.tts.base.TTSProvider
+
+::: roomkit.voice.tts.mock.MockTTSProvider
+
+## Mock Voice Backend
+
+::: roomkit.voice.backends.mock.MockVoiceBackend
+
+::: roomkit.voice.backends.mock.MockVoiceCall
+
+## Voice Events
+
+::: roomkit.BargeInEvent
+
+::: roomkit.TTSCancelledEvent
+
+::: roomkit.PartialTranscriptionEvent
+
+::: roomkit.VADSilenceEvent
+
+::: roomkit.VADAudioLevelEvent
+
+## Callback Types
+
+| Callback | Signature |
+|----------|-----------|
+| `SpeechStartCallback` | `(VoiceSession) -> Any` |
+| `SpeechEndCallback` | `(VoiceSession, bytes) -> Any` |
+| `PartialTranscriptionCallback` | `(VoiceSession, str, float, bool) -> Any` |
+| `VADSilenceCallback` | `(VoiceSession, int) -> Any` |
+| `VADAudioLevelCallback` | `(VoiceSession, float, bool) -> Any` |
+| `BargeInCallback` | `(VoiceSession) -> Any` |

{roomkit-0.1.1 → roomkit-0.2.1}/docs/api/sources.md

@@ -266,6 +266,130 @@ WebSocketSource requires the `websockets` package:
 pip install roomkit[websocket]
 ```
 
+### SSESource
+
+Connect to a Server-Sent Events (SSE) endpoint and receive real-time updates:
+
+```python
+from roomkit import RoomKit
+from roomkit.sources import SSESource
+
+# Basic usage with default JSON parser
+source = SSESource(
+    url="https://api.example.com/events",
+    channel_id="sse-events",
+)
+await kit.attach_source("sse-events", source)
+```
+
+The default parser expects SSE `data` fields to contain JSON:
+
+```json
+{
+    "sender_id": "user123",
+    "text": "Hello world",
+    "external_id": "msg-456",
+    "metadata": {"key": "value"}
+}
+```
+
+Supported event types: `message`, `msg`, `chat`, or empty (default). Other event types (e.g., `ping`, `heartbeat`) are skipped.
+
+#### Custom SSE Parser
+
+For custom SSE formats, provide a parser function that receives the event type, data, and optional event ID:
+
+```python
+from roomkit import InboundMessage, TextContent
+
+def my_parser(event: str, data: str, event_id: str | None) -> InboundMessage | None:
+    """Parse custom SSE events."""
+    if event != "chat":
+        return None  # Only process 'chat' events
+
+    # Parse custom format: "user:message"
+    parts = data.split(":", 1)
+    if len(parts) < 2:
+        return None
+
+    return InboundMessage(
+        channel_id="sse-chat",
+        sender_id=parts[0],
+        content=TextContent(body=parts[1]),
+        external_id=event_id,
+    )
+
+source = SSESource(
+    url="https://stream.example.com/chat",
+    channel_id="sse-chat",
+    parser=my_parser,
+)
+```
+
+#### SSESource Options
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | `str` | required | SSE endpoint URL |
+| `channel_id` | `str` | required | Channel ID for emitted messages |
+| `parser` | `Callable` | JSON parser | Function to parse SSE events: `(event, data, id) -> InboundMessage` |
+| `headers` | `dict[str, str]` | `None` | HTTP headers (e.g., Authorization) |
+| `params` | `dict[str, str]` | `None` | Query parameters for the URL |
+| `timeout` | `float` | `30.0` | Connection timeout in seconds |
+| `last_event_id` | `str` | `None` | Resume from this event ID (sent as `Last-Event-ID` header) |
+
+#### Resuming from Last Event ID
+
+SSE supports resumption via the `Last-Event-ID` header. SSESource tracks the last received event ID automatically:
+
+```python
+# Initial connection
+source = SSESource(
+    url="https://api.example.com/events",
+    channel_id="sse-events",
+)
+await kit.attach_source("sse-events", source)
+
+# ... connection drops ...
+
+# Get the last event ID for resumption
+last_id = source.last_event_id
+print(f"Last received event: {last_id}")
+
+# Create new source that resumes from last position
+resumed_source = SSESource(
+    url="https://api.example.com/events",
+    channel_id="sse-events",
+    last_event_id=last_id,
+)
+await kit.attach_source("sse-events", resumed_source)
+```
+
+When `auto_restart=True` (default), RoomKit automatically handles reconnection and uses the tracked `last_event_id` for seamless resumption.
+
+#### Authentication
+
+Pass authentication via headers:
+
+```python
+source = SSESource(
+    url="https://api.example.com/events",
+    channel_id="sse-events",
+    headers={
+        "Authorization": "Bearer your-token-here",
+        "X-API-Key": "your-api-key",
+    },
+)
+```
+
+#### Installation
+
+SSESource requires `httpx` and `httpx-sse`:
+
+```bash
+pip install roomkit[sse]
+```
+
 ## Implementing a Custom Source
 
 Extend `SourceProvider` or `BaseSourceProvider` to create custom sources:

{roomkit-0.1.1 → roomkit-0.2.1}/docs/architecture.md

@@ -17,6 +17,9 @@ graph TB
         WA_EXT["WhatsApp"]
         HTTP_EXT["HTTP Webhooks"]
         AI_EXT["AI APIs (Anthropic, OpenAI, Gemini)"]
+        VOICE_EXT["Voice Clients (FastRTC / WebRTC)"]
+        STT_EXT["STT (Deepgram)"]
+        TTS_EXT["TTS (ElevenLabs)"]
     end
 
     subgraph RoomKit["RoomKit Orchestrator"]
@@ -40,6 +43,13 @@ graph TB
         WA_CH["WhatsAppChannel"]
         HTTP_CH["HTTPChannel"]
         AI_CH["AIChannel"]
+        VOICE_CH["VoiceChannel"]
+    end
+
+    subgraph VoiceStack["Voice Stack"]
+        VB["VoiceBackend (FastRTC)"]
+        STT["STTProvider (Deepgram)"]
+        TTS["TTSProvider (ElevenLabs)"]
     end
 
     subgraph Storage["Storage Layer"]
@@ -55,6 +65,7 @@ graph TB
     WA_EXT --> WA_CH
     HTTP_EXT --> HTTP_CH
     AI_EXT --> AI_CH
+    VOICE_EXT --> VB
 
     WS_CH --> IR
     SMS_CH --> IR
@@ -62,6 +73,7 @@ graph TB
     EMAIL_CH --> IR
     MSG_CH --> IR
     HTTP_CH --> IR
+    VOICE_CH --> IR
 
     IR --> IP
     IP --> HE
@@ -78,6 +90,7 @@ graph TB
     ER --> WA_CH
     ER --> HTTP_CH
     ER --> AI_CH
+    ER --> VOICE_CH
 
     HE --> STORE
     ER --> STORE
@@ -85,6 +98,13 @@ graph TB
 
     WS_CH -.-> RT
     RT -.-> WS_CH
+
+    VOICE_CH --> VB
+    VOICE_CH --> STT
+    VOICE_CH --> TTS
+    VB --> VOICE_EXT
+    STT --> STT_EXT
+    TTS --> TTS_EXT
 ```
 
 ---
@@ -135,9 +155,42 @@ All transport channels (SMS, RCS, Email, WhatsApp, Messenger, HTTP) use the unif
 | `WhatsAppChannel` | Transport | `WhatsAppChannel()` factory | WhatsApp Business (mock only) |
 | `HTTPChannel` | Transport | `HTTPChannel()` factory | Generic webhook |
 | `AIChannel` | Intelligence | Direct class | Anthropic Claude, OpenAI GPT, Google Gemini |
+| `VoiceChannel` | Transport | Direct class | FastRTC backend + Deepgram STT + ElevenLabs TTS |
 
 The `TransportChannel` class is data-driven: it reads a `recipient_key` from binding metadata for the delivery address, and passes configurable `defaults` to the provider's `send()` method. This eliminates the need for per-channel subclasses.
 
+### Voice Stack
+
+The voice subsystem provides real-time audio support via three pluggable abstractions:
+
+| Component | ABC | Implementations | Responsibility |
+|---|---|---|---|
+| **VoiceBackend** | `voice/base.py` | `FastRTCVoiceBackend` (FastRTC WebSocket), `MockVoiceBackend` | Audio transport: WebSocket/WebRTC connections, VAD callbacks, session management, audio streaming |
+| **STTProvider** | `voice/stt.py` | `DeepgramSTTProvider`, `MockSTTProvider` | Speech-to-text: transcribe audio chunks or streams to text |
+| **TTSProvider** | `voice/tts.py` | `ElevenLabsTTSProvider`, `MockTTSProvider` | Text-to-speech: synthesize text to audio chunks for streaming |
+
+The `VoiceChannel` orchestrates the full pipeline:
+
+```
+Client audio → VoiceBackend (VAD) → STTProvider → Hook pipeline → process_inbound()
+                                                                        ↓
+Client audio ← VoiceBackend ← TTSProvider ← AI response ← Event broadcast
+```
+
+**VoiceBackend capabilities** are declared via `VoiceCapability` flags:
+- `INTERRUPTION` -- Backend can cancel ongoing audio playback
+- `PARTIAL_STT` -- Backend provides partial/streaming transcription
+- `VAD_SILENCE` -- Backend emits silence detection events
+- `VAD_AUDIO_LEVEL` -- Backend emits periodic audio level events
+- `BARGE_IN` -- Backend detects user interrupting TTS playback
+
+**Voice hook triggers** extend the standard hook system:
+- `ON_SPEECH_START`, `ON_SPEECH_END` -- VAD events
+- `ON_TRANSCRIPTION` -- After STT, sync (can modify or block the text)
+- `BEFORE_TTS`, `AFTER_TTS` -- Around TTS synthesis, sync (can modify text)
+- `ON_BARGE_IN`, `ON_TTS_CANCELLED` -- Interruption events
+- `ON_PARTIAL_TRANSCRIPTION`, `ON_VAD_SILENCE`, `ON_VAD_AUDIO_LEVEL` -- Streaming events
+
 ### Storage Layer
 
 The `ConversationStore` ABC defines the complete persistence interface:
@@ -273,6 +326,49 @@ flowchart TD
 
 This ensures AI-to-AI conversations complete atomically within a single `process_inbound` call, bounded by the `max_chain_depth` limit.
 
+### Voice Pipeline
+
+When a `VoiceChannel` is configured with a backend, STT, and TTS, the full real-time voice pipeline runs:
+
+```mermaid
+sequenceDiagram
+    participant Client as Voice Client (Browser)
+    participant VB as VoiceBackend (FastRTC)
+    participant VC as VoiceChannel
+    participant STT as STTProvider (Deepgram)
+    participant HE as Hook Engine
+    participant RK as RoomKit (process_inbound)
+    participant AI as AIChannel
+    participant TTS as TTSProvider (ElevenLabs)
+
+    Client->>VB: Audio stream (WebSocket)
+    VB->>VB: VAD: detect speech start
+    VB->>VC: on_speech_start(session)
+    VC->>HE: ON_SPEECH_START hooks
+
+    VB->>VB: VAD: detect pause (speech end)
+    VB->>VC: on_speech_end(session, audio_bytes)
+    VC->>HE: ON_SPEECH_END hooks
+    VC->>STT: transcribe(audio_chunk)
+    STT-->>VC: "Hello, I need help"
+
+    VC->>VB: send_transcription(session, text, "user")
+    VC->>HE: ON_TRANSCRIPTION hooks (sync, can block/modify)
+
+    VC->>RK: process_inbound(InboundMessage)
+    RK->>AI: Event broadcast
+    AI-->>RK: AI response text
+
+    RK->>VC: deliver(event) with AI response
+    VC->>HE: BEFORE_TTS hooks (sync, can modify)
+    VC->>VB: send_transcription(session, text, "assistant")
+    VC->>TTS: synthesize_stream(text)
+    TTS-->>VC: AudioChunk stream
+    VC->>VB: send_audio(session, stream)
+    VB->>Client: mu-law audio (WebSocket)
+    VC->>HE: AFTER_TTS hooks
+```
+
 ---
 
 ## External Integrations
@@ -291,6 +387,16 @@ All AI providers support:
 - **Function calling / tools** via the `AITool` model
 - **Vision** (Gemini built-in, others configurable via `supports_vision`)
 
+### Voice Providers
+
+| Provider | SDK | Purpose |
+|---|---|---|
+| Deepgram | `httpx>=0.27`, `websockets>=13.0` | Streaming speech-to-text via `DeepgramSTTProvider` |
+| ElevenLabs | `httpx>=0.27`, `websockets>=13.0` | Text-to-speech synthesis via `ElevenLabsTTSProvider` |
+| FastRTC | `fastrtc`, `numpy` | WebSocket audio transport with VAD via `FastRTCVoiceBackend` |
+
+Voice providers use the same **lazy dependency loading** pattern as other providers -- the SDK is imported only when the provider is instantiated. The `roomkit[fastrtc]` optional extra installs FastRTC and NumPy.
+
 ### Communication Providers
 
 | Provider | SDK | Channel | Features |