roomkit 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

roomkit/core/_channel_ops.py

@@ -16,6 +16,7 @@ from roomkit.models.enums import (
 
 if TYPE_CHECKING:
     from roomkit.channels.base import Channel
+    from roomkit.channels.voice import VoiceChannel
     from roomkit.core.event_router import EventRouter
     from roomkit.core.locks import RoomLockManager
     from roomkit.store.base import ConversationStore
@@ -31,9 +32,15 @@ class ChannelOpsMixin(HelpersMixin):
 
     def register_channel(self, channel: Channel) -> None:
         """Register a channel implementation by its ID."""
+        from roomkit.channels.voice import VoiceChannel
+
         self._channels[channel.channel_id] = channel
         self._event_router = None  # Reset router cache
 
+        # Set framework reference on VoiceChannel for inbound routing
+        if isinstance(channel, VoiceChannel):
+            channel.set_framework(self)  # type: ignore[arg-type]
+
     async def attach_channel(
         self,
         room_id: str,

roomkit/core/_inbound.py

@@ -369,6 +369,10 @@ class InboundMixin(HelpersMixin):
                     await self._store.add_event(blocked)
                 # Queue nested reentry events for further broadcasting
                 pending_reentries.extend(reentry_result.reentry_events)
+                # Run AFTER_BROADCAST hooks for reentry events (e.g., AI responses)
+                await self._hook_engine.run_async_hooks(
+                    room_id, HookTrigger.AFTER_BROADCAST, reentry, reentry_ctx
+                )
 
         # Persist side effects from hooks and broadcast
         all_tasks = sync_result.tasks + broadcast_result.tasks

roomkit/core/framework.py

@@ -11,9 +11,15 @@ from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from roomkit.models.delivery import InboundMessage, InboundResult
+    from roomkit.models.event import AudioContent
     from roomkit.providers.sms.meta import WebhookMeta
+    from roomkit.voice.backends.base import VoiceBackend
+    from roomkit.voice.base import VoiceSession
+    from roomkit.voice.stt.base import STTProvider
+    from roomkit.voice.tts.base import TTSProvider
 
 from roomkit.channels.base import Channel
+from roomkit.channels.voice import VoiceChannel
 from roomkit.channels.websocket import SendFn, WebSocketChannel
 from roomkit.core._channel_ops import ChannelOpsMixin
 from roomkit.core._helpers import FrameworkEventHandler, HelpersMixin, IdentityHookFn
@@ -69,6 +75,8 @@ __all__ = [
     "RoomNotFoundError",
     "SourceAlreadyAttachedError",
     "SourceNotFoundError",
+    "VoiceBackendNotConfiguredError",
+    "VoiceNotConfiguredError",
 ]
 
 
@@ -104,6 +112,14 @@ class SourceNotFoundError(RoomKitError):
     """Source not found for channel."""
 
 
+class VoiceNotConfiguredError(RoomKitError):
+    """Raised when voice operation attempted without configured provider."""
+
+
+class VoiceBackendNotConfiguredError(RoomKitError):
+    """Raised when voice backend operation attempted without configured backend."""
+
+
 class RoomKit(InboundMixin, ChannelOpsMixin, RoomLifecycleMixin, HelpersMixin):
     """Central orchestrator tying rooms, channels, hooks, and storage."""
 
@@ -118,6 +134,9 @@ class RoomKit(InboundMixin, ChannelOpsMixin, RoomLifecycleMixin, HelpersMixin):
         max_chain_depth: int = 5,
         identity_timeout: float = 10.0,
         process_timeout: float = 30.0,
+        stt: STTProvider | None = None,
+        tts: TTSProvider | None = None,
+        voice: VoiceBackend | None = None,
     ) -> None:
         """Initialise the RoomKit orchestrator.
 
@@ -138,6 +157,9 @@ class RoomKit(InboundMixin, ChannelOpsMixin, RoomLifecycleMixin, HelpersMixin):
             max_chain_depth: Maximum reentry chain depth to prevent infinite loops.
             identity_timeout: Timeout in seconds for identity resolution calls.
             process_timeout: Timeout in seconds for the locked processing phase.
+            stt: Optional speech-to-text provider for transcription.
+            tts: Optional text-to-speech provider for synthesis.
+            voice: Optional voice backend for real-time audio transport.
         """
         self._store = store or InMemoryStore()
         self._identity_resolver = identity_resolver
@@ -158,6 +180,10 @@ class RoomKit(InboundMixin, ChannelOpsMixin, RoomLifecycleMixin, HelpersMixin):
         # Event-driven sources
         self._sources: dict[str, SourceProvider] = {}
         self._source_tasks: dict[str, asyncio.Task[None]] = {}
+        # Voice support
+        self._stt = stt
+        self._tts = tts
+        self._voice = voice
 
     @property
     def store(self) -> ConversationStore:
@@ -174,6 +200,148 @@ class RoomKit(InboundMixin, ChannelOpsMixin, RoomLifecycleMixin, HelpersMixin):
         """The realtime backend for ephemeral events."""
         return self._realtime
 
+    @property
+    def stt(self) -> STTProvider | None:
+        """Speech-to-text provider (optional)."""
+        return self._stt
+
+    @property
+    def tts(self) -> TTSProvider | None:
+        """Text-to-speech provider (optional)."""
+        return self._tts
+
+    @property
+    def voice(self) -> VoiceBackend | None:
+        """Voice backend for real-time audio (optional)."""
+        return self._voice
+
+    async def connect_voice(
+        self,
+        room_id: str,
+        participant_id: str,
+        channel_id: str,
+        *,
+        metadata: dict[str, Any] | None = None,
+    ) -> VoiceSession:
+        """Connect a participant to a voice session.
+
+        Creates a voice session via the configured VoiceBackend and binds it
+        to the specified room and voice channel for message routing.
+
+        Args:
+            room_id: The room to join.
+            participant_id: The participant's ID.
+            channel_id: The voice channel ID.
+            metadata: Optional session metadata.
+
+        Returns:
+            A VoiceSession representing the connection.
+
+        Raises:
+            VoiceBackendNotConfiguredError: If no voice backend is configured.
+            ChannelNotRegisteredError: If the channel is not a VoiceChannel.
+            RoomNotFoundError: If the room doesn't exist.
+        """
+        if self._voice is None:
+            raise VoiceBackendNotConfiguredError("No voice backend configured")
+
+        # Verify room exists
+        await self.get_room(room_id)
+
+        # Get the voice channel
+        channel = self._channels.get(channel_id)
+        if not isinstance(channel, VoiceChannel):
+            raise ChannelNotRegisteredError(
+                f"Channel {channel_id} is not a registered VoiceChannel"
+            )
+
+        # Get the binding
+        binding = await self._store.get_binding(room_id, channel_id)
+        if binding is None:
+            raise ChannelNotFoundError(f"Channel {channel_id} not attached to room {room_id}")
+
+        # Create the session
+        session = await self._voice.connect(
+            room_id, participant_id, channel_id, metadata=metadata
+        )
+
+        # Bind session to channel for routing
+        channel.bind_session(session, room_id, binding)
+
+        await self._emit_framework_event(
+            "voice_connected",
+            room_id=room_id,
+            channel_id=channel_id,
+            data={
+                "session_id": session.id,
+                "participant_id": participant_id,
+            },
+        )
+
+        return session
+
+    async def disconnect_voice(self, session: VoiceSession) -> None:
+        """Disconnect a voice session.
+
+        Args:
+            session: The session to disconnect.
+
+        Raises:
+            VoiceBackendNotConfiguredError: If no voice backend is configured.
+        """
+        if self._voice is None:
+            raise VoiceBackendNotConfiguredError("No voice backend configured")
+
+        # Get the voice channel and unbind
+        channel = self._channels.get(session.channel_id)
+        if isinstance(channel, VoiceChannel):
+            channel.unbind_session(session)
+
+        await self._voice.disconnect(session)
+
+        await self._emit_framework_event(
+            "voice_disconnected",
+            room_id=session.room_id,
+            channel_id=session.channel_id,
+            data={
+                "session_id": session.id,
+                "participant_id": session.participant_id,
+            },
+        )
+
+    async def transcribe(self, audio: AudioContent) -> str:
+        """Transcribe audio to text using configured STT provider.
+
+        Args:
+            audio: AudioContent with URL to audio file.
+
+        Returns:
+            Transcribed text.
+
+        Raises:
+            VoiceNotConfiguredError: If no STT provider is configured.
+        """
+        if self._stt is None:
+            raise VoiceNotConfiguredError("No STT provider configured")
+        return await self._stt.transcribe(audio)
+
+    async def synthesize(self, text: str, *, voice: str | None = None) -> AudioContent:
+        """Synthesize text to audio using configured TTS provider.
+
+        Args:
+            text: Text to synthesize.
+            voice: Optional voice ID (uses provider default if not specified).
+
+        Returns:
+            AudioContent with URL to generated audio.
+
+        Raises:
+            VoiceNotConfiguredError: If no TTS provider is configured.
+        """
+        if self._tts is None:
+            raise VoiceNotConfiguredError("No TTS provider configured")
+        return await self._tts.synthesize(text, voice=voice)
+
     def _get_router(self) -> EventRouter:
         if self._event_router is None:
             self._event_router = EventRouter(
@@ -184,13 +352,16 @@ class RoomKit(InboundMixin, ChannelOpsMixin, RoomLifecycleMixin, HelpersMixin):
         return self._event_router
 
     async def close(self) -> None:
-        """Close all sources, channels, and the realtime backend."""
+        """Close all sources, channels, voice backend, and the realtime backend."""
         # Stop all event sources first
         for channel_id in list(self._sources.keys()):
             await self.detach_source(channel_id)
         # Then close channels
         for channel in self._channels.values():
             await channel.close()
+        # Close voice backend
+        if self._voice:
+            await self._voice.close()
         await self._realtime.close()
 
     async def __aenter__(self) -> RoomKit:
@@ -277,6 +448,11 @@ class RoomKit(InboundMixin, ChannelOpsMixin, RoomLifecycleMixin, HelpersMixin):
             router = self._get_router()
             await router.broadcast(event, binding, context)
 
+            # Run AFTER_BROADCAST hooks for observability and fan-out
+            await self._hook_engine.run_async_hooks(
+                room_id, HookTrigger.AFTER_BROADCAST, event, context
+            )
+
         return event
 
     # -- WebSocket lifecycle --

roomkit/core/hooks.py

@@ -152,11 +152,24 @@ class HookEngine:
         self,
         room_id: str,
         trigger: HookTrigger,
-        event: RoomEvent,
+        event: RoomEvent | Any,
         context: RoomContext,
+        *,
+        skip_event_filter: bool = False,
     ) -> SyncPipelineResult:
-        """Run sync hooks sequentially. Stops on block, passes modified events."""
-        hooks = self._get_hooks(room_id, trigger, HookExecution.SYNC, event=event)
+        """Run sync hooks sequentially. Stops on block, passes modified events.
+
+        Args:
+            room_id: The room ID to run hooks for.
+            trigger: The hook trigger type.
+            event: The event to pass to hooks. For voice hooks, this may be
+                a VoiceSession or str instead of RoomEvent.
+            context: The room context.
+            skip_event_filter: If True, skip channel-based event filtering.
+                Use this for voice hooks where event is not a RoomEvent.
+        """
+        filter_event = None if skip_event_filter else event
+        hooks = self._get_hooks(room_id, trigger, HookExecution.SYNC, event=filter_event)
         result = SyncPipelineResult(event=event)
 
         for hook in hooks:
@@ -201,11 +214,24 @@ class HookEngine:
         self,
         room_id: str,
         trigger: HookTrigger,
-        event: RoomEvent,
+        event: RoomEvent | Any,
         context: RoomContext,
+        *,
+        skip_event_filter: bool = False,
     ) -> None:
