HydraLLM : orchestrateur intelligent

HydraLLM : orchestrateur intelligent

HydraLLM est une passerelle context-aware conçue pour exploiter efficacement plusieurs ressources LLM. Elle route les requêtes entre Gemini / Groq / Cerebras, fournit des circuit breakers par fournisseur, une rotation aléatoire des clés (avec cooldown tenant compte des quotas), des capacités d’enrichissement web en temps réel, et met en place une API compatible OpenAI sur une Clean Architecture stricte (Domain puis Services puis Adapters puis API).

• Version : 1.3.0 (pyproject.toml)
• Python : 3.10+
• Point d’entrée d’exécution : python main.py
• UI intégrée : http://localhost:8000/ui
• Endpoint compatible OpenAI : POST /v1/chat/completions

Spécification technique de HydraLLM (SPEC)

1. Vue d’ensemble

HydraLLM est une passerelle LLM haute disponibilité conforme à la Clean Architecture. Elle fournit un routage intelligent entre plusieurs fournisseurs, une isolation des pannes basée sur des circuit breakers, des fonctions d’enrichissement web en temps réel, et prend entièrement en charge la spécification de l’API OpenAI.

2. Spécification des composants principaux

2.1 Gateway (src/services/gateway.py)

• Orchestration : coordonne le flux chargement de session -> analyse du contexte -> enrichissement web -> exécution résiliente -> persistance.
• Motifs techniques de routage : inclut dans chaque réponse les bases de décision sous forme de constantes explicites.
  • USER_HINT : désignation explicite par l’utilisateur
  • TOKEN_OPTIMIZED : optimisation basée sur le nombre de tokens
  • WEB_INTENT_SEARCH : résultat de l’analyse d’intention de recherche web
  • MULTIMODAL_ANALYSIS : détection du besoin de traitement d’image
  • KEY_AVAILABILITY : état des clés et résultat du failover

2.2 Context Analyzer (src/services/analyzer.py)

• Algorithme de routage : analyse la longueur en tokens, le caractère multimodal et l’intention de recherche web afin de produire la RoutingDecision optimale.
• Filtrage dynamique de disponibilité : reflète l’état en temps réel du KeyManager pour exclure des choix les modèles des fournisseurs qui n’ont aucune clé active.

2.3 Key Manager (src/services/key_manager.py)

• Rotation des clés : sélection aléatoire dans le pool de clés actives et suivi de l’utilisation.
• Gestion des incidents : applique des cooldowns différenciés selon le type d’erreur.
  • 403 Forbidden : 24 heures (gestion des pannes permanentes au niveau de la clé)
  • 429 Rate Limit / Quota : 1 heure
  • autres erreurs de communication : 5 minutes

2.4 Web Context Service (src/services/web_context_service.py)

• Enrichissement des données : collecte d’informations en temps réel basée sur Playwright/Scrapling et injection dans le prompt.
• Suivi des performances : enregistre le taux de succès, le nombre de caractères collectés et la latence via la table scraping_metrics.

3. Résilience et schémas de récupération (Troubleshooting Insights)

• Concurrency Guard : applique asyncio.Lock et threading.Lock aux opérations d’écriture de KeyManager et SessionManager afin de garantir l’intégrité des données sous forte charge.
• Self-Healing Scraper : déclenche un mécanisme de redémarrage automatique lors de la détection d’un crash d’instance navigateur.
• Unpacking Guard : respecte un type de retour strict (tuple[list, str | None]) et des garde-fous pour prévenir les erreurs NoneType pouvant survenir pendant le traitement des données enrichies.