chainlit

Chainlit provides a Python decorator-based callback system (@cl.on_message, @cl.on_chat_start, @cl.on_action) that hooks into a FastAPI + Socket.IO backend to enable real-time bidirectional message streaming between client and server. Developers define conversational logic as async Python functions that receive Message objects and emit responses via the cl.Message API, with automatic WebSocket serialization and session-scoped state management. The system handles connection lifecycle, message queuing, and concurrent request handling through FastAPI's async runtime.

Chainlit provides native callback handlers for LangChain (ChainlitCallbackHandler) and LlamaIndex (LlamaIndexCallbackHandler) that automatically instrument LLM calls, tool invocations, and retrieval operations into a hierarchical Step system. Each step captures input/output, model metadata, token counts, and latency, creating a visual trace in the UI. The callbacks hook into the frameworks' event systems (LangChain's BaseCallbackHandler, LlamaIndex's BaseCallbackHandler) and emit Step objects via the Chainlit emitter, with no code changes required beyond adding the callback to the chain/agent initialization.

Chainlit uses a declarative configuration system based on chainlit.toml (TOML format) for setting application metadata, UI customization, authentication, data persistence, and feature flags. Configuration is loaded at startup and can be overridden via environment variables (e.g., CHAINLIT_AUTH_SECRET). The system supports feature flags for enabling/disabling functionality (e.g., CHAINLIT_ENABLE_TELEMETRY), and provides a Config class for programmatic access to settings.

Chainlit provides a command-line interface (chainlit run, chainlit deploy, chainlit create) for running applications. The run command supports hot-reload (--watch flag) for automatic server restart on file changes, debug mode (--debug flag) for detailed logging, and headless mode (--headless flag) for API-only operation without the UI. The CLI also provides options for specifying port, host, and other runtime parameters.

Chainlit provides integrations with messaging platforms (Slack, Discord, Microsoft Teams) that route platform-specific messages to Chainlit callbacks and send responses back to the platform. Each platform integration uses the platform's API (Slack Bolt, Discord.py, Microsoft Bot Framework) to receive messages, convert them to Chainlit Message objects, and emit them to the appropriate callback. Responses are converted back to platform-specific format and sent to the user.

Chainlit abstracts data persistence through a DataLayer interface supporting multiple backends: SQLAlchemy (PostgreSQL, MySQL, SQLite), DynamoDB, and cloud storage (AWS S3, Azure Blob, GCP Cloud Storage). The system uses a repository pattern with concrete implementations (SQLAlchemyDataLayer, DynamoDBDataLayer) that handle CRUD operations for conversations, messages, steps, and user data. Configuration is declarative via chainlit.toml or environment variables, allowing runtime backend switching without code changes. The data model uses SQLAlchemy ORM for relational backends and custom serialization for NoSQL, with automatic schema migration support.

Chainlit uses python-socketio (Socket.IO 4.x protocol) to establish persistent WebSocket connections between browser clients and the FastAPI backend, with automatic reconnection, message queuing, and session lifecycle management. Each client connection is assigned a session ID, and all messages are routed through a session-scoped context (cl.user_session) that persists across message exchanges. The system handles connection drops, browser tab switching, and concurrent requests through Socket.IO's built-in acknowledgment and retry mechanisms, with configurable timeouts and heartbeat intervals.

Chainlit provides a React/TypeScript frontend (@chainlit/app) that renders messages, steps, and interactive elements (buttons, file uploads, forms) in real-time as they arrive via WebSocket. The frontend uses a state management system (likely Redux or Context API based on DeepWiki references) to maintain conversation history, user input, and UI state, with automatic re-rendering on message updates. Elements are composable components (Image, PDF, File, Plotly charts) that can be embedded in messages, and the UI supports markdown rendering, syntax highlighting for code blocks, and audio playback. The Copilot Widget provides an embeddable chat interface for third-party websites.

Chainlit supports the Model Context Protocol (MCP) standard for exposing tools and resources to LLMs through a standardized interface. Developers can register MCP servers (local or remote) that define tools with JSON schemas, and Chainlit automatically makes these tools available to LangChain agents or direct LLM calls. The system validates tool inputs against schemas, handles tool execution with error recovery, and streams tool results back to the LLM. MCP integration is declarative via configuration or programmatic via the cl.MCP API.

Chainlit provides pluggable authentication via OAuth (Google, GitHub, Microsoft), JWT tokens, password-based login, or custom header-based schemes (for reverse proxy integration). The system uses a User object to represent authenticated users, with optional role and permission attributes for authorization. Authentication is enforced at the WebSocket connection level — unauthenticated clients are rejected before reaching callback handlers. Custom authentication can be implemented by subclassing the Auth class and overriding the authenticate() method.

Chainlit provides built-in file upload support through the @cl.on_file_upload callback and the FileUploadMessage type. Files are received as multipart form data, automatically stored in the configured data layer (local filesystem, S3, Azure Blob, etc.), and made available to callback handlers as File objects with metadata (name, size, mime type, path). The system handles concurrent uploads, validates file types/sizes, and provides a file browser UI component for users to select and upload files.

Chainlit provides a Step system for capturing intermediate results in multi-step processes (LLM calls, tool invocations, retrievals). Steps are hierarchical — parent steps can contain child steps, creating a tree structure that mirrors the execution flow. Each step captures input, output, metadata (model, tokens, latency), and status (running, succeeded, failed). Steps are emitted via the cl.Step API and automatically rendered in the UI as collapsible trees. The system also provides a Message type for user/assistant messages with optional metadata and elements.

Chainlit provides an @cl.action decorator for registering callbacks that respond to user interactions (button clicks, form submissions, select changes). Actions are defined with a name and optional payload schema, and the UI renders corresponding interactive elements. When a user triggers an action, the payload is sent to the backend via WebSocket, deserialized, and passed to the action callback. The system handles action validation, error handling, and response streaming back to the UI.