-        """Run async hooks concurrently. Errors are logged, never raised."""
-        hooks = self._get_hooks(room_id, trigger, HookExecution.ASYNC, event=event)
+        """Run async hooks concurrently. Errors are logged, never raised.
+
+        Args:
+            room_id: The room ID to run hooks for.
+            trigger: The hook trigger type.
+            event: The event to pass to hooks. For voice hooks, this may be
+                a VoiceSession or str instead of RoomEvent.
+            context: The room context.
+            skip_event_filter: If True, skip channel-based event filtering.
+                Use this for voice hooks where event is not a RoomEvent.
+        """
+        filter_event = None if skip_event_filter else event
+        hooks = self._get_hooks(room_id, trigger, HookExecution.ASYNC, event=filter_event)
         if not hooks:
             return
 

roomkit/models/enums.py

@@ -162,6 +162,18 @@ class HookTrigger(StrEnum):
     ON_ERROR = "on_error"
     # Delivery status (outbound message tracking)
     ON_DELIVERY_STATUS = "on_delivery_status"
+    # Voice (RFC §18)
+    ON_SPEECH_START = "on_speech_start"
+    ON_SPEECH_END = "on_speech_end"
+    ON_TRANSCRIPTION = "on_transcription"
+    BEFORE_TTS = "before_tts"
+    AFTER_TTS = "after_tts"
+    # Voice - Enhanced (RFC §19)
+    ON_BARGE_IN = "on_barge_in"
+    ON_TTS_CANCELLED = "on_tts_cancelled"
+    ON_PARTIAL_TRANSCRIPTION = "on_partial_transcription"
+    ON_VAD_SILENCE = "on_vad_silence"
+    ON_VAD_AUDIO_LEVEL = "on_vad_audio_level"
 
 
 @unique

