React Chat Interface

Talk Box provides a modern, responsive React-based chat interface that offers the same simplicity as the traditional browser interface while providing a polished, professional user experience.

Quick Start

The React chat interface works exactly like the traditional bot.show("browser") method, but with a modern React frontend:

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")

That’s it! This single command will:

• start a FastAPI backend server
• start a React development server
• install dependencies automatically
• automatically load .env files (if present)
• open the chat interface in your browser
• connect to your configured LLM provider

Installation Requirements

What You Need to Install

Python Package (automatic):

pip install talk-box

Node.js (one-time manual install):

macOS

brew install node

Ubuntu/Debian

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows

Download and install from nodejs.org

Any Platform (nvm)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

What Happens Automatically

Once you have Node.js installed, everything else is handled automatically:

1. React Dependencies: automatically installed via npm install on first run
2. Server Management: both FastAPI and React servers start automatically
3. Configuration: bot settings are automatically passed to the frontend
4. Browser Opening: interface opens automatically at http://localhost:5173

First Run Experience

With Node.js Already Installed

🚀 Starting React Chat Interface...
✅ Node.js found: v18.17.0
📦 Installing React dependencies...
✅ React dependencies installed
🔧 Starting backend server...
✅ FastAPI server started
⚛️ Starting React interface...
✅ React server started
🔧 Configuring bot settings...
🌐 Opening React chat interface...
✅ React chat interface launched!
   📱 Interface: http://localhost:5173
   🔧 API: http://127.0.0.1:8000

Without Node.js

🚀 Starting React Chat Interface...
❌ Node.js is required for the React chat interface
📋 Installation instructions:
   • macOS: brew install node
   • Ubuntu/Debian: curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs
   • Windows: Download from https://nodejs.org/
   • Or use Node Version Manager (nvm): https://github.com/nvm-sh/nvm

💡 After installing Node.js, run your script again!

Complete Examples

Basic Chatbot

import talk_box as tb

# Simple chatbot with minimal configuration
bot = tb.ChatBot().model("gpt-4")
bot.show("react")

Technical Assistant

import talk_box as tb

# Technical programming assistant
bot = (
    tb.ChatBot(
        name="CodeHelper",
        description="A programming assistant specializing in Python"
    )
    .model("gpt-4")
    .preset("technical_advisor")
    .temperature(0.2)
    .persona("You are an expert Python developer who explains concepts clearly")
)

bot.show("react")

Creative Writing Partner

import talk_box as tb

# Creative writing assistant with structured prompt
writing_prompt = (
    tb.PromptBuilder()
    .persona("You are a creative writing partner who helps with storytelling, character development, and plot ideas")
    .avoid_topics(["politics", "religion"])
)

bot = (
    tb.ChatBot(
        name="WriteBot",
        description="A creative writing companion"
    )
    .model("gpt-4")
    .temperature(0.8)
    .system_prompt(writing_prompt)
)

bot.show("react")

Advanced System Prompts

The React interface fully supports complex system prompts built with PromptBuilder:

import talk_box as tb

# Advanced system prompt with PromptBuilder
bot = (
    tb.ChatBot()
    .provider_model("gpt-4")
    .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")
    )
)

bot.show("react")

With Environment Variables

You can configure API keys using environment variables or .env files:

import os
import talk_box as tb

# Method 1: Set environment variables directly
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

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

bot.show("react")

Using .env Files (Recommended)

For better security and convenience, use a .env file. Important: You must explicitly load the .env file in your script:

# First, create a .env file in your project directory:
# OPENAI_API_KEY=your-actual-api-key-here
# ANTHROPIC_API_KEY=your-anthropic-key-here

from dotenv import load_dotenv
import talk_box as tb

# Load environment variables from .env file BEFORE creating the bot
load_dotenv()

bot = (
    tb.ChatBot()
    .provider_model("openai:gpt-4")
    .system_prompt("You are a helpful assistant.")
)

