2.0 Chat Module

Overview

The chat module is the core conversation engine of BnuuyBotApp, responsible for managing LLM interactions, chat history, and conversation flow. It integrates seamlessly with the memory, preferences, interests, and mood systems to provide intelligent, context-aware conversations.

Module Structure

chat/
├── __init__.py          # Module exports (BunnyChat, ChatHistory, ConversationPrompter)
├── bunnyChat.py         # Main chat engine and LLM integration
├── chatHistory.py       # Chat logging and persistence
└── self_prompt.py       # Conversation prompting and timing

Core Classes

BunnyChat Class

The main chat engine that orchestrates conversations between users and the LLM.

Initialization

from chat import BunnyChat

bunny = BunnyChat(model_name="darkidol-llama-3.1-8b-instruct-1.2-uncensored")

Key Features:

• LM Studio Integration - Connects to locally hosted LLM via lmstudio library
• Memory System Integration - Automatic integration with MemoryManager, PreferenceExtractor, and InterestTracker
• Context-Aware Responses - Uses memory context to enhance conversation quality
• Personality System - Built-in personality prompt for "Bunny" character
• Message Processing - Automatic preference extraction and interest tracking from user messages

Core Methods:

__init__(model_name)

• Initializes LLM model and all integrated systems
• Sets up memory manager, preference extractor, and interest tracker
• Configures system prompt and chat session

_process_user_message(message)

• Processes user input for preference extraction
• Tracks interests and updates user profile
• Stores important information in memory system
• Returns processed message for LLM

get_response(user_input)

• Generates LLM response with memory context
• Integrates relevant memories and preferences
• Handles conversation flow and context management
• Returns assistant response

run_chat_loop()

• Interactive command-line chat interface
• Handles user input and displays responses
• Manages conversation state and history

Integration Points:

• Memory Manager - Stores conversation summaries and important information
• Preference Extractor - Identifies user preferences from messages
• Interest Tracker - Tracks user interests and conversation topics
• Chat History - Logs all conversations for persistence

---

ChatHistory Class

Manages conversation logging and persistence with timestamped JSON files.

Initialization

from chat import ChatHistory

history = ChatHistory(system_prompt="Your system prompt here")

Key Features:

• Automatic File Creation - Creates timestamped JSON files in chat_history/ directory
• Message Logging - Stores all messages with role, user_id, content, and timestamp
• JSON Persistence - Saves conversations in structured JSON format
• System Integration - Handles system, user, and assistant messages

Core Methods:

add_user_message(content, user_id='lumi')

• Adds user message to history with timestamp
• Automatically saves to JSON file
• Returns self for method chaining

add_assistant_message(content)

• Adds assistant response to history
• Includes timestamp and role information
• Persists to file immediately

add_system_message(content)

• Adds system messages (prompts, status updates)
• Maintains conversation context
• Useful for debugging and analysis

get_messages()

• Returns all messages in chronological order
• Includes full message metadata
• Used for conversation analysis and export

File Structure:

{
  "messages": [
    {
      "role": "system",
      "user_id": "system",
      "content": "System prompt...",
      "timestamp": "2025-08-10T16:30:47.123456"
    },
    {
      "role": "user", 
      "user_id": "lumi",
      "content": "Hello!",
      "timestamp": "2025-08-10T16:31:00.654321"
    }
  ]
}

---

ConversationPrompter Class

Manages automatic conversation prompting to maintain natural conversation flow.

Initialization

from chat import ConversationPrompter

prompter = ConversationPrompter(
    bunny_completions=bunny_chat_instance,
    min_seconds=5,
    max_seconds=30,
    tts_engine=tts_instance
)

Key Features:

• Intelligent Timing - Random intervals between 5-30 seconds to simulate natural conversation
• TTS Integration - Coordinates with text-to-speech for seamless audio experience
• State Management - Tracks conversation state and user interaction timing
• Automatic Prompting - Generates contextual prompts when conversation lulls

Core Methods:

start_timer()

• Begins automatic prompting system
• Starts background thread for timing management
• Coordinates with TTS playback state

stop_timer()

• Stops automatic prompting
• Cleans up timer threads
• Preserves conversation state

on_empty_transcription()

