ChatBot

Main entry point for building and managing conversational AI chatbots with integrated conversation handling.

USAGE

ChatBot(name=None, description=None, id=None)

The ChatBot class is the primary interface for creating intelligent chatbots in Talk Box. It provides a chainable API for configuration and returns Conversation objects that manage message history and context. This design creates a natural learning path where users start with ChatBot for configuration, receive Conversation objects for message management, and discover Message objects within conversations.

Layered API Design:

ChatBot (this class): configuration and interaction entry point
Conversation: multi-turn conversation management and message history
Message: individual message data structures with metadata

The integration ensures that all chat interactions automatically create and manage conversation history, making multi-turn conversations natural and persistent. Advanced users can access lower-level Conversation and Message classes for specialized use cases.

Notes

The ChatBot class takes no initialization parameters. All configuration is done through the chainable methods after instantiation.

Returns

ChatBot: A new ChatBot instance with default configuration and auto-enabled LLM integration (when available).

Conversation Management

All chat interactions return Conversation objects, providing seamless conversation management:

chat(): send message and get conversation with response
start_conversation(): create new empty conversation
continue_conversation(): continue existing conversation

Conversations automatically handle message history, chronological ordering, and context management. Users can access individual Message objects within conversations for detailed inspection.

Chainable Configuration Methods

Configure your chatbot behavior with these chainable methods:

model(): set the language model to use
preset(): apply behavior presets like "technical_advisor"
temperature(): control response randomness (0.0-2.0)
max_tokens(): set maximum response length
tools(): enable specific tools and capabilities
persona(): define the chatbot’s personality
avoid(): specify topics or behaviors to avoid
verbose(): enable detailed output logging

All configuration methods return self, enabling method chaining for concise setup.

Browser Integration

The ChatBot class provides interactive browser interfaces:

Automatic Launch: when displayed in Jupyter notebooks, opens browser chat interface
Manual Sessions: use create_chat_session() for explicit browser interface control
Configuration Display: shows current configuration when LLM integration unavailable

Examples

Basic conversation flow

The natural progression from ChatBot to Conversation to Message:

import talk_box as tb

# 1. Configure chatbot (entry point)
bot = tb.ChatBot().model("gpt-4").temperature(0.7).preset("helpful")

# 2. Start conversation (returns Conversation object)
conversation = bot.chat("Hello! What can you help me with?")

# 3. Continue conversation (updates Conversation)
conversation = bot.chat("Tell me about machine learning", conversation=conversation)

# 4. Access individual messages (Message objects)
for message in conversation.get_messages():
    print(f"{message.role}: {message.content}")
    print(f"Timestamp: {message.timestamp}")

Advanced conversation management

Explicit conversation management for complex workflows:

# Start with empty conversation
conversation = bot.start_conversation()

# Add multiple exchanges
conversation = bot.continue_conversation(conversation, "What's the weather?")
conversation = bot.continue_conversation(conversation, "What about tomorrow?")

# Access conversation metadata
print(f"Total messages: {conversation.get_message_count()}")
print(f"Last message: {conversation.get_last_message().content}")

# Filter by role
user_messages = conversation.get_messages(role="user")
assistant_messages = conversation.get_messages(role="assistant")

Discovering the full API layer by layer

Start simple and naturally discover more advanced features:

import talk_box as tb

# Layer 1: Basic ChatBot usage
bot = tb.ChatBot().model("gpt-4")
convo = bot.chat("Hello!")

# Layer 2: Conversation management (discovered from return type)
convo.add_user_message("Another question")
messages = convo.get_messages()

# Layer 3: Message details (discovered from conversation contents)
latest = convo.get_last_message()
print(f"Message ID: {latest.message_id}")
print(f"Metadata: {latest.metadata}")

# Layer 4: Advanced conversation features
convo.set_context_window(10)  # Limit conversation length
context_msgs = convo.get_context_messages()  # Get messages in context window