# StrokeGPT - AI Hardware Controller

## Overview

StrokeGPT is a Flask-based web application that provides an AI-powered interface for controlling adult hardware devices (specifically "The Handy" device). The application features real-time chat with an AI companion that can control device movements, multiple interactive modes (Auto, Milking, Edging), voice synthesis capabilities, and a highly customizable persona system. The AI learns user preferences over time and maintains conversation history to provide personalized experiences.

## User Preferences

Preferred communication style: Simple, everyday language.

## System Architecture

### Backend Architecture
- **Framework**: Flask web application with modular service-oriented architecture
- **Core Services**:
  - `LLMService`: Handles communication with local Ollama LLM server for AI responses
  - `AudioService`: Manages ElevenLabs API integration for text-to-speech
  - `AutoblowController`/`HandyController`: Device communication and control
  - `SettingsManager`: Persistent configuration and user preferences
  - `BackgroundModes`: Threaded execution of automated interaction modes

### Frontend Architecture
- **Interface**: Single-page application with HTML/CSS/JavaScript
- **Layout**: Grid-based responsive design with collapsible sidebar
- **Real-time Communication**: AJAX polling for chat updates and device status
- **State Management**: Client-side JavaScript manages UI state and mode transitions

### AI Integration Pattern
- **Local LLM**: Uses Ollama server running llama3:8b-instruct-q4_K_M model
- **Structured Responses**: AI returns JSON-formatted responses containing chat text, device commands, and mood states
- **Context Management**: Maintains chat history, user profile, and persona consistency
- **Safety Systems**: Built-in movement limiters and emergency stop functionality

### Device Control Architecture
- **Abstracted Hardware Interface**: Common interface supporting multiple device types (Handy, Autoblow)
- **Command Translation**: Converts AI-generated movement parameters to device-specific API calls
- **User Calibration**: Maps AI commands to user-defined safe ranges
- **Real-time Control**: Immediate response to AI commands and user overrides

### Data Persistence
- **Settings Storage**: JSON-based configuration files for user preferences and device settings
- **Memory System**: Persistent user profile with likes, dislikes, and key memories
- **Pattern Storage**: Liked movement patterns saved for future AI reference
- **Session State**: In-memory chat history and current interaction context

### Threading Model
- **Background Modes**: Separate threads for automated interaction modes with clean shutdown
- **Event-driven Communication**: Thread-safe event system for user interrupts and mode changes
- **Concurrent Operations**: Non-blocking AI requests and device commands

## External Dependencies

### Required Services
- **Ollama Server**: Local LLM inference server (http://127.0.0.1:11434/api/chat)
- **The Handy API**: Cloud-based device control (https://www.handyfeeling.com/api/handy/v2/)
- **ElevenLabs API**: Text-to-speech voice synthesis (optional)

### Python Dependencies
- **Flask**: Web framework for HTTP server and routing
- **requests**: HTTP client for external API communication
- **elevenlabs**: Official SDK for voice synthesis integration

### Hardware Requirements
- **Compatible Devices**: The Handy or Autoblow hardware controllers
- **Network Connection**: Required for device control and voice features
- **Local Compute**: Sufficient resources for running Ollama LLM locally