MAX · Sistema de IA Multi-Agente Autónomo y Socio Estratégico

Copia pública sanitizada del core de MAX System. Arquitectura de microservicios distribuida para orquestación de agentes autónomos de IA, enrutamiento dinámico multinivel de LLMs y ejecución remota de comandos.

---

🎯 ¿Por qué existe MAX System? (La Problemática)

La mayoría de asistentes de IA comerciales actúan como chatbots aislados sin memoria a largo plazo, sin acceso a herramientas locales y con un costo operativo elevado al depender de un solo modelo costoso (como Claude 3.5 Sonnet o GPT-4o) para cualquier tarea, sin importar su complejidad.

MAX System fue creado para resolver tres problemas fundamentales:

1. Falta de autonomía operacional: La incapacidad de delegar tareas complejas de desarrollo de software que requieren ejecutar código local, consultar bases de datos y manipular archivos.
2. Costos ineficientes de inferencia: Pagar tarifas premium por tareas triviales que modelos más ligeros u open-source pueden resolver por una fracción del costo ($0 o <$0.003).
3. Pérdida de contexto persistente: La fragmentación del conocimiento entre sesiones de chat. MAX mantiene una memoria vectorial centralizada en Supabase (pgvector) conectada a múltiples canales.

---

⚡ ¿Para qué sirve MAX System? (El Propósito y Valor)

MAX actúa como un COO Digital (Chief Operating Officer) y segundo cerebro estratégico. Su objetivo principal es recibir instrucciones en lenguaje natural a través de Telegram o la API local, analizar la intención, decidir la estrategia de ejecución óptima y coordinar una red de agentes especializados que ejecutan cambios reales en repositorios, servidores y sistemas externos.

Casos de uso clave:

• Orquestación de código: Refactorización, generación de tests unitarios y auditorías de código mediante agentes especializados (Pi Service).
• Ejecución remota segura: Ejecución de comandos en la máquina local o servidor mediante el cliente OpenClaw.
• Enrutamiento inteligente de LLMs: Selección dinámica entre modelos propietarios (Claude 3.5 Opus/Sonnet) y modelos open-source (DeepSeek R1, Qwen 2.5, Minimax) según la complejidad.

---

🏗️ Arquitectura del Sistema

graph TD
    User([Telegram / API Client]) -->|Mensaje / Comando| Nginx[Nginx Reverse Proxy]
    Nginx -->|Autenticación JWT| Dispatch[Dispatch Engine :8001]
    
    subgraph Orquestación Central
        Dispatch -->|Enrutamiento de nivel| Router{Clasificador de Complejidad}
        Router -->|Nivel 1-2: Rápido / Gratis| PiService[Pi Service :8000]
        Router -->|Nivel 3-4: Autónomo / Razonamiento| ClaudeAPI[Claude / DeepSeek R1 API]
    end
    
    subgraph Servicios & Herramientas
        Dispatch <-->|Búsqueda Semántica| Supabase[(Supabase pgvector)]
        Dispatch -->|Servidor MCP| OpenClaw[OpenClaw Agent Exec :8002]
        OpenClaw -->|Comandos de Sistema| LocalPC[Entorno Local / Servidor]
    end

Loading

---

🧩 Motores y Microservicios

Servicio	Puerto	Rol Principal	Modelos / Stack
Dispatch	8001	Cerebro orquestador y clasificador de intenciones	Python, FastAPI, Anthropic API
Pi Service	8000	Generación de código de alta velocidad y tareas livianas	Minimax, Qwen 2.5, Kimi, GPT-OSS 120B
OpenClaw	8002	Ejecutor de comandos del sistema y manipulación de archivos	Python, AsyncIO, Subprocess

---

📊 Matriz de Enrutamiento Dinámico (Niveles de Complejidad)

Nivel	Trigger / Intención	Modelos Asignados	Costo Promedio
1 - Simple	Consultas directas, mensajes cortos, 1 acción	Pi Minimax	$0.00
2 - Normal	Generación de funciones conocidas, formato de datos	Pi Qwen / GLM / GPT-OSS	$0.00
3 - Complejo	Múltiples pasos, lectura/escritura de archivos	Pi Kimi + Claude Haiku	~$0.003
4 - Avanzado	Razonamiento autónomo de 3+ acciones complejas	DeepSeek R1 + Claude Sonnet	~$0.01

---

🛠️ Stack Tecnológico

• Backend & Core: Python 3.11+, FastAPI, Pydantic, AsyncIO.
• Protocolo de Integración: Model Context Protocol (MCP), Server-Sent Events (SSE).
• Base de Datos & Memoria: Supabase (PostgreSQL 17 + extensión pgvector).
• Infraestructura & Servidor: AWS EC2 (Ubuntu 24.04), Docker Compose, Nginx Reverse Proxy.
• Canales de Entrada: Telegram Bot API (long-polling / webhook).

---

🔑 Variables de Entorno (.env)

# Configuración del servidor
ENVIRONMENT=production
DISPATCH_PORT=8001
DISPATCH_SECRET=tu_secreto_super_seguro

# Proveedores de IA
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENROUTER_API_KEY=sk-or-v1-...
OLLAMA_CLOUD_URL=https://api.ollama.com
OLLAMA_API_KEY=tu_ollama_key

# Memoria Persistente (Supabase)
SUPABASE_URL=https://tu-proyecto.supabase.co
SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6...

# Integraciones
TELEGRAM_TOKEN=123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ

---

🚀 Inicio Rápido en Local

# 1. Clonar el repositorio
git clone https://github.com/jd5073356-max/max-system-public.git
cd max-system-public

# 2. Configurar variables de entorno
cp .env.example .env
# Edita el archivo .env con tus credenciales

# 3. Levantar con Docker Compose
docker compose up -d

# 4. Verificar estado del servicio
curl http://localhost:8001/health

---

📋 Estado del Proyecto

📌 En hibernación activa por migración.
El sistema funcionó de manera ininterrumpida en producción sobre AWS EC2. Actualmente se encuentra en proceso de migración hacia una arquitectura Homelab local para reducir costos fijos a $0. El código de este repositorio sirve como referencia de arquitectura para sistemas de agentes autónomos distribuidos.

---

👤 Autor

Juan David Herrera
AI Automation Engineer | Product Engineer · AI, Systems & Web3
Bogotá, Colombia

• GitHub: @jd5073356-max
• LinkedIn: linkedin.com/in/juan-david-herrera