roomkit 0.1.0__py3-none-any.whl

roomkit/providers/anthropic/ai.py

@@ -0,0 +1,145 @@
+"""Anthropic AI provider — generates responses via the Anthropic Messages API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from roomkit.providers.ai.base import (
+    AIContext,
+    AIImagePart,
+    AIProvider,
+    AIResponse,
+    AITextPart,
+    AIToolCall,
+    ProviderError,
+)
+from roomkit.providers.anthropic.config import AnthropicConfig
+
+# Claude models that support vision (Claude 3 and later)
+_VISION_MODELS = (
+    "claude-3",
+    "claude-sonnet-4",
+    "claude-opus-4",
+)
+
+
+class AnthropicAIProvider(AIProvider):
+    """AI provider using the Anthropic Messages API."""
+
+    def __init__(self, config: AnthropicConfig) -> None:
+        try:
+            import anthropic as _anthropic
+        except ImportError as exc:
+            raise ImportError(
+                "anthropic is required for AnthropicAIProvider. "
+                "Install it with: pip install roomkit[anthropic]"
+            ) from exc
+        self._config = config
+        self._api_status_error = _anthropic.APIStatusError
+        self._client = _anthropic.AsyncAnthropic(
+            api_key=config.api_key.get_secret_value(),
+        )
+
+    @property
+    def model_name(self) -> str:
+        return self._config.model
+
+    @property
+    def supports_vision(self) -> bool:
+        """Claude 3+ 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 Anthropic API.
+
+        Converts AITextPart/AIImagePart to Anthropic'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",
+                        "source": {
+                            "type": "url",
+                            "url": part.url,
+                        },
+                    }
+                )
+        return parts
+
+    async def generate(self, context: AIContext) -> AIResponse:
+        messages: list[dict[str, Any]] = [
+            {"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.system_prompt:
+            kwargs["system"] = context.system_prompt
+        if context.temperature is not None:
+            kwargs["temperature"] = context.temperature
+
+        # Add tools if provided
+        if context.tools:
+            kwargs["tools"] = [
+                {
+                    "name": t.name,
+                    "description": t.description,
+                    "input_schema": t.parameters,
+                }
+                for t in context.tools
+            ]
+
+        try:
+            response = await self._client.messages.create(**kwargs)
+        except self._api_status_error as exc:
+            retryable = exc.status_code in (429, 500, 502, 503, 529)
+            raise ProviderError(
+                str(exc),
+                retryable=retryable,
+                provider="anthropic",
+                status_code=exc.status_code,
+            ) from exc
+        except Exception as exc:
+            raise ProviderError(
+                str(exc),
+                retryable=False,
+                provider="anthropic",
+                status_code=None,
+            ) from exc
+
+        # Extract text content and tool calls from response
+        text_content = ""
+        tool_calls: list[AIToolCall] = []
+        for block in response.content:
+            if block.type == "text":
+                text_content = block.text
+            elif block.type == "tool_use":
+                tool_calls.append(
+                    AIToolCall(
+                        id=block.id,
+                        name=block.name,
+                        arguments=block.input,
+                    )
+                )
+
+        return AIResponse(
+            content=text_content,
+            finish_reason=response.stop_reason,
+            usage={
+                "input_tokens": response.usage.input_tokens,
+                "output_tokens": response.usage.output_tokens,
+            },
+            metadata={"model": response.model},
+            tool_calls=tool_calls,
+        )

roomkit/providers/anthropic/config.py

@@ -0,0 +1,14 @@
+"""Anthropic provider configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, SecretStr
+
+
+class AnthropicConfig(BaseModel):
+    """Anthropic AI provider configuration."""
+
+    api_key: SecretStr
+    model: str = "claude-sonnet-4-20250514"
+    max_tokens: int = 1024
+    temperature: float = 0.7

roomkit/providers/elasticemail/__init__.py

@@ -0,0 +1,6 @@
+"""Elastic Email provider."""
+
+from roomkit.providers.elasticemail.config import ElasticEmailConfig
+from roomkit.providers.elasticemail.email import ElasticEmailProvider
+
+__all__ = ["ElasticEmailConfig", "ElasticEmailProvider"]

roomkit/providers/elasticemail/config.py

@@ -0,0 +1,16 @@
+"""Elastic Email provider configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, SecretStr
+
+
+class ElasticEmailConfig(BaseModel):
+    """Elastic Email provider configuration."""
+
+    api_key: SecretStr
+    from_email: str
+    from_name: str | None = None
+    is_transactional: bool = True
+    base_url: str = "https://api.elasticemail.com/v2/email/send"
+    timeout: float = 30.0

roomkit/providers/elasticemail/email.py

@@ -0,0 +1,97 @@
+"""Elastic Email provider — sends emails via the Elastic Email v2 API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from roomkit.models.delivery import ProviderResult
+from roomkit.models.event import RichContent, RoomEvent, TextContent
+from roomkit.providers.elasticemail.config import ElasticEmailConfig
+from roomkit.providers.email.base import EmailProvider
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class ElasticEmailProvider(EmailProvider):
+    """Send-only email provider using the Elastic Email REST API."""
+
+    def __init__(self, config: ElasticEmailConfig) -> None:
+        try:
+            import httpx as _httpx
+        except ImportError as exc:
+            raise ImportError(
+                "httpx is required for ElasticEmailProvider. "
+                "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,
+        from_: str | None = None,
+        subject: str | None = None,
+    ) -> ProviderResult:
+        body_text, body_html = self._extract_body(event)
+        if not body_text and not body_html:
+            return ProviderResult(success=False, error="empty_message")
+
+        data: dict[str, Any] = {
+            "apikey": self._config.api_key.get_secret_value(),
+            "from": from_ or self._config.from_email,
+            "to": to,
+            "subject": subject or "",
+            "bodyText": body_text,
+            "bodyHtml": body_html,
+            "isTransactional": str(self._config.is_transactional).lower(),
+        }
+        if self._config.from_name:
+            data["fromName"] = self._config.from_name
+
+        try:
+            resp = await self._client.post(self._config.base_url, data=data)
+            resp.raise_for_status()
+            result = 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(result)
+
+    @staticmethod
+    def _parse_response(data: dict[str, Any]) -> ProviderResult:
+        if data.get("success"):
+            return ProviderResult(
+                success=True,
+                provider_message_id=data.get("data", {}).get("transactionid"),
+            )
+        return ProviderResult(
+            success=False,
+            error=data.get("error", "unknown_error"),
+        )
+
+    @staticmethod
+    def _extract_body(event: RoomEvent) -> tuple[str, str]:
+        """Return ``(body_text, body_html)`` from the event content."""
+        content = event.content
+        if isinstance(content, RichContent):
+            return "", content.body
+        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/email/base.py

@@ -0,0 +1,46 @@
+"""Abstract base class for email 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 EmailProvider(ABC):
+    """Email delivery provider."""
+
+    @property
+    def name(self) -> str:
+        """Provider name (e.g. 'sendgrid', 'ses')."""
+        return self.__class__.__name__
+
+    @abstractmethod
+    async def send(
+        self,
+        event: RoomEvent,
+        to: str,
+        from_: str | None = None,
+        subject: str | None = None,
+    ) -> ProviderResult:
+        """Send an email message.
+
+        Args:
+            event: The room event containing the message content.
+            to: Recipient email address.
+            from_: Sender email address override.
+            subject: Email subject line.
+
+        Returns:
+            Result with provider-specific delivery metadata.
+        """
+        ...
+
+    async def parse_inbound(self, payload: dict[str, Any]) -> InboundMessage:
+        """Parse an inbound email payload into an InboundMessage."""
+        raise NotImplementedError
+
+    async def close(self) -> None:  # noqa: B027
+        """Release resources. Override in subclasses that hold connections."""

roomkit/providers/email/mock.py

@@ -0,0 +1,34 @@
+"""Mock email 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.email.base import EmailProvider
+
+
+class MockEmailProvider(EmailProvider):
+    """Records sent emails for verification in tests."""
+
+    def __init__(self) -> None:
+        self.sent: list[dict[str, Any]] = []
+
+    async def send(
+        self,
+        event: RoomEvent,
+        to: str,
+        from_: str | None = None,
+        subject: str | None = None,
+    ) -> ProviderResult:
+        self.sent.append(
+            {
+                "event": event,
+                "to": to,
+                "from": from_ or "",
+                "subject": subject or "",
+            }
+        )
+        return ProviderResult(success=True, provider_message_id=uuid4().hex)

roomkit/providers/gemini/__init__.py

@@ -0,0 +1,6 @@
+"""Google Gemini provider."""
+
+from roomkit.providers.gemini.ai import GeminiAIProvider
+from roomkit.providers.gemini.config import GeminiConfig
+
+__all__ = ["GeminiAIProvider", "GeminiConfig"]

roomkit/providers/gemini/ai.py

@@ -0,0 +1,153 @@
+"""Google Gemini AI provider — generates responses via the Google Generative AI API."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, cast
+
+from roomkit.providers.ai.base import (
+    AIContext,
+    AIImagePart,
+    AIMessage,
+    AIProvider,
+    AIResponse,
+    AITextPart,
+    AIToolCall,
+    ProviderError,
+)
+from roomkit.providers.gemini.config import GeminiConfig
+
+
+class GeminiAIProvider(AIProvider):
+    """AI provider using the Google Gemini API."""
+
+    def __init__(self, config: GeminiConfig) -> None:
+        try:
+            from google import genai as _genai
+            from google.genai import types as _types
+        except ImportError as exc:
+            raise ImportError(
+                "google-genai is required for GeminiAIProvider. "
+                "Install it with: pip install roomkit[gemini]"
+            ) from exc
+
+        self._config = config
+        self._genai = _genai
+        self._types = _types
+        self._client = _genai.Client(api_key=config.api_key.get_secret_value())
+
+    @property
+    def model_name(self) -> str:
+        return self._config.model
+
+    @property
+    def supports_vision(self) -> bool:
+        """All Gemini models support vision."""
+        return True
+
+    def _format_messages(self, messages: list[AIMessage]) -> list[Any]:
+        """Convert AIMessage list to Gemini Content format."""
+        contents = []
+        for msg in messages:
+            role = "model" if msg.role == "assistant" else "user"
+            parts = self._format_content(msg.content)
+            contents.append(self._types.Content(role=role, parts=parts))
+        return contents
+
+    def _format_content(self, content: str | list[AITextPart | AIImagePart]) -> list[Any]:
+        """Convert content to Gemini Parts."""
+        if isinstance(content, str):
+            return [self._types.Part.from_text(text=content)]
+
+        parts = []
+        for item in content:
+            if isinstance(item, AITextPart):
+                parts.append(self._types.Part.from_text(text=item.text))
+            elif isinstance(item, AIImagePart):
+                parts.append(
+                    self._types.Part.from_uri(
+                        file_uri=item.url,
+                        mime_type=item.mime_type or "image/jpeg",
+                    )
+                )
+        return parts
+
+    def _extract_tool_calls(self, response: Any) -> list[AIToolCall]:
+        """Extract tool calls from Gemini response."""
+        tool_calls: list[AIToolCall] = []
+        if not response.candidates:
+            return tool_calls
+
+        for part in response.candidates[0].content.parts:
+            if hasattr(part, "function_call") and part.function_call:
+                fc = part.function_call
+                tool_calls.append(
+                    AIToolCall(
+                        id=fc.name,  # Gemini doesn't provide separate IDs
+                        name=fc.name,
+                        arguments=dict(fc.args) if fc.args else {},
+                    )
+                )
+        return tool_calls
+
+    async def generate(self, context: AIContext) -> AIResponse:
+        # Build generation config
+        gen_config = self._types.GenerateContentConfig(
+            temperature=context.temperature,
+            max_output_tokens=context.max_tokens,
+        )
+
+        if context.system_prompt:
+            gen_config.system_instruction = context.system_prompt
+
+        # Add tools if provided
+        if context.tools:
+            func_decls = [
+                self._types.FunctionDeclaration(
+                    name=t.name,
+                    description=t.description,
+                    # Cast to Any: Gemini SDK accepts dict as Schema at runtime
+                    parameters=cast(Any, t.parameters) if t.parameters else None,
+                )
+                for t in context.tools
+            ]
+            gen_config.tools = [self._types.Tool(function_declarations=func_decls)]
+
+        # Format messages
+        contents = self._format_messages(context.messages)
+
+        try:
+            # Generate (sync API, wrap in executor for async)
+            response = await asyncio.to_thread(
+                self._client.models.generate_content,
+                model=self._config.model,
+                contents=contents,
+                config=gen_config,
+            )
+        except Exception as exc:
+            # Check for rate limit or server errors
+            exc_str = str(exc).lower()
+            retryable = any(
+                term in exc_str for term in ["rate", "limit", "429", "500", "502", "503"]
+            )
+            raise ProviderError(
+                str(exc),
+                retryable=retryable,
+                provider="gemini",
+                status_code=None,
+            ) from exc
+
+        # Extract usage metadata
+        usage: dict[str, int] = {}
+        if response.usage_metadata:
+            usage = {
+                "prompt_tokens": response.usage_metadata.prompt_token_count or 0,
+                "completion_tokens": response.usage_metadata.candidates_token_count or 0,
+            }
+
+        return AIResponse(
+            content=response.text or "",
+            usage=usage,
+            tool_calls=self._extract_tool_calls(response),
+            metadata={"model": self._config.model},
+        )

roomkit/providers/gemini/config.py

@@ -0,0 +1,14 @@
+"""Google Gemini provider configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, SecretStr
+
+
+class GeminiConfig(BaseModel):
+    """Google Gemini AI provider configuration."""
+
+    api_key: SecretStr
+    model: str = "gemini-2.0-flash"
+    max_tokens: int = 1024
+    temperature: float = 1.0  # Gemini default

roomkit/providers/http/__init__.py

@@ -0,0 +1,15 @@
+"""Generic HTTP webhook provider."""
+
+from roomkit.providers.http.base import HTTPProvider
+from roomkit.providers.http.config import HTTPProviderConfig
+from roomkit.providers.http.mock import MockHTTPProvider
+from roomkit.providers.http.provider import WebhookHTTPProvider
+from roomkit.providers.http.webhook import parse_http_webhook
+
+__all__ = [
+    "HTTPProvider",
+    "HTTPProviderConfig",
+    "MockHTTPProvider",
+    "WebhookHTTPProvider",
+    "parse_http_webhook",
+]

roomkit/providers/http/base.py

@@ -0,0 +1,33 @@
+"""Abstract base class for HTTP providers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from roomkit.models.delivery import ProviderResult
+from roomkit.models.event import RoomEvent
+
+
+class HTTPProvider(ABC):
+    """Generic HTTP webhook delivery provider."""
+
+    @property
+    def name(self) -> str:
+        """Provider name."""
+        return self.__class__.__name__
+
+    @abstractmethod
+    async def send(self, event: RoomEvent, to: str) -> ProviderResult:
+        """Send an event via HTTP webhook.
+
+        Args:
+            event: The room event to deliver.
+            to: Target webhook URL.
+
+        Returns:
+            Result with provider-specific delivery metadata.
+        """
+        ...
+
+    async def close(self) -> None:  # noqa: B027
+        """Release resources. Override in subclasses that hold connections."""

roomkit/providers/http/config.py

@@ -0,0 +1,14 @@
+"""HTTP webhook provider configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, SecretStr
+
+
+class HTTPProviderConfig(BaseModel):
+    """Configuration for the generic HTTP webhook provider."""
+
+    webhook_url: str
+    secret: SecretStr | None = None
+    timeout: float = 30.0
+    headers: dict[str, str] = {}

roomkit/providers/http/mock.py

@@ -0,0 +1,21 @@
+"""Mock HTTP 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.http.base import HTTPProvider
+
+
+class MockHTTPProvider(HTTPProvider):
+    """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)