eval.ChatBot

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

Usage

eval.ChatBot()

conversation handling.

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

Attributes

Name	Description
preset_manager	Get the preset manager, creating it lazily.

preset_manager

Get the preset manager, creating it lazily.

preset_manager

Methods

Name	Description
__init__()	Initialize a new ChatBot instance.
add_tools()	Add specific built-in tools.
avoid()	Configure topics or behaviors the chatbot must refuse to engage with.
chain_prompts()	Chain multiple structured prompts in attention-optimized order.
chat()	Send a message to the chatbot and get a response within a conversation context.
check_llm_status()	Check the status of LLM integration and get setup help if needed.
continue_conversation()	Continue an existing conversation with a new message.
create_chat_session()	Create a chat session backed by the configured LLM provider.
enable_llm_mode()	Enable LLM mode explicitly (DEPRECATED - LLM is auto-enabled by default).
enable_tool_box()	Enable all built-in Tool Box tools (deprecated - use .tools(“all”) instead).
get_avoid_topics()	Get the list of topics or behaviors this chatbot is configured to avoid.
get_config()	Return a copy of the full chatbot configuration dictionary.
get_config_summary()	Get a comprehensive summary of the current chatbot configuration.
get_system_prompt()	Get the final constructed system prompt that will be sent to the LLM.
get_usage()	Get the accumulated token usage and cost for this chatbot’s session.
guard_stats()	Get activation statistics for all attached guardrails.
guardrail()	Add a guardrail to the chatbot’s validation pipeline.
install_chatlas_help()	Get step-by-step instructions for installing chatlas to enable LLM integration.
max_tokens()	Set the maximum number of tokens for chatbot responses.
mock_responses()	Set scripted responses for demonstration and testing purposes.
model()	Configure the language model to use for generating responses.
persona()	Set a persona that shapes the chatbot’s tone and behavior.
persona_pack()	Load a complete, production-ready persona configuration.
preset()	Apply a pre-configured behavior template to instantly specialize the chatbot.
prompt_builder()	Create an attention-optimized prompt builder for declarative prompt composition.
provider_model()	Set provider and model using a single string (e.g., “openai:gpt-4o”).
quick_start()	Get a quick-start guide tailored to this chatbot’s current configuration.
show()	Display diagnostic information or launch chat interfaces.
start_conversation()	Start a new conversation with this chatbot.
structured_prompt()	Configure the chatbot with a structured prompt built from keyword sections.
system_prompt()	Set a custom system prompt, overriding any preset system prompt.
temperature()	Control the randomness and creativity level of chatbot responses.
tools()	Configure tools for this chatbot with unified API for custom and built-in tools.
verbose()	Enable or disable verbose diagnostic output during chat interactions.

init()

Initialize a new ChatBot instance.

Usage

Source

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

Parameters

name: Optional[str] = None: A human-readable name for this chatbot (e.g., "Customer Support Bot").
description: Optional[str] = None: A brief description of the chatbot’s purpose and capabilities.
id: Optional[str] = None: A unique identifier for this chatbot configuration (useful for A/B testing).

add_tools()

Add specific built-in tools.

Usage

Source

add_tools(tool_names)

Parameters

tool_names: list[str]: Names of specific Tool Box tools to add

Returns

ChatBot: The chatbot instance with selected tools for method chaining

Examples

>>> bot = ChatBot().add_tools(["calculate", "text_stats"])

avoid()

Configure topics or behaviors the chatbot must refuse to engage with.

Usage

Source

avoid(avoid_list)

The avoid list feeds into both the system prompt (instructing the LLM to decline requests on these topics) and the autotest_avoid_topics() testing framework that validates compliance.

Parameters

avoid_list: list[str]: A list of topic strings the chatbot should not discuss or assist with (e.g., ["medical_advice", "legal_advice"]).

Returns

ChatBot: The same instance for method chaining.

Examples

import talk_box as tb

bot = tb.ChatBot().avoid(["medical_advice", "financial_planning"])
bot.get_avoid_topics()

['medical_advice', 'financial_planning']

chain_prompts()

Chain multiple structured prompts in attention-optimized order.

Usage

Source

chain_prompts(*prompts)

This method allows you to combine multiple prompt components while maintaining optimal attention patterns. Components are automatically ordered to maximize the model’s focus on the most important information.

Parameters

*prompts: Prompt components to chain together. Can be raw strings or PromptBuilder instances.

Returns

ChatBot: Returns self for method chaining.

Examples

Chaining different prompt components

# Create specialized prompt components
security_prompt = (bot.prompt_builder()
    .core_analysis(["SQL injection risks", "XSS vulnerabilities"])
    .build())

performance_prompt = (bot.prompt_builder()
    .core_analysis(["Database query optimization", "Memory usage"])
    .build())

# Chain them with attention optimization
bot.chain_prompts(
    "You are a senior security and performance engineer.",
    security_prompt,
    performance_prompt,
    "Focus on the most critical issues that impact user security."
)

chat()

Send a message to the chatbot and get a response within a conversation context.

Usage

Source

chat(message, conversation=None)

This method creates or updates a conversation by adding the user’s message and the chatbot’s response. If no conversation is provided, a new one is automatically created. This is the primary way to interact with the chatbot while maintaining conversation history and context.

Parameters

message: Union[str, Attachments]

The user’s message to send to the chatbot. Can be:

A string message
An Attachments object containing files and an optional prompt

conversation: Optional[Conversation] = None

An existing conversation to continue. If not provided, a new conversation is created automatically.

Returns

Conversation: The conversation object containing the full message history including the new user message and chatbot response.

Examples

Basic single-message chat

import talk_box as tb

bot = tb.ChatBot().model("gpt-4").temperature(0.7)
convo = bot.chat("Hello! How are you?")
print(convo.get_last_message().content)

Chat with file attachments

from talk_box import ChatBot
from talk_box.attachments import Attachments

bot = ChatBot().model("gpt-4")

# Create attachments
attachments = Attachments().with_prompt("What's in these files?")
attachments.add_file("document.pdf")
attachments.add_file("image.png")

# Chat with attachments
convo = bot.chat(attachments)
print(convo.get_last_message().content)

Continuing a conversation

# Start a conversation
convo = bot.chat("What's machine learning?")

# Continue the same conversation
convo = bot.chat("Can you give me an example?", conversation=convo)

# View full conversation history
for msg in convo.get_messages():
    print(f"{msg.role}: {msg.content}")

check_llm_status()

Check the status of LLM integration and get setup help if needed.

Usage

Source

check_llm_status()

Returns a dictionary indicating whether the LLM backend is active, the current status string, and a help payload with troubleshooting guidance when the integration is not enabled.

Returns

dict

A dictionary with the following keys:

"enabled" (bool): Whether the LLM is active.
"status" (str): Human-readable status label.
"help" (str | dict): Setup instructions or confirmation message.

Examples

import talk_box as tb

bot = tb.ChatBot()
status = bot.check_llm_status()
status["enabled"]

True

continue_conversation()

Continue an existing conversation with a new message.

Usage

Source

continue_conversation(conversation, message)

This is a convenience method that’s equivalent to calling chat(message, conversation=conversation) but makes the intent of continuing a conversation more explicit.

Parameters

conversation: Conversation: The existing conversation to continue.
message: str: The user’s message to add to the conversation.

Returns

Conversation: The updated conversation with the new exchange.

Examples

# Start conversation
conversation = bot.start_conversation()

# Continue it explicitly
conversation = bot.continue_conversation(conversation, "What's the weather like?")
conversation = bot.continue_conversation(conversation, "What about tomorrow?")

