wingbot 3.76.18 → 3.77.0-alpha.1

package/src/LLMToolRunner.js

@@ -0,0 +1,580 @@
+/**
+ * @author Ondrej Veres
+ */
+'use strict';
+
+const LLMType = require('./LLMType');
+const compileWithState = require('./utils/compileWithState');
+const stateData = require('./utils/stateData');
+const getCondition = require('./utils/getCondition');
+const { compare, ConditionOperators } = require('./utils/customCondition');
+const { getValue } = require('./utils/getUpdate');
+
+/** @typedef {import('./Request')} Request */
+/** @typedef {import('./Responder')} Responder */
+/** @typedef {import('./Plugins')} Plugins */
+/** @typedef {import('./LLMSession')} LLMSession */
+/** @typedef {import('./Responder').QuickReply} QuickReply */
+
+/**
+ * texts in languages as the designer exports them ([{ l, t }], as the multilang inputs),
+ * or { [lang]: text }
+ *
+ * @typedef {{ l: string|null, t: string }[]|{ [lang: string]: string }} ToolTexts
+ */
+
+/**
+ * @typedef {object} ToolParameterDefinition
+ * @prop {string} name
+ * @prop {'string'|'number'|'boolean'|'enum'|'array'} type
+ * @prop {boolean} [optional]
+ * @prop {string} [description]
+ * @prop {{ value: string, description: string }[]} [values]
+ * @prop {ToolParameterDefinition[]} [items] - array: fields of the objects in the array
+ */
+
+/**
+ * A button of a situation - a prefilled call of a tool (or just a text the user sends)
+ *
+ * @typedef {object} ToolButtonDefinition
+ * @prop {ToolTexts} title
+ * @prop {string|null} tool - the tool the click calls (null - the title goes to the LLM as a text)
+ * @prop {object|null} [args] - arguments of the tool, strings can use the values
+ *   of the situation ("{{botCounterOffer}}" keeps the number)
+ * @prop {boolean} [hasCondition] - the condition (as the conditions of the designer):
+ *   the variables are the values of the situation and the state
+ * @prop {boolean} [hasEditableCondition]
+ * @prop {any[][]} [editableCondition]
+ * @prop {string} [conditionFn]
+ */
+
+/**
+ * What happens in a situation - the designer sets either the instruction for the LLM
+ * (the conversation with the LLM continues), or the target (a postback)
+ *
+ * @typedef {object} ToolSituationDefinition
+ * @prop {ToolTexts} [instruction]
+ * @prop {string|null} [action] - target interaction
+ * @prop {object} [setState] - set before the postback to the target
+ *   (strings can use the values of the situation)
+ * @prop {ToolButtonDefinition[]} [buttons] - offered with the answer of the LLM
+ */
+
+/**
+ * Tool as it comes from the designer (Tools tab, on the root block of the snapshot)
+ *
+ * @typedef {object} ToolDefinition
+ * @prop {string} id
+ * @prop {string} description
+ * @prop {ToolParameterDefinition[]} [parameters]
+ * @prop {{ [id: string]: ToolSituationDefinition }} [situations]
+ */
+
+/**
+ * What a tool (registered with plugins.registerTool()) returns - the situation, the code
+ * found out. What follows (an instruction for the LLM, or a target) is set in the designer.
+ *
+ * @typedef {object} ToolResult
+ * @prop {string} situation - id of the situation
+ * @prop {object} [data] - values for the texts, the set state and the buttons
+ * @prop {string} [asTool] - the situation is defined on another tool
+ *   (e.g. a refusal, which turned out to be a repeated offer)
+ */
+
+/**
+ * @typedef {object} LLMToolRunnerOptions
+ * @prop {object[]} [blocks] - blocks of the snapshot (the tools are on the root block)
+ * @prop {Plugins} [plugins] - code of the tools (plugins.registerTool())
+ * @prop {Console} [log]
+ * @prop {boolean} [allowForbiddenSnippetWords] - for the code conditions of the buttons
+ *   (as in the bot)
+ * @prop {string} [source] - for the logs and the tracking (e.g. "prompt", "mainLoop")
+ */
+
+/**
+ * @param {ToolTexts} texts
+ * @param {string} lang
+ * @returns {string}
+ */
+function textForLang (texts, lang) {
+    if (!texts) {
+        return '';
+    }
+    // a text can have alternatives (["Accept", "Take it"]) - the first filled one is used
+    const first = (t) => (Array.isArray(t) ? t.find((a) => `${a || ''}`.trim()) || '' : t || '');
+    const byLang = Array.isArray(texts)
+        ? Object.fromEntries(texts.map((tr) => [tr.l || '', first(tr.t)]))
+        : Object.fromEntries(Object.entries(texts).map(([l, t]) => [l, first(t)]));
+    if (lang && `${byLang[lang] || ''}`.trim()) {
+        return byLang[lang];
+    }
+    return byLang.en || Object.values(byLang).find((t) => `${t || ''}`.trim()) || '';
+}
+
+/**
+ * @param {ToolParameterDefinition} param
+ * @returns {LLMType}
+ */
+function parameterType (param) {
+    let type;
+    let { description } = param;
+
+    switch (param.type) {
+        case 'number':
+            type = LLMType.number();
+            break;
+        case 'boolean':
+            type = LLMType.boolean();
+            break;
+        case 'enum':
+            type = LLMType.enum(param.values.map((v) => v.value));
+            description = [
+                description,
+                ...param.values
+                    .filter((v) => v.description)
+                    .map((v) => `- ${v.value}: ${v.description}`)
+            ].filter((d) => !!d).join('\n');
+            break;
+        case 'array':
+            // array of objects - the fields are parameters too
+            type = LLMType.array(LLMType.object(Object.fromEntries(
+                (param.items || []).map((item) => [item.name, parameterType(item)])
+            )));
+            break;
+        default:
+            type = LLMType.string();
+    }
+
+    if (description) {
+        type.description(description);
+    }
+    return param.optional ? type.optional() : type;
+}
+
+/**
+ * @param {ToolDefinition} def
+ * @returns {LLMType}
+ */
+function parametersType (def) {
+    return LLMType.object(Object.fromEntries(
+        (def.parameters || []).map((param) => [param.name, parameterType(param)])
+    ));
+}
+
+// a template, which is just one value - "{{price}}"
+const SINGLE_VALUE = /^\{\{\s*([a-zA-Z0-9_$]+)\s*\}\}$/;
+
+// the click of a button of a situation - in the data of the quick reply
+const BUTTON_KEY = '_llmToolButton';
+
+/**
+ * @param {string} template
+ * @param {(template: string) => string} compile
+ * @param {object} values
+ * @returns {any}
+ */
+function compileValue (template, compile, values) {
+    const single = template.trim().match(SINGLE_VALUE);
+    if (single && Object.prototype.hasOwnProperty.call(values, single[1])) {
+        return values[single[1]];
+    }
+    return compile(template);
+}
+
+/**
+ * Set state from the designer - texts are filled with the values of the situation now
+ * (the values won't be in the state later), special values (increment, entity, ...)
+ * are kept. A template with just one value keeps its type ("{{price}}" stays a number).
+ *
+ * @param {object} setState
+ * @param {(template: string) => string} compile
+ * @param {object} [values]
+ * @returns {object}
+ */
+function quickReplySetState (setState, compile, values = {}) {
+    return Object.fromEntries(
+        Object.entries(setState || {})
+            .map(([key, value]) => [
+                key,
+                typeof value === 'string' ? compileValue(value, compile, values) : value
+            ])
+    );
+}
+
+/**
+ * Arguments of a tool for a button - every string can use the values of the situation,
+ * a template with just one value keeps its type
+ *
+ * @param {any} args
+ * @param {(template: string) => string} compile
+ * @param {object} [values]
+ * @returns {any}
+ */
+function compileArgs (args, compile, values = {}) {
+    if (typeof args === 'string') {
+        return compileValue(args, compile, values);
+    }
+    if (Array.isArray(args)) {
+        return args.map((a) => compileArgs(a, compile, values));
+    }
+    if (args && typeof args === 'object') {
+        return Object.fromEntries(Object.entries(args)
+            .map(([key, value]) => [key, compileArgs(value, compile, values)]));
+    }
+    return args;
+}
+
+/**
+ * Runs the tools placed in the interactions ("LLM Tool" blocks the request passed)
+ * within an LLM session, which talks to the user:
+ *
+ * - the LLM calls a tool by what the user did, the code of the tool
+ *   (plugins.registerTool()) returns the situation
+ * - what follows is in the designer (Tools tab): the instruction for the LLM
+ *   with the buttons, or the target interaction (a postback)
+ * - a button is a prefilled call of a tool - the click runs the same code
+ *   as when the user writes it (handleButton())
+ */
+class LLMToolRunner {
+
+    /**
+     * @param {Request} req
+     * @param {Responder} res
+     * @param {LLMToolRunnerOptions} [options]
+     */
+    constructor (req, res, options = {}) {
+        const {
+            blocks = [], plugins = null, log = console, source = 'llm',
+            allowForbiddenSnippetWords = false
+        } = options;
+
+        this._req = req;
+        this._res = res;
+        this._plugins = plugins;
+        this._log = log;
+        this._source = source;
+        this._allowForbiddenSnippetWords = allowForbiddenSnippetWords;
+
+        const rootBlock = (blocks || []).find((b) => b && b.isRoot);
+
+        /** @type {ToolDefinition[]} */
+        this._definitions = (rootBlock && rootBlock.tools) || [];
+
+        /** @type {Map<string, (args: object, session: LLMSession) => Promise<string>>} */
+        this._attached = new Map();
+
+        /** @type {string|null} */
+        this.postBackAction = null;
+
+        /** @type {QuickReply[]} */
+        this.quickReplies = [];
+
+        /** number of tools attached to the session */
+        this.count = 0;
+    }
+
+    /**
+     * the current state - with the changes of the tools (e.g. a new language
+     * is used for the texts right after the tool switched it)
+     *
+     * @returns {object}
+     */
+    _stateData () {
+        return stateData(this._req, this._res);
+    }
+
+    /**
+     * @param {string} template
+     * @param {object} [values]
+     * @returns {string}
+     */
+    _compile (template, values = {}) {
+        return compileWithState(this._req, this._res, template, {
+            ...this._stateData(),
+            ...values
+        });
+    }
+
+    /**
+     * @param {string} action
+     * @param {LLMSession} session
+     * @returns {string}
+     */
+    _makePostBack (action, session) {
+        if (this.postBackAction) {
+            return 'Ignored - the conversation already continues elsewhere.';
+        }
+        this.postBackAction = action;
+        session.stop();
+        return 'OK';
+    }
+
+    /**
+     * @param {ToolDefinition} def
+     * @param {string} situation
+     * @param {object} values
+     * @returns {string}
+     */
+    _instructionText (def, situation, values) {
+        const { lang } = this._stateData();
+        const sit = (def.situations || {})[situation] || {};
+        const template = textForLang(sit.instruction, lang);
+
+        if (!template) {
+            this._log.error(`LLM tool "${def.id}" - situation "${situation}" has no instruction in the designer`);
+            return `${situation}: ${JSON.stringify(values)}`;
+        }
+        return this._compile(template, values);
+    }
+
+    /**
+     * The condition of the button - over the values of the situation and the state
+     *
+     * @param {ToolDefinition} def
+     * @param {ToolButtonDefinition} button
+     * @param {object} values
+     * @returns {boolean}
+     */
+    _buttonShown (def, button, values) {
+        if (!button.hasCondition) {
+            return true;
+        }
+        try {
+            if (!button.hasEditableCondition) {
+                // a code condition - (req, res, values)
+                const fn = getCondition(button, {
+                    configuration: this._req.configuration,
+                    allowForbiddenSnippetWords: this._allowForbiddenSnippetWords
+                }, `LLM tool "${def.id}" button`);
+                const shown = fn(this._req, this._res, values);
+                if (shown && typeof shown.then === 'function') {
+                    // the buttons are made synchronously - an async condition can't be used
+                    throw new Error('the condition must not be async');
+                }
+                return !!shown;
+            }
+            const data = { ...this._stateData(), ...values };
+            const raw = [
+                ConditionOperators['matches regexp'],
+                ConditionOperators['not matches regexp'],
+                ConditionOperators['is true'],
+                ConditionOperators['is false']
+            ];
+            return (button.editableCondition || []).some((list) => list.every((cond) => compare(
+                getValue(cond.variable, data),
+                cond.operator,
+                raw.includes(cond.operator) ? cond.value : this._compile(cond.value, values)
+            )));
+        } catch (e) {
+            this._log.error(`LLM tool "${def.id}" - invalid condition of a button: ${e.message}`, e);
+            return false;
+        }
+    }
+
+    /**
+     * The buttons of the situation - with the answer of the LLM
+     *
+     * @param {ToolDefinition} def
+     * @param {string} situation
+     * @param {object} values
+     */
+    _addButtons (def, situation, values) {
+        const sit = (def.situations || {})[situation] || {};
+        const { lang } = this._stateData();
+        const compile = (t) => this._compile(t, values);
+        const action = this._res.currentAction();
+
+        (sit.buttons || [])
+            .filter((button) => this._buttonShown(def, button, values))
+            .forEach((button) => {
+                const title = compile(textForLang(button.title, lang)).trim();
+
+                if (!title) {
+                    this._log.error(`LLM tool "${def.id}" - a button of "${situation}" has no title in the designer`);
+                    return;
+                }
+                this.quickReplies.push({
+                    action,
+                    title,
+                    ...(button.tool && {
+                        data: {
+                            [BUTTON_KEY]: {
+                                tool: button.tool,
+                                args: compileArgs(button.args || {}, compile, values)
+                            }
+                        }
+                    })
+                });
+            });
+    }
+
+    /**
+     * Runs the code of the tool and what follows the situation
+     *
+     * @param {ToolDefinition} def
+     * @param {Function} fn
+     * @param {object} args
+     * @param {LLMSession} session
+     * @returns {Promise<string>}
+     */
+    async _runTool (def, fn, args, session) {
+        const { _req: req, _res: res } = this;
+
+        /** @type {ToolResult} */
+        const result = await fn(args, req, res, session);
+
+        if (!result || !result.situation) {
+            // no situation - the result goes to the LLM as it is (as in LLMSession)
+            if (result === undefined || result === null) {
+                return 'OK';
+            }
+            return typeof result === 'string' ? result : JSON.stringify(result);
+        }
+
+        const { situation, data: values = {} } = result;
+        res.trackEvent('tool', this._source, def.id, situation);
+
+        const sitDef = result.asTool
+            ? this._definitions.find((d) => d.id === result.asTool) || def
+            : def;
+        const sit = (sitDef.situations || {})[situation];
+
+        if (!sit) {
+            this._log.error(`LLM tool "${def.id}" - situation "${situation}" is not in the designer (tools.json)`);
+        }
+
+        if (sit && sit.action) {
+            if (this.postBackAction) {
+                // another tool has already moved the conversation - its state stays
+                return this._makePostBack(sit.action, session);
+            }
+            // the conversation continues in the target interaction
+            const setState = quickReplySetState(
+                sit.setState,
+                (t) => this._compile(t, values),
+                values
+            );
+            if (Object.keys(setState).length) {
+                res.setState(setState);
+            }
+            return this._makePostBack(sit.action, session);
+        }
+
+        // only the buttons of the last situation are offered (the earlier ones are outdated)
+        this.quickReplies = [];
+        this._addButtons(sitDef, situation, values);
+        return this._instructionText(sitDef, situation, values);
+    }
+
+    /**
+     * Adds the tools placed in the interactions, the request passed, to the session
+     *
+     * @param {LLMSession} session
+     * @returns {this}
+     */
+    attach (session) {
+        this._res.llmTools()
+            .map((id) => {
+                const def = this._definitions.find((d) => d.id === id);
+                if (!def) {
+                    this._log.error(`LLM tool "${id}" is placed in an interaction, but it's not in the Tools tab`);
+                }
+                return def;
+            })
+            .filter((def) => !!def)
+            .forEach((def) => {
+                const fn = this._plugins && this._plugins.getTool(def.id);
+
+                if (!fn) {
+                    this._log.error(`LLM tool "${def.id}" is in the designer, but it's not registered in the code`);
+                    return;
+                }
+
+                const run = (args, s) => this._runTool(def, fn, args, s);
+                this._attached.set(def.id, run);
+                this.count += 1;
+                session.tool({
+                    name: def.id,
+                    description: def.description,
+                    parameters: parametersType(def),
+                    fn: run
+                });
+            });
+
+        return this;
+    }
+
+    /**
+     * The click of a button of a situation - calls its tool the same way, as when
+     * the LLM calls it (the call is in the conversation for the LLM).
+     * Then generate the answer - unless the situation made a postback (postBackAction).
+     *
+     * Only the tools placed on the way can be called (the data of the click come
+     * from the user - the same as writing it).
+     *
+     * @param {LLMSession} session
+     * @returns {Promise<boolean>} - a button was clicked
+     */
+    async handleButton (session) {
+        const button = this._req.actionData()[BUTTON_KEY];
+
+        if (!button || typeof button.tool !== 'string') {
+            return false;
+        }
+
+        const run = this._attached.get(button.tool);
+        if (!run) {
+            this._log.error(`LLM tool "${button.tool}" of a button is not placed on the way to the interaction`);
+            return false;
+        }
+
+        const args = button.args && typeof button.args === 'object' ? button.args : {};
+        const id = `button_${button.tool}`;
+        let content;
+        try {
+            content = await run(args, session);
+        } catch (e) {
+            // the same as a failed call of the LLM - not in the conversation, the LLM answers
+            this._log.error(`LLM tool "${button.tool}" of a button: ${e.message}`, e, { args });
+            return false;
+        }
+
+        session.push(
+            {
+                role: 'assistant',
+                toolCalls: [{
+                    id, type: 'function', name: button.tool, args: JSON.stringify(args)
+                }]
+            },
+            { role: 'tool', content, toolCallId: id }
+        );
+        return true;
+    }
+
+    /**
+     * Provider options for the generation - one tool call at a time, when there are tools
+     * (the tools change the state - e.g. two offers in one message would both be recorded)
+     *
+     * @param {LLMSession} session
+     * @returns {string|object}
+     */
+    generateOptions (session) {
+        const { preset } = session;
+        if (this.count === 0) {
+            return preset;
+        }
+        return {
+            ...(typeof preset === 'string' || !preset ? { preset } : preset),
+            parallelToolCalls: false
+        };
+    }
+}
+
+LLMToolRunner.BUTTON_KEY = BUTTON_KEY;
+LLMToolRunner.textForLang = textForLang;
+LLMToolRunner.parameterType = parameterType;
+LLMToolRunner.parametersType = parametersType;
+LLMToolRunner.quickReplySetState = quickReplySetState;
+LLMToolRunner.compileArgs = compileArgs;
+
+module.exports = LLMToolRunner;

