roomkit 0.1.0__py3-none-any.whl

roomkit/channels/ai.py

@@ -0,0 +1,238 @@
+"""AI channel implementation."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from roomkit.channels.base import Channel
+from roomkit.models.channel import (
+    ChannelBinding,
+    ChannelCapabilities,
+    ChannelOutput,
+)
+from roomkit.models.context import RoomContext
+from roomkit.models.delivery import InboundMessage
+from roomkit.models.enums import (
+    ChannelCategory,
+    ChannelDirection,
+    ChannelMediaType,
+    ChannelType,
+)
+from roomkit.models.event import (
+    CompositeContent,
+    EventSource,
+    MediaContent,
+    RoomEvent,
+    TextContent,
+)
+from roomkit.providers.ai.base import (
+    AIContext,
+    AIImagePart,
+    AIMessage,
+    AIProvider,
+    AITextPart,
+    AITool,
+    ProviderError,
+)
+
+logger = logging.getLogger("roomkit.channels.ai")
+
+
+class AIChannel(Channel):
+    """AI intelligence channel that generates responses using an AI provider."""
+
+    channel_type = ChannelType.AI
+    category = ChannelCategory.INTELLIGENCE
+    direction = ChannelDirection.BIDIRECTIONAL
+
+    def __init__(
+        self,
+        channel_id: str,
+        provider: AIProvider,
+        system_prompt: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+        max_context_events: int = 50,
+    ) -> None:
+        super().__init__(channel_id)
+        self._provider = provider
+        self._system_prompt = system_prompt
+        self._temperature = temperature
+        self._max_tokens = max_tokens
+        self._max_context_events = max_context_events
+
+    @property
+    def info(self) -> dict[str, Any]:
+        return {"provider": type(self._provider).__name__}
+
+    def capabilities(self) -> ChannelCapabilities:
+        media_types = [ChannelMediaType.TEXT, ChannelMediaType.RICH]
+        if self._provider.supports_vision:
+            media_types.append(ChannelMediaType.MEDIA)
+        return ChannelCapabilities(
+            media_types=media_types,
+            supports_rich_text=True,
+            supports_media=self._provider.supports_vision,
+        )
+
+    async def handle_inbound(self, message: InboundMessage, context: RoomContext) -> RoomEvent:
+        raise NotImplementedError("AI channel does not accept inbound messages")
+
+    async def on_event(
+        self, event: RoomEvent, binding: ChannelBinding, context: RoomContext
+    ) -> ChannelOutput:
+        """React to an event by generating an AI response.
+
+        Skips events from this channel to prevent self-loops.
+        """
+        if event.source.channel_id == self.channel_id:
+            return ChannelOutput.empty()
+        return await self._generate_response(event, binding, context)
+
+    async def deliver(
+        self, event: RoomEvent, binding: ChannelBinding, context: RoomContext
+    ) -> ChannelOutput:
+        """Intelligence channels are not called via deliver by the router."""
+        return ChannelOutput.empty()
+
+    async def _generate_response(
+        self, event: RoomEvent, binding: ChannelBinding, context: RoomContext
+    ) -> ChannelOutput:
+        """Generate an AI response for the given event."""
+        ai_context = self._build_context(event, binding, context)
+        try:
+            response = await self._provider.generate(ai_context)
+        except ProviderError as exc:
+            logger.exception(
+                "AI provider error for channel %s",
+                self.channel_id,
+                extra={
+                    "provider": exc.provider,
+                    "retryable": exc.retryable,
+                    "status_code": exc.status_code,
+                },
+            )
+            return ChannelOutput.empty()
+        except Exception:
+            logger.exception("AI provider failed for channel %s", self.channel_id)
+            return ChannelOutput.empty()
+
+        response_event = RoomEvent(
+            room_id=event.room_id,
+            source=EventSource(
+                channel_id=self.channel_id,
+                channel_type=self.channel_type,
+            ),
+            content=TextContent(body=response.content),
+            chain_depth=event.chain_depth + 1,
+            metadata={"ai_usage": response.usage},
+        )
+
+        return ChannelOutput(
+            responded=True,
+            response_events=[response_event],
+        )
+
+    def _build_context(
+        self, event: RoomEvent, binding: ChannelBinding, context: RoomContext
+    ) -> AIContext:
+        """Build AI context from room events.
+
+        Per-room overrides can be set via binding.metadata:
+        - system_prompt: Override the channel's default system prompt
+        - temperature: Override the channel's default temperature
+        - max_tokens: Override the channel's default max_tokens
+        - tools: List of tool definitions for function calling
+        """
+        # Per-room overrides from binding metadata
+        system_prompt = binding.metadata.get("system_prompt", self._system_prompt)
+        temperature = binding.metadata.get("temperature", self._temperature)
+        max_tokens = binding.metadata.get("max_tokens", self._max_tokens)
+        raw_tools = binding.metadata.get("tools", [])
+
+        # Convert raw tool dicts to AITool instances
+        tools = [
+            AITool(
+                name=t["name"],
+                description=t.get("description", ""),
+                parameters=t.get("parameters", {}),
+            )
+            for t in raw_tools
+        ]
+
+        messages: list[AIMessage] = []
+
+        for past_event in context.recent_events[-self._max_context_events :]:
+            role = self._determine_role(past_event)
+            content = self._extract_content(past_event)
+            if content:
+                messages.append(AIMessage(role=role, content=content))
+
+        # Add current event
+        content = self._extract_content(event)
+        if content:
+            messages.append(AIMessage(role="user", content=content))
+
+        # Determine target channel capabilities for capability-aware generation
+        transport_bindings = [
+            b
+            for b in context.bindings
+            if b.category == ChannelCategory.TRANSPORT and b.channel_id != self.channel_id
+        ]
+        target_caps = transport_bindings[0].capabilities if transport_bindings else None
+        target_media = target_caps.media_types if target_caps else []
+
+        return AIContext(
+            messages=messages,
+            system_prompt=system_prompt,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            tools=tools,
+            room=context,
+            target_capabilities=target_caps,
+            target_media_types=target_media,
+        )
+
+    def _determine_role(self, event: RoomEvent) -> str:
+        if event.source.channel_id == self.channel_id:
+            return "assistant"
+        return "user"
+
+    def _extract_content(self, event: RoomEvent) -> str | list[AITextPart | AIImagePart]:
+        """Extract content, including images if provider supports vision."""
+        content = event.content
+
+        if not self._provider.supports_vision:
+            # Text-only fallback (existing behavior)
+            return self._extract_text(event)
+
+        # Build multimodal content
+        if isinstance(content, TextContent):
+            return content.body  # Simple case: just text
+
+        if isinstance(content, MediaContent):
+            parts: list[AITextPart | AIImagePart] = []
+            if content.caption:
+                parts.append(AITextPart(text=content.caption))
+            parts.append(AIImagePart(url=content.url, mime_type=content.mime_type))
+            return parts
+
+        if isinstance(content, CompositeContent):
+            parts = []
+            for part in content.parts:
+                if isinstance(part, TextContent):
+                    parts.append(AITextPart(text=part.body))
+                elif isinstance(part, MediaContent):
+                    if part.caption:
+                        parts.append(AITextPart(text=part.caption))
+                    parts.append(AIImagePart(url=part.url, mime_type=part.mime_type))
+            return parts if parts else ""
+
+        # Fallback for other types
+        return self._extract_text(event)
+
+    def _extract_text(self, event: RoomEvent) -> str:
+        if isinstance(event.content, TextContent):
+            return event.content.body
+        return ""

roomkit/channels/base.py

@@ -0,0 +1,66 @@
+"""Abstract base class for channels."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from roomkit.models.channel import ChannelBinding, ChannelCapabilities, ChannelOutput
+from roomkit.models.context import RoomContext
+from roomkit.models.delivery import InboundMessage
+from roomkit.models.enums import (
+    ChannelCategory,
+    ChannelDirection,
+    ChannelMediaType,
+    ChannelType,
+)
+from roomkit.models.event import RoomEvent, TextContent
+
+
+class Channel(ABC):
+    """Base class for all channels."""
+
+    channel_type: ChannelType
+    category: ChannelCategory = ChannelCategory.TRANSPORT
+    direction: ChannelDirection = ChannelDirection.BIDIRECTIONAL
+
+    def __init__(self, channel_id: str) -> None:
+        self.channel_id = channel_id
+        self._provider: Any = None
+
+    @property
+    def info(self) -> dict[str, Any]:
+        """Return channel metadata. Override in subclasses."""
+        return {}
+
+    @abstractmethod
+    async def handle_inbound(self, message: InboundMessage, context: RoomContext) -> RoomEvent:
+        """Process an inbound message into a RoomEvent."""
+
+    @abstractmethod
+    async def deliver(
+        self, event: RoomEvent, binding: ChannelBinding, context: RoomContext
+    ) -> ChannelOutput:
+        """Deliver an event to this channel."""
+
+    async def on_event(
+        self, event: RoomEvent, binding: ChannelBinding, context: RoomContext
+    ) -> ChannelOutput:
+        """React to an event. Default: no-op for transport channels."""
+        return ChannelOutput.empty()
+
+    def capabilities(self) -> ChannelCapabilities:
+        """Return channel capabilities."""
+        return ChannelCapabilities(media_types=[ChannelMediaType.TEXT])
+
+    async def close(self) -> None:
+        """Close the channel and its provider."""
+        if self._provider is not None:
+            await self._provider.close()
+
+    @staticmethod
+    def extract_text(event: RoomEvent) -> str:
+        """Extract plain text from an event's content."""
+        if isinstance(event.content, TextContent):
+            return event.content.body
+        return ""

