goblin-agents 2.1.0 → 2.2.2

package/lib/llm/aiAgent.js

@@ -12,8 +12,9 @@ const {
   record,
 } = require('xcraft-core-stones');
 const {getMutex} = require('xcraft-core-utils/lib/locks.js');
-const LLMProvider = require('./providers.js');
+const LLMProviders = require('./providers.js');
 const {OCR_SYSTEM_PROMPT, getPDFImages, splitThinkTags} = require('./utils.js');
+const Logger = require('../logger.js');
 
 class MessageShape {
   role = enumeration('assistant', 'user', 'tool');
@@ -129,6 +130,17 @@ function vectorToSqlLiteralInt8(vec) {
   return hex;
 }
 
+function cleanText(text) {
+  if (typeof text !== 'string') {
+    return text;
+  }
+  const {thinks, cleanText} = splitThinkTags(text);
+  for (const think of thinks) {
+    this.log.dbg(`🧐 ${think}`);
+  }
+  return cleanText;
+}
+
 class AiAgentShape {
   id = id('aiAgent');
   version = number;
@@ -294,7 +306,7 @@ class AiAgent extends Elf {
 
   _provider;
   _conf;
-  _batchLock = getMutex;
+  _mutex = getMutex;
 
   /**
    * @param {string} id
@@ -341,7 +353,7 @@ class AiAgent extends Elf {
       return;
     }
 
-    const Instance = LLMProvider.get(this.state.provider);
+    const Instance = LLMProviders.get(this.state.provider);
     this._provider = new Instance(this.state.host, this.state.headers.toJS());
     this._conf = {provider, host, headersStr};
   }
@@ -367,27 +379,45 @@ class AiAgent extends Elf {
     await this.persist();
   }
 
-  async gen(prompt) {
+  async gen(prompt, contextId = 'default') {
+    const logger = Logger.get(contextId, this);
+
+    await this._mutex.lock(this.id);
+    this.quest.defer(() => this._mutex.unlock(this.id));
+
     await this._loadProvider();
 
     let options;
     if (this.state.options) {
       options = this.state.options.toJS();
     }
-    const res = await this._provider.gen({
+    const format = this.state.format
+      ? typeof this.state.format === 'string'
+        ? this.state.format
+        : this.state.format.toJS()
+      : undefined;
+    let res = await this._provider.gen({
       model: this.state.model,
       reasoning: this.state.reasoning,
       prompt,
       system: this.state.prompt,
-      format: this.state.format?.toJS(),
+      format,
       options,
       stream: false,
     });
-    const {thinks, cleanText} = splitThinkTags(res);
-    for (const think of thinks) {
-      this.log.dbg(`🧐 ${think}`);
-    }
-    return cleanText;
+
+    logger.push('aiAgent.gen', {
+      id: this.id,
+      model: this.state.model,
+      options: Object.entries(options).reduce(
+        (out, opt) => `${out} ${opt[0]}=${opt[1]}`,
+        ''
+      ),
+      reasoning: this.state.reasoning,
+      format: format || 'N/A',
+    });
+
+    return cleanText(res);
   }
 
   async reset(contextId, save = false) {
@@ -404,6 +434,9 @@ class AiAgent extends Elf {
   }
 
   async readPDFpages(pdfPath) {
+    await this._mutex.lock(this.id);
+    this.quest.defer(() => this._mutex.unlock(this.id));
+
     await this._loadProvider();
 
     const images = await getPDFImages(pdfPath);
@@ -440,6 +473,10 @@ class AiAgent extends Elf {
     if (!rawText) {
       return null;
     }
+
+    await this._mutex.lock(this.id);
+    this.quest.defer(() => this._mutex.unlock(this.id));
+
     await this._loadProvider();
     const vectors = await this._provider.embed({
       model: this.state.model,
@@ -457,8 +494,8 @@ class AiAgent extends Elf {
       return [];
     }
 
-    await this._batchLock.lock(this.id);
-    this.quest.defer(() => this._batchLock.unlock(this.id));
+    await this._mutex.lock(this.id);
+    this.quest.defer(() => this._mutex.unlock(this.id));
 
     await this._loadProvider();
     const res = await this._provider.embedInBatch({
@@ -477,6 +514,11 @@ class AiAgent extends Elf {
   }
 
   async chat(contextId, question, userDesktopId) {
+    const logger = Logger.get(contextId, this);
+
+    await this._mutex.lock(this.id);
+    this.quest.defer(() => this._mutex.unlock(this.id));
+
     await this._loadProvider();
     const contextMessages = this.state.messages[contextId] || [];
     const messages = [
@@ -509,6 +551,18 @@ class AiAgent extends Elf {
 
     const result = await this._provider.chat(chatCompletionRequest);
 
+    logger.push('aiAgent.chat', {
+      id: this.id,
+      model: chatCompletionRequest.model,
+      options: Object.entries(chatCompletionRequest.options).reduce(
+        (out, opt) => `${out} ${opt[0]}=${opt[1]}`,
+        ''
+      ),
+      question,
+      reasoning: result.message?.reasoning,
+      callTools: !!result.message.tool_calls?.length,
+    });
+
     if (this.state.toolServiceId && this.state.tools) {
       const used = await this.callTools(
         contextId,
@@ -522,23 +576,22 @@ class AiAgent extends Elf {
       }
     }
 
-    //keep agent response
-    const {thinks, cleanText} = splitThinkTags(result.message.content);
-    this.logic.chat(contextId, 'assistant', cleanText);
-    for (const think of thinks) {
-      this.log.dbg(`🧐 ${think}`);
+    const res = cleanText(result.message.content);
+    if (typeof res === 'string') {
+      //keep agent response
+      this.logic.chat(contextId, 'assistant', cleanText);
     }
-    this.log.dbg(`🐈 Chat session ended : ${contextId}`);
 
-    return cleanText;
+    this.log.dbg(`🐈 Chat session ended : ${contextId}`);
+    return res;
   }
 
   async callTools(contextId, message, userDesktopId) {
-    const {tool_calls, content} = message;
+    const {tool_calls} = message;
     if (!tool_calls || !userDesktopId) {
       return false;
     }
-    this.logic.callTools(contextId, content, tool_calls);
+    this.logic.callTools(contextId, tool_calls);
     for (const tool of tool_calls) {
       const {
         id,
@@ -585,6 +638,10 @@ class AiAgent extends Elf {
     if (this.state.provider !== 'ollama') {
       throw new Error('Streaming API not impl.');
     }
+
+    await this._mutex.lock(this.id);
+    this.quest.defer(() => this._mutex.unlock(this.id));
+
     await this._loadProvider();
 
     const contextMessages = this.state.messages[contextId] || [];
@@ -619,6 +676,9 @@ class AiAgent extends Elf {
   }
 
   async resumeExchange(resumePrompt, contextId) {
+    await this._mutex.lock(this.id);
+    this.quest.defer(() => this._mutex.unlock(this.id));
+
     await this._loadProvider();
     const contextMessages = this.state.messages[contextId] || [];
 
@@ -643,6 +703,9 @@ class AiAgent extends Elf {
   }
 
   async react(reactPrompt, contextId, question) {
+    await this._mutex.lock(this.id);
+    this.quest.defer(() => this._mutex.unlock(this.id));
+
     await this._loadProvider();
     const feedId = await this.newQuestFeed();
     const contextMessages = this.state.messages[contextId] || [];

package/lib/llm/providers/ollama.js

@@ -0,0 +1,97 @@
+// @ts-check
+const {Ollama} = require('ollama');
+const {Semaphore} = require('xcraft-core-utils/lib/locks.js');
+const LLMProvider = require('./provider.js');
+
+class OllamaProvider extends LLMProvider {
+  #semEmbed = new Semaphore(4);
+  #ollama;
+
+  constructor(host, headers) {
+    super();
+    this.#ollama = new Ollama({
+      host,
+      headers,
+    });
+  }
+
+  async chat(chatRequest) {
+    const {
+      model,
+      messages,
+      options,
+      format,
+      tools,
+      stream,
+      reasoning,
+    } = chatRequest;
+    const useFormat = !!format;
+    const chat = await this.#ollama.chat({
+      model,
+      messages,
+      options,
+      format,
+      tools,
+      stream,
+      think: reasoning,
+    });
+    if (useFormat) {
+      chat.message.content = JSON.parse(chat.message.content);
+      return chat;
+    } else {
+      return chat;
+    }
+  }
+
+  async gen(genRequest) {
+    const {
+      model,
+      system,
+      prompt,
+      format,
+      options,
+      stream,
+      reasoning,
+    } = genRequest;
+    const useFormat = !!format;
+    const gen = await this.#ollama.generate({
+      model,
+      prompt,
+      system,
+      format,
+      options,
+      stream,
+      think: reasoning,
+    });
+    if (useFormat) {
+      return JSON.parse(gen.response);
+    } else {
+      return gen.response;
+    }
+  }
+
+  async embed(embedRequest) {
+    try {
+      await this.#semEmbed.wait();
+      const {model, input} = embedRequest;
+      const {embeddings} = await this.#ollama.embed({
+        model,
+        input,
+      });
+      return embeddings[0];
+    } finally {
+      this.#semEmbed.signal();
+    }
+  }
+
+  async embedInBatch(embedRequest) {
+    const {model, input} = embedRequest;
+    const {embeddings} = await this.#ollama.embed({
+      model,
+      input,
+    });
+    return embeddings;
+  }
+}
+
+module.exports = OllamaProvider;

package/lib/llm/providers/opanAi.js

@@ -0,0 +1,101 @@
+// @ts-check
+const {RestAPI} = require('xcraft-core-utils');
+const LLMProvider = require('./provider.js');
+
+class OpenAIProvider extends LLMProvider {
+  #baseUrl;
+  #openAI;
+
+  constructor(host = 'https://openrouter.ai/api/v1', headers) {
+    super();
+    this.#baseUrl = host;
+    this.#openAI = new RestAPI(300000, headers);
+  }
+
+  async chat(chatRequest) {
+    delete chatRequest.reasoning; //not yet supported
+    if (chatRequest.options) {
+      chatRequest = {...chatRequest, ...chatRequest.options};
+      delete chatRequest.options;
+    }
+    if (!chatRequest.tools) {
+      delete chatRequest.tools;
+    }
+    if (!chatRequest.format) {
+      delete chatRequest.format;
+    }
+    const useFormat = chatRequest?.format !== undefined;
+    if (useFormat) {
+      chatRequest.response_format = {
+        type: 'json_schema',
+        json_schema: {
+          name: 'default',
+          schema: {
+            type: 'object',
+            properties: {
+              results: {...chatRequest.format},
+            },
+            required: ['results'],
+          },
+        },
+      };
+
+      delete chatRequest.format;
+    }
+    const query = `${this.#baseUrl}/chat/completions`;
+    const chat = await this.#openAI._post(query, chatRequest, {
+      retry: {
+        methods: ['POST'],
+      },
+    });
+    const {choices} = chat;
+    if (chat.error) {
+      const err = new Error(
+        chat.error?.metadata
+          ? JSON.stringify(chat.error?.metadata)
+          : chat.error.message
+      );
+      err.code = chat.error.code;
+      throw err;
+    }
+    if (useFormat) {
+      choices[0].message.content = JSON.parse(
+        choices[0].message.content
+      ).results;
+      return choices[0];
+    } else {
+      return choices[0];
+    }
+  }
+
+  async gen(genRequest) {
+    const {model, system, prompt, format, tools, options, stream} = genRequest;
+    const chatRequest = {
+      model,
+      messages: [
+        {role: 'system', content: system},
+        {role: 'user', content: prompt},
+      ],
+      options,
+      format,
+      tools,
+      stream,
+    };
+    const chat = await this.chat(chatRequest);
+    return chat.message.content;
+  }
+
+  async embed(embedRequest) {
+    const query = `${this.#baseUrl}/v1/embeddings`;
+    const {data} = await this.#openAI._post(query, embedRequest);
+    return data[0].embedding;
+  }
+
+  async embedInBatch(embedRequest) {
+    const query = `${this.#baseUrl}/v1/embeddings`;
+    const {data} = await this.#openAI._post(query, embedRequest);
+    return data;
+  }
+}
+
+module.exports = OpenAIProvider;

package/lib/llm/providers/provider.js

@@ -0,0 +1,36 @@
+// @ts-check
+
+class LLMProvider {
+  constructor() {
+    if (new.target === LLMProvider) {
+      throw new Error('Cannot instantiate an abstract class.');
+    }
+  }
+
+  async chatStream() {
+    throw new Error('not impl.');
+  }
+
+  /**
+   * @returns {Promise<*>}
+   */
+  async chat() {
+    throw new Error('not impl.');
+  }
+
+  /**
+   * @returns {Promise<*>}
+   */
+  async gen() {
+    throw new Error('not impl.');
+  }
+
+  /**
+   * @returns {Promise<*>}
+   */
+  async embed() {
+    throw new Error('not impl.');
+  }
+}
+
+module.exports = LLMProvider;

package/lib/llm/providers.js

@@ -1,8 +1,8 @@
-const {Ollama} = require('ollama');
-const {RestAPI} = require('xcraft-core-utils');
-const {Semaphore} = require('xcraft-core-utils/lib/locks.js');
+// @ts-check
+const OllamaProvider = require('./providers/ollama.js');
+const OpenAIProvider = require('./providers/opanAi.js');
 
-class LLMProvider {
+class LLMProviders {
   static get(name) {
     switch (name) {
       default:
@@ -12,215 +12,6 @@ class LLMProvider {
         return OpenAIProvider;
     }
   }
-
-  constructor() {
-    if (new.target === LLMProvider) {
-      throw new Error('Cannot instantiate an abstract class.');
-    }
-  }
-
-  async chatStream() {
-    throw new Error('not impl.');
-  }
-
-  async chat() {
-    throw new Error('not impl.');
-  }
-
-  async gen() {
-    throw new Error('not impl.');
-  }
-
-  async embed() {
-    throw new Error('not impl.');
-  }
-}
-
-class OllamaProvider extends LLMProvider {
-  #semEmbed = new Semaphore(4);
-  #ollama;
-
-  constructor(host, headers) {
-    super();
-    this.#ollama = new Ollama({
-      host,
-      headers,
-    });
-  }
-
-  async chat(chatRequest) {
-    const {
-      model,
-      messages,
-      options,
-      format,
-      tools,
-      stream,
-      reasoning,
-    } = chatRequest;
-    const useFormat = !!format;
-    const chat = await this.#ollama.chat({
-      model,
-      messages,
-      options,
-      format,
-      tools,
-      stream,
-      think: reasoning,
-    });
-    if (useFormat) {
-      chat.message.content = JSON.parse(chat.message.content);
-      return chat;
-    } else {
-      return chat;
-    }
-  }
-
-  async gen(genRequest) {
-    const {
-      model,
-      system,
-      prompt,
-      format,
-      options,
-      stream,
-      reasoning,
-    } = genRequest;
-    const useFormat = !!format;
-    const gen = await this.#ollama.generate({
-      model,
-      prompt,
-      system,
-      format,
-      options,
-      stream,
-      think: reasoning,
-    });
-    if (useFormat) {
-      return JSON.parse(gen.response);
-    } else {
-      return gen.response;
-    }
-  }
-
-  async embed(embedRequest) {
-    try {
-      await this.#semEmbed.wait();
-      const {model, input} = embedRequest;
-      const {embeddings} = await this.#ollama.embed({
-        model,
-        input,
-      });
-      return embeddings[0];
-    } finally {
-      this.#semEmbed.signal();
-    }
-  }
-
-  async embedInBatch(embedRequest) {
-    const {model, input} = embedRequest;
-    const {embeddings} = await this.#ollama.embed({
-      model,
-      input,
-    });
-    return embeddings;
-  }
-}
-
-class OpenAIProvider extends LLMProvider {
-  #baseUrl;
-  #openAI;
-
-  constructor(host = 'https://openrouter.ai/api/v1', headers) {
-    super();
-    this.#baseUrl = host;
-    this.#openAI = new RestAPI(300000, headers);
-  }
-
-  async chat(chatRequest) {
-    delete chatRequest.reasoning; //not yet supported
-    if (chatRequest.options) {
-      chatRequest = {...chatRequest, ...chatRequest.options};
-      delete chatRequest.options;
-    }
-    if (!chatRequest.tools) {
-      delete chatRequest.tools;
-    }
-    if (!chatRequest.format) {
-      delete chatRequest.format;
-    }
-    const useFormat = chatRequest?.format !== undefined;
-    if (useFormat) {
-      chatRequest.response_format = {
-        type: 'json_schema',
-        json_schema: {
-          name: 'default',
-          schema: {
-            type: 'object',
-            properties: {
-              results: {...chatRequest.format},
-            },
-            required: ['results'],
-          },
-        },
-      };
-
-      delete chatRequest.format;
-    }
-    const query = `${this.#baseUrl}/chat/completions`;
-    const chat = await this.#openAI._post(query, chatRequest, {
-      retry: {
-        methods: ['POST'],
-      },
-    });
-    const {choices} = chat;
-    if (chat.error) {
-      const err = new Error(
-        chat.error?.metadata
-          ? JSON.stringify(chat.error?.metadata)
-          : chat.error.message
-      );
-      err.code = chat.error.code;
-      throw err;
-    }
-    if (useFormat) {
-      choices[0].message.content = JSON.parse(
-        choices[0].message.content
-      ).results;
-      return choices[0];
-    } else {
-      return choices[0];
-    }
-  }
-
-  async gen(genRequest) {
-    const {model, system, prompt, format, tools, options, stream} = genRequest;
-    const chatRequest = {
-      model,
-      messages: [
-        {role: 'system', content: system},
-        {role: 'user', content: prompt},
-      ],
-      options,
-      format,
-      tools,
-      stream,
-    };
-    const chat = await this.chat(chatRequest);
-    return chat.message.content;
-  }
-
-  async embed(embedRequest) {
-    const query = `${this.#baseUrl}/v1/embeddings`;
-    const {data} = await this.#openAI._post(query, embedRequest);
-    return data[0].embedding;
-  }
-
-  async embedInBatch(embedRequest) {
-    const query = `${this.#baseUrl}/v1/embeddings`;
-    const {data} = await this.#openAI._post(query, embedRequest);
-    return data;
-  }
 }
 
