modelfusion 0.47.0 → 0.47.2

package/README.md

@@ -1,6 +1,6 @@
 # ModelFusion
 
-> ### Build AI applications, chatbots, and agents with JavaScript and TypeScript.
+> ### Build multi-modal AI apps, chatbots, and agents with JavaScript and TypeScript.
 
 [![NPM Version](https://img.shields.io/npm/v/modelfusion?color=33cd56&logo=npm)](https://www.npmjs.com/package/modelfusion)
 [![MIT License](https://img.shields.io/github/license/lgrammel/modelfusion)](https://opensource.org/licenses/MIT)
@@ -360,6 +360,41 @@ const reconstructedText = await tokenizer.detokenize(tokens);
 
 Providers: [OpenAI](https://modelfusion.dev/integration/model-provider/openai), [Cohere](https://modelfusion.dev/integration/model-provider/cohere), [Llama.cpp](https://modelfusion.dev/integration/model-provider/llamacpp)
 
+### [Guards](https://modelfusion.dev/guide/guard)
+
+Guard functions 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."),
+    ],
+  })
+);
+```
+
 ### [Upserting and Retrieving Objects from Vector Indices](https://modelfusion.dev/guide/vector-index)
 
 ```ts
@@ -396,41 +431,6 @@ 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."),
-    ],
-  })
-);
-```
-
 ### Prompt Formats
 
 Prompt formats let you use higher level prompt structures (such as instruction or chat prompts) for different models.
@@ -536,6 +536,7 @@ Integrations: [Helicone](https://modelfusion.dev/integration/observability/helic
   - [Describe Image](https://modelfusion.dev/guide/function/describe-image)
   - [Generate Image](https://modelfusion.dev/guide/function/generate-image)
     - [Prompt Format](https://modelfusion.dev/guide/function/generate-image/prompt-format)
+- [Guards](https://modelfusion.dev/guide/guard)
 - [Tools](https://modelfusion.dev/guide/tools)
 - [Vector Indices](https://modelfusion.dev/guide/vector-index)
   - [Upsert](https://modelfusion.dev/guide/vector-index/upsert)

package/core/structure/Schema.d.ts

@@ -1,14 +1,14 @@
 /**
- * Validates that the structure of `value` matches the structure of this schema.
+ * Validates that the structure of `data` matches the structure of this schema.
  */
 export interface Schema<STRUCTURE> {
     /**
-     * Validates that the structure of `value` matches the structure of this schema,
-     * and returns a typed version of value if it does.
+     * Validates that the structure of `data` matches the structure of this schema,
+     * and returns a typed version of data if it does.
      */
-    validate(value: unknown): {
+    validate(data: unknown): {
         success: true;
-        value: STRUCTURE;
+        data: STRUCTURE;
     } | {
         success: false;
         error: unknown;

package/core/structure/UncheckedSchema.cjs

@@ -16,8 +16,8 @@ class UncheckedSchema {
             value: void 0
         });
     }
-    validate(value) {
-        return { success: true, value: value };
+    validate(data) {
+        return { success: true, data: data };
     }
     getJsonSchema() {
         return this.jsonSchema;

package/core/structure/UncheckedSchema.d.ts

@@ -2,9 +2,9 @@ import { Schema } from "./Schema.js";
 export declare class UncheckedSchema<STRUCTURE> implements Schema<STRUCTURE> {
     private readonly jsonSchema?;
     constructor(jsonSchema?: unknown);
-    validate(value: unknown): {
+    validate(data: unknown): {
         success: true;
-        value: STRUCTURE;
+        data: STRUCTURE;
     } | {
         success: false;
         error: unknown;

package/core/structure/UncheckedSchema.js

@@ -13,8 +13,8 @@ export class UncheckedSchema {
             value: void 0
         });
     }
-    validate(value) {
-        return { success: true, value: value };
+    validate(data) {
+        return { success: true, data: data };
     }
     getJsonSchema() {
         return this.jsonSchema;

package/core/structure/ZodSchema.cjs

@@ -18,11 +18,8 @@ class ZodSchema {
         });
         this.zodSchema = zodSchema;
     }
-    validate(value) {
-        const parseResult = this.zodSchema.safeParse(value);
-        return parseResult.success
-            ? { success: true, value: parseResult.data }
-            : parseResult;
+    validate(data) {
+        return this.zodSchema.safeParse(data);
     }
     getJsonSchema() {
         return (0, zod_to_json_schema_1.zodToJsonSchema)(this.zodSchema);

package/core/structure/ZodSchema.d.ts

@@ -3,9 +3,9 @@ import { Schema } from "./Schema.js";
 export declare class ZodSchema<STRUCTURE> implements Schema<STRUCTURE> {
     readonly zodSchema: z.Schema<STRUCTURE>;
     constructor(zodSchema: z.Schema<STRUCTURE>);
-    validate(value: unknown): {
+    validate(data: unknown): {
         success: true;
-        value: STRUCTURE;
+        data: STRUCTURE;
     } | {
         success: false;
         error: unknown;

package/core/structure/ZodSchema.js

@@ -15,11 +15,8 @@ export class ZodSchema {
         });
         this.zodSchema = zodSchema;
     }
-    validate(value) {
-        const parseResult = this.zodSchema.safeParse(value);
-        return parseResult.success
-            ? { success: true, value: parseResult.data }
-            : parseResult;
+    validate(data) {
+        return this.zodSchema.safeParse(data);
     }
     getJsonSchema() {
         return zodToJsonSchema(this.zodSchema);

package/event-source/readEventSource.cjs

@@ -1,20 +1,17 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readEventSource = void 0;
-const secure_json_parse_1 = __importDefault(require("secure-json-parse"));
+const parseJSON_js_1 = require("../util/parseJSON.cjs");
 function readEventSource({ url, schema, onEvent, onError = console.error, }) {
     const eventSource = new EventSource(url);
     eventSource.onmessage = (e) => {
         try {
-            const validationResult = schema.validate(secure_json_parse_1.default.parse(e.data));
-            if (!validationResult.success) {
-                onError(validationResult.error, eventSource);
+            const parseResult = (0, parseJSON_js_1.safeParseJsonWithSchema)(e.data, schema);
+            if (!parseResult.success) {
+                onError(parseResult.error, eventSource);
                 return;
             }
-            onEvent(validationResult.value, eventSource);
+            onEvent(parseResult.data, eventSource);
         }
         catch (error) {
             onError(error, eventSource);

package/event-source/readEventSource.d.ts

@@ -1,4 +1,4 @@
-import { Schema } from "../core/structure/Schema";
+import { Schema } from "../core/structure/Schema.js";
 export declare function readEventSource<T>({ url, schema, onEvent, onError, }: {
     url: string;
     schema: Schema<T>;

package/event-source/readEventSource.js

@@ -1,14 +1,14 @@
-import SecureJSON from "secure-json-parse";
+import { safeParseJsonWithSchema } from "../util/parseJSON.js";
 export function readEventSource({ url, schema, onEvent, onError = console.error, }) {
     const eventSource = new EventSource(url);
     eventSource.onmessage = (e) => {
         try {
-            const validationResult = schema.validate(SecureJSON.parse(e.data));
-            if (!validationResult.success) {
-                onError(validationResult.error, eventSource);
+            const parseResult = safeParseJsonWithSchema(e.data, schema);
+            if (!parseResult.success) {
+                onError(parseResult.error, eventSource);
                 return;
             }
-            onEvent(validationResult.value, eventSource);
+            onEvent(parseResult.data, eventSource);
         }
         catch (error) {
             onError(error, eventSource);

package/event-source/readEventSourceStream.cjs

@@ -1,10 +1,7 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readEventSourceStream = void 0;
-const secure_json_parse_1 = __importDefault(require("secure-json-parse"));
+const parseJSON_js_1 = require("../util/parseJSON.cjs");
 const AsyncQueue_js_1 = require("./AsyncQueue.cjs");
 const parseEventSourceStream_js_1 = require("./parseEventSourceStream.cjs");
 function readEventSourceStream({ stream, schema, errorHandler, }) {
@@ -14,12 +11,12 @@ function readEventSourceStream({ stream, schema, errorHandler, }) {
         .then(async (events) => {
         try {
             for await (const event of events) {
-                const validationResult = schema.validate(secure_json_parse_1.default.parse(event.data));
+                const validationResult = (0, parseJSON_js_1.safeParseJsonWithSchema)(event.data, schema);
                 if (!validationResult.success) {
                     errorHandler?.(validationResult.error);
                     continue;
                 }
-                queue.push(validationResult.value);
+                queue.push(validationResult.data);
             }
         }
         catch (error) {

package/event-source/readEventSourceStream.js

@@ -1,4 +1,4 @@
-import SecureJSON from "secure-json-parse";
+import { safeParseJsonWithSchema } from "../util/parseJSON.js";
 import { AsyncQueue } from "./AsyncQueue.js";
 import { parseEventSourceStream } from "./parseEventSourceStream.js";
 export function readEventSourceStream({ stream, schema, errorHandler, }) {
@@ -8,12 +8,12 @@ export function readEventSourceStream({ stream, schema, errorHandler, }) {
         .then(async (events) => {
         try {
             for await (const event of events) {
-                const validationResult = schema.validate(SecureJSON.parse(event.data));
+                const validationResult = safeParseJsonWithSchema(event.data, schema);
                 if (!validationResult.success) {
                     errorHandler?.(validationResult.error);
                     continue;
                 }
-                queue.push(validationResult.value);
+                queue.push(validationResult.data);
             }
         }
         catch (error) {

package/guard/fixStructure.cjs

@@ -3,6 +3,56 @@ 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");
+/**
+ * Attempts to correct and retry structure generation when encountering parsing or validation errors.
+ *
+ * This function acts as a guard within the structure generation process. If the generation results in
+ * an error, identified as either a `StructureParseError` or `StructureValidationError`, the function
+ * triggers a retry mechanism. It uses the `modifyInputForRetry` method, provided via options, to adjust
+ * the input parameters, aiming to resolve the issue that caused the initial error. The process continues
+ * until a valid structure is generated, or it exhausts the predefined retry limits.
+ *
+ * @template INPUT - The expected format/type of the input data used for structure generation.
+ * @template OUTPUT - The expected format/type of the output data, i.e., the successfully generated structure.
+ *
+ * @param {Object} options - Configuration options for modifying the input before retrying structure generation.
+ * @param {function} options.modifyInputForRetry - A function that takes the error type, original input, and error object.
+ *        It modifies the input data based on the error information, aiming to correct the issue for the retry attempt.
+ *        This function must return a promise that resolves with the modified input.
+ *
+ * @returns {Guard<INPUT, OUTPUT>} A guard function that intercepts the structure generation process, checking for
+ *          errors, and initiating retries by modifying the input parameters. The guard can trigger multiple retries
+ *          if the issues persist. If the process succeeds, it returns the valid structure; otherwise, it returns
+ *          undefined, indicating the exhaustion of retry attempts or a non-recoverable error.
+ *
+ * @example
+ * 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."),
+ *    ],
+ *  })
+ * );
+ */
 const fixStructure = ({ modifyInputForRetry }) => async (result) => {
     if (result.type === "error" &&
         (result.error instanceof StructureValidationError_js_1.StructureValidationError ||

package/guard/fixStructure.d.ts

@@ -1,6 +1,56 @@
 import { StructureParseError } from "../model-function/generate-structure/StructureParseError.js";
 import { StructureValidationError } from "../model-function/generate-structure/StructureValidationError.js";
 import { Guard } from "./guard.js";
+/**
+ * Attempts to correct and retry structure generation when encountering parsing or validation errors.
+ *
+ * This function acts as a guard within the structure generation process. If the generation results in
+ * an error, identified as either a `StructureParseError` or `StructureValidationError`, the function
+ * triggers a retry mechanism. It uses the `modifyInputForRetry` method, provided via options, to adjust
+ * the input parameters, aiming to resolve the issue that caused the initial error. The process continues
+ * until a valid structure is generated, or it exhausts the predefined retry limits.
+ *
+ * @template INPUT - The expected format/type of the input data used for structure generation.
+ * @template OUTPUT - The expected format/type of the output data, i.e., the successfully generated structure.
+ *
+ * @param {Object} options - Configuration options for modifying the input before retrying structure generation.
+ * @param {function} options.modifyInputForRetry - A function that takes the error type, original input, and error object.
+ *        It modifies the input data based on the error information, aiming to correct the issue for the retry attempt.
+ *        This function must return a promise that resolves with the modified input.
+ *
+ * @returns {Guard<INPUT, OUTPUT>} A guard function that intercepts the structure generation process, checking for
+ *          errors, and initiating retries by modifying the input parameters. The guard can trigger multiple retries
+ *          if the issues persist. If the process succeeds, it returns the valid structure; otherwise, it returns
+ *          undefined, indicating the exhaustion of retry attempts or a non-recoverable error.
+ *
+ * @example
+ * 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."),
+ *    ],
+ *  })
+ * );
+ */
 export declare const fixStructure: <INPUT, OUTPUT>(options: {
     modifyInputForRetry: (options: {
         type: "error";

package/guard/fixStructure.js

@@ -1,5 +1,55 @@
 import { StructureParseError } from "../model-function/generate-structure/StructureParseError.js";
 import { StructureValidationError } from "../model-function/generate-structure/StructureValidationError.js";
+/**
+ * Attempts to correct and retry structure generation when encountering parsing or validation errors.
+ *
+ * This function acts as a guard within the structure generation process. If the generation results in
+ * an error, identified as either a `StructureParseError` or `StructureValidationError`, the function
+ * triggers a retry mechanism. It uses the `modifyInputForRetry` method, provided via options, to adjust
+ * the input parameters, aiming to resolve the issue that caused the initial error. The process continues
+ * until a valid structure is generated, or it exhausts the predefined retry limits.
+ *
+ * @template INPUT - The expected format/type of the input data used for structure generation.
+ * @template OUTPUT - The expected format/type of the output data, i.e., the successfully generated structure.
+ *
+ * @param {Object} options - Configuration options for modifying the input before retrying structure generation.
+ * @param {function} options.modifyInputForRetry - A function that takes the error type, original input, and error object.
+ *        It modifies the input data based on the error information, aiming to correct the issue for the retry attempt.
+ *        This function must return a promise that resolves with the modified input.
+ *
+ * @returns {Guard<INPUT, OUTPUT>} A guard function that intercepts the structure generation process, checking for
+ *          errors, and initiating retries by modifying the input parameters. The guard can trigger multiple retries
+ *          if the issues persist. If the process succeeds, it returns the valid structure; otherwise, it returns
+ *          undefined, indicating the exhaustion of retry attempts or a non-recoverable error.
+ *
+ * @example
+ * 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."),
+ *    ],
+ *  })
+ * );
+ */
 export const fixStructure = ({ modifyInputForRetry }) => async (result) => {
     if (result.type === "error" &&
         (result.error instanceof StructureValidationError ||

package/guard/guard.d.ts

@@ -22,7 +22,7 @@ export type Guard<INPUT, OUTPUT> = ({ type, input, output, error, }: OutputResul
 } | {
     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?: {
+export declare function guard<INPUT, OUTPUT>(execute: (input: INPUT) => PromiseLike<OUTPUT>, input: INPUT, guards: Guard<INPUT, OUTPUT> | Array<Guard<INPUT, OUTPUT>>, options?: {
     maxRetries: number;
 }): Promise<OUTPUT | undefined>;
 export {};