Documentation — IA

Assistant conversationnel (Qwen par défaut via Ollama). Contexte des modules Wiki et Documents. Historique des conversations, sélection des modules pour le contexte.

Les modules Blueprint Modular font partie de l'application Next.js. Il n'y a pas de package séparé par module (pas de pip install blueprint-modular-ia ni npm install blueprint-modular-ia) : on installe l'application une fois, puis on configure la base PostgreSQL et le serveur Ollama (ou Anthropic) pour l'assistant. Cette documentation décrit comment le module IA fonctionne, comment l'installer (application, base de données, serveur Ollama et modèle), comment choisir le modèle (Qwen, Mistral, Claude), les lignes de commande pour installer l'assistant IA et toutes ses dépendances (Node, Prisma, Ollama, Qwen ou Mistral), les lignes de code pour charger et utiliser le module (API, composant AIChat), et la gestion des $ dans la zone de saisie pour référencer les modules (Wiki, Documents, etc.) dans vos questions.

Comment fonctionne le module IA

Le module IA fournit un assistant conversationnel intégré à l'app. Par défaut, les réponses sont générées par un modèle local via Ollama (ex. Qwen3 8B). Le contexte envoyé au modèle peut inclure les données des modules Wiki et Documents : titres et contenu des articles wiki récents, liste des documents uploadés et métadonnées. L'utilisateur choisit quels modules activer dans le panneau de contexte ; le client construit alors un bloc de texte à partir du registry des modules et l'envoie en context_from_modules à l'API. L'historique des conversations est sauvegardé en base (AiConversation, AiMessage) ; chaque discussion peut être reprise, supprimée ou dupliquée.

  • Providers : Qwen et Mistral via Ollama ; Claude (Anthropic) si ANTHROPIC_API_KEY est défini. Seuls ces providers sont implémentés.
  • Transcription vocale (Whisper) : un bouton Micro dans la zone de saisie permet de dicter la question au lieu de la taper. L'audio est envoyé à POST /api/wiki/transcribe (micro-service Whisper sur le VPS, port 9000) ; le texte transcrit est inséré dans la zone de saisie. Même service que pour le Wiki (nouvel article par dictée).
  • Streaming : les réponses sont streamées (Server-Sent Events) pour affichage progressif.
  • Prompts : le prompt système (lib/ai/prompt-templates) précise le rôle de l'assistant (Blueprint Modular, français, pas de calcul ni d'hypothèses). Si un contexte modules est fourni, il est injecté dans le prompt système.

Implémentation (côté app)

Le module IA repose sur : (1) la route API POST /api/ai/chat qui reçoit le message, l'historique et le contexte modules, appelle le client Ollama ou Anthropic, et stream la réponse ; (2) le client lib/ai/vllm-client.ts qui envoie les requêtes à Ollama (/api/chat en streaming) ; (3) le module registry (lib/ai/module-registry.ts) dans lequel Wiki et Documents s'enregistrent au chargement de l'app (ModuleRegistryInit) ; (4) le composant AIChat qui gère la saisie, l'autocomplétion des tokens $, l'envoi des messages et l'affichage du flux. Les conversations sont persistées via saveConversationTurn dans l'API après chaque réponse complète.

Lignes de code pour charger et utiliser le module IA

Charger le module :

Le module IA est intégré à l'application Next.js ; il n'y a pas de import ou de script à exécuter pour le « charger » séparément. Au démarrage de l'app, le module registry est initialisé (ModuleRegistryInit) et enregistre les modules Wiki, Documents, etc. ; l'assistant IA consomme ce registry pour construire le contexte. Assurez-vous que les routes API (/api/ai/chat, /api/ai/conversations, etc.) et le schéma Prisma (AiConversation, AiMessage) sont en place — ce qui est le cas après prisma migrate deploy.

Utiliser le module :

Depuis l'interface : ouvrez la page /modules/ia. Vous pouvez envoyer des messages, sélectionner les modules (Wiki, Documents) dans le panneau de contexte pour inclure leur contenu dans le contexte envoyé au modèle, taper $ dans la zone de saisie pour insérer des références ($wiki, $doc), et consulter ou reprendre l'historique des conversations. Depuis du code : appelez POST /api/ai/chat avec message, provider_name, conversation_history, discussion_id (optionnel), context_from_modules (texte construit côté client à partir du module registry). Voir l'exemple d'appel côté client plus bas.

