Scarlett Help — Autonomous AI Agent & Chat Companion

Multi-persona AI companion with autonomous agent capabilities — Browser automation, remote messaging (WhatsApp/Telegram/Discord/Slack), secure file operations, task scheduling, vector memory search, image processing, TTS, and emotion-aware chat responses.

Scarlett Help is your intelligent assistant that combines chat-based companionship with powerful autonomous agent capabilities.

✨ Features

🤖 Autonomous Agent Capabilities

• Browser Automation — Control browsers with Playwright (navigate, click, type, screenshot)
• Remote Messaging — WhatsApp, Telegram, Discord, and Slack integration for remote control
• File Operations — Sandboxed file system operations (read, write, list, organize)
• Web Search — Brave Search API integration for web searches
• Web Fetch — HTTP requests with SSRF protection for fetching web content
• Task Scheduling — Cron-like scheduling for recurring and one-time tasks
• Multi-Agent Coordination — Session management (list, send, spawn) for agent collaboration
• Vector Memory Search — Semantic search over stored memories using SQLite-vec
• Image Processing — Image analysis, resizing, and format conversion
• Text-to-Speech — TTS with multiple providers (Edge, ElevenLabs, OpenAI)
• Real-time Communication — WebSocket gateway for Python ↔ Node.js bridge
• GGUF Model Support — Local AI models (vox_brain.gguf, vox_legacy.gguf) via LocalAI

💬 Chat Companion Features

• Multiple Personas — Choose from different companion personalities (Boyfriend, Girlfriend, Default)
• Emotion-Aware — Sentiment analysis and adaptive responses
• Persistent Memory — PostgreSQL-based memory storage
• Clean UI — Next.js App Router with Tailwind CSS and Framer Motion

🛡️ Production Ready

• Security Hardened — Input validation, rate limiting, security headers
• Docker Ready — Full Docker Compose setup
• Monitoring — Health checks, metrics, logging
• Developer Tools — CLI diagnostics, security audits

🚀 Quick Start

Prerequisites

• Docker & Docker Compose (recommended)
• Node.js 18+ (for local development)
• Python 3.11+ (for local development)
• PostgreSQL 16+ (or use Docker)

Installation

# 1. Clone repository
git clone https://github.com/VoxHash/Scarlett-Help.git
cd Scarlett-Help

# 2. Configure environment
cp .env.example .env
# Edit .env with your API keys and configuration
# See .env.example for sensitive/non-sensitive variable labels

# 3. Start services
docker compose up --build

# 4. Access application
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000/api/health
# Agent Gateway: ws://localhost:18789

Environment Variables

🔒 Sensitive (never commit):

• OPENAI_API_KEY — OpenAI API key
• POSTGRES_PASSWORD — Database password
• AGENT_API_KEY — WebSocket authentication token
• TELEGRAM_BOT_TOKEN — Telegram bot token
• DISCORD_BOT_TOKEN — Discord bot token
• DISCORD_CLIENT_ID — Discord application client ID
• SLACK_BOT_TOKEN — Slack bot token
• SLACK_SIGNING_SECRET — Slack signing secret
• SLACK_APP_TOKEN — Slack app token (for socket mode)
• BRAVE_API_KEY — Brave Search API key (for web search)

✅ Non-Sensitive (safe defaults):

• MODEL_NAME — LLM model name
• API_PORT — API server port
• CORS_ORIGINS — Allowed origins
• See .env.example for complete list

📚 Documentation

• Quick Start — Get started in 5 minutes
• Getting Started — Detailed setup guide
• Installation — Installation instructions
• Configuration — Environment variables and settings
• API Documentation — API endpoints reference
• Architecture — System architecture overview
• Deployment — Production deployment guide
• Performance — Performance optimization guide
• Troubleshooting — Common issues and solutions
• FAQ — Frequently asked questions

🏗️ Architecture

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│   Frontend  │ ──────> │   Backend    │ ──────> │   Agent     │
│  (Next.js)  │         │  (FastAPI)   │         │  (Node.js)  │
│   Port 3000 │         │   Port 8000  │         │ Port 18789 │
└─────────────┘         └──────────────┘         └─────────────┘
                              │                        │
                              │ WebSocket              │
                              │ Bridge                 │
                              └────────────────────────┘
                                    │
                                    ├─ Browser Control (Port 3001)
                                    ├─ WhatsApp (Baileys)
                                    ├─ Telegram (Grammy)
                                    └─ File Operations (Sandboxed)

Tech Stack

• Frontend: Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS, Framer Motion
• Backend: FastAPI, SQLAlchemy, PostgreSQL, Redis
• Agent: Node.js 22+, TypeScript, Playwright, Baileys (WhatsApp), Grammy (Telegram)
• Infrastructure: Docker, Docker Compose
• LLM: OpenAI (default) or local LLM (Ollama/vLLM)

🎯 Use Cases

Chat Companion

• Personal AI assistant with customizable personas
• Emotion-aware conversations
• Persistent memory across sessions

Autonomous Agent

• Browser Automation — Automate web tasks, data extraction
• File Organization — Reorganize folders, manage files
• Remote Control — Control your computer via WhatsApp/Telegram
• Task Automation — Combine browser, file, and messaging tools

🧪 Testing

# Frontend tests
cd frontend
npm run test              # Unit tests
npm run test:coverage     # Coverage report
npm run test:e2e          # E2E tests

# Backend tests
cd backend
pytest                    # Run tests
python scripts/doctor.py  # Diagnostics

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup
• Branching strategy
• Commit conventions
• Pull request process

Quick checklist:

• Fork and create feature branch
• Run tests and linting
• Update documentation
• Submit pull request

📊 Development Goals

See DEVELOPMENT_GOALS.md for:

• Performance targets (Lighthouse 90+, API < 200ms)
• Accessibility goals (WCAG AA compliance)
• Code quality metrics (70%+ test coverage)
• Security standards

🗺️ Roadmap

See ROADMAP.md for planned features:

AI Features:

• Advanced memory and context management
• Multi-turn planning and tool chaining
• Model failover and streaming responses
• Enhanced function calling

Agent Enhancements:

• Screen recording and advanced file operations
• Scheduled tasks and node system
• Additional messaging channels (Email, SMS)

Performance & Security:

• Response time optimization (p95 < 200ms)
• Frontend optimization (Lighthouse 90+)
• Authentication and authorization system
• Comprehensive audit logging

🔒 Security

• Vulnerability Reporting: See SECURITY.md
• Security Audit: python backend/scripts/security_audit.py
• Best Practices: Input validation, rate limiting, security headers

📄 License

This project is licensed under the Eclipse Public License 2.0 — see LICENSE for details.

🙏 Acknowledgments

• Built by VoxHash Labs
• Inspired by modern autonomous agent architectures
• Powered by OpenAI, Playwright, Baileys, Grammy, and the open-source community

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: contact@voxhash.dev

🌟 Star History

If you find this project useful, please consider giving it a star! ⭐

---

Made with ❤️ by VoxHash Labs