roomkit 0.1.0__py3-none-any.whl

roomkit/models/event.py

@@ -0,0 +1,203 @@
+"""Event and content models."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Annotated, Any, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from roomkit.models.enums import (
+    ChannelDirection,
+    ChannelType,
+    EventStatus,
+    EventType,
+)
+
+
+class TextContent(BaseModel):
+    """Plain text message content."""
+
+    type: Literal["text"] = "text"
+    body: str
+    language: str | None = None
+
+
+class RichContent(BaseModel):
+    """Rich formatted content (HTML/Markdown)."""
+
+    type: Literal["rich"] = "rich"
+    body: str
+    format: Literal["html", "markdown"] = "markdown"
+    plain_text: str | None = None
+    buttons: list[dict[str, Any]] = Field(default_factory=list)
+    cards: list[dict[str, Any]] = Field(default_factory=list)
+    quick_replies: list[str] = Field(default_factory=list)
+
+
+class MediaContent(BaseModel):
+    """Media attachment content."""
+
+    type: Literal["media"] = "media"
+    url: str
+    mime_type: str
+    filename: str | None = None
+    size_bytes: int | None = Field(default=None, ge=0)
+    caption: str | None = None
+
+    @field_validator("url")
+    @classmethod
+    def _validate_url(cls, v: str) -> str:
+        if not v.startswith(("http://", "https://")):
+            raise ValueError("URL must start with http:// or https://")
+        return v
+
+
+class LocationContent(BaseModel):
+    """Geographic location content."""
+
+    type: Literal["location"] = "location"
+    latitude: float = Field(ge=-90.0, le=90.0)
+    longitude: float = Field(ge=-180.0, le=180.0)
+    label: str | None = None
+    address: str | None = None
+
+
+class AudioContent(BaseModel):
+    """Audio message content."""
+
+    type: Literal["audio"] = "audio"
+    url: str
+    mime_type: str = "audio/ogg"
+    duration_seconds: float | None = Field(default=None, ge=0.0)
+    transcript: str | None = None
+
+    @field_validator("url")
+    @classmethod
+    def _validate_url(cls, v: str) -> str:
+        if not v.startswith(("http://", "https://")):
+            raise ValueError("URL must start with http:// or https://")
+        return v
+
+
+class VideoContent(BaseModel):
+    """Video message content."""
+
+    type: Literal["video"] = "video"
+    url: str
+    mime_type: str = "video/mp4"
+    duration_seconds: float | None = Field(default=None, ge=0.0)
+    thumbnail_url: str | None = None
+
+    @field_validator("url", "thumbnail_url")
+    @classmethod
+    def _validate_url(cls, v: str | None) -> str | None:
+        if v is not None and not v.startswith(("http://", "https://")):
+            raise ValueError("URL must start with http:// or https://")
+        return v
+
+
+class CompositeContent(BaseModel):
+    """Multi-part content combining multiple content types."""
+
+    type: Literal["composite"] = "composite"
+    parts: list[EventContent]
+
+    @model_validator(mode="after")
+    def _validate_parts(self) -> CompositeContent:
+        if not self.parts:
+            raise ValueError("CompositeContent must have at least one part")
+        depth = self._nesting_depth(self)
+        if depth > 5:
+            raise ValueError(f"CompositeContent nesting depth {depth} exceeds maximum of 5")
+        return self
+
+    @staticmethod
+    def _nesting_depth(content: object, current: int = 1) -> int:
+        """Recursively compute nesting depth of CompositeContent."""
+        if not isinstance(content, CompositeContent):
+            return 0
+        max_child = 0
+        for part in content.parts:
+            child_depth = CompositeContent._nesting_depth(part, current + 1)
+            if child_depth > max_child:
+                max_child = child_depth
+        return 1 + max_child
+
+
+class SystemContent(BaseModel):
+    """System-generated content."""
+
+    type: Literal["system"] = "system"
+    body: str
+    code: str | None = None
+    data: dict[str, Any] = Field(default_factory=dict)
+
+
+class TemplateContent(BaseModel):
+    """Pre-approved template content (WhatsApp Business, etc.)."""
+
+    type: Literal["template"] = "template"
+    template_id: str
+    language: str = "en"
+    parameters: dict[str, str] = Field(default_factory=dict)
+    body: str | None = None
+
+
+EventContent = Annotated[
+    TextContent
+    | RichContent
+    | MediaContent
+    | LocationContent
+    | AudioContent
+    | VideoContent
+    | CompositeContent
+    | SystemContent
+    | TemplateContent,
+    Field(discriminator="type"),
+]
+
+
+class ChannelData(BaseModel):
+    """Provider-specific channel metadata."""
+
+    provider: str | None = None
+    external_id: str | None = None
+    thread_id: str | None = None
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+class EventSource(BaseModel):
+    """Origin information for an event."""
+
+    channel_id: str
+    channel_type: ChannelType
+    direction: ChannelDirection = ChannelDirection.INBOUND
+    participant_id: str | None = None
+    external_id: str | None = None
+    provider: str | None = None
+    raw_payload: dict[str, Any] = Field(default_factory=dict)
+    provider_message_id: str | None = None
+
+
+class RoomEvent(BaseModel):
+    """A single event in a room conversation."""
+
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    room_id: str
+    type: EventType = EventType.MESSAGE
+    source: EventSource
+    content: EventContent
+    status: EventStatus = EventStatus.PENDING
+    blocked_by: str | None = None
+    visibility: str = "all"
+    index: int = Field(default=0, ge=0)
+    chain_depth: int = Field(default=0, ge=0)
+    parent_event_id: str | None = None
+    correlation_id: str | None = None
+    idempotency_key: str | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    channel_data: ChannelData = Field(default_factory=ChannelData)
+    delivery_results: dict[str, Any] = Field(default_factory=dict)

roomkit/models/framework_event.py

@@ -0,0 +1,19 @@
+"""Framework-level event model."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class FrameworkEvent(BaseModel):
+    """An event emitted by the framework for observability."""
+
+    type: str
+    room_id: str | None = None
+    channel_id: str | None = None
+    event_id: str | None = None
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    data: dict[str, Any] = Field(default_factory=dict)

