README.md · perseus-ai-platform

150 lines · markdown

# 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
 
```bash
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
 
```bash
# 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) |

1	# Perseus -- Multi-Agent AI Orchestration Platform
2
3	> 20-agent task routing system with multi-LLM integration, infrastructure management, and Discord command and control
4
5	## Overview
6
7	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.
8
9	The system acts as a centralized command layer for homelab operations: from GPU monitoring and database backups to content generation and competitive analysis.
10
11	## Architecture
12
13	```
14	+------------------+ +------------------+
15	\| Discord Bot \| \| FastAPI REST \|
16	\| (DM + Channel) \| \| (Port 3002) \|
17	+--------+---------+ +--------+---------+
18	\| \|
19	+------------+-------------+
20	\|
21	+-------v--------+
22	\| Chat Router \|
23	\| (Intent Match) \|
24	+-------+--------+
25	\|
26	+----------------+----------------+
27	\| \| \| \| \|
28	+----v--+ +---v--+ +--v---+ +-v-----+ +v---------+
29	\|System \| \|Infra \| \|Agent \| \|Search \| \|General \|
30	\|Cmds \| \|SSH \| \|Route \| \|Brave \| \|Assistant \|
31	+-------+ +------+ +--+---+ +------+ +----------+
32	\|
33	+------------+------------+
34	\| \| \| \| \|
35	social trend content comply revenue
36	post hunt curator scan track
37	```
38
39	## Features
40
41	### 20-Agent Task Registry
42	Each agent has a designated LLM backend (cloud or local) and trigger phrases:
43	- social_publisher -- Social media content generation with post queue
44	- trend_hunter -- Market trend analysis and niche discovery
45	- content_curator -- Content filtering, deduplication, and ranking
46	- content_rewriter -- SEO-optimized metadata generation
47	- compliance_scanner -- Policy and copyright risk assessment (GPT-4o-mini)
48	- revenue_tracker -- Ad platform analytics with Grok analysis
49	- infra_monitor -- Full-stack health monitoring across all nodes
50	- backup_manager -- Automated vzdump, pg_dump, and config archival
51	- command_executor -- SSH command execution with safety controls
52	- general_assistant -- Catchall brain with web search augmentation
53
54	### Multi-LLM Integration
55	- Grok/xAI -- Primary analysis engine ($2/$10 per 1M tokens)
56	- GPT-4o-mini -- Compliance scanning ($0.15/$0.60 per 1M tokens)
57	- Ollama (local) -- Free inference for content agents, trend analysis
58	- Runtime switching via `!model grok` / `!model gpt` / `!model ollama [name]`
59	- Per-request cost tracking against a monthly budget ceiling
60
61	### Infrastructure Management
62	- SSH execution across all homelab nodes with three safety tiers:
63	- Blocklist: destructive commands rejected immediately
64	- Auto-approve: read-only operations execute without confirmation
65	- Manual approval: everything else requires explicit `!exec`
66	- Health monitoring: CPU, RAM, disk, GPU utilization, temperature, Ollama model status
67	- Backup system: Proxmox vzdump snapshots, PostgreSQL dumps, config archives with retention policies
68	- Infrastructure map with aliases (e.g., "gpu" resolves to the correct node)
69
70	### AI Response Processing
71	The AI can emit structured directives that Perseus interprets and executes:
72	- `EXECUTE:hostname:command` -- runs SSH commands inline during conversation
73	- `SEARCH:query` -- triggers Brave web search and injects results
74
75	### Discord Command and Control
76	- Natural language chat routed to the active brain
77	- DM-based admin control with owner-only authentication
78	- Rate limiting per user
79	- Long message chunking (auto-splits at 2000 chars)
80	- Conversation context carried across exchanges
81
82	## Tech Stack
83
84	\| Component \| Purpose \|
85	\|-----------\|---------\|
86	\| Python 3.11 \| Core runtime \|
87	\| FastAPI \| REST API (port 3002) \|
88	\| Discord.py \| Bot interface with DM admin \|
89	\| PostgreSQL \| Agent activity logging, cost analytics \|
90	\| Grok/xAI API \| Primary AI brain with web + X search \|
91	\| OpenAI API (GPT-4o-mini) \| Compliance scanning \|
92	\| Ollama \| Free local LLM inference on GPU \|
93	\| Brave Search API \| Web search integration \|
94	\| X/Twitter API \| OAuth 1.0a social posting \|
95	\| Node.js + Express \| Video library microservice API \|
96	\| SSH + subprocess \| Cross-node command execution \|
97
98	## Setup
99
100	### Prerequisites
101	- Python 3.10+
102	- PostgreSQL
103	- Ollama with at least one model pulled
104	- Discord bot token
105	- SSH key access to your infrastructure nodes
106
107	### Installation
108
109	```bash
110	git clone https://github.com/YOUR_USERNAME/perseus-ai-platform.git
111	cd perseus-ai-platform
112
113	pip install fastapi uvicorn requests discord.py psycopg2-binary
114
115	# Set up PostgreSQL
116	createdb perseus
117	psql perseus -c "CREATE TABLE metadata (id SERIAL PRIMARY KEY, agent TEXT, timestamp TEXT, command TEXT, result TEXT, cost_usd REAL DEFAULT 0);"
118
119	# Configure environment
120	cp .env.example .env
121	# Edit .env with your API keys, IPs, and credentials
122
123	# For video API (optional)
124	cd video-api && npm install && cd ..
125	```
126
127	### Running
128
129	```bash
130	# Start Perseus (Discord + FastAPI + all agents)
131	uvicorn main:app --host 0.0.0.0 --port 3002
132
133	# Start video API (optional, separate process)
134	node video-api.js
135	```
136
137	## Configuration
138
139	See `.env.example` for all environment variables. Key settings:
140
141	\| Variable \| Description \|
142	\|----------\|-------------\|
143	\| `XAI_API_KEY` \| Grok/xAI API key (primary brain) \|
144	\| `OPENAI_API_KEY` \| OpenAI API key (compliance scanner) \|
145	\| `BRAVE_API_KEY` \| Brave Search API key \|
146	\| `DISCORD_TOKEN` \| Discord bot token \|
147	\| `OLLAMA_URL` \| Ollama server URL \|
148	\| `PG_*` \| PostgreSQL connection details \|
149	\| `NODE*_IP` \| Infrastructure node IP addresses \|
150	\| `MONTHLY_BUDGET` \| API spend ceiling (default $10) \|