goblin-agents 0.1.4 → 0.1.10

package/README.md

@@ -0,0 +1,373 @@
+# 📘 Documentation du module 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.
+
+## 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, avec une séparation claire entre la logique métier (`AiAgentLogic`) et l'interface de l'acteur (`AiAgent`).
+
+## 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.
+
+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
+- 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
+
+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.
+
+## Exemples d'utilisation
+
+### Création d'un agent IA
+
+```javascript
+const {AiAgent} = require('goblin-agents/lib/llm/aiAgent.js');
+
+// Dans une méthode d'un acteur Elf
+async initAgents() {
+  const feedId = await this.newQuestFeed();
+
+  // Création d'un agent avec Ollama (local)
+  const ollamaAgentId = SmartId.from('aiAgent', 'ollama-mistral-assistant');
+  const agent = await new AiAgent(this).create(ollamaAgentId, 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'
+  });
+
+  // Création d'un agent avec OpenAI (cloud)
+  const openAiAgentId = SmartId.from('aiAgent', 'gpt-4o-assistant');
+  const agent = await new AiAgent(this).create(openAiAgentId, feedId, {
+    name: 'Assistant Personnel',
+    role: 'assistant',
+    provider: 'open-ai',
+    model: 'openai/gpt-4o',
+    host: 'https://openrouter.ai/api/v1',
+    headers: {
+      Authorization: `Bearer <votre-clef-api>`,
+    },
+    usability: 'stable'
+  });
+```
+
+### 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
+  const response = await agent.chat(contextId, question, desktopId);
+
+  if(saveExchange) {
+    //Persiste l'échange contextuel nouvelle paire (question->réponse) sur le disque
+    await agent.save();
+  }
+  return response;
+}
+```
+
+### 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);
+
+  // Demande un résumé des échanges
+  const resumePrompt = "Résume l'essentiel de nos échanges en utilisant l'historique des messages";
+  const resumedContent = await agent.resumeExchange(resumePrompt, 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é
+  await agent.set(contextId, [{role: 'assistant', content: resumedContent}]);
+
+  // Sauve ce nouvel état
+  await agent.save();
+}
+```
+
+### 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);
+
+  // 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"
+    tools: [
+      {
+        type: 'function',
+        function: {
+          name: 'getWeather', //nom de la quête de l'acteur qui récupère la météo
+          description: 'Obtenir la météo pour une ville',
+          parameters: {
+            type: 'object',
+            properties: {
+              city: {
+                type: 'string',
+                description: 'Nom de la ville'
+              }
+            },
+            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);
+```
+
+### Génération d'embeddings pour la recherche sémantique
+
+```javascript
+// Dans une méthode d'un acteur Elf
+// {
+//  'indexContent@article-1', 'Contenu à indexer'
+//  'indexContent@article-2', 'Un autre contenu à indexer'
+// }
+//
+async updateKnowledgeBase(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 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
+    );
+  }
+}
+
+// Dans une méthode d'un acteur Elf
+async queryKnowledgeBase(question = "Comment fonctionne l'apprentissage par renforcement?") {
+  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);
+
+  // Générer un embedding pour un texte, par ex. pour une recherche
+  // Convertit la question texte en vecteurs
+  const vectors = await agent.embed(question);
+
+  // Effectue une recherche par similitude dans cryo
+  // Utilise un Archetype "IndexedContent"
+  // Limite la recherche au contenu indexé en français
+  // avec un scope 'knowledge-base'
+  // les 100 premier résultats les plus pertinents
+  const results = await this.cryo.searchDistance2(
+    IndexedContentLogic.db,
+    vectors,
+    ['fr'],
+    ['knowledge-base'],
+    100
+  );
+
+  // Itère sur les données et retourne les résultats
+  // a l'appelant
+  return Array.from(results);
+}
+```
+
+## Interactions avec d'autres modules
+
+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
+
+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
+
+| 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
+
+### `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.
+
+### `config.js`
+
+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`)
+- Les paramètres par nom (`settings`)
+
+Cette configuration permet de personnaliser le comportement des agents au niveau de l'application.
+
+### `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
+
+#### É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`
+
+Ce fichier définit les classes pour interagir avec différents fournisseurs de LLM :
+
+- **LLMProvider** : Classe abstraite définissant l'interface commune
+- **OllamaProvider** : Implémentation pour le fournisseur Ollama (local)
+- **OpenAIProvider** : Implémentation pour OpenAI et services compatibles
+
+Ces classes encapsulent les détails d'implémentation spécifiques à chaque fournisseur, offrant une interface unifiée pour le reste du module. Elles gèrent les différences dans les formats de requête et de réponse, permettant à l'acteur AiAgent de fonctionner de manière transparente avec différents fournisseurs.
+
+### `lib/llm/utils.js`
+
+Ce fichier contient diverses fonctions utilitaires pour :
+
+- Extraction de texte à partir d'images PDF (`getPDFImages`)
+- Nettoyage et simplification de contenu HTML (`cleanHtmlContent`, `simplifyHtml`)
+- Découpage de texte en segments gérables (`splitLongText`, `html2chunks`)
+- Estimation du nombre de tokens (`estimateTokenCount`)
+- Construction de prompts à partir d'articles (`buildPromptFromArticles`)
+- Traitement par lots des embeddings (`embedChunksInBatch`, `chunkArray`)
+
+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.
+
+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.
+
+_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.4",
+  "version": "0.1.10",
   "description": "AI Agents framework",
   "author": "Samuel Loup",
   "license": "MIT",