# RoomKit

> Minimum version: 0.7.0 | Python 3.12+

> Full documentation: [llms-full.txt](llms-full.txt)

> RoomKit is a pure async Python library for building multi-channel conversation systems.
> It provides room-based abstractions for managing conversations across SMS, Email, Voice, 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, tool call notifications. 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.publish_tool_call(room_id, channel_id, tool_calls, event_type, duration_ms=None)`, `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, REACTION, TOOL_CALL_START, TOOL_CALL_END, CUSTOM. AIChannel auto-publishes TOOL_CALL_START/TOOL_CALL_END during tool execution with payloads: `{tool_calls: [{id, name, arguments|result}], round, channel_id, duration_ms?}`

## 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, VoiceChannel, RealtimeVoiceChannel, MessengerChannel, TeamsChannel, HTTPChannel, WhatsAppChannel, WhatsAppPersonalChannel
- [Voice Channel](docs/api/providers-voice.md): VoiceBackend ABC, STTProvider, TTSProvider, DeepgramSTTProvider, ElevenLabsTTSProvider, FastRTCVoiceBackend - real-time voice with barge-in support
- [Realtime Voice](docs/api/providers-realtime-voice.md): RealtimeVoiceChannel, RealtimeVoiceProvider ABC, GeminiLiveProvider, OpenAIRealtimeProvider, WebSocketRealtimeTransport, FastRTCRealtimeTransport (WebRTC passthrough) - speech-to-speech AI with tool calling, text injection, auto-reconnect

## Key Concepts (in llms-full.txt)

- **Channel-to-AI Message Flow**: How messages flow from transport channels through the inbound pipeline to AI and back via the reentry loop, with chain depth tracking
- **Content Transcoding**: ChannelCapabilities, DefaultContentTranscoder fallback chain (Rich→Text, Media→Text, etc.), custom ContentTranscoder implementation
- **ConversationState**: Persistent state across conversation turns — phase, active_agent_id, handoff_count, context dict for custom data, transition() for phase changes, PhaseTransition audit trail
- **Dynamic Routing**: ConversationRouter with RoutingConditions (phases, channel_types, intents, source_channel_ids, custom callable), routing by content/origin/state

## 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, 11 content types — TextContent, RichContent, MediaContent, AudioContent, VideoContent, LocationContent, CompositeContent, TemplateContent, SystemContent, EditContent, DeleteContent
- [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 (media_types, max_length, supports_edit/delete/reactions), 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
- [Teams Providers](docs/api/providers-teams.md): TeamsProvider ABC, BotFrameworkTeamsProvider, ConversationReferenceStore, parse_teams_activity, is_bot_added - Bot Framework SDK integration with proactive messaging, bot mention detection, lifecycle events
- [Voice Providers](docs/api/providers-voice.md): VoiceBackend, STTProvider (Deepgram), TTSProvider (ElevenLabs), FastRTCVoiceBackend
- [Realtime Voice Providers](docs/api/providers-realtime-voice.md): GeminiLiveProvider (speech-to-speech via Gemini Live API), OpenAIRealtimeProvider (speech-to-speech via OpenAI Realtime API), WebSocketRealtimeTransport (browser audio via WebSocket), FastRTCRealtimeTransport (browser audio via WebRTC)
- [WhatsApp Providers](docs/api/providers-whatsapp.md): WhatsAppProvider (Business API), WhatsAppPersonalProvider (neonize - unofficial multidevice protocol with typing indicators, read receipts, media handling)

## 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
