roomkit 0.1.0__py3-none-any.whl

roomkit/llms.txt

@@ -0,0 +1,52 @@
+# RoomKit
+
+> RoomKit is a pure async Python library for building multi-channel conversation systems.
+> It provides room-based abstractions for managing conversations across SMS, Email, WebSocket,
+> AI, and other channels with pluggable storage, identity resolution, hooks, and realtime events.
+> Python 3.12+, Pydantic 2.x, fully typed, zero required dependencies beyond Pydantic.
+
+RoomKit follows a pluggable architecture pattern where core abstractions (ConversationStore,
+RoomLockManager, RealtimeBackend, IdentityResolver) have in-memory defaults but can be replaced
+with distributed implementations (Redis, PostgreSQL, etc.) for production deployments.
+
+## Getting Started
+
+- [Features Overview](docs/features.md): Core features, channel support matrix, hooks, AI integration, resilience, identity resolution, and usage workflows
+- [Architecture](docs/architecture.md): System design, component relationships, and extension points
+
+## Core API
+
+- [RoomKit](docs/api/roomkit.md): Central orchestrator class - room lifecycle, channel management, hooks, inbound processing
+- [Hooks](docs/api/hooks.md): HookEngine, HookRegistration - event interception at BEFORE_BROADCAST, AFTER_BROADCAST, lifecycle triggers
+- [Routing](docs/api/routing.md): InboundRoomRouter - strategy for routing inbound messages to rooms
+- [Store](docs/api/store.md): ConversationStore ABC and InMemoryStore - room, event, participant, task persistence
+- [Realtime](docs/api/realtime.md): RealtimeBackend for ephemeral events - typing indicators, presence, read receipts. Key methods: `kit.publish_typing(room_id, user_id, is_typing=True)`, `kit.publish_presence(room_id, user_id, status)`, `kit.publish_read_receipt(room_id, user_id, event_id)`, `kit.subscribe_room(room_id, callback) -> subscription_id`, `kit.unsubscribe_room(subscription_id)`. EphemeralEventType enum: TYPING_START, TYPING_STOP, PRESENCE_ONLINE, PRESENCE_AWAY, PRESENCE_OFFLINE, READ_RECEIPT, CUSTOM
+
+## Channels
+
+- [Channel ABC](docs/api/channel.md): Base class for all channels - handle_inbound, deliver, on_event, capabilities
+- [Built-in Channels](docs/api/channels.md): SMSChannel, EmailChannel, AIChannel, WebSocketChannel, MessengerChannel, HTTPChannel, WhatsAppChannel
+
+## Models
+
+- [Room & Timers](docs/api/room.md): Room model with status lifecycle (ACTIVE, PAUSED, CLOSED, ARCHIVED) and timer configuration
+- [Events & Content](docs/api/events.md): RoomEvent, TextContent, MediaContent, RichContent, CompositeContent, TemplateContent, LocationContent
+- [Identity](docs/api/identity.md): Identity, IdentityResult, IdentityHookResult, Participant - identification pipeline
+- [Delivery](docs/api/delivery.md): InboundMessage, InboundResult, DeliveryResult, ProviderResult
+- [Channel Models](docs/api/channel-models.md): ChannelBinding, ChannelCapabilities, ChannelOutput, RateLimit, RetryPolicy
+- [Hook Models](docs/api/hook-models.md): HookResult, InjectedEvent, Task, Observation
+
+## Providers
+
+- [AI Providers](docs/api/providers-ai.md): AIProvider ABC, AnthropicAIProvider, OpenAIAIProvider, GeminiAIProvider, MockAIProvider - context building, vision support
+- [SMS Providers](docs/api/providers-sms.md): SMSProvider ABC, TwilioSMSProvider, TelnyxSMSProvider, SinchSMSProvider, VoiceMeUpSMSProvider - webhook parsing, signature verification, MMS support
+- [Email Providers](docs/api/providers-email.md): EmailProvider ABC, ElasticEmailProvider
+- [HTTP Providers](docs/api/providers-http.md): HTTPProvider ABC, WebhookHTTPProvider - generic webhook integration
+- [Messenger Providers](docs/api/providers-messenger.md): MessengerProvider ABC, FacebookMessengerProvider
+
+## Optional
+
+- [Enums](docs/api/enums.md): ChannelType, EventType, EventStatus, RoomStatus, HookTrigger, HookExecution, IdentificationStatus, ParticipantRole
+- [Technical Details](docs/technical.md): Implementation details and internal architecture
+- [RFC](docs/roomkit-rfc.md): Original design document and rationale
+- [CPaaS Comparison](docs/cpaas-comparison.md): Comparison with other communication platforms