Installation du module IA et dépendances

Le module IA fait partie de l'application Next.js. Aucun package séparé n'est requis pour l'UI ; en revanche, pour des réponses réelles (hors mock), il faut un serveur Ollama (ou une clé Anthropic pour Claude). Les dépendances Node sont déjà dans le projet (@anthropic-ai/sdk pour Claude ; pas de SDK OpenAI pour l'instant, Ollama utilise l'API HTTP).

1. Installer l'application

npm install
npx prisma generate --schema=prisma/schema.prisma
npx prisma migrate deploy

Les modèles Prisma AiConversation et AiMessage sont créés par les migrations. DATABASE_URL doit être défini dans .env. Pour la liste des structures BDD et prérequis production par module, voir docs/DATABASE.md dans le dépôt.

2. Installer et lancer Ollama (modèle Qwen ou Mistral)

# Installer Ollama : https://ollama.com/download

# Lancer le serveur et télécharger le modèle :
ollama serve
ollama pull qwen3:8b

# Optionnel — autre modèle :
ollama pull mistral:7b

Par défaut, l'app utilise AI_SERVER_URL=http://localhost:11434. En dev sans serveur, définir AI_MOCK=true pour des réponses mockées.

3. (Optionnel) Claude (Anthropic)

Pour utiliser Claude comme provider, définir ANTHROPIC_API_KEY dans .env. L'API chat détecte le provider demandé (vllm, qwen, mistral, claude) et appelle soit Ollama soit Anthropic.

Résumé des commandes (installer le module IA et toutes les dépendances)

Enchaînement complet pour avoir l'assistant IA opérationnel (app + base + Ollama + modèle) :

# 1. Dépendances Node et schéma Prisma
npm install
npx prisma generate --schema=prisma/schema.prisma

# 2. Base PostgreSQL
npx prisma migrate deploy

# 3. Serveur Ollama (terminal dédié ou arrière-plan)
ollama serve
ollama pull qwen3:8b

# 4. Lancer l'app
npm run dev

# 5. Ouvrir l'assistant IA
# http://localhost:3000/modules/ia