roomkit/models/hook.py

@@ -0,0 +1,68 @@
+"""Hook-related models."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from roomkit.models.event import RoomEvent
+from roomkit.models.task import Observation, Task
+
+
+class InjectedEvent(BaseModel):
+    """An event injected by a hook as a side effect."""
+
+    event: RoomEvent
+    target_channel_ids: list[str] | None = None
+
+
+class HookResult(BaseModel):
+    """Result returned by a sync hook."""
+
+    action: Literal["allow", "block", "modify"]
+    event: RoomEvent | None = None
+    reason: str | None = None
+    injected_events: list[InjectedEvent] = Field(default_factory=list)
+    tasks: list[Task] = Field(default_factory=list)
+    observations: list[Observation] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _validate_action_fields(self) -> HookResult:
+        if self.action == "modify" and self.event is None:
+            raise ValueError("action='modify' requires 'event' to be set")
+        if self.action == "block" and self.reason is None:
+            raise ValueError("action='block' requires 'reason' to be set")
+        return self
+
+    @classmethod
+    def allow(cls, injected: list[InjectedEvent] | None = None) -> HookResult:
+        """Allow the event to proceed."""
+        return cls(action="allow", injected_events=injected or [])
+
+    @classmethod
+    def block(
+        cls,
+        reason: str,
+        injected: list[InjectedEvent] | None = None,
+        tasks: list[Task] | None = None,
+        observations: list[Observation] | None = None,
+    ) -> HookResult:
+        """Block the event from proceeding."""
+        return cls(
+            action="block",
+            reason=reason,
+            injected_events=injected or [],
+            tasks=tasks or [],
+            observations=observations or [],
+        )
+
+    @classmethod
+    def modify(
+        cls,
+        event: RoomEvent,
+        injected: list[InjectedEvent] | None = None,
+    ) -> HookResult:
+        """Modify the event before it proceeds."""
+        return cls(action="modify", event=event, injected_events=injected or [])

roomkit/models/identity.py

@@ -0,0 +1,81 @@
+"""Identity and identification models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from roomkit.models.enums import IdentificationStatus
+from roomkit.models.hook import InjectedEvent
+
+
+class Identity(BaseModel):
+    """A resolved user identity."""
+
+    id: str
+    organization_id: str | None = None
+    display_name: str | None = None
+    email: str | None = None
+    phone: str | None = None
+    channel_addresses: dict[str, list[str]] = Field(default_factory=dict)
+    external_id: str | None = None
+    external_ids: dict[str, str] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class IdentityResult(BaseModel):
+    """Result of identity resolution."""
+
+    status: IdentificationStatus
+    identity: Identity | None = None
+    candidates: list[Identity] = Field(default_factory=list)
+    address: str | None = None
+    channel_type: str | None = None
+    challenge_type: str | None = None
+    message: str | None = None
+
+
+class IdentityHookResult(BaseModel):
+    """Result from an identity resolution hook."""
+
+    status: IdentificationStatus
+    identity: Identity | None = None
+    display_name: str | None = None
+    candidates: list[Identity] | None = None
+    inject: InjectedEvent | None = None
+    reason: str | None = None
+    challenge_type: str | None = None
+    message: str | None = None
+
+    @classmethod
+    def resolved(cls, identity: Identity) -> IdentityHookResult:
+        """Resolved - we know who this is."""
+        return cls(status=IdentificationStatus.IDENTIFIED, identity=identity)
+
+    @classmethod
+    def pending(
+        cls,
+        display_name: str | None = None,
+        candidates: list[Identity] | None = None,
+    ) -> IdentityHookResult:
+        """Pending - create participant with status=pending. Advisor resolves later."""
+        return cls(
+            status=IdentificationStatus.PENDING,
+            display_name=display_name,
+            candidates=candidates,
+        )
+
+    @classmethod
+    def challenge(cls, inject: InjectedEvent, message: str | None = None) -> IdentityHookResult:
+        """Challenge - hold the message, ask the sender to self-identify."""
+        return cls(
+            status=IdentificationStatus.CHALLENGE_SENT,
+            inject=inject,
+            message=message,
+        )
+
+    @classmethod
+    def reject(cls, reason: str = "Unknown sender") -> IdentityHookResult:
+        """Reject - do not create room or participant."""
+        return cls(status=IdentificationStatus.REJECTED, reason=reason)

