spb/immbot-ai

1# API — Immbot AI23Toutes les routes sont sous `/api`. Auth par cookie de session httpOnly. Les mutations exigent la4même origine (défense CSRF) et renvoient `{error}` avec le statut HTTP approprié en cas d'échec.56## Authentification7| Route | Méthode | Corps / retour |8|---|---|---|9| `/auth/login` | POST | `{username, password}` → `{ok, mustChangePassword, role}` (429 après 8 échecs/15 min) |10| `/auth/register` | POST | `{username, displayName, email?, password, accessCode?, courses[]}` |11| `/auth/change-password` | POST | `{currentPassword, newPassword}` — révoque puis recrée la session |12| `/auth/logout` | POST | — |1314## Chat15| Route | Méthode | Détail |16|---|---|---|17| `/chat` | POST | `{conversationId?, courseCode, message, model, mode, knowledgeMode, attachmentIds[], crossCourse?, regenerateOfMessageId?}` → **SSE** : `meta` (ids), `delta` (texte), `error`, `done` (contenu final, citations résolues, jetons, palier de coût, citations invalides neutralisées) |18| `/models` | GET | Modèles activés (capacités, palier de coût) + préréglages |19| `/conversations` | GET | Liste (`?q=` recherche, `?archived=1`) |20| `/conversations/[id]` | GET/PATCH/DELETE | Fil complet / renommer, dossier, épingler, archiver / supprimer |21| `/conversations/[id]/branch` | POST | `{upToMessageId}` → nouvelle conversation |22| `/messages/[id]` | PATCH | `{feedback?, flag?, flagReason?, save?}` |23| `/citations/[chunkId]` | GET | Panneau source (extrait, voisins) — contrôle d'accès par espace |24| `/uploads` | POST | multipart `file` (+`conversationId`) — types vérifiés par signature, texte extrait, indexé dans l'espace étudiant |25| `/announcements` | GET | Annonces actives des cours de l'utilisateur |2627## Apprentissage (inscription au cours vérifiée partout)28| Route | Méthode | Détail |29|---|---|---|30| `/learning/[course]/overview` | GET | Maîtrise, série, stats, recommandations justifiées |31| `/learning/[course]/concepts` | GET | Nœuds (maîtrise, compteurs) + liens typés |32| `/learning/[course]/flashcards` | GET/POST | File dues+nouvelles / `create` ou `generate` (IA, RAG) |33| `/learning/flashcards/review` | POST | `{cardId, q:2-5, suspend?, favorite?}` — SM-2 + maîtrise |34| `/learning/quiz` | POST | actions `start` / `answer` (correction serveur + cahier d'erreurs) / `next` (adaptatif) / `finish` |35| `/learning/exams` | GET/POST | Liste+tentatives / `start`, `submit` (correction, analyse par concept et axe) |36| `/learning/[course]/plan` | GET/POST | Plan actif / `create` (génération), `toggle` (cocher) |37| `/learning/errors` | GET/PATCH | Cahier d'erreurs / statut ou suppression |38| `/learning/[course]/summaries` | GET/POST | Résumés / génération (scope semaine/concept/examen, style) avec citations validées |39| `/library` | GET/POST/DELETE | Bibliothèque personnelle |4041## Administration (rôle instructor/admin ; admin pour les mutations sensibles)42| Route | Méthode | Détail |43|---|---|---|44| `/admin/overview` | GET | Usage, coûts (jour/mois/série 14 j), erreurs, santé |45| `/admin/models` | GET/POST | Registre complet (prix) / `override` (activer, favori, note), `presets` |46| `/admin/ingest` | GET/POST | Runs + documents / relance (`?force=1`) |47| `/admin/prompts` | GET/POST | Noms, contenu+historique (`?name=`) / nouvelle version |48| `/admin/announcements` | GET/POST | CRUD (`create/update/delete`) |49| `/admin/users` | GET/PATCH | Utilisateurs+journal / rôle, désactivation, reset (mot de passe temporaire), cours, sessions |50| `/admin/pedagogy` | GET | Agrégats anonymisés (seuil 3 étudiants), questions difficiles, signalements |51| `/admin/settings` | GET/POST | Budgets, intégrité, croisement inter-cours, partage |5253## Mode « Cours interactif » et outils (function calling)5455Quand le modèle choisi supporte les outils, le chat lui expose :56- **Outils de cours** (tous les modes sauf Général ; accès direct SANS base vectorielle) :57  `lister_seances`, `plan_seance` (sections + titres des diapositives), `lire_diapositives`58  (contenu complet d'une plage, max 12), `rechercher_cours` (FTS5). Tout contenu servi reçoit une59  balise `[Sx]` enregistrée dans le contexte → citations validées comme d'habitude.60- **Outils Web** (modes Cours interactif / Cours + général / Général, si `EXA_API_KEY` /61  `FIRECRAWL_API_KEY` sont configurées) : `recherche_web` (Exa) et `lire_page_web` (Firecrawl,62  Markdown). Les sources Web sont attribuées par URL, jamais mélangées aux citations de cours.6364Le mode de connaissances `course-tools` (« Cours interactif ») part SANS extraits pré-récupérés :65le modèle explore lui-même (max 5 tours d'outils). Le flux SSE émet `{type:"tool", name, label}`66à chaque appel — affiché en direct dans l'interface — et `done` inclut `toolTrace` (persisté dans67`messages.tool_trace`).68