-module.exports = LLMProvider;
+module.exports = LLMProviders;

package/lib/llm/utils.js

@@ -236,8 +236,23 @@ function groupSentences(text, maxSize) {
   return chunks;
 }
 
+/**
+ * Construit un prompt à partir d'une liste d'articles, avec gestion du format et de la limite de tokens.
+ *
+ * @param {ArticleShape[]} articles - Liste des articles sources utilisés pour générer le prompt.
+ * @param {"text"|"json"} [format="text"] - Format de sortie attendu :
+ *   - `"text"` → prompt en texte brut
+ *   - `"json"` → prompt structuré en JSON
+ * @param {number} [maxTotalTokens] - Nombre maximal de tokens autorisés dans le prompt.
+ *   Si non défini, aucun contrôle n'est appliqué.
+ * @param {function} [dbg=() => null] - Fonction de débogage optionnelle appelée
+ *   avec des informations intermédiaires (signature `(info: any) => void`).
+ * @returns {string} - Le prompt généré, soit en texte brut (string),
+ *   soit en objet JSON stringifié selon le format choisi.
+ */
 function buildPromptFromArticlesMulti(
   articles,
+  format = 'text',
   maxTotalTokens,
   dbg = () => null
 ) {
@@ -247,15 +262,23 @@ function buildPromptFromArticlesMulti(
   let sections = [];
   let sectionTokenCount = 0;
   for (const article of articles) {
-    const {kind, title, sourceId, distance, combinedScore, chunk} = article;
-    const articleBlock = JSON.stringify({
-      kind,
-      title,
-      url: sourceId.startsWith('http') ? sourceId : null,
-      distance,
-      combinedScore,
-      chunk,
-    });
+    const {kind, title, sourceId, description, finalScore} = article;
+
+    let articleBlock = '';
+    if (format === 'json') {
+      articleBlock = JSON.stringify({
+        kind,
+        title,
+        url: sourceId.startsWith('http') ? sourceId : null,
+        finalScore,
+        description,
+      });
+    } else {
+      articleBlock += `# ${title}\n\n`;
+      articleBlock += `**score :** ${finalScore}\n\n`;
+      articleBlock += `\`\`\`html\n${description}\n\`\`\`\n\n`;
+    }
+
     dbg(articleBlock);
     const tokensForArticle = estimateTokenCount(articleBlock);
 
@@ -268,7 +291,10 @@ function buildPromptFromArticlesMulti(
     sectionTokenCount += tokensForArticle;
   }
 
-  return `[${sections.join(',')}]`;
+  if (format === 'json') {
+    return `[${sections.join(',')}]`;
+  }
+  return sections.join('---\n\n');
 }
 
 /**

package/lib/logger.js

@@ -0,0 +1,104 @@
+// @ts-check
+const path = require('node:path');
+const fse = require('fs-extra');
+const {string, Sculpt, dateTime, object} = require('xcraft-core-stones');
+const xConfig = require('xcraft-core-etc')().load('xcraft');
+
+class MessageShape {
+  timestamp = dateTime;
+  step = string;
+  payload = object;
+}
+
+class Message extends Sculpt(MessageShape) {}
+
+class Logger {
+  #id;
+
+  /** @type {Set<Message>} */
+  #messages = new Set();
+
+  /** @type {Map<string, Logger>} */
+  static #loggers = new Map();
+  static #logDir = path.join(xConfig.xcraftRoot, 'var/log/ai');
+
+  constructor(id) {
+    this.#id = id;
+    fse.ensureDirSync(Logger.#logDir);
+    Logger.#loggers.set(id, this);
+  }
+
+  /**
+   * @param {string} step
+   * @param {object} payload
+   */
+  push(step, payload) {
+    const timestamp = new Date().toISOString();
+    const msg = new Message({timestamp, step, payload});
+    this.#messages.add(msg);
+  }
+
+  async #report() {
+    let timestamp = new Date().toISOString();
+    let messages = '';
+
+    for (const message of this.#messages) {
+      timestamp = message.timestamp;
+
+      const messageFile = path.join(__dirname, 'report/message.html');
+      let reportMessage = await fse.readFile(messageFile, 'utf8');
+
+      let payload = '';
+      for (const [key, value] of Object.entries(message.payload)) {
+        const itemFile = path.join(__dirname, 'report/item.html');
+        let reportItem = await fse.readFile(itemFile, 'utf8');
+        payload += reportItem
+          .replace('${KEY}', key)
+          .replace('${VALUE}', `${value}`.replaceAll('\n', '<br/>'));
+      }
+
+      messages += reportMessage
+        .replace('${TIMESTAMP}', message.timestamp)
+        .replace('${STEP}', message.step)
+        .replace('${PAYLOAD}', payload);
+    }
+
+    const reportFile = path.join(__dirname, 'report/report.html');
+    let report = await fse.readFile(reportFile, 'utf8');
+    report = report
+      .replace('${MESSAGES}', messages)
+      .replace('${TITLE}', `AI reporting for ${this.#id}`);
+
+    const ts = timestamp.split(':').slice(0, 2).join('').split('-').join('');
+    const reportOutput = path.join(Logger.#logDir, `${this.#id}_${ts}Z.html`);
+    await fse.writeFile(reportOutput, report, 'utf8');
+  }
+
+  async dispose() {
+    if (this.#id && this.#id !== 'default') {
+      await this.#report();
+    }
+    Logger.#loggers.delete(this.#id);
+  }
+
+  static get(id, quest) {
+    if (quest.quest) {
+      quest = quest.quest;
+    }
+    if (Logger.#loggers.has(id)) {
+      const logger = Logger.#loggers.get(id);
+      if (logger) {
+        return logger;
+      }
+    }
+    const logger = new Logger(id);
+    quest.defer(async () => await logger.dispose());
+    return logger;
+  }
+
+  static get logDir() {
+    return Logger.#logDir;
+  }
+}
+
+module.exports = Logger;

package/lib/report/item.html

@@ -0,0 +1,2 @@
+<dt><strong>${KEY}:</strong></dt>
+<dd>${VALUE}</dd>

package/lib/report/message.html

@@ -0,0 +1,8 @@
+<h2>${STEP}</h2>
+<p>
+  <small><em>${TIMESTAMP}</em></small>
+</p>
+<dl>
+  ${PAYLOAD}
+</dl>
+<hr />

package/lib/report/report.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <title>${TITLE}</title>
+  </head>
+  <body>
+    ${MESSAGES}
+  </body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goblin-agents",
-  "version": "2.1.0",
+  "version": "2.2.2",
   "description": "AI Agents framework",
   "author": "Epsitec SA",
   "contributors": [