HydraLLM: Orquestrador Inteligente

HydraLLM: Orquestrador Inteligente

HydraLLM é um gateway sensível ao contexto projetado para utilizar com eficiência vários recursos de LLM. Ele roteia requisições entre Gemini / Groq / Cerebras, oferece disjuntor por provedor, rotação aleatória de chaves (com cooldown sensível a quota), recursos de enriquecimento web em tempo real e implementa uma API compatível com OpenAI sobre uma Clean Architecture rigorosa (Domain -> Services -> Adapters -> API).

• Versão: 1.3.0 (pyproject.toml)
• Python: 3.10+
• Ponto de entrada de execução: python main.py
• UI integrada: http://localhost:8000/ui
• Endpoint compatível com OpenAI: POST /v1/chat/completions

Especificação técnica do HydraLLM (SPEC)

1. Visão geral

O HydraLLM é um gateway de LLM de alta disponibilidade que segue a Clean Architecture. Ele oferece roteamento inteligente entre múltiplos provedores, isolamento de falhas com base em circuit breaker, recursos de enriquecimento web em tempo real e suporte completo à especificação da API da OpenAI.

2. Especificação dos componentes principais

2.1 Gateway (src/services/gateway.py)

• Orquestração: coordena o fluxo de carregamento de sessão -> análise de contexto -> enriquecimento web -> execução resiliente -> persistência.
• Motivos técnicos de roteamento: inclui em todas as respostas a base da tomada de decisão com constantes claras.
  • USER_HINT: especificação explícita do usuário
  • TOKEN_OPTIMIZED: otimização baseada na quantidade de tokens
  • WEB_INTENT_SEARCH: resultado da análise de intenção de busca na web
  • MULTIMODAL_ANALYSIS: detecção da necessidade de processamento de imagem
  • KEY_AVAILABILITY: estado das chaves e resultado do failover

2.2 Analisador de Contexto (src/services/analyzer.py)

• Algoritmo de roteamento: analisa comprimento de tokens, natureza multimodal e intenção de busca na web para gerar a RoutingDecision ideal.
• Filtragem dinâmica de disponibilidade: reflete o estado em tempo real do KeyManager e exclui das opções os modelos de provedores sem chaves ativas.

2.3 Gerenciador de Chaves (src/services/key_manager.py)

• Rotação de chaves: seleção aleatória dentro do pool de chaves ativas e rastreamento de uso.
• Gerenciamento de falhas: aplica cooldown diferenciado por tipo de erro.
  • 403 Forbidden: 24 horas (resposta a falha permanente no nível da chave)
  • 429 Rate Limit / Quota: 1 hora
  • Outros erros de comunicação: 5 minutos

2.4 Serviço de Contexto Web (src/services/web_context_service.py)

• Enriquecimento de dados: coleta informações em tempo real com base em Playwright/Scrapling e injeta isso no prompt.
• Rastreamento de desempenho: registra taxa de sucesso, quantidade de caracteres coletados e latência por meio da tabela scraping_metrics.

3. Padrões de resiliência e recuperação (Troubleshooting Insights)

• Concurrency Guard: aplica asyncio.Lock e threading.Lock às operações de escrita do KeyManager e do SessionManager para garantir a integridade dos dados sob alta carga.
• Self-Healing Scraper: aciona um mecanismo de reinicialização automática ao detectar falha de instância do navegador.
• Unpacking Guard: segue tipos de retorno estritos (tuple[list, str | None]) e proteções para evitar erros de NoneType que podem ocorrer ao processar dados enriquecidos.