roomkit 0.1.0__py3-none-any.whl

roomkit/providers/http/provider.py

@@ -0,0 +1,105 @@
+"""Generic HTTP webhook provider — POSTs events to a configurable URL."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import TYPE_CHECKING, Any
+
+from roomkit.models.delivery import ProviderResult
+from roomkit.models.event import RoomEvent, TextContent
+from roomkit.providers.http.base import HTTPProvider
+from roomkit.providers.http.config import HTTPProviderConfig
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class WebhookHTTPProvider(HTTPProvider):
+    """HTTP provider that POSTs JSON payloads to a webhook URL."""
+
+    def __init__(self, config: HTTPProviderConfig) -> None:
+        try:
+            import httpx as _httpx
+        except ImportError as exc:
+            raise ImportError(
+                "httpx is required for WebhookHTTPProvider. "
+                "Install it with: pip install roomkit[httpx]"
+            ) from exc
+        self._config = config
+        self._httpx = _httpx
+        self._client: httpx.AsyncClient = _httpx.AsyncClient(
+            timeout=config.timeout,
+        )
+
+    async def send(self, event: RoomEvent, to: str) -> ProviderResult:
+        text = self._extract_text(event)
+        if not text:
+            return ProviderResult(success=False, error="empty_message")
+
+        payload = self._build_payload(event, to, text)
+        body = json.dumps(payload)
+        headers = self._build_headers(body)
+
+        try:
+            resp = await self._client.post(
+                self._config.webhook_url,
+                content=body,
+                headers=headers,
+            )
+            resp.raise_for_status()
+            data: dict[str, Any] = resp.json()
+        except self._httpx.TimeoutException:
+            return ProviderResult(success=False, error="timeout")
+        except self._httpx.HTTPStatusError as exc:
+            return ProviderResult(
+                success=False,
+                error=f"http_{exc.response.status_code}",
+            )
+        except self._httpx.HTTPError as exc:
+            return ProviderResult(success=False, error=str(exc))
+
+        return self._parse_response(data)
+
+    def _build_payload(self, event: RoomEvent, to: str, text: str) -> dict[str, Any]:
+        return {
+            "recipient_id": to,
+            "channel_id": event.source.channel_id,
+            "room_id": event.room_id,
+            "content": {"type": "text", "body": text},
+            "metadata": event.metadata or {},
+        }
+
+    def _build_headers(self, body: str) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            **self._config.headers,
+        }
+        if self._config.secret is not None:
+            signature = hmac.new(
+                self._config.secret.get_secret_value().encode(),
+                body.encode(),
+                hashlib.sha256,
+            ).hexdigest()
+            headers["X-RoomKit-Signature"] = signature
+        return headers
+
+    @staticmethod
+    def _parse_response(data: dict[str, Any]) -> ProviderResult:
+        return ProviderResult(
+            success=True,
+            provider_message_id=data.get("message_id"),
+        )
+
+    @staticmethod
+    def _extract_text(event: RoomEvent) -> str:
+        content = event.content
+        if isinstance(content, TextContent):
+            return content.body
+        if hasattr(content, "body"):
+            return str(content.body)
+        return ""
+
+    async def close(self) -> None:
+        await self._client.aclose()

roomkit/providers/http/webhook.py

@@ -0,0 +1,33 @@
+"""Inbound HTTP webhook parser."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from roomkit.models.delivery import InboundMessage
+from roomkit.models.event import TextContent
+
+
+def parse_http_webhook(
+    payload: dict[str, Any],
+    channel_id: str,
+) -> InboundMessage:
+    """Convert a simple JSON body into an InboundMessage.
+
+    Expected payload shape::
+
+        {
+            "sender_id": "user-123",
+            "body": "Hello!",
+            "external_id": "msg-456",   // optional
+            "metadata": {}              // optional
+        }
+    """
+    return InboundMessage(
+        channel_id=channel_id,
+        sender_id=payload["sender_id"],
+        content=TextContent(body=payload.get("body", "")),
+        external_id=payload.get("external_id"),
+        idempotency_key=payload.get("external_id"),
+        metadata=payload.get("metadata", {}),
+    )

