goblin-agents 3.1.1 → 3.3.0

package/contextCache.js

@@ -0,0 +1,4 @@
+const {Elf} = require('xcraft-core-goblin');
+const {ContextCache, ContextCacheLogic} = require('./lib/contextCache.js');
+
+exports.xcraftCommands = Elf.birth(ContextCache, ContextCacheLogic);

package/lib/contextCache.js

@@ -0,0 +1,69 @@
+// @ts-check
+const {Elf} = require('xcraft-core-goblin');
+const {record, string} = require('xcraft-core-stones');
+
+class ContextCacheShape {
+  id = string;
+  contexts = record(string, string);
+}
+
+class ContextCacheState extends Elf.Sculpt(ContextCacheShape) {}
+
+class ContextCacheLogic extends Elf.Spirit {
+  state = new ContextCacheState({
+    id: 'contextCache',
+    contexts: {},
+  });
+
+  append(contextId, markdown) {
+    const current = this.state.contexts[contextId] || '';
+    this.state.contexts[contextId] = current + markdown;
+  }
+
+  clear(contextId) {
+    delete this.state.contexts[contextId];
+  }
+}
+
+class ContextCache extends Elf.Alone {
+  logic = Elf.getLogic(ContextCacheLogic);
+  state = new ContextCacheState();
+
+  async init() {
+    return this;
+  }
+
+  async append(contextId, markdown) {
+    if (typeof contextId !== 'string') {
+      throw new TypeError('contextId must be a string');
+    }
+    if (typeof markdown !== 'string') {
+      throw new TypeError('markdown must be a string');
+    }
+
+    this.logic.append(contextId, markdown);
+  }
+
+  async read(contextId) {
+    if (typeof contextId !== 'string') {
+      throw new TypeError('contextId must be a string');
+    }
+
+    return this.state.contexts[contextId] || '';
+  }
+
+  async clear(contextId) {
+    if (typeof contextId !== 'string') {
+      throw new TypeError('contextId must be a string');
+    }
+
+    this.logic.clear(contextId);
+  }
+}
+
+module.exports = {
+  ContextCache,
+  ContextCacheLogic,
+  ContextCacheShape,
+  ContextCacheState,
+};

package/lib/llm/aiAgent.js

@@ -13,7 +13,12 @@ const {
 } = require('xcraft-core-stones');
 const {getMutex} = require('xcraft-core-utils/lib/locks.js');
 const LLMProviders = require('./providers.js');
