roomkit 0.1.1__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roomkit
-Version: 0.1.1
+Version: 0.2.0
 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

{roomkit-0.1.1 → roomkit-0.2.0}/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.0}/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.0/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.0/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.0}/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.0}/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 |