goblin-agents 2.4.0 → 2.4.2

package/README.md

@@ -1,8 +1,8 @@
-# 📘 Documentation du module goblin-agents
+# 📘 goblin-agents
 
 ## Aperçu
 
-Le module `goblin-agents` fournit une infrastructure complète pour intégrer des agents d'intelligence artificielle (IA) dans l'écosystème Xcraft. Il permet de créer, configurer et interagir avec différents modèles de langage (LLM) via des fournisseurs comme Ollama et OpenAI. Ce module est conçu pour faciliter l'utilisation d'agents IA dans diverses applications, en offrant des fonctionnalités avancées comme la gestion de conversations, l'analyse de documents PDF, et l'utilisation d'outils externes.
+Le module `goblin-agents` fournit une infrastructure complète pour intégrer des agents d'intelligence artificielle (IA) dans l'écosystème Xcraft. Il permet de créer, configurer et interagir avec différents modèles de langage (LLM) via des fournisseurs comme Ollama et OpenAI/OpenRouter. Ce module facilite l'utilisation d'agents IA dans diverses applications en offrant des fonctionnalités avancées : gestion de conversations multi-contextes, analyse de documents PDF par OCR, génération d'embeddings vectoriels pour la recherche sémantique, utilisation d'outils externes, journalisation HTML des échanges, et support du paradigme ReAct pour des agents autonomes.
 
 ## Sommaire
 
@@ -15,28 +15,48 @@ Le module `goblin-agents` fournit une infrastructure complète pour intégrer de
 
 ## Structure du module
 
-- **AiAgent** : Acteur principal qui encapsule un agent IA et ses fonctionnalités
-- **Providers** : Classes pour interagir avec différents fournisseurs de LLM (Ollama, OpenAI)
-- **Utilitaires** : Fonctions pour le traitement de texte, l'OCR, et la manipulation de documents
+Le module est organisé autour du pattern Elf Archetype, avec une séparation claire entre la logique métier et l'interface de l'acteur :
 
-Le module est organisé autour du pattern Elf, avec une séparation claire entre la logique métier (`AiAgentLogic`) et l'interface de l'acteur (`AiAgent`).
+- **`AiAgent`** : Acteur principal persisté (Elf.Archetype) qui encapsule un agent IA et expose ses fonctionnalités sur le bus Xcraft
+- **`AiAgentLogic`** : Logique de mutation d'état de l'acteur (pattern Redux)
+- **`LLMProviders`** : Registre et classes concrètes pour interagir avec différents fournisseurs LLM (Ollama, OpenAI)
+- **`Logger`** : Système de journalisation HTML des échanges IA par session
+- **Utilitaires** : Fonctions pour le traitement de texte, HTML, OCR, découpage de chunks et embeddings
 
 ## Fonctionnement global
 
-Le module `goblin-agents` permet de créer et gérer des agents IA qui peuvent interagir avec les utilisateurs via des conversations textuelles. Chaque agent est configuré avec un modèle spécifique, un fournisseur (Ollama ou OpenAI), et des paramètres qui définissent son comportement.
+Chaque agent est configuré avec un modèle spécifique, un fournisseur LLM, un prompt système et des paramètres qui définissent son comportement. Les agents peuvent maintenir plusieurs **contextes de conversation** simultanément via un `contextId`, chaque contexte conservant son propre historique de messages.
 
-Les agents peuvent maintenir plusieurs contextes de conversation simultanément, ce qui permet d'avoir des conversations distinctes avec différents utilisateurs ou sur différents sujets. Chaque contexte conserve son propre historique de messages, ce qui permet à l'agent de maintenir la cohérence dans ses réponses.
+Le flux général d'utilisation d'un agent :
 
-Le module prend en charge diverses fonctionnalités avancées :
+```
+[Création/chargement de l'agent]
+        ↓
+[Configuration : provider, model, prompt, tools, options]
+        ↓
+[Appel de méthodes : chat, gen, embed, ask, react...]
+        ↓
+[Le provider LLM (Ollama ou OpenAI) traite la requête]
+        ↓
+[La réponse est stockée dans l'historique du contexte]
+        ↓
+[Persistance optionnelle via save()]
+```
+
+Un **mutex par agent** garantit la sérialisation des requêtes simultanées sur le même agent. Chaque échange peut être journalisé dans un fichier HTML de rapport via le `Logger`.
+
+Le module supporte plusieurs modes d'interaction :
+
+- **Génération simple** (`gen`) : prompt → réponse sans historique
+- **Chat conversationnel** (`chat`) : avec historique de contexte, appels d'outils optionnels
+- **Streaming** (`ask`) : réponse en flux temps réel via événements Xcraft (Ollama uniquement)
+- **Vision/OCR** (`vision`, `readPDFpages`) : analyse d'images et de PDFs
+- **Embeddings** (`embed`, `embedInBatch`) : vectorisation pour la recherche sémantique
+- **ReAct** (`react`) : raisonnement et action autonomes avec orchestration multi-agents
 