-const {OCR_SYSTEM_PROMPT, getPDFImages, splitThinkTags} = require('./utils.js');
+const {
+  OCR_SYSTEM_PROMPT,
+  getPDFImages,
+  splitThinkTags,
+  getContextUsage,
+} = require('./utils.js');
 const Logger = require('../logger.js');
 
 const CONVERSATION_TITLE_PROMPT = `Create a concise and informative title that summarizes the main topic of the conversation.
@@ -30,6 +35,15 @@ class MessageShape {
   tool_name = option(string);
 }
 
+class UsageShape {
+  used = number;
+  reserved = number;
+  remaining = number;
+  total = number;
+  percentage = number;
+  nearLimit = boolean;
+}
+
 class OptionsShape {
   // Active NUMA (Non-Uniform Memory Access) pour optimiser la gestion mémoire sur les architectures multi-sockets.
   numa = option(boolean);
@@ -150,6 +164,7 @@ class AiAgentShape {
   role = string; //agent role
   prompt = string; //default system prompt
   contexts = record(string, string); //additionnal system prompt context
+  usages = record(string, UsageShape);
   reasonings = record(
     string,
     enumeration(false, true, 'low', 'medium', 'high')
@@ -204,6 +219,7 @@ class AiAgentLogic extends Elf.Archetype {
     provider: defaultValues.provider,
     model: defaultValues.model,
     otherModels: defaultValues.otherModels,
+    usages: {},
     messages: {},
     contexts: {},
     reasonings: {},
@@ -239,10 +255,21 @@ class AiAgentLogic extends Elf.Archetype {
     this.patch(patch);
     state.version = version;
   }
+  _updateContextUsage(contextId, usage) {
+    this.state.usages[contextId] = usage;
+  }
 
   reset(contextId) {
     const {state} = this;
     state.messages[contextId] = [];
+    state.usages[contextId] = {
+      used: 0,
+      reserved: 0,
+      remaining: this.state.options?.num_ctx || 4096,
+      total: this.state.options?.num_ctx || 4096,
+      percentage: 0,
+      nearLimit: false,
+    };
     if (state.contexts[contextId]) {
       delete state.contexts[contextId];
     }
@@ -470,8 +497,8 @@ class AiAgent extends Elf {
     return cleanText(res);
   }
 
-  async reset(contextId, save = false) {
-    if (!contextId) {
+  async reset(contextId = null, save = false) {
+    if (contextId === null) {
       for (const contextId of Object.keys(this.state.messages)) {
         await this.reset(contextId);
       }
@@ -509,7 +536,7 @@ class AiAgent extends Elf {
           ],
         },
       ];
-      const result = await this._provider.chat({
+      const {result} = await this._provider.chat({
         model: this.state.model,
         reasoning: this.state.reasoning,
         messages,
@@ -542,7 +569,7 @@ class AiAgent extends Elf {
         ],
       },
     ];
-    const result = await this._provider.chat({
+    const {result} = await this._provider.chat({
       model: this.state.model,
       reasoning: this.state.reasoning,
       messages,
@@ -594,6 +621,37 @@ class AiAgent extends Elf {
     this.logic.set(contextId, messages);
   }
 
+  async getContextUsage(contextId) {
+    const usage = this.state.usages[contextId];
+    if (!usage) {
+      return {
+        used: 0,
+        reserved: 0,
+        remaining: this.state.options?.num_ctx || 4096,
+        total: this.state.options?.num_ctx || 4096,
+        percentage: 0,
+        nearLimit: false,
+      };
+    }
+    return {
+      used: usage.used,
+      reserved: usage.reserved,
+      remaining: usage.remaining,
+      total: usage.total,
+      percentage: usage.percentage,
+      nearLimit: usage.nearLimit,
+    };
+  }
+
+  async _updateContextUsage(contextId, response) {
+    const usage = getContextUsage(
+      response,
+      this.state.options?.num_ctx || undefined,
+      this.state.options?.num_predict || undefined
+    );
+    this.logic._updateContextUsage(contextId, usage);
+  }
+
   /**
    * Set chat session context, model and level of reasoning
    * @param {string} contextId
@@ -673,8 +731,8 @@ ${context}
       tools: disableTool ? undefined : this.state.tools?.toJS(),
     };
 
-    const result = await this._provider.chat(chatCompletionRequest);
-
+    const {result, usage} = await this._provider.chat(chatCompletionRequest);
+    await this._updateContextUsage(contextId, usage);
     logger.push('aiAgent.chat', {
       id: this.id,
       model: chatCompletionRequest.model,
@@ -695,7 +753,7 @@ ${context}
       );
       if (used) {
         //leave for a second turn
-        this.log.dbg(`🐈 Chat session ended : ${contextId}`);
+        this.log.dbg(`🐈 Chat session ended by a tool call: ${contextId}`);
         return true;
       }
     }
@@ -712,7 +770,7 @@ ${context}
 
   async callTools(contextId, message, userDesktopId) {
     const {tool_calls} = message;
-    if (!tool_calls || !userDesktopId) {
+    if (!tool_calls?.length || !userDesktopId) {
       return false;
     }
     this.logic.callTools(contextId, tool_calls);
@@ -722,20 +780,19 @@ ${context}
         function: {name},
       } = tool;
 
-      let result = '';
-      let toolArguments = {};
-      if (
-        tool.function.arguments &&
-        typeof tool.function.arguments === 'string'
-      ) {
-        toolArguments = JSON.parse(tool.function.arguments);
-      } else if (
-        tool.function.arguments &&
-        typeof tool.function.arguments === 'object'
-      ) {
-        toolArguments = tool.function.arguments;
-      }
       try {
+        let toolArguments = {};
+        if (
+          tool.function.arguments &&
+          typeof tool.function.arguments === 'string'
+        ) {
+          toolArguments = JSON.parse(tool.function.arguments);
+        } else if (
+          tool.function.arguments &&
+          typeof tool.function.arguments === 'object'
+        ) {
+          toolArguments = tool.function.arguments;
+        }
         const payload = {
           id: this.state.toolServiceId,
           desktopId: userDesktopId,
@@ -745,10 +802,18 @@ ${context}
         const toolNamespace = this.state.toolServiceId?.split('@', 1)[0];
         const toolCmd = `${toolNamespace}.${name}`;
         this.log.dbg(`🔧 Tool call: ${toolCmd}(${JSON.stringify(payload)})`);
-        result = await this.quest.cmd(toolCmd, payload);
-        await this.addToolMessage(contextId, id, name, result);
+        const result = await this.quest.cmd(toolCmd, payload);
+        const content =
+          typeof result === 'string' ? result : JSON.stringify(result ?? null);
+        await this.addToolMessage(contextId, id, name, content);
       } catch (err) {
         this.log.dbg(`🔧 Tool error : ${err.message}`);
+        await this.addToolMessage(
+          contextId,
+          id,
+          name,
+          JSON.stringify({status: 'error', message: err.message})
+        );
       }
     }
     return true;

package/lib/llm/providers/ollama.js

@@ -37,9 +37,9 @@ class OllamaProvider extends LLMProvider {
     });
     if (useFormat) {
       chat.message.content = JSON.parse(chat.message.content);
-      return chat;
+      return {result: chat};
     } else {
-      return chat;
+      return {result: chat};
     }
   }
 

package/lib/llm/providers/opanAi.js

@@ -53,7 +53,7 @@ class OpenAIProvider extends LLMProvider {
         methods: ['POST'],
       },
     });
-    const {choices} = chat;
+    const {choices, usage} = chat;
     if (chat.error) {
       const err = new Error(
         chat.error?.metadata
@@ -67,9 +67,9 @@ class OpenAIProvider extends LLMProvider {
       choices[0].message.content = JSON.parse(
         choices[0].message.content
       ).results;
-      return choices[0];
+      return {result: choices[0], usage};
     } else {
-      return choices[0];
+      return {result: choices[0], usage};
     }
   }
 
@@ -96,8 +96,8 @@ class OpenAIProvider extends LLMProvider {
       stream,
       reasoning,
     };
-    const chat = await this.chat(chatRequest);
-    return chat.message.content;
+    const {result} = await this.chat(chatRequest);
+    return result.message.content;
   }
 
   async embed(embedRequest) {

package/lib/llm/utils.js

@@ -49,6 +49,9 @@ const getPDFImages = async (pdfPath, pagesToProcess) => {
 };
 
 const cleanHtmlContent = (html) => {
+  if (typeof html !== 'string') {
+    return '';
+  }
   const decodedHtml = HtmlEntities.decode(html);
   const textOnly = decodedHtml.replace(/<[^>]+>/g, '');
   const cleanedText = textOnly.replace(/\s+/g, ' ').trim();
@@ -379,6 +382,27 @@ function splitThinkTags(input) {
   };
 }
 
+function getContextUsage(usage, numCtx = 65536, maxTokens = 4096) {
+  const used = usage?.prompt_tokens ?? usage?.prompt_eval_count;
+
+  if (!Number.isFinite(used)) {
+    return null;
+  }
+
+  const available = Math.max(0, numCtx - used);
+  const reserved = Math.min(maxTokens, available);
+  const remaining = available - reserved;
+
+  return {
+    used,
+    reserved,
+    remaining,
+    total: numCtx,
+    percentage: Math.min(100, (used / numCtx) * 100),
+    nearLimit: used + maxTokens >= numCtx,
+  };
+}
+
 module.exports = {
   chunkArray,
   embedChunksInBatch,
@@ -394,4 +418,5 @@ module.exports = {
   groupSentences,
   buildPromptFromArticlesMulti,
   splitThinkTags,
+  getContextUsage,
 };

package/package.json

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