Chatbot

Conversation state management and message history

The Chatbot class manages conversation state, chat history, and system prompt configuration for voice conversations.

Class: Chatbot

Manages the conversation state machine and preprocesses messages for the LLM.

Import

from unmute.llm.chatbot import Chatbot

Constructor

__init__ · method

Creates a new Chatbot instance with empty conversation history.

chatbot = Chatbot()

Methods

conversation_state

conversation_state · method

Returns the current conversation state.

States:

• "waiting_for_user" - Bot is idle, waiting for user to speak
• "user_speaking" - User is currently speaking
• "bot_speaking" - Bot is generating/speaking a response

state = chatbot.conversation_state()
if state == "bot_speaking":
    print("Bot is currently responding")

add_chat_message_delta

add_chat_message_delta · async method

Adds a text delta to the conversation history.

Parameters:

• delta (str) - Text chunk to add
• role (Literal[“user”, “assistant”]) - Message role
• generating_message_i (int | None) - Index of message being generated

Returns: True if a new message was started, False if appending to existing

# Add user message
is_new = await chatbot.add_chat_message_delta("Hello!", role="user", generating_message_i=None)

# Add assistant response chunks
await chatbot.add_chat_message_delta("Hi", role="assistant", generating_message_i=0)
await chatbot.add_chat_message_delta(" there!", role="assistant", generating_message_i=0)

preprocessed_messages

preprocessed_messages · method

Returns the conversation history with preprocessing applied.

Preprocessing includes:

• Removing interruption markers
• Removing silence markers
• Trimming incomplete messages

messages = chatbot.preprocessed_messages()
# [
#   {"role": "system", "content": "You are a helpful assistant."},
#   {"role": "user", "content": "Hello!"},
#   {"role": "assistant", "content": "Hi there!"}
# ]

set_instructions

set_instructions · method

Sets the system prompt instructions for the conversation.

Parameters:

• instructions (Instructions) - Instruction configuration object

from unmute.llm.system_prompt import SmalltalkInstructions

instructions = SmalltalkInstructions(language="en")
chatbot.set_instructions(instructions)

get_instructions

get_instructions · method

Returns the current instructions configuration.

instructions = chatbot.get_instructions()
if instructions:
    print(f"Using instruction type: {instructions.type}")

get_system_prompt

get_system_prompt · method

Generates the system prompt text from the current instructions.

system_prompt = chatbot.get_system_prompt()
print(system_prompt)  # "You are a friendly conversational AI..."

last_message

last_message · method

Returns the content of the last message with the specified role.

Parameters:

• role (str) - Role to search for (“user” or “assistant”)

last_user_msg = chatbot.last_message("user")
last_bot_msg = chatbot.last_message("assistant")

Conversation State Machine

The Chatbot tracks conversation state based on message history:

Instructions Types

The Chatbot supports multiple instruction types defined in unmute.llm.system_prompt:

• SmalltalkInstructions - Casual conversation
• ConstantInstructions - Fixed system prompt text
• QuizShowInstructions - Quiz game personality
• GuessAnimalInstructions - Animal guessing game
• NewsInstructions - News reading personality
• UnmuteExplanationInstructions - Explains how Unmute works

See Voices and Characters for details on configuring instructions.

Usage Example

from unmute.llm.chatbot import Chatbot
from unmute.llm.system_prompt import SmalltalkInstructions

# Create chatbot with smalltalk personality
chatbot = Chatbot()
chatbot.set_instructions(SmalltalkInstructions(language="en"))

# Simulate conversation
await chatbot.add_chat_message_delta("Hi there!", role="user", generating_message_i=None)
await chatbot.add_chat_message_delta("Hello! ", role="assistant", generating_message_i=0)
await chatbot.add_chat_message_delta("How can I help?", role="assistant", generating_message_i=0)

# Get conversation state
state = chatbot.conversation_state()  # "bot_speaking"

# Get processed messages for LLM
messages = chatbot.preprocessed_messages()

Integration with UnmuteHandler

The Chatbot is used internally by UnmuteHandler to manage conversation state:

# UnmuteHandler uses Chatbot internally
handler = UnmuteHandler()
# handler.chatbot manages the conversation

See UnmuteHandler for the main orchestration class.

Related

• UnmuteHandler - Main conversation orchestrator
• LLM Utils - LLM integration utilities
• Voices and Characters - Configure system prompts