roomkit/providers/messenger/__init__.py

@@ -0,0 +1,15 @@
+"""Facebook Messenger provider."""
+
+from roomkit.providers.messenger.base import MessengerProvider
+from roomkit.providers.messenger.config import MessengerConfig
+from roomkit.providers.messenger.facebook import FacebookMessengerProvider
+from roomkit.providers.messenger.mock import MockMessengerProvider
+from roomkit.providers.messenger.webhook import parse_messenger_webhook
+
+__all__ = [
+    "FacebookMessengerProvider",
+    "MessengerConfig",
+    "MessengerProvider",
+    "MockMessengerProvider",
+    "parse_messenger_webhook",
+]

roomkit/providers/messenger/base.py

@@ -0,0 +1,33 @@
+"""Abstract base class for Messenger providers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from roomkit.models.delivery import ProviderResult
+from roomkit.models.event import RoomEvent
+
+
+class MessengerProvider(ABC):
+    """Facebook Messenger delivery provider."""
+
+    @property
+    def name(self) -> str:
+        """Provider name."""
+        return self.__class__.__name__
+
+    @abstractmethod
+    async def send(self, event: RoomEvent, to: str) -> ProviderResult:
+        """Send a Facebook Messenger message.
+
+        Args:
+            event: The room event containing the message content.
+            to: Recipient Messenger user ID.
+
+        Returns:
+            Result with provider-specific delivery metadata.
+        """
+        ...
+
+    async def close(self) -> None:  # noqa: B027
+        """Release resources. Override in subclasses that hold connections."""

roomkit/providers/messenger/config.py

@@ -0,0 +1,17 @@
+"""Facebook Messenger provider configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, SecretStr
+
+
+class MessengerConfig(BaseModel):
+    """Facebook Messenger provider configuration."""
+
+    page_access_token: SecretStr
+    api_version: str = "v21.0"
+    timeout: float = 30.0
+
+    @property
+    def base_url(self) -> str:
+        return f"https://graph.facebook.com/{self.api_version}/me/messages"

roomkit/providers/messenger/facebook.py

@@ -0,0 +1,95 @@
+"""Facebook Messenger provider — sends messages via the Messenger Platform Send API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from roomkit.models.delivery import ProviderResult
+from roomkit.models.event import RoomEvent, TextContent
+from roomkit.providers.messenger.base import MessengerProvider
+from roomkit.providers.messenger.config import MessengerConfig
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class FacebookMessengerProvider(MessengerProvider):
+    """Send messages via the Facebook Messenger Platform Send API."""
+
+    def __init__(self, config: MessengerConfig) -> None:
+        try:
+            import httpx as _httpx
+        except ImportError as exc:
+            raise ImportError(
+                "httpx is required for FacebookMessengerProvider. "
+                "Install it with: pip install roomkit[httpx]"
+            ) from exc
+        self._config = config
+        self._httpx = _httpx
+        self._client: httpx.AsyncClient = _httpx.AsyncClient(
+            timeout=config.timeout,
+        )
+
+    async def send(self, event: RoomEvent, to: str) -> ProviderResult:
+        text = self._extract_text(event)
+        if not text:
+            return ProviderResult(success=False, error="empty_message")
+
+        payload: dict[str, Any] = {
+            "recipient": {"id": to},
+            "messaging_type": "RESPONSE",
+            "message": {"text": text},
+        }
+
+        try:
+            resp = await self._client.post(
+                self._config.base_url,
+                json=payload,
+                params={
+                    "access_token": self._config.page_access_token.get_secret_value(),
+                },
+            )
+            resp.raise_for_status()
+            data = resp.json()
+        except self._httpx.TimeoutException:
+            return ProviderResult(success=False, error="timeout")
+        except self._httpx.HTTPStatusError as exc:
+            return self._parse_error(exc)
+        except self._httpx.HTTPError as exc:
+            return ProviderResult(success=False, error=str(exc))
+
+        return ProviderResult(
+            success=True,
+            provider_message_id=data.get("message_id"),
+        )
+
+    @staticmethod
+    def _parse_error(exc: Any) -> ProviderResult:
+        """Extract a Facebook Graph API error message when available."""
+        try:
+            body = exc.response.json()
+            error = body.get("error", {})
+            code = error.get("code", exc.response.status_code)
+            message = error.get("message", "")
+            return ProviderResult(
+                success=False,
+                error=f"graph_{code}",
+                metadata={"message": message},
+            )
+        except Exception:
+            return ProviderResult(
+                success=False,
+                error=f"http_{exc.response.status_code}",
+            )
+
+    @staticmethod
+    def _extract_text(event: RoomEvent) -> str:
+        content = event.content
+        if isinstance(content, TextContent):
+            return content.body
+        if hasattr(content, "body"):
+            return str(content.body)
+        return ""
+
+    async def close(self) -> None:
+        await self._client.aclose()

roomkit/providers/messenger/mock.py

@@ -0,0 +1,21 @@
+"""Mock Messenger provider for testing."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from roomkit.models.delivery import ProviderResult
+from roomkit.models.event import RoomEvent
+from roomkit.providers.messenger.base import MessengerProvider
+
+
+class MockMessengerProvider(MessengerProvider):
+    """Records sent messages for verification in tests."""
+
+    def __init__(self) -> None:
+        self.sent: list[dict[str, Any]] = []
+
+    async def send(self, event: RoomEvent, to: str) -> ProviderResult:
+        self.sent.append({"event": event, "to": to})
+        return ProviderResult(success=True, provider_message_id=uuid4().hex)