roomkit/models/__init__.py

@@ -0,0 +1,104 @@
+"""RoomKit data models."""
+
+from roomkit.models.channel import (
+    ChannelBinding,
+    ChannelCapabilities,
+    ChannelOutput,
+    RateLimit,
+)
+from roomkit.models.context import RoomContext
+from roomkit.models.delivery import (
+    DeliveryResult,
+    InboundMessage,
+    InboundResult,
+    ProviderResult,
+)
+from roomkit.models.enums import (
+    Access,
+    ChannelCategory,
+    ChannelDirection,
+    ChannelMediaType,
+    ChannelType,
+    DeliveryMode,
+    EventStatus,
+    EventType,
+    HookExecution,
+    HookTrigger,
+    IdentificationStatus,
+    ParticipantRole,
+    ParticipantStatus,
+    RoomStatus,
+    TaskStatus,
+)
+from roomkit.models.event import (
+    AudioContent,
+    ChannelData,
+    CompositeContent,
+    EventContent,
+    EventSource,
+    LocationContent,
+    MediaContent,
+    RichContent,
+    RoomEvent,
+    SystemContent,
+    TemplateContent,
+    TextContent,
+    VideoContent,
+)
+from roomkit.models.framework_event import FrameworkEvent
+from roomkit.models.hook import HookResult, InjectedEvent
+from roomkit.models.identity import Identity, IdentityHookResult, IdentityResult
+from roomkit.models.participant import Participant
+from roomkit.models.room import Room, RoomTimers
+from roomkit.models.task import Observation, Task
+
+__all__ = [
+    "Access",
+    "AudioContent",
+    "ChannelBinding",
+    "ChannelCapabilities",
+    "ChannelCategory",
+    "ChannelData",
+    "ChannelDirection",
+    "ChannelMediaType",
+    "ChannelOutput",
+    "ChannelType",
+    "CompositeContent",
+    "DeliveryMode",
+    "DeliveryResult",
+    "EventContent",
+    "EventSource",
+    "EventStatus",
+    "EventType",
+    "FrameworkEvent",
+    "HookExecution",
+    "HookResult",
+    "HookTrigger",
+    "Identity",
+    "IdentificationStatus",
+    "IdentityHookResult",
+    "IdentityResult",
+    "InboundMessage",
+    "InboundResult",
+    "InjectedEvent",
+    "LocationContent",
+    "MediaContent",
+    "Observation",
+    "Participant",
+    "ParticipantRole",
+    "ParticipantStatus",
+    "ProviderResult",
+    "RateLimit",
+    "RichContent",
+    "Room",
+    "RoomContext",
+    "RoomEvent",
+    "RoomStatus",
+    "RoomTimers",
+    "SystemContent",
+    "Task",
+    "TaskStatus",
+    "TemplateContent",
+    "TextContent",
+    "VideoContent",
+]

roomkit/models/channel.py

