2. Communication Gemini & Authentification

Cette section détaille les protocoles et mécanismes de sécurité permettant à ECHO d'interagir avec l'API de Google Gemini de manière structurée.

Mécanismes d'Authentification API

Pour communiquer avec les modèles de Google (Gemini), le Framework s'appuie sur une architecture multi-provider. Cette conception garantit la connectivité via différentes méthodes d'accès, selon le contexte (Local ou Cloud).

• Résolution Multi-Provider : L'authentification est priorisée au sein du module EchoAuth.get_ordered_auth_providers(). Le système tente en priorité de s'authentifier par OAuth2, puis bascule sur les clés API statiques si l'OAuth2 n'est pas configuré.
• Le protocole d'authentification PKCE : ECHO utilise le flux Authorization Code + PKCE (RFC 7636) pour l'authentification OAuth2 headless dans Docker. PKCE (Proof Key for Code Exchange) est une extension du flux OAuth2 empêchant l'interception du code d'autorisation. Il génère une paire de secrets éphémères (code_verifier et code_challenge) à usage unique.
• Clés API : En solution de repli (ou par choix utilisateur), de simples clés API AI Studio (commençant par AIza…) peuvent être définies dans l'interface et utilisées directement.

En pratique pour l'OAuth2 : lorsqu'aucun fournisseur d'accès n'est configuré et qu'aucune clé API n'est fournie, le Pipe déclenche le flux PKCE automatiquement au premier message. Un tunnel SSH éphémère (asyncssh) est ouvert sur un port dynamique de la plage 8020–8024, et le callback OAuth2 est reçu sur un port interne (8025–8034). L'utilisateur reçoit un lien cliquable dans l'interface et n'a qu'à autoriser ECHO sur son compte Google pour récupérer ses identifiants.

Méthodes Factorisées d'Appel (EchoGeminiClient)

Le framework centralise toutes les communications sortantes vers les modèles de langage au sein du module EchoGeminiClient. Ce client HTTP/2 asynchrone orchestre le routage, la résilience et la mise en forme canonique des requêtes.

• Routage Transparent : Le client bascule dynamiquement entre l'API publique (AI Studio) et l'API interne (Antigravity) selon l'identité d'accès prioritaire, en appliquant les traductions de noms de modèles nécessaires.
• Failover Hybride et Résilience : En cas de surcharge (HTTP 429, 500, 503), le client applique un backoff exponentiel avec jitter. Si le seuil d'échecs consécutifs est franchi, il bascule automatiquement sur la source d'accès suivante (par exemple, d'OAuth2 vers la clé de secours). Si le modèle lui-même est inaccessible, une cascade descendante (PRO → FLASH → LITE) est enclenchée.
• Statut Tri-état : Chaque appel LLM, qu'il provienne du Pipe ou d'un outil agentique, renvoie un statut standardisé (success, warning, error). Une divergence (clamping de politique ou cascade) est marquée comme warning avec le détail du motif.

# 1. Préparation du contexte réseau (HTTP/2, Headers furtifs, Auth)
req_ctx = await EchoGeminiClient._prepare_request_context(
    provider=active_provider,
    target_model="gemini-3.5-flash",
    payload={"contents": [...]},
    method="streamGenerateContent",
    chat_id=chat_id,
    enable_paid_credits=True
)

# 2. Appel Centralisé avec Cascade Cognitive (PRO -> FLASH -> LITE)
data, model_key, reason = await EchoGeminiClient.call_cascade(
    target_model_key="MODEL_FLASH", 
    payload=payload,
    user_id=user_id,
    metadata=__metadata__,
    events=events,
    include_thoughts=False
)

# Analyse du statut tri-état
if reason:
    status = "warning"  # Ex: "policy clamping" ou "cascade downgrade"
else:
    status = "success"