local-llm-agent/docs/50-requerimientos/RNF-REQUERIMIENTOS-NO-FUNCIONALES.md

# Requerimientos No Funcionales - Local LLM Agent

**Version:** 1.0.0
**Fecha:** 2026-01-20
**Proyecto:** local-llm-agent
**Prioridad:** P1 (Infraestructura)

---

## 1. RENDIMIENTO (PERFORMANCE)

### RNF-P-001: Latencia de Respuesta

| Atributo | Valor |
|----------|-------|
| ID | RNF-P-001 |
| Categoria | Performance |
| Prioridad | MUST HAVE |

**Descripcion:**
El sistema DEBE cumplir con los siguientes objetivos de latencia.

**Metricas:**

| Operacion | Tier | Latencia p50 | Latencia p95 | Latencia p99 |
|-----------|------|--------------|--------------|--------------|
| Chat Completion | small | 300ms | 500ms | 800ms |
| Chat Completion | main | 1000ms | 2000ms | 3500ms |
| List Models | - | 30ms | 100ms | 200ms |
| Health Check | - | 10ms | 50ms | 100ms |
| MCP Tools | small | 400ms | 800ms | 1200ms |

**Condiciones de Medicion:**
- Medido end-to-end desde Gateway hasta respuesta
- Bajo carga normal (< 3 agentes concurrentes)
- Modelo cargado en memoria (warm start)

---

### RNF-P-002: Throughput

| Atributo | Valor |
|----------|-------|
| ID | RNF-P-002 |
| Categoria | Performance |
| Prioridad | SHOULD HAVE |

**Descripcion:**
El sistema DEBE soportar el siguiente throughput sostenido.

**Metricas:**

| Metrica | Objetivo Minimo | Objetivo Optimo |
|---------|-----------------|-----------------|
| Requests por minuto (tier small) | 20 | 40 |
| Requests por minuto (tier main) | 5 | 10 |
| Tokens por segundo (generacion) | 60 | 100 |
| Agentes concurrentes | 2 | 3 |

**Nota:** Limitado por capacidad de GPU (RTX 5060 Ti 16GB)

---

### RNF-P-003: Cold Start Time

| Atributo | Valor |
|----------|-------|
| ID | RNF-P-003 |
| Categoria | Performance |
| Prioridad | NICE TO HAVE |

**Descripcion:**
El sistema DEBE inicializarse en tiempo razonable desde cold start.

**Metricas:**

| Componente | Tiempo Maximo |
|------------|---------------|
| Gateway startup | 5 segundos |
| Inference Engine startup | 10 segundos |
| Modelo carga inicial | 60 segundos |
| Sistema completo operativo | 90 segundos |

---

## 2. ESCALABILIDAD (SCALABILITY)

### RNF-S-001: Escalabilidad de Modelos

| Atributo | Valor |
|----------|-------|
| ID | RNF-S-001 |
| Categoria | Scalability |
| Prioridad | NICE TO HAVE (Fase 3) |

**Descripcion:**
El sistema DEBERIA soportar multiples modelos/adaptadores en el futuro.

**Objetivos Fase 3:**
- Soporte para Multi-LoRA (2-4 adaptadores simultaneos)
- Hot-swap de modelos sin reinicio
- Routing basado en proyecto/dominio

**Restricciones Actuales (MVP):**
- Un modelo activo a la vez
- Cambio de modelo requiere reinicio de backend

---

### RNF-S-002: Escalabilidad de Agentes

| Atributo | Valor |
|----------|-------|
| ID | RNF-S-002 |
| Categoria | Scalability |
| Prioridad | SHOULD HAVE |

**Descripcion:**
El sistema DEBE escalar a multiples agentes concurrentes.

**Capacidad:**

| Fase | Agentes Concurrentes | Batch Size |
|------|---------------------|------------|
| MVP | 2 | 1 |
| Fase 2 | 3 | 2 |
| Fase 3 | 5+ | 4 |

---

## 3. DISPONIBILIDAD (AVAILABILITY)

### RNF-A-001: Uptime Objetivo

| Atributo | Valor |
|----------|-------|
| ID | RNF-A-001 |
| Categoria | Availability |
| Prioridad | SHOULD HAVE |

**Descripcion:**
El sistema DEBE mantener disponibilidad adecuada para entorno de desarrollo.

**Metricas:**

| Metrica | Objetivo |
|---------|----------|
| Uptime durante horas laborales | 95% |
| MTTR (Mean Time To Recovery) | < 5 minutos |
| Degraded mode availability | 99% |

**Modo Degradado:**
- Si Ollama no responde, Gateway retorna 503 con mensaje claro
- Health check refleja estado degradado
- Logs indican problema para diagnostico rapido

---

### RNF-A-002: Graceful Degradation

| Atributo | Valor |
|----------|-------|
| ID | RNF-A-002 |
| Categoria | Availability |
| Prioridad | SHOULD HAVE |

**Descripcion:**
El sistema DEBE degradarse graciosamente ante fallos parciales.