@@ -0,0 +1,99 @@
+"""Channel-related data models."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from roomkit.models.enums import (
+    Access,
+    ChannelCategory,
+    ChannelDirection,
+    ChannelMediaType,
+    ChannelType,
+    DeliveryMode,
+)
+from roomkit.models.event import RoomEvent
+from roomkit.models.task import Observation, Task
+
+
+class RateLimit(BaseModel):
+    """Rate limiting configuration for a channel."""
+
+    max_per_second: float | None = Field(default=None, gt=0.0)
+    max_per_minute: float | None = Field(default=None, gt=0.0)
+    max_per_hour: float | None = Field(default=None, gt=0.0)
+
+
+class RetryPolicy(BaseModel):
+    """Configures retry behaviour for channel delivery."""
+
+    max_retries: int = Field(default=3, ge=0)
+    base_delay_seconds: float = Field(default=1.0, gt=0.0)
+    max_delay_seconds: float = Field(default=60.0, gt=0.0)
+    exponential_base: float = Field(default=2.0, gt=0.0)
+
+
+class ChannelCapabilities(BaseModel):
+    """What a channel can do."""
+
+    media_types: list[ChannelMediaType] = Field(default_factory=lambda: [ChannelMediaType.TEXT])
+    max_length: int | None = Field(default=None, gt=0)
+    supports_threading: bool = False
+    supports_reactions: bool = False
+    supports_read_receipts: bool = False
+    supports_typing: bool = False
+    supports_templates: bool = False
+    supports_rich_text: bool = False
+    supports_buttons: bool = False
+    max_buttons: int | None = Field(default=None, gt=0)
+    supports_cards: bool = False
+    supports_quick_replies: bool = False
+    supports_media: bool = False
+    supported_media_types: list[str] = Field(default_factory=list)
+    max_media_size_bytes: int | None = Field(default=None, gt=0)
+    supports_audio: bool = False
+    max_audio_duration_seconds: int | None = Field(default=None, gt=0)
+    supported_audio_formats: list[str] = Field(default_factory=list)
+    supports_video: bool = False
+    max_video_duration_seconds: int | None = Field(default=None, gt=0)
+    supported_video_formats: list[str] = Field(default_factory=list)
+    delivery_mode: DeliveryMode = DeliveryMode.BROADCAST
+    custom: dict[str, Any] = Field(default_factory=dict)
+
+
+class ChannelBinding(BaseModel):
+    """A channel's attachment to a room."""
+
+    channel_id: str
+    room_id: str
+    channel_type: ChannelType
+    category: ChannelCategory = ChannelCategory.TRANSPORT
+    direction: ChannelDirection = ChannelDirection.BIDIRECTIONAL
+    access: Access = Access.READ_WRITE
+    muted: bool = False
+    visibility: str = "all"
+    participant_id: str | None = None
+    last_read_index: int | None = Field(default=None, ge=0)
+    attached_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    capabilities: ChannelCapabilities = Field(default_factory=ChannelCapabilities)
+    rate_limit: RateLimit | None = None
+    retry_policy: RetryPolicy | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ChannelOutput(BaseModel):
+    """Output produced by a channel after receiving an event."""
+
+    responded: bool = False
+    response_events: list[RoomEvent] = Field(default_factory=list)
+    tasks: list[Task] = Field(default_factory=list)
+    observations: list[Observation] = Field(default_factory=list)
+    metadata_updates: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def empty(cls) -> ChannelOutput:
+        """Create an empty output with no responses or side effects."""
+        return cls()

roomkit/models/context.py

