system-docs/v4-archive/orchestrator/README.md

# LLM Orchestrator

![Estado](https://img.shields.io/badge/Estado-IMPLEMENTADO-brightgreen)


Sistema de orquestación multi-agente compatible con cualquier LLM.

## ¿Qué es esto?

Un framework para crear y coordinar múltiples agentes de IA que pueden:
- Ejecutar comandos en tu sistema
- Leer y escribir archivos
- Conectarse a servidores via SSH
- Hacer llamadas a APIs
- Trabajar juntos en tareas complejas

## Características

- **Multi-modelo**: Claude, GPT-4, Gemini, Llama, Mistral, y 100+ más
- **Herramientas universales**: Bash, lectura/escritura de archivos, SSH, HTTP
- **Agentes personalizables**: Define tantos agentes como necesites
- **LOGs automáticos**: Registro de todas las acciones
- **Sin dependencias pesadas**: Solo Python estándar + LiteLLM opcional

## Instalación

```bash
# Clonar o descomprimir
cd orchestrator

# Crear entorno virtual
python3 -m venv .venv
source .venv/bin/activate

# Instalar dependencias opcionales
pip install litellm  # Para usar GPT-4, Gemini, Llama, etc.
```

## Uso rápido

### 1. Define tus agentes

Edita `config.yaml`:

```yaml
agents:
  researcher:
    role: "Investigador que busca información"
    provider: claude
    model: sonnet
    tools: [bash, read, http_request]
    
  coder:
    role: "Programador que escribe código"
    provider: litellm
    model: gpt4o
    tools: [read, write, bash]
    
  reviewer:
    role: "Revisor que valida el trabajo"
    provider: litellm
    model: gemini-pro
    tools: [read, grep]
```

### 2. Ejecuta el orquestador

```bash
# Modo interactivo
python orchestrator/main.py

# Ejecutar un agente específico
python orchestrator/main.py --agent researcher --prompt "Busca información sobre X"

# Ver estado
python orchestrator/main.py --status
```

### 3. Comandos interactivos

```
/status          - Ver estado del sistema
/agents          - Listar agentes disponibles
/agent <nombre>  - Cambiar agente activo
/logs <agente>   - Ver historial del agente
/all             - Ejecutar en todos los agentes
/quit            - Salir
```

## Estructura

```
orchestrator/
├── config.yaml              # ← Tu configuración de agentes
├── orchestrator/
│   ├── main.py              # Punto de entrada
│   ├── config.py            # Carga de configuración
│   ├── providers/           # Conexión con LLMs
│   │   ├── claude_provider.py
│   │   └── litellm_provider.py
│   ├── tools/               # Herramientas disponibles
│   │   ├── executor.py
│   │   └── definitions.py
│   ├── agents/              # Lógica de agentes
│   │   └── base.py
│   └── tasks/               # Tareas predefinidas
├── logs/                    # Historial por agente
├── outputs/                 # Archivos generados
└── examples/                # Ejemplos de configuración
```

## Providers disponibles

| Provider | Modelos | Requisito |
|----------|---------|-----------|
| `claude` | sonnet, opus, haiku | Claude Code CLI instalado |
| `litellm` | gpt4o, gemini-pro, llama3, mistral... | `pip install litellm` + API keys |

## Herramientas disponibles

| Herramienta | Descripción |
|-------------|-------------|
| `bash` | Ejecuta comandos del sistema |
| `read` | Lee archivos |
| `write` | Escribe/crea archivos |
| `glob` | Busca archivos por patrón |
| `grep` | Busca texto en archivos |
| `ssh` | Ejecuta comandos en servidores remotos |
| `http_request` | Hace peticiones HTTP/API |
| `list_dir` | Lista contenido de directorios |

## Ejemplos

### Agente simple (solo conversación)

```yaml
agents:
  assistant:
    role: "Asistente general"
    provider: claude
    model: sonnet
    tools: []  # Sin herramientas
```

### Equipo de desarrollo

```yaml
agents:
  architect:
    role: "Diseña la arquitectura del sistema"
    provider: claude
    model: opus
    tools: [read, write, bash]
    
  developer:
    role: "Implementa el código"
    provider: litellm
    model: gpt4o
    tools: [read, write, bash, grep]
    
  tester:
    role: "Escribe y ejecuta tests"
    provider: litellm
    model: gemini-pro
    tools: [read, bash]
```

### Agentes con servidores

```yaml
servers:
  production:
    host: 192.168.1.100
    user: deploy
    key: ~/.ssh/id_rsa
    
  staging:
    host: 192.168.1.101
    user: deploy
    key: ~/.ssh/id_rsa

agents:
  deployer:
    role: "Despliega aplicaciones a servidores"
    provider: claude
    model: sonnet
    tools: [ssh, bash, read]
    servers: [production, staging]
```

## Variables de entorno

Para usar modelos de pago via LiteLLM:

```bash
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."
export ANTHROPIC_API_KEY="..."  # Si usas Claude via API
```

## Licencia

MIT - Usa, modifica y comparte libremente.