wingbot 3.74.8 → 3.75.9-alpha.2

package/src/LLMRouter.js

@@ -0,0 +1,325 @@
+/**
+ * @author David Menger
+ */
+'use strict';
+
+const GlobalIntents = require('./GlobalIntents');
+const LLMType = require('./LLMType');
+
+/** @typedef {import('./GlobalIntents').GlobalIntentsMap} GlobalIntentsMap */
+/** @typedef {import('./GlobalIntents').ResolvedGlobalIntentsMap} ResolvedGlobalIntentsMap */
+/** @typedef {import('./GlobalIntents').GlobalIntentResolved} GlobalIntentResolved */
+/** @typedef {import('./GlobalIntents').MatchingResolver} MatchingResolver */
+/** @typedef {import('./GlobalIntents').MatcherResult} MatcherResult */
+/** @typedef {import('./LLMDispatcher').ILLMRouter} ILLMRouter */
+/** @typedef {import('./Request')} Request */
+/** @typedef {import('./LLM')} LLM */
+/** @typedef {import('./prompt').Prompt} Prompt */
+/** @typedef {import('./Router').RoutingInstruction} RoutingInstruction */
+
+/**
+ * @typedef {object} NLPActionInfo
+ * @prop {MatcherResult} intent
+ * @prop {boolean} aboveConfidence
+ * @prop {boolean} winner
+ * @prop {string} [title]
+ * @prop {string|string[]} [match]
+ */
+
+/**
+ * @typedef {object} BaseRouteAction
+ * @prop {string} action
+ * @prop {object} [data]
+ * @prop {object} [setState]
+ * @prop {object} [_aiKeys]
+ */
+
+/**
+ * @typedef {object} LLMRouting
+ * @prop {LLMRoutingCache} globals
+ * @prop {ILLMRouter|null} router
+ * @prop {Map<string, LLMRoutingCache>} locals
+ */
+
+/**
+ * @typedef {Pick<GlobalIntentResolved, 'action'|'classification'>} LLMAction
+ */
+
+/**
+ * @typedef {BaseRouteAction & Partial<NLPActionInfo>} RoutingAction
+ */
+
+/**
+ * @callback RouterResolver
+ * @param {LLM} llm
+ * @param {Request} req
+ * @param {LLMRoutingInput} routing
+ *
+ * @returns {Promise<RoutingAction|null>}
+ */
+
+/**
+ * @typedef {Pick<LLMRoutingCache, 'actionList'|'actionListString'|'byAction'>} LLMRoutingInput
+ */
+
+/**
+ * @typedef {object} LLMRoutingCache
+ * @prop {boolean} [keepUserInInteractionsWithBounceAllowed]
+ * @prop {string} actionListString
+ * @prop {LLMAction[]} actionList
+ * @prop {ILLMRouter|null} router
+ * @prop {Map<string, GlobalIntentResolved>} byAction
+ */
+
+/**
+ * @typedef {object} LLMRouterOptions
+ * @prop {boolean} [keepUserInInteractionsWithBounceAllowed]
+ * @prop {boolean} [global]
+ */
+
+/**
+ * @typedef {Omit<LLMRouterOptions, 'global'>} GILLMExtension
+ */
+
+/**
+ * @class LLMRouter
+ */
+class LLMRouter {
+
+    // lets give it "reduce" method? - can forward that info to dispatcher
+
+    /**
+     *
+     * @param {RouterResolver} routeResolver
+     * @param {Omit<LLMRouterOptions, 'global'>} [options]
+     */
+    static global (routeResolver, options = {}) {
+        return new LLMRouter(routeResolver, {
+            ...options,
+            global: true
+        });
+    }
+
+    /**
+     *
+     * @param {RouterResolver} [routeResolver]
+     * @param {LLMRouterOptions} [options]
+     */
+    constructor (routeResolver = null, options = {}) {
+        const { global = false, ...rest } = options;
+        this._route = routeResolver;
+        this._global = global;
+
+        /** @typedef {GlobalIntentsMap} */
+        this.globalIntents = new Map();
+
+        if (global) {
+            const gi = GlobalIntents.create({
+                router: this._route ? this : null,
+                ...rest
+            });
+            this.globalIntents.set(gi.id, gi);
+        } else if (Object.keys(rest).length) {
+            const gi = GlobalIntents.create({
+                local: true,
+                ...rest
+            });
+            this.globalIntents.set(gi.id, gi);
+        }
+    }
+
+    /**
+     * @type {object}
+     */
+    static _cachedStructuredOutput = null;
+
+    /**
+     *
+     * @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;
+    }
+
+    /**
+     *
+     * prompt wi
+     *
+     * @param {Prompt} prompt
+     * @returns {RouterResolver}
+     */
+    static defaultRoute (prompt) {
+        /** @type {RouterResolver} */
+        const route = async (llm, req, routing) => {
+            const res = await llm.session('routing')
+                .setData(routing)
+                .systemPrompt(prompt)
+                .generateStructured(LLMRouter.structuredOutput());
+
+            if (!routing.byAction.has(LLMRouter._normByAction(res.action))) {
+                return null;
+            }
+
+            return res;
+        };
+
+        return route;
+    }
+
+    /**
+     *
+     * @returns {RoutingInstruction}
+     */
+    reduce () {
+        return false;
+    }
+
+    on () {
+        // acually does nothing too
+    }
+
+    /**
+     *
+     * @param {LLM} llm
+     * @param {Request} req
+     * @param {LLMRoutingInput} routing
+     * @returns {Promise<RoutingAction|null>}
+     */
+    async resolve (llm, req, routing) { // eslint-disable-line no-unused-vars
+        if (!this._route) {
+            return null;
+        }
+        return this._route(llm, req, routing);
+    }
+
+    /**
+     *
+     * @param {string} path
+     * @param {string} classification
+     * @returns {MatchingResolver}
+     */
+    route (path, classification) {
+        return GlobalIntents.resolver(path, {
+            classification,
+            router: this._route ? this : null,
+            local: !this._global
+        });
+    }
+
+    /**
+     *
+     * @param {string} path
+     * @param {string} classification
+     * @returns {MatchingResolver}
+     */
+    static route (path, classification) {
+        return GlobalIntents.resolver(path, {
+            classification
+        });
+    }
+
+    static _normByAction (act) {
+        return act.replace(/^\/|\/$/g, '');
+    }
+
+    /**
+     *
+     * @param {GlobalIntentResolved[]} resolvedLlm
+     * @returns {LLMRoutingCache}
+     */
+    static _prepareRoutingInput (resolvedLlm) {
+        const byAction = new Map();
+        let router = null;
+        let keepUserInInteractionsWithBounceAllowed;
+
+        const actionList = resolvedLlm.map((gi) => {
+            const { action, classification } = gi;
+            byAction.set(LLMRouter._normByAction(gi.action), gi);
+
+            if (typeof gi.keepUserInInteractionsWithBounceAllowed === 'boolean') {
+                keepUserInInteractionsWithBounceAllowed = true;
+            }
+
+            if (router && router !== gi.router) {
+                throw new Error(`Multiple local routers on "${gi.localPath}"`);
+            } else {
+                router = gi.router;
+            }
+
+            return { action, classification };
+        });
+
+        const actionListString = actionList
+            .map((gi) => `- \`${gi.action}\`: ${gi.classification}`)
+            .join('\n');
+
+        return {
+            ...(typeof keepUserInInteractionsWithBounceAllowed === 'boolean'
+                ? { keepUserInInteractionsWithBounceAllowed }
+                : {}),
+            actionListString,
+            actionList,
+            byAction,
+            router
+        };
+    }
+
+    /**
+     *
+     * @param {ResolvedGlobalIntentsMap} globalIntents
+     * @returns {LLMRouting}
+     */
+    static prepareRouting (globalIntents) {
+        /** @type {Map<string, GlobalIntentResolved[]>} */
+        const locals = new Map();
+        /** @type {GlobalIntentResolved[]} */
+        const globals = [];
+        /** @type {ILLMRouter} */
+        let router = null;
+
+        for (const gi of globalIntents.values()) {
+            if (!gi.classification
+                && !gi.router
+                && typeof gi.keepUserInInteractionsWithBounceAllowed === 'undefined') continue;
+
+            if (gi.local) {
+                let local = locals.get(gi.localPath);
+                if (!local) {
+                    local = [];
+                    locals.set(gi.localPath, local);
+                }
+                local.push(gi);
+            } else if (gi.classification) {
+                globals.push(gi);
+            } else if (gi.router) { // public default router without classification
+                if (router !== null) {
+                    throw new Error(`Detected more than one global router on '${gi.localPath}'. Only single global router allowed.`);
+                }
+                router = gi.router;
+            }
+        }
+
+        return {
+            router,
+            locals: new Map(
+                Array.from(locals)
+                    .map(([localPath, locs]) => [
+                        localPath,
+                        LLMRouter._prepareRoutingInput(locs)
+                    ])
+            ),
+            globals: LLMRouter._prepareRoutingInput(globals)
+        };
+    }
+
+}
+
+module.exports = LLMRouter;