roomkit/channels/transport.py

@@ -0,0 +1,115 @@
+"""Unified transport channel implementation."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from roomkit.channels.base import Channel
+from roomkit.models.channel import ChannelBinding, ChannelCapabilities, ChannelOutput
+from roomkit.models.context import RoomContext
+from roomkit.models.delivery import InboundMessage
+from roomkit.models.enums import ChannelType
+from roomkit.models.event import CompositeContent, EventSource, MediaContent, RoomEvent
+
+logger = logging.getLogger("roomkit.channels.transport")
+
+
+class TransportChannel(Channel):
+    """Generic transport channel driven by configuration rather than subclassing.
+
+    All transport channels (SMS, Email, WhatsApp, Messenger, HTTP) share the
+    same inbound/deliver logic.  The only differences are data: which
+    ``ChannelType``, which ``ChannelCapabilities``, which metadata key holds the
+    recipient address, and which extra kwargs to pass to the provider's
+    ``send()`` method.
+
+    Use the factory functions (``SMSChannel``, ``EmailChannel``, …) in
+    ``roomkit.channels`` for convenient construction.
+    """
+
+    def __init__(
+        self,
+        channel_id: str,
+        channel_type: ChannelType,
+        *,
+        provider: Any = None,
+        capabilities: ChannelCapabilities | None = None,
+        recipient_key: str = "recipient_id",
+        defaults: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialise a transport channel.
+
+        Args:
+            channel_id: Unique identifier for this channel instance.
+            channel_type: The channel type (SMS, email, etc.).
+            provider: Provider that handles external delivery (e.g. ElasticEmailProvider).
+            capabilities: Media and feature capabilities for this channel.
+            recipient_key: Binding metadata key that holds the recipient address.
+            defaults: Default kwargs passed to ``provider.send()``.  If a default
+                value is ``None``, the actual value is read from the binding metadata
+                at delivery time.
+        """
+        super().__init__(channel_id)
+        self.channel_type = channel_type
+        self._provider = provider
+        self._capabilities = capabilities or ChannelCapabilities()
+        self._recipient_key = recipient_key
+        self._defaults: dict[str, Any] = defaults or {}
+
+    @property
+    def info(self) -> dict[str, Any]:
+        """Return non-None default values as channel info metadata."""
+        return {k: v for k, v in self._defaults.items() if v is not None}
+
+    def capabilities(self) -> ChannelCapabilities:
+        """Return the channel's media and feature capabilities."""
+        return self._capabilities
+
+    async def handle_inbound(self, message: InboundMessage, context: RoomContext) -> RoomEvent:
+        """Convert an inbound message into a room event."""
+        # Use MMS channel type for SMS with media content
+        channel_type = self.channel_type
+        if channel_type == ChannelType.SMS and self._has_media(message.content):
+            channel_type = ChannelType.MMS
+
+        return RoomEvent(
+            room_id=context.room.id,
+            source=EventSource(
+                channel_id=self.channel_id,
+                channel_type=channel_type,
+                external_id=message.external_id,
+            ),
+            content=message.content,
+            idempotency_key=message.idempotency_key,
+            metadata=message.metadata,
+        )
+
+    @staticmethod
+    def _has_media(content: Any) -> bool:
+        """Check if content contains media."""
+        if isinstance(content, MediaContent):
+            return True
+        if isinstance(content, CompositeContent):
+            return any(isinstance(part, MediaContent) for part in content.parts)
+        return False
+
+    async def deliver(
+        self, event: RoomEvent, binding: ChannelBinding, context: RoomContext
+    ) -> ChannelOutput:
+        """Deliver an event to the external recipient via the provider.
+
+        The recipient address is read from ``binding.metadata[recipient_key]``.
+        Extra kwargs are built from ``defaults``: fixed values are passed as-is,
+        ``None`` defaults are resolved from binding metadata at delivery time.
+        """
+        if self._provider is None:
+            logger.debug("No provider configured for %s, skipping delivery", self.channel_id)
+            return ChannelOutput.empty()
+
+        to = binding.metadata.get(self._recipient_key, "")
+        kwargs: dict[str, Any] = {}
+        for key, value in self._defaults.items():
+            kwargs[key] = binding.metadata.get(key, value) if value is None else value
+        await self._provider.send(event, to=to, **kwargs)
+        return ChannelOutput.empty()

