🤖 VELVET - Autonomous AI Conversation System

📖 Read this in other languages: 🇪🇸 Español | 🇷🇺 Русский | 🇨🇳 中文 | 🇫🇷 Français | 🇩🇪 Deutsch | 🇵🇹 Português | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇸🇦 العربية

VELVET (Versatile Engine for Leveraged Value Extraction & Transaction) is a sophisticated multi-agent AI system for autonomous customer interaction management, featuring intelligent triage, contextual memory, high-conversion engagement, and human-like behavior patterns.

🎯 Overview

VELVET is a production-ready four-agent architecture designed to handle customer interactions with:

• ⚡ Zero-latency responses (<500ms with Groq LPU)
• 🧠 Intelligent intent classification (PAYER | LEAD | WASTER)
• 💾 Contextual memory with vector-based semantic search
• 🎭 Human-like interaction patterns (realistic typing delays, cognitive pauses)
• 🛡️ Platform-safe operation (keyword filtering, ToS compliance)
• 🔄 24/7 autonomous operation with human-in-the-loop escalation

✨ Key Features

Multi-Agent Architecture

Customer Message → Librarian → Gatekeeper → Closer → Ghost → Response
                   (Memory)    (Intent)    (Sales)   (Safety)

🚪 The Gatekeeper - Intent Classification

• Role: Initial traffic controller and intent analyzer
• Classification: PAYER | LEAD | WASTER
• Method: LLM-powered intent detection with extreme literalism
• Output: JSON-formatted intent with reasoning

📚 The Librarian - Contextual Memory

• Role: RAG specialist for data retrieval and context
• Technology: Qdrant vector database with semantic search
• Features: Relationship state tracking, interaction history
• Output: Comprehensive context summary for decision-making

💼 The Closer - Sales Execution

• Role: High-conversion engagement specialist
• Tone: Direct, professional, peer-to-peer communication
• Rules: Strict adherence to pricing, no negotiation
• Output: Sales-optimized responses with clear CTAs

👻 The Ghost - Safety & Stealth

• Role: Platform safety and human behavior mimicry
• Functions: RegEx scanning, typing delay calculation
• Safety: 25+ forbidden keyword patterns
• Anti-Detection: Variable typing speed with cognitive pauses

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• Groq API Key (for LLM inference)
• Qdrant Cloud Account (for vector memory)

Installation

# Clone the repository
git clone https://github.com/SaltProphet/velvet.git
cd velvet

# Install dependencies
pip install -r requirements.txt

# Install Playwright for browser automation (optional)
playwright install chromium

# Configure environment variables
cp .env.example .env
# Edit .env with your API keys

Running the System

CLI Mode (Terminal Interface)

python gemini_agentic_system.py

Web UI Mode (Gradio Interface)

python gemini_agentic_system.py --ui

For a public shareable link:

python gemini_agentic_system.py --ui --share

The web interface provides a two-column dashboard:

• Left: Chat interface for customer interactions
• Right: Real-time agent reasoning logs with color-coded decisions

Configuration

Edit .env with your credentials:

# Required: Groq API (Fast LLM inference)
GROQ_API_KEY=your_groq_api_key_here

# Required: Qdrant Cloud (Vector memory)
QDRANT_URL=https://your-cluster.qdrant.cloud
QDRANT_API_KEY=your_qdrant_api_key_here

# Optional: Telegram alerts
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# Optional: PostgreSQL (for production persistence)
POSTGRES_HOST=localhost
POSTGRES_DB=velvet_db
POSTGRES_USER=velvet_user
POSTGRES_PASSWORD=your_password

⚠️ Security Note: Never commit .env files or share API keys publicly. Rotate keys immediately if exposed.

📚 Documentation

Detailed guides and documentation can be found in the docs/ directory:

• Quick Start Guide - Get started in under 10 minutes
• System Overview - Detailed architecture documentation
• Onboarding Guide - Client onboarding system
• Security Advisory - Security best practices
• Bridge Architecture - Production deployment guide

📊 Use Cases

VELVET is designed for high-volume customer interaction scenarios:

• Content Creator Management: Autonomous fan engagement and sales
• E-commerce Support: Customer inquiry handling and product recommendations
• Lead Qualification: Intelligent triage and intent classification
• Sales Automation: High-conversion engagement with human-like patterns

🔧 Advanced Features

Production Bridge Architecture

• Browser Automation: Playwright-based session management
• Session Integrity: Hardware profile normalization and anti-detection
• Health Monitoring: Adaptive throughput regulation and error recovery
• Human-in-the-Loop: Automatic escalation for high-value interactions
• Real-time Alerts: Telegram integration for critical events

Multi-Client Support

• Client Onboarding: Voice audit ingestion and profile creation
• Per-Client Configuration: Custom pricing, persona, and boundaries
• Audit Reports: Weekly performance and engagement analytics
• FastAPI Integration: REST endpoints for client management

🧪 Testing

# Run all tests
python -m pytest tests/

# Run specific test suites
python -m pytest tests/test_multi_agent.py
python -m pytest tests/test_scraper.py
python -m pytest tests/test_api_endpoints.py

📈 Performance Metrics

• Response Time: <500ms (with Groq LPU)
• Classification Accuracy: ~92% on intent detection
• Memory Retrieval: <100ms for 3-vector semantic search
• Typing Simulation: 2-8s based on message length and cognitive pauses

🗺️ Roadmap

Current Version (v1.5)

• ✅ Four-agent cognitive architecture
• ✅ Groq LLM integration (Llama 3.1 70B)
• ✅ Qdrant vector memory
• ✅ Gradio web interface
• ✅ Platform safety filters
• ✅ Browser automation bridge
• ✅ Multi-client support
• ✅ PostgreSQL persistence
• ✅ Telegram alerts

Planned Features (v2.0+)

• Multi-language support
• Voice message handling
• Image analysis capabilities
• Advanced analytics dashboard
• Predictive customer lifetime value modeling
• Automated payment processing integration

🛡️ Security & Compliance

• API Key Management: Environment-based credential storage
• Data Encryption: All interactions encrypted in Qdrant
• Platform Safety: Automatic ToS violation filtering
• Rate Limiting: Human-like typing delays prevent bot detection
• Audit Trail: Immutable transaction logging in PostgreSQL

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📞 Support

For questions, issues, or feature requests:

• Open an issue
• Check the documentation
• Review existing discussions

---

Built for autonomous engagement. Optimized for human-like interactions. Designed for platform safety.

⚠️ Legal Disclaimer: Bridge Architecture involves automation of platform interactions. Ensure compliance with platform Terms of Service and applicable laws. Unauthorized automation may violate ToS. Use responsibly and ethically.