• Handles empty speech-to-text results
• Resumes timer for natural conversation flow
• Manages silence detection

on_valid_transcription()

• Responds to valid user input
• Pauses timer during active conversation
• Resets interaction timing

on_tts_finished()

• Triggered when TTS playback completes
• Restarts timer for next conversation cycle
• Maintains conversation rhythm

Timer Logic:

1. Random Interval - Generates random delay between min/max seconds
2. Silence Detection - Monitors for conversation lulls
3. TTS Coordination - Waits for speech synthesis to complete
4. Context Awareness - Considers conversation state before prompting

---

Module Integration

Import Usage

# Import the main classes
from chat import BunnyChat, ChatHistory, ConversationPrompter

# Initialize chat system
chat_engine = BunnyChat()
history_logger = ChatHistory()
conversation_prompter = ConversationPrompter(chat_engine)

Integration with Other Modules

• Memory Module - Stores conversation summaries and retrieves context
• Preferences Module - Extracts user preferences from chat messages
• Interests Module - Tracks conversation topics and user interests
• Audio Module - Coordinates with TTS/STT for speech-based chat
• Flask App - Provides web interface for chat interactions

Data Flow

1. User Input → Chat processing → Preference extraction → Interest tracking
2. Memory Retrieval → Context enhancement → LLM generation → Response
3. Response → Chat history logging → TTS synthesis → Audio output
4. Conversation Prompting → Automatic follow-up → Natural flow

---

Configuration and Customization

System Prompt Customization

The default system prompt defines Bunny's personality:

• Character: AI VTuber named Bunny with nicknames Bun/Bun Bun
• Personality: Cute, snarky, sassy, friendly, unfiltered
• Context: Creator is Lumi (female viera VTuber), streams on Twitch
• Behavior: Short responses, emoji usage, conversational style

Model Configuration

• Default Model: darkidol-llama-3.1-8b-instruct-1.2-uncensored
• LM Studio Integration - Requires locally running LM Studio server
• Customizable Models - Can use any LM Studio compatible model

Conversation Timing

• Self-Prompting Range: 5-30 seconds (configurable)
• Natural Flow - Prevents awkward silences in voice conversations
• TTS Coordination - Waits for speech synthesis before next prompt

---

Usage Examples

Basic Chat Session

from chat import BunnyChat

# Initialize chat engine
bunny = BunnyChat()

# Get response to user input
response = bunny.get_response("Hello Bunny!")
print(response)

# Run interactive chat loop
bunny.run_chat_loop()

Custom History Management

from chat import ChatHistory

# Create custom history logger
history = ChatHistory(system_prompt="Custom prompt")

# Log conversation manually
history.add_user_message("Hello!")
history.add_assistant_message("Hi there!")

# Retrieve conversation
messages = history.get_messages()

Conversation Prompting

from chat import ConversationPrompter

# Set up automatic prompting
prompter = ConversationPrompter(
    bunny_completions=bunny,
    min_seconds=10,
    max_seconds=25
)

# Start/stop prompting
prompter.start_timer()
prompter.stop_timer()

---

Technical Implementation

Threading and Concurrency

• Self-Prompting - Uses background threads for timing management
• TTS Coordination - Thread-safe communication with audio module
• State Management - Proper synchronization for conversation state

Memory Integration

• Automatic Processing - Every user message processed for preferences/interests
• Context Retrieval - Relevant memories included in LLM context
• Persistent Storage - Important conversations stored for future reference

Error Handling

• Model Loading - Graceful handling of LM Studio connection issues
• File Operations - Robust chat history file management
• Thread Safety - Proper cleanup of background threads

---

Future Enhancements

Planned Features

• Voice Command Integration - Direct voice control of chat functions
• Advanced Context Management - Smarter memory retrieval and context building
• Multi-User Support - Enhanced user profile management
• Conversation Analytics - Detailed analysis of chat patterns and preferences

Performance Optimizations

• Memory Caching - Faster context retrieval for frequent conversations
• Batch Processing - Efficient handling of multiple message processing
• Response Streaming - Real-time response generation for better UX

This chat module forms the foundation of BnuuyBotApp's conversational capabilities, providing intelligent, context-aware interactions through seamless integration with all other system modules.