create_chat_session()

Create a chat session backed by the configured LLM provider.

Usage

Source

create_chat_session()

When chatlas is installed this returns a fully configured chatlas.Chat instance ready for interactive use. If chatlas is unavailable a lightweight SimpleChatSession fallback is returned instead.

Returns

chatlas.Chat | SimpleChatSession: A chat session object. The concrete type depends on whether the chatlas package is installed.

Examples

import talk_box as tb

bot = tb.ChatBot().model("gpt-4")
session = bot.create_chat_session()

enable_llm_mode()

Enable LLM mode explicitly (DEPRECATED - LLM is auto-enabled by default).

Usage

Source

enable_llm_mode()

This method is deprecated and unnecessary since LLM integration is automatically enabled during ChatBot initialization. It remains for backward compatibility only.

Returns

ChatBot: Returns self for method chaining

Note

LLM integration is automatically enabled when you create a ChatBot. You do not need to call this method unless you’re using legacy code.

enable_tool_box()

Enable all built-in Tool Box tools (deprecated - use .tools(“all”) instead).

Usage

Source

enable_tool_box()

This method loads and registers all 14 built-in tools from the Tool Box library.

Deprecated since version Use

.tools("all") instead for consistency with the unified tools API.

Returns

ChatBot: The chatbot instance with Tool Box enabled for method chaining.

Examples

>>> # Deprecated approach
>>> bot = ChatBot().enable_tool_box()

>>> # Preferred approach
>>> bot = ChatBot().tools("all")

get_avoid_topics()

Get the list of topics or behaviors this chatbot is configured to avoid.

Usage

Source

get_avoid_topics()

This method provides access to the original avoid topics configuration, which is essential for testing frameworks that need to validate whether the bot properly adheres to its avoid topics constraints.

Returns

list[str]: A copy of the avoid topics list to prevent external modification

Examples

>>> bot = ChatBot().avoid(["medical_advice", "financial_planning"])
>>> topics = bot.get_avoid_topics()
>>> print(topics)
['medical_advice', 'financial_planning']

get_config()

Return a copy of the full chatbot configuration dictionary.

Usage

Source

get_config()

The returned dictionary includes all settings applied through the fluent API (model, temperature, persona, tools, etc.). Because it is a shallow copy, mutations do not affect the chatbot’s internal state.

Returns

dict[str, Any]: A copy of the configuration dictionary with keys such as "model", "temperature", "persona", "tools", "verbose", and others.

Examples

import talk_box as tb

bot = tb.ChatBot().model("gpt-4").temperature(0.2)
config = bot.get_config()
print(config["model"], config["temperature"])

gpt-4 0.2

get_config_summary()

Get a comprehensive summary of the current chatbot configuration.

Usage

Source

get_config_summary()

This includes model settings, prompt configuration, and metadata: useful for debugging, logging, A/B testing, and displaying in UI components.

Returns

dict[str, Any]

Complete configuration summary including:

basic info (name, description, id)
model parameters (model, temperature, max_tokens)
prompt components (preset, custom prompt, persona, constraints)
system prompt (final constructed prompt)
advanced settings (tools, verbose mode, LLM status)

Examples

>>> bot = ChatBot(name="Support Bot").preset("customer_support")
>>> config = bot.get_config_summary()
>>> print(config["name"], config["model"], len(config["system_prompt"]))
"Support Bot" "gpt-3.5-turbo" 245

get_system_prompt()

Get the final constructed system prompt that will be sent to the LLM.

Usage

Source

get_system_prompt()

This combines preset system prompts, custom system prompts, persona descriptions, constraints from ‘avoid’ settings, and other configuration elements into the final prompt text.

Returns

str: The complete system prompt that will be used for LLM interactions

Examples

>>> bot = ChatBot().preset("technical_advisor").persona("Senior Engineer")
>>> print(bot.get_system_prompt())
"You are a senior technical advisor..."

get_usage()

Get the accumulated token usage and cost for this chatbot’s session.

Usage

Source

get_usage()

Returns

SessionUsage: Token counts and estimated cost across all chat turns.

Examples

>>> bot = ChatBot().model("gpt-4")
>>> convo = bot.chat("Hello!")
>>> usage = bot.get_usage()
>>> print(usage.total_tokens, usage.total_cost)

guard_stats()

Get activation statistics for all attached guardrails.

Usage

Source

guard_stats()

Returns

dict[str, dict[str, int]]: Mapping of guard name to counts of passed, blocked, and rewritten activations.

Examples

stats = bot.guard_stats()
# {'no_pii': {'passed': 42, 'blocked': 0, 'rewritten': 3},
#  'max_response_length': {'passed': 40, 'blocked': 0, 'rewritten': 5}}

guardrail()

Add a guardrail to the chatbot’s validation pipeline.

Usage

Source

guardrail(guard)

Guards run in the order they are added. Input guards validate user messages before the LLM sees them. Output guards validate LLM responses before they are returned to the user. If any guard blocks a message, the pipeline short-circuits.

Parameters

guard: Guard: A Guard instance, typically created by @tb.guardrail, or one of the built-in guard factories (tb.no_pii(), tb.max_response_length(), etc.).

Returns

ChatBot: The same instance for method chaining.

Examples

import talk_box as tb

bot = (
    tb.ChatBot()
    .guardrail(tb.no_pii())
    .guardrail(tb.max_response_length(500))
    .guardrail(tb.disclaimer_required("Not financial advice."))
)

install_chatlas_help()

Get step-by-step instructions for installing chatlas to enable LLM integration.

Usage

Source

install_chatlas_help()

Returns

str: Detailed installation guide for different environments

max_tokens()

Set the maximum number of tokens for chatbot responses.

Usage

Source

max_tokens(tokens)

The max_tokens() option controls the maximum length of generated responses by limiting the number of tokens (roughly equivalent to words and punctuation) that the language model can produce in a single response. This is crucial for managing response length, controlling costs, ensuring consistent behavior, and preventing excessively long outputs that might overwhelm users or exceed system limits.

Understanding token limits is essential for balancing response completeness with practical constraints. Different models have varying token counting methods and maximum context windows, making this parameter both a performance optimization tool and a cost management mechanism.

Token counting varies by model and provider, but generally:

1 token ≈ 0.75 English words
100 tokens ≈ 75 words or ~1-2 sentences
500 tokens ≈ 375 words or ~1-2 paragraphs
1000 tokens ≈ 750 words or ~1 page of text

Parameters

tokens: int: Maximum number of tokens for response generation. Must be positive. See the “Token Usage Guidelines” section below for detailed recommendations and model-specific limits.

Returns

ChatBot: Returns self to enable method chaining, allowing you to combine max_tokens setting with other configuration methods.

Raises

ValueError: If tokens is not a positive integer. Some models may also have specific upper limits that could trigger additional validation errors.

Token Usage Guidelines

Choose token limits based on your specific use case and content requirements:

Short Responses (50-200 tokens):

quick answers, confirmations, brief explanations
customer support acknowledgments
code snippets and short technical answers
chat-style interactions

Medium Responses (200-800 tokens):

detailed explanations and tutorials
code documentation and examples
product descriptions and feature explanations
structured analysis and recommendations

Long Responses (800-2000 tokens):

comprehensive guides and documentation
detailed technical analysis
creative writing and storytelling
in-depth research summaries

Extended Responses (2000+ tokens):

long-form content generation
detailed reports and documentation
comprehensive tutorials and guides
complex analysis requiring extensive explanation

Model-Specific Limits: Different models have varying maximum context windows (shared between input and output):