roomkit/models/participant.py

@@ -0,0 +1,34 @@
+"""Participant model."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from roomkit.models.enums import (
+    IdentificationStatus,
+    ParticipantRole,
+    ParticipantStatus,
+)
+
+
+class Participant(BaseModel):
+    """A participant in a room conversation."""
+
+    id: str
+    room_id: str
+    channel_id: str
+    display_name: str | None = None
+    role: ParticipantRole = ParticipantRole.MEMBER
+    status: ParticipantStatus = ParticipantStatus.ACTIVE
+    identification: IdentificationStatus = IdentificationStatus.PENDING
+    identity_id: str | None = None
+    candidates: list[str] | None = None
+    connected_via: list[str] = Field(default_factory=list)
+    external_id: str | None = None
+    resolved_at: datetime | None = None
+    resolved_by: str | None = None
+    joined_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    metadata: dict[str, Any] = Field(default_factory=dict)

roomkit/models/room.py

@@ -0,0 +1,33 @@
+"""Room model."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from roomkit.models.enums import RoomStatus
+
+
+class RoomTimers(BaseModel):
+    """Timer configuration for a room."""
+
+    inactive_after_seconds: int | None = Field(default=None, ge=0)
+    closed_after_seconds: int | None = Field(default=None, ge=0)
+    last_activity_at: datetime | None = None
+
+
+class Room(BaseModel):
+    """A conversation room."""
+
+    id: str
+    organization_id: str | None = None
+    status: RoomStatus = RoomStatus.ACTIVE
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    closed_at: datetime | None = None
+    timers: RoomTimers = Field(default_factory=RoomTimers)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    event_count: int = Field(default=0, ge=0)
+    latest_index: int = Field(default=0, ge=0)

roomkit/models/task.py

