modelfusion 0.42.0 → 0.44.0

package/README.md

@@ -19,8 +19,9 @@ ModelFusion is a library for building AI apps, chatbots, and agents. It provides
 
 - **Multimodal Support**: Beyond just LLMs, ModelFusion encompasses a diverse array of models including text generation, text-to-speech, speech-to-text, and image generation, allowing you to build multifaceted AI applications with ease.
 - **Flexibility and control**: AI application development can be complex and unique to each project. With ModelFusion, you have complete control over the prompts and model settings, and you can access the raw responses from the models quickly to build what you need.
-- **Type inference and validation**: ModelFusion uses TypeScript and [Zod](https://github.com/colinhacks/zod) to infer types wherever possible and to validate model responses.
-- **Integrated support features**: Essential features like logging, retries, throttling, tracing, and error handling are built-in, helping you focus more on building your application.
+- **Type inference and validation**: ModelFusion uses TypeScript to infer types wherever possible and to validate model responses. By default, [Zod](https://github.com/colinhacks/zod) is used for type validation, but you can also use other libraries.
+- **Guards**: ModelFusion provides a guard function that you can use to implement retry on error, redacting and changing reponses, etc.
+- **Integrated support features**: Essential features like **observability**, logging, retries, throttling, tracing, and error handling are built-in, helping you focus more on building your application.
 
 ## Quick Install
 
@@ -454,6 +455,41 @@ const retrievedTexts = await retrieve(
 
 Available Vector Stores: [Memory](https://modelfusion.dev/integration/vector-index/memory), [Pinecone](https://modelfusion.dev/integration/vector-index/pinecone)
 
+### Guards
+
+[Guards](https://github.com/lgrammel/modelfusion/tree/main/examples/basic/src/guard) can be used to implement retry on error, redacting and changing reponses, etc.
+
+#### Retry structure parsing on error:
+
+```ts
+const result = await guard(
+  (input) =>
+    generateStructure(
+      new OpenAIChatModel({
+        // ...
+      }),
+      new ZodStructureDefinition({
+        // ...
+      }),
+      input
+    ),
+  [
+    // ...
+  ],
+  fixStructure({
+    modifyInputForRetry: async ({ input, error }) => [
+      ...input,
+      OpenAIChatMessage.functionCall(null, {
+        name: error.structureName,
+        arguments: error.valueText,
+      }),
+      OpenAIChatMessage.user(error.message),
+      OpenAIChatMessage.user("Please fix the error and try again."),
+    ],
+  })
+);
+```
+
 ### Observability
 
 Integrations: [Helicone](https://modelfusion.dev/integration/observability/helicone)
@@ -560,3 +596,7 @@ Extracts information about a topic from a PDF and writes a tweet in your own sty
 ### [Contributing Guide](https://github.com/lgrammel/modelfusion/blob/main/CONTRIBUTING.md)
 
 Read the [ModelFusion contributing guide](https://github.com/lgrammel/modelfusion/blob/main/CONTRIBUTING.md) to learn about the development process, how to propose bugfixes and improvements, and how to build and test your changes.
+
+```
+
+```

package/core/getRun.cjs

@@ -0,0 +1,60 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRun = exports.getRun = void 0;
+let runStorage;
+const isNode = typeof process !== "undefined" &&
+    process.versions != null &&
+    process.versions.node != null;
+async function ensureLoaded() {
+    if (!isNode)
+        return Promise.resolve();
+    if (!runStorage) {
+        const { AsyncLocalStorage } = await Promise.resolve().then(() => __importStar(require("node:async_hooks")));
+        runStorage = new AsyncLocalStorage();
+    }
+    return Promise.resolve();
+}
+/**
+ * Returns the run stored in an AsyncLocalStorage if running in Node.js. It can be set with `withRun()`.
+ */
+async function getRun(run) {
+    await ensureLoaded();
+    return run ?? runStorage?.getStore();
+}
+exports.getRun = getRun;
+/**
+ * Stores the run in an AsyncLocalStorage if running in Node.js. It can be retrieved with `getRun()`.
+ */
+async function withRun(run, callback) {
+    await ensureLoaded();
+    if (runStorage != null) {
+        await runStorage.run(run, callback);
+    }
+    else {
+        await callback();
+    }
+}
+exports.withRun = withRun;

package/core/getRun.d.ts

@@ -0,0 +1,9 @@
+import { Run } from "./Run";
+/**
+ * Returns the run stored in an AsyncLocalStorage if running in Node.js. It can be set with `withRun()`.
+ */
+export declare function getRun(run?: Run): Promise<Run | undefined>;
+/**
+ * Stores the run in an AsyncLocalStorage if running in Node.js. It can be retrieved with `getRun()`.
+ */
+export declare function withRun(run: Run, callback: () => PromiseLike<void>): Promise<void>;

package/core/getRun.js

@@ -0,0 +1,32 @@
+let runStorage;
+const isNode = typeof process !== "undefined" &&
+    process.versions != null &&
+    process.versions.node != null;
+async function ensureLoaded() {
+    if (!isNode)
+        return Promise.resolve();
+    if (!runStorage) {
+        const { AsyncLocalStorage } = await import("node:async_hooks");
+        runStorage = new AsyncLocalStorage();
+    }
+    return Promise.resolve();
+}
+/**
+ * Returns the run stored in an AsyncLocalStorage if running in Node.js. It can be set with `withRun()`.
+ */
+export async function getRun(run) {
+    await ensureLoaded();
+    return run ?? runStorage?.getStore();
+}
+/**
+ * Stores the run in an AsyncLocalStorage if running in Node.js. It can be retrieved with `getRun()`.
+ */
+export async function withRun(run, callback) {
+    await ensureLoaded();
+    if (runStorage != null) {
+        await runStorage.run(run, callback);
+    }
+    else {
+        await callback();
+    }
+}

package/core/index.cjs

@@ -24,4 +24,5 @@ __exportStar(require("./GlobalFunctionObservers.cjs"), exports);
 __exportStar(require("./Run.cjs"), exports);
 __exportStar(require("./Vector.cjs"), exports);
 __exportStar(require("./api/index.cjs"), exports);
+__exportStar(require("./getRun.cjs"), exports);
 __exportStar(require("./structure/index.cjs"), exports);

package/core/index.d.ts

@@ -8,4 +8,5 @@ export * from "./GlobalFunctionObservers.js";
 export * from "./Run.js";
 export * from "./Vector.js";
 export * from "./api/index.js";
+export * from "./getRun.js";
 export * from "./structure/index.js";

package/core/index.js

@@ -8,4 +8,5 @@ export * from "./GlobalFunctionObservers.js";
 export * from "./Run.js";
 export * from "./Vector.js";
 export * from "./api/index.js";
+export * from "./getRun.js";
 export * from "./structure/index.js";

package/guard/fixStructure.cjs

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fixStructure = void 0;
+const StructureParseError_js_1 = require("../model-function/generate-structure/StructureParseError.cjs");
+const StructureValidationError_js_1 = require("../model-function/generate-structure/StructureValidationError.cjs");
+const fixStructure = ({ modifyInputForRetry }) => async (result) => {
+    if (result.type === "error" &&
+        (result.error instanceof StructureValidationError_js_1.StructureValidationError ||
+            result.error instanceof StructureParseError_js_1.StructureParseError)) {
+        return {
+            action: "retry",
+            input: await modifyInputForRetry({
+                type: "error",
+                input: result.input,
+                error: result.error,
+            }),
+        };
+    }
+    return undefined;
+};
+exports.fixStructure = fixStructure;

package/guard/fixStructure.d.ts

@@ -0,0 +1,10 @@
+import { StructureParseError } from "../model-function/generate-structure/StructureParseError.js";
+import { StructureValidationError } from "../model-function/generate-structure/StructureValidationError.js";
+import { Guard } from "./guard.js";
+export declare const fixStructure: <INPUT, OUTPUT>(options: {
+    modifyInputForRetry: (options: {
+        type: "error";
+        input: INPUT;
+        error: StructureValidationError | StructureParseError;
+    }) => PromiseLike<INPUT>;
+}) => Guard<INPUT, OUTPUT>;

package/guard/fixStructure.js

@@ -0,0 +1,17 @@
+import { StructureParseError } from "../model-function/generate-structure/StructureParseError.js";
+import { StructureValidationError } from "../model-function/generate-structure/StructureValidationError.js";
+export const fixStructure = ({ modifyInputForRetry }) => async (result) => {
+    if (result.type === "error" &&
+        (result.error instanceof StructureValidationError ||
+            result.error instanceof StructureParseError)) {
+        return {
+            action: "retry",
+            input: await modifyInputForRetry({
+                type: "error",
+                input: result.input,
+                error: result.error,
+            }),
+        };
+    }
+    return undefined;
+};

package/guard/guard.cjs

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.guard = void 0;
+async function guard(execute, input, guards, options) {
+    if (typeof guards === "function") {
+        guards = [guards];
+    }
+    const maxRetries = options?.maxRetries ?? 1;
+    let attempts = 0;
+    while (attempts <= maxRetries) {
+        let result;
+        try {
+            result = {
+                type: "value",
+                input,
+                output: await execute(input),
+            };
+        }
+        catch (error) {
+            result = {
+                type: "error",
+                input,
+                error,
+            };
+        }
+        let isValid = true;
+        for (const guard of guards) {
+            const guardResult = await guard(result);
+            if (guardResult === undefined) {
+                continue;
+            }
+            switch (guardResult.action) {
+                case "passThrough": {
+                    break;
+                }
+                case "retry": {
+                    input = guardResult.input;
+                    isValid = false;
+                    break;
+                }
+                case "return": {
+                    result = {
+                        type: "value",
+                        input,
+                        output: guardResult.output,
+                    };
+                    break;
+                }
+                case "throwError": {
+                    result = {
+                        type: "error",
+                        input,
+                        error: guardResult.error,
+                    };
+                    break;
+                }
+            }
+        }
+        if (isValid) {
+            if (result.type === "value") {
+                return result.output;
+            }
+            else {
+                throw result.error;
+            }
+        }
+        attempts++;
+    }
+    throw new Error(`Maximum retry attempts of ${maxRetries} reached ` +
+        `without producing a valid output or handling an error after ${attempts} attempts.`);
+}
+exports.guard = guard;

package/guard/guard.d.ts

@@ -0,0 +1,28 @@
+type OutputResult<INPUT, OUTPUT> = {
+    type: "value";
+    input: INPUT;
+    output: OUTPUT;
+    error?: undefined;
+} | {
+    type: "error";
+    input: INPUT;
+    output?: undefined;
+    error: unknown;
+};
+export type OutputValidator<INPUT, OUTPUT> = ({ type, input, output, error, }: OutputResult<INPUT, OUTPUT>) => PromiseLike<boolean>;
+export type Guard<INPUT, OUTPUT> = ({ type, input, output, error, }: OutputResult<INPUT, OUTPUT>) => PromiseLike<{
+    action: "retry";
+    input: INPUT;
+} | {
+    action: "return";
+    output: OUTPUT;
+} | {
+    action: "throwError";
+    error: unknown;
+} | {
+    action: "passThrough";
+} | undefined>;
+export declare function guard<INPUT, OUTPUT>(execute: (input: INPUT) => PromiseLike<OUTPUT>, input: INPUT, guards: Array<Guard<INPUT, OUTPUT>> | Guard<INPUT, OUTPUT>, options?: {
+    maxRetries: number;
+}): Promise<OUTPUT | undefined>;
+export {};

package/guard/guard.js

@@ -0,0 +1,68 @@
+export async function guard(execute, input, guards, options) {
+    if (typeof guards === "function") {
+        guards = [guards];
+    }
+    const maxRetries = options?.maxRetries ?? 1;
+    let attempts = 0;
+    while (attempts <= maxRetries) {
+        let result;
+        try {
+            result = {
+                type: "value",
+                input,
+                output: await execute(input),
+            };
+        }
+        catch (error) {
+            result = {
+                type: "error",
+                input,
+                error,
+            };
+        }
+        let isValid = true;
+        for (const guard of guards) {
+            const guardResult = await guard(result);
+            if (guardResult === undefined) {
+                continue;
+            }
+            switch (guardResult.action) {
+                case "passThrough": {
+                    break;
+                }
+                case "retry": {
+                    input = guardResult.input;
+                    isValid = false;
+                    break;
+                }
+                case "return": {
+                    result = {
+                        type: "value",
+                        input,
+                        output: guardResult.output,
+                    };
+                    break;
+                }
+                case "throwError": {
+                    result = {
+                        type: "error",
+                        input,
+                        error: guardResult.error,
+                    };
+                    break;
+                }
+            }
+        }
+        if (isValid) {
+            if (result.type === "value") {
+                return result.output;
+            }
+            else {
+                throw result.error;
+            }
+        }
+        attempts++;
+    }
+    throw new Error(`Maximum retry attempts of ${maxRetries} reached ` +
+        `without producing a valid output or handling an error after ${attempts} attempts.`);
+}

package/guard/index.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./fixStructure.cjs"), exports);
+__exportStar(require("./guard.cjs"), exports);

package/guard/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./fixStructure.js";
+export * from "./guard.js";

package/guard/index.js

@@ -0,0 +1,2 @@
+export * from "./fixStructure.js";
+export * from "./guard.js";

package/index.cjs

@@ -18,6 +18,7 @@ __exportStar(require("./composed-function/index.cjs"), exports);
 __exportStar(require("./core/index.cjs"), exports);
 __exportStar(require("./cost/index.cjs"), exports);
 __exportStar(require("./event-source/index.cjs"), exports);
+__exportStar(require("./guard/index.cjs"), exports);
 __exportStar(require("./model-function/index.cjs"), exports);
 __exportStar(require("./model-provider/index.cjs"), exports);
 __exportStar(require("./observability/index.cjs"), exports);

package/index.d.ts

@@ -2,6 +2,7 @@ export * from "./composed-function/index.js";
 export * from "./core/index.js";
 export * from "./cost/index.js";
 export * from "./event-source/index.js";
+export * from "./guard/index.js";
 export * from "./model-function/index.js";
 export * from "./model-provider/index.js";
 export * from "./observability/index.js";

package/index.js

@@ -2,6 +2,7 @@ export * from "./composed-function/index.js";
 export * from "./core/index.js";
 export * from "./cost/index.js";
 export * from "./event-source/index.js";
+export * from "./guard/index.js";
 export * from "./model-function/index.js";
 export * from "./model-provider/index.js";
 export * from "./observability/index.js";

package/model-function/executeCall.cjs

@@ -7,6 +7,7 @@ const GlobalFunctionLogging_js_1 = require("../core/GlobalFunctionLogging.cjs");
 const GlobalFunctionObservers_js_1 = require("../core/GlobalFunctionObservers.cjs");
 const AbortError_js_1 = require("../core/api/AbortError.cjs");
 const getFunctionCallLogger_js_1 = require("../core/getFunctionCallLogger.cjs");
+const getRun_js_1 = require("../core/getRun.cjs");
 const DurationMeasurement_js_1 = require("../util/DurationMeasurement.cjs");
 const runSafe_js_1 = require("../util/runSafe.cjs");
 class ModelFunctionPromise extends Promise {
@@ -54,7 +55,7 @@ function executeCall({ model, options, input, functionType, generateResponse, })
 }
 exports.executeCall = executeCall;
 async function doExecuteCall({ model, options, input, functionType, generateResponse, }) {
-    const run = options?.run;
+    const run = await (0, getRun_js_1.getRun)(options?.run);
     const settings = model.settings;
     const eventSource = new FunctionEventSource_js_1.FunctionEventSource({
         observers: [
@@ -84,7 +85,12 @@ async function doExecuteCall({ model, options, input, functionType, generateResp
         eventType: "started",
         ...startMetadata,
     });
-    const result = await (0, runSafe_js_1.runSafe)(() => generateResponse(options));
+    const result = await (0, runSafe_js_1.runSafe)(() => generateResponse({
+        functionId: options?.functionId,
+        logging: options?.logging,
+        observers: options?.observers,
+        run,
+    }));
     const finishMetadata = {
         eventType: "finished",
         ...startMetadata,

package/model-function/executeCall.js

@@ -4,6 +4,7 @@ import { getGlobalFunctionLogging } from "../core/GlobalFunctionLogging.js";
 import { getGlobalFunctionObservers } from "../core/GlobalFunctionObservers.js";
 import { AbortError } from "../core/api/AbortError.js";
 import { getFunctionCallLogger } from "../core/getFunctionCallLogger.js";
+import { getRun } from "../core/getRun.js";
 import { startDurationMeasurement } from "../util/DurationMeasurement.js";
 import { runSafe } from "../util/runSafe.js";
 export class ModelFunctionPromise extends Promise {
@@ -49,7 +50,7 @@ export function executeCall({ model, options, input, functionType, generateRespo
     }));
 }
 async function doExecuteCall({ model, options, input, functionType, generateResponse, }) {
-    const run = options?.run;
+    const run = await getRun(options?.run);
     const settings = model.settings;
     const eventSource = new FunctionEventSource({
         observers: [
@@ -79,7 +80,12 @@ async function doExecuteCall({ model, options, input, functionType, generateResp
         eventType: "started",
         ...startMetadata,
     });
-    const result = await runSafe(() => generateResponse(options));
+    const result = await runSafe(() => generateResponse({
+        functionId: options?.functionId,
+        logging: options?.logging,
+        observers: options?.observers,
+        run,
+    }));
     const finishMetadata = {
         eventType: "finished",
         ...startMetadata,

package/model-function/generate-structure/StructureFromTextGenerationModel.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StructureFromTextGenerationModel = void 0;
 const generateText_js_1 = require("../generate-text/generateText.cjs");
+const StructureParseError_js_1 = require("./StructureParseError.cjs");
 class StructureFromTextGenerationModel {
     constructor({ model, format, }) {
         Object.defineProperty(this, "model", {
@@ -30,10 +31,20 @@ class StructureFromTextGenerationModel {
     }
     async doGenerateStructure(structure, prompt, options) {
         const { response, value } = await (0, generateText_js_1.generateText)(this.model, this.format.createPrompt(prompt, structure), options).asFullResponse();
-        return {
-            response,
-            structure: this.format.extractStructure(value),
-        };
+        try {
+            return {
+                response,
+                value: this.format.extractStructure(value),
+                valueText: value,
+            };
+        }
+        catch (error) {
+            throw new StructureParseError_js_1.StructureParseError({
+                structureName: structure.name,
+                valueText: value,
+                cause: error,
+            });
+        }
     }
     withSettings(additionalSettings) {
         return new StructureFromTextGenerationModel({

package/model-function/generate-structure/StructureFromTextGenerationModel.d.ts

@@ -18,7 +18,8 @@ export declare class StructureFromTextGenerationModel<PROMPT, MODEL extends Text
     get settingsForEvent(): Partial<MODEL["settings"]>;
     doGenerateStructure(structure: StructureDefinition<string, unknown>, prompt: PROMPT, options?: FunctionOptions): Promise<{
         response: unknown;
-        structure: unknown;
+        value: unknown;
+        valueText: string;
     }>;
     withSettings(additionalSettings: Partial<MODEL["settings"]>): this;
 }

package/model-function/generate-structure/StructureFromTextGenerationModel.js

@@ -1,4 +1,5 @@
 import { generateText } from "../generate-text/generateText.js";
+import { StructureParseError } from "./StructureParseError.js";
 export class StructureFromTextGenerationModel {
     constructor({ model, format, }) {
         Object.defineProperty(this, "model", {
@@ -27,10 +28,20 @@ export class StructureFromTextGenerationModel {
     }
     async doGenerateStructure(structure, prompt, options) {
         const { response, value } = await generateText(this.model, this.format.createPrompt(prompt, structure), options).asFullResponse();
-        return {
-            response,
-            structure: this.format.extractStructure(value),
-        };
+        try {
+            return {
+                response,
+                value: this.format.extractStructure(value),
+                valueText: value,
+            };
+        }
+        catch (error) {
+            throw new StructureParseError({
+                structureName: structure.name,
+                valueText: value,
+                cause: error,
+            });
+        }
     }
     withSettings(additionalSettings) {
         return new StructureFromTextGenerationModel({

package/model-function/generate-structure/StructureGenerationModel.d.ts

@@ -7,7 +7,8 @@ export interface StructureGenerationModelSettings extends ModelSettings {
 export interface StructureGenerationModel<PROMPT, SETTINGS extends StructureGenerationModelSettings = StructureGenerationModelSettings> extends Model<SETTINGS> {
     doGenerateStructure(structure: StructureDefinition<string, unknown>, prompt: PROMPT, options?: FunctionOptions): PromiseLike<{
         response: unknown;
-        structure: unknown;
+        valueText: string;
+        value: unknown;
         usage?: {
             promptTokens: number;
             completionTokens: number;

package/model-function/generate-structure/StructureOrTextGenerationModel.d.ts

@@ -9,10 +9,12 @@ export interface StructureOrTextGenerationModel<PROMPT, SETTINGS extends Structu
         structureAndText: {
             structure: null;
             value: null;
+            valueText: null;
             text: string;
         } | {
             structure: string;
             value: unknown;
+            valueText: string;
             text: string | null;
         };
         usage?: {