GPT-3.5-turbo: up to 4,096 tokens total
GPT-4: up to 8,192 tokens total
GPT-4-turbo: up to 128,000 tokens total
Claude-3: up to 200,000 tokens total

Examples

Setting tokens for different response types

Configure max_tokens based on your expected response length:

import talk_box as tb

# Brief answers for quick interactions
quick_bot = (
    tb.ChatBot()
    .model("gpt-3.5-turbo")
    .max_tokens(150)  # ~100-120 words
    .preset("customer_support")
)

# Detailed explanations for technical questions
detailed_bot = (
    tb.ChatBot()
    .model("gpt-4-turbo")
    .max_tokens(1000)  # ~750 words
    .preset("technical_advisor")
)

# Long-form content generation
content_bot = (
    tb.ChatBot()
    .model("claude-opus-4-7")
    .max_tokens(3000)  # ~2250 words
    .preset("creative_writer")
)

Balancing completeness with constraints

Optimize token limits for specific scenarios:

# Code generation: precise and concise
code_bot = (
    tb.ChatBot()
    .model("gpt-4-turbo")
    .max_tokens(500)  # Focus on essential code
    .temperature(0.1)
    .persona("Senior software engineer providing clean, efficient code")
)

# Documentation writing: comprehensive but structured
docs_bot = (
    tb.ChatBot()
    .model("gpt-4-turbo")
    .max_tokens(1500)  # Detailed but focused
    .temperature(0.3)
    .persona("Technical writer creating clear, comprehensive documentation")
)

# Creative writing: longer form allowed
story_bot = (
    tb.ChatBot()
    .model("claude-opus-4-7")
    .max_tokens(2500)  # Allow creative expression
    .temperature(0.9)
    .preset("creative_writer")
)

Dynamic token adjustment based on context

Adapt max_tokens based on conversation needs:

class AdaptiveTokenBot:
    def __init__(self):
        self.bot = tb.ChatBot().model("gpt-4-turbo")

    def respond(self, message: str, response_type: str):
        if response_type == "brief":
            self.bot.max_tokens(200)  # Quick answers
        elif response_type == "detailed":
            self.bot.max_tokens(1000)  # Thorough explanations
        elif response_type == "comprehensive":
            self.bot.max_tokens(2000)  # In-depth analysis
        else:
            self.bot.max_tokens(500)  # Default moderate length

        return self.bot.chat(message)

# Usage examples
adaptive = AdaptiveTokenBot()

# Brief response for simple questions
quick_answer = adaptive.respond(
    "What is Python?",
    "brief"
)

# Detailed response for complex topics
detailed_answer = adaptive.respond(
    "Explain machine learning algorithms",
    "detailed"
)

Cost optimization with token limits

Use max_tokens to control API costs:

# Cost-conscious configuration for high-volume usage
efficient_bot = (
    tb.ChatBot()
    .model("gpt-3.5-turbo")  # Lower cost model
    .max_tokens(300)  # Limit response length
    .temperature(0.5)  # Balanced creativity
)

# Premium configuration for important interactions
premium_bot = (
    tb.ChatBot()
    .model("gpt-4-turbo")
    .max_tokens(1500)  # Allow detailed responses
    .temperature(0.7)
)

# Budget tracking example
def cost_aware_chat(message: str, budget_tier: str):
    if budget_tier == "economy":
        bot = tb.ChatBot().model("gpt-3.5-turbo").max_tokens(200)
    elif budget_tier == "standard":
        bot = tb.ChatBot().model("gpt-4").max_tokens(500)
    else:  # premium
        bot = tb.ChatBot().model("gpt-4-turbo").max_tokens(1500)

    return bot.chat(message)

Token limits for different content types

Optimize based on content format requirements:

# Email responses: professional length
email_bot = (
    tb.ChatBot()
    .max_tokens(400)  # Professional email length
    .persona("Professional and concise business communicator")
    .preset("customer_support")
)

# Blog post generation: substantial content
blog_bot = (
    tb.ChatBot()
    .max_tokens(2000)  # Article-length content
    .temperature(0.8)
    .persona("Engaging content writer")
)

# Social media responses: very brief
social_bot = (
    tb.ChatBot()
    .max_tokens(100)  # Tweet-length responses
    .temperature(0.7)
    .persona("Friendly and engaging social media manager")
)

# Technical documentation: comprehensive
tech_docs_bot = (
    tb.ChatBot()
    .max_tokens(1800)  # Detailed technical content
    .temperature(0.2)
    .preset("technical_advisor")
)

Monitoring token usage

Track actual vs. maximum token usage:

def monitor_token_usage(messages: list[str], max_tokens: int):
    """Monitor actual token usage vs. limits."""
    bot = tb.ChatBot().model("gpt-4-turbo").max_tokens(max_tokens)

    usage_data = []
    for message in messages:
        response = bot.chat(message)

        # Note: Actual token counting would require model-specific methods
        estimated_tokens = len(response.content.split()) * 1.3  # Rough estimate

        usage_data.append({
            "message": message[:50] + "..." if len(message) > 50 else message,
            "max_tokens": max_tokens,
            "estimated_used": int(estimated_tokens),
            "utilization": f"{(estimated_tokens/max_tokens)*100:.1f}%"
        })

    return usage_data

# Example usage
test_messages = [
    "What is artificial intelligence?",
    "Explain quantum computing in detail",
    "Write a short poem about technology"
]

usage_report = monitor_token_usage(test_messages, 500)
for entry in usage_report:
    print(f"Message: {entry['message']}")
    print(f"Utilization: {entry['utilization']}")
    print()

Token Management Best Practices

Start Conservative: begin with lower token limits and increase as needed to avoid unexpectedly long responses.

Content-Specific Limits: set different limits for different types of content (code, explanations, creative writing, etc.).

Cost Monitoring: use token limits as a cost control mechanism, especially for high-volume applications.

User Experience: balance completeness with readability as very long responses can overwhelm users.

Model Considerations: different models have different token counting methods and optimal ranges.

Performance Implications

Response Time: higher token limits may increase response generation time, especially for complex requests.

Cost Scaling: most API providers charge based on token usage, making this parameter directly tied to operational costs.

Context Window: remember that max_tokens is shared with input tokens in most models’ context windows.

Completion Quality: very low token limits may result in incomplete responses, while very high limits may lead to verbose, unfocused outputs.

Notes

Model Variations: different models count tokens differently and have varying optimal token ranges for quality output.

Shared Context: in most models, max_tokens counts toward the total context window, which includes both input and output tokens.

Truncation Behavior: when a response reaches the max_tokens limit, it is typically truncated, which may result in incomplete sentences or thoughts.

Dynamic Adjustment: consider implementing dynamic token adjustment based on response type, user preferences, or conversation context.

mock_responses()

Set scripted responses for demonstration and testing purposes.

Usage

Source

mock_responses(responses)

When mock responses are queued, chat() returns them in order instead of calling the LLM or using echo mode. This is useful for documentation examples, deterministic testing, and demos that need realistic-looking output without requiring API keys.

Responses are consumed in FIFO order. Once exhausted, the chatbot reverts to its normal behavior (LLM or echo mode).

Parameters

responses: list[str]: A list of response strings to return sequentially from chat().

Returns

ChatBot: The same instance for method chaining.

Examples

import talk_box as tb

bot = tb.ChatBot().mock_responses([
    "Hello! How can I help you today?",
    "I'd be happy to assist with that.",
])

convo = bot.chat("Hi there")
print(convo.get_last_message().content)
# "Hello! How can I help you today?"

model()

Configure the language model to use for generating responses.

Usage

Source

