# Arquitectura Local LLM Agent

## Vision General

Local LLM Agent es un gateway de LLM local que permite a los agentes del workspace (Claude Code, Trae, Gemini) delegar tareas simples para optimizar el uso de contexto y tokens en los modelos principales.

## Diagrama de Arquitectura

```
┌─────────────────────────────────────────────────────────────────┐
│                    AGENTES EXTERNOS                              │
│   Claude Code (Orquestador) │ Trae (Ejecutor) │ Gemini (QA)     │
└─────────────────────────────┬───────────────────────────────────┘
                              │ HTTP/REST
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              LOCAL-LLM-AGENT (Puerto 3160)                      │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │           API Gateway (NestJS)                            │  │
│  │                                                           │  │
│  │  ┌─────────────────────┐  ┌─────────────────────────────┐ │  │
│  │  │ OpenAI Compatible   │  │ MCP Tools                   │ │  │
│  │  │ POST /v1/chat/...   │  │ POST /mcp/tools/:name       │ │  │
│  │  │ GET  /v1/models     │  │ GET  /mcp/tools             │ │  │
│  │  └─────────────────────┘  └─────────────────────────────┘ │  │
│  │                              │                            │  │
│  │  ┌───────────────────────────┴────────────────────────┐   │  │
│  │  │              Router Service                         │   │  │
│  │  │  - Tier Classification (small/main)                │   │  │
│  │  │  - Token Estimation                                │   │  │
│  │  │  - Project Detection                               │   │  │
│  │  └────────────────────────────────────────────────────┘   │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              │ HTTP                              │
│  ┌───────────────────────────┴───────────────────────────────┐  │
│  │           Inference Engine (Python FastAPI)               │  │
│  │                                                           │  │
│  │  ┌─────────────────────┐  ┌─────────────────────────────┐ │  │
│  │  │ Ollama Backend      │  │ vLLM Backend (futuro)       │ │  │
│  │  │ (MVP)               │  │ - Multi-LoRA                │ │  │
│  │  └─────────────────────┘  │ - Continuous Batching       │ │  │
│  │                           └─────────────────────────────┘ │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                 NVIDIA RTX 5060 Ti (16GB VRAM)                  │
│  GPT-OSS 20B Q4_K_M (~14GB) + KV Cache (~1.5GB)                │
└─────────────────────────────────────────────────────────────────┘
```

## Componentes

### 1. API Gateway (NestJS)

Punto de entrada para todos los agentes. Expone:

- **OpenAI-Compatible API**: Compatibilidad con el estandar OpenAI para integracion facil
- **MCP Tools API**: Herramientas especializadas para tareas comunes
- **Router Service**: Clasificacion de tier y deteccion de proyecto

### 2. Inference Engine (Python FastAPI)

Motor de inferencia con soporte para multiples backends:

- **Ollama Backend (MVP)**: Integracion con Ollama existente
- **vLLM Backend (Futuro)**: Para capacidades avanzadas (Multi-LoRA, batching)

### 3. Router Service

Clasifica requests en tiers:

| Tier | Max Tokens | Max Context | Latencia Target | Uso |
|------|------------|-------------|-----------------|-----|
| small | 512 | 4096 | 500ms | Clasificacion, extraccion simple |
| main | 2048 | 16384 | 2000ms | Tareas complejas |

## Flujo de Requests

```
1. Agente envia request a Gateway (3160)
2. Router clasifica tier basado en:
   - Estimacion de tokens
   - Header x_tier (opcional)
   - Tipo de herramienta MCP
3. Gateway envia a Inference Engine (3161)
4. Inference Engine ejecuta contra Ollama (11434)
5. Respuesta regresa al agente
```

## Configuracion de VRAM

```
Total VRAM: 16GB
├── Modelo (GPT-OSS 20B Q4_K_M): 14GB
├── KV Cache (dinamico): 1.5GB
└── Buffer: 0.5GB
```

## Escalabilidad

- **Concurrencia**: 2-3 agentes simultaneos
- **Batch Size**: 4 requests
- **Context Length**: Hasta 16384 tokens

## Evolucion Planeada

### Fase 1 (MVP)
- Gateway basico
- Ollama backend
- MCP tools basicos

### Fase 2 (Multi-Proyecto)
- LoRA adapters por proyecto
- Project detection automatico
- Metricas por proyecto

### Fase 3 (Produccion)
- vLLM backend en WSL
- Multi-LoRA simultaneo
- Continuous batching