bot.show("react")

Tip

System Prompt Support: The React interface now properly supports custom system prompts set via .system_prompt(). Previously, system prompts were not being passed from the ChatBot configuration to the React interface, but this has been fixed.

Tip

Security Note: Always add .env to your .gitignore file to prevent accidentally committing API keys to version control!

Features

Modern UI/UX

• Responsive Design: works seamlessly on desktop, tablet, and mobile
• Clean Interface: modern chat bubbles with professional styling
• Typing Indicators: animated typing indicator with subtle pulsing animation
• Code Highlighting: syntax-highlighted code blocks with proper formatting
• Dark Mode Ready: built-in support for light and dark themes
• Bot Information: interactive info popover showing bot configuration
• System Prompt Viewer: nested popover to view the full system prompt text

Chat Features

• Message History: full conversation history maintained automatically
• Real-time Updates: instant message delivery and responses
• Error Handling: graceful error messages with retry functionality
• Copy Support: easy copying of messages and code blocks
• Markdown Support: full markdown rendering including lists, links, and formatting

Technical Features

• TypeScript: full type safety and excellent developer experience
• Hot Reload: instant updates during development
• Component Architecture: modular, reusable React components
• State Management: proper state handling with those React hooks
• API Integration: RESTful API with FastAPI backend

Configuration Options

All standard Talk Box configuration methods work with the React interface:

Temperature and Creativity

bot.temperature(0.1)         # Very focused and deterministic
bot.temperature(0.7)         # Balanced creativity
bot.temperature(1.2)         # Highly creative and varied

Presets

bot.preset("helpful")           # General helpful assistant
bot.preset("technical_advisor") # Technical problem solving
bot.preset("creative_writer")   # Creative writing assistance
bot.preset("data_analyst")      # Data analysis and insights

Manual Server Management

If you need more control, you can start servers manually:

Start Backend Server:

cd talk_box/web_components/python_server
python chat_server.py

Start React Server:

cd talk_box/web_components/react-chat
npm run dev

Then use the interface:

# Bot will detect running servers automatically
bot.show("react")

Troubleshooting

Common Issues and Solutions

“vite: command not found” Error

If you see an error like:

❌ React server process exited unexpectedly:
STDERR: sh: vite: command not found

This indicates corrupted or incomplete npm dependencies. Solution:

# Navigate to the React project directory
cd talk_box/web_components/react-chat

# Clean reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Verify vite is installed
npx vite --version

React Server Won’t Start

If the React development server fails to start:

1. Check Node.js version (requires Node.js 16+):

   node --version

2. Manually install dependencies:

   cd talk_box/web_components/react-chat
   npm install

3. Test vite directly:

   cd talk_box/web_components/react-chat
   npx vite --version
   npm run dev

Port Already in Use

If you see “port already in use” errors:

• React (port 5173): Stop any running vite processes
• FastAPI (port 8000): Stop any running Python servers

# Kill processes using the ports
lsof -ti:5173 | xargs kill -9
lsof -ti:8000 | xargs kill -9

Browser Opens But Shows Blank Page

1. Check console errors in browser developer tools
2. Verify both servers are running:
   • Frontend: http://localhost:5173
   • Backend: http://127.0.0.1:8000/health
3. Clear browser cache and reload

Dependencies Keep Breaking

If you frequently encounter dependency issues:

1. Use Node Version Manager (nvm) for consistent Node.js versions

2. Consider using the traditional browser interface as a fallback:

   bot.show("browser")  # Uses simple HTML interface

Conclusion

The React chat interface brings Talk Box into the modern web development ecosystem while maintaining the simplicity and power you expect. With just Node.js as a prerequisite, you get a polished, professional chat interface that works well with all Talk Box features.

Whether you’re prototyping a new AI application, building a production chatbot, or creating interactive demos, bot.show("react") provides an excellent balance of simplicity and sophistication.