wingbot 3.76.3 → 3.76.4-alpha.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wingbot",
-  "version": "3.76.3",
+  "version": "3.76.4-alpha.10",
   "description": "Enterprise Messaging Bot Conversation Engine",
   "main": "index.js",
   "type": "commonjs",
@@ -76,4 +76,4 @@
     "axios": "^1.6.4",
     "handlebars": "^4.0.0"
   }
-}
+}

package/src/ChatGpt.js

@@ -441,6 +441,7 @@ class ChatGpt {
 
             this._log('#GPT request', body);
 
+            const startTime = Date.now();
             const response = await this._fetch(apiUrl, {
                 method: 'POST',
                 headers: {
@@ -470,7 +471,9 @@ class ChatGpt {
 
             const [choice] = responseData.choices;
 
-            this._log('#GPT response', { choice, responseData });
+            const durationMs = Date.now() - startTime;
+
+            this._log('#GPT response', { choice, responseData, durationMs });
 
             return choice;
         } catch (e) {

package/src/LLM.js

@@ -107,11 +107,13 @@ const LLMSession = require('./LLMSession');
  * @prop {'low'|'medium'|'high'|string} [verbosity]
  * @prop {'text'|SimpleJsonSchema} [responseFormat]
  * @prop {number} [temperature]
+ * @prop {number} [maxToolCallRounds]
  */
 
 /**
  * @typedef {object} LLMLogOptions
  * @prop {VectorSearchResult} [vectorSearchResult]
+ * @prop {ToolFunction[]} [tools]
  */
 
 /**
@@ -158,6 +160,9 @@ const LLMSession = require('./LLMSession');
  * @prop {LLMMessage[]} prompt
  * @prop {LLMMessage} result
  * @prop {VectorSearchResult} [vectorSearchResult]
+ * @prop {ToolFunction[]} [tools]
+ * @prop {number} [durationMs]
+ * @prop {string} [toolChoice]
  */
 
 /**
@@ -423,8 +428,17 @@ class LLM {
     async generate (session, preset = {}, logOptions = {}) {
         const opts = this.llmOptions(preset);
         const prompt = await session.toArray(true);
+        const startTime = Date.now();
         const result = await this._provider.requestChat(prompt, opts, session.tools);
-        this.logPrompt(prompt, result, logOptions.vectorSearchResult);
+        const durationMs = Date.now() - startTime;
+        this.logPrompt(
+            prompt,
+            result,
+            logOptions.vectorSearchResult,
+            session.tools,
+            durationMs,
+            opts.toolChoice
+        );
         return result;
     }
 
@@ -433,11 +447,19 @@ class LLM {
      * @param {LLMMessage[]} prompt
      * @param {LLMMessage} result
      * @param {VectorSearchResult} [vectorSearchResult]
+     * @param {ToolFunction[]} [tools]
+     * @param {number} [durationMs]
+     * @param {string} [toolChoice]
      */
-    logPrompt (prompt, result, vectorSearchResult) {
+    logPrompt (prompt, result, vectorSearchResult, tools, durationMs, toolChoice) {
         this._lastResult = result;
         this._configuration.logger.logPrompt({
-            prompt, result, vectorSearchResult
+            prompt,
+            result,
+            vectorSearchResult,
+            tools,
+            durationMs,
+            ...(toolChoice != null && { toolChoice })
         });
     }
 

package/src/LLMDispatcher.js

@@ -260,6 +260,7 @@ class LLMDispatcher {
                 ...routing,
                 actionList: [],
                 actionListString: '',
+                structuredOutput: LLMRouter.structuredOutput(),
                 byAction: new Map(),
                 router
             };

package/src/LLMRouter.js

@@ -66,7 +66,8 @@ const LLMType = require('./LLMType');
  */
 
 /**
- * @typedef {Pick<LLMRoutingCache, 'actionList'|'actionListString'|'byAction'>} LLMRoutingInput
+ * @typedef {Pick<LLMRoutingCache,
+ *   'actionList'|'actionListString'|'byAction'|'structuredOutput'>} LLMRoutingInput
  */
 
 /**
@@ -74,6 +75,7 @@ const LLMType = require('./LLMType');
  * @prop {boolean} [keepUserInInteractionsWithBounceAllowed]
  * @prop {string} actionListString
  * @prop {LLMAction[]} actionList
+ * @prop {object} structuredOutput - JSON schema for the routing response
  * @prop {ILLMRouter|null} router
  * @prop {Map<string, GlobalIntentResolved>} byAction
  * @prop {GlobalIntentResolved[]} routes
@@ -142,24 +144,31 @@ class LLMRouter {
     }
 
     /**
-     * @type {object}
+     * Sentinel action returned when the user did not change the conversation
+     * context (or when the model can't decide). Not present in `byAction`.
+     *
+     * @type {string}
      */
-    static _cachedStructuredOutput = null;
+    static NOT_CHANGED = '-not-changed-';
 
     /**
+     * Builds the JSON schema for the routing response. The `action` field is
+     * constrained to an enum of the routable actions plus the `-not-changed-`
+     * sentinel, so the model can only return a valid routing target.
+     *
+     * Called once per router config from `_prepareRoutingInput`; the result is
+     * stored on the routing cache, so it is not rebuilt per request.
      *
+     * @param {string[]} [actions] - routable action values (e.g. `/btm/dodavatel`)
      * @returns {object}
      */
-    static structuredOutput () {
-        if (LLMRouter._cachedStructuredOutput === null) {
-            LLMRouter._cachedStructuredOutput = LLMType
-                .object({
-                    action: LLMType.string()
-                        .description('recommended action')
-                }, 'conversation_routing_information')
-                .toJSON();
-        }
-        return LLMRouter._cachedStructuredOutput;
+    static structuredOutput (actions = []) {
+        return LLMType
+            .object({
+                action: LLMType.enum([LLMRouter.NOT_CHANGED, ...actions])
+                    .description('recommended action')
+            }, 'conversation_routing_information')
+            .toJSON();
     }
 
     /**
@@ -183,7 +192,7 @@ class LLMRouter {
 
             let res;
             try {
-                res = await session.generateStructured(LLMRouter.structuredOutput());
+                res = await session.generateStructured(routing.structuredOutput);
             } catch (e) {
                 // Fail closed: any error in routing classification is treated
                 // as "no context change" so the user's current flow continues.
@@ -315,6 +324,7 @@ class LLMRouter {
                 : {}),
             actionListString,
             actionList,
+            structuredOutput: LLMRouter.structuredOutput(actionList.map((a) => a.action)),
             byAction,
             router,
             routes: resolvedLlm
@@ -367,6 +377,7 @@ class LLMRouter {
             : {
                 actionListString: '',
                 actionList: [],
+                structuredOutput: LLMRouter.structuredOutput(),
                 byAction: new Map(),
                 router: null,
                 routes: []

package/src/LLMSession.js

@@ -93,6 +93,7 @@ const stateData = require('./utils/stateData');
  * @prop {string[]} [enum] - Allowed values for this parameter
  * @prop {number} [minimum] - Minimum value for numeric parameters
  * @prop {number} [maximum] - Maximum value for numeric parameters
+ * @prop {string} [format] - JSON Schema string format, e.g. 'date-time', 'email', 'uuid'
  */
 
 /** @typedef {{ [key: string]: JsonSchemaProp }} SimpleJsonSchema */
@@ -170,6 +171,10 @@ const stateData = require('./utils/stateData');
  * @prop {LLMCallPreset} [preset]
  */
 
+// max number of consecutive tool-call rounds resolved within a single generate()
+// before we force a tool-less final answer (guards against tool-call loops)
+const MAX_TOOL_CALL_ROUNDS = 5;
+
 /**
  * @class LLMSession
  * @implements {PromiseLike<LLMMessage<any>>}
@@ -224,6 +229,9 @@ class LLMSession {
         this._res = res || llm?.res;
 
         this._preset = preset;
+
+        /** @type {PossiblyAsyncContent|null} */
+        this._fallbackMessage = null;
     }
 
     /**
@@ -850,6 +858,38 @@ class LLMSession {
         return this;
     }
 
+    /**
+     * Sets a message to send to the user when a subsequent `generate()` call
+     * fails (e.g. a provider network timeout). Instead of rejecting - which
+     * would surface the raw error to the user - the failure is logged and this
+     * message is sent in place of the model's reply, so the chain resolves
+     * cleanly. If the message resolves to an empty value, the original error
+     * is rethrown (same as when no fallback is set).
+     *
+     * Only affects `generate()`. `generateStructured()` keeps using delegated
+     * errors (see {@link onDelegatedError}).
+     *
+     * @param {PossiblyAsyncContent} content
+     * @returns {this}
+     */
+    setFallbackMessage (content) {
+        this._job(() => {
+            this._fallbackMessage = content;
+        }, true);
+        return this;
+    }
+
+    /**
+     * @returns {Promise<string>}
+     */
+    async _resolveFallbackContent () {
+        const fallback = this._fallbackMessage;
+        const content = typeof fallback === 'function'
+            ? fallback(this._resolveData())
+            : fallback;
+        return Promise.resolve(content);
+    }
+
     /**
      *
      * @param {LLMCallPreset} [providerOptions]
@@ -857,7 +897,28 @@ class LLMSession {
      * @returns {this}
      */
     generate (providerOptions = this._preset, logOptions = {}) {
-        this._job(() => this._generate(providerOptions, logOptions));
+        this._job(async () => {
+            try {
+                return await this._generate(providerOptions, logOptions);
+            } catch (e) {
+                if (this._fallbackMessage === null) {
+                    throw e;
+                }
+
+                const content = await this._resolveFallbackContent();
+                if (!content) {
+                    // no usable fallback message - propagate the original error
+                    throw e;
+                }
+                this._llm.log.error(`LLMSession.generate failed, sending fallback message: ${e.message}`, e);
+
+                /** @type {LLMMessage} */
+                const result = { role: ROLE_ASSISTANT, content };
+                this._generatedIndex = this._chat.length;
+                this._chat.push(result);
+                return result;
+            }
+        });
         return this;
     }
 
@@ -912,9 +973,14 @@ class LLMSession {
      * @returns {Promise<LLMMessage<any>>}
      */
     async _generate (providerOptions = this._preset, logOptions = {}) {
+        const { maxToolCallRounds = MAX_TOOL_CALL_ROUNDS } = this._llm.llmOptions(providerOptions);
         let result = await this._llm.generate(this, providerOptions, logOptions);
 
-        if (result.toolCalls?.length) {
+        // the model may chain several rounds of tool calls before it produces
+        // a final text answer - keep resolving them until it stops (bounded)
+        let rounds = 0;
+        while (result.toolCalls?.length && rounds < maxToolCallRounds) {
+            rounds += 1;
             const toolCalls = [];
             const results = await Promise.all(
                 result.toolCalls.map(async (tc) => {
@@ -936,27 +1002,54 @@ class LLMSession {
                 );
                 result = await this._llm.generate(this, providerOptions, logOptions);
             } else {
-                // everything failed
-                /** @type {LLMCallPreset} */
-                const overrideChoice = typeof providerOptions === 'string'
-                    ? {
-                        preset: providerOptions,
-                        toolChoice: 'none'
-                    }
-                    : {
-                        ...providerOptions,
-                        toolChoice: 'none'
-                    };
-                result = await this._llm.generate(this, overrideChoice, logOptions);
+                // everything failed - force a final text answer without tools
+                this._llm.log.error(
+                    `LLMSession: all ${result.toolCalls.length} tool call(s) failed in round ${rounds}, `
+                    + 'forcing a tool-less final answer',
+                    { toolCalls: result.toolCalls }
+                );
+                result = await this._generateWithoutTools(providerOptions, logOptions);
+                break;
             }
         }
 
+        // safety net: if the model is still requesting tools (e.g. it hit the
+        // round limit), force one final tool-less generation so we never return
+        // a tool-call message (content === null) to the send pipeline
+        if (result.toolCalls?.length) {
+            this._llm.log.error(
+                `LLMSession: reached maxToolCallRounds (${maxToolCallRounds}), `
+                + 'dropping pending tool calls and forcing a tool-less final answer',
+                { toolCalls: result.toolCalls }
+            );
+            result = await this._generateWithoutTools(providerOptions, logOptions);
+        }
+
         this._generatedIndex = this._chat.length;
         this._chat.push(result);
 
         return result;
     }
 
+    /**
+     *
+     * @param {LLMCallPreset} providerOptions
+     * @param {LLMLogOptions} logOptions
+     * @returns {Promise<LLMMessage<any>>}
+     */
+    _generateWithoutTools (providerOptions, logOptions) {
+        const overrideChoice = typeof providerOptions === 'string'
+            ? {
+                preset: providerOptions,
+                toolChoice: 'none'
+            }
+            : {
+                ...providerOptions,
+                toolChoice: 'none'
+            };
+        return this._llm.generate(this, overrideChoice, logOptions);
+    }
+
     /**
      *
      * @param {ToolCall} toolCall
@@ -1089,6 +1182,10 @@ class LLMSession {
      * @returns {LLMMessage[]}
      */
     static toMessages (result) {
+        // tool-call / structured messages carry no text content - nothing to send
+        if (typeof result.content !== 'string') {
+            return [];
+        }
         let filtered = result.content
             .replace(/\n\n\n+/g, '\n\n')
             .split(/\n\n+(?!\s*-)/g)

package/src/LLMType.js

@@ -25,6 +25,7 @@ class LLMType {
         this._name = name;
 
         this._description = null;
+        this._format = null;
         this._min = null;
         this._max = null;
 
@@ -155,6 +156,24 @@ class LLMType {
         return this;
     }
 
+    /**
+     * Sets the JSON Schema `format` for a string property.
+     *
+     * Supported values: `'date-time'`, `'time'`, `'date'`, `'duration'`,
+     * `'email'`, `'hostname'`, `'ipv4'`, `'ipv6'`, `'uuid'`.
+     *
+     * @example
+     * const createdAt = LLMType.string().format('date-time').description('Creation timestamp');
+     *
+     * @param {'date-time'|'time'|'date'|'duration'|'email'|
+     * 'hostname'|'ipv4'|'ipv6'|'uuid'|string} value
+     * @returns {this}
+     */
+    format (value) {
+        this._format = value;
+        return this;
+    }
+
     /**
      * Sets minimum boundary and maps it to a type-specific JSON Schema keyword.
      *
@@ -282,7 +301,8 @@ class LLMType {
     _baseSchema () {
         return /** @type {object} */ ({
             ...(this._description !== null && { description: this._description }),
-            ...(this._name !== null && { name: this._name })
+            ...(this._name !== null && { name: this._name }),
+            ...(this._format !== null && { format: this._format })
         });
     }
 

package/src/graphApi/schema.gql

@@ -123,10 +123,18 @@ type VectorSearchResult {
   resultDocuments: [VectorSearchDocument!]!  
 }
 
+type ToolFunction {
+    name: String!
+    description: String
+    parameters: Any
+}
+
 type PromptInfo {
     prompt: [LLMMessage!]!
     result: LLMMessage!
     vectorSearchResult: VectorSearchResult
+    tools: [ToolFunction!]
+    durationMs: Float
 }
 
 type UserInteraction {