@@ -0,0 +1,35 @@
+"""Room context model."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from roomkit.models.channel import ChannelBinding
+from roomkit.models.enums import ChannelType
+from roomkit.models.event import RoomEvent
+from roomkit.models.participant import Participant
+from roomkit.models.room import Room
+
+
+class RoomContext(BaseModel):
+    """Contextual information about a room for hook and channel processing."""
+
+    room: Room
+    bindings: list[ChannelBinding] = Field(default_factory=list)
+    participants: list[Participant] = Field(default_factory=list)
+    recent_events: list[RoomEvent] = Field(default_factory=list)
+
+    def other_channels(self, exclude_channel_id: str) -> list[ChannelBinding]:
+        """Get all bindings except the specified channel."""
+        return [b for b in self.bindings if b.channel_id != exclude_channel_id]
+
+    def channels_by_type(self, channel_type: ChannelType) -> list[ChannelBinding]:
+        """Get all bindings of a specific channel type."""
+        return [b for b in self.bindings if b.channel_type == channel_type]
+
+    def get_binding(self, channel_id: str) -> ChannelBinding | None:
+        """Get the binding for a specific channel."""
+        for b in self.bindings:
+            if b.channel_id == channel_id:
+                return b
+        return None

roomkit/models/delivery.py

@@ -0,0 +1,76 @@
+"""Delivery and provider result models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from roomkit.models.event import EventContent, RoomEvent
+
+
+class ProviderResult(BaseModel):
+    """Result from a provider delivery attempt."""
+
+    success: bool
+    provider_message_id: str | None = None
+    error: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class InboundMessage(BaseModel):
+    """A message received from an external provider."""
+
+    channel_id: str
+    sender_id: str
+    content: EventContent
+    external_id: str | None = None
+    thread_id: str | None = None
+    idempotency_key: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class InboundResult(BaseModel):
+    """Result of processing an inbound message."""
+
+    event: RoomEvent | None = None
+    blocked: bool = False
+    reason: str | None = None
+
+
+class DeliveryResult(BaseModel):
+    """Result of delivering an event to a channel."""
+
+    channel_id: str
+    success: bool
+    provider_result: ProviderResult | None = None
+    error: str | None = None
+
+
+class DeliveryStatus(BaseModel):
+    """Status update for an outbound message from a provider webhook.
+
+    Providers send status webhooks when messages are sent, delivered, failed, etc.
+    Use this with the ON_DELIVERY_STATUS hook to track outbound message delivery.
+
+    Attributes:
+        provider: Provider name (e.g., "telnyx", "twilio").
+        message_id: Provider's unique message identifier.
+        status: Status string (e.g., "sent", "delivered", "failed").
+        recipient: Phone number/address the message was sent to.
+        sender: Phone number/address the message was sent from.
+        error_code: Provider-specific error code (if failed).
+        error_message: Human-readable error message (if failed).
+        timestamp: When the status was reported.
+        raw: Original webhook payload for debugging.
+    """
+
+    provider: str
+    message_id: str
+    status: str
+    recipient: str = ""
+    sender: str = ""
+    error_code: str | None = None
+    error_message: str | None = None
+    timestamp: str | None = None
+    raw: dict[str, Any] = Field(default_factory=dict)

roomkit/models/enums.py