package/src/Plugins.js

@@ -46,6 +46,20 @@ const { compileWithState } = require('./utils');
  * @prop {string[]} [notLastMessageItems]
  */
 
+/**
+ * Tool, which can be offered to the LLM - its description and parameters are
+ * defined in the designer (tools.json)
+ *
+ * @template {object} [S=object]
+ * @template {BaseConfiguration} [C=object]
+ * @callback PluginTool
+ * @param {object} args - arguments filled by the LLM
+ * @param {Request<S,C>} req
+ * @param {Responder} res
+ * @param {import('./LLMSession')} session
+ * @returns {any|Promise<any>}
+ */
+
 /**
  * Custom code plugins for BuildRouter and wingbot.ai
  *
@@ -57,6 +71,9 @@ class Plugins {
 
     constructor () {
         this._plugins = new Map();
+
+        /** @type {Map<string,PluginTool<S,C>>} */
+        this._tools = new Map();
     }
 
     /**
@@ -214,6 +231,10 @@ class Plugins {
         name._plugins.forEach((el, key) => {
             this._plugins.set(key, el);
         });
+        // a plugins object of an older wingbot has no tools
+        (name._tools || new Map()).forEach((el, key) => {
+            this._tools.set(key, el);
+        });
     }
 
     /**
@@ -231,6 +252,38 @@ class Plugins {
         this._plugins.set(name, { pluginFactory, options });
     }
 
+    /**
+     * Register tool for the LLM
+     *
+     * @param {string} id - tool id (has to match the id in tools.json)
+     * @param {PluginTool<S,C>} tool
+     */
+    registerTool (id, tool) {
+        if (typeof tool !== 'function') {
+            throw new Error(`Tool should be a function, ${typeof tool} given (tool: ${id})`);
+        }
+        this._tools.set(id, tool);
+    }
+
+    /**
+     * Get registered tool
+     *
+     * @param {string} id
+     * @returns {PluginTool<S,C>|null}
+     */
+    getTool (id) {
+        return this._tools.get(id) || null;
+    }
+
+    /**
+     * Ids of all registered tools
+     *
+     * @returns {string[]}
+     */
+    getToolIds () {
+        return Array.from(this._tools.keys());
+    }
+
 }
 
 module.exports = Plugins;