package/src/LLMSession.js

@@ -6,12 +6,16 @@
 const {
     FILTER_SCOPE_CONVERSATION, ROLE_ASSISTANT, ROLE_USER, ROLE_SYSTEM
 } = require('./LLMConsts');
+const stateData = require('./utils/stateData');
 
 /** @typedef {import('./Responder').QuickReply} QuickReply */
 /** @typedef {import('./LLM').LLMCallPreset} LLMCallPreset */
 /** @typedef {import('./LLM')} LLM */
 /** @typedef {import('./LLM').LLMLogOptions} LLMLogOptions */
 
+/** @typedef {import('./Request')} Request */
+/** @typedef {import('./Responder')} Responder */
+
 /** @typedef {'user'|'assistant'} LLMChatRole */
 /** @typedef {'system'} LLMSystemRole */
 /** @typedef {'tool'} LLMToolRole */
@@ -29,7 +33,9 @@ const {
  * @prop {string} args - JSON string
  */
 
-/** @typedef {string|Promise<string>} PossiblyAsyncContent */
+/** @typedef {import('./prompt').Renderer} Renderer */
+
+/** @typedef {string|Promise<string>|Renderer} PossiblyAsyncContent */
 
 /**
  * @template {LLMRole} [R=LLMRole]
@@ -112,7 +118,6 @@ const {
  * @prop {string} name - The function name
  * @prop {string} [description] - What the function does
  * @prop {FnParamsObject} [parameters] - Parameter schema
- * @prop {boolean} [strict]
  */
 
 /**
@@ -155,6 +160,16 @@ const {
  *      - toJson
  */
 
+/**
+ * @typedef {object} SessionOptions
+ * @prop {LLMFilter[]} [filters]
+ * @prop {SendCallback} [onSend]
+ * @prop {Request} [req]
+ * @prop {Responder} [res]
+ * @prop {object} [data]
+ * @prop {LLMCallPreset} [preset]
+ */
+
 /**
  * @class LLMSession
  * @implements {PromiseLike<LLMMessage<any>>}
@@ -165,10 +180,18 @@ class LLMSession {
      *
      * @param {LLM} llm
      * @param {(PossiblyAsyncLLMMessage|AsyncLLMMessage)[]} [chat]
-     * @param {SendCallback} [onSend]
-     * @param {LLMFilter[]} [filters=[]]
+     * @param {SessionOptions} [options]
      */
-    constructor (llm, chat = [], onSend = null, filters = []) {
+    constructor (llm, chat = [], options = {}) {
+        const {
+            onSend = null,
+            filters = [],
+            data = {},
+            req = null,
+            res = null,
+            preset = undefined
+        } = options;
+
         this._llm = llm;
 
         this._onSend = onSend;
@@ -194,6 +217,36 @@ class LLMSession {
 
         /** @type {Map<string,ObjectTool>} */
         this._tools = new Map();
+
+        this._data = { ...data };
+
+        this._req = req || llm?.req;
+        this._res = res || llm?.res;
+
+        this._preset = preset;
+    }
+
+    /**
+     *
+     * @param {object} data
+     * @returns {this}
+     */
+    setData (data) {
+        this._job(() => {
+            Object.assign(this._data, data);
+        }, true);
+        return this;
+    }
+
+    _resolveData () {
+        const dataFromReqRes = this._req || this._res
+            ? stateData(this._req, this._res)
+            : {};
+
+        return {
+            ...dataFromReqRes,
+            ...this._data
+        };
     }
 
     _job (task, runNowAndSyncWhenQueueIsEmpty = false) {
@@ -297,19 +350,15 @@ class LLMSession {
             .map(({
                 name,
                 description = null,
-                parameters = {},
-                strict = true
+                parameters = {}
             }) => ({
                 name,
                 ...(description && { description }),
-                ...(typeof strict === 'boolean' ? { strict } : {}),
+                strict: true,
                 parameters: {
                     type: 'object',
                     properties: {},
                     additionalProperties: false,
-                    required: 'properties' in parameters
-                        ? Object.keys(parameters.properties)
-                        : [],
                     ...parameters
                 }
             }));
@@ -447,11 +496,15 @@ class LLMSession {
                 return;
             }
             if ('content' in m
+                && typeof m.content !== 'function'
                 && (m.content instanceof Promise
                     || (typeof m.content !== 'string' && m.content && 'then' in m.content))) {
                 return;
             }
-            if (filtered && this._filters.length >= 0 && 'content' in m && typeof m.content === 'string') {
+            if (filtered
+                && this._filters.length >= 0
+                && 'content' in m
+                && (typeof m.content === 'string' || typeof m.content === 'function')) {
                 const content = this._filters.reduce((text, filter) => {
                     if (!text) {
                         return text;
@@ -463,7 +516,7 @@ class LLMSession {
                     }
                     const res = filter.filter(text, m.role);
                     return res === true ? text : res;
-                }, m.content);
+                }, typeof m.content === 'function' ? m.content.toString() : m.content);
 
                 if (typeof content === 'string') {
                     // @ts-ignore
@@ -472,6 +525,11 @@ class LLMSession {
                         content
                     });
                 }
+            } else if ('content' in m && typeof m.content === 'function') {
+                ret.push({
+                    ...m,
+                    content: m.content.toString()
+                });
             } else {
                 // @ts-ignore
                 ret.push(m);
@@ -520,6 +578,9 @@ class LLMSession {
         if (typeof m.content === 'string') {
             return m.content;
         }
+        if (typeof m.content === 'function') {
+            return m.content.toString();
+        }
         return '<Promise>';
     }
 
@@ -627,12 +688,17 @@ class LLMSession {
                 })();
                 return wrapped;
             }
-            if (!('content' in msg) || !this._contentIsPromise(msg.content)) {
+            if (!('content' in msg) || (!this._contentIsPromise(msg.content) && typeof msg.content !== 'function')) {
                 return msg;
             }
+
+            const contentPromise = typeof msg.content === 'function'
+                ? msg.content(this._resolveData())
+                : msg.content;
+
             const ret = {
                 ...msg,
-                content: Promise.resolve(msg.content)
+                content: Promise.resolve(contentPromise)
                     .then((r) => {
                         // @ts-ignore
                         ret.content = r;
@@ -688,7 +754,7 @@ class LLMSession {
 
     /**
      *
-     * @param {string|Promise<string>} content
+     * @param {string|Promise<string>|Renderer} content
      * @returns {this}
      */
     user (content) {
@@ -701,7 +767,7 @@ class LLMSession {
 
     /**
      *
-     * @param {string|Promise<string>} content
+     * @param {string|Promise<string>|Renderer} content
      * @returns {this}
      */
     assistant (content) {
@@ -714,7 +780,7 @@ class LLMSession {
 
     /**
      *
-     * @param {string|Promise<string>} content
+     * @param {string|Promise<string>|Renderer} content
      * @returns {this}
      */
     systemPrompt (content) {
@@ -747,7 +813,7 @@ class LLMSession {
      * @param {LLMLogOptions} [logOptions]
      * @returns {this}
      */
-    generate (providerOptions = undefined, logOptions = {}) {
+    generate (providerOptions = this._preset, logOptions = {}) {
         this._job(() => this._generate(providerOptions, logOptions));
         return this;
     }
@@ -759,7 +825,7 @@ class LLMSession {
      * @param {LLMLogOptions} [logOptions]
      * @returns {this}
      */
-    generateStructured (output, providerOptions = undefined, logOptions = {}) {
+    generateStructured (output, providerOptions = this._preset, logOptions = {}) {
 
         const responseFormat = 'toJSON' in output && typeof output.toJSON === 'function'
             ? output.toJSON()
@@ -787,7 +853,7 @@ class LLMSession {
      * @param {LLMLogOptions} [logOptions]
      * @returns {Promise<LLMMessage<any>>}
      */
-    async _generate (providerOptions = undefined, logOptions = {}) {
+    async _generate (providerOptions = this._preset, logOptions = {}) {
         let result = await this._llm.generate(this, providerOptions, logOptions);
 
         if (result.toolCalls?.length) {

package/src/LLMType.js

@@ -196,10 +196,11 @@ class LLMType {
     }
 
     /**
-     * Marks field as optional when used as an object property.
+     * Marks field as optional when used as an object property. In the
+     * generated schema this surfaces as a nullable type (e.g. `['string', 'null']`)
+     * — strict mode still requires the key to be present, just allows `null`.
      *
-     * When used outside object-property context, it has no practical effect,
-     * because requiredness is evaluated by parent object schemas.
+     * Outside an object-property context it has no practical effect.
      *
      * @example
      * const input = LLMType.object({
@@ -215,10 +216,9 @@ class LLMType {
     }
 
     /**
-     * Returns JSON Schema representation.
-     *
-     * For object schemas, nested properties are resolved recursively by calling
-     * `toJSON()` on each nested `LLMType` instance.
+     * Returns JSON Schema representation in OpenAI strict-mode form:
+     * every property is listed in `required`, and properties marked
+     * `optional()` are made nullable instead of being dropped from `required`.
      *
      * @example
      * const schema = LLMType.object({
@@ -246,18 +246,18 @@ class LLMType {
                 const properties = {};
                 const required = [];
                 Object.entries(this._properties).forEach(([key, child]) => {
-                    properties[key] = child.toJSON();
-                    if (child._required) {
-                        required.push(key);
+                    const childSchema = child.toJSON();
+                    if (!child._required) {
+                        childSchema.type = [childSchema.type, 'null'];
                     }
+                    properties[key] = childSchema;
+                    required.push(key);
                 });
 
                 schema.type = 'object';
                 schema.properties = properties;
                 schema.additionalProperties = false;
-                if (required.length > 0) {
-                    schema.required = required;
-                }
+                schema.required = required;
                 break;
             }