@@ -0,0 +1,36 @@
+"""Task and observation models."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from roomkit.models.enums import TaskStatus
+
+
+class Task(BaseModel):
+    """A task assigned within a room."""
+
+    id: str
+    room_id: str
+    title: str
+    description: str | None = None
+    assigned_to: str | None = None
+    status: TaskStatus = TaskStatus.PENDING
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Observation(BaseModel):
+    """An observation produced by an intelligence channel."""
+
+    id: str
+    room_id: str
+    channel_id: str
+    content: str
+    category: str | None = None
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    metadata: dict[str, Any] = Field(default_factory=dict)

roomkit/providers/ai/base.py

@@ -0,0 +1,140 @@
+"""Abstract base class for AI providers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from roomkit.models.channel import ChannelCapabilities
+from roomkit.models.context import RoomContext
+from roomkit.models.enums import ChannelMediaType
+from roomkit.models.task import Observation, Task
+
+
+class AITextPart(BaseModel):
+    """Text part of a multimodal message."""
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+class AIImagePart(BaseModel):
+    """Image part of a multimodal message."""
+
+    type: Literal["image"] = "image"
+    url: str
+    mime_type: str | None = None
+
+
+class AITool(BaseModel):
+    """Tool definition for function calling."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any] = Field(default_factory=dict)
+
+
+class AIToolCall(BaseModel):
+    """A tool call from the AI response."""
+
+    id: str
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+class ProviderError(Exception):
+    """Error from an AI provider SDK call.
+
+    Attributes:
+        retryable: Whether the caller should retry the request.
+        provider: Name of the provider that raised the error.
+        status_code: HTTP status code from the provider, if available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retryable: bool = False,
+        provider: str = "",
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.retryable = retryable
+        self.provider = provider
+        self.status_code = status_code
+
+
+class AIMessage(BaseModel):
+    """A message in the AI conversation context."""
+
+    role: str  # "system", "user", "assistant"
+    content: str | list[AITextPart | AIImagePart]
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AIContext(BaseModel):
+    """Context passed to AI provider for generation."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    messages: list[AIMessage] = Field(default_factory=list)
+    system_prompt: str | None = None
+    temperature: float = 0.7
+    max_tokens: int = 1024
+    tools: list[AITool] = Field(default_factory=list)
+    room: RoomContext | None = None
+    target_capabilities: ChannelCapabilities | None = None
+    target_media_types: list[ChannelMediaType] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AIResponse(BaseModel):
+    """Response from an AI provider."""
+
+    content: str
+    finish_reason: str | None = None
+    usage: dict[str, int] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    tasks: list[Task] = Field(default_factory=list)
+    observations: list[Observation] = Field(default_factory=list)
+    tool_calls: list[AIToolCall] = Field(default_factory=list)
+
+
+class AIProvider(ABC):
+    """AI model provider for generating responses."""
+
+    @property
+    def name(self) -> str:
+        """Provider name (e.g. 'anthropic', 'openai')."""
+        return self.__class__.__name__
+
+    @property
+    def supports_vision(self) -> bool:
+        """Whether this provider can process images."""
+        return False
+
+    @property
+    @abstractmethod
+    def model_name(self) -> str:
+        """Model identifier (e.g. 'claude-sonnet-4-20250514', 'gpt-4o')."""
+        ...
+
+    @abstractmethod
+    async def generate(self, context: AIContext) -> AIResponse:
+        """Generate an AI response from the given context.
+
+        Args:
+            context: Conversation context including messages, system prompt,
+                temperature, and target channel capabilities.
+
+        Returns:
+            The AI response with content, usage stats, and optional
+            tasks/observations.
+        """
+        ...
+
+    async def close(self) -> None:  # noqa: B027
+        """Release resources. Override in subclasses that hold connections."""

roomkit/providers/ai/mock.py

@@ -0,0 +1,33 @@
+"""Mock AI provider for testing."""
+
+from __future__ import annotations
+
+from roomkit.providers.ai.base import AIContext, AIProvider, AIResponse
+
+
+class MockAIProvider(AIProvider):
+    """Round-robin response provider for tests."""
+
+    def __init__(self, responses: list[str] | None = None, *, vision: bool = False) -> None:
+        self.responses = responses or ["Hello from AI"]
+        self.calls: list[AIContext] = []
+        self._index = 0
+        self._vision = vision
+
+    @property
+    def model_name(self) -> str:
+        return "mock"
+
+    @property
+    def supports_vision(self) -> bool:
+        return self._vision
+
+    async def generate(self, context: AIContext) -> AIResponse:
+        self.calls.append(context)
+        content = self.responses[self._index % len(self.responses)]
+        self._index += 1
+        return AIResponse(
+            content=content,
+            finish_reason="stop",
+            usage={"prompt_tokens": 10, "completion_tokens": 5},
+        )

roomkit/providers/anthropic/__init__.py

@@ -0,0 +1,6 @@
+"""Anthropic provider."""
+
+from roomkit.providers.anthropic.ai import AnthropicAIProvider
+from roomkit.providers.anthropic.config import AnthropicConfig
+
+__all__ = ["AnthropicAIProvider", "AnthropicConfig"]