Adrian Flores Cortes 3def230d58 Initial commit: local-llm-agent infrastructure project

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-02-02 16:42:45 -06:00

12 KiB

Raw Permalink Blame History

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:

{
  "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:

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

12 KiB Raw Permalink Blame History

Requerimientos No Funcionales - Local LLM Agent

1. RENDIMIENTO (PERFORMANCE)

RNF-P-001: Latencia de Respuesta

RNF-P-002: Throughput

RNF-P-003: Cold Start Time

2. ESCALABILIDAD (SCALABILITY)

RNF-S-001: Escalabilidad de Modelos

RNF-S-002: Escalabilidad de Agentes

3. DISPONIBILIDAD (AVAILABILITY)

RNF-A-001: Uptime Objetivo

RNF-A-002: Graceful Degradation

4. SEGURIDAD (SECURITY)

RNF-SEC-001: Autenticacion y Autorizacion

RNF-SEC-002: Seguridad de Comunicacion

RNF-SEC-003: Proteccion de Datos

5. MANTENIBILIDAD (MAINTAINABILITY)

RNF-M-001: Modularidad

RNF-M-002: Logging y Trazabilidad

RNF-M-003: Configurabilidad

RNF-M-004: Testing

6. USABILIDAD (USABILITY)

RNF-U-001: Compatibilidad OpenAI

RNF-U-002: Documentacion API

7. RECURSOS Y RESTRICCIONES

RNF-R-001: Uso de VRAM

RNF-R-002: Uso de Memoria RAM

RNF-R-003: Uso de CPU

8. COMPATIBILIDAD (COMPATIBILITY)

RNF-C-001: Compatibilidad con Backends

RNF-C-002: Compatibilidad con Agentes

9. RESUMEN DE PRIORIDADES

10. REFERENCIAS

12 KiB

Raw Permalink Blame History