Skip to main content

Chainlit UI

Location: apps/chainlit_ui/
Tech Stack: Chainlit, FastAPI
Purpose: Production-ready chat interface for conversational AI applications

🎯 Overview​

Chainlit UI provides a modern, production-ready chat interface with built-in conversation memory, user authentication, and beautiful UI components. Perfect for deploying chatbots and conversational agents.

Use this when:

  • Building a chatbot or virtual assistant
  • Need conversation history and memory
  • Want a polished, user-friendly interface
  • Deploying customer-facing applications
  • Need multi-user support with authentication

⚡ Quick Start​

cd apps/chainlit_ui
pip install -r requirements.txt
export OPENAI_API_KEY="your-key"
chainlit run app.py

# Open: http://localhost:8000

💬 Interface Features​

Modern Chat Experience​

┌─────────────────────────────────────────────┐
│  RecoAgent Chat          [Settings] [Logout]│
├─────────────────────────────────────────────┤
│                                             │
│  🤖 Hello! How can I help you today?        │
│                                             │
│  👤 What is hybrid search?                  │
│                                             │
│  🤖 Hybrid search combines BM25 keyword     │
│     search with vector semantic search...   │
│                                             │
│     📄 Sources:                             │
│     • hybrid_retrieval_guide.pdf (p. 3)     │
│     • rag_best_practices.md                 │
│                                             │
│  👤 [Type your message...]                  │
│     [Send]                    🎤 [📎 Upload]│
└─────────────────────────────────────────────┘

Key Features​

  1. Conversation Memory

    • Remembers context across messages
    • Per-user conversation history
    • Session management

  2. Rich UI Components

    • Markdown formatting
    • Code syntax highlighting
    • Image and file display
    • Interactive elements

  3. Source Attribution

    • Expandable source cards
    • Document previews
    • Relevance scores

  4. User Management

    • Authentication (optional)
    • Multi-user support
    • User preferences

🔧 Configuration​

Create .env file:

# LLM Configuration
OPENAI_API_KEY=your-key
LLM_MODEL=gpt-4
TEMPERATURE=0.7

# Chainlit Settings
CHAINLIT_HOST=0.0.0.0
CHAINLIT_PORT=8000
CHAINLIT_AUTH_SECRET=your-secret-key

# Chat Settings
MAX_HISTORY_MESSAGES=20
SHOW_SOURCES=true
ENABLE_VOICE_INPUT=true
ENABLE_FILE_UPLOAD=true

# Database (for conversation history)
DATABASE_URL=postgresql://user:pass@localhost/chainlit

🎨 Customization​

Branding & Theme​

# .chainlit/config.toml
[UI]
name = "RecoAgent Assistant"
default_theme = "light"
primary_color = "#4CAF50"
secondary_color = "#2196F3"

[UI.logo]
url = "/public/logo.png"

Custom Avatars​

# Set custom avatars
@cl.on_chat_start
async def start():
    await cl.Avatar(
        name="RecoAgent",
        url="/public/bot-avatar.png"
    ).send()

Custom Actions​

# Add custom buttons
actions = [
    cl.Action(
        name="feedback",
        value="good",
        label="👍 Helpful"
    ),
    cl.Action(
        name="feedback",
        value="bad",
        label="👎 Not helpful"
    )
]
await cl.Message(
    content="Was this helpful?",
    actions=actions
).send()

💾 Conversation Management​

Save Conversations​

# Automatic conversation saving
@cl.on_message
async def on_message(message: cl.Message):
    # Process message
    response = agent.ask(message.content)
    
    # Save to database
    save_conversation(
        user_id=message.author,
        message=message.content,
        response=response.answer
    )
    
    await cl.Message(content=response.answer).send()

Load History​

# Load previous conversations
@cl.on_chat_start
async def start():
    history = load_conversation_history(user_id)
    for msg in history:
        await cl.Message(
            content=msg.content,
            author=msg.author
        ).send()

🔐 Authentication​

Simple Password Auth​

# .chainlit/config.toml
[auth]
enable = true

# auth.py
@cl.password_auth_callback
def auth_callback(username: str, password: str):
    if username == "admin" and password == "secure":
        return cl.User(identifier="admin")
    return None

OAuth Integration​

# Support for GitHub, Google, etc.
[auth.oauth]
provider = "github"
client_id = "your-client-id"
client_secret = "your-secret"

📁 File Upload Support​

# Handle file uploads
@cl.on_message
async def on_message(message: cl.Message):
    # Check for attachments
    if message.elements:
        for file in message.elements:
            # Process uploaded file
            content = file.content
            agent.add_documents([content])
            
    # Process message as usual
    response = agent.ask(message.content)
    await cl.Message(content=response.answer).send()

🎤 Voice Input​

Enable voice-to-text input:

# config.toml
[features]
enable_voice_input = true
voice_language = "en-US"

📊 Analytics Integration​

# Track user interactions
@cl.on_message
async def on_message(message: cl.Message):
    # Log analytics
    analytics.track(
        user_id=message.author,
        event="message_sent",
        properties={
            "message_length": len(message.content),
            "has_attachments": bool(message.elements)
        }
    )

🚀 Production Deployment​

Docker Deployment​

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["chainlit", "run", "app.py", "--host", "0.0.0.0", "--port", "8000"]

Environment Variables​

# Production settings
CHAINLIT_AUTH_SECRET=production-secret-key
DATABASE_URL=postgresql://...
ENABLE_TELEMETRY=false
LOG_LEVEL=INFO

🎯 Use Cases​

Customer Support Bot​

# Handle customer queries
@cl.on_message
async def support_bot(message: cl.Message):
    # Check if ticket should be created
    if should_escalate(message.content):
        ticket_id = create_support_ticket(message.content)
        response = f"I've created ticket #{ticket_id}"
    else:
        response = agent.ask(message.content).answer
    
    await cl.Message(content=response).send()

Document Q&A​

# Upload docs and ask questions
@cl.on_chat_start
async def start():
    files = await cl.AskFileMessage(
        content="Upload documents to analyze",
        accept=["application/pdf", "text/plain"]
    ).send()
    
    # Index documents
    agent.add_documents(files)
    await cl.Message("Documents indexed! Ask me anything.").send()

🆘 Troubleshooting​

IssueSolution
Port 8000 in useChange port: chainlit run app.py --port 8001
Auth not workingCheck CHAINLIT_AUTH_SECRET is set
Messages not savingVerify DATABASE_URL connection
Slow responsesEnable streaming responses

📚 Related Docs​

Ready for users! Deploy your chatbot with Chainlit! 💬