Perseus -- Multi-Agent AI Orchestration Platform

20-agent task routing system with multi-LLM integration, infrastructure management, and Discord command and control

Overview

Perseus is an AI orchestration platform that routes natural language commands to specialized agents across a self-hosted Proxmox homelab. It integrates multiple LLM providers (Grok/xAI, OpenAI, and local Ollama) with runtime model switching, SSH-based infrastructure management, web search, social media posting, and real-time health monitoring -- all controllable via Discord.

The system acts as a centralized command layer for homelab operations: from GPU monitoring and database backups to content generation and competitive analysis.

Architecture

+------------------+       +------------------+
|   Discord Bot    |       |   FastAPI REST   |
| (DM + Channel)   |       |   (Port 3002)    |
+--------+---------+       +--------+---------+
         |                          |
         +------------+-------------+
                      |
              +-------v--------+
              |  Chat Router   |
              | (Intent Match) |
              +-------+--------+
                      |
     +----------------+----------------+
     |        |       |       |        |
+----v--+ +---v--+ +--v---+ +-v-----+ +v---------+
|System | |Infra | |Agent | |Search | |General   |
|Cmds   | |SSH   | |Route | |Brave  | |Assistant |
+-------+ +------+ +--+---+ +------+ +----------+
                       |
          +------------+------------+
          |     |      |     |      |
       social trend  content comply revenue
       post   hunt   curator scan   track

Features

20-Agent Task Registry

Each agent has a designated LLM backend (cloud or local) and trigger phrases:

• social_publisher -- Social media content generation with post queue
• trend_hunter -- Market trend analysis and niche discovery
• content_curator -- Content filtering, deduplication, and ranking
• content_rewriter -- SEO-optimized metadata generation
• compliance_scanner -- Policy and copyright risk assessment (GPT-4o-mini)
• revenue_tracker -- Ad platform analytics with Grok analysis
• infra_monitor -- Full-stack health monitoring across all nodes
• backup_manager -- Automated vzdump, pg_dump, and config archival
• command_executor -- SSH command execution with safety controls
• general_assistant -- Catchall brain with web search augmentation

Multi-LLM Integration

• Grok/xAI -- Primary analysis engine ($2/$10 per 1M tokens)
• GPT-4o-mini -- Compliance scanning ($0.15/$0.60 per 1M tokens)
• Ollama (local) -- Free inference for content agents, trend analysis
• Runtime switching via !model grok / !model gpt / !model ollama [name]
• Per-request cost tracking against a monthly budget ceiling

Infrastructure Management

• SSH execution across all homelab nodes with three safety tiers:
  • Blocklist: destructive commands rejected immediately
  • Auto-approve: read-only operations execute without confirmation
  • Manual approval: everything else requires explicit !exec
• Health monitoring: CPU, RAM, disk, GPU utilization, temperature, Ollama model status
• Backup system: Proxmox vzdump snapshots, PostgreSQL dumps, config archives with retention policies
• Infrastructure map with aliases (e.g., "gpu" resolves to the correct node)

AI Response Processing

The AI can emit structured directives that Perseus interprets and executes:

• EXECUTE:hostname:command -- runs SSH commands inline during conversation
• SEARCH:query -- triggers Brave web search and injects results

Discord Command and Control

• Natural language chat routed to the active brain
• DM-based admin control with owner-only authentication
• Rate limiting per user
• Long message chunking (auto-splits at 2000 chars)
• Conversation context carried across exchanges

Tech Stack

Component	Purpose
Python 3.11	Core runtime
FastAPI	REST API (port 3002)
Discord.py	Bot interface with DM admin
PostgreSQL	Agent activity logging, cost analytics
Grok/xAI API	Primary AI brain with web + X search
OpenAI API (GPT-4o-mini)	Compliance scanning
Ollama	Free local LLM inference on GPU
Brave Search API	Web search integration
X/Twitter API	OAuth 1.0a social posting
Node.js + Express	Video library microservice API
SSH + subprocess	Cross-node command execution

Setup

Prerequisites

• Python 3.10+
• PostgreSQL
• Ollama with at least one model pulled
• Discord bot token
• SSH key access to your infrastructure nodes

Installation

git clone https://github.com/YOUR_USERNAME/perseus-ai-platform.git
cd perseus-ai-platform

pip install fastapi uvicorn requests discord.py psycopg2-binary

# Set up PostgreSQL
createdb perseus
psql perseus -c "CREATE TABLE metadata (id SERIAL PRIMARY KEY, agent TEXT, timestamp TEXT, command TEXT, result TEXT, cost_usd REAL DEFAULT 0);"

# Configure environment
cp .env.example .env
# Edit .env with your API keys, IPs, and credentials

# For video API (optional)
cd video-api && npm install && cd ..

Running

# Start Perseus (Discord + FastAPI + all agents)
uvicorn main:app --host 0.0.0.0 --port 3002

# Start video API (optional, separate process)
node video-api.js

Configuration

See .env.example for all environment variables. Key settings:

Variable	Description
XAI_API_KEY	Grok/xAI API key (primary brain)
OPENAI_API_KEY	OpenAI API key (compliance scanner)
BRAVE_API_KEY	Brave Search API key
DISCORD_TOKEN	Discord bot token
OLLAMA_URL	Ollama server URL
PG_*	PostgreSQL connection details
NODE*_IP	Infrastructure node IP addresses
MONTHLY_BUDGET	API spend ceiling (default $10)