Chainlit

Build production-ready conversational AI applications in Python with rich UI.

Installation

pip install chainlit

Quick Start

import chainlit as cl

@cl.on_message
async def on_message(message: cl.Message):
    await cl.Message(content=f"You said: {message.content}").send()

Run with:

chainlit run app.py -w

Core Concepts

Lifecycle Hooks

import chainlit as cl

@cl.on_chat_start
async def start():
    cl.user_session.set("history", [])
    await cl.Message(content="Hello!").send()

@cl.on_message
async def on_message(message: cl.Message):
    await cl.Message(content="Got it!").send()

@cl.on_chat_end
async def end():
    print("Session ended")

Streaming Responses

from openai import AsyncOpenAI
import chainlit as cl

client = AsyncOpenAI()
cl.instrument_openai()

@cl.on_message
async def on_message(message: cl.Message):
    msg = cl.Message(content="")
    await msg.send()

    stream = await client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": message.content}],
        stream=True
    )

    async for chunk in stream:
        if token := chunk.choices[0].delta.content:
            await msg.stream_token(token)

    await msg.update()

Steps (Chain of Thought)

@cl.step(type="tool")
async def search(query: str):
    return f"Results for: {query}"

@cl.step(type="llm")
async def generate(context: str):
    return await llm_call(context)

@cl.on_message
async def on_message(message: cl.Message):
    results = await search(message.content)
    answer = await generate(results)
    await cl.Message(content=answer).send()

User Session

@cl.on_chat_start
async def start():
    cl.user_session.set("counter", 0)

@cl.on_message
async def on_message(message: cl.Message):
    count = cl.user_session.get("counter")
    count += 1
    cl.user_session.set("counter", count)

Ask User for Input

# Text input
response = await cl.AskUserMessage(content="What's your name?").send()
name = response.get("output") if response else "Anonymous"

# File upload
files = await cl.AskFileMessage(
    content="Upload a file",
    accept=["text/plain", "application/pdf"]
).send()

# Action selection
response = await cl.AskActionMessage(
    content="Choose:",
    actions=[
        cl.Action(name="yes", label="Yes"),
        cl.Action(name="no", label="No"),
    ]
).send()

UI Elements

@cl.on_message
async def on_message(message: cl.Message):
    elements = [
        cl.Text(name="code.py", content="print('hello')", language="python"),
        cl.Image(name="chart", path="./chart.png", display="inline"),
        cl.File(name="report.pdf", path="./report.pdf"),
    ]

    await cl.Message(content="Results:", elements=elements).send()

Actions (Buttons)

@cl.action_callback("approve")
async def on_approve(action: cl.Action):
    await action.remove()
    await cl.Message(content="Approved!").send()

@cl.on_message
async def on_message(message: cl.Message):
    actions = [cl.Action(name="approve", label="Approve")]
    await cl.Message(content="Review:", actions=actions).send()

Reference Documentation

For detailed guidance:

• lifecycle.md - on_chat_start, on_message, on_chat_end hooks
• messages.md - Message class, streaming, chat_context
• steps.md - Step decorator, context manager, nested steps
• elements.md - Text, Image, File, PDF, Audio, Video, Plotly
• actions.md - Action buttons, callbacks, payloads
• ask-user.md - AskUserMessage, AskFileMessage, AskActionMessage
• session.md - User session, reserved keys, state management
• auth.md - Password, OAuth, header authentication
• integrations.md - OpenAI, LangChain, LlamaIndex, Mistral
• patterns.md - RAG, document Q&A, multi-agent, feedback

Integrations

# OpenAI
cl.instrument_openai()

# LangChain
config = RunnableConfig(callbacks=[cl.LangchainCallbackHandler()])

# LlamaIndex
callback_manager = CallbackManager([cl.LlamaIndexCallbackHandler()])

Configuration

.chainlit/config.toml:

[project]
name = "My App"

[UI]
cot = "full"  # Show chain of thought: full, hidden, tool_call

Run Commands

# Development with auto-reload
chainlit run app.py -w

# Production
chainlit run app.py --host 0.0.0.0 --port 8000

# Generate auth secret
chainlit create-secret

Key Imports

import chainlit as cl

# Core
cl.Message, cl.Step, cl.Action

# Elements
cl.Text, cl.Image, cl.File, cl.Pdf, cl.Audio, cl.Video
cl.Plotly, cl.Dataframe, cl.TaskList

# Ask User
cl.AskUserMessage, cl.AskFileMessage, cl.AskActionMessage

# Decorators
@cl.on_chat_start, @cl.on_message, @cl.on_chat_end
@cl.step, @cl.action_callback
@cl.password_auth_callback, @cl.oauth_callback