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