model(model_name)

Sets the specific language model that will be used when the chatbot generates responses. This method supports models from various providers including OpenAI, Anthropic, Google, and others through the chatlas integration. The model choice significantly impacts response quality, speed, cost, and capabilities.

The chatbot automatically detects the appropriate provider based on the model name and handles authentication via environment variables. Different models have different strengths as some excel at reasoning, others at creativity, and others at specific domains like code generation.

Parameters

model_name: str: The name of the language model to use. Exact model names may vary by provider. Check provider documentation for the most current model names and capabilities.

Returns

ChatBot: Returns self to enable method chaining, allowing you to configure multiple parameters in a single fluent expression.

Raises

ValueError: If the model name is empty or None. The method does not validate model availability at configuration time. Validation occurs when creating chat sessions.

Model Types By Provider

Here are some examples of model types by provider:

OpenAI Models:

"gpt-4o": latest multimodal model with excellent capabilities
"gpt-4-turbo": GPT-4 with improved performance and lower cost
"gpt-4": Original GPT-4 model with excellent reasoning capabilities
"gpt-3.5-turbo": fast, cost-effective model good for most tasks (default)

Anthropic Models:

"claude-sonnet-4-6": Claude model with excellent reasoning
"claude-haiku-4-5": fast, efficient model for simple tasks
"claude-opus-4-7": very capable Claude model for complex tasks

Google Models:

"gemini-pro": The flagship model from Google

Examples

Using different models for different purposes

Configure chatbots with models optimized for specific tasks:

import talk_box as tb

# High-performance model for complex reasoning
reasoning_bot = tb.ChatBot().model("gpt-4-turbo")

# Default balanced model (recommended starting point)
balanced_bot = tb.ChatBot().model("gpt-3.5-turbo")

# Fast, cost-effective model for simple tasks
quick_bot = tb.ChatBot().model("gpt-3.5-turbo")

# Creative model for storytelling
creative_bot = tb.ChatBot().model("claude-opus-4-7")

# Multimodal model for image analysis
vision_bot = tb.ChatBot().model("gpt-4o")

Model selection with method chaining

Combine model selection with other configuration options:

import talk_box as tb

# Technical advisor with high-performance model
tech_bot = (
    tb.ChatBot()
    .model("gpt-4-turbo")
    .preset("technical_advisor")
    .temperature(0.2)  # Low creativity for factual responses
    .max_tokens(2000)
)

# Creative writer with Claude
writer_bot = (
    tb.ChatBot()
    .model("claude-opus-4-7")
    .preset("creative_writer")
    .temperature(0.8)  # High creativity
    .persona("Imaginative storyteller with rich vocabulary")
)

Dynamic model switching

Change models based on task requirements:

import talk_box as tb

bot = tb.ChatBot().preset("technical_advisor")

# Use fast model for quick questions
bot.model("gpt-3.5-turbo")
quick_response = bot.chat("What is Python?")

# Switch to powerful model for complex analysis
bot.model("gpt-4-turbo")
detailed_response = bot.chat("Explain the architectural trade-offs between microservices and monoliths")

Model capabilities and selection guide

Choose models based on your specific requirements:

import talk_box as tb

# For code generation and technical tasks
code_bot = tb.ChatBot().model("gpt-4-turbo").preset("technical_advisor")

# For creative writing and storytelling
creative_bot = tb.ChatBot().model("claude-opus-4-7").preset("creative_writer")

# For cost-effective general tasks
general_bot = tb.ChatBot().model("gpt-3.5-turbo").preset("customer_support")

# For multimodal tasks (text + images)
vision_bot = tb.ChatBot().model("gpt-4o")

Notes

Provider Authentication: ensure appropriate API keys are set in environment variables (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY) for the chosen model provider.

Model Availability: model availability may change over time. Check provider documentation for current model names and deprecation schedules.

Cost Considerations: different models have different pricing structures. Consider cost implications for production deployments.

Rate Limits: each model/provider has different rate limits. Plan accordingly for high-volume applications.

Context Windows: models have different maximum context window sizes, affecting how much conversation history can be included in requests.

persona()

Set a persona that shapes the chatbot’s tone and behavior.

Usage

Source

persona(persona_description)

The persona string becomes the opening identity statement in the constructed system prompt (e.g., “You are {persona_description}”). It occupies the highest-attention primacy position, so it strongly influences all subsequent responses.

Parameters

persona_description: str: A natural-language description of who the chatbot should be. Can range from a short role label ("a helpful assistant") to a multi-sentence character brief.

Returns

ChatBot: The same instance for method chaining.

Examples

import talk_box as tb

bot = tb.ChatBot().persona("a senior Python developer")
bot.get_config()["persona"]

'a senior Python developer'

persona_pack()

Load a complete, production-ready persona configuration.

Usage

Source

persona_pack(name, *, default_guards=True)

Personas are comprehensive assistant configurations that bundle an attention-optimized system prompt, recommended models, tools, avoid topics, temperature, and token limits into a single loadable pack. Each persona is defined in YAML and tested for quality.

Unlike preset() (which sets tone/expertise/verbosity loosely), persona_pack() builds a full PromptBuilder-based system prompt using research-backed attention patterns (primacy bias, clustering, recency bias).

Personas may also declare default guardrails (e.g., PII detection, disclaimers) that are applied automatically. Pass default_guards=False to skip them.

Parameters

name: str: The persona name (e.g., "customer_support_tier1", "code_reviewer"). Use talk_box.personas.list_personas() to see all available names.
default_guards: bool = True: Whether to apply the persona’s default guardrails. Defaults to True. Set to False to load the persona without any automatic guards.

Returns

ChatBot: Returns self for method chaining.

Raises

KeyError: If the persona name is not found.

Examples

>>> import talk_box as tb
>>> bot = tb.ChatBot().persona_pack("code_reviewer")
>>> bot = tb.ChatBot().persona_pack("customer_support_tier1").model("ollama:llama4")
>>> bot = tb.ChatBot().persona_pack("financial_advisor", default_guards=False)

preset()

Apply a pre-configured behavior template to instantly specialize the chatbot.

Usage

Source

preset(preset_name)

Presets are professionally crafted behavior templates that instantly configure multiple aspects of the chatbot including conversational tone, expertise areas, response verbosity, operational constraints, and system prompts. This provides a quick way to create specialized chatbots for specific domains without manually configuring each parameter.

The preset system includes a curated library of templates covering common use cases like customer support, technical advisory, creative writing, data analysis, and legal information. Each preset is designed by experts to provide optimal performance for its intended domain while maintaining flexibility for customization.

When a preset is applied, it sets default values for various configuration parameters. You can still override individual settings after applying a preset, allowing for both rapid deployment and fine-tuned customization.

Parameters

preset_name: Union[str, PresetNames]

The name of the behavior preset to apply. You can use either a string or a constant from PresetNames for better autocomplete and type safety.

Using PresetNames constants (recommended):

import talk_box as tb
bot = tb.ChatBot().preset(tb.PresetNames.TECHNICAL_ADVISOR)

See the “Available Presets” section below for a complete list of available presets and their descriptions.

Returns

ChatBot: Returns self to enable method chaining, allowing you to combine preset application with other configuration methods.

Raises

ValueError: If the preset name is not found in the available preset library. The method fails gracefully and continues if preset loading encounters issues.

Available Presets

The Talk Box framework includes professionally crafted presets for common use cases:

Business and Support:

PresetNames.CUSTOMER_SUPPORT or "customer_support": polite, professional customer service interactions with concise responses and helpful guidance
PresetNames.LEGAL_ADVISOR or "legal_advisor": professional legal information with appropriate disclaimers and thorough, well-sourced responses