Définir dans .env : DATABASE_URL, NEXTAUTH_SECRET, NEXTAUTH_URL, AI_SERVER_URL (ex. http://localhost:11434), AI_MODEL (ex. qwen3:8b). Sans Ollama : AI_MOCK=true pour des réponses simulées.

Comment choisir le modèle

L'assistant peut utiliser plusieurs providers. Le choix se fait dans l'interface (sélecteur de modèle) et/ou via les variables d'environnement.

  • Ollama (Qwen, Mistral) : par défaut, l'app utilise le modèle configuré dans AI_MODEL (ex. qwen3:8b). Pour Qwen et Mistral spécifiquement, vous pouvez définir AI_MODEL_QWEN et AI_MODEL_MISTRAL. Téléchargez le modèle avec ollama pull qwen3:8b ou ollama pull mistral:7b, puis sélectionnez le provider correspondant dans l'UI.
  • Claude (Anthropic) : définissez ANTHROPIC_API_KEY dans .env. Le provider « claude » devient disponible dans l'assistant ; les requêtes sont envoyées à l'API Anthropic au lieu d'Ollama.
  • Mock : en développement sans serveur, AI_MOCK=true désactive les appels réels et renvoie une réponse factice (utile pour tester l'UI).

Variables d'environnement

  • AI_SERVER_URL — URL du serveur Ollama (ex. http://localhost:11434 ou http://vps:11434).
  • AI_MODEL — Modèle Ollama par défaut (ex. qwen3:8b).
  • AI_MODEL_QWEN, AI_MODEL_MISTRAL — Override par provider si besoin.
  • AI_MOCK — true pour désactiver les appels réels et renvoyer des réponses mockées (dév).
  • AI_TIMEOUT — Délai max en secondes (ex. 120).
  • AI_MAX_RETRIES — Nombre de tentatives en cas d'erreur réseau.
  • ANTHROPIC_API_KEY — Clé API Anthropic pour le provider Claude.

Gestion des $ dans l'assistant (références aux modules)

Dans le champ de saisie de l'assistant IA, taper un $ affiche une liste de suggestions de tokens ($wiki, $doc, $metric, etc.). Ces tokens servent à l'autocomplétion : en sélectionnant un token, vous l'insérez dans le message. Ils n'injectent pas le contenu des modules à la place du $ ; ils rappellent quels types de données peuvent être inclus. Le contenu effectif (articles wiki, documents) est injecté dans le contexte envoyé au modèle lorsque les modules correspondants sont sélectionnés dans le panneau de contexte (Module Registry). En résumé : le $ permet de compléter rapidement une référence dans le texte ; la sélection des modules (Wiki, Documents) dans le panneau détermine ce qui est envoyé au modèle comme contexte.

Comment utiliser le $ dans l'assistant :

  1. Ouvrez l'assistant IA (page /modules/ia).
  2. Dans le panneau de contexte, cochez les modules dont vous voulez inclure le contenu (ex. Wiki, Documents) ; le texte de contexte sera construit et envoyé avec votre message.
  3. Dans la zone de saisie, tapez $ : une liste de tokens s'affiche ($wiki, $doc, $metric, etc.). Sélectionnez un token pour l'insérer dans votre message (ex. « Résume $wiki »).
  4. Le token $wiki (ou autre) dans le message est un rappel ; le contenu réel des articles ou documents est ajouté au contexte grâce aux cases cochées dans le panneau. Envoyez le message ; l'IA répond en s'appuyant sur le contexte fourni.

Tokens disponibles :

  • $wiki — Wiki (articles).
  • $doc — Documents (analyses, contrats).
  • $metric — Métriques (dashboard).
  • $table, $chart, $data — Références données (étendues possibles).

Où sont sauvegardées les conversations

Les conversations sont stockées en base PostgreSQL : table AiConversation (id, userId, preview, createdAt, updatedAt) et table AiMessage (id, conversationId, userMessage, aiResponse, providerName, createdAt). Chaque tour de dialogue est enregistré après la fin du streaming. L'historique est chargé via GET /api/ai/conversations et affiché dans le panneau latéral ; une discussion peut être supprimée via DELETE /api/ai/conversations/[id].

API du module IA (résumé)

  • POST /api/ai/chat — Envoyer un message et recevoir un stream de réponses. Body : message, provider_name (vllm, qwen, mistral, claude), conversation_history, discussion_id, context_from_modules (texte construit côté client depuis le module registry). Réponse : SSE avec type: chunk | done | error, discussion_id dans done.
  • GET /api/ai/conversations — Liste des conversations de l'utilisateur (preview, messages).
  • POST /api/ai/conversations — Créer une nouvelle conversation (retourne l'id).
  • DELETE /api/ai/conversations/[id] — Supprimer une conversation.
  • GET /api/ai/conversations/[id]/messages — Détail des messages d'une conversation (si exposé).
  • GET /api/ai/health — Santé du serveur Ollama (disponibilité, latence).
  • GET /api/ai/providers — Liste des providers (vllm, qwen, mistral, claude, etc.) et indicateur de configuration (ex. ANTHROPIC_API_KEY pour Claude).
  • POST /api/wiki/transcribe — Transcription vocale (Whisper). Utilisée par le bouton Micro de la zone de saisie IA et par le Wiki (nouvel article par dictée). Body : multipart/form-data avec champ audio (fichier webm/mp4). Réponse : { transcription: string }. Prérequis : micro-service Whisper démarré (ex. port 9000, variable WHISPER_SERVICE_URL dans .env).

Exemple d'appel côté client (contexte modules)

// Le composant AIChat récupère le contexte des modules sélectionnés puis appelle l'API :
const moduleIds = moduleRegistry.getAllModules().map((m) => m.moduleId);
const { text: contextFromModules } = await moduleRegistry.buildContext(moduleIds);

const res = await fetch("/api/ai/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    message: userMessage,
    provider_name: "vllm",
    conversation_history: recentMessages,
    discussion_id: currentDiscussionId ?? undefined,
    context_from_modules: contextFromModules?.trim() || undefined,
  }),
  credentials: "include",
});