Skip to main content
Chat is the easiest Capsule surface to start with. A message handler receives a Session and a Message, then replies back to the same session.

​
1. Create the app

import cpsl

app = cpsl.App(
    name="first-chat",
    image=cpsl.Image(),
)
App(...) is the object capsule serve and capsule deploy read.

​
2. Add a message handler

@app.message()
async def handle(session: cpsl.Session, msg: cpsl.Message):
    await session.reply(f"You said: {msg.text}")
Run it: 
capsule serve app.py:app
Open the preview URL and send a message.

​
3. Add conversation history

Most model APIs want alternating user and assistant messages. Capsule keeps the session history and can merge the current message for you: 
@app.message()
async def handle(session: cpsl.Session, msg: cpsl.Message):
    messages = session.chat_messages(msg)
    await session.reply(f"This session has {len(messages)} model messages.")

​
4. Stream a reply

Use streaming when work takes longer than a single response. 
@app.message()
async def handle(session: cpsl.Session, msg: cpsl.Message):
    async with session.stream_reply() as reply:
        reply.write("Starting...\n")
        reply.write(f"Working on: {msg.text}\n")
        reply.write("Done.")

​
Full example

import cpsl

app = cpsl.App(name="first-chat", image=cpsl.Image())


@app.message()
async def handle(session: cpsl.Session, msg: cpsl.Message):
    text = (msg.text or "").strip()
    if not text:
        await session.reply("Send me a message.")
        return

    session.data["last_message"] = text
    await session.reply(f"You said: {text}")

​
Next steps