Technical and Development:

PresetNames.TECHNICAL_ADVISOR or "technical_advisor": authoritative technical guidance with detailed explanations, code examples, and best practices
PresetNames.DATA_ANALYST or "data_analyst": analytical, evidence-based responses for data science and statistical analysis tasks

Creative and Content:

PresetNames.CREATIVE_WRITER or "creative_writer": imaginative storytelling and creative content generation with descriptive, engaging responses

Additional presets may be available through custom preset libraries or organizational preset collections.

Examples

Using default presets for common scenarios

Apply presets for different types of interactions:

import talk_box as tb

# Customer support chatbot
support_bot = (
    tb.ChatBot()
    .preset("customer_support")
    .model("gpt-3.5-turbo")  # Fast, cost-effective for support
)

# Technical advisor for development questions
tech_bot = (
    tb.ChatBot()
    .preset("technical_advisor")
    .model("gpt-4-turbo")  # Powerful model for complex technical questions
)

# Creative writing assistant
writer_bot = (
    tb.ChatBot()
    .preset("creative_writer")
    .model("claude-opus-4-7")  # Excellent for creative tasks
)

Combining presets with custom configuration

Start with a preset and customize specific aspects:

# Start with technical advisor preset, then customize
specialized_bot = (
    tb.ChatBot()
    .preset("technical_advisor")
    .persona("Senior Python developer specializing in web frameworks")
    .temperature(0.1)  # Very low randomness for precise technical answers
    .tools(["code_executor", "documentation_search"])
    .avoid(["deprecated_practices", "insecure_patterns"])
)

# Customer support with custom personality
friendly_support = (
    tb.ChatBot()
    .preset("customer_support")
    .persona("Enthusiastic and empathetic customer advocate")
    .verbose(True)  # Detailed explanations for complex issues
)

Preset-specific optimizations

Different presets work better with specific models and settings:

# Data analyst with analytical model and settings
analyst_bot = (
    tb.ChatBot()
    .preset("data_analyst")
    .model("gpt-4-turbo")  # Strong reasoning capabilities
    .temperature(0.2)  # Low creativity, high accuracy
    .max_tokens(2000)  # Allow detailed analysis
)

# Creative writer with creative model and settings
creative_bot = (
    tb.ChatBot()
    .preset("creative_writer")
    .model("claude-opus-4-7")  # Excellent creative capabilities
    .temperature(0.8)  # High creativity
    .max_tokens(3000)  # Allow longer creative outputs
)

Inspecting preset configuration

View what a preset configures before applying it:

# Get preset details
manager = tb.PresetManager()
tech_preset = manager.get_preset("technical_advisor")

if tech_preset:
    print(f"Tone: {tech_preset.tone}")
    print(f"Expertise: {tech_preset.expertise}")
    print(f"Verbosity: {tech_preset.verbosity}")
    print(f"Constraints: {', '.join(tech_preset.constraints)}")

# Apply preset and check final configuration
bot = tb.ChatBot().preset("technical_advisor")
config = bot.get_config()
print(f"Final config: {config}")

Dynamic preset switching

Change presets based on conversation context:

# Start with customer support
bot = tb.ChatBot().preset("customer_support")

# Handle general customer inquiry
response1 = bot.chat("I need help with my order")

# Switch to technical advisor for technical questions
bot.preset("technical_advisor")
response2 = bot.chat("How do I integrate your API?")

# Switch to data analyst for analytics questions
bot.preset("data_analyst")
response3 = bot.chat("What patterns do you see in our user data?")

Preset Customization

Individual Override: all preset settings can be overridden by calling the corresponding configuration methods after applying the preset.

Custom Presets: organizations can create custom presets using the PresetManager to add domain-specific behavior templates.

Preset Inheritance: advanced implementations can create preset hierarchies where specialized presets extend base presets with additional configuration.

Context Awareness: some presets include conditional logic in their system prompts that adapts behavior based on conversation context.

Notes

Preset Loading: presets are loaded from the PresetManager which initializes with a default library and can be extended with custom presets.

Graceful Failure: if a preset is not found or fails to load, the method continues without error, allowing the chatbot to function with default settings.

System Prompts: each preset includes carefully crafted system prompts that provide detailed behavioral instructions to the underlying language model.

Best Practices: choose presets that match your intended use case, then fine-tune with additional configuration methods as needed.

prompt_builder()

Create an attention-optimized prompt builder for declarative prompt composition.

Usage

Source

prompt_builder(builder_type="general")

This method returns a specialized prompt builder that implements attention-based structuring principles from modern prompt engineering research. The builder helps engineers create prompts with optimal attention patterns through a fluent, declarative API.

Based on research showing that structure matters more than specific word choices, this builder enables you to:

front-load critical information (primacy bias)
create structured sections for clear attention clustering
avoid attention drift through specific constraints
build modular, maintainable prompt components

Parameters

builder_type: Union[str, BuilderTypes] = "general": Type of prompt builder to create. You can use either a string or a constant from BuilderTypes for better autocomplete and type safety.

Returns

PromptBuilder: A prompt builder with methods for declarative prompt composition.

Available Builder Types

The following builder types are available:

BuilderTypes.GENERAL or "general": basic attention-optimized builder
BuilderTypes.ARCHITECTURAL or "architectural": pre-configured for code architecture analysis
BuilderTypes.CODE_REVIEW or "code_review": pre-configured for code review tasks
BuilderTypes.DEBUGGING or "debugging": pre-configured for debugging assistance

Examples

Basic attention-optimized prompt building

import talk_box as tb

bot = tb.ChatBot().model("gpt-4-turbo")

# Build an attention-optimized prompt
prompt = (bot.prompt_builder()
    .persona("senior software architect", "comprehensive codebase analysis")
    .task_context("Create architectural documentation")
    .critical_constraint("Focus on identifying architectural debt")
    .core_analysis([
        "Tools, frameworks, and design patterns",
        "Data models and API design patterns",
        "Architectural inconsistencies"
    ])
    .output_format([
        "Use clear headings and bullet points",
        "Include specific examples from codebase"
    ])
    .final_emphasis("Prioritize findings by impact and consistency")
    .build())

# Use the structured prompt
response = bot.chat(prompt)

Pre-configured builders for common tasks

# Architectural analysis with pre-configured structure
arch_prompt = (bot.prompt_builder(tb.BuilderTypes.ARCHITECTURAL)
    .focus_on("identifying technical debt")
    .build())

# Code review with attention-optimized structure
review_prompt = (bot.prompt_builder(tb.BuilderTypes.CODE_REVIEW)
    .avoid_topics(["personal criticism"])
    .focus_on("actionable improvement suggestions")
    .build())

Preview prompt structure before building

builder = (bot.prompt_builder()
    .persona("technical advisor")
    .core_analysis(["Security", "Performance", "Maintainability"])
    .output_format(["Structured sections", "Specific examples"]))

# Preview the attention structure
structure = builder.preview_structure()
print(f"Estimated tokens: {structure['estimated_tokens']}")
print(f"Priority sections: {len(structure['structured_sections'])}")

# Build when satisfied with structure
prompt = builder._build()

Notes

The returned builder implements attention-based principles:

Primacy bias: critical information is front-loaded
Structured sections: clear attention clustering prevents drift
Personas: behavioral anchoring for consistent responses
Specific constraints: avoid vague instructions that cause attention drift
Recency bias: final emphasis leverages end-of-prompt attention

provider_model()

Set provider and model using a single string (e.g., “openai:gpt-4o”).

