# 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