HydraLLM: orquestador inteligente

HydraLLM: orquestador inteligente

HydraLLM es una gateway consciente del contexto, diseñada para aprovechar de forma eficiente múltiples recursos de LLM. Enruta solicitudes entre Gemini / Groq / Cerebras, ofrece circuit breakers por proveedor, rotación aleatoria de claves (incluyendo enfriamiento consciente de cuotas), capacidades de enriquecimiento web en tiempo real, y estructura una API compatible con OpenAI sobre una estricta Clean Architecture (Domain luego Services luego Adapters luego API).

• Versión: 1.3.0 (pyproject.toml)
• Python: 3.10+
• Punto de entrada de ejecución: python main.py
• UI integrada: http://localhost:8000/ui
• Endpoint compatible con OpenAI: POST /v1/chat/completions

Especificación técnica de HydraLLM (SPEC)

1. Resumen

HydraLLM es una gateway de LLM de alta disponibilidad que cumple con Clean Architecture. Proporciona enrutamiento inteligente entre múltiples proveedores, aislamiento de fallas basado en circuit breakers, capacidades de enriquecimiento web en tiempo real y soporte completo para la especificación de la API de OpenAI.

2. Especificación de componentes clave

2.1 Gateway (src/services/gateway.py)

• Orquestación: coordina el flujo de carga de sesión -> análisis de contexto -> enriquecimiento web -> ejecución resiliente -> persistencia.
• Motivos técnicos de enrutamiento: incluye en todas las respuestas la base de la decisión mediante constantes claras.
  • USER_HINT: especificación explícita del usuario
  • TOKEN_OPTIMIZED: optimización basada en la cantidad de tokens
  • WEB_INTENT_SEARCH: resultado del análisis de intención de búsqueda web
  • MULTIMODAL_ANALYSIS: detección de necesidad de procesar imágenes
  • KEY_AVAILABILITY: estado de las claves y resultado del failover

2.2 Analizador de contexto (src/services/analyzer.py)

• Algoritmo de enrutamiento: analiza la longitud de tokens, si es multimodal y la intención de búsqueda web para generar la RoutingDecision óptima.
• Filtrado dinámico de disponibilidad: refleja el estado en tiempo real de KeyManager para excluir de las opciones los modelos de proveedores que no tienen claves activas.

2.3 Gestor de claves (src/services/key_manager.py)

• Rotación de claves: selección aleatoria dentro del pool de claves activas y seguimiento de uso.
• Gestión de fallas: aplica enfriamientos diferenciados según el tipo de error.
  • 403 Forbidden: 24 horas (respuesta a fallas permanentes por clave)
  • 429 Rate Limit / Quota: 1 hora
  • Otros errores de comunicación: 5 minutos

2.4 Servicio de contexto web (src/services/web_context_service.py)

• Enriquecimiento de datos: recopilación de información en tiempo real basada en Playwright/Scrapling e inyección en el prompt.
• Seguimiento de rendimiento: registra tasa de éxito, cantidad de caracteres recopilados y latencia mediante la tabla scraping_metrics.

3. Patrones de resiliencia y recuperación (Troubleshooting Insights)

• Concurrency Guard: aplica asyncio.Lock y threading.Lock a las operaciones de escritura de KeyManager y SessionManager para garantizar la integridad de los datos bajo alta carga.
• Self-Healing Scraper: activa un mecanismo de reinicio automático al detectar fallas en instancias del navegador.
• Unpacking Guard: cumple con tipos de retorno estrictos (tuple[list, str | None]) y protecciones para prevenir errores de NoneType que pueden ocurrir al procesar datos enriquecidos.