# Intégration OpenRouter — Immbot AI

# Architecture

Navigateur ──(SSE, sans clé)── Next.js API ──(Bearer OPENROUTER_API_KEY)── openrouter.ai/api/v1

La clé ne quitte jamais le serveur (lib/openrouter/client.ts, registry.ts).

# Registre dynamique (lib/openrouter/registry.ts)

• GET /models → normalisation (prix $/M jetons, modalités d'entrée, supported_parameters) → cache mémoire 15 min (l'ancien cache sert de secours si l'API échoue).
• Capacités détectées : images, fichiers, outils, raisonnement, sortie structurée, contexte max.
• Palier de coût calculé (économique < 1 $/M pondéré ≤ modéré < 8 $/M ≤ coûteux) — les étudiants voient le palier, l'admin voit les prix exacts.
• Surcharges admin (model_overrides) : activer/désactiver, favori, note. Un modèle désactivé est refusé côté serveur même si le client force son id.
• Préréglages configurables (settings.model_presets) avec repli ordonné : le premier modèle disponible et activé de la liste est utilisé (resolvePreset).

# Appels de complétion (lib/openrouter/client.ts)

• streamChat : SSE (stream: true, usage: {include: true}) relayé événement par événement au navigateur ; supporte models: [principal, ...secours] pour le repli fournisseur d'OpenRouter.
• completeChat : non-streaming, response_format: json_object pour les générateurs (quiz, flashcards, résumés).
• Multimodal : messages content[] avec image_url (data-URL base64) pour les images ; les documents texte (PDF/DOCX/XLSX extraits localement) sont injectés comme texte délimité.

# Suivi des coûts

Chaque appel journalise jetons entrée/sortie, coût estimé (prix du registre × jetons), latence, succès/erreur (usage_log). Budgets appliqués avant chaque appel (lib/usage.ts) : par étudiant/jour, étudiant/mois, global/mois, requêtes/jour — configurables dans l'admin.

# Choix des modèles par tâche

# Limites connues

• OpenRouter n'offre pas d'endpoint d'embeddings → embeddings locaux (voir rag-architecture.md).
• Les prix du registre sont indicatifs ; le coût facturé exact est visible dans le tableau de bord OpenRouter (l'endpoint /generation par requête est une évolution possible).