Usage

Source

provider_model(provider_model)

This method provides a convenient way to configure both the AI provider and model in a single call using a colon-separated format. This is especially useful when you want to explicitly specify the provider or when working with models from different providers that might have similar names.

Parameters

provider_model: str: String in the format "provider:model" (e.g., "openai:gpt-4o", "anthropic:claude-3-opus"). If only a model name is provided without a colon, defaults to OpenAI provider.

Returns

ChatBot: Returns self for method chaining, allowing you to configure multiple parameters in a single fluent expression.

Raises

ValueError: If the provider_model= string is empty, None, or improperly formatted.

Examples

Using explicit provider and model combinations

import talk_box as tb

# OpenAI models
openai_bot = tb.ChatBot().provider_model("openai:gpt-4o")

# Anthropic models
anthropic_bot = tb.ChatBot().provider_model("anthropic:claude-opus-4-7")

# Google models
google_bot = tb.ChatBot().provider_model("google:gemini-pro")

# Default to OpenAI if no provider specified
default_bot = tb.ChatBot().provider_model("gpt-4-turbo")

Method chaining with provider_model

# Complete configuration with explicit provider
bot = (
    ChatBot()
    .provider_model("anthropic:claude-opus-4-7")
    .preset("technical_advisor")
    .temperature(0.2)
    .max_tokens(2000)
)

Notes

Provider Authentication: ensure appropriate API keys are set in environment variables for the specified provider (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY).

Provider Detection: when only a model name is provided, the system defaults to OpenAI. For other providers, always specify the provider explicitly.

quick_start()

Get a quick-start guide tailored to this chatbot’s current configuration.

Usage

Source

quick_start()

The guide covers basic usage commands, configuration options, and the chatbot’s active settings (model, temperature, etc.).

Returns

str: A multi-line guide string ready to print.

Examples

import talk_box as tb

bot = tb.ChatBot().model("gpt-4")
guide = bot.quick_start()
"gpt-4" in guide

True

show()

Display diagnostic information or launch chat interfaces.

Usage

Source

show(mode="help")

This method provides explicit control over displaying diagnostic information and launching chat interfaces, complementing the automatic display when the ChatBot object is shown.

Parameters

mode: str = "help"

The type of interface to show:

"browser": launch browser chat interface
"console": launch interactive console/terminal chat
"config": display configuration summary in notebook
"prompt": display the final system prompt
"help": show quick-start guide for using this ChatBot
"status": check LLM integration status and troubleshooting
"install": show step-by-step chatlas installation guide

Examples

>>> bot = ChatBot().model("gpt-4").preset("technical_advisor")
>>> bot.show("help")        # Show quick-start guide (default)
>>> bot.show("status")      # Check LLM integration status
>>> bot.show("browser")     # Launch browser chat interface
>>> bot.show("console")     # Launch terminal chat interface
>>> bot.show("config")      # Show configuration summary

start_conversation()

Start a new conversation with this chatbot.

Usage

Source

start_conversation()

Creates a fresh conversation instance that can be used for multi-turn interactions with the chatbot. This is useful when you want to explicitly manage conversation state and context.

Returns

Conversation: A new, empty conversation instance ready for interaction.

Examples

Starting a managed conversation

import talk_box as tb

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

# Start a new conversation
conversation = bot.start_conversation()

# Add messages manually or use chat method
conversation.add_user_message("Hello!")
updated_conversation = bot.chat("How are you?", conversation=conversation)

structured_prompt()

Configure the chatbot with a structured prompt built from keyword sections.

Usage

Source

structured_prompt(**sections)

This is a convenience method for quickly building attention-optimized prompts without using the full prompt builder API. It automatically structures the provided sections according to attention-based principles.

Parameters

**sections: Keyword arguments defining prompt sections.

Returns

ChatBot: Returns self for method chaining

Recognized Keyword Arguments

persona: behavioral role (e.g., "senior developer")
task: primary task description
constraints: list of requirements or constraints
format: list of output formatting requirements
examples: dict of input/output examples
focus: primary goal to emphasize

Examples

Quick structured prompt creation

import talk_box as tb

bot = (
    tb.ChatBot()
    .model("gpt-4-turbo")
    .structured_prompt(
        persona="senior software architect",
        task="Analyze codebase architecture and identify improvements",
        constraints=[
            "Focus on security vulnerabilities",
            "Identify performance bottlenecks",
            "Suggest specific fixes"
        ],
        format=[
            "Use bullet points for findings",
            "Include code examples",
            "Prioritize by severity"
        ],
        focus="actionable recommendations for immediate implementation"
    )
)

Combining with other configuration

expert_bot = (
    tb.ChatBot()
    .model("gpt-4-turbo")
    .temperature(0.2)
    .structured_prompt(
        persona="expert debugger",
        task="Identify root cause of performance issues",
        constraints=["Provide reproducible test cases"],
        focus="finding the root cause, not just symptoms"
    )
    .max_tokens(1500)
)

system_prompt()

Set a custom system prompt, overriding any preset system prompt.

Usage

Source

system_prompt(prompt)

This method allows for fine-grained prompt engineering. The custom system prompt will take precedence over any preset system prompt, though it will still be combined with persona, constraints, and other configuration elements.

Three Approaches To System Prompt Creation

Direct String Approach: pass a complete system prompt as a single string. This is straightforward for simple prompts or when adapting existing prompts.

ChatBot.prompt_builder() Method (Recommended): use the attention-optimized prompt_builder() method from a ChatBot instance. This provides better structure, maintainability, and leverages modern prompt engineering research on attention patterns.

PromptBuilder Class: use the PromptBuilder class directly for maximum flexibility and reusable prompt templates that can be used across multiple ChatBot instances.

The structured prompt approaches (methods 2 and 3) are especially valuable for:

complex multi-section prompts
professional domain specializations
prompts requiring consistent structure across variations
team environments where prompt templates need to be maintainable
reusable prompt templates across different chatbot configurations

Parameters

prompt: Union[str, PromptBuilder]: The custom system prompt text. Can include prompt engineering techniques, specific instructions, formatting requirements, etc.

Returns

ChatBot: Returns self for method chaining

Examples

Comparing the three approaches

Direct String Approach: simple and direct:

import talk_box as tb

# Quick setup with string prompt
bot = tb.ChatBot().model("gpt-4-turbo").system_prompt(
    "You are a helpful Python tutor. Always provide working code examples "
    "and explain the reasoning behind each solution."
)

ChatBot.prompt_builder() Method: structured and maintainable:

import talk_box as tb

# Same functionality with better structure
bot = tb.ChatBot().model("gpt-4-turbo")

# Build an attention-optimized prompt
prompt = (
    bot.prompt_builder()
    .persona("helpful Python tutor", "educational programming assistance")
    .core_analysis(["Provide working code examples", "Explain reasoning behind solutions"])
    .output_format(["Clear step-by-step explanations", "Commented code examples"])
    ._build()
)

# Apply the structured prompt
bot.system_prompt(prompt)

PromptBuilder Class Directly: maximum flexibility and reusability:

import talk_box as tb

# Create reusable prompt template
python_tutor_template = (
    tb.PromptBuilder()
    .persona("helpful Python tutor", "educational programming assistance")
    .core_analysis(["Provide working code examples", "Explain reasoning behind solutions"])
    .output_format(["Clear step-by-step explanations", "Commented code examples"])
    ._build()
)

# Use the same template across multiple bots
beginner_bot = tb.ChatBot().model("gpt-3.5-turbo").system_prompt(python_tutor_template)
advanced_bot = tb.ChatBot().model("gpt-4-turbo").system_prompt(python_tutor_template)