**Comportamiento:**

| Escenario | Comportamiento |
|-----------|----------------|
| Ollama no disponible | Gateway retorna 503, health indica "unhealthy" |
| Alta latencia backend | Log warning, continua procesando |
| Memoria insuficiente | Rechaza nuevos requests, procesa cola existente |
| Timeout en request | Retorna error timeout, libera recursos |

---

## 4. SEGURIDAD (SECURITY)

### RNF-SEC-001: Autenticacion y Autorizacion

| Atributo | Valor |
|----------|-------|
| ID | RNF-SEC-001 |
| Categoria | Security |
| Prioridad | NICE TO HAVE (Fase 2) |

**Descripcion:**
El sistema DEBERIA implementar autenticacion basica.

**MVP:** Sin autenticacion (red local confiable)

**Fase 2:**
- API Key simple via header `X-API-Key`
- Whitelist de IPs permitidas
- Rate limiting basico por IP

---

### RNF-SEC-002: Seguridad de Comunicacion

| Atributo | Valor |
|----------|-------|
| ID | RNF-SEC-002 |
| Categoria | Security |
| Prioridad | SHOULD HAVE |

**Descripcion:**
El sistema DEBE asegurar comunicaciones internas.

**Medidas:**
- Comunicacion Gateway <-> Inference Engine via red Docker interna
- No exponer Inference Engine a red externa
- CORS configurado restrictivamente
- Headers de seguridad basicos

---

### RNF-SEC-003: Proteccion de Datos

| Atributo | Valor |
|----------|-------|
| ID | RNF-SEC-003 |
| Categoria | Security |
| Prioridad | SHOULD HAVE |

**Descripcion:**
El sistema DEBE proteger datos sensibles en logs y almacenamiento.

**Medidas:**
- No loggear contenido completo de prompts
- Truncar contenido en logs a 100 caracteres
- No persistir prompts/respuestas por defecto
- Sanitizar inputs antes de pasar a backend

---

## 5. MANTENIBILIDAD (MAINTAINABILITY)

### RNF-M-001: Modularidad

| Atributo | Valor |
|----------|-------|
| ID | RNF-M-001 |
| Categoria | Maintainability |
| Prioridad | MUST HAVE |

**Descripcion:**
El sistema DEBE mantener separacion clara entre componentes.

**Estructura:**
```
local-llm-agent/
├── apps/
│   ├── gateway/          # NestJS - API Gateway
│   │   ├── src/
│   │   │   ├── modules/
│   │   │   │   ├── chat/
│   │   │   │   ├── models/
│   │   │   │   ├── mcp-tools/
│   │   │   │   └── health/
│   │   │   └── common/
│   │   └── test/
│   │
│   └── inference-engine/ # Python - Backend
│       ├── src/
│       │   ├── routes/
│       │   ├── engine/
│       │   └── adapters/
│       └── tests/
│
├── docs/
├── orchestration/
└── docker-compose.yml
```

---

### RNF-M-002: Logging y Trazabilidad

| Atributo | Valor |
|----------|-------|
| ID | RNF-M-002 |
| Categoria | Maintainability |
| Prioridad | SHOULD HAVE |

**Descripcion:**
El sistema DEBE proveer logging suficiente para debugging y monitoreo.

**Requerimientos:**
- Logs en formato JSON estructurado
- Correlation ID (request_id) en toda la cadena
- Niveles: DEBUG, INFO, WARNING, ERROR
- Timestamps ISO 8601
- Metricas de latencia por request

**Ejemplo Log:**
```json
{
  "timestamp": "2026-01-20T10:30:00.123Z",
  "level": "INFO",
  "logger": "gateway.chat",
  "request_id": "req-abc123",
  "message": "Chat completion finished",
  "latency_ms": 1234,
  "prompt_tokens": 150,
  "completion_tokens": 50,
  "model": "gpt-oss-20b"
}
```

---

### RNF-M-003: Configurabilidad

| Atributo | Valor |
|----------|-------|
| ID | RNF-M-003 |
| Categoria | Maintainability |
| Prioridad | MUST HAVE |

**Descripcion:**
El sistema DEBE ser configurable via environment variables.

**Principios:**
- Todas las configuraciones via ENV vars
- Valores sensibles nunca en codigo
- Defaults razonables para desarrollo
- Documentacion de todas las variables

---

### RNF-M-004: Testing

| Atributo | Valor |
|----------|-------|
| ID | RNF-M-004 |
| Categoria | Maintainability |
| Prioridad | SHOULD HAVE |

**Descripcion:**
El sistema DEBE tener cobertura de tests adecuada.

**Objetivos:**

| Tipo de Test | Cobertura Objetivo |
|--------------|-------------------|
| Unit Tests | 70% |
| Integration Tests | Endpoints criticos |
| E2E Tests | Happy path |

---

## 6. USABILIDAD (USABILITY)

### RNF-U-001: Compatibilidad OpenAI

