# RoomKit

> Minimum version: 0.38.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 plus InMemoryStore, SQLiteStore, and PostgresStore - 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, RCSChannel, EmailChannel, WhatsAppChannel, WhatsAppPersonalChannel, MessengerChannel, TelegramChannel, TeamsChannel, DiscordChannel, BuzzChannel, HTTPChannel, WebSocketChannel, AIChannel, VoiceChannel, RealtimeVoiceChannel, VideoChannel, AudioVideoChannel, RealtimeAudioVideoChannel, ConferenceChannel, ACPChannel, CLIChannel
- [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
- [Conference](docs/api/conference.md): ConferenceChannel + ConferenceBackend ABC (LiveKit SFU, Mock) - multi-party audio/video conferences with an AI bot participant (STT/TTS)
- [Event Sources](docs/api/sources.md): source-driven ingestion powering Discord, Buzz (Nostr), WhatsApp Personal and custom WebSocket/SSE integrations

## 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, AzureAIProvider, GeminiAIProvider, GeminiVertexProvider (Vertex AI), MistralAIProvider, OllamaAIProvider, OpenRouterAIProvider, PolarGridAIProvider, XAIAIProvider (Grok), vLLM, MockAIProvider - context building, tool calling, vision, thinking/reasoning
- [SMS Providers](docs/api/providers-sms.md): SMSProvider ABC, TwilioSMSProvider, TelnyxSMSProvider, SinchSMSProvider, VoiceMeUpSMSProvider - webhook parsing, signature verification, MMS support
- [RCS Providers](docs/api/providers-rcs.md): RCSProvider ABC, Twilio and Telnyx implementations - rich cards, carousels, suggested replies
- [Email Providers](docs/api/providers-email.md): EmailProvider ABC, ElasticEmailProvider, SendGridProvider
- [Telegram Providers](docs/api/providers-telegram.md): TelegramProvider ABC, TelegramBotProvider (Telegram Bot API)
- [Discord Providers](docs/api/providers-discord.md): DiscordProvider ABC, DiscordBotProvider (Discord Bot API)
- [Buzz Providers](docs/api/providers-buzz.md): BuzzRelayProvider ABC, BuzzProvider - Buzz (Nostr relay) workspace messaging via buzzkit
- [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)

## Agentic AI & Voice Internals

- [Memory](docs/api/memory.md): SlidingWindowMemory, SummarizingMemory (two-tier context budget), RetrievalMemory - AI context management
- [Knowledge (RAG)](docs/api/knowledge.md): KnowledgeSource ABC, PostgresKnowledgeSource (full-text search) - retrieval-augmented context
- [Tools](docs/api/tools.md): Tool ABC, tool handlers, MCP tool provider, Tool Search (progressive disclosure)
- [Skills](docs/api/skills.md): reusable agent skill packages with availability gating
- [Scoring](docs/api/scoring.md): ScoringHook, ConversationScorer - automatic response quality scoring; user feedback via kit.submit_feedback()
- [Delegation](docs/api/delegation.md): agent-to-agent task delegation over the status bus
- [Voice Pipeline](docs/api/voice-pipeline.md): pluggable stages - VAD, AEC, AGC, denoiser, diarization, DTMF, recorder, resampler, turn detection
- [SIP Backend](docs/api/sip-backend.md) / [RTP Backend](docs/api/rtp-backend.md): telephony voice transports
- [Telemetry](docs/api/telemetry.md): TelemetryProvider - latency and usage instrumentation

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