roomkit/providers/messenger/webhook.py

@@ -0,0 +1,42 @@
+"""Facebook Messenger webhook parsing helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from roomkit.models.delivery import InboundMessage
+from roomkit.models.event import TextContent
+
+
+def parse_messenger_webhook(
+    payload: dict[str, Any],
+    channel_id: str,
+) -> list[InboundMessage]:
+    """Convert a Facebook Messenger webhook payload into InboundMessages.
+
+    Facebook sends batches of events under ``payload["entry"]``.  Each entry
+    contains a ``messaging`` list with individual messages.  Only messages that
+    carry a ``message.text`` field are returned; delivery/read receipts and
+    postbacks are silently skipped.
+    """
+    messages: list[InboundMessage] = []
+    for entry in payload.get("entry", []):
+        for event in entry.get("messaging", []):
+            msg = event.get("message")
+            if msg is None or "text" not in msg:
+                continue
+            sender_id = event.get("sender", {}).get("id", "")
+            messages.append(
+                InboundMessage(
+                    channel_id=channel_id,
+                    sender_id=sender_id,
+                    content=TextContent(body=msg["text"]),
+                    external_id=msg.get("mid"),
+                    idempotency_key=msg.get("mid"),
+                    metadata={
+                        "recipient_id": event.get("recipient", {}).get("id", ""),
+                        "timestamp": event.get("timestamp", 0),
+                    },
+                )
+            )
+    return messages

roomkit/providers/openai/__init__.py

@@ -0,0 +1,6 @@
+"""OpenAI provider."""
+
+from roomkit.providers.openai.ai import OpenAIAIProvider
+from roomkit.providers.openai.config import OpenAIConfig
+
+__all__ = ["OpenAIAIProvider", "OpenAIConfig"]

roomkit/providers/openai/ai.py

@@ -0,0 +1,155 @@
+"""OpenAI AI provider — generates responses via the OpenAI Chat Completions API."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from roomkit.providers.ai.base import (
+    AIContext,
+    AIImagePart,
+    AIProvider,
+    AIResponse,
+    AITextPart,
+    AIToolCall,
+    ProviderError,
+)
+from roomkit.providers.openai.config import OpenAIConfig
+
+# OpenAI models that support vision
+_VISION_MODELS = (
+    "gpt-4o",
+    "gpt-4-turbo",
+    "gpt-4-vision",
+    "o1",
+    "o3",
+)
+
+
+class OpenAIAIProvider(AIProvider):
+    """AI provider using the OpenAI Chat Completions API."""
+
+    def __init__(self, config: OpenAIConfig) -> None:
+        try:
+            import openai as _openai
+        except ImportError as exc:
+            raise ImportError(
+                "openai is required for OpenAIAIProvider. "
+                "Install it with: pip install roomkit[openai]"
+            ) from exc
+        self._config = config
+        self._api_status_error = _openai.APIStatusError
+        self._client = _openai.AsyncOpenAI(
+            api_key=config.api_key.get_secret_value(),
+            base_url=config.base_url,
+        )
+
+    @property
+    def model_name(self) -> str:
+        return self._config.model
+
+    @property
+    def supports_vision(self) -> bool:
+        """GPT-4o and GPT-4-turbo models support vision."""
+        return any(self._config.model.startswith(prefix) for prefix in _VISION_MODELS)
+
+    def _format_content(
+        self, content: str | list[AITextPart | AIImagePart]
+    ) -> str | list[dict[str, Any]]:
+        """Format message content for OpenAI API.
+
+        Converts AITextPart/AIImagePart to OpenAI's content block format.
+        """
+        if isinstance(content, str):
+            return content
+
+        parts: list[dict[str, Any]] = []
+        for part in content:
+            if isinstance(part, AITextPart):
+                parts.append({"type": "text", "text": part.text})
+            elif isinstance(part, AIImagePart):
+                parts.append(
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": part.url},
+                    }
+                )
+        return parts
+
+    async def generate(self, context: AIContext) -> AIResponse:
+        messages: list[dict[str, Any]] = []
+        if context.system_prompt:
+            messages.append({"role": "system", "content": context.system_prompt})
+        messages.extend(
+            {"role": m.role, "content": self._format_content(m.content)} for m in context.messages
+        )
+
+        kwargs: dict[str, Any] = {
+            "model": self._config.model,
+            "max_tokens": context.max_tokens or self._config.max_tokens,
+            "messages": messages,
+        }
+        if context.temperature is not None:
+            kwargs["temperature"] = context.temperature
+
+        # Add tools if provided
+        if context.tools:
+            kwargs["tools"] = [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": t.name,
+                        "description": t.description,
+                        "parameters": t.parameters,
+                    },
+                }
+                for t in context.tools
+            ]
+
+        try:
+            response = await self._client.chat.completions.create(**kwargs)
+        except ProviderError:
+            raise
+        except self._api_status_error as exc:
+            retryable = exc.status_code in (429, 500, 502, 503)
+            raise ProviderError(
+                str(exc),
+                retryable=retryable,
+                provider="openai",
+                status_code=exc.status_code,
+            ) from exc
+        except Exception as exc:
+            raise ProviderError(
+                str(exc),
+                retryable=False,
+                provider="openai",
+                status_code=None,
+            ) from exc
+
+        choice = response.choices[0]
+        usage: dict[str, int] = {}
+        if response.usage:
+            usage = {
+                "prompt_tokens": response.usage.prompt_tokens,
+                "completion_tokens": response.usage.completion_tokens,
+            }
+
+        # Extract tool calls from response
+        tool_calls: list[AIToolCall] = []
+        if choice.message.tool_calls:
+            for tc in choice.message.tool_calls:
+                tool_calls.append(
+                    AIToolCall(
+                        id=tc.id,
+                        name=tc.function.name,
+                        arguments=json.loads(tc.function.arguments),
+                    )
+                )
+
+        return AIResponse(
+            content=choice.message.content or "",
+            finish_reason=choice.finish_reason,
+            usage=usage,
+            metadata={"model": response.model},
+            tool_calls=tool_calls,
+        )

