modelfusion 0.53.1 → 0.53.2

package/core/FunctionOptions.d.ts

@@ -5,7 +5,7 @@ import { FunctionObserver } from "./FunctionObserver.js";
  */
 export type FunctionOptions = {
     /**
-     * Optional function identifier that is used in events to identify the function.
+     * Optional function identifier. Used in events and logging.
      */
     functionId?: string;
     /**
@@ -18,11 +18,12 @@ export type FunctionOptions = {
      */
     observers?: Array<FunctionObserver>;
     /**
-     * Optional run as part of which this function is called.
+     * Optional run as part of which this function is called. Used in events and logging.
+     * Run callbacks are invoked when it is provided.
      */
     run?: Run;
     /**
-     * Unique identifier of the call id of the parent function.
+     * Unique identifier of the call id of the parent function. Used in events and logging.
      */
     parentCallId?: string | undefined;
 };

package/model-function/embed/embed.cjs

@@ -6,6 +6,8 @@ const ModelFunctionPromise_js_1 = require("../ModelFunctionPromise.cjs");
 /**
  * Generate embeddings for multiple values.
  *
+ * @see https://modelfusion.dev/guide/function/embed
+ *
  * @example
  * const embeddings = await embedMany(
  *   new OpenAITextEmbeddingModel(...),
@@ -14,6 +16,12 @@ const ModelFunctionPromise_js_1 = require("../ModelFunctionPromise.cjs");
  *     "He keenly observed and absorbed everything around him, from the birds in the sky to the trees in the forest.",
  *   ]
  * );
+ *
+ * @param {EmbeddingModel<VALUE, EmbeddingModelSettings>} model - The model to use for generating embeddings.
+ * @param {VALUE[]} values - The values to generate embeddings for.
+ * @param {FunctionOptions} [options] - Optional settings for the function.
+ *
+ * @returns {ModelFunctionPromise<Vector[]>} - A promise that resolves to an array of vectors representing the embeddings.
  */
 function embedMany(model, values, options) {
     return new ModelFunctionPromise_js_1.ModelFunctionPromise((0, executeStandardCall_js_1.executeStandardCall)({
@@ -50,11 +58,19 @@ exports.embedMany = embedMany;
 /**
  * Generate an embedding for a single value.
  *
+ * @see https://modelfusion.dev/guide/function/embed
+ *
  * @example
  * const embedding = await embed(
  *   new OpenAITextEmbeddingModel(...),
  *   "At first, Nox didn't know what to do with the pup."
  * );
+ *
+ * @param {EmbeddingModel<VALUE, EmbeddingModelSettings>} model - The model to use for generating the embedding.
+ * @param {VALUE} value - The value to generate an embedding for.
+ * @param {FunctionOptions} [options] - Optional settings for the function.
+ *
+ * @returns {ModelFunctionPromise<Vector>} - A promise that resolves to a vector representing the embedding.
  */
 function embed(model, value, options) {
     return new ModelFunctionPromise_js_1.ModelFunctionPromise((0, executeStandardCall_js_1.executeStandardCall)({

package/model-function/embed/embed.d.ts

@@ -5,6 +5,8 @@ import { EmbeddingModel, EmbeddingModelSettings } from "./EmbeddingModel.js";
 /**
  * Generate embeddings for multiple values.
  *
+ * @see https://modelfusion.dev/guide/function/embed
+ *
  * @example
  * const embeddings = await embedMany(
  *   new OpenAITextEmbeddingModel(...),
@@ -13,15 +15,29 @@ import { EmbeddingModel, EmbeddingModelSettings } from "./EmbeddingModel.js";
  *     "He keenly observed and absorbed everything around him, from the birds in the sky to the trees in the forest.",
  *   ]
  * );
+ *
+ * @param {EmbeddingModel<VALUE, EmbeddingModelSettings>} model - The model to use for generating embeddings.
+ * @param {VALUE[]} values - The values to generate embeddings for.
+ * @param {FunctionOptions} [options] - Optional settings for the function.
+ *
+ * @returns {ModelFunctionPromise<Vector[]>} - A promise that resolves to an array of vectors representing the embeddings.
  */
 export declare function embedMany<VALUE>(model: EmbeddingModel<VALUE, EmbeddingModelSettings>, values: VALUE[], options?: FunctionOptions): ModelFunctionPromise<Vector[]>;
 /**
  * Generate an embedding for a single value.
  *
+ * @see https://modelfusion.dev/guide/function/embed
+ *
  * @example
  * const embedding = await embed(
  *   new OpenAITextEmbeddingModel(...),
  *   "At first, Nox didn't know what to do with the pup."
  * );
+ *
+ * @param {EmbeddingModel<VALUE, EmbeddingModelSettings>} model - The model to use for generating the embedding.
+ * @param {VALUE} value - The value to generate an embedding for.
+ * @param {FunctionOptions} [options] - Optional settings for the function.
+ *
+ * @returns {ModelFunctionPromise<Vector>} - A promise that resolves to a vector representing the embedding.
  */
 export declare function embed<VALUE>(model: EmbeddingModel<VALUE, EmbeddingModelSettings>, value: VALUE, options?: FunctionOptions): ModelFunctionPromise<Vector>;

package/model-function/embed/embed.js

@@ -3,6 +3,8 @@ import { ModelFunctionPromise } from "../ModelFunctionPromise.js";
 /**
  * Generate embeddings for multiple values.
  *
+ * @see https://modelfusion.dev/guide/function/embed
+ *
  * @example
  * const embeddings = await embedMany(
  *   new OpenAITextEmbeddingModel(...),
@@ -11,6 +13,12 @@ import { ModelFunctionPromise } from "../ModelFunctionPromise.js";
  *     "He keenly observed and absorbed everything around him, from the birds in the sky to the trees in the forest.",
  *   ]
  * );
+ *
+ * @param {EmbeddingModel<VALUE, EmbeddingModelSettings>} model - The model to use for generating embeddings.
+ * @param {VALUE[]} values - The values to generate embeddings for.
+ * @param {FunctionOptions} [options] - Optional settings for the function.
+ *
+ * @returns {ModelFunctionPromise<Vector[]>} - A promise that resolves to an array of vectors representing the embeddings.
  */
 export function embedMany(model, values, options) {
     return new ModelFunctionPromise(executeStandardCall({
@@ -46,11 +54,19 @@ export function embedMany(model, values, options) {
 /**
  * Generate an embedding for a single value.
  *
+ * @see https://modelfusion.dev/guide/function/embed
+ *
  * @example
  * const embedding = await embed(
  *   new OpenAITextEmbeddingModel(...),
  *   "At first, Nox didn't know what to do with the pup."
  * );
+ *
+ * @param {EmbeddingModel<VALUE, EmbeddingModelSettings>} model - The model to use for generating the embedding.
+ * @param {VALUE} value - The value to generate an embedding for.
+ * @param {FunctionOptions} [options] - Optional settings for the function.
+ *
+ * @returns {ModelFunctionPromise<Vector>} - A promise that resolves to a vector representing the embedding.
  */
 export function embed(model, value, options) {
     return new ModelFunctionPromise(executeStandardCall({

package/model-function/generate-image/generateImage.cjs

@@ -4,11 +4,13 @@ exports.generateImage = void 0;
 const executeStandardCall_js_1 = require("../executeStandardCall.cjs");
 const ImageGenerationPromise_js_1 = require("./ImageGenerationPromise.cjs");
 /**
- * Generates a base64-encoded image using a prompt.
- * The prompt format depends on the model.
- * For example, OpenAI image models expect a string prompt,
+ * Generates an image using a prompt.
+ *
+ * The prompt depends on the model. For example, OpenAI image models expect a string prompt,
  * and Stability AI models expect an array of text prompts with optional weights.
  *
+ * @see https://modelfusion.dev/guide/function/generate-image
+ *
  * @example
  * const image = await generateImage(
  *   new StabilityImageGenerationModel(...),
@@ -17,6 +19,13 @@ const ImageGenerationPromise_js_1 = require("./ImageGenerationPromise.cjs");
  *     { text: "style of early 19th century painting", weight: 0.5 },
  *   ]
  * );
+ *
+ * @param {ImageGenerationModel<PROMPT, ImageGenerationModelSettings>} model - The image generation model to be used.
+ * @param {PROMPT} prompt - The prompt to be used for image generation.
+ * @param {FunctionOptions} [options] - Optional settings for the function.
+ *
+ * @returns {ImageGenerationPromise} - Returns a promise that resolves to the generated image.
+ * The image is a Buffer containing the image data in PNG format.
  */
 function generateImage(model, prompt, options) {
     return new ImageGenerationPromise_js_1.ImageGenerationPromise((0, executeStandardCall_js_1.executeStandardCall)({

package/model-function/generate-image/generateImage.d.ts

@@ -2,11 +2,13 @@ import { FunctionOptions } from "../../core/FunctionOptions.js";
 import { ImageGenerationModel, ImageGenerationModelSettings } from "./ImageGenerationModel.js";
 import { ImageGenerationPromise } from "./ImageGenerationPromise.js";
 /**
- * Generates a base64-encoded image using a prompt.
- * The prompt format depends on the model.
- * For example, OpenAI image models expect a string prompt,
+ * Generates an image using a prompt.
+ *
+ * The prompt depends on the model. For example, OpenAI image models expect a string prompt,
  * and Stability AI models expect an array of text prompts with optional weights.
  *
+ * @see https://modelfusion.dev/guide/function/generate-image
+ *
  * @example
  * const image = await generateImage(
  *   new StabilityImageGenerationModel(...),
@@ -15,5 +17,12 @@ import { ImageGenerationPromise } from "./ImageGenerationPromise.js";
  *     { text: "style of early 19th century painting", weight: 0.5 },
  *   ]
  * );
+ *
+ * @param {ImageGenerationModel<PROMPT, ImageGenerationModelSettings>} model - The image generation model to be used.
+ * @param {PROMPT} prompt - The prompt to be used for image generation.
+ * @param {FunctionOptions} [options] - Optional settings for the function.
+ *
+ * @returns {ImageGenerationPromise} - Returns a promise that resolves to the generated image.
+ * The image is a Buffer containing the image data in PNG format.
  */
 export declare function generateImage<PROMPT>(model: ImageGenerationModel<PROMPT, ImageGenerationModelSettings>, prompt: PROMPT, options?: FunctionOptions): ImageGenerationPromise;

package/model-function/generate-image/generateImage.js

@@ -1,11 +1,13 @@
 import { executeStandardCall } from "../executeStandardCall.js";
 import { ImageGenerationPromise } from "./ImageGenerationPromise.js";
 /**
- * Generates a base64-encoded image using a prompt.
- * The prompt format depends on the model.
- * For example, OpenAI image models expect a string prompt,
+ * Generates an image using a prompt.
+ *
+ * The prompt depends on the model. For example, OpenAI image models expect a string prompt,
  * and Stability AI models expect an array of text prompts with optional weights.
  *
+ * @see https://modelfusion.dev/guide/function/generate-image
+ *
  * @example
  * const image = await generateImage(
  *   new StabilityImageGenerationModel(...),
@@ -14,6 +16,13 @@ import { ImageGenerationPromise } from "./ImageGenerationPromise.js";
  *     { text: "style of early 19th century painting", weight: 0.5 },
  *   ]
  * );
+ *
+ * @param {ImageGenerationModel<PROMPT, ImageGenerationModelSettings>} model - The image generation model to be used.
+ * @param {PROMPT} prompt - The prompt to be used for image generation.
+ * @param {FunctionOptions} [options] - Optional settings for the function.
+ *
+ * @returns {ImageGenerationPromise} - Returns a promise that resolves to the generated image.
+ * The image is a Buffer containing the image data in PNG format.
  */
 export function generateImage(model, prompt, options) {
     return new ImageGenerationPromise(executeStandardCall({

package/model-function/generate-speech/generateSpeech.cjs

@@ -4,7 +4,22 @@ exports.generateSpeech = void 0;
 const ModelFunctionPromise_js_1 = require("../ModelFunctionPromise.cjs");
 const executeStandardCall_js_1 = require("../executeStandardCall.cjs");
 /**
- * Synthesizes speech from text.
+ * Synthesizes speech from text. Also called text-to-speech (TTS).
+ *
+ * @see https://modelfusion.dev/guide/function/generate-speech
+ *
+ * @example
+ * const speech = await generateSpeech(
+ *   new LmntSpeechModel(...),
+ *   "Good evening, ladies and gentlemen! Exciting news on the airwaves tonight " +
+ *    "as The Rolling Stones unveil 'Hackney Diamonds.'
+ * );
+ *
+ * @param {SpeechGenerationModel<SpeechGenerationModelSettings>} model - The speech generation model.
+ * @param {string} text - The text to be converted to speech.
+ * @param {FunctionOptions} [options] - Optional function options.
+ *
+ * @returns {ModelFunctionPromise<Buffer>} - A promise that resolves to a buffer containing the synthesized speech.
  */
 function generateSpeech(model, text, options) {
     return new ModelFunctionPromise_js_1.ModelFunctionPromise((0, executeStandardCall_js_1.executeStandardCall)({

package/model-function/generate-speech/generateSpeech.d.ts

@@ -3,6 +3,21 @@ import { FunctionOptions } from "../../core/FunctionOptions.js";
 import { ModelFunctionPromise } from "../ModelFunctionPromise.js";
 import { SpeechGenerationModel, SpeechGenerationModelSettings } from "./SpeechGenerationModel.js";
 /**
- * Synthesizes speech from text.
+ * Synthesizes speech from text. Also called text-to-speech (TTS).
+ *
+ * @see https://modelfusion.dev/guide/function/generate-speech
+ *
+ * @example
+ * const speech = await generateSpeech(
+ *   new LmntSpeechModel(...),
+ *   "Good evening, ladies and gentlemen! Exciting news on the airwaves tonight " +
+ *    "as The Rolling Stones unveil 'Hackney Diamonds.'
+ * );
+ *
+ * @param {SpeechGenerationModel<SpeechGenerationModelSettings>} model - The speech generation model.
+ * @param {string} text - The text to be converted to speech.
+ * @param {FunctionOptions} [options] - Optional function options.
+ *
+ * @returns {ModelFunctionPromise<Buffer>} - A promise that resolves to a buffer containing the synthesized speech.
  */
 export declare function generateSpeech(model: SpeechGenerationModel<SpeechGenerationModelSettings>, text: string, options?: FunctionOptions): ModelFunctionPromise<Buffer>;

package/model-function/generate-speech/generateSpeech.js

@@ -1,7 +1,22 @@
 import { ModelFunctionPromise } from "../ModelFunctionPromise.js";
 import { executeStandardCall } from "../executeStandardCall.js";
 /**
- * Synthesizes speech from text.
+ * Synthesizes speech from text. Also called text-to-speech (TTS).
+ *
+ * @see https://modelfusion.dev/guide/function/generate-speech
+ *
+ * @example
+ * const speech = await generateSpeech(
+ *   new LmntSpeechModel(...),
+ *   "Good evening, ladies and gentlemen! Exciting news on the airwaves tonight " +
+ *    "as The Rolling Stones unveil 'Hackney Diamonds.'
+ * );
+ *
+ * @param {SpeechGenerationModel<SpeechGenerationModelSettings>} model - The speech generation model.
+ * @param {string} text - The text to be converted to speech.
+ * @param {FunctionOptions} [options] - Optional function options.
+ *
+ * @returns {ModelFunctionPromise<Buffer>} - A promise that resolves to a buffer containing the synthesized speech.
  */
 export function generateSpeech(model, text, options) {
     return new ModelFunctionPromise(executeStandardCall({

package/model-function/generate-speech/streamSpeech.cjs

@@ -5,7 +5,28 @@ const AsyncQueue_js_1 = require("../../util/AsyncQueue.cjs");
 const AsyncIterableResultPromise_js_1 = require("../AsyncIterableResultPromise.cjs");
 const executeStreamCall_js_1 = require("../executeStreamCall.cjs");
 /**
- * Synthesizes speech from text.
+ * Stream synthesized speech from text. Also called text-to-speech (TTS).
+ * Duplex streaming where both the input and output are streamed is supported.
+ *
+ * @see https://modelfusion.dev/guide/function/generate-speech
+ *
+ * @example
+ * const textStream = await streamText(...);
+ *
+ * const speechStream = await streamSpeech(
+ *   new ElevenLabsSpeechModel(...),
+ *   textStream
+ * );
+ *
+ * for await (const speechPart of speechStream) {
+ *   // ...
+ * }
+ *
+ * @param {StreamingSpeechGenerationModel<SpeechGenerationModelSettings>} model - The speech generation model.
+ * @param {AsyncIterable<string> | string} text - The text to be converted to speech. Can be a string or an async iterable of strings.
+ * @param {FunctionOptions} [options] - Optional function options.
+ *
+ * @returns {AsyncIterableResultPromise<Buffer>} An async iterable promise that contains the synthesized speech chunks.
  */
 function streamSpeech(model, text, options) {
     let textStream;

package/model-function/generate-speech/streamSpeech.d.ts

@@ -3,6 +3,27 @@ import { FunctionOptions } from "../../core/FunctionOptions.js";
 import { AsyncIterableResultPromise } from "../AsyncIterableResultPromise.js";
 import { StreamingSpeechGenerationModel, SpeechGenerationModelSettings } from "./SpeechGenerationModel.js";
 /**
- * Synthesizes speech from text.
+ * Stream synthesized speech from text. Also called text-to-speech (TTS).
+ * Duplex streaming where both the input and output are streamed is supported.
+ *
+ * @see https://modelfusion.dev/guide/function/generate-speech
+ *
+ * @example
+ * const textStream = await streamText(...);
+ *
+ * const speechStream = await streamSpeech(
+ *   new ElevenLabsSpeechModel(...),
+ *   textStream
+ * );
+ *
+ * for await (const speechPart of speechStream) {
+ *   // ...
+ * }
+ *
+ * @param {StreamingSpeechGenerationModel<SpeechGenerationModelSettings>} model - The speech generation model.
+ * @param {AsyncIterable<string> | string} text - The text to be converted to speech. Can be a string or an async iterable of strings.
+ * @param {FunctionOptions} [options] - Optional function options.
+ *
+ * @returns {AsyncIterableResultPromise<Buffer>} An async iterable promise that contains the synthesized speech chunks.
  */
 export declare function streamSpeech(model: StreamingSpeechGenerationModel<SpeechGenerationModelSettings>, text: AsyncIterable<string> | string, options?: FunctionOptions): AsyncIterableResultPromise<Buffer>;

package/model-function/generate-speech/streamSpeech.js

@@ -2,7 +2,28 @@ import { AsyncQueue } from "../../util/AsyncQueue.js";
 import { AsyncIterableResultPromise } from "../AsyncIterableResultPromise.js";
 import { executeStreamCall } from "../executeStreamCall.js";
 /**
- * Synthesizes speech from text.
+ * Stream synthesized speech from text. Also called text-to-speech (TTS).
+ * Duplex streaming where both the input and output are streamed is supported.
+ *
+ * @see https://modelfusion.dev/guide/function/generate-speech
+ *
+ * @example
+ * const textStream = await streamText(...);
+ *
+ * const speechStream = await streamSpeech(
+ *   new ElevenLabsSpeechModel(...),
+ *   textStream
+ * );
+ *
+ * for await (const speechPart of speechStream) {
+ *   // ...
+ * }
+ *
+ * @param {StreamingSpeechGenerationModel<SpeechGenerationModelSettings>} model - The speech generation model.
+ * @param {AsyncIterable<string> | string} text - The text to be converted to speech. Can be a string or an async iterable of strings.
+ * @param {FunctionOptions} [options] - Optional function options.
+ *
+ * @returns {AsyncIterableResultPromise<Buffer>} An async iterable promise that contains the synthesized speech chunks.
  */
 export function streamSpeech(model, text, options) {
     let textStream;

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

@@ -4,6 +4,47 @@ exports.generateStructure = void 0;
 const executeStandardCall_js_1 = require("../executeStandardCall.cjs");
 const ModelFunctionPromise_js_1 = require("../ModelFunctionPromise.cjs");
 const StructureValidationError_js_1 = require("./StructureValidationError.cjs");
+/**
+ * Generate a typed object for a prompt and a structure definition.
+ * The structure definition is used as part of the final prompt.
+ *
+ * For the OpenAI chat model, this generates and parses a function call with a single function.
+ *
+ * @see https://modelfusion.dev/guide/function/generate-structure
+ *
+ * @example
+ * const sentiment = await generateStructure(
+ *   new OpenAIChatModel(...),
+ *   new ZodStructureDefinition({
+ *     name: "sentiment",
+ *     description: "Write the sentiment analysis",
+ *     schema: z.object({
+ *       sentiment: z
+ *         .enum(["positive", "neutral", "negative"])
+ *         .describe("Sentiment."),
+ *     }),
+ *   }),
+ *   [
+ *     OpenAIChatMessage.system(
+ *       "You are a sentiment evaluator. " +
+ *         "Analyze the sentiment of the following product review:"
+ *     ),
+ *     OpenAIChatMessage.user(
+ *       "After I opened the package, I was met by a very unpleasant smell " +
+ *         "that did not disappear even after washing. Never again!"
+ *     ),
+ *   ]
+ * );
+ *
+ * @param {StructureGenerationModel<PROMPT, SETTINGS>} model - The model to generate the structure.
+ * @param {StructureDefinition<NAME, STRUCTURE>} structureDefinition - The structure definition to be used.
+ * @param {PROMPT | ((structureDefinition: StructureDefinition<NAME, STRUCTURE>) => PROMPT)} prompt
+ * The prompt to be used.
+ * You can also pass a function that takes the structure definition as an argument and returns the prompt.
+ * @param {FunctionOptions} [options] - Optional function options.
+ *
+ * @returns {ModelFunctionPromise<STRUCTURE>} - Returns a promise that resolves to the generated structure.
+ */
 function generateStructure(model, structureDefinition, prompt, options) {
     // Note: PROMPT must not be a function.
     const expandedPrompt = typeof prompt === "function"

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

@@ -2,4 +2,45 @@ import { FunctionOptions } from "../../core/FunctionOptions.js";
 import { StructureDefinition } from "../../core/structure/StructureDefinition.js";
 import { ModelFunctionPromise } from "../ModelFunctionPromise.js";
 import { StructureGenerationModel, StructureGenerationModelSettings } from "./StructureGenerationModel.js";
+/**
+ * Generate a typed object for a prompt and a structure definition.
+ * The structure definition is used as part of the final prompt.
+ *
+ * For the OpenAI chat model, this generates and parses a function call with a single function.
+ *
+ * @see https://modelfusion.dev/guide/function/generate-structure
+ *
+ * @example
+ * const sentiment = await generateStructure(
+ *   new OpenAIChatModel(...),
+ *   new ZodStructureDefinition({
+ *     name: "sentiment",
+ *     description: "Write the sentiment analysis",
+ *     schema: z.object({
+ *       sentiment: z
+ *         .enum(["positive", "neutral", "negative"])
+ *         .describe("Sentiment."),
+ *     }),
+ *   }),
+ *   [
+ *     OpenAIChatMessage.system(
+ *       "You are a sentiment evaluator. " +
+ *         "Analyze the sentiment of the following product review:"
+ *     ),
+ *     OpenAIChatMessage.user(
+ *       "After I opened the package, I was met by a very unpleasant smell " +
+ *         "that did not disappear even after washing. Never again!"
+ *     ),
+ *   ]
+ * );
+ *
+ * @param {StructureGenerationModel<PROMPT, SETTINGS>} model - The model to generate the structure.
+ * @param {StructureDefinition<NAME, STRUCTURE>} structureDefinition - The structure definition to be used.
+ * @param {PROMPT | ((structureDefinition: StructureDefinition<NAME, STRUCTURE>) => PROMPT)} prompt
+ * The prompt to be used.
+ * You can also pass a function that takes the structure definition as an argument and returns the prompt.
+ * @param {FunctionOptions} [options] - Optional function options.
+ *
+ * @returns {ModelFunctionPromise<STRUCTURE>} - Returns a promise that resolves to the generated structure.
+ */
 export declare function generateStructure<STRUCTURE, PROMPT, NAME extends string, SETTINGS extends StructureGenerationModelSettings>(model: StructureGenerationModel<PROMPT, SETTINGS>, structureDefinition: StructureDefinition<NAME, STRUCTURE>, prompt: PROMPT | ((structureDefinition: StructureDefinition<NAME, STRUCTURE>) => PROMPT), options?: FunctionOptions): ModelFunctionPromise<STRUCTURE>;

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

@@ -1,6 +1,47 @@
 import { executeStandardCall } from "../executeStandardCall.js";
 import { ModelFunctionPromise } from "../ModelFunctionPromise.js";
 import { StructureValidationError } from "./StructureValidationError.js";
+/**
+ * Generate a typed object for a prompt and a structure definition.
+ * The structure definition is used as part of the final prompt.
+ *
+ * For the OpenAI chat model, this generates and parses a function call with a single function.
+ *
+ * @see https://modelfusion.dev/guide/function/generate-structure
+ *
+ * @example
+ * const sentiment = await generateStructure(
+ *   new OpenAIChatModel(...),
+ *   new ZodStructureDefinition({
+ *     name: "sentiment",
+ *     description: "Write the sentiment analysis",
+ *     schema: z.object({
+ *       sentiment: z
+ *         .enum(["positive", "neutral", "negative"])
+ *         .describe("Sentiment."),
+ *     }),
+ *   }),
+ *   [
+ *     OpenAIChatMessage.system(
+ *       "You are a sentiment evaluator. " +
+ *         "Analyze the sentiment of the following product review:"
+ *     ),
+ *     OpenAIChatMessage.user(
+ *       "After I opened the package, I was met by a very unpleasant smell " +
+ *         "that did not disappear even after washing. Never again!"
+ *     ),
+ *   ]
+ * );
+ *
+ * @param {StructureGenerationModel<PROMPT, SETTINGS>} model - The model to generate the structure.
+ * @param {StructureDefinition<NAME, STRUCTURE>} structureDefinition - The structure definition to be used.
+ * @param {PROMPT | ((structureDefinition: StructureDefinition<NAME, STRUCTURE>) => PROMPT)} prompt
+ * The prompt to be used.
+ * You can also pass a function that takes the structure definition as an argument and returns the prompt.
+ * @param {FunctionOptions} [options] - Optional function options.
+ *
+ * @returns {ModelFunctionPromise<STRUCTURE>} - Returns a promise that resolves to the generated structure.
+ */
 export function generateStructure(model, structureDefinition, prompt, options) {
     // Note: PROMPT must not be a function.
     const expandedPrompt = typeof prompt === "function"

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

@@ -5,6 +5,68 @@ const executeStandardCall_js_1 = require("../executeStandardCall.cjs");
 const ModelFunctionPromise_js_1 = require("../ModelFunctionPromise.cjs");
 const NoSuchStructureError_js_1 = require("./NoSuchStructureError.cjs");
 const StructureValidationError_js_1 = require("./StructureValidationError.cjs");
+/**
+ * Generates a typed object or plain text based on the given prompt and structure definitions.
+ * The structure definition is used as part of the final prompt.
+ *
+ * This function interacts with a specified model to either return a structured object conforming to one of the provided
+ * structure definitions or a plain text response if the model decides not to return a structured object.
+ *
+ * For the OpenAI chat model, this generates and parses a function call with automatic function selection.
+ *
+ * @see https://modelfusion.dev/guide/function/generate-structure-or-text
+ *
+ * @example
+ * const { structure, value, text } = await generateStructureOrText(
+ *   new OpenAIChatModel(...),
+ *   [
+ *     new ZodStructureDefinition({
+ *       name: "getCurrentWeather" as const, // mark 'as const' for type inference
+ *       description: "Get the current weather in a given location",
+ *       schema: z.object({
+ *         location: z
+ *           .string()
+ *           .describe("The city and state, e.g. San Francisco, CA"),
+ *         unit: z.enum(["celsius", "fahrenheit"]).optional(),
+ *       }),
+ *     }),
+ *     new ZodStructureDefinition({
+ *       name: "getContactInformation" as const,
+ *       description: "Get the contact information for a given person",
+ *       schema: z.object({
+ *         name: z.string().describe("The name of the person"),
+ *       }),
+ *     }),
+ *   ],
+ *   [OpenAIChatMessage.user(query)]
+ * );
+ *
+ * switch (structure) {
+ *   case "getCurrentWeather": {
+ *     const { location, unit } = value;
+ *     console.log("getCurrentWeather", location, unit);
+ *     break;
+ *   }
+ *
+ *   case "getContactInformation": {
+ *     const { name } = value;
+ *     console.log("getContactInformation", name);
+ *     break;
+ *   }
+ *
+ *   case null: {
+ *     console.log("No function call. Generated text: ", text);
+ *   }
+ * }
+ *
+ * @param {StructureOrTextGenerationModel<PROMPT, SETTINGS>} model - The model responsible for generating structured data or text.
+ * @param {STRUCTURES} structureDefinitions - An array of StructureDefinition instances defining the possible structures of the expected response.
+ * @param {PROMPT | ((structureDefinitions: STRUCTURES) => PROMPT)} prompt - The prompt used to generate the structure or text.
+ * You can also pass a function that takes the array of structure definitions as an argument and returns the prompt.
+ * @param {FunctionOptions} [options] - Additional options to control the function's execution behavior.
+ *
+ * @returns {ModelFunctionPromise<{ structure: null; value: null; text: string } | ToOutputValue<STRUCTURES>>} - Returns a promise that resolves to an object containing either a structured response conforming to one of the provided definitions or a plain text response.
+ */
 function generateStructureOrText(model, structureDefinitions, prompt, options) {
     // Note: PROMPT must not be a function.
     const expandedPrompt = typeof prompt === "function"