roomkit 0.1.0__py3-none-any.whl

roomkit/__init__.py

@@ -0,0 +1,372 @@
+"""RoomKit - Pure async Python library for multi-channel conversations."""
+
+from roomkit._version import __version__
+from roomkit.channels import (
+    EmailChannel,
+    HTTPChannel,
+    MessengerChannel,
+    RCSChannel,
+    SMSChannel,
+    WhatsAppChannel,
+)
+from roomkit.channels.ai import AIChannel
+from roomkit.channels.base import Channel
+from roomkit.channels.transport import TransportChannel
+from roomkit.channels.websocket import WebSocketChannel
+from roomkit.core.framework import (
+    ChannelNotFoundError,
+    ChannelNotRegisteredError,
+    IdentityNotFoundError,
+    ParticipantNotFoundError,
+    RoomKit,
+    RoomKitError,
+    RoomNotFoundError,
+    SourceAlreadyAttachedError,
+    SourceNotFoundError,
+)
+from roomkit.core.hooks import HookEngine, HookRegistration
+from roomkit.core.inbound_router import DefaultInboundRoomRouter, InboundRoomRouter
+from roomkit.core.locks import InMemoryLockManager, RoomLockManager
+from roomkit.identity.base import IdentityResolver
+from roomkit.identity.mock import MockIdentityResolver
+from roomkit.models.channel import (
+    ChannelBinding,
+    ChannelCapabilities,
+    ChannelOutput,
+    RateLimit,
+    RetryPolicy,
+)
+from roomkit.models.context import RoomContext
+from roomkit.models.delivery import (
+    DeliveryResult,
+    DeliveryStatus,
+    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,
+    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
+from roomkit.providers.ai.base import (
+    AIContext,
+    AIImagePart,
+    AIMessage,
+    AIProvider,
+    AIResponse,
+    AITextPart,
+    AITool,
+    AIToolCall,
+    ProviderError,
+)
+from roomkit.providers.ai.mock import MockAIProvider
+from roomkit.providers.anthropic.ai import AnthropicAIProvider
+from roomkit.providers.anthropic.config import AnthropicConfig
+from roomkit.providers.elasticemail.config import ElasticEmailConfig
+from roomkit.providers.elasticemail.email import ElasticEmailProvider
+from roomkit.providers.email.base import EmailProvider
+from roomkit.providers.email.mock import MockEmailProvider
+from roomkit.providers.gemini.ai import GeminiAIProvider
+from roomkit.providers.gemini.config import GeminiConfig
+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
+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
+from roomkit.providers.openai.ai import OpenAIAIProvider
+from roomkit.providers.openai.config import OpenAIConfig
+from roomkit.providers.rcs.base import RCSDeliveryResult, RCSProvider
+from roomkit.providers.rcs.mock import MockRCSProvider
+from roomkit.providers.sinch.config import SinchConfig
+from roomkit.providers.sinch.sms import SinchSMSProvider, parse_sinch_webhook
+from roomkit.providers.sms.base import SMSProvider
+from roomkit.providers.sms.meta import WebhookMeta, extract_sms_meta
+from roomkit.providers.sms.mock import MockSMSProvider
+from roomkit.providers.sms.phone import is_valid_phone, normalize_phone
+from roomkit.providers.telnyx.config import TelnyxConfig
+from roomkit.providers.telnyx.rcs import (
+    TelnyxRCSConfig,
+    TelnyxRCSProvider,
+    parse_telnyx_rcs_webhook,
+)
+from roomkit.providers.telnyx.sms import (
+    TelnyxSMSProvider,
+    parse_telnyx_webhook,
+)
+from roomkit.providers.twilio.config import TwilioConfig
+from roomkit.providers.twilio.rcs import (
+    TwilioRCSConfig,
+    TwilioRCSProvider,
+    parse_twilio_rcs_webhook,
+)
+from roomkit.providers.twilio.sms import TwilioSMSProvider, parse_twilio_webhook
+from roomkit.providers.voicemeup.config import VoiceMeUpConfig
+from roomkit.providers.voicemeup.sms import (
+    VoiceMeUpSMSProvider,
+    configure_voicemeup_mms,
+    parse_voicemeup_webhook,
+)
+from roomkit.providers.whatsapp.base import WhatsAppProvider
+from roomkit.providers.whatsapp.mock import MockWhatsAppProvider
+from roomkit.realtime.base import (
+    EphemeralCallback,
+    EphemeralEvent,
+    EphemeralEventType,
+    RealtimeBackend,
+)
+from roomkit.realtime.memory import InMemoryRealtime
+from roomkit.sources.base import (
+    BaseSourceProvider,
+    EmitCallback,
+    SourceHealth,
+    SourceProvider,
+    SourceStatus,
+)
+from roomkit.store.base import ConversationStore
+from roomkit.store.memory import InMemoryStore
+
+# AI documentation helpers (lazy import to avoid file I/O at import time)
+
+
+def get_llms_txt() -> str:
+    """Get the contents of llms.txt for LLM consumption."""
+    from roomkit.ai_docs import get_llms_txt as _get_llms_txt
+
+    return _get_llms_txt()
+
+
+def get_agents_md() -> str:
+    """Get the contents of AGENTS.md for AI coding assistants."""
+    from roomkit.ai_docs import get_agents_md as _get_agents_md
+
+    return _get_agents_md()
+
+
+def get_ai_context() -> str:
+    """Get combined AI context (AGENTS.md + llms.txt)."""
+    from roomkit.ai_docs import get_ai_context as _get_ai_context
+
+    return _get_ai_context()
+
+
+__all__ = [
+    "__version__",
+    # Core
+    "RoomKit",
+    "RoomKitError",
+    "RoomNotFoundError",
+    "ChannelNotFoundError",
+    "ChannelNotRegisteredError",
+    "ParticipantNotFoundError",
+    "IdentityNotFoundError",
+    "SourceAlreadyAttachedError",
+    "SourceNotFoundError",
+    "RoomLockManager",
+    "InMemoryLockManager",
+    # Sources (event-driven)
+    "BaseSourceProvider",
+    "EmitCallback",
+    "SourceHealth",
+    "SourceProvider",
+    "SourceStatus",
+    # Routing
+    "InboundRoomRouter",
+    "DefaultInboundRoomRouter",
+    # Channels
+    "Channel",
+    "TransportChannel",
+    "AIChannel",
+    "EmailChannel",
+    "RCSChannel",
+    "SMSChannel",
+    "WebSocketChannel",
+    "MessengerChannel",
+    "HTTPChannel",
+    "WhatsAppChannel",
+    # Models - Enums
+    "Access",
+    "ChannelCategory",
+    "ChannelDirection",
+    "ChannelMediaType",
+    "ChannelType",
+    "DeliveryMode",
+    "EventStatus",
+    "EventType",
+    "HookExecution",
+    "HookTrigger",
+    "IdentificationStatus",
+    "ParticipantRole",
+    "ParticipantStatus",
+    "RoomStatus",
+    "TaskStatus",
+    # Models - Data
+    "AudioContent",
+    "ChannelBinding",
+    "ChannelCapabilities",
+    "ChannelOutput",
+    "CompositeContent",
+    "DeliveryResult",
+    "DeliveryStatus",
+    "EventContent",
+    "EventSource",
+    "FrameworkEvent",
+    "HookResult",
+    "Identity",
+    "IdentityHookResult",
+    "IdentityResult",
+    "InboundMessage",
+    "InboundResult",
+    "InjectedEvent",
+    "LocationContent",
+    "MediaContent",
+    "Observation",
+    "Participant",
+    "ProviderResult",
+    "RateLimit",
+    "RetryPolicy",
+    "RichContent",
+    "Room",
+    "RoomContext",
+    "RoomEvent",
+    "RoomTimers",
+    "SystemContent",
+    "Task",
+    "TemplateContent",
+    "TextContent",
+    "VideoContent",
+    # Hooks
+    "HookEngine",
+    "HookRegistration",
+    # Provider Errors
+    "ProviderError",
+    # Provider ABCs
+    "AIProvider",
+    "EmailProvider",
+    "HTTPProvider",
+    "MessengerProvider",
+    "RCSProvider",
+    "SMSProvider",
+    "WhatsAppProvider",
+    # AI
+    "AIContext",
+    "AIImagePart",
+    "AIMessage",
+    "AIResponse",
+    "AITextPart",
+    "AITool",
+    "AIToolCall",
+    "MockAIProvider",
+    # AI – Anthropic
+    "AnthropicAIProvider",
+    "AnthropicConfig",
+    # AI – Gemini
+    "GeminiAIProvider",
+    "GeminiConfig",
+    # AI – OpenAI
+    "OpenAIAIProvider",
+    "OpenAIConfig",
+    # HTTP – Generic Webhook
+    "HTTPProviderConfig",
+    "MockHTTPProvider",
+    "WebhookHTTPProvider",
+    "parse_http_webhook",
+    # Email
+    "ElasticEmailConfig",
+    "ElasticEmailProvider",
+    "MockEmailProvider",
+    # Messenger
+    "FacebookMessengerProvider",
+    "MessengerConfig",
+    "MockMessengerProvider",
+    "parse_messenger_webhook",
+    # SMS
+    "MockSMSProvider",
+    "WebhookMeta",
+    "extract_sms_meta",
+    "is_valid_phone",
+    "normalize_phone",
+    # SMS - Sinch
+    "SinchConfig",
+    "SinchSMSProvider",
+    "parse_sinch_webhook",
+    # SMS - Telnyx
+    "TelnyxConfig",
+    "TelnyxSMSProvider",
+    "parse_telnyx_webhook",
+    # RCS - Telnyx
+    "TelnyxRCSConfig",
+    "TelnyxRCSProvider",
+    "parse_telnyx_rcs_webhook",
+    # SMS - Twilio
+    "TwilioConfig",
+    "TwilioSMSProvider",
+    "parse_twilio_webhook",
+    # SMS - VoiceMeUp
+    "VoiceMeUpConfig",
+    "VoiceMeUpSMSProvider",
+    "configure_voicemeup_mms",
+    "parse_voicemeup_webhook",
+    # RCS
+    "MockRCSProvider",
+    "RCSDeliveryResult",
+    # RCS - Twilio
+    "TwilioRCSConfig",
+    "TwilioRCSProvider",
+    "parse_twilio_rcs_webhook",
+    # WhatsApp
+    "MockWhatsAppProvider",
+    # Identity
+    "IdentityResolver",
+    "MockIdentityResolver",
+    # Store
+    "ConversationStore",
+    "InMemoryStore",
+    # Realtime
+    "EphemeralCallback",
+    "EphemeralEvent",
+    "EphemeralEventType",
+    "InMemoryRealtime",
+    "RealtimeBackend",
+    # AI Docs
+    "get_agents_md",
+    "get_ai_context",
+    "get_llms_txt",
+]

roomkit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

roomkit/ai_docs.py

@@ -0,0 +1,93 @@
+"""AI documentation helpers for llms.txt and AGENTS.md access."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+
+def _find_file(filename: str) -> str:
+    """Find and read a file from package or repository root."""
+    # Try 1: importlib.resources (installed package)
+    try:
+        files = resources.files("roomkit")
+        return (files / filename).read_text(encoding="utf-8")
+    except (FileNotFoundError, TypeError):
+        pass
+
+    # Try 2: package directory (editable install with files copied)
+    pkg_dir = Path(__file__).parent
+    pkg_path = pkg_dir / filename
+    if pkg_path.exists():
+        return pkg_path.read_text(encoding="utf-8")
+
+    # Try 3: repository root (development mode)
+    # Go up from src/roomkit to repository root
+    repo_root = pkg_dir.parent.parent
+    repo_path = repo_root / filename
+    if repo_path.exists():
+        return repo_path.read_text(encoding="utf-8")
+
+    raise FileNotFoundError(f"{filename} not found in roomkit package or repository")
+
+
+def get_llms_txt() -> str:
+    """Get the contents of llms.txt for LLM consumption.
+
+    Returns:
+        The llms.txt content as a string.
+
+    Example:
+        >>> from roomkit.ai_docs import get_llms_txt
+        >>> content = get_llms_txt()
+        >>> print(content[:50])
+        # RoomKit
+        ...
+    """
+    return _find_file("llms.txt")
+
+
+def get_agents_md() -> str:
+    """Get the contents of AGENTS.md for AI coding assistants.
+
+    Returns:
+        The AGENTS.md content as a string.
+
+    Example:
+        >>> from roomkit.ai_docs import get_agents_md
+        >>> content = get_agents_md()
+        >>> print(content[:50])
+        # RoomKit
+        ...
+    """
+    return _find_file("AGENTS.md")
+
+
+def get_ai_context() -> str:
+    """Get combined AI context (AGENTS.md + llms.txt summary).
+
+    Useful for providing complete context to AI assistants.
+
+    Returns:
+        Combined content optimized for AI consumption.
+
+    Example:
+        >>> from roomkit.ai_docs import get_ai_context
+        >>> context = get_ai_context()
+        >>> # Pass to AI assistant as system context
+    """
+    agents = get_agents_md()
+    llms = get_llms_txt()
+
+    return f"""# RoomKit AI Context
+
+## Project Guidelines (AGENTS.md)
+
+{agents}
+
+---
+
+## Documentation Index (llms.txt)
+
+{llms}
+"""

roomkit/channels/__init__.py

@@ -0,0 +1,194 @@
+"""Channel implementations and transport-channel factories."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from roomkit.channels.transport import TransportChannel
+from roomkit.models.channel import ChannelCapabilities
+from roomkit.models.enums import ChannelMediaType, ChannelType
+
+# ---------------------------------------------------------------------------
+# Capability constants
+# ---------------------------------------------------------------------------
+
+SMS_CAPABILITIES = ChannelCapabilities(
+    media_types=[ChannelMediaType.TEXT, ChannelMediaType.MEDIA],
+    max_length=1600,
+    supports_read_receipts=True,
+    supports_media=True,
+)
+
+EMAIL_CAPABILITIES = ChannelCapabilities(
+    media_types=[
+        ChannelMediaType.TEXT,
+        ChannelMediaType.RICH,
+        ChannelMediaType.MEDIA,
+    ],
+    supports_threading=True,
+    supports_rich_text=True,
+    supports_media=True,
+)
+
+WHATSAPP_CAPABILITIES = ChannelCapabilities(
+    media_types=[
+        ChannelMediaType.TEXT,
+        ChannelMediaType.RICH,
+        ChannelMediaType.MEDIA,
+        ChannelMediaType.LOCATION,
+        ChannelMediaType.TEMPLATE,
+    ],
+    max_length=4096,
+    supports_read_receipts=True,
+    supports_reactions=True,
+    supports_templates=True,
+    supports_rich_text=True,
+    supports_buttons=True,
+    max_buttons=3,
+    supports_quick_replies=True,
+    supports_media=True,
+)
+
+MESSENGER_CAPABILITIES = ChannelCapabilities(
+    media_types=[
+        ChannelMediaType.TEXT,
+        ChannelMediaType.RICH,
+        ChannelMediaType.MEDIA,
+        ChannelMediaType.TEMPLATE,
+    ],
+    max_length=2000,
+    supports_read_receipts=True,
+    supports_buttons=True,
+    max_buttons=3,
+    supports_quick_replies=True,
+    supports_media=True,
+)
+
+HTTP_CAPABILITIES = ChannelCapabilities(
+    media_types=[ChannelMediaType.TEXT, ChannelMediaType.RICH],
+)
+
+RCS_CAPABILITIES = ChannelCapabilities(
+    media_types=[
+        ChannelMediaType.TEXT,
+        ChannelMediaType.RICH,
+        ChannelMediaType.MEDIA,
+    ],
+    max_length=8000,  # RCS supports longer messages
+    supports_read_receipts=True,
+    supports_typing=True,
+    supports_rich_text=True,
+    supports_buttons=True,
+    supports_quick_replies=True,
+    supports_cards=True,
+    supports_media=True,
+)
+
+# ---------------------------------------------------------------------------
+# Factory functions
+# ---------------------------------------------------------------------------
+
+
+def SMSChannel(
+    channel_id: str,
+    *,
+    provider: Any = None,
+    from_number: str | None = None,
+) -> TransportChannel:
+    """Create an SMS transport channel."""
+    return TransportChannel(
+        channel_id,
+        ChannelType.SMS,
+        provider=provider,
+        capabilities=SMS_CAPABILITIES,
+        recipient_key="phone_number",
+        defaults={"from_": from_number},
+    )
+
+
+def EmailChannel(
+    channel_id: str,
+    *,
+    provider: Any = None,
+    from_address: str | None = None,
+) -> TransportChannel:
+    """Create an Email transport channel."""
+    return TransportChannel(
+        channel_id,
+        ChannelType.EMAIL,
+        provider=provider,
+        capabilities=EMAIL_CAPABILITIES,
+        recipient_key="email_address",
+        defaults={"from_": from_address, "subject": None},
+    )
+
+
+def WhatsAppChannel(
+    channel_id: str,
+    *,
+    provider: Any = None,
+) -> TransportChannel:
+    """Create a WhatsApp transport channel."""
+    return TransportChannel(
+        channel_id,
+        ChannelType.WHATSAPP,
+        provider=provider,
+        capabilities=WHATSAPP_CAPABILITIES,
+        recipient_key="phone_number",
+    )
+
+
+def MessengerChannel(
+    channel_id: str,
+    *,
+    provider: Any = None,
+) -> TransportChannel:
+    """Create a Facebook Messenger transport channel."""
+    return TransportChannel(
+        channel_id,
+        ChannelType.MESSENGER,
+        provider=provider,
+        capabilities=MESSENGER_CAPABILITIES,
+        recipient_key="facebook_user_id",
+    )
+
+
+def HTTPChannel(
+    channel_id: str,
+    *,
+    provider: Any = None,
+) -> TransportChannel:
+    """Create an HTTP webhook transport channel."""
+    return TransportChannel(
+        channel_id,
+        ChannelType.WEBHOOK,
+        provider=provider,
+        capabilities=HTTP_CAPABILITIES,
+        recipient_key="recipient_id",
+    )
+
+
+def RCSChannel(
+    channel_id: str,
+    *,
+    provider: Any = None,
+    fallback: bool = True,
+) -> TransportChannel:
+    """Create an RCS (Rich Communication Services) transport channel.
+
+    Args:
+        channel_id: Unique identifier for this channel.
+        provider: RCS provider instance (e.g., TwilioRCSProvider).
+        fallback: If True (default), allow SMS fallback when RCS unavailable.
+
+    Returns:
+        A TransportChannel configured for RCS messaging.
+    """
+    return TransportChannel(
+        channel_id,
+        ChannelType.RCS,
+        provider=provider,
+        capabilities=RCS_CAPABILITIES,
+        recipient_key="phone_number",
+        defaults={"fallback": fallback},
+    )