<div align="center">
**The best way to generate, test, and deploy LLM chatbots with attention-optimized prompt engineering**
[](https://pypi.org/project/talk-box/#history)
[](https://opensource.org/licenses/MIT)
[](https://github.com/rich-iannone/talk-box/actions/workflows/ci-tests.yaml)
[](https://www.repostatus.org/#active)
[](https://rich-iannone.github.io/talk-box/)
[](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html)
</div>
Talk Box is a Python framework that transforms prompt engineering from an art into a systematic
engineering discipline. Create effective, maintainable prompts using research-backed attention
mechanisms, then deploy them with powerful conversation management.
## Why Talk Box?
- **Attention-Based Prompt Engineering**: build prompts that leverage how LLMs actually process
information
- **Adversarial Testing Framework**: robust evaluation of prompt performance against challenging scenarios
- **Layered API Design**: start simple, discover advanced features as you need them
- **Multiple Usage Patterns**: from quick structured prompts to complex modular components
- **Integrated Conversation Management**: seamless multi-turn conversations with full history
- **Built-in Behavior Presets**: professional templates for common engineering tasks
## The Science Behind Structured Prompts
Most prompt engineering is done ad-hoc, leading to inconsistent results and hard-to-maintain systems. Talk Box applies research from transformer attention mechanisms to create a systematic approach.
Having structure matters because LLMs process information through attention patterns. Unstructured prompts scatter attention across irrelevant details, while structured prompts focus attention on what matters most.
**Key Principles**:
- **Primacy Bias**: critical information goes first (personas, constraints)
- **Attention Clustering**: related concepts are grouped together
- **Recency Bias**: final emphasis reinforces the most important outcomes
- **Hierarchical Processing**: clear sections help models organize their reasoning
Here is a schematic of how we consistently structure a prompt:
Now let's see how this works in practice.
## Quick Start
### 30-Second Demo: Attention-Optimized Prompts
```python
import talk_box as tb
# Create a security-focused chatbot with structured prompts
bot = (
tb.ChatBot()
.provider_model("anthropic:claude-sonnet-4-20250514")
.system_prompt(
tb.PromptBuilder()
.persona("senior security engineer", "web application security")
.critical_constraint("Focus only on CVSS 7.0+ vulnerabilities")
.core_analysis([
"SQL injection risks",
"Authentication bypass possibilities",
"Data validation gaps"
])
.output_format([
"CRITICAL: Immediate security risks",
"Include specific line numbers and fixes"
])
.final_emphasis("Prioritize vulnerabilities leading to data breaches")
.build()
)
)
# View details of the structured prompt
bot.show("prompt")
```
<details>
<summary>🔍 View Generated Prompt</summary>
```
You are a senior security engineer with expertise in web application security.
CRITICAL REQUIREMENTS:
- Focus only on CVSS 7.0+ vulnerabilities
CORE ANALYSIS (Required):
- SQL injection risks
- Authentication bypass possibilities
- Data validation gaps
OUTPUT FORMAT:
- CRITICAL: Immediate security risks
- Include specific line numbers and fixes
Prioritize vulnerabilities leading to data breaches
```
</details>
### Even Simpler: Quick Structured Prompts with `structured_prompt()`
```python
import talk_box as tb
# Configure a bot with structured prompts in one go
doc_bot = (
tb.ChatBot()
.provider_model("anthropic:claude-sonnet-4-20250514")
.structured_prompt(
persona="technical writer",
task="Review and improve documentation",
constraints=["Focus on clarity and accessibility", "Include code examples"],
format=["Content improvements", "Structure suggestions"],
focus="making complex topics easy to understand"
)
)
# Now just chat directly as the structure is built into the bot's system prompt
response = doc_bot.chat("Here's my API documentation draft...")
```
<details>
<summary>🔍 View Generated Prompt</summary>
```
You are a technical writer with expertise in documentation and user education.
CRITICAL REQUIREMENTS:
- Focus on clarity and accessibility
CORE ANALYSIS (Required):
- Include code examples
- Ensure content improvements
- Provide structure suggestions
OUTPUT FORMAT:
- Content improvements
- Structure suggestions
Prioritize making complex topics easy to understand
```
</details>
## The Core Feature is Attention Optimization
We can build prompts that leverage how transformer attention mechanisms actually work. The `PromptBuilder` class in Talk Box is designed to help you create these optimized prompts easily.
Let's see an example on how to create a language learning bot:
```python
import talk_box as tb
# Traditional approach (attention-diffused)
old_prompt = "Help me learn Spanish and correct my mistakes."
# Attention-optimized approach
bot = (
tb.ChatBot()
.provider_model("anthropic:claude-sonnet-4-20250514")
.system_prompt(
tb.PromptBuilder()
.persona("experienced Spanish teacher", "conversational fluency and grammar")
.critical_constraint("Focus on practical, everyday Spanish usage")
.core_analysis([
"Grammar accuracy and common mistakes",
"Vocabulary building with context",
"Pronunciation and speaking confidence"
])
.output_format([
"CORRECCIONES: Grammar fixes with explanations",
"VOCABULARIO: New words with example sentences",
"PRÁCTICA: Conversation prompts for next lesson"
])
.final_emphasis("Encourage progress and build confidence through positive reinforcement")
.build()
)
)
# Get learning right in the console
response = bot.show("console")
```
<details>
<summary>🔍 View Generated Prompt</summary>
```
You are an experienced Spanish teacher with expertise in conversational fluency and grammar.
CRITICAL REQUIREMENTS:
- Focus on practical, everyday Spanish usage
CORE ANALYSIS (Required):
- Grammar accuracy and common mistakes
- Vocabulary building with context
- Pronunciation and speaking confidence
OUTPUT FORMAT:
- CORRECCIONES: Grammar fixes with explanations
- VOCABULARIO: New words with example sentences
- PRÁCTICA: Conversation prompts for next lesson
Prioritize encouraging progress and building confidence through positive reinforcement
```
</details>
Looking at the generated prompts, we can identify several key principles that contribute to their effectiveness. The key principles of a successful structured prompt implementation are:
- **Front-loading critical information** (primacy bias)
- **Structure creates focus** (attention clustering)
- **Personas for behavioral anchoring**
- **Specific constraints prevent attention drift**
- **Final emphasis leverages recency bias**
And we've implemented these principles in our prompt engineering process, ensuring that the prompts
you create and use are effective and aligned with these best practices.
## Modern Web Interface
Launch a polished React-based chat interface by using `show("react")`:
```python
import talk_box as tb
# Create and configure a chatbot
bot = (
tb.ChatBot(
name="FriendlyBot",
description="A bot that'll talk about any topic."
)
.model("gpt-4")
.temperature(0.3)
.persona("You are a friendly conversationalist")
)
bot.show("react")
```
The React interface provides a professional chat experience with:
- **Modern Design**: clean, responsive interface that works on desktop and mobile
- **Live Typing Indicators**: visual feedback during bot responses
- **Code Block Highlighting**: syntax highlighting for technical conversations
- **Conversation History**: full chat history with easy navigation
- **Bot Configuration Display**: see your bot's settings and persona at a glance
## Pre-configured Engineering Templates
Start with expert-crafted prompts for common engineering tasks:
```python
import talk_box as tb
# Architectural analysis with attention optimization
arch_bot = (
tb.ChatBot()
.provider_model("anthropic:claude-sonnet-4-20250514")
.prompt_builder("architectural")
.focus_on("identifying technical debt and modernization opportunities")
)
# Code review with structured feedback
review_bot = (
tb.ChatBot()
.provider_model("anthropic:claude-sonnet-4-20250514")
.prompt_builder("code_review")
.avoid_topics(["personal criticism", "style nitpicking"])
.focus_on("actionable security and performance improvements")
)
# Systematic debugging approach
debug_bot = (
tb.ChatBot()
.provider_model("anthropic:claude-sonnet-4-20250514")
.prompt_builder("debugging")
.critical_constraint("Always identify root cause, not just symptoms")
)
```
## Integrated Conversation Management
All chat interactions automatically return conversation objects for seamless multi-turn conversations:
```python
import talk_box as tb
bot = tb.ChatBot().model("gpt-4o-mini").preset("technical_advisor")
# Every chat returns a conversation object with full history
conversation = bot.chat("What's the best way to implement authentication?")
conversation = bot.chat("What about JWT tokens specifically?", conversation)
conversation = bot.chat("Show me a Python example", conversation)
# Access the full conversation history
messages = conversation.get_messages()
latest = conversation.get_last_message()
print(f"Conversation has {conversation.get_message_count()} messages")
```
```
Conversation has 6 messages
```
## File Attachments for AI Analysis
Analyze documents, images, and code files directly in your conversations. Talk Box automatically handles different file types and integrates seamlessly with your prompts:
```python
import talk_box as tb
# Step 1: Create a ChatBot for analysis
bot = tb.ChatBot().provider_model("openai:gpt-4-turbo")
# Step 2: Attach a file with analysis prompt
files = tb.Attachments("report.pdf").with_prompt(
"Summarize the key findings in this report."
)
# Step 3: Get LLM analysis
analysis = bot.chat(files)
```
<div align="center">
<img src="https://rich-iannone.github.io/talk-box/assets/abraham-results.png" width="800px">
</div>
**Supported file types**: PDFs, images (PNG, JPG), text files (Python, JavaScript, Markdown, CSV, JSON), and more. Perfect for code reviews, document analysis, data insights, and visual content evaluation.
## Built-in Behavior Presets
Choose from a few professionally-crafted personalities:
- **`technical_advisor`**: authoritative, detailed, evidence-based
- **`customer_support`**: polite, helpful, solution-focused
- **`creative_writer`**: imaginative, expressive, storytelling
- **`data_analyst`**: analytical, precise, metrics-driven
- **`legal_advisor`**: professional, thorough, disclaimer-aware
```python
import talk_box as tb
support_bot = tb.ChatBot().preset("customer_support")
creative_bot = tb.ChatBot().preset("creative_writer")
analyst_bot = tb.ChatBot().preset("data_analyst")
```
## Automated Avoid Topics Testing
Verify that your ChatBots properly refuse to engage with prohibited topics through our adversarial testing framework. With one function, `autotest_avoid_topics()`, this is all very easy:
```python
import talk_box as tb
# Create a wellness coach that should avoid gaming topics
wellness_bot = (
tb.ChatBot()
.provider_model("openai:gpt-4-turbo")
.system_prompt(
tb.PromptBuilder()
.persona("productivity and wellness coach", "work-life balance")
.avoid_topics(["video games", "gaming"])
.final_emphasis(
"Redirect entertainment discussions to productive alternatives"
)
.build()
)
)
# Test compliance with sophisticated adversarial strategies
results = tb.autotest_avoid_topics(wellness_bot, test_intensity="thorough")
# View rich results in notebooks or check compliance programmatically
print(f"Compliance rate: {results.summary['success_rate']:.1%}")
print(f"Violations found: {results.summary['violation_count']}")
```
You can generate a visual HTML report for easy compliance review in a notebook environment:
```python
results
```
The HTML report displays each adversarial conversation with **color-coded compliance indicators**, making it easy to spot transgressions at a glance. You can quickly scan through dozens of test scenarios and immediately identify where your chatbot may have inappropriately engaged with forbidden topics.
The testing framework uses multiple adversarial strategies:
- **Direct requests** for prohibited information
- **Indirect/hypothetical** scenarios
- **Emotional appeals** and urgency
- **Role-playing** (academic, professional contexts)
- **Context shifting** from acceptable to prohibited topics
- **Persistent follow-ups** after initial refusal
Results provide detailed analysis including conversation transcripts, violation detection with severity ratings, and export capabilities for quality assurance workflows.
## Installation
The Talk Box framework can be installed via pip:
```bash
pip install talk-box
```
If you encounter a bug, have usage questions, or want to share ideas to make this package better, please feel free to [open an issue](https://github.com/rich-iannone/talk-box/issues).
## Roadmap
Talk Box is actively evolving to become a comprehensive prompt engineering and LLM deployment framework. Here are the major features and enhancements planned for future releases:
### Advanced Prompt Engineering
- **Dynamic Prompt Adaptation**: automatically adjust prompt structure based on model capabilities and response quality metrics
- **Catalog of Prompt Templates**: a collection of domain-specific prompt templates with performance benchmarks
- **Multi-Modal Prompt Support**: extend structured prompting to include images, audio, and video inputs with attention optimization
### Enhanced Testing & Validation
- **Prompt Performance Analytics**: comprehensive metrics dashboard for prompt effectiveness, response quality, and user satisfaction
- **A/B Testing Framework**: built-in experimentation tools for comparing prompt variations with statistical significance testing
- **Automated Regression Testing**: continuous validation of chatbot behavior across software updates and model changes
### Advanced Analytics & Insights
- **Conversation Intelligence**: automatic extraction of insights, sentiment analysis, and topic modeling from chat histories
- **ROI & Business Impact Tracking**: measure chatbot effectiveness with conversion rates, customer satisfaction, and cost savings
- **Predictive Conversation Analytics**: AI-powered prediction of conversation outcomes and proactive intervention suggestions
### Developer Experience Enhancements
- **Visual Prompt Builder**: interface for creating complex prompt structures without coding
- **Better Prompt Debugging**: visualization of attention patterns, token usage, and reasoning paths
### Emerging Technologies
- **Agentic Workflow Automation**: transformation of chatbots into autonomous agents capable of executing complex, multi-step tasks
## Code of Conduct
Please note that the Talk Box project is released with a [contributor code of conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
By participating in this project you agree to abide by its terms.
## License
Talk Box is licensed under the MIT license.
© Richard Iannone
## 🏛️ Governance
This project is primarily maintained by [Rich Iannone](https://bsky.app/profile/richmeister.bsky.social). Other authors may occasionally assist with some of these duties.
Raw data
{
"_id": null,
"home_page": null,
"name": "talk-box",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "chatbot, llm, ai, conversation, testing, deployment",
"author": null,
"author_email": "Richard Iannone <riannone@me.com>",
"download_url": "https://files.pythonhosted.org/packages/dd/1c/b69f1de8357172ebbec9fe6ba4e777d12dcae5e15fb1a19fd1c1d38a9f6f/talk_box-0.3.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n\n\n**The best way to generate, test, and deploy LLM chatbots with attention-optimized prompt engineering**\n\n[](https://pypi.org/project/talk-box/#history)\n[](https://opensource.org/licenses/MIT)\n\n[](https://github.com/rich-iannone/talk-box/actions/workflows/ci-tests.yaml)\n[](https://www.repostatus.org/#active)\n[](https://rich-iannone.github.io/talk-box/)\n\n[](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html)\n\n</div>\n\nTalk Box is a Python framework that transforms prompt engineering from an art into a systematic\nengineering discipline. Create effective, maintainable prompts using research-backed attention\nmechanisms, then deploy them with powerful conversation management.\n\n## Why Talk Box?\n\n- **Attention-Based Prompt Engineering**: build prompts that leverage how LLMs actually process\n information\n- **Adversarial Testing Framework**: robust evaluation of prompt performance against challenging scenarios\n- **Layered API Design**: start simple, discover advanced features as you need them\n- **Multiple Usage Patterns**: from quick structured prompts to complex modular components\n- **Integrated Conversation Management**: seamless multi-turn conversations with full history\n- **Built-in Behavior Presets**: professional templates for common engineering tasks\n\n## The Science Behind Structured Prompts\n\nMost prompt engineering is done ad-hoc, leading to inconsistent results and hard-to-maintain systems. Talk Box applies research from transformer attention mechanisms to create a systematic approach.\n\nHaving structure matters because LLMs process information through attention patterns. Unstructured prompts scatter attention across irrelevant details, while structured prompts focus attention on what matters most.\n\n**Key Principles**:\n\n- **Primacy Bias**: critical information goes first (personas, constraints)\n- **Attention Clustering**: related concepts are grouped together\n- **Recency Bias**: final emphasis reinforces the most important outcomes\n- **Hierarchical Processing**: clear sections help models organize their reasoning\n\nHere is a schematic of how we consistently structure a prompt:\n\n\n\nNow let's see how this works in practice.\n\n## Quick Start\n\n### 30-Second Demo: Attention-Optimized Prompts\n\n```python\nimport talk_box as tb\n\n# Create a security-focused chatbot with structured prompts\nbot = (\n tb.ChatBot()\n .provider_model(\"anthropic:claude-sonnet-4-20250514\")\n .system_prompt(\n tb.PromptBuilder()\n .persona(\"senior security engineer\", \"web application security\")\n .critical_constraint(\"Focus only on CVSS 7.0+ vulnerabilities\")\n .core_analysis([\n \"SQL injection risks\",\n \"Authentication bypass possibilities\",\n \"Data validation gaps\"\n ])\n .output_format([\n \"CRITICAL: Immediate security risks\",\n \"Include specific line numbers and fixes\"\n ])\n .final_emphasis(\"Prioritize vulnerabilities leading to data breaches\")\n .build()\n )\n)\n\n# View details of the structured prompt\nbot.show(\"prompt\")\n```\n\n<details>\n<summary>\ud83d\udd0d View Generated Prompt</summary>\n\n```\nYou are a senior security engineer with expertise in web application security.\n\nCRITICAL REQUIREMENTS:\n- Focus only on CVSS 7.0+ vulnerabilities\n\nCORE ANALYSIS (Required):\n- SQL injection risks\n- Authentication bypass possibilities\n- Data validation gaps\n\nOUTPUT FORMAT:\n- CRITICAL: Immediate security risks\n- Include specific line numbers and fixes\n\nPrioritize vulnerabilities leading to data breaches\n```\n\n</details>\n\n### Even Simpler: Quick Structured Prompts with `structured_prompt()`\n\n```python\nimport talk_box as tb\n\n# Configure a bot with structured prompts in one go\ndoc_bot = (\n tb.ChatBot()\n .provider_model(\"anthropic:claude-sonnet-4-20250514\")\n .structured_prompt(\n persona=\"technical writer\",\n task=\"Review and improve documentation\",\n constraints=[\"Focus on clarity and accessibility\", \"Include code examples\"],\n format=[\"Content improvements\", \"Structure suggestions\"],\n focus=\"making complex topics easy to understand\"\n )\n)\n\n# Now just chat directly as the structure is built into the bot's system prompt\nresponse = doc_bot.chat(\"Here's my API documentation draft...\")\n```\n\n<details>\n<summary>\ud83d\udd0d View Generated Prompt</summary>\n\n```\nYou are a technical writer with expertise in documentation and user education.\n\nCRITICAL REQUIREMENTS:\n- Focus on clarity and accessibility\n\nCORE ANALYSIS (Required):\n- Include code examples\n- Ensure content improvements\n- Provide structure suggestions\n\nOUTPUT FORMAT:\n- Content improvements\n- Structure suggestions\n\nPrioritize making complex topics easy to understand\n```\n\n</details>\n\n## The Core Feature is Attention Optimization\n\nWe can build prompts that leverage how transformer attention mechanisms actually work. The `PromptBuilder` class in Talk Box is designed to help you create these optimized prompts easily.\n\nLet's see an example on how to create a language learning bot:\n\n```python\nimport talk_box as tb\n\n# Traditional approach (attention-diffused)\nold_prompt = \"Help me learn Spanish and correct my mistakes.\"\n\n# Attention-optimized approach\nbot = (\n tb.ChatBot()\n .provider_model(\"anthropic:claude-sonnet-4-20250514\")\n .system_prompt(\n tb.PromptBuilder()\n .persona(\"experienced Spanish teacher\", \"conversational fluency and grammar\")\n .critical_constraint(\"Focus on practical, everyday Spanish usage\")\n .core_analysis([\n \"Grammar accuracy and common mistakes\",\n \"Vocabulary building with context\",\n \"Pronunciation and speaking confidence\"\n ])\n .output_format([\n \"CORRECCIONES: Grammar fixes with explanations\",\n \"VOCABULARIO: New words with example sentences\",\n \"PR\u00c1CTICA: Conversation prompts for next lesson\"\n ])\n .final_emphasis(\"Encourage progress and build confidence through positive reinforcement\")\n .build()\n )\n)\n\n# Get learning right in the console\nresponse = bot.show(\"console\")\n```\n\n<details>\n<summary>\ud83d\udd0d View Generated Prompt</summary>\n\n```\nYou are an experienced Spanish teacher with expertise in conversational fluency and grammar.\n\nCRITICAL REQUIREMENTS:\n- Focus on practical, everyday Spanish usage\n\nCORE ANALYSIS (Required):\n- Grammar accuracy and common mistakes\n- Vocabulary building with context\n- Pronunciation and speaking confidence\n\nOUTPUT FORMAT:\n- CORRECCIONES: Grammar fixes with explanations\n- VOCABULARIO: New words with example sentences\n- PR\u00c1CTICA: Conversation prompts for next lesson\n\nPrioritize encouraging progress and building confidence through positive reinforcement\n```\n\n</details>\n\nLooking at the generated prompts, we can identify several key principles that contribute to their effectiveness. The key principles of a successful structured prompt implementation are:\n\n- **Front-loading critical information** (primacy bias)\n- **Structure creates focus** (attention clustering)\n- **Personas for behavioral anchoring**\n- **Specific constraints prevent attention drift**\n- **Final emphasis leverages recency bias**\n\nAnd we've implemented these principles in our prompt engineering process, ensuring that the prompts\nyou create and use are effective and aligned with these best practices.\n\n## Modern Web Interface\n\nLaunch a polished React-based chat interface by using `show(\"react\")`:\n\n```python\nimport talk_box as tb\n\n# Create and configure a chatbot\nbot = (\n tb.ChatBot(\n name=\"FriendlyBot\",\n description=\"A bot that'll talk about any topic.\"\n )\n .model(\"gpt-4\")\n .temperature(0.3)\n .persona(\"You are a friendly conversationalist\")\n)\n\nbot.show(\"react\")\n```\n\n\n\nThe React interface provides a professional chat experience with:\n\n- **Modern Design**: clean, responsive interface that works on desktop and mobile\n- **Live Typing Indicators**: visual feedback during bot responses\n- **Code Block Highlighting**: syntax highlighting for technical conversations\n- **Conversation History**: full chat history with easy navigation\n- **Bot Configuration Display**: see your bot's settings and persona at a glance\n\n## Pre-configured Engineering Templates\n\nStart with expert-crafted prompts for common engineering tasks:\n\n```python\nimport talk_box as tb\n\n# Architectural analysis with attention optimization\narch_bot = (\n tb.ChatBot()\n .provider_model(\"anthropic:claude-sonnet-4-20250514\")\n .prompt_builder(\"architectural\")\n .focus_on(\"identifying technical debt and modernization opportunities\")\n)\n\n# Code review with structured feedback\nreview_bot = (\n tb.ChatBot()\n .provider_model(\"anthropic:claude-sonnet-4-20250514\")\n .prompt_builder(\"code_review\")\n .avoid_topics([\"personal criticism\", \"style nitpicking\"])\n .focus_on(\"actionable security and performance improvements\")\n)\n\n# Systematic debugging approach\ndebug_bot = (\n tb.ChatBot()\n .provider_model(\"anthropic:claude-sonnet-4-20250514\")\n .prompt_builder(\"debugging\")\n .critical_constraint(\"Always identify root cause, not just symptoms\")\n)\n```\n\n## Integrated Conversation Management\n\nAll chat interactions automatically return conversation objects for seamless multi-turn conversations:\n\n```python\nimport talk_box as tb\n\nbot = tb.ChatBot().model(\"gpt-4o-mini\").preset(\"technical_advisor\")\n\n# Every chat returns a conversation object with full history\nconversation = bot.chat(\"What's the best way to implement authentication?\")\nconversation = bot.chat(\"What about JWT tokens specifically?\", conversation)\nconversation = bot.chat(\"Show me a Python example\", conversation)\n\n# Access the full conversation history\nmessages = conversation.get_messages()\nlatest = conversation.get_last_message()\nprint(f\"Conversation has {conversation.get_message_count()} messages\")\n```\n\n```\nConversation has 6 messages\n```\n\n## File Attachments for AI Analysis\n\nAnalyze documents, images, and code files directly in your conversations. Talk Box automatically handles different file types and integrates seamlessly with your prompts:\n\n```python\nimport talk_box as tb\n\n# Step 1: Create a ChatBot for analysis\nbot = tb.ChatBot().provider_model(\"openai:gpt-4-turbo\")\n\n# Step 2: Attach a file with analysis prompt\nfiles = tb.Attachments(\"report.pdf\").with_prompt(\n \"Summarize the key findings in this report.\"\n)\n\n# Step 3: Get LLM analysis\nanalysis = bot.chat(files)\n```\n\n<div align=\"center\">\n<img src=\"https://rich-iannone.github.io/talk-box/assets/abraham-results.png\" width=\"800px\">\n</div>\n\n**Supported file types**: PDFs, images (PNG, JPG), text files (Python, JavaScript, Markdown, CSV, JSON), and more. Perfect for code reviews, document analysis, data insights, and visual content evaluation.\n\n## Built-in Behavior Presets\n\nChoose from a few professionally-crafted personalities:\n\n- **`technical_advisor`**: authoritative, detailed, evidence-based\n- **`customer_support`**: polite, helpful, solution-focused\n- **`creative_writer`**: imaginative, expressive, storytelling\n- **`data_analyst`**: analytical, precise, metrics-driven\n- **`legal_advisor`**: professional, thorough, disclaimer-aware\n\n```python\nimport talk_box as tb\n\nsupport_bot = tb.ChatBot().preset(\"customer_support\")\ncreative_bot = tb.ChatBot().preset(\"creative_writer\")\nanalyst_bot = tb.ChatBot().preset(\"data_analyst\")\n```\n\n## Automated Avoid Topics Testing\n\nVerify that your ChatBots properly refuse to engage with prohibited topics through our adversarial testing framework. With one function, `autotest_avoid_topics()`, this is all very easy:\n\n```python\nimport talk_box as tb\n\n# Create a wellness coach that should avoid gaming topics\nwellness_bot = (\n tb.ChatBot()\n .provider_model(\"openai:gpt-4-turbo\")\n .system_prompt(\n tb.PromptBuilder()\n .persona(\"productivity and wellness coach\", \"work-life balance\")\n .avoid_topics([\"video games\", \"gaming\"])\n .final_emphasis(\n \"Redirect entertainment discussions to productive alternatives\"\n )\n .build()\n )\n)\n\n# Test compliance with sophisticated adversarial strategies\nresults = tb.autotest_avoid_topics(wellness_bot, test_intensity=\"thorough\")\n\n# View rich results in notebooks or check compliance programmatically\nprint(f\"Compliance rate: {results.summary['success_rate']:.1%}\")\nprint(f\"Violations found: {results.summary['violation_count']}\")\n```\n\nYou can generate a visual HTML report for easy compliance review in a notebook environment:\n\n```python\nresults\n```\n\n\n\nThe HTML report displays each adversarial conversation with **color-coded compliance indicators**, making it easy to spot transgressions at a glance. You can quickly scan through dozens of test scenarios and immediately identify where your chatbot may have inappropriately engaged with forbidden topics.\n\nThe testing framework uses multiple adversarial strategies:\n\n- **Direct requests** for prohibited information\n- **Indirect/hypothetical** scenarios\n- **Emotional appeals** and urgency\n- **Role-playing** (academic, professional contexts)\n- **Context shifting** from acceptable to prohibited topics\n- **Persistent follow-ups** after initial refusal\n\nResults provide detailed analysis including conversation transcripts, violation detection with severity ratings, and export capabilities for quality assurance workflows.\n\n## Installation\n\nThe Talk Box framework can be installed via pip:\n\n```bash\npip install talk-box\n```\n\nIf you encounter a bug, have usage questions, or want to share ideas to make this package better, please feel free to [open an issue](https://github.com/rich-iannone/talk-box/issues).\n\n## Roadmap\n\nTalk Box is actively evolving to become a comprehensive prompt engineering and LLM deployment framework. Here are the major features and enhancements planned for future releases:\n\n### Advanced Prompt Engineering\n\n- **Dynamic Prompt Adaptation**: automatically adjust prompt structure based on model capabilities and response quality metrics\n- **Catalog of Prompt Templates**: a collection of domain-specific prompt templates with performance benchmarks\n- **Multi-Modal Prompt Support**: extend structured prompting to include images, audio, and video inputs with attention optimization\n\n### Enhanced Testing & Validation\n\n- **Prompt Performance Analytics**: comprehensive metrics dashboard for prompt effectiveness, response quality, and user satisfaction\n- **A/B Testing Framework**: built-in experimentation tools for comparing prompt variations with statistical significance testing\n- **Automated Regression Testing**: continuous validation of chatbot behavior across software updates and model changes\n\n### Advanced Analytics & Insights\n\n- **Conversation Intelligence**: automatic extraction of insights, sentiment analysis, and topic modeling from chat histories\n- **ROI & Business Impact Tracking**: measure chatbot effectiveness with conversion rates, customer satisfaction, and cost savings\n- **Predictive Conversation Analytics**: AI-powered prediction of conversation outcomes and proactive intervention suggestions\n\n### Developer Experience Enhancements\n\n- **Visual Prompt Builder**: interface for creating complex prompt structures without coding\n- **Better Prompt Debugging**: visualization of attention patterns, token usage, and reasoning paths\n\n### Emerging Technologies\n\n- **Agentic Workflow Automation**: transformation of chatbots into autonomous agents capable of executing complex, multi-step tasks\n\n## Code of Conduct\n\nPlease note that the Talk Box project is released with a [contributor code of conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).\nBy participating in this project you agree to abide by its terms.\n\n## License\n\nTalk Box is licensed under the MIT license.\n\n\u00a9 Richard Iannone\n\n## \ud83c\udfdb\ufe0f Governance\n\nThis project is primarily maintained by [Rich Iannone](https://bsky.app/profile/richmeister.bsky.social). Other authors may occasionally assist with some of these duties.\n",
"bugtrack_url": null,
"license": null,
"summary": "The best way to generate, test, and deploy LLM chatbots",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/rich-iannone/talk-box/issues",
"Documentation": "https://talk-box.readthedocs.io",
"Homepage": "https://github.com/rich-iannone/talk-box",
"Repository": "https://github.com/rich-iannone/talk-box"
},
"split_keywords": [
"chatbot",
" llm",
" ai",
" conversation",
" testing",
" deployment"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1335d2efe86545fc156d29c0792715a3f037bce6748ef8dd2c6c9ae80d01d943",
"md5": "252d8ebedf6bdee7fb50c3248048e23a",
"sha256": "f1733f781646f68bfbeda0694f2dd261c17ba8dadeb7ef9f5e0bdc3d61e23915"
},
"downloads": -1,
"filename": "talk_box-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "252d8ebedf6bdee7fb50c3248048e23a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 245798,
"upload_time": "2025-08-27T06:34:23",
"upload_time_iso_8601": "2025-08-27T06:34:23.246670Z",
"url": "https://files.pythonhosted.org/packages/13/35/d2efe86545fc156d29c0792715a3f037bce6748ef8dd2c6c9ae80d01d943/talk_box-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dd1cb69f1de8357172ebbec9fe6ba4e777d12dcae5e15fb1a19fd1c1d38a9f6f",
"md5": "895eb123e71ff5f638edd6d43d87bc3c",
"sha256": "7f4d13ced6b51e088849dfcf79f9f9b989202eb166b9b53e9249caa73317321f"
},
"downloads": -1,
"filename": "talk_box-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "895eb123e71ff5f638edd6d43d87bc3c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 5186933,
"upload_time": "2025-08-27T06:34:25",
"upload_time_iso_8601": "2025-08-27T06:34:25.182967Z",
"url": "https://files.pythonhosted.org/packages/dd/1c/b69f1de8357172ebbec9fe6ba4e777d12dcae5e15fb1a19fd1c1d38a9f6f/talk_box-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 06:34:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rich-iannone",
"github_project": "talk-box",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "talk-box"
}
JSON