roomkit/providers/openai/config.py

@@ -0,0 +1,24 @@
+"""OpenAI provider configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, SecretStr
+
+
+class OpenAIConfig(BaseModel):
+    """OpenAI AI provider configuration.
+
+    Attributes:
+        api_key: API key for authentication.
+        base_url: Custom base URL for OpenAI-compatible APIs (e.g., Ollama, LM Studio,
+            Azure OpenAI, or other providers). If None, uses the default OpenAI API.
+        model: Model identifier to use.
+        max_tokens: Maximum tokens in the response.
+        temperature: Sampling temperature.
+    """
+
+    api_key: SecretStr
+    base_url: str | None = None
+    model: str = "gpt-4o"
+    max_tokens: int = 1024
+    temperature: float = 0.7

roomkit/providers/pydantic_ai/__init__.py

@@ -0,0 +1,5 @@
+"""Pydantic AI provider."""
+
+from roomkit.providers.pydantic_ai.config import PydanticAIConfig
+
+__all__ = ["PydanticAIConfig"]

roomkit/providers/pydantic_ai/config.py

@@ -0,0 +1,14 @@
+"""Pydantic AI provider configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, SecretStr
+
+
+class PydanticAIConfig(BaseModel):
+    """Pydantic AI provider configuration."""
+
+    model: str = "openai:gpt-4o"
+    api_key: SecretStr | None = None
+    temperature: float = 0.7
+    max_tokens: int = 1024

