Chainlit

Warnings

• breaking Chainlit v2.9.4 introduced a breaking change requiring a database migration for users employing persistence. You must run `ALTER TABLE steps ADD COLUMN IF NOT EXISTS modes JSONB;` to migrate your database.
  Fix: Execute the SQL command `ALTER TABLE steps ADD COLUMN IF NOT EXISTS modes JSONB;` on your Chainlit database before upgrading or starting applications on version 2.9.4 or higher.
• gotcha Chainlit is an async-first framework. All operations that interact with the UI, such as `cl.Message().send()` or other `cl` methods that involve sending data, must be `await`ed. Failing to do so will result in a coroutine object being returned instead of the expected action, potentially leading to silent failures or unexpected behavior.
  Fix: Always prepend `await` to asynchronous Chainlit function calls, e.g., `await cl.Message(...).send()`.
• gotcha When authentication is enabled (e.g., via `CHAINLIT_AUTH_SECRET` or OAuth), 'Invalid authentication token' errors can occur, especially when rendering images. This often indicates a missing or incorrect `CHAINLIT_AUTH_SECRET` environment variable.
  Fix: Ensure the `CHAINLIT_AUTH_SECRET` environment variable is correctly set and accessible to your Chainlit application. For OAuth, verify all `OAUTH_PROVIDER_CLIENT_ID`, `OAUTH_PROVIDER_CLIENT_SECRET`, and domain variables are correctly configured.
• gotcha Configuration defined in `chainlit.toml` (e.g., project name, UI settings) may occasionally be ignored, particularly in certain older versions (e.g., v2.7.2). This can lead to default settings being applied instead of your custom configurations.
  Fix: Verify your `chainlit.toml` file is correctly formatted and located. If issues persist, ensure `load_dotenv()` (if used) is called before `import chainlit`. Consider updating to the latest Chainlit version, as such issues are often addressed.

Install

• pip install chainlit Install stable version

Imports

• cl

  import chainlit as cl

• cl.on_chat_start

  @cl.on_chat_start

  Decorator for functions that run when a new chat session begins.
• cl.on_message

  @cl.on_message

  Decorator for functions that handle incoming user messages.
• cl.Message

  await cl.Message(content='Hello!').send()

  Chainlit is async-first; all `cl.Message` operations must be `await`ed to send the message and avoid returning a coroutine object.

Quickstart

This quickstart demonstrates a basic Chainlit application. Create a file named `app.py`, paste the code, and run it using `chainlit run app.py -w` in your terminal. This will start the Chainlit UI in your browser, where you can interact with the bot. The `@cl.on_chat_start` function sends a welcome message, and `@cl.on_message` handles incoming user messages, simulating an intermediate step and then echoing the user's input.

import chainlit as cl
import os

# Optional: Set CHAINLIT_AUTH_SECRET if authentication is enabled for your app
# os.environ['CHAINLIT_AUTH_SECRET'] = os.environ.get('CHAINLIT_AUTH_SECRET', 'your_secret_key_here_for_testing')

@cl.on_chat_start
async def start():
    await cl.Message(
        content="Welcome! I am a simple Chainlit bot. Type anything to get a response."
    ).send()

@cl.on_message
async def main(message: cl.Message):
    # Simulate a tool's response
    await cl.Message(author="Tool", content=f"Processing: {message.content}", indent=1).send()

    # Send back the final answer
    await cl.Message(content=f"You said: {message.content}").send()

# To run this:
# 1. Save the code as `app.py`
# 2. Run `chainlit run app.py -w` in your terminal