goblin-agents 0.1.5 → 0.1.10

package/README.md

@@ -19,6 +19,7 @@ Le module `goblin-agents` permet de créer et gérer des agents IA qui peuvent i
 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 module prend en charge diverses fonctionnalités avancées :
+
 - Génération de texte à partir de prompts
 - Conversations interactives avec historique
 - Extraction de texte à partir d'images de documents PDF
@@ -36,7 +37,7 @@ Les agents peuvent être configurés avec une grande variété d'options qui inf
 const {AiAgent} = require('goblin-agents/lib/llm/aiAgent.js');
 
 // Dans une méthode d'un acteur Elf
-async initAgents() {  
+async initAgents() {
   const feedId = await this.newQuestFeed();
 
   // Création d'un agent avec Ollama (local)
@@ -72,15 +73,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 
+
+  // Continue la conversation sur ce contexte par ex. 'story-xyz' et
   // obtient une réponse à la question de l'utilisateur
   const response = await agent.chat(contextId, question, desktopId);
 
@@ -95,11 +95,10 @@ async askAgent(desktopId, agentId, contextId, question, saveExchange = false) {
 ### Résumer et "squasher" un contexte
 
 ```javascript
-
 // Dans une méthode d'un acteur Elf
 async resumeAndSquashContexte(agentId, contextId) {
   const feedId = await this.newQuestFeed();
-  
+
   // Instancie l'agent approprié par ex. 'aiAgent@gpt-4o-assistant'
   const agent = await new AiAgent(this).create(agentId, feedId);
 
@@ -110,7 +109,7 @@ async resumeAndSquashContexte(agentId, contextId) {
   // Reset la mémoire contextuel et persiste le changement
   await agent.reset(contextId, true);
 
-  // Ajoute un nouvel historique d'échange a partir du résumé 
+  // Ajoute un nouvel historique d'échange a partir du résumé
   await agent.set(contextId, [{role: 'assistant', content: resumedContent}]);
 
   // Sauve ce nouvel état
@@ -121,11 +120,10 @@ async resumeAndSquashContexte(agentId, contextId) {
 ### Utilisation d'outils externes
 
 ```javascript
-
 // Dans une méthode d'un acteur Elf
 async addWeatherToolSupportToAgent(agentId) {
   const feedId = await this.newQuestFeed();
-  
+
   // Instancie l'agent approprié par ex. 'aiAgent@gpt-4o-assistant'
   const agent = await new AiAgent(this).create(agentId, feedId);
 
@@ -160,13 +158,11 @@ async addWeatherToolSupportToAgent(agentId) {
 // 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);
-
 ```
 
 ### Génération d'embeddings pour la recherche sémantique
 
 ```javascript
-
 // Dans une méthode d'un acteur Elf
 // {
 //  'indexContent@article-1', 'Contenu à indexer'
@@ -189,9 +185,9 @@ async updateKnowledgeBase(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 
+  // Upsert les articles dans un archetype IndexedContent
   for(const articleId of articleIds) {
-    // Récupère les vecteurs correspondant au texte dans le lot 
+    // Récupère les vecteurs correspondant au texte dans le lot
     // et le texte original
     const index = articleIds.indexOf(articleId);
     const vectors = vectorsBatch[index];
@@ -252,19 +248,21 @@ async queryKnowledgeBase(question = "Comment fonctionne l'apprentissage par renf
 
 Le module `goblin-agents` interagit avec plusieurs autres composants de l'écosystème Xcraft :
 
-- **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-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
 
 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.
 
 ## Configuration avancée
 
-- **version** : Version des agents (par défaut: 2)
-- **defaultProfile** : Profil par défaut des agents (par défaut: null)
-- **defaultSettings** : Paramètres par défaut (par défaut: null)
-- **profiles** : Profils pour remplacer les paramètres (par défaut: {})
-- **settings** : Paramètres par nom (par défaut: {})
+| 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 | {} |
 
 ## Détails des sources
 
@@ -276,6 +274,7 @@ Ce fichier est le point d'entrée du module, exportant les commandes Xcraft pour
 
 Ce fichier définit la configuration du module, permettant de spécifier :
 
+- La version des agents (`version`)
 - Le profil par défaut des agents (`defaultProfile`)
 - Les paramètres par défaut (`defaultSettings`)
 - Les profils pour remplacer les paramètres (`profiles`)
@@ -294,14 +293,53 @@ Ce fichier contient la définition complète de l'acteur AiAgent, avec :
 - **AiAgentLogic** : Logique métier de l'agent (mutations d'état)
 - **AiAgent** : Classe principale de l'acteur avec les méthodes d'interaction
 
-L'acteur AiAgent offre de nombreuses méthodes pour interagir avec les modèles de langage, gérer les conversations, et utiliser des outils externes. Il prend en charge différentes configurations et options pour personnaliser le comportement des modèles.
-
-Les options de configuration sont particulièrement riches et permettent d'ajuster finement le comportement des modèles, notamment :
-- Gestion de la mémoire (NUMA, VRAM)
-- Taille du contexte et traitement par lots
-- Paramètres de génération (température, top_k, top_p)
-- Pénalités pour éviter les répétitions
-- Algorithmes adaptatifs comme Mirostat
+#### É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
+- `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
+
+#### Méthodes publiques
+
+- **`create(id, desktopId, agentState)`** - Crée un nouvel agent avec l'ID et l'état spécifiés.
+- **`patch(agentState)`** - Met à jour l'état de l'agent avec les propriétés fournies.
+- **`upgrade(version, agentState)`** - Met à niveau l'agent vers une nouvelle version avec l'état spécifié.
+- **`gen(prompt)`** - Génère du texte à partir d'un prompt.
+- **`reset(contextId, save)`** - Réinitialise l'historique des messages pour un contexte spécifique.
+- **`readPDFpages(pdfPath)`** - Extrait le texte des pages d'un document PDF.
+- **`embed(rawText)`** - Génère un embedding vectoriel pour un texte donné.
+- **`embedInBatch(rawTexts)`** - Génère des embeddings vectoriels pour plusieurs textes en une seule requête.
+- **`set(contextId, messages)`** - Définit l'historique des messages pour un contexte spécifique.
+- **`chat(contextId, question, userDesktopId, sessionId)`** - Engage une conversation avec l'agent dans un contexte spécifique.
+- **`callTools(contextId, message, userDesktopId, sessionId)`** - Appelle des outils externes en fonction des demandes de l'agent.
+- **`addToolMessage(contextId, toolId, toolName, answer)`** - Ajoute une réponse d'outil à l'historique des messages.
+- **`ask(contextId, question, questionId)`** - Pose une question à l'agent avec streaming de la réponse.
+- **`resumeExchange(resumePrompt, contextId)`** - Résume un échange de conversation.
+- **`react(reactPrompt, contextId, question)`** - Utilise le paradigme ReAct pour raisonner et agir sur une question.
+- **`callAgent(contextId, agentId, action, feedId)`** - Appelle un autre agent pour effectuer une action.
+- **`addAssistantMessage(contextId, message)`** - Ajoute un message de l'assistant à l'historique.
+- **`save()`** - Persiste l'état de l'agent.
+- **`change(path, newValue)`** - Modifie une propriété spécifique de l'état de l'agent.
+- **`getUserChatContextHistory(contextId, filterTool)`** - Récupère l'historique des messages pour un contexte spécifique.
+- **`getBaseSettings()`** - Récupère les paramètres de base de l'agent.
+- **`getUsability()`** - Récupère l'état d'utilisabilité de l'agent.
+- **`trash()`** - Marque l'agent comme supprimé.
+- **`delete()`** - Supprime l'agent.
 
 ### `lib/llm/providers.js`
 
@@ -328,4 +366,8 @@ Ces utilitaires sont essentiels pour préparer les données avant de les envoyer
 
 Le module inclut également des fonctionnalités spécifiques pour l'OCR (reconnaissance optique de caractères) avec un prompt système dédié (`OCR_SYSTEM_PROMPT`) qui guide les modèles multimodaux dans l'extraction de texte à partir d'images.
 
-*Ce document est une mise à jour de la documentation précédente.*
+_Cette documentation a été mise à jour automatiquement._
+
+[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

package/lib/llm/providers.js

@@ -151,7 +151,11 @@ class OpenAIProvider extends LLMProvider {
     const chat = await this.#openAI._post(query, chatRequest);
     const {choices} = chat;
     if (chat.error) {
-      const err = new Error(chat.error.message);
+      const err = new Error(
+        chat.error?.metadata
+          ? JSON.stringify(chat.error?.metadata)
+          : chat.error.message
+      );
       err.code = chat.error.code;
       throw err;
     }

package/lib/llm/utils.js

@@ -77,7 +77,7 @@ const splitLongText = (text, maxLength, baseId) => {
   return segments;
 };
 
-const html2chunks = async (html, chunkSize = 1000, chunkOverlap = 0) => {
+const html2chunks = async (html, chunkSize = 300, chunkOverlap = 0) => {
   const textSplitter = RecursiveCharacterTextSplitter.fromLanguage('html', {
     chunkSize,
     chunkOverlap,
@@ -223,58 +223,46 @@ function groupSentences(text, maxSize) {
   return chunks;
 }
 
-const buildPromptFromArticles = (articles, question, maxTokens) => {
-  let context = '[CONTEXT]\n\n';
-  let currentTokenCount = estimateTokenCount(context);
-
-  articles.forEach((article) => {
-    const {kind, title, link, locale} = article;
-    const articleContext = `# ${kind}: ${title} #\nLien: ${link}\n Langue: ${locale}\n`;
-
-    context += articleContext;
-
-    if (article.segments && article.segments.length > 0) {
-      context += '## Segments pertinents: ##\n';
-      article.segments
-        .sort((a, b) => b.score - a.score) // Trier par pertinence
-        .forEach((s, i) => {
-          let segmentContext = `  ${i + 1}. ${s.segment} (Pertinence: ${
-            s.score
-          })\n`;
-          currentTokenCount += estimateTokenCount(segmentContext);
-
-          if (currentTokenCount > maxTokens) {
-            return;
-          }
-
-          context += segmentContext;
-
-          // Ajouter du contexte avant et après le segment
-          const beforeContext = article.content.substring(
-            Math.max(0, s.start - 50),
-            s.start
-          );
-          const afterContext = article.content.substring(
-            s.end,
-            Math.min(article.content.length, s.end + 50)
-          );
-
-          const additionalContext = `### Contexte avant: ###\n${beforeContext}\n### Contexte après: ###\n${afterContext}\n`;
-          currentTokenCount += estimateTokenCount(additionalContext);
+function buildPromptFromArticlesMulti(
+  initialQuestion,
+  questionsWithArticles,
+  maxTotalTokens
+) {
+  let prompt = '[CONTEXT]\n\n';
+  let currentTokenCount = estimateTokenCount(prompt);
+
+  const buffer = 16000; // Réserve de tokens pour l'instruction + réponse
+  const maxTokensPerQuestion = Math.floor(
+    (maxTotalTokens - buffer) / questionsWithArticles.length
+  );
+
+  for (const {articles} of questionsWithArticles) {
+    let section = '';
+    let sectionTokenCount = estimateTokenCount(section);
+    for (const article of articles) {
+      const {title, sourceId, description} = article;
+      const articleBlock = `\n# ${title} \n## Lien: ${sourceId}\n\n${description}\n`;
+      const tokensForArticle = estimateTokenCount(articleBlock);
+
+      if (sectionTokenCount + tokensForArticle > maxTokensPerQuestion) {
+        break;
+      }
 
-          if (currentTokenCount > maxTokens) {
-            return;
-          }
+      section += articleBlock;
+      sectionTokenCount += tokensForArticle;
+    }
 
-          context += additionalContext;
-        });
+    if (currentTokenCount + sectionTokenCount > maxTotalTokens - buffer) {
+      break;
     }
-  });
 
-  const questionContext = '[QUESTION]\n\n' + question;
-  context += questionContext;
-  return context.trim();
-};
+    prompt += section;
+    currentTokenCount += sectionTokenCount;
+  }
+  const questionContext = '[QUESTION]\n\n' + initialQuestion;
+  prompt += questionContext;
+  return prompt.trim();
+}
 
 /**
  * Split an array into smaller chunks of a given size.
@@ -301,7 +289,7 @@ function chunkArray(array, size) {
  * @returns {Promise<object>} A map of embeddings structured as:
  *    { [contentId]: { [key]: { chunk, embedding } } }
  */
-async function embedChunksInBatch(agent, allChunks, batchSize = 500) {
+async function embedChunksInBatch(agent, allChunks, batchSize = 50) {
   const embeddingsByContent = {};
 
   for (let start = 0; start < allChunks.length; start += batchSize) {
@@ -340,5 +328,5 @@ module.exports = {
   getPDFImages,
   sliceText,
   groupSentences,
-  buildPromptFromArticles,
+  buildPromptFromArticlesMulti,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goblin-agents",
-  "version": "0.1.5",
+  "version": "0.1.10",
   "description": "AI Agents framework",
   "author": "Samuel Loup",
   "license": "MIT",