@sprucelabs/sprucebot-llm 14.3.3 → 15.0.0

package/README.md

@@ -504,4 +504,4 @@ yarn build.dist     # Production build
 yarn chat           # Interactive chat demo
 yarn chat.images    # Chat with image support
 yarn generate.samples
-```
+```

package/build/.spruce/errors/errors.types.d.ts

@@ -1,5 +1,16 @@
 import { default as SchemaEntity } from '@sprucelabs/schema';
 import * as SpruceSchema from '@sprucelabs/schema';
+export declare namespace SpruceErrors.SprucebotLlm {
+    interface StateUpdateFailed {
+    }
+    interface StateUpdateFailedSchema extends SpruceSchema.Schema {
+        id: 'stateUpdateFailed';
+        namespace: 'SprucebotLlm';
+        name: 'State Update Failed';
+        fields: {};
+    }
+    type StateUpdateFailedEntity = SchemaEntity<SpruceErrors.SprucebotLlm.StateUpdateFailedSchema>;
+}
 export declare namespace SpruceErrors.SprucebotLlm {
     interface NoBotInstanceSet {
     }

package/build/.spruce/errors/options.types.d.ts

@@ -1,5 +1,8 @@
 import { SpruceErrors } from "./errors.types";
 import { ErrorOptions as ISpruceErrorOptions } from "@sprucelabs/error";
+export interface StateUpdateFailedErrorOptions extends SpruceErrors.SprucebotLlm.StateUpdateFailed, ISpruceErrorOptions {
+    code: 'STATE_UPDATE_FAILED';
+}
 export interface NoBotInstanceSetErrorOptions extends SpruceErrors.SprucebotLlm.NoBotInstanceSet, ISpruceErrorOptions {
     code: 'NO_BOT_INSTANCE_SET';
 }
@@ -12,5 +15,5 @@ export interface InvalidCallbackErrorOptions extends SpruceErrors.SprucebotLlm.I
 export interface CallbackErrorErrorOptions extends SpruceErrors.SprucebotLlm.CallbackError, ISpruceErrorOptions {
     code: 'CALLBACK_ERROR';
 }
-type ErrorOptions = NoBotInstanceSetErrorOptions | InvalidLlmAdapterErrorOptions | InvalidCallbackErrorOptions | CallbackErrorErrorOptions;
+type ErrorOptions = StateUpdateFailedErrorOptions | NoBotInstanceSetErrorOptions | InvalidLlmAdapterErrorOptions | InvalidCallbackErrorOptions | CallbackErrorErrorOptions;
 export default ErrorOptions;

package/build/.spruce/errors/sprucebotLlm/stateUpdateFailed.schema.d.ts

@@ -0,0 +1,3 @@
+import { SpruceErrors } from '../errors.types';
+declare const stateUpdateFailedSchema: SpruceErrors.SprucebotLlm.StateUpdateFailedSchema;
+export default stateUpdateFailedSchema;

package/build/.spruce/errors/sprucebotLlm/stateUpdateFailed.schema.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const schema_1 = require("@sprucelabs/schema");
+const stateUpdateFailedSchema = {
+    id: 'stateUpdateFailed',
+    namespace: 'SprucebotLlm',
+    name: 'State Update Failed',
+    fields: {}
+};
+schema_1.SchemaRegistry.getInstance().trackSchema(stateUpdateFailedSchema);
+exports.default = stateUpdateFailedSchema;

package/build/bots/TurnRequest.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const ResponseParser_1 = __importDefault(require("../parsingResponses/ResponseParser"));
+const SpruceError_1 = __importDefault(require("../errors/SpruceError"));
+const ResponseParserFactory_1 = __importDefault(require("../parsingResponses/ResponseParserFactory"));
 class TurnRequest {
     constructor(options) {
         this.isCancelled = false;
@@ -35,7 +36,16 @@ class TurnRequest {
             isDone = parsed.isDone;
             state = parsed.state;
             callbackResults = parsed.callbackResults;
-            await this.optionallyUpdateState(state);
+            try {
+                await this.optionallyUpdateState(state);
+            }
+            catch (err) {
+                throw new SpruceError_1.default({
+                    code: 'STATE_UPDATE_FAILED',
+                    friendlyMessage: `Updating state failed with error: ${err.message}`,
+                    originalError: err,
+                });
+            }
         }
         catch (err) {
             this.trackMessage({
@@ -44,7 +54,7 @@ class TurnRequest {
             });
             if (err.options?.code === 'INVALID_CALLBACK' ||
                 err.options?.code === 'CALLBACK_ERROR' ||
-                err.options?.code === 'VALIDATION_FAILED') {
+                err.options?.code === 'STATE_UPDATE_FAILED') {
                 return this.sendMessage({ from: 'Api', message: `Error: ${err.message}` }, cb);
             }
             throw err;
@@ -82,7 +92,7 @@ class TurnRequest {
             : undefined);
     }
     async parseResponse(response, callbacks) {
-        const parser = ResponseParser_1.default.getInstance();
+        const parser = ResponseParserFactory_1.default.getInstance();
         const parsed = await parser.parse(response, callbacks);
         return parsed;
     }

package/build/bots/adapters/{OpenAiMessageBuilder.d.ts → MessageBuilder.d.ts}

@@ -1,10 +1,11 @@
 import { ChatCompletionMessageParam } from 'openai/resources';
 import { SprucebotLlmBot } from '../../llm.types';
-export default class OpenAiMessageBuilder {
+export default class MessageBuilder {
     private bot;
     private memoryLimit;
     protected constructor(bot: SprucebotLlmBot, options?: BuildMessageOptions);
-    static Builder(bot: SprucebotLlmBot, options?: BuildMessageOptions): OpenAiMessageBuilder;
+    static Builder(bot: SprucebotLlmBot, options?: BuildMessageOptions): MessageBuilder;
+    private get parser();
     buildMessages(): ChatCompletionMessageParam[];
     private buildChatHistoryMessages;
     private mapMessageToCompletion;

package/build/bots/adapters/{OpenAiMessageBuilder.js → MessageBuilder.js}

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const ResponseParserFactory_1 = __importDefault(require("../../parsingResponses/ResponseParserFactory"));
 const templates_1 = require("../templates");
-class OpenAiMessageBuilder {
+class MessageBuilder {
     constructor(bot, options) {
         const { memoryLimit } = options ?? {};
         this.bot = bot;
@@ -12,6 +16,9 @@ class OpenAiMessageBuilder {
     static Builder(bot, options) {
         return new this(bot, options);
     }
+    get parser() {
+        return ResponseParserFactory_1.default.getInstance();
+    }
     buildMessages() {
         const values = this.bot.serialize();
         const allMessages = [
@@ -132,6 +139,8 @@ class OpenAiMessageBuilder {
                         <Parameter${param.isRequired ? ' required="true"' : ''}>
                             <Name>${param.name}</Name>
                             <Type>${param.type}</Type>
+                            ${param.isArray ? '<IsArray>true</IsArray>' : ''}
+                            ${'minArrayLength' in param ? `<MinArrayLength>${param.minArrayLength}</MinArrayLength>` : ''}
                             ${param.description ? `<Description>${param.description}</Description>` : ''}${parameterChoices}
                         </Parameter>`;
                 }
@@ -144,7 +153,7 @@ class OpenAiMessageBuilder {
         const api = `<APIReference>\n\n${descriptions.join('\n\n')}</APIReference>`;
         return {
             role: 'system',
-            content: `You have an API available to you to lookup answers. When you need the response of the function call to proceed, you can call a function using a custom markup we created that looks like this: <<FunctionName/>>. The API will respond with the results and then you can continue the conversation with your new knowledge. If the api call has parameters, call it like this: <<FunctionName>>{{parametersJsonEncoded}}<</FunctionName>>. Make sure to json encode the data and drop it between the function tags. Note: You can only make one API call at a time. The API is as follows (in xml format):\n\n${api}`,
+            content: `You have an API available to you to lookup answers. When you need the response of the function call to proceed, you can call a function using a custom markup we created: ${this.parser.getFunctionCallInstructions()}. The API is as follows (in xml format):\n\n${api}`,
         };
     }
     buildPleaseKeepInMindMessage(pleaseKeepInMindThat) {
@@ -156,7 +165,7 @@ class OpenAiMessageBuilder {
     buildStateMessage(state) {
         return {
             role: 'system',
-            content: `The current state of this conversation is:\n\n${JSON.stringify(state)}. As the state is being updated, send it back to me in json format (something in can JSON.parse()) at the end of each response (it's not meant for reading, but for parsing, so don't call it out, but send it as we progress), surrounded by the State Boundary (${templates_1.STATE_BOUNDARY}), like this:\n\n${templates_1.STATE_BOUNDARY} { "fieldName": "fieldValue" } ${templates_1.STATE_BOUNDARY}`,
+            content: `The current state of this conversation is:\n\n${JSON.stringify(state)}. As the conversation progresses and you need to update state, follow these instructions: ${this.parser.getStateUpdateInstructions()}`,
         };
     }
     buildYourJobMessage(yourJob) {
@@ -178,4 +187,4 @@ class OpenAiMessageBuilder {
         };
     }
 }
-exports.default = OpenAiMessageBuilder;
+exports.default = MessageBuilder;

package/build/bots/adapters/MessageSender.js

@@ -5,8 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const sdk_1 = require("@anthropic-ai/sdk");
 const openai_1 = require("openai");
+const MessageBuilder_1 = __importDefault(require("./MessageBuilder"));
 const OpenAiAdapter_1 = require("./OpenAiAdapter");
-const OpenAiMessageBuilder_1 = __importDefault(require("./OpenAiMessageBuilder"));
 class MessageSenderImpl {
     constructor(send, log) {
         this.log = log;
@@ -17,7 +17,7 @@ class MessageSenderImpl {
     }
     async sendMessage(bot, options) {
         const { memoryLimit, ...rest } = options;
-        const messageBuilder = OpenAiMessageBuilder_1.default.Builder(bot, {
+        const messageBuilder = MessageBuilder_1.default.Builder(bot, {
             memoryLimit,
         });
         const messages = messageBuilder.buildMessages();

package/build/errors/SpruceError.js

@@ -42,6 +42,9 @@ ${options.validCallbacks.map((name, idx) => `${idx + 1}: ${name}`).join('\n')}`;
             case 'INVALID_LLM_ADAPTER':
                 message = `SPRUCE_LLM_ADAPTER=${options.adapter} is not a valid adapter. Please set SPRUCE_LLM_ADAPTER to a valid adapter (OpenAi, Anthropic, Ollama) and try again.`;
                 break;
+            case 'STATE_UPDATE_FAILED':
+                message = 'A State Update Failed just happened!';
+                break;
             default:
                 message = super.friendlyMessage();
         }

package/build/errors/stateUpdateFailed.builder.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    id: string;
+    name: string;
+    fields: {};
+};
+export default _default;

package/build/errors/stateUpdateFailed.builder.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const schema_1 = require("@sprucelabs/schema");
+exports.default = (0, schema_1.buildErrorSchema)({
+    id: 'stateUpdateFailed',
+    name: 'State Update Failed',
+    fields: {},
+});

package/build/esm/.spruce/errors/errors.types.d.ts

@@ -1,5 +1,16 @@
 import { default as SchemaEntity } from '@sprucelabs/schema';
 import * as SpruceSchema from '@sprucelabs/schema';
+export declare namespace SpruceErrors.SprucebotLlm {
+    interface StateUpdateFailed {
+    }
+    interface StateUpdateFailedSchema extends SpruceSchema.Schema {
+        id: 'stateUpdateFailed';
+        namespace: 'SprucebotLlm';
+        name: 'State Update Failed';
+        fields: {};
+    }
+    type StateUpdateFailedEntity = SchemaEntity<SpruceErrors.SprucebotLlm.StateUpdateFailedSchema>;
+}
 export declare namespace SpruceErrors.SprucebotLlm {
     interface NoBotInstanceSet {
     }

package/build/esm/.spruce/errors/options.types.d.ts

@@ -1,5 +1,8 @@
 import { SpruceErrors } from "./errors.types";
 import { ErrorOptions as ISpruceErrorOptions } from "@sprucelabs/error";
+export interface StateUpdateFailedErrorOptions extends SpruceErrors.SprucebotLlm.StateUpdateFailed, ISpruceErrorOptions {
+    code: 'STATE_UPDATE_FAILED';
+}
 export interface NoBotInstanceSetErrorOptions extends SpruceErrors.SprucebotLlm.NoBotInstanceSet, ISpruceErrorOptions {
     code: 'NO_BOT_INSTANCE_SET';
 }
@@ -12,5 +15,5 @@ export interface InvalidCallbackErrorOptions extends SpruceErrors.SprucebotLlm.I
 export interface CallbackErrorErrorOptions extends SpruceErrors.SprucebotLlm.CallbackError, ISpruceErrorOptions {
     code: 'CALLBACK_ERROR';
 }
-type ErrorOptions = NoBotInstanceSetErrorOptions | InvalidLlmAdapterErrorOptions | InvalidCallbackErrorOptions | CallbackErrorErrorOptions;
+type ErrorOptions = StateUpdateFailedErrorOptions | NoBotInstanceSetErrorOptions | InvalidLlmAdapterErrorOptions | InvalidCallbackErrorOptions | CallbackErrorErrorOptions;
 export default ErrorOptions;

package/build/esm/bots/TurnRequest.js

@@ -7,7 +7,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import ResponseParser from '../parsingResponses/ResponseParser.js';
+import SpruceError from '../errors/SpruceError.js';
+import ResponseParserFactory from '../parsingResponses/ResponseParserFactory.js';
 export default class TurnRequest {
     constructor(options) {
         this.isCancelled = false;
@@ -41,7 +42,16 @@ export default class TurnRequest {
                 isDone = parsed.isDone;
                 state = parsed.state;
                 callbackResults = parsed.callbackResults;
-                yield this.optionallyUpdateState(state);
+                try {
+                    yield this.optionallyUpdateState(state);
+                }
+                catch (err) {
+                    throw new SpruceError({
+                        code: 'STATE_UPDATE_FAILED',
+                        friendlyMessage: `Updating state failed with error: ${err.message}`,
+                        originalError: err,
+                    });
+                }
             }
             catch (err) {
                 this.trackMessage({
@@ -50,7 +60,7 @@ export default class TurnRequest {
                 });
                 if (((_c = err.options) === null || _c === void 0 ? void 0 : _c.code) === 'INVALID_CALLBACK' ||
                     ((_d = err.options) === null || _d === void 0 ? void 0 : _d.code) === 'CALLBACK_ERROR' ||
-                    ((_e = err.options) === null || _e === void 0 ? void 0 : _e.code) === 'VALIDATION_FAILED') {
+                    ((_e = err.options) === null || _e === void 0 ? void 0 : _e.code) === 'STATE_UPDATE_FAILED') {
                     return this.sendMessage({ from: 'Api', message: `Error: ${err.message}` }, cb);
                 }
                 throw err;
@@ -92,7 +102,7 @@ export default class TurnRequest {
     }
     parseResponse(response, callbacks) {
         return __awaiter(this, void 0, void 0, function* () {
-            const parser = ResponseParser.getInstance();
+            const parser = ResponseParserFactory.getInstance();
             const parsed = yield parser.parse(response, callbacks);
             return parsed;
         });

package/build/esm/bots/adapters/{OpenAiMessageBuilder.d.ts → MessageBuilder.d.ts}

@@ -1,10 +1,11 @@
 import { ChatCompletionMessageParam } from 'openai/resources';
 import { SprucebotLlmBot } from '../../llm.types';
-export default class OpenAiMessageBuilder {
+export default class MessageBuilder {
     private bot;
     private memoryLimit;
     protected constructor(bot: SprucebotLlmBot, options?: BuildMessageOptions);
-    static Builder(bot: SprucebotLlmBot, options?: BuildMessageOptions): OpenAiMessageBuilder;
+    static Builder(bot: SprucebotLlmBot, options?: BuildMessageOptions): MessageBuilder;
+    private get parser();
     buildMessages(): ChatCompletionMessageParam[];
     private buildChatHistoryMessages;
     private mapMessageToCompletion;

package/build/esm/bots/adapters/{OpenAiMessageBuilder.js → MessageBuilder.js}

@@ -1,5 +1,6 @@
-import { DONE_TOKEN, STATE_BOUNDARY } from '../templates.js';
-export default class OpenAiMessageBuilder {
+import ResponseParserFactory from '../../parsingResponses/ResponseParserFactory.js';
+import { DONE_TOKEN } from '../templates.js';
+export default class MessageBuilder {
     constructor(bot, options) {
         var _a;
         const { memoryLimit } = options !== null && options !== void 0 ? options : {};
@@ -10,6 +11,9 @@ export default class OpenAiMessageBuilder {
     static Builder(bot, options) {
         return new this(bot, options);
     }
+    get parser() {
+        return ResponseParserFactory.getInstance();
+    }
     buildMessages() {
         const values = this.bot.serialize();
         const allMessages = [
@@ -131,6 +135,8 @@ export default class OpenAiMessageBuilder {
                         <Parameter${param.isRequired ? ' required="true"' : ''}>
                             <Name>${param.name}</Name>
                             <Type>${param.type}</Type>
+                            ${param.isArray ? '<IsArray>true</IsArray>' : ''}
+                            ${'minArrayLength' in param ? `<MinArrayLength>${param.minArrayLength}</MinArrayLength>` : ''}
                             ${param.description ? `<Description>${param.description}</Description>` : ''}${parameterChoices}
                         </Parameter>`;
                 }
@@ -143,7 +149,7 @@ export default class OpenAiMessageBuilder {
         const api = `<APIReference>\n\n${descriptions.join('\n\n')}</APIReference>`;
         return {
             role: 'system',
-            content: `You have an API available to you to lookup answers. When you need the response of the function call to proceed, you can call a function using a custom markup we created that looks like this: <<FunctionName/>>. The API will respond with the results and then you can continue the conversation with your new knowledge. If the api call has parameters, call it like this: <<FunctionName>>{{parametersJsonEncoded}}<</FunctionName>>. Make sure to json encode the data and drop it between the function tags. Note: You can only make one API call at a time. The API is as follows (in xml format):\n\n${api}`,
+            content: `You have an API available to you to lookup answers. When you need the response of the function call to proceed, you can call a function using a custom markup we created: ${this.parser.getFunctionCallInstructions()}. The API is as follows (in xml format):\n\n${api}`,
         };
     }
     buildPleaseKeepInMindMessage(pleaseKeepInMindThat) {
@@ -155,7 +161,7 @@ export default class OpenAiMessageBuilder {
     buildStateMessage(state) {
         return {
             role: 'system',
-            content: `The current state of this conversation is:\n\n${JSON.stringify(state)}. As the state is being updated, send it back to me in json format (something in can JSON.parse()) at the end of each response (it's not meant for reading, but for parsing, so don't call it out, but send it as we progress), surrounded by the State Boundary (${STATE_BOUNDARY}), like this:\n\n${STATE_BOUNDARY} { "fieldName": "fieldValue" } ${STATE_BOUNDARY}`,
+            content: `The current state of this conversation is:\n\n${JSON.stringify(state)}. As the conversation progresses and you need to update state, follow these instructions: ${this.parser.getStateUpdateInstructions()}`,
         };
     }
     buildYourJobMessage(yourJob) {

package/build/esm/bots/adapters/MessageSender.js

@@ -20,8 +20,8 @@ var __rest = (this && this.__rest) || function (s, e) {
 };
 import { APIUserAbortError as AnthropicAbortError } from '@anthropic-ai/sdk';
 import { APIUserAbortError } from 'openai';
+import MessageBuilder from './MessageBuilder.js';
 import { MESSAGE_RESPONSE_ERROR_MESSAGE } from './OpenAiAdapter.js';
-import OpenAiMessageBuilder from './OpenAiMessageBuilder.js';
 class MessageSenderImpl {
     constructor(send, log) {
         this.log = log;
@@ -35,7 +35,7 @@ class MessageSenderImpl {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d;
             const { memoryLimit } = options, rest = __rest(options, ["memoryLimit"]);
-            const messageBuilder = OpenAiMessageBuilder.Builder(bot, {
+            const messageBuilder = MessageBuilder.Builder(bot, {
                 memoryLimit,
             });
             const messages = messageBuilder.buildMessages();

package/build/esm/errors/SpruceError.js

@@ -37,6 +37,9 @@ ${options.validCallbacks.map((name, idx) => `${idx + 1}: ${name}`).join('\n')}`;
             case 'INVALID_LLM_ADAPTER':
                 message = `SPRUCE_LLM_ADAPTER=${options.adapter} is not a valid adapter. Please set SPRUCE_LLM_ADAPTER to a valid adapter (OpenAi, Anthropic, Ollama) and try again.`;
                 break;
+            case 'STATE_UPDATE_FAILED':
+                message = 'A State Update Failed just happened!';
+                break;
             default:
                 message = super.friendlyMessage();
         }

package/build/esm/errors/stateUpdateFailed.builder.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    id: string;
+    name: string;
+    fields: {};
+};
+export default _default;

package/build/esm/errors/stateUpdateFailed.builder.js

@@ -0,0 +1,6 @@
+import { buildErrorSchema } from '@sprucelabs/schema';
+export default buildErrorSchema({
+    id: 'stateUpdateFailed',
+    name: 'State Update Failed',
+    fields: {},
+});

package/build/esm/llm.types.d.ts

@@ -103,3 +103,14 @@ export interface SendMessageWithImage {
     imageBase64: string;
 }
 export type LllmReasoningEffort = ReasoningEffort;
+export interface ResponseParser {
+    parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
+    getStateUpdateInstructions(): string;
+    getFunctionCallInstructions(): string;
+}
+export interface ParsedResponse {
+    isDone: boolean;
+    state?: Record<string, any>;
+    message: string;
+    callbackResults?: SendMessage;
+}

package/build/esm/parsingResponses/ResponseParserFactory.d.ts

@@ -0,0 +1,10 @@
+import { ResponseParser } from '../llm.types';
+export default class ResponseParserFactory {
+    private static instance;
+    private static _version;
+    static set version(version: ParserVersion);
+    static get version(): ParserVersion;
+    static setInstance(parser: ResponseParser): void;
+    static getInstance(): ResponseParser;
+}
+export type ParserVersion = 'v1' | 'v2';

package/build/esm/parsingResponses/ResponseParserFactory.js

@@ -0,0 +1,21 @@
+import ResponseParserV1 from './ResponseParserV1.js';
+import ResponseParserV2 from './ResponseParserV2.js';
+class ResponseParserFactory {
+    static set version(version) {
+        this._version = version;
+        this.instance =
+            version === 'v1' ? new ResponseParserV1() : new ResponseParserV2();
+    }
+    static get version() {
+        return this._version;
+    }
+    static setInstance(parser) {
+        this.instance = parser;
+    }
+    static getInstance() {
+        return this.instance;
+    }
+}
+ResponseParserFactory.instance = new ResponseParserV2();
+ResponseParserFactory._version = 'v2';
+export default ResponseParserFactory;

package/build/esm/parsingResponses/ResponseParserV1.d.ts

@@ -0,0 +1,12 @@
+import { LlmCallbackMap, ParsedResponse, ResponseParser } from '../llm.types';
+export default class ResponseParserV1 implements ResponseParser {
+    parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
+    private validateAndNormalizeCallbackOptions;
+    private findFirstBadCallback;
+    private invokeCallbackAndDropInLegacyResults;
+    private doesIncludeDoneToken;
+    private parseState;
+    private assertAtMostOneCallback;
+    getStateUpdateInstructions(): string;
+    getFunctionCallInstructions(): string;
+}

package/build/esm/parsingResponses/{ResponseParser.js → ResponseParserV1.js}

@@ -7,31 +7,13 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __rest = (this && this.__rest) || function (s, e) {
-    var t = {};
-    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
-        t[p] = s[p];
-    if (s != null && typeof Object.getOwnPropertySymbols === "function")
-        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
-            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
-                t[p[i]] = s[p[i]];
-        }
-    return t;
-};
-import { normalizeSchemaValues, validateSchemaValues, } from '@sprucelabs/schema';
 import { DONE_TOKEN, STATE_BOUNDARY } from '../bots/templates.js';
 import SpruceError from '../errors/SpruceError.js';
 import renderPlaceholder from './renderPlaceholder.js';
-class ResponseParser {
-    static setInstance(parser) {
-        this.instance = parser;
-    }
-    static getInstance() {
-        return this.instance;
-    }
+import validateAndNormalizeCallbackOptions from './validateAndNormalizeCallbackOptions.js';
+export default class ResponseParserV1 {
     parse(response, callbacks) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
             let message = response.replace(DONE_TOKEN, '').trim();
             let state;
             let callbackResults;
@@ -68,17 +50,7 @@ class ResponseParser {
                     try {
                         const callback = callbacks === null || callbacks === void 0 ? void 0 : callbacks[key];
                         if (data) {
-                            const schema = {
-                                id: 'validationSchema',
-                                fields: {},
-                            };
-                            ((_a = callback === null || callback === void 0 ? void 0 : callback.parameters) !== null && _a !== void 0 ? _a : []).forEach((param) => {
-                                const { name } = param, rest = __rest(param, ["name"]);
-                                schema.fields[name] =
-                                    rest;
-                            });
-                            validateSchemaValues(schema, data);
-                            data = normalizeSchemaValues(schema, data);
+                            data = this.validateAndNormalizeCallbackOptions(callback, data);
                         }
                         callbackResults = yield (callback === null || callback === void 0 ? void 0 : callback.cb(data));
                         message = message.replace(xmlCallMatches[0], '').trim();
@@ -113,6 +85,11 @@ class ResponseParser {
             };
         });
     }
+    validateAndNormalizeCallbackOptions(callback, options) {
+        var _a;
+        options = validateAndNormalizeCallbackOptions((_a = callback === null || callback === void 0 ? void 0 : callback.parameters) !== null && _a !== void 0 ? _a : [], options);
+        return options;
+    }
     findFirstBadCallback(message) {
         const simpleMatches = message.match(new RegExp(`<<(.*)\/?>>`, 'g'));
         const extraJsonMatches = message.match(new RegExp(`<<.*?>>(.*?)<<\/.*?>>`, 'gs'));
@@ -145,6 +122,10 @@ class ResponseParser {
             });
         }
     }
+    getStateUpdateInstructions() {
+        return `Send updates to me in json format (something it can JSON.parse()) at the end of each response (it's not meant for reading, but for parsing, so don't call it out, but send it as we progress), surrounded by the State Boundary (${STATE_BOUNDARY}), like this:\n\n${STATE_BOUNDARY} { "fieldName": "fieldValue" } ${STATE_BOUNDARY}`;
+    }
+    getFunctionCallInstructions() {
+        return `A function call looks like this: <<FunctionName/>>. The API will respond with the results and then you can continue the conversation with your new knowledge. If the api call has parameters, call it like this: <<FunctionName>>{{parametersJsonEncoded}}<</FunctionName>>. Make sure to json encode the data and drop it between the function tags. Note: You can only make one API call at a time`;
+    }
 }
-ResponseParser.instance = new ResponseParser();
-export default ResponseParser;

package/build/esm/parsingResponses/ResponseParserV2.d.ts

@@ -0,0 +1,7 @@
+import { ResponseParser, LlmCallbackMap, ParsedResponse } from '../llm.types';
+export default class ResponseParserV2 implements ResponseParser {
+    parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
+    private invokeCallbacks;
+    getStateUpdateInstructions(): string;
+    getFunctionCallInstructions(): string;
+}

package/build/esm/parsingResponses/ResponseParserV2.js

@@ -0,0 +1,73 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { DONE_TOKEN } from '../bots/templates.js';
+import validateAndNormalizeCallbackOptions from './validateAndNormalizeCallbackOptions.js';
+export default class ResponseParserV2 {
+    parse(response, callbacks) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let message = response.replace(DONE_TOKEN, '').trim();
+            let state = undefined;
+            let callbackResults = undefined;
+            const hasCallbacks = message.includes('@callback');
+            if (hasCallbacks) {
+                callbackResults = yield this.invokeCallbacks(message, callbacks);
+            }
+            const hasState = response.includes('@updateState');
+            if (hasState) {
+                const stateMatch = message.match(/@updateState\s+({[\s\S]*?})\n?/);
+                if (stateMatch && stateMatch[1]) {
+                    state = JSON.parse(stateMatch[1]);
+                    message = message.replace(stateMatch[0], '').trim();
+                }
+            }
+            return {
+                isDone: response.includes(DONE_TOKEN),
+                message,
+                callbackResults,
+                state,
+            };
+        });
+    }
+    invokeCallbacks(message, callbacks) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let callbackResults = '';
+            const matches = [...message.matchAll(/^@callback\s+({.*})$/gm)];
+            for (const match of matches) {
+                const callbackData = match && match[1] ? JSON.parse(match[1]) : null;
+                const { name, options } = callbackData || {};
+                try {
+                    const callback = callbacks === null || callbacks === void 0 ? void 0 : callbacks[name];
+                    if (callback === null || callback === void 0 ? void 0 : callback.parameters) {
+                        validateAndNormalizeCallbackOptions(callback.parameters, options);
+                    }
+                    const results = yield (callback === null || callback === void 0 ? void 0 : callback.cb(options));
+                    callbackResults += `@results ${JSON.stringify({
+                        name,
+                        results,
+                    })}\n`;
+                }
+                catch (err) {
+                    callbackResults += `@results ${JSON.stringify({
+                        name,
+                        error: err,
+                    })}\n`;
+                }
+            }
+            callbackResults = callbackResults.trim();
+            return callbackResults;
+        });
+    }
+    getStateUpdateInstructions() {
+        return 'Updating state works similar to all function calls. Use the following syntax:\n@updateState { "updates": "here" }\n. Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send.';
+    }
+    getFunctionCallInstructions() {
+        return `A function call is done using the following syntax:\n@callback { "name": "callbackName", "options": {} }\nMake sure to json encode the options and include the name of the callback you want to call. You can call as many callbacks as you want in a single response by including multiple @callback lines.`;
+    }
+}

package/build/esm/parsingResponses/validateAndNormalizeCallbackOptions.d.ts

@@ -0,0 +1,2 @@
+import { LlmCallbackParameter } from '../llm.types';
+export default function validateAndNormalizeCallbackOptions(parameters: LlmCallbackParameter[], options: Record<string, any>): Record<string, any>;

package/build/esm/parsingResponses/validateAndNormalizeCallbackOptions.js

@@ -0,0 +1,26 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { validateSchemaValues, normalizeSchemaValues, } from '@sprucelabs/schema';
+export default function validateAndNormalizeCallbackOptions(parameters, options) {
+    const schema = {
+        id: 'validationSchema',
+        fields: {},
+    };
+    (parameters !== null && parameters !== void 0 ? parameters : []).forEach((param) => {
+        const { name } = param, rest = __rest(param, ["name"]);
+        schema.fields[name] =
+            rest;
+    });
+    validateSchemaValues(schema, options);
+    options = normalizeSchemaValues(schema, options);
+    return options;
+}

package/build/llm.types.d.ts

@@ -103,3 +103,14 @@ export interface SendMessageWithImage {
     imageBase64: string;
 }
 export type LllmReasoningEffort = ReasoningEffort;
+export interface ResponseParser {
+    parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
+    getStateUpdateInstructions(): string;
+    getFunctionCallInstructions(): string;
+}
+export interface ParsedResponse {
+    isDone: boolean;
+    state?: Record<string, any>;
+    message: string;
+    callbackResults?: SendMessage;
+}

package/build/parsingResponses/ResponseParserFactory.d.ts

@@ -0,0 +1,10 @@
+import { ResponseParser } from '../llm.types';
+export default class ResponseParserFactory {
+    private static instance;
+    private static _version;
+    static set version(version: ParserVersion);
+    static get version(): ParserVersion;
+    static setInstance(parser: ResponseParser): void;
+    static getInstance(): ResponseParser;
+}
+export type ParserVersion = 'v1' | 'v2';

package/build/parsingResponses/ResponseParserFactory.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ResponseParserV1_1 = __importDefault(require("./ResponseParserV1"));
+const ResponseParserV2_1 = __importDefault(require("./ResponseParserV2"));
+class ResponseParserFactory {
+    static set version(version) {
+        this._version = version;
+        this.instance =
+            version === 'v1' ? new ResponseParserV1_1.default() : new ResponseParserV2_1.default();
+    }
+    static get version() {
+        return this._version;
+    }
+    static setInstance(parser) {
+        this.instance = parser;
+    }
+    static getInstance() {
+        return this.instance;
+    }
+}
+ResponseParserFactory.instance = new ResponseParserV2_1.default();
+ResponseParserFactory._version = 'v2';
+exports.default = ResponseParserFactory;

package/build/parsingResponses/ResponseParserV1.d.ts

@@ -0,0 +1,12 @@
+import { LlmCallbackMap, ParsedResponse, ResponseParser } from '../llm.types';
+export default class ResponseParserV1 implements ResponseParser {
+    parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
+    private validateAndNormalizeCallbackOptions;
+    private findFirstBadCallback;
+    private invokeCallbackAndDropInLegacyResults;
+    private doesIncludeDoneToken;
+    private parseState;
+    private assertAtMostOneCallback;
+    getStateUpdateInstructions(): string;
+    getFunctionCallInstructions(): string;
+}

package/build/parsingResponses/{ResponseParser.js → ResponseParserV1.js}

@@ -3,17 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const schema_1 = require("@sprucelabs/schema");
 const templates_1 = require("../bots/templates");
 const SpruceError_1 = __importDefault(require("../errors/SpruceError"));
 const renderPlaceholder_1 = __importDefault(require("./renderPlaceholder"));
-class ResponseParser {
-    static setInstance(parser) {
-        this.instance = parser;
-    }
-    static getInstance() {
-        return this.instance;
-    }
+const validateAndNormalizeCallbackOptions_1 = __importDefault(require("./validateAndNormalizeCallbackOptions"));
+class ResponseParserV1 {
     async parse(response, callbacks) {
         let message = response.replace(templates_1.DONE_TOKEN, '').trim();
         let state;
@@ -51,17 +45,7 @@ class ResponseParser {
                 try {
                     const callback = callbacks?.[key];
                     if (data) {
-                        const schema = {
-                            id: 'validationSchema',
-                            fields: {},
-                        };
-                        (callback?.parameters ?? []).forEach((param) => {
-                            const { name, ...rest } = param;
-                            schema.fields[name] =
-                                rest;
-                        });
-                        (0, schema_1.validateSchemaValues)(schema, data);
-                        data = (0, schema_1.normalizeSchemaValues)(schema, data);
+                        data = this.validateAndNormalizeCallbackOptions(callback, data);
                     }
                     callbackResults = await callback?.cb(data);
                     message = message.replace(xmlCallMatches[0], '').trim();
@@ -95,6 +79,10 @@ class ResponseParser {
             callbackResults: callbackResults ?? undefined,
         };
     }
+    validateAndNormalizeCallbackOptions(callback, options) {
+        options = (0, validateAndNormalizeCallbackOptions_1.default)(callback?.parameters ?? [], options);
+        return options;
+    }
     findFirstBadCallback(message) {
         const simpleMatches = message.match(new RegExp(`<<(.*)\/?>>`, 'g'));
         const extraJsonMatches = message.match(new RegExp(`<<.*?>>(.*?)<<\/.*?>>`, 'gs'));
@@ -124,6 +112,11 @@ class ResponseParser {
             });
         }
     }
+    getStateUpdateInstructions() {
+        return `Send updates to me in json format (something it can JSON.parse()) at the end of each response (it's not meant for reading, but for parsing, so don't call it out, but send it as we progress), surrounded by the State Boundary (${templates_1.STATE_BOUNDARY}), like this:\n\n${templates_1.STATE_BOUNDARY} { "fieldName": "fieldValue" } ${templates_1.STATE_BOUNDARY}`;
+    }
+    getFunctionCallInstructions() {
+        return `A function call looks like this: <<FunctionName/>>. The API will respond with the results and then you can continue the conversation with your new knowledge. If the api call has parameters, call it like this: <<FunctionName>>{{parametersJsonEncoded}}<</FunctionName>>. Make sure to json encode the data and drop it between the function tags. Note: You can only make one API call at a time`;
+    }
 }
-ResponseParser.instance = new ResponseParser();
-exports.default = ResponseParser;
+exports.default = ResponseParserV1;

package/build/parsingResponses/ResponseParserV2.d.ts

@@ -0,0 +1,7 @@
+import { ResponseParser, LlmCallbackMap, ParsedResponse } from '../llm.types';
+export default class ResponseParserV2 implements ResponseParser {
+    parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
+    private invokeCallbacks;
+    getStateUpdateInstructions(): string;
+    getFunctionCallInstructions(): string;
+}

package/build/parsingResponses/ResponseParserV2.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const templates_1 = require("../bots/templates");
+const validateAndNormalizeCallbackOptions_1 = __importDefault(require("./validateAndNormalizeCallbackOptions"));
+class ResponseParserV2 {
+    async parse(response, callbacks) {
+        let message = response.replace(templates_1.DONE_TOKEN, '').trim();
+        let state = undefined;
+        let callbackResults = undefined;
+        const hasCallbacks = message.includes('@callback');
+        if (hasCallbacks) {
+            callbackResults = await this.invokeCallbacks(message, callbacks);
+        }
+        const hasState = response.includes('@updateState');
+        if (hasState) {
+            const stateMatch = message.match(/@updateState\s+({[\s\S]*?})\n?/);
+            if (stateMatch && stateMatch[1]) {
+                state = JSON.parse(stateMatch[1]);
+                message = message.replace(stateMatch[0], '').trim();
+            }
+        }
+        return {
+            isDone: response.includes(templates_1.DONE_TOKEN),
+            message,
+            callbackResults,
+            state,
+        };
+    }
+    async invokeCallbacks(message, callbacks) {
+        let callbackResults = '';
+        const matches = [...message.matchAll(/^@callback\s+({.*})$/gm)];
+        for (const match of matches) {
+            const callbackData = match && match[1] ? JSON.parse(match[1]) : null;
+            const { name, options } = callbackData || {};
+            try {
+                const callback = callbacks?.[name];
+                if (callback?.parameters) {
+                    (0, validateAndNormalizeCallbackOptions_1.default)(callback.parameters, options);
+                }
+                const results = await callback?.cb(options);
+                callbackResults += `@results ${JSON.stringify({
+                    name,
+                    results,
+                })}\n`;
+            }
+            catch (err) {
+                callbackResults += `@results ${JSON.stringify({
+                    name,
+                    error: err,
+                })}\n`;
+            }
+        }
+        callbackResults = callbackResults.trim();
+        return callbackResults;
+    }
+    getStateUpdateInstructions() {
+        return 'Updating state works similar to all function calls. Use the following syntax:\n@updateState { "updates": "here" }\n. Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send.';
+    }
+    getFunctionCallInstructions() {
+        return `A function call is done using the following syntax:\n@callback { "name": "callbackName", "options": {} }\nMake sure to json encode the options and include the name of the callback you want to call. You can call as many callbacks as you want in a single response by including multiple @callback lines.`;
+    }
+}
+exports.default = ResponseParserV2;

package/build/parsingResponses/validateAndNormalizeCallbackOptions.d.ts

@@ -0,0 +1,2 @@
+import { LlmCallbackParameter } from '../llm.types';
+export default function validateAndNormalizeCallbackOptions(parameters: LlmCallbackParameter[], options: Record<string, any>): Record<string, any>;

package/build/parsingResponses/validateAndNormalizeCallbackOptions.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = validateAndNormalizeCallbackOptions;
+const schema_1 = require("@sprucelabs/schema");
+function validateAndNormalizeCallbackOptions(parameters, options) {
+    const schema = {
+        id: 'validationSchema',
+        fields: {},
+    };
+    (parameters ?? []).forEach((param) => {
+        const { name, ...rest } = param;
+        schema.fields[name] =
+            rest;
+    });
+    (0, schema_1.validateSchemaValues)(schema, options);
+    options = (0, schema_1.normalizeSchemaValues)(schema, options);
+    return options;
+}

package/package.json

@@ -8,7 +8,7 @@
       "eta"
     ]
   },
-  "version": "14.3.3",
+  "version": "15.0.0",
   "files": [
     "build"
   ],
@@ -67,32 +67,32 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
     "@sprucelabs/error": "^8.1.12",
-    "@sprucelabs/mercury-event-emitter": "^46.1.10",
-    "@sprucelabs/mercury-types": "^49.1.12",
-    "@sprucelabs/schema": "^33.2.9",
-    "@sprucelabs/spruce-skill-utils": "^34.0.18",
+    "@sprucelabs/mercury-event-emitter": "^46.1.11",
+    "@sprucelabs/mercury-types": "^49.1.13",
+    "@sprucelabs/schema": "^34.0.0",
+    "@sprucelabs/spruce-skill-utils": "^34.0.19",
     "eta": "3.5.0",
-    "openai": "^6.23.0"
+    "openai": "^6.27.0"
   },
   "resolutions": {
     "eta": "3.5.0"
   },
   "devDependencies": {
-    "@regressionproof/cli": "^0.9.1",
-    "@regressionproof/jest-reporter": "^0.9.1",
-    "@sprucelabs/esm-postbuild": "^9.0.20",
-    "@sprucelabs/jest-json-reporter": "^10.0.28",
-    "@sprucelabs/resolve-path-aliases": "^4.0.20",
+    "@regressionproof/cli": "^0.9.4",
+    "@regressionproof/jest-reporter": "^0.9.4",
+    "@sprucelabs/esm-postbuild": "^9.0.21",
+    "@sprucelabs/jest-json-reporter": "^10.0.29",
+    "@sprucelabs/resolve-path-aliases": "^4.0.21",
     "@sprucelabs/semantic-release": "^6.0.0",
     "@sprucelabs/test": "^11.1.6",
     "@sprucelabs/test-utils": "^7.2.15",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.4.0",
     "chokidar-cli": "^3.0.0",
     "dotenv": "^17.3.1",
-    "eslint": "^10.0.2",
+    "eslint": "^10.0.3",
     "eslint-config-spruce": "^11.2.35",
-    "jest": "^30.2.0",
-    "jest-circus": "^30.2.0",
+    "jest": "^30.3.0",
+    "jest-circus": "^30.3.0",
     "prettier": "^3.8.1",
     "ts-node": "^10.9.2",
     "tsc-watch": "^7.2.0",

package/build/esm/parsingResponses/ResponseParser.d.ts

@@ -1,18 +0,0 @@
-import { LlmCallbackMap, SendMessage } from '../llm.types';
-export default class ResponseParser {
-    private static instance;
-    static setInstance(parser: ResponseParser): void;
-    static getInstance(): ResponseParser;
-    parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
-    private findFirstBadCallback;
-    private invokeCallbackAndDropInLegacyResults;
-    private doesIncludeDoneToken;
-    private parseState;
-    private assertAtMostOneCallback;
-}
-export interface ParsedResponse {
-    isDone: boolean;
-    state?: Record<string, any>;
-    message: string;
-    callbackResults?: SendMessage;
-}

package/build/parsingResponses/ResponseParser.d.ts

@@ -1,18 +0,0 @@
-import { LlmCallbackMap, SendMessage } from '../llm.types';
-export default class ResponseParser {
-    private static instance;
-    static setInstance(parser: ResponseParser): void;
-    static getInstance(): ResponseParser;
-    parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
-    private findFirstBadCallback;
-    private invokeCallbackAndDropInLegacyResults;
-    private doesIncludeDoneToken;
-    private parseState;
-    private assertAtMostOneCallback;
-}
-export interface ParsedResponse {
-    isDone: boolean;
-    state?: Record<string, any>;
-    message: string;
-    callbackResults?: SendMessage;
-}