Skip to main content
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us