roomkit/channels/websocket.py

@@ -0,0 +1,85 @@
+"""WebSocket channel implementation."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from roomkit.channels.base import Channel
+from roomkit.models.channel import ChannelBinding, ChannelCapabilities, ChannelOutput
+from roomkit.models.context import RoomContext
+from roomkit.models.delivery import InboundMessage
+from roomkit.models.enums import ChannelMediaType, ChannelType
+from roomkit.models.event import EventSource, RoomEvent
+
+logger = logging.getLogger("roomkit.channels.websocket")
+
+SendFn = Callable[[str, RoomEvent], Coroutine[Any, Any, None]]
+
+
+class WebSocketChannel(Channel):
+    """WebSocket transport channel with connection registry."""
+
+    channel_type = ChannelType.WEBSOCKET
+
+    def __init__(self, channel_id: str) -> None:
+        super().__init__(channel_id)
+        self._connections: dict[str, SendFn] = {}
+
+    @property
+    def info(self) -> dict[str, Any]:
+        return {"connection_count": len(self._connections)}
+
+    def capabilities(self) -> ChannelCapabilities:
+        return ChannelCapabilities(
+            media_types=[
+                ChannelMediaType.TEXT,
+                ChannelMediaType.RICH,
+                ChannelMediaType.MEDIA,
+            ],
+            supports_typing=True,
+            supports_read_receipts=True,
+            supports_reactions=True,
+            supports_rich_text=True,
+            supports_media=True,
+            supports_buttons=True,
+            supports_cards=True,
+            supports_quick_replies=True,
+        )
+
+    def register_connection(self, connection_id: str, send_fn: SendFn) -> None:
+        """Register a WebSocket connection."""
+        self._connections[connection_id] = send_fn
+
+    def unregister_connection(self, connection_id: str) -> None:
+        """Unregister a WebSocket connection."""
+        self._connections.pop(connection_id, None)
+
+    @property
+    def connection_count(self) -> int:
+        return len(self._connections)
+
+    async def handle_inbound(self, message: InboundMessage, context: RoomContext) -> RoomEvent:
+        return RoomEvent(
+            room_id=context.room.id,
+            source=EventSource(
+                channel_id=self.channel_id,
+                channel_type=self.channel_type,
+                participant_id=message.sender_id,
+            ),
+            content=message.content,
+            idempotency_key=message.idempotency_key,
+            metadata=message.metadata,
+        )
+
+    async def deliver(
+        self, event: RoomEvent, binding: ChannelBinding, context: RoomContext
+    ) -> ChannelOutput:
+        for conn_id, send_fn in list(self._connections.items()):
+            try:
+                await send_fn(conn_id, event)
+            except Exception:
+                logger.exception("WebSocket send failed for connection %s", conn_id)
+                self._connections.pop(conn_id, None)
+        return ChannelOutput.empty()