@@ -0,0 +1,170 @@
+"""All string enums for RoomKit."""
+
+from __future__ import annotations
+
+from enum import StrEnum, unique
+
+
+@unique
+class ChannelType(StrEnum):
+    SMS = "sms"
+    MMS = "mms"
+    RCS = "rcs"
+    EMAIL = "email"
+    WHATSAPP = "whatsapp"
+    WEBSOCKET = "websocket"
+    AI = "ai"
+    VOICE = "voice"
+    PUSH = "push"
+    MESSENGER = "messenger"
+    WEBHOOK = "webhook"
+    SYSTEM = "system"
+
+
+@unique
+class ChannelCategory(StrEnum):
+    TRANSPORT = "transport"
+    INTELLIGENCE = "intelligence"
+
+
+@unique
+class ChannelDirection(StrEnum):
+    INBOUND = "inbound"
+    OUTBOUND = "outbound"
+    BIDIRECTIONAL = "bidirectional"
+
+
+@unique
+class ChannelMediaType(StrEnum):
+    TEXT = "text"
+    RICH = "rich"
+    MEDIA = "media"
+    AUDIO = "audio"
+    VIDEO = "video"
+    LOCATION = "location"
+    TEMPLATE = "template"
+
+
+@unique
+class EventType(StrEnum):
+    MESSAGE = "message"
+    SYSTEM = "system"
+    TYPING = "typing"
+    READ_RECEIPT = "read_receipt"
+    DELIVERY_RECEIPT = "delivery_receipt"
+    PRESENCE = "presence"
+    REACTION = "reaction"
+    EDIT = "edit"
+    DELETE = "delete"
+    # Participant lifecycle (RFC §5.1)
+    PARTICIPANT_JOINED = "participant_joined"
+    PARTICIPANT_LEFT = "participant_left"
+    PARTICIPANT_IDENTIFIED = "participant_identified"
+    # Channel lifecycle (RFC §3.7)
+    CHANNEL_ATTACHED = "channel_attached"
+    CHANNEL_DETACHED = "channel_detached"
+    CHANNEL_MUTED = "channel_muted"
+    CHANNEL_UNMUTED = "channel_unmuted"
+    CHANNEL_UPDATED = "channel_updated"
+    # Side effects
+    TASK_CREATED = "task_created"
+    OBSERVATION = "observation"
+
+
+@unique
+class EventStatus(StrEnum):
+    PENDING = "pending"
+    DELIVERED = "delivered"
+    READ = "read"
+    FAILED = "failed"
+    BLOCKED = "blocked"
+
+
+@unique
+class Access(StrEnum):
+    READ_WRITE = "read_write"
+    READ_ONLY = "read_only"
+    WRITE_ONLY = "write_only"
+    NONE = "none"
+
+
+@unique
+class IdentificationStatus(StrEnum):
+    IDENTIFIED = "identified"
+    PENDING = "pending"
+    AMBIGUOUS = "ambiguous"
+    UNKNOWN = "unknown"
+    CHALLENGE_SENT = "challenge_sent"
+    REJECTED = "rejected"
+
+
+@unique
+class ParticipantRole(StrEnum):
+    OWNER = "owner"
+    AGENT = "agent"
+    MEMBER = "member"
+    OBSERVER = "observer"
+    BOT = "bot"
+
+
+@unique
+class ParticipantStatus(StrEnum):
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    LEFT = "left"
+    BANNED = "banned"
+
+
+@unique
+class TaskStatus(StrEnum):
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@unique
+class RoomStatus(StrEnum):
+    ACTIVE = "active"
+    PAUSED = "paused"
+    CLOSED = "closed"
+    ARCHIVED = "archived"
+
+
+@unique
+class DeliveryMode(StrEnum):
+    BROADCAST = "broadcast"
+    DIRECT = "direct"
+    ROUND_ROBIN = "round_robin"
+
+
+@unique
+class HookTrigger(StrEnum):
+    # Event pipeline (RFC §4.1)
+    BEFORE_BROADCAST = "before_broadcast"
+    AFTER_BROADCAST = "after_broadcast"
+    # Channel lifecycle (RFC §4.1)
+    ON_CHANNEL_ATTACHED = "on_channel_attached"
+    ON_CHANNEL_DETACHED = "on_channel_detached"
+    ON_CHANNEL_MUTED = "on_channel_muted"
+    ON_CHANNEL_UNMUTED = "on_channel_unmuted"
+    # Room lifecycle (RFC §4.1)
+    ON_ROOM_CREATED = "on_room_created"
+    ON_ROOM_PAUSED = "on_room_paused"
+    ON_ROOM_CLOSED = "on_room_closed"
+    # Identity (RFC §7.3)
+    ON_IDENTITY_AMBIGUOUS = "on_identity_ambiguous"
+    ON_IDENTITY_UNKNOWN = "on_identity_unknown"
+    ON_PARTICIPANT_IDENTIFIED = "on_participant_identified"
+    # Side effects
+    ON_TASK_CREATED = "on_task_created"
+    ON_ERROR = "on_error"
+    # Delivery status (outbound message tracking)
+    ON_DELIVERY_STATUS = "on_delivery_status"
+
+
+@unique
+class HookExecution(StrEnum):
+    SYNC = "sync"
+    ASYNC = "async"