roomkit/providers/rcs/__init__.py

@@ -0,0 +1,9 @@
+"""RCS providers for rich communication services."""
+
+from roomkit.providers.rcs.base import RCSProvider
+from roomkit.providers.rcs.mock import MockRCSProvider
+
+__all__ = [
+    "RCSProvider",
+    "MockRCSProvider",
+]

roomkit/providers/rcs/base.py

@@ -0,0 +1,95 @@
+"""Abstract base class for RCS providers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from roomkit.models.delivery import InboundMessage, ProviderResult
+from roomkit.models.event import RoomEvent
+
+
+class RCSDeliveryResult(ProviderResult):
+    """Extended result for RCS delivery with fallback information."""
+
+    channel_used: str = "rcs"  # "rcs" or "sms" if fallback occurred
+    fallback: bool = False
+
+
+class RCSProvider(ABC):
+    """RCS delivery provider for rich communication services."""
+
+    @property
+    def name(self) -> str:
+        """Provider name (e.g. 'twilio', 'sinch')."""
+        return self.__class__.__name__
+
+    @property
+    @abstractmethod
+    def sender_id(self) -> str:
+        """RCS sender/agent identifier."""
+        ...
+
+    @property
+    def supports_fallback(self) -> bool:
+        """Whether this provider supports automatic SMS fallback."""
+        return True
+
+    @abstractmethod
+    async def send(
+        self,
+        event: RoomEvent,
+        to: str,
+        *,
+        fallback: bool = True,
+    ) -> RCSDeliveryResult:
+        """Send an RCS message.
+
+        Args:
+            event: The room event containing the message content.
+            to: Recipient phone number (E.164 format).
+            fallback: If True, allow fallback to SMS when RCS unavailable.
+
+        Returns:
+            Result with delivery info including whether fallback occurred.
+        """
+        ...
+
+    async def check_capability(self, phone_number: str) -> bool:
+        """Check if a phone number supports RCS.
+
+        Args:
+            phone_number: Phone number to check (E.164 format).
+
+        Returns:
+            True if the number supports RCS, False otherwise.
+
+        Raises:
+            NotImplementedError: If the provider doesn't support capability check.
+        """
+        raise NotImplementedError(f"{self.name} does not support RCS capability checking")
+
+    async def parse_webhook(self, payload: dict[str, Any]) -> InboundMessage:
+        """Parse an inbound webhook payload into an InboundMessage."""
+        raise NotImplementedError
+
+    def verify_signature(
+        self,
+        payload: bytes,
+        signature: str,
+        timestamp: str | None = None,
+    ) -> bool:
+        """Verify that a webhook payload was signed by the provider.
+
+        Args:
+            payload: Raw request body bytes.
+            signature: Signature header value from the webhook request.
+            timestamp: Timestamp header value (required by some providers).
+
+        Returns:
+            True if the signature is valid, False otherwise.
+        """
+        raise NotImplementedError(f"{self.name} does not support webhook signature verification")
+
+    async def close(self) -> None:  # noqa: B027
+        """Release resources. Override in subclasses that hold connections."""