Why structured approaches are recommended for complex prompts

For complex professional domains, structured prompt building provides superior results:

import talk_box as tb

# Create a security code reviewer with attention-optimized structure
bot = tb.ChatBot().model("gpt-4-turbo")

security_prompt = (
    bot.prompt_builder()
    .persona("senior security engineer", "application security code review")
    .task_context("Comprehensive security review following OWASP methodology")
    .critical_constraint("Prioritize security vulnerabilities over style issues")
    .core_analysis([
        "Input validation and sanitization",
        "Authentication and authorization controls",
        "Secure data handling (encryption, PII protection)",
        "Error handling (no sensitive info in errors)",
        "Dependencies and third-party library security"
    ])
    .output_format([
        "🚨 CRITICAL ISSUES: Security vulnerabilities with CVSS scores",
        "⚠️ HIGH PRIORITY: Logic errors and architectural problems",
        "📈 IMPROVEMENTS: Performance and maintainability suggestions"
    ])
    .final_emphasis("Professional, constructive tone with educational explanations")
    ._build()
)

bot.system_prompt(security_prompt)

Benefits of this structured approach:

clear attention hierarchy (critical info first)
maintainable and modifiable sections
consistent output format across reviews
research-backed attention optimization

Using PromptBuilder class for reusable templates

The direct PromptBuilder class approach excels for template reuse across teams:

import talk_box as tb

# Create a reusable code review template
code_review_template = (
    tb.PromptBuilder()
    .persona("experienced software engineer", "comprehensive code review")
    .task_context("Thorough code review focusing on quality and best practices")
    .core_analysis([
        "Code correctness and logic",
        "Performance and efficiency",
        "Security considerations",
        "Maintainability and readability",
        "Test coverage and edge cases"
    ])
    .output_format([
        "## Summary: Overall assessment and key points",
        "## Issues: Specific problems with line references",
        "## Suggestions: Concrete improvement recommendations",
        "## Strengths: What the code does well"
    ])
    .final_emphasis("Constructive feedback that helps developers improve")
    ._build()
)

# Use the same template across different team contexts
senior_reviewer = tb.ChatBot().model("gpt-4-turbo").system_prompt(code_review_template)
junior_reviewer = tb.ChatBot().model("gpt-3.5-turbo").system_prompt(code_review_template)

# Customize for specific languages while keeping base structure
python_template = (
    tb.PromptBuilder()
    .from_template(code_review_template)  # Inherit base structure
    .add_constraint("Focus on Pythonic idioms and PEP 8 compliance")
    ._build()
)

python_reviewer = tb.ChatBot().model("gpt-4-turbo").system_prompt(python_template)

When to use each approach:

Direct String: simple, one-off prompts
ChatBot.prompt_builder(): complex prompts for single bot instance
PromptBuilder Class: reusable templates, team standards, prompt libraries

Best Practices

Use direct strings for simple prompts: quick, straightforward prompts work well with direct string assignment when you need something fast and simple.

Use ChatBot.prompt_builder() for complex single-use prompts: when creating sophisticated system prompts for a specific ChatBot instance with multiple sections, constraints, and formatting requirements.

Use PromptBuilder class directly for reusable templates: when you need prompt templates that can be shared across multiple ChatBot instances, team standards, or organizational prompt libraries.

Combine with other methods: all three approaches work seamlessly with .persona(), .avoid(), and other configuration methods for additional customization.

Template Hierarchy: consider creating base templates with PromptBuilder class and extending them for specific use cases to maintain consistency while allowing customization.

Notes

Attention Optimization: both PromptBuilder approaches create prompts that follow modern prompt engineering research on attention patterns and cognitive load optimization.

Maintenance: structured prompts created with PromptBuilder are easier to modify, debug, and version control in team environments.

Performance: all three approaches result in equivalent runtime performance; the choice is primarily about development experience, maintainability, and reusability needs.

temperature()

Control the randomness and creativity level of chatbot responses.

Usage

Source

temperature(temp)

Temperature is a crucial parameter that controls the balance between deterministic accuracy and creative variability in language model outputs. Lower temperatures produce more focused, consistent, and predictable responses, while higher temperatures encourage more diverse, creative, and exploratory outputs at the potential cost of accuracy.

The temperature parameter directly affects the probability distribution over possible next tokens during text generation. At temperature 0, the model always selects the most likely next token, resulting in deterministic outputs. Higher temperatures flatten the probability distribution, allowing less likely but potentially more creative tokens to be selected.

Understanding temperature is essential for fine-tuning chatbot behavior to match specific use cases, from precise technical assistance to creative brainstorming and content generation.

Parameters

temp: float: The temperature value controlling response randomness, typically ranging from 0.0 to 2.0. Lower values produce more deterministic and consistent responses, while higher values encourage creativity and variability. See the “Temperature Ranges” section below for detailed guidance.

Returns

ChatBot: Returns self to enable method chaining, allowing you to combine temperature setting with other configuration methods.

Raises

ValueError: If temperature is negative or excessively high (typically > 2.0), though exact limits depend on the underlying model provider.

Temperature Ranges

Choose temperature values based on your specific use case requirements:

Ultra-Low (0.0-0.2):

0.0: completely deterministic, always chooses most likely response
0.1: near-deterministic with minimal variation
0.2: highly consistent with occasional minor variations
Best for: code generation, mathematical calculations, factual Q&A

Low (0.3-0.5):

0.3: consistent with slight creative touches
0.4: balanced consistency with controlled variation
0.5: moderate creativity while maintaining reliability
Best for: technical documentation, structured analysis, tutorials

Medium (0.6-0.8):

0.6: balanced creativity and consistency
0.7: default setting for most general-purpose applications
0.8: enhanced creativity with good coherence
Best for: conversational AI, content writing, explanations

High (0.9-1.2):

0.9: creative responses with acceptable coherence
1.0: high creativity, more diverse phrasings
1.2: very creative, potentially unexpected responses
Best for: brainstorming, creative writing, ideation

Ultra-High (1.3-2.0):

1.5: highly experimental and creative outputs
2.0: maximum creativity, potentially incoherent
Best for: artistic exploration, experimental content

Values above 2.0 are generally not recommended as they may produce incoherent or nonsensical responses.

Examples

Temperature for different use cases

Configure temperature based on your specific needs:

import talk_box as tb

# Ultra-precise for code generation and technical tasks
code_bot = (
    tb.ChatBot()
    .model("gpt-4-turbo")
    .temperature(0.0)  # Deterministic outputs
    .preset("technical_advisor")
)

# Balanced for general conversation
general_bot = (
    tb.ChatBot()
    .model("gpt-3.5-turbo")
    .temperature(0.7)  # Default balanced setting
)

# Creative for content generation
creative_bot = (
    tb.ChatBot()
    .model("claude-opus-4-7")
    .temperature(1.0)  # High creativity
    .preset("creative_writer")
)

Precision vs. creativity trade-offs

Demonstrate the impact of different temperature settings:

# For mathematical calculations: use minimal temperature
math_bot = (
    tb.ChatBot()
    .temperature(0.1)
    .persona("Mathematics tutor focused on step-by-step solutions")
)

# For brainstorming: use higher temperature
brainstorm_bot = (
    tb.ChatBot()
    .temperature(1.1)
    .persona("Creative strategist generating innovative ideas")
)

# For customer support: balanced approach
support_bot = (
    tb.ChatBot()
    .temperature(0.4)
    .preset("customer_support")
    .persona("Helpful and consistent customer service representative")
)

Domain-specific temperature optimization

