| # 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 |