| Atributo | Valor |
|----------|-------|
| ID | RNF-U-001 |
| Categoria | Usability |
| Prioridad | MUST HAVE |

**Descripcion:**
El sistema DEBE ser compatible con clientes OpenAI existentes.

**Metricas:**
- SDK OpenAI Python debe funcionar sin modificacion
- SDK OpenAI Node.js debe funcionar sin modificacion
- Solo cambiar base_url para usar local-llm-agent

**Ejemplo Uso:**
```python
import openai

client = openai.OpenAI(
    base_url="http://localhost:3160/v1",
    api_key="not-required"
)

response = client.chat.completions.create(
    model="gpt-oss-20b",
    messages=[{"role": "user", "content": "Hello"}]
)
```

---

### RNF-U-002: Documentacion API

| Atributo | Valor |
|----------|-------|
| ID | RNF-U-002 |
| Categoria | Usability |
| Prioridad | SHOULD HAVE |

**Descripcion:**
El sistema DEBE proveer documentacion de API.

**Requerimientos:**
- Swagger/OpenAPI disponible en /docs
- Ejemplos de uso para cada endpoint
- Schema de request/response documentado

---

## 7. RECURSOS Y RESTRICCIONES

### RNF-R-001: Uso de VRAM

| Atributo | Valor |
|----------|-------|
| ID | RNF-R-001 |
| Categoria | Resources |
| Prioridad | MUST HAVE |

**Descripcion:**
El sistema DEBE operar dentro de los limites de VRAM disponible.

**Budget VRAM (RTX 5060 Ti 16GB):**

| Componente | Asignacion |
|------------|------------|
| Modelo base (Q4_K_M) | 14 GB |
| KV Cache | 1.5 GB |
| Buffer sistema | 0.5 GB |
| **Total** | **16 GB** |

**Restricciones:**
- No cargar modelos mayores a 14GB
- Monitorear uso de VRAM via nvidia-smi
- Alertar si VRAM > 95%

---

### RNF-R-002: Uso de Memoria RAM

| Atributo | Valor |
|----------|-------|
| ID | RNF-R-002 |
| Categoria | Resources |
| Prioridad | SHOULD HAVE |

**Descripcion:**
El sistema DEBE mantener uso de RAM razonable.

**Objetivos:**

| Componente | RAM Maxima |
|------------|------------|
| Gateway | 512 MB |
| Inference Engine | 1 GB |
| Total servicios | 1.5 GB |

---

### RNF-R-003: Uso de CPU

| Atributo | Valor |
|----------|-------|
| ID | RNF-R-003 |
| Categoria | Resources |
| Prioridad | NICE TO HAVE |

**Descripcion:**
El sistema DEBERIA minimizar uso de CPU (inferencia en GPU).

**Objetivos:**
- CPU usage promedio < 20% durante inferencia
- Spikes permitidos durante carga de modelo

---

## 8. COMPATIBILIDAD (COMPATIBILITY)

### RNF-C-001: Compatibilidad con Backends

| Atributo | Valor |
|----------|-------|
| ID | RNF-C-001 |
| Categoria | Compatibility |
| Prioridad | MUST HAVE |

**Descripcion:**
El sistema DEBE soportar multiples backends de inferencia.

**Backends Soportados:**

| Backend | Version | Estado | Notas |
|---------|---------|--------|-------|
| Ollama | >= 0.1.0 | MVP | Windows nativo |
| vLLM | >= 0.2.0 | Fase 3 | Requiere WSL |

---

### RNF-C-002: Compatibilidad con Agentes

| Atributo | Valor |
|----------|-------|
| ID | RNF-C-002 |
| Categoria | Compatibility |
| Prioridad | MUST HAVE |

**Descripcion:**
El sistema DEBE ser compatible con los agentes del workspace.

**Agentes Soportados:**
- Claude Code (via API OpenAI-compatible)
- Trae (via API OpenAI-compatible)
- Gemini (via API OpenAI-compatible)

---

## 9. RESUMEN DE PRIORIDADES

| Prioridad | RNFs |
|-----------|------|
| MUST HAVE | RNF-P-001, RNF-M-001, RNF-M-003, RNF-U-001, RNF-R-001, RNF-C-001, RNF-C-002 |
| SHOULD HAVE | RNF-P-002, RNF-A-001, RNF-A-002, RNF-SEC-002, RNF-SEC-003, RNF-M-002, RNF-M-004, RNF-U-002, RNF-R-002, RNF-S-002 |
| NICE TO HAVE | RNF-P-003, RNF-S-001, RNF-SEC-001, RNF-R-003 |

---

## 10. REFERENCIAS

- ADR-001: Runtime Selection
- ADR-002: Model Selection
- RF-REQUERIMIENTOS-FUNCIONALES.md
- ARQUITECTURA-LOCAL-LLM.md

---

**Documento Controlado**
- Autor: Requirements-Analyst Agent
- Revisor: Architecture-Analyst Agent
- Fecha: 2026-01-20