Adjust temperature for specific professional domains:

# Legal analysis: high precision required
legal_bot = (
    tb.ChatBot()
    .preset("legal_advisor")
    .temperature(0.2)  # Low creativity, high accuracy
    .model("gpt-4-turbo")
)

# Marketing content: creative but controlled
marketing_bot = (
    tb.ChatBot()
    .temperature(0.8)  # Creative but coherent
    .persona("Brand-aware marketing specialist")
    .avoid(["generic_language", "cliches"])
)

# Data analysis: analytical precision
analyst_bot = (
    tb.ChatBot()
    .preset("data_analyst")
    .temperature(0.3)  # Consistent analytical approach
    .tools(["statistical_analysis", "data_visualization"])
)

Dynamic temperature adjustment

Adapt temperature based on conversation context:

class AdaptiveBot:
    def __init__(self):
        self.bot = tb.ChatBot().model("gpt-4-turbo")

    def answer_question(self, question: str, question_type: str):
        if question_type == "factual":
            self.bot.temperature(0.1)  # High precision
        elif question_type == "creative":
            self.bot.temperature(1.0)  # High creativity
        elif question_type == "analytical":
            self.bot.temperature(0.3)  # Balanced analysis
        else:
            self.bot.temperature(0.7)  # Default

        return self.bot.chat(question)

# Usage
adaptive = AdaptiveBot()

# Factual question with low temperature
factual_response = adaptive.answer_question(
    "What is the capital of France?",
    "factual"
)

# Creative question with high temperature
creative_response = adaptive.answer_question(
    "Write a haiku about machine learning",
    "creative"
)

Temperature with model-specific considerations

Different models respond differently to temperature settings:

# GPT models: standard temperature ranges
gpt_bot = (
    tb.ChatBot()
    .model("gpt-4-turbo")
    .temperature(0.7)  # Works well with GPT models
)

# Claude models: may handle higher temperatures better
claude_bot = (
    tb.ChatBot()
    .model("claude-opus-4-7")
    .temperature(0.9)  # Claude often maintains coherence at higher temps
)

# Local models: may need different calibration
local_bot = (
    tb.ChatBot()
    .model("llama-2-13b-chat")
    .temperature(0.5)  # Conservative for smaller models
)

A/B testing different temperatures

Compare response quality across temperature settings:

def compare_temperatures(question: str, temperatures: list[float]):
    """Compare the same question across different temperatures."""
    results = {}

    for temp in temperatures:
        bot = (
            tb.ChatBot()
            .model("gpt-4-turbo")
            .temperature(temp)
        )

        response = bot.chat(question)
        results[temp] = response

    return results

# Test different temperatures
question = "Explain quantum computing in simple terms"
temps = [0.2, 0.5, 0.8, 1.1]

comparison = compare_temperatures(question, temps)

for temp, response in comparison.items():
    print(f"Temperature {temp}:")
    print(f"{response.content[:100]}...")
    print()

Temperature Guidelines

Code Generation: Use 0.0-0.2 for precise, syntactically correct code with minimal variation.

Technical Writing: Use 0.2-0.4 for accurate, consistent technical documentation and explanations.

General Conversation: Use 0.6-0.8 for natural, engaging dialogue with appropriate variation.

Creative Content: Use 0.8-1.2 for storytelling, marketing copy, and creative ideation.

Brainstorming: Use 1.0-1.5 for maximum idea diversity and out-of-the-box thinking.

Model Considerations

Provider Differences: different AI providers may interpret temperature values differently, so test with your specific model.

Model Size: larger models often handle higher temperatures better while maintaining coherence.

Fine-tuned Models: custom fine-tuned models may have different optimal temperature ranges compared to base models.

Context Length: longer conversations may benefit from slightly lower temperatures to maintain consistency.

Notes

Reproducibility: use temperature 0.0 for reproducible outputs across multiple runs with the same input.

Gradual Adjustment: when uncertain, start with default (0.7) and adjust incrementally based on response quality.

Task Specificity: consider the specific requirements of your task when choosing temperature (accuracy vs. creativity trade-offs).

Monitoring: monitor response quality when adjusting temperature, as optimal values may vary by use case and model.

tools()

Configure tools for this chatbot with unified API for custom and built-in tools.

Usage

Source

tools(tools)

This method provides a single, consistent way to add any combination of: - Built-in Tool Box tools (by string name) - Custom tools (by passing TalkBoxTool objects) - Tools from Python files (by file/directory path) - All Tool Box tools (with “all” shortcut)

Parameters

tools: Union[list[str], list[TalkBoxTool], str]

Tools to add to this chatbot. Can be:

List of string names for built-in Tool Box tools: [“calculate”, “web_search”]
List of TalkBoxTool objects for custom tools: [my_custom_tool, another_tool]
Mixed list: [“calculate”, my_custom_tool, “web_search”, “my_tools.py”]
String “all” to load all built-in Tool Box tools
Python file path: “my_tools.py” to load all tools from file
Directory path: “./tools/” to load all tools from directory

Returns

ChatBot: The chatbot instance with tools configured for method chaining

Examples

>>> # Add specific built-in tools
>>> bot = ChatBot().tools(["calculate", "text_stats", "validate_email"])

>>> # Add custom tools
>>> bot = ChatBot().tools([my_custom_tool, another_custom_tool])

>>> # Mix built-in and custom tools
>>> bot = ChatBot().tools(["calculate", my_custom_tool, "web_search"])

>>> # Load all built-in tools
>>> bot = ChatBot().tools("all")

>>> # Load tools from Python file
>>> bot = ChatBot().tools("my_business_tools.py")

>>> # Load tools from directory
>>> bot = ChatBot().tools("./company_tools/")

>>> # Mix file loading with other tools
>>> bot = ChatBot().tools(["calculate", "my_tools.py", my_custom_tool])

>>> # Chaining - add more tools later
>>> bot = ChatBot().tools(["calculate"]).tools([my_custom_tool])

verbose()

Enable or disable verbose diagnostic output during chat interactions.

Usage

Source

verbose(enabled=True)

When verbose mode is active the chatbot prints additional diagnostic information (e.g., prompt construction details, model parameters) to stdout during each call to chat() or show().

Parameters

enabled: bool = True: Set to True to turn on verbose output, False to silence it. Defaults to True.

Returns

ChatBot: The same instance for method chaining.

Examples

import talk_box as tb

bot = tb.ChatBot().verbose()
bot.get_config()["verbose"]

True

Notes

Returns

Conversation Management

Chainable Configuration Methods

Browser Integration

Examples

Basic conversation flow

Advanced conversation management

Discovering the full API layer by layer

Attributes

preset_manager

Methods

__init__()

Parameters

add_tools()

Parameters

Returns

Examples

avoid()

Parameters

Returns

Examples

chain_prompts()

Parameters

Returns

Examples

Chaining different prompt components

chat()

Parameters

Returns

Examples

Basic single-message chat

Chat with file attachments

Continuing a conversation

check_llm_status()

Returns

Examples

continue_conversation()

Parameters

Returns

Examples

create_chat_session()

Returns

Examples

enable_llm_mode()

Returns

Note

enable_tool_box()

Returns

Examples

get_avoid_topics()

Returns

Examples

get_config()

Returns

Examples

get_config_summary()

Returns

Examples

get_system_prompt()

Returns

Examples

get_usage()

Returns

Examples

guard_stats()

Returns

Examples

guardrail()

Parameters

Returns

Examples

install_chatlas_help()

Returns

max_tokens()

Parameters

Returns

Raises

Token Usage Guidelines

Examples

init()