# RoomKit

> Minimum version: 0.66.2 | 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
- [Shared Microphone Capture](docs/guides/shared-mic-capture.md): AudioCaptureSource ABC, LocalMicSource, MockCaptureSource - device capture that outlives a session, with a bounded backlog ring so a wake word can replay the utterance that triggered it
- [Realtime Voice](docs/api/providers-realtime-voice.md): RealtimeVoiceChannel, RealtimeVoiceProvider ABC, GeminiLiveProvider, OpenAIRealtimeProvider, OpenAILiveProvider, XAIRealtimeProvider, DeepgramAgentProvider, 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, CerebrasAIProvider, AzureAIProvider, GeminiAIProvider, GeminiVertexProvider (Vertex AI), MistralAIProvider, OllamaAIProvider, OpenRouterAIProvider, LiteLLMAIProvider (LiteLLM proxy), PolarGridAIProvider, XAIAIProvider (Grok), DeepSeekAIProvider, QwenAIProvider (Alibaba Model Studio), vLLM, LlamaCppAIProvider (local GGUF via llama.cpp), 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
- [Image Providers](docs/api/providers-image.md): ImageProvider ABC, ImageResult (always a data URI), OpenAIImageProvider, GeminiImageProvider, XAIImageProvider (Grok Imagine), OpenRouterImageProvider (OpenRouter Image API), AzureImageProvider, MockImageProvider - decoupled image generation and editing, disjoint model catalogs (RFC §25)
- [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), OpenAILiveProvider (full-duplex speech-to-speech via OpenAI GPT-Live, reasoning and tools delegated to a backend model), XAIRealtimeProvider (speech-to-speech via xAI Grok), DeepgramAgentProvider (Deepgram Voice Agent: Nova listens, an LLM thinks, Aura speaks, each chosen separately), 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