roomkit/sources/__init__.py

@@ -18,7 +18,7 @@ __all__ = [
     "SourceStatus",
     # Lazy imports for optional sources
     "WebSocketSource",
-    "default_json_parser",
+    "SSESource",
 ]
 
 
@@ -28,8 +28,8 @@ def __getattr__(name: str) -> Any:
         from roomkit.sources.websocket import WebSocketSource
 
         return WebSocketSource
-    if name == "default_json_parser":
-        from roomkit.sources.websocket import default_json_parser
+    if name == "SSESource":
+        from roomkit.sources.sse import SSESource
 
-        return default_json_parser
+        return SSESource
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

roomkit/sources/sse.py

@@ -0,0 +1,226 @@
+"""Server-Sent Events (SSE) source for RoomKit."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from roomkit.models.delivery import InboundMessage
+from roomkit.models.event import TextContent
+from roomkit.sources.base import BaseSourceProvider, EmitCallback, SourceStatus
+
+# Optional dependency - import for availability check
+try:
+    import httpx
+    from httpx_sse import aconnect_sse
+
+    HAS_SSE = True
+except ImportError:
+    httpx = None  # type: ignore[assignment]
+    aconnect_sse = None  # type: ignore[assignment]
+    HAS_SSE = False
+
+logger = logging.getLogger("roomkit.sources.sse")
+
+# Type alias for event parser
+SSEEventParser = Callable[[str, str, str | None], InboundMessage | None]
+
+
+def default_json_parser(channel_id: str) -> SSEEventParser:
+    """Create a default JSON event parser.
+
+    Expects SSE data field to contain JSON:
+    {
+        "sender_id": "user123",
+        "text": "Hello world",
+        "external_id": "msg-456",  # optional
+        "metadata": {}             # optional
+    }
+
+    Args:
+        channel_id: Channel ID to use for parsed messages.
+
+    Returns:
+        A parser function that converts SSE events to InboundMessage.
+    """
+
+    def parser(event: str, data: str, event_id: str | None) -> InboundMessage | None:
+        # Skip non-message events (e.g., heartbeats, pings)
+        if event not in ("message", "msg", "chat", ""):
+            logger.debug("Skipping event type: %s", event)
+            return None
+
+        try:
+            payload = json.loads(data)
+
+            if not isinstance(payload, dict):
+                return None
+            if "sender_id" not in payload:
+                return None
+
+            return InboundMessage(
+                channel_id=channel_id,
+                sender_id=payload["sender_id"],
+                content=TextContent(body=payload.get("text", "")),
+                external_id=payload.get("external_id") or event_id,
+                metadata=payload.get("metadata", {}),
+            )
+        except (json.JSONDecodeError, KeyError, TypeError) as e:
+            logger.debug("Failed to parse SSE data: %s", e)
+            return None
+
+    return parser
+
+
+class SSESource(BaseSourceProvider):
+    """Server-Sent Events (SSE) source for receiving messages.
+
+    Connects to an SSE endpoint and emits parsed events into RoomKit.
+    Handles reconnection automatically when the connection drops.
+
+    Example:
+        from roomkit import RoomKit
+        from roomkit.sources import SSESource
+
+        # Simple usage with default JSON parser
+        source = SSESource(
+            url="https://api.example.com/events",
+            channel_id="sse-events",
+        )
+        await kit.attach_source("sse-events", source)
+
+        # With authentication
+        source = SSESource(
+            url="https://api.example.com/events",
+            channel_id="sse-events",
+            headers={"Authorization": "Bearer token123"},
+        )
+
+        # Custom parser for non-JSON events
+        def my_parser(event: str, data: str, event_id: str | None) -> InboundMessage | None:
+            if event != "chat":
+                return None
+            return InboundMessage(
+                channel_id="custom",
+                sender_id="system",
+                content=TextContent(body=data),
+                external_id=event_id,
+            )
+
+        source = SSESource(
+            url="https://stream.example.com/chat",
+            channel_id="custom",
+            parser=my_parser,
+        )
+    """
+
+    def __init__(
+        self,
+        url: str,
+        channel_id: str,
+        *,
+        parser: SSEEventParser | None = None,
+        headers: dict[str, str] | None = None,
+        params: dict[str, str] | None = None,
+        timeout: float = 30.0,
+        last_event_id: str | None = None,
+    ) -> None:
+        """Initialize SSE source.
+
+        Args:
+            url: SSE endpoint URL.
+            channel_id: Channel ID for emitted messages.
+            parser: Function to parse SSE events into InboundMessage.
+                Receives (event_type, data, event_id) and returns InboundMessage or None.
+                If None, uses default JSON parser.
+            headers: HTTP headers for the request (e.g., Authorization).
+            params: Query parameters for the URL.
+            timeout: Connection timeout in seconds.
+            last_event_id: Resume from this event ID (sent as Last-Event-ID header).
+        """
+        super().__init__()
+        self._url = url
+        self._channel_id = channel_id
+        self._parser = parser or default_json_parser(channel_id)
+        self._headers = headers or {}
+        self._params = params or {}
+        self._timeout = timeout
+        self._last_event_id = last_event_id
+        self._client: Any = None
+
+    @property
+    def name(self) -> str:
+        return f"sse:{self._url}"
+
+    async def start(self, emit: EmitCallback) -> None:
+        """Connect and start receiving SSE events."""
+        if not HAS_SSE:
+            raise ImportError(
+                "httpx and httpx-sse are required for SSESource. "
+                "Install with: pip install roomkit[sse]"
+            )
+
+        self._reset_stop()
+        self._set_status(SourceStatus.CONNECTING)
+
+        # Build headers with Last-Event-ID if resuming
+        headers = dict(self._headers)
+        if self._last_event_id:
+            headers["Last-Event-ID"] = self._last_event_id
+
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                self._client = client
+
+                async with aconnect_sse(
+                    client,
+                    "GET",
+                    self._url,
+                    headers=headers,
+                    params=self._params,
+                ) as event_source:
+                    self._set_status(SourceStatus.CONNECTED)
+                    logger.info("Connected to SSE endpoint: %s", self._url)
+
+                    await self._receive_loop(event_source, emit)
+
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            self._set_status(SourceStatus.ERROR, str(e))
+            raise
+        finally:
+            self._client = None
+
+    async def _receive_loop(self, event_source: Any, emit: EmitCallback) -> None:
+        """Main receive loop - reads SSE events and emits them."""
+        async for sse in event_source.aiter_sse():
+            if self._should_stop():
+                break
+
+            # Track last event ID for potential reconnection
+            if sse.id:
+                self._last_event_id = sse.id
+
+            # Parse the event
+            message = self._parser(sse.event, sse.data, sse.id)
+            if message is not None:
+                result = await emit(message)
+                self._record_message()
+
+                if result.blocked:
+                    logger.debug("Message blocked: %s", result.reason)
+
+    async def stop(self) -> None:
+        """Stop receiving and close the connection."""
+        await super().stop()
+        logger.info("SSE source stopped")
+
+    @property
+    def last_event_id(self) -> str | None:
+        """Get the last received event ID for resumption."""
+        return self._last_event_id