-- Génération de texte à partir de prompts
-- Conversations interactives avec historique
-- Extraction de texte à partir d'images de documents PDF
-- Génération d'embeddings vectoriels pour la recherche sémantique
-- Utilisation d'outils externes via un système d'appels d'outils
-- Paradigme ReAct (Reasoning and Acting) pour des agents plus autonomes
+### Gestion de version des agents
 
-Les agents peuvent être configurés avec une grande variété d'options qui influencent leur comportement, comme la température (créativité), la taille du contexte, et diverses pénalités pour éviter les répétitions.
+La méthode `beforePersistOnServer` protège contre les régressions de version : si un client tente de persister un agent avec une version différente de celle configurée dans `goblin-agents`, les données du serveur sont restaurées depuis le dernier état persisté (`cryo`).
 
 ## Exemples d'utilisation
 
@@ -49,33 +69,27 @@ const {AiAgent} = require('goblin-agents/lib/llm/aiAgent.js');
 async initAgents() {
   const feedId = await this.newQuestFeed();
 
-  // Création d'un agent avec Ollama (local)
-  const ollamaAgentId = 'aiAgent@ollama-mistral-assistant';
-  const agent = await new AiAgent(this).create(ollamaAgentId, feedId, {
+  // Agent local via Ollama
+  const agent = await new AiAgent(this).create('aiAgent@mistral-assistant', feedId, {
     name: 'Assistant Personnel',
     role: 'assistant',
     prompt: 'Tu es un assistant personnel serviable et précis.',
     provider: 'ollama',
     model: 'mistral-small',
     host: 'http://127.0.0.1:11434',
-    options: {
-      temperature: 0.7
-    },
-    usability: 'stable'
+    options: {temperature: 0.7},
+    usability: 'stable',
   });
 
-  // Création d'un agent avec OpenAI (cloud)
-  const openAiAgentId = 'aiAgent@gpt-4o-assistant';
-  const cloudAgent = await new AiAgent(this).create(openAiAgentId, feedId, {
-    name: 'Assistant Personnel',
+  // Agent cloud via OpenRouter
+  const cloudAgent = await new AiAgent(this).create('aiAgent@gpt4o-assistant', feedId, {
+    name: 'Assistant GPT-4o',
     role: 'assistant',
     provider: 'open-ai',
     model: 'openai/gpt-4o',
     host: 'https://openrouter.ai/api/v1',
-    headers: {
-      Authorization: `Bearer <votre-clef-api>`,
-    },
-    usability: 'stable'
+    headers: {Authorization: `Bearer <votre-clef-api>`},
+    usability: 'stable',
   });
 }
 ```
@@ -83,19 +97,14 @@ async initAgents() {
 ### Conversation avec un agent
 
 ```javascript
-// Dans une méthode d'un acteur Elf
 async askAgent(desktopId, agentId, contextId, question, saveExchange = false) {
   const feedId = await this.newQuestFeed();
-
-  // Instancie l'agent approprié par ex. 'aiAgent@gpt-4o-assistant'
   const agent = await new AiAgent(this).create(agentId, feedId);
 
-  // Continue la conversation sur ce contexte par ex. 'story-xyz' et
-  // obtient une réponse à la question de l'utilisateur
+  // Conversation avec historique sur le contexte 'story-xyz'
   const response = await agent.chat(contextId, question, desktopId);
 
-  if(saveExchange) {
-    //Persiste l'échange contextuel nouvelle paire (question->réponse) sur le disque
+  if (saveExchange) {
     await agent.save();
   }
   return response;
@@ -105,258 +114,263 @@ async askAgent(desktopId, agentId, contextId, question, saveExchange = false) {
 ### Utilisation d'outils externes
 
 ```javascript
-// Dans une méthode d'un acteur Elf
-async addWeatherToolSupportToAgent(agentId) {
+async addWeatherToolToAgent(agentId, contextId, desktopId) {
   const feedId = await this.newQuestFeed();
-
-  // Instancie l'agent approprié par ex. 'aiAgent@gpt-4o-assistant'
   const agent = await new AiAgent(this).create(agentId, feedId);
 
-  // Configurer un agent avec des outils
-  // Provoquera des envois de commandes sur le bus à l'acteur "weather"
-  // en appelant la quête "getWeather(city)"
   await agent.patch({
-    toolServiceId: 'weather', //acteur (ici le singleton weather) qui expose des quêtes "outils"
+    toolServiceId: 'weather', // acteur singleton qui expose les quêtes "outils"
     tools: [
       {
         type: 'function',
         function: {
-          name: 'getWeather', //nom de la quête de l'acteur qui récupère la météo
+          name: 'getWeather',
           description: 'Obtenir la météo pour une ville',
           parameters: {
             type: 'object',
             properties: {
-              city: {
-                type: 'string',
-                description: 'Nom de la ville'
-              }
+              city: {type: 'string', description: 'Nom de la ville'},
             },
-            required: ['city']
-          }
-        }
-      }
-    ]
+            required: ['city'],
+          },
+        },
+      },
+    ],
   });
 
-  // L'agent pourra maintenant utiliser l'outil weather.getWeather
-  const question = "Quel temps fait-il à Paris aujourd'hui?";
-  const response = await agent.chat(contextId, question, desktopId);
+  const response = await agent.chat(contextId, "Quel temps fait-il à Paris?", desktopId);
+  return response;
 }
 ```
 
-### Génération d'embeddings pour la recherche sémantique
+### Génération d'embeddings par lots
 
 ```javascript
-// Dans une méthode d'un acteur Elf
-async updateKnowledgeBase(articles) {
+async indexArticles(agentId, articles) {
   const feedId = await this.newQuestFeed();
-
-  // Instancie l'agent approprié pour faire un embedding
-  // par ex. 'aiAgent@default-embedder'
   const agent = await new AiAgent(this).create(agentId, feedId);
 
-  // Récupère les textes à indexer
+  const articleIds = Object.keys(articles);
   const texts = Object.values(articles);
 
-  // Prépare un boucle d'insertion par id d'article
-  const articlesIds = Object.keys(articles);
-
-  // Générer des embeddings pour plusieurs textes en une seule requête
   const vectorsBatch = await agent.embedInBatch(texts);
 
-  // Upsert les articles dans un archetype IndexedContent
-  for(const articleId of articleIds) {
-    // Récupère les vecteurs correspondant au texte dans le lot
-    // et le texte original
-    const index = articleIds.indexOf(articleId);
-    const vectors = vectorsBatch[index];
-    const text = texts[index];
-
-    const indexedContent = new IndexedContentState({
-      id: articleId,
-      text, //texte original de l'article
-      meta: {
-        locale: 'fr', //définit la locale
-        scope: 'knowledge-base', //définit le scope
-        vectors, //vecteur correspondants au texte
-        status: 'published',
-      }
-    });
-
-    // Effectue l'upsert de l'archetype
-    await new IndexedContent(this).insertOrReplace(
-      articleId,
-      feedId,
-      indexedContent
-    );
+  for (let i = 0; i < articleIds.length; i++) {
+    const articleId = articleIds[i];
+    const vectors = vectorsBatch[i];
+    const text = texts[i];
+    // Insérer dans une base vectorielle...
   }
 }
 ```
 
-## Interactions avec d'autres modules
+### Agent ReAct autonome
 
-Le module `goblin-agents` interagit avec plusieurs autres composants de l'écosystème Xcraft :
+```javascript
+async runReactAgent(agentId, contextId, question) {
+  const feedId = await this.newQuestFeed();
+  const agent = await new AiAgent(this).create(agentId, feedId);
+
+  const reactPrompt = `Tu es un agent autonome. Raisonne étape par étape et agis.`;
+  const result = await agent.react(reactPrompt, contextId, question);
+  // result : { agentId, action, result, observation }
+  return result;
+}
+```
+
+## Interactions avec d'autres modules
 
-- **[xcraft-core-goblin]** : Fournit l'infrastructure Elf pour la création d'acteurs
-- **[xcraft-core-stones]** : Utilisé pour la définition des types de données
-- **[xcraft-core-utils]** : Utilisé pour les appels API REST et la gestion des verrous
-- **[xcraft-core-etc]** : Utilisé pour la gestion de la configuration du module
+- **[xcraft-core-goblin]** : Fournit l'infrastructure Elf/Archetype pour la création et la persistance des acteurs
+- **[xcraft-core-stones]** : Utilisé pour la définition et la validation des types de données (shapes)
+- **[xcraft-core-utils]** : Utilisé pour les appels API REST (`RestAPI`), la gestion des verrous (`getMutex`, `Semaphore`)
+- **[xcraft-core-etc]** : Utilisé pour charger la configuration du module (version des agents)
 
-Le module peut également interagir avec d'autres services Goblin via le système d'appels d'outils, permettant aux agents d'effectuer des actions concrètes dans l'application.
+Le module peut interagir avec n'importe quel autre acteur Goblin/Elf via le système d'appels d'outils : l'agent envoie des commandes sur le bus Xcraft vers le `toolServiceId` configuré, permettant aux agents IA d'effectuer des actions concrètes dans l'application.
 
 ## Configuration avancée
 
-| Option          | Description                           | Type   | Valeur par défaut |
-| --------------- | ------------------------------------- | ------ | ----------------- |
-| version         | Version des agents                    | Number | 2                 |
-| defaultProfile  | Profil par défaut des agents          | String | null              |
-| defaultSettings | Paramètres par défaut                 | Object | null              |
-| profiles        | Profils pour remplacer les paramètres | Object | {}                |
-| settings        | Paramètres par nom                    | Object | {}                |
+| Option    | Description        | Type   | Valeur par défaut |
+| --------- | ------------------ | ------ | ----------------- |
+| `version` | Version des agents | Number | `2`               |
 
 ## Détails des sources
 
 ### `aiAgent.js`
 
-Ce fichier est le point d'entrée du module, exportant les commandes Xcraft pour l'acteur AiAgent. Il importe l'acteur et sa logique depuis le fichier principal et les expose au système Xcraft via `Elf.birth()`.
+Point d'entrée du module. Exporte les commandes Xcraft pour l'acteur `AiAgent` via `Elf.birth()`, ce qui enregistre l'acteur sur le bus Xcraft au démarrage du serveur.
 
 ### `lib/llm/aiAgent.js`
 
-Ce fichier contient la définition complète de l'acteur AiAgent, avec :
-
-- **MessageShape** : Définit la structure des messages échangés (rôle, contenu, images, appels d'outils)
-- **OptionsShape** : Définit les nombreuses options de configuration des modèles LLM
-- **AiAgentShape** : Définit la structure des données de l'agent
-- **AiAgentState** : Classe d'état de l'agent basée sur le shape
-- **AiAgentLogic** : Logique métier de l'agent (mutations d'état)
-- **AiAgent** : Classe principale de l'acteur avec les méthodes d'interaction
+Cœur du module. Contient la définition complète de l'acteur `AiAgent`.
 
 #### État et modèle de données
 
-L'état d'un agent IA est défini par la classe `AiAgentShape` qui contient les propriétés suivantes :
-
-- `id` : Identifiant unique de l'agent
-- `version` : Version de l'agent
-- `name` : Nom de l'agent
-- `role` : Rôle de l'agent (assistant, etc.)
-- `prompt` : Prompt par défaut utilisé pour définir le comportement de l'agent
-- `provider` : Fournisseur LLM ('ollama' ou 'open-ai')
-- `model` : Modèle de langage utilisé
-- `host` : URL du serveur LLM
-- `headers` : En-têtes HTTP pour les requêtes API
-- `messages` : Historique des messages par contexte
-- `options` : Options de configuration du modèle (voir OptionsShape)
-- `format` : Format de sortie attendu
-- `tools` : Outils externes disponibles pour l'agent
-- `toolServiceId` : Identifiant du service d'outils
-- `usability` : État d'utilisabilité ('disabled', 'experimental', 'stable', 'deprecated')
-- `meta` : Métadonnées de l'agent
-
-La classe `OptionsShape` définit de nombreuses options de configuration pour les modèles LLM, incluant des paramètres comme la température, la taille du contexte, les pénalités de répétition, et les options d'optimisation mémoire.
+L'état de l'agent est défini par `AiAgentShape` :
+
+| Propriété       | Type                                                       | Description                                             |
+| --------------- | ---------------------------------------------------------- | ------------------------------------------------------- |
+| `id`            | `id('aiAgent')`                                            | Identifiant unique de l'agent                           |
+| `version`       | `number`                                                   | Version de l'agent (protection contre les régressions)  |
+| `name`          | `string`                                                   | Nom de l'agent                                          |
+| `role`          | `string`                                                   | Rôle de l'agent (ex : `'assistant'`)                    |
+| `prompt`        | `string`                                                   | Prompt système par défaut                               |
+| `provider`      | `'ollama' \| 'open-ai'`                                    | Fournisseur LLM                                         |
+| `model`         | `string`                                                   | Modèle LLM principal                                    |
+| `otherModels`   | `array(string)`                                            | Modèles alternatifs (rotation possible)                 |
+| `host`          | `string`                                                   | URL du serveur LLM (défaut : `http://127.0.0.1:11434`)  |
+| `headers`       | `record(string, string)`                                   | En-têtes HTTP pour les requêtes API (authentification…) |
+| `messages`      | `record(string, array(MessageShape))`                      | Historique des messages indexé par `contextId`          |
+| `options`       | `option(OptionsShape)`                                     | Options de configuration du modèle LLM                  |
+| `format`        | `option(object)`                                           | Format de sortie JSON attendu                           |
+| `tools`         | `option(array(object))`                                    | Définitions des outils externes disponibles             |
+| `toolServiceId` | `option(string)`                                           | ID de l'acteur exposant les quêtes outils               |
+| `usability`     | `'disabled' \| 'experimental' \| 'stable' \| 'deprecated'` | État d'utilisabilité de l'agent                         |
+| `reasoning`     | `option(boolean)`                                          | Active le mode raisonnement (think tags)                |
+| `vectorQuality` | `option('f32' \| 'int8')`                                  | Qualité des vecteurs pour les embeddings                |
+| `meta`          | `MetaShape`                                                | Métadonnées (statut : `'published'` ou `'trashed'`)     |
+
+**`MessageShape`** décrit chaque message de l'historique :
+
+- `role` : `'assistant' | 'user' | 'tool'`
+- `content` : contenu textuel du message
+- `images` : liste optionnelle d'images base64
+- `tool_calls` : appels d'outils optionnels
+- `tool_call_id` / `tool_name` : référence à un appel d'outil (messages de type `tool`)
+
+**`OptionsShape`** expose tous les paramètres de fine-tuning des modèles Ollama : `temperature`, `num_ctx`, `num_gpu`, `top_k`, `top_p`, `repeat_penalty`, `seed`, `stop`, `mirostat`, etc. Chaque option est facultative (`option(...)`).
 
 #### Cycle de vie de l'acteur
 
-L'acteur AiAgent suit le cycle de vie standard des acteurs Elf Archetype :
+`AiAgent` est un **Elf.Archetype** persisté dans la base `agents` avec un index sur `role`.
 
-1. **Création** : Via la méthode `create()` qui initialise l'agent avec un ID et un état
-2. **Configuration** : Via `patch()` pour modifier les paramètres ou `upgrade()` pour les mises à jour de version
-3. **Utilisation** : Via les méthodes de conversation et de génération
-4. **Persistance** : Via `save()` pour sauvegarder l'état
-5. **Suppression** : Via `trash()` pour marquer comme supprimé ou `delete()` pour suppression définitive
+1. **Création** : `create(id, desktopId, agentState?)` — initialise l'agent, applique les valeurs par défaut, persiste.
+2. **Mise à jour** : `patch(agentState)` — met à jour les paramètres et persiste.
+3. **Migration de version** : `upgrade(version, agentState)` — applique une mise à niveau uniquement si la version est supérieure à la version actuelle.
+4. **Utilisation** : méthodes de conversation, génération, embeddings.
+5. **Persistance manuelle** : `save()` — persiste l'état courant.
+6. **Suppression logique** : `trash()` — passe le statut meta à `'trashed'`.
+7. **Suppression physique** : `delete()` — méthode présente (vide, gérée par le framework).
 
 #### Méthodes publiques
 
-- **`create(id, desktopId, agentState)`** — Crée un nouvel agent avec l'ID et l'état spécifiés. Persiste automatiquement l'agent après création.
-- **`patch(agentState)`** — Met à jour l'état de l'agent avec les propriétés fournies et persiste les changements.
-- **`upgrade(version, agentState)`** — Met à niveau l'agent vers une nouvelle version avec l'état spécifié, uniquement si la version est supérieure à la version actuelle.
-- **`gen(prompt)`** — Génère du texte à partir d'un prompt en utilisant le modèle configuré de l'agent.
-- **`reset(contextId, save=false)`** — Réinitialise l'historique des messages pour un contexte spécifique. Si aucun contextId n'est fourni, réinitialise tous les contextes.
-- **`readPDFpages(pdfPath)`** — Extrait le texte des pages d'un document PDF en utilisant l'OCR via un modèle multimodal.
-- **`embed(rawText)`** — Génère un embedding vectoriel pour un texte donné, retourné sous forme de littéral SQL hexadécimal.
-- **`embedInBatch(rawTexts=[])`** — Génère des embeddings vectoriels pour plusieurs textes en une seule requête, optimisé pour les traitements par lots avec gestion des verrous.
-- **`set(contextId, messages)`** — Définit directement l'historique des messages pour un contexte spécifique.
-- **`chat(contextId, question, userDesktopId, sessionId=null)`** — Engage une conversation avec l'agent dans un contexte spécifique. Gère automatiquement l'historique et les appels d'outils.
-- **`ask(contextId, question, questionId)`** — Pose une question à l'agent avec streaming de la réponse (uniquement pour Ollama). Émet des événements pour chaque partie de la réponse.
-- **`resumeExchange(resumePrompt, contextId)`** — Reprend un échange existant avec un nouveau prompt système, en utilisant l'historique du contexte comme base.
-- **`react(reactPrompt, contextId, question)`** — Utilise le paradigme ReAct (Reasoning and Acting) pour permettre à l'agent de raisonner et d'agir de manière autonome.
-- **`callAgent(contextId, agentId, action, feedId)`** — Appelle un autre agent pour effectuer une action spécifique dans le cadre d'une orchestration multi-agents.
-- **`addAssistantMessage(contextId, message)`** — Ajoute un message de l'assistant à l'historique d'un contexte spécifique.
-- **`change(path, newValue)`** — Modifie une propriété spécifique de l'état de l'agent avec gestion automatique des types pour certains paramètres.
-- **`getUserChatContextHistory(contextId, filterTool=true)`** — Récupère l'historique des messages pour un contexte spécifique avec option de filtrage des messages d'outils.
-- **`getBaseSettings()`** — Retourne les paramètres de base de l'agent (provider, host, headers, model).
-- **`getUsability()`** — Retourne l'état d'utilisabilité de l'agent.
-- **`trash()`** — Marque l'agent comme supprimé en changeant son statut meta à 'trashed'.
-- **`save()`** — Persiste l'état actuel de l'agent sur le disque.
+- **`create(id, desktopId, agentState?)`** — Crée et persiste un nouvel agent. `agentState` permet d'initialiser les propriétés dès la création.
+- **`patch(agentState)`** — Met à jour les paramètres de l'agent (provider, model, tools, options, etc.) et persiste.
+- **`upgrade(version, agentState)`** — Migre l'agent vers une nouvelle version si `version > state.version`.
+- **`useOtherModel(model)`** — Permute le modèle actif avec un modèle de `otherModels`. Retourne `false` si le modèle n'est pas dans la liste.
+- **`getModelList()`** — Retourne la liste complète des modèles disponibles (`[model, ...otherModels]`).
+- **`gen(prompt, contextId='default')`** — Génère une réponse à partir d'un prompt sans historique conversationnel. Journalise l'échange.
+- **`reset(contextId, save=false)`** — Réinitialise l'historique d'un contexte. Sans `contextId`, réinitialise tous les contextes.
+- **`readPDFpages(pdfPath, pages)`** — Extrait le texte des pages spécifiées d'un PDF via OCR multimodal. Retourne un tableau de descriptions par page.
+- **`vision(context, image)`** — Analyse une image base64 avec un contexte textuel. Retourne la description générée par le modèle.
+- **`embed(rawText)`** — Génère un embedding vectoriel pour un texte. Retourne une chaîne hex SQL (float32 ou int8 selon `vectorQuality`).
+- **`embedInBatch(rawTexts=[])`** — Génère des embeddings pour plusieurs textes en une requête. Retourne un tableau de chaînes hex SQL.
+- **`set(contextId, messages)`** — Remplace directement l'historique d'un contexte par une liste de messages.
+- **`chat(contextId, question, userDesktopId)`** — Conversation avec historique. Gère automatiquement les appels d'outils si configurés. Retourne la réponse texte ou `true` si un second tour d'outils est nécessaire.
+- **`callTools(contextId, message, userDesktopId)`** — Exécute les appels d'outils demandés par le modèle, envoie les commandes sur le bus Xcraft et enregistre les résultats dans l'historique.
+- **`addToolMessage(contextId, toolId, toolName, answer)`** — Ajoute un message de résultat d'outil dans l'historique d'un contexte.
+- **`ask(contextId, question, questionId)`** — Pose une question avec streaming (Ollama uniquement). Émet des événements `<questionId>` pour chaque fragment de réponse.
+- **`resumeExchange(resumePrompt, contextId)`** — Reprend un échange existant avec un nouveau prompt système pour générer un résumé ou une synthèse de la conversation.
+- **`react(reactPrompt, contextId, question)`** — Paradigme ReAct : le modèle produit une observation, une pensée, une action et un résultat structurés (JSON). Peut déléguer à un autre agent via `callAgent`.
+- **`callAgent(contextId, agentId, action, feedId)`** — Instancie et interroge un autre agent `AiAgent` pour une action dans un workflow multi-agents.
+- **`addAssistantMessage(contextId, message)`** — Ajoute directement un message assistant dans l'historique d'un contexte.
+- **`save()`** — Persiste l'état courant sur le disque.
+- **`change(path, newValue)`** — Modifie une propriété de l'état par chemin (ex : `'options.temperature'`). Convertit automatiquement les types pour `temperature` (float) et `num_ctx` (int).
+- **`getUserChatContextHistory(contextId, filterTool=true)`** — Retourne l'historique utilisateur d'un contexte, en filtrant optionnellement les messages d'outils.
+- **`getToolChatContextHistory(contextId)`** — Retourne uniquement les messages de type `tool` de l'historique d'un contexte.
+- **`getBaseSettings()`** — Retourne les paramètres de base : `{provider, host, headers, model, otherModels}`.
+- **`trash()`** — Marque l'agent comme supprimé (`meta.status = 'trashed'`) et persiste.
+- **`publish()`** — Marque l'agent comme publié (`meta.status = 'published'`) et persiste.
 
 ### `lib/llm/providers.js`
 
-Ce fichier définit l'architecture des fournisseurs de LLM avec une classe abstraite `LLMProvider` et ses implémentations concrètes :
+Registre des fournisseurs LLM. La classe `LLMProviders` expose une méthode statique `get(name)` qui retourne la classe du provider correspondant (`OllamaProvider` par défaut, `OpenAIProvider` pour `'open-ai'`).
 
-#### LLMProvider (classe abstraite)
+### `lib/llm/providers/provider.js`
 
-Définit l'interface commune que tous les fournisseurs doivent implémenter :
+Classe abstraite `LLMProvider` définissant l'interface commune :
 
-- `chat()` : Conversation avec le modèle
-- `gen()` : Génération de texte
-- `embed()` : Génération d'embeddings
-- `embedInBatch()` : Génération d'embeddings par lots
+- `chat(chatRequest)` : conversation avec le modèle
+- `gen(genRequest)` : génération de texte
+- `embed(embedRequest)` : embedding d'un texte
+- `embedInBatch(embedRequest)` : embedding par lots
 
-#### OllamaProvider
+Ne peut pas être instanciée directement.
 
-Implémentation pour le fournisseur Ollama (serveur local) :
+### `lib/llm/providers/ollama.js`
+
+Implémentation concrète pour **Ollama** (serveur local) :
 
 - Utilise la bibliothèque `ollama` pour communiquer avec le serveur
-- Gère le streaming pour les conversations en temps réel
-- Implémente un sémaphore pour limiter les requêtes d'embedding simultanées (max 4)
-- Supporte tous les formats de sortie JSON structurés
+- Implémente un **sémaphore** (`Semaphore(4)`) pour limiter à 4 requêtes d'embedding simultanées
+- Supporte le mode `stream` et le mode raisonnement (`think: reasoning`)
+- Parse automatiquement les réponses JSON structurées (`format`)
+
+### `lib/llm/providers/opanAi.js`
+
+Implémentation concrète pour **OpenAI** et services compatibles (OpenRouter, etc.) :
+
+- Utilise `RestAPI` de [xcraft-core-utils] pour les appels HTTP avec retry sur POST
+- Adapte le format des requêtes : les `options` Ollama sont mergées à la racine de la requête
+- Gère les schémas JSON structurés via `response_format` avec `json_schema`
+- La méthode `gen` est implémentée via `chat` (conversion prompt → message user)
+- Le mode `reasoning` n'est pas encore supporté (supprimé de la requête)
 
-#### OpenAIProvider
+### `lib/logger.js`
 
-Implémentation pour OpenAI et services compatibles (OpenRouter, etc.) :
+Système de journalisation HTML des échanges IA. Chaque session de logging est identifiée par un `id` (typiquement le `contextId`).
 
-- Utilise `RestAPI` de xcraft-core-utils pour les appels HTTP
-- Adapte les formats de requête entre Ollama et OpenAI
-- Gère les schémas JSON pour les réponses structurées
-- Supporte les en-têtes d'authentification personnalisés
+**Fonctionnement :**
+
+- `Logger.get(id, quest)` : récupère ou crée un logger pour l'id donné. Enregistre automatiquement un `defer` sur la quête pour appeler `dispose()` à la fin.
+- `push(step, payload)` : enregistre un message horodaté avec une étape nommée et un payload clé/valeur.
+- `dispose()` : génère un rapport HTML dans `<xcraftRoot>/var/log/ai/` (fichier nommé `<id>_<timestamp>Z.html`) et nettoie le logger du registre. Le logger `'default'` ne génère pas de rapport.
+
+Les rapports HTML sont construits à partir de templates dans `lib/report/` et peuvent servir à l'audit ou au débogage des conversations IA.
 
 ### `lib/llm/utils.js`
 
-Ce fichier contient un ensemble complet d'utilitaires pour le traitement de texte et de documents :
+Ensemble complet d'utilitaires pour le traitement de texte, HTML et documents.
+
+**Traitement de documents PDF :**
+
+- **`getPDFImages(pdfPath, pages)`** — Convertit les pages spécifiées d'un PDF en images base64 (PNG). Nécessite `pdf-to-png-converter` comme dépendance explicite du projet consommateur.
+- **`OCR_SYSTEM_PROMPT`** — Prompt système spécialisé pour guider les modèles multimodaux dans l'extraction fidèle de texte depuis des images.
 
-#### Traitement de documents PDF
+**Traitement HTML :**
 
-- **`getPDFImages(pdfPath)`** — Convertit les pages d'un PDF en images base64 pour l'OCR avec des options optimisées pour la qualité du texte.
-- **`OCR_SYSTEM_PROMPT`** — Prompt système spécialisé pour guider les modèles multimodaux dans l'extraction de texte à partir d'images.
+- **`cleanHtmlContent(html)`** — Supprime toutes les balises HTML et normalise les espaces blancs.
+- **`simplifyHtml(html)`** — Nettoie le HTML en ne gardant que les éléments sûrs via `sanitize-html`.
+- **`extractTitlesAndContent(html)`** — Extrait titres (`h1`–`h6`) et paragraphes en préservant la structure, avec découpage des segments longs.
+- **`html2chunks(html, chunkSize=300, chunkOverlap=0, minChunkLength=10)`** — Découpe un document HTML en chunks via `RecursiveCharacterTextSplitter` de LangChain.
 
-#### Traitement de texte et HTML
+**Gestion des tokens et découpage :**
 
-- **`cleanHtmlContent(html)`** — Nettoie le contenu HTML en supprimant les balises et en normalisant les espaces.
-- **`simplifyHtml(html)`** — Simplifie le HTML en gardant uniquement les éléments sûrs via sanitize-html.
-- **`extractTitlesAndContent(html)`** — Extrait intelligemment les titres et le contenu d'un document HTML en préservant la structure.
-- **`html2chunks(html, chunkSize=300, chunkOverlap=0)`** — Découpe un document HTML en chunks en utilisant RecursiveCharacterTextSplitter de LangChain.
+- **`estimateTokenCount(text)`** — Estime le nombre de tokens (mots × 1.33).
+- **`splitLongText(text, maxLength, baseId)`** — Découpe un texte en segments mot-à-mot avec IDs incrémentaux.
+- **`sliceText(text, chunkSize)`** — Découpe par phrases en respectant `chunkSize`.
+- **`groupSentences(text, maxSize)`** — Groupe des phrases en blocs de taille optimale, avec fallback mot-à-mot pour les phrases très longues.
 
-#### Gestion des tokens et découpage
+**Traitement par lots et embeddings :**
 
-- **`estimateTokenCount(text)`** — Estime le nombre de tokens d'un texte (approximation basée sur les mots × 1.33).
-- **`splitLongText(text, maxLength, baseId)`** — Découpe un texte long en segments de taille maximale en préservant les mots entiers.
-- **`sliceText(text, chunkSize)`** — Découpe un texte en chunks en respectant les limites de phrases.
-- **`groupSentences(text, maxSize)`** — Groupe les phrases en chunks de taille optimale pour les modèles de langage.
+- **`chunkArray(array, size)`** — Divise un tableau en sous-tableaux de taille fixe.
+- **`embedChunksInBatch(agent, allChunks, batchSize=50, prefix='passage: ')`** — Traite les embeddings par lots et retourne une map `{ [contentId]: { [key]: { chunk, embedding } } }`.
+- **`buildPromptFromArticlesMulti(articles, format='text', maxTotalTokens, dbg)`** — Construit un prompt multi-articles optimisé en respectant une limite de tokens (avec buffer de 16 000 tokens pour l'instruction et la réponse).
 
-#### Traitement par lots et optimisation
+**Utilitaires divers :**
 
-- **`chunkArray(array, size)`** — Divise un tableau en sous-tableaux de taille spécifiée pour le traitement par lots.
-- **`embedChunksInBatch(agent, allChunks, batchSize=50)`** — Traite les embeddings par lots en associant chaque embedding à son contenu d'origine.
-- **`buildPromptFromArticlesMulti(initialQuestion, questionsWithArticles, maxTotalTokens)`** — Construit des prompts optimisés à partir de multiples articles en respectant les limites de tokens.
+- **`splitThinkTags(input)`** — Extrait et sépare le contenu des balises `<think>...</think>` (raisonnement interne) du texte propre. Retourne `{ thinks, cleanText }`.
+- **`vectorToSqlLiteral(vec)`** — Convertit un vecteur Float32Array en chaîne hex SQL (float32).
+- **`vectorToSqlLiteralInt8(vec)`** — Convertit un vecteur normalisé [-1,1] en int8 quantifié, puis en chaîne hex SQL (plus compact, moins précis).
 
-#### Utilitaires de conversion
+## Licence
 
-- **`vectorToSqlLiteral(vec)`** — Convertit un vecteur Float32Array en littéral SQL hexadécimal pour le stockage en base de données.
+Ce module est distribué sous [licence MIT](./LICENSE).
 
-Ces utilitaires sont essentiels pour préparer les données avant de les envoyer aux modèles de langage et pour traiter les résultats. Ils permettent notamment de gérer les contraintes de taille de contexte des modèles en découpant intelligemment les textes longs tout en préservant la cohérence sémantique.
+---
 
-_Cette documentation a été mise à jour automatiquement._
+_Ce contenu a été généré par IA_
 
 [xcraft-core-goblin]: https://github.com/Xcraft-Inc/xcraft-core-goblin
 [xcraft-core-stones]: https://github.com/Xcraft-Inc/xcraft-core-stones
 [xcraft-core-utils]: https://github.com/Xcraft-Inc/xcraft-core-utils
-[xcraft-core-etc]: https://github.com/Xcraft-Inc/xcraft-core-etc
+[xcraft-core-etc]: https://github.com/Xcraft-Inc/xcraft-core-etc

package/lib/llm/utils.js

@@ -90,13 +90,19 @@ const splitLongText = (text, maxLength, baseId) => {
   return segments;
 };
 
-const html2chunks = async (html, chunkSize = 300, chunkOverlap = 50) => {
+const html2chunks = async (
+  html,
+  chunkSize = 300,
+  chunkOverlap = 0,
+  minChunkLength = 10
+) => {
   const textSplitter = RecursiveCharacterTextSplitter.fromLanguage('html', {
     chunkSize,
     chunkOverlap,
     separators: RecursiveCharacterTextSplitter.getSeparatorsForLanguage('html'),
   });
-  return await textSplitter.splitText(html);
+  const chunks = await textSplitter.splitText(html);
+  return chunks.filter((chunk) => chunk.length >= minChunkLength);
 };
 
 const extractTitlesAndContent = (html) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goblin-agents",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "AI Agents framework",
   "author": "Epsitec SA",
   "contributors": [
@@ -18,8 +18,8 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@langchain/core": "^0.3.42",
-    "@langchain/textsplitters": "^0.1.0",
+    "@langchain/core": "^1.1.28",
+    "@langchain/textsplitters": "^1.0.1",
     "fs-extra": "^11.3.0",
     "html-entities": "^2.4.0",
     "ollama": "^0.5.10",