modelfusion 0.53.0 → 0.53.2

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"

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

@@ -14,6 +14,68 @@ type ToStructureUnion<T> = {
     } : never;
 }[keyof T];
 type ToOutputValue<STRUCTURES extends StructureDefinitionArray<StructureDefinition<any, any>[]>> = ToStructureUnion<ToStructureDefinitionMap<STRUCTURES>>;
+/**
+ * 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.
+ */
 export declare function generateStructureOrText<STRUCTURES extends StructureDefinition<any, any>[], PROMPT>(model: StructureOrTextGenerationModel<PROMPT, StructureOrTextGenerationModelSettings>, structureDefinitions: STRUCTURES, prompt: PROMPT | ((structureDefinitions: STRUCTURES) => PROMPT), options?: FunctionOptions): ModelFunctionPromise<{
     structure: null;
     value: null;

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

@@ -2,6 +2,68 @@ import { executeStandardCall } from "../executeStandardCall.js";
 import { ModelFunctionPromise } from "../ModelFunctionPromise.js";
 import { NoSuchStructureError } from "./NoSuchStructureError.js";
 import { StructureValidationError } from "./StructureValidationError.js";
+/**
+ * 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.
+ */
 export function generateStructureOrText(model, structureDefinitions, prompt, options) {
     // Note: PROMPT must not be a function.
     const expandedPrompt = typeof prompt === "function"

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

@@ -4,7 +4,78 @@ exports.streamStructure = void 0;
 const isDeepEqualData_js_1 = require("../../util/isDeepEqualData.cjs");
 const AsyncIterableResultPromise_js_1 = require("../AsyncIterableResultPromise.cjs");
 const executeStreamCall_js_1 = require("../executeStreamCall.cjs");
+/**
+ * Generate and stream an object for a prompt and a structure definition.
+ *
+ * The final object is typed according to the structure definition.
+ * The partial objects are of unknown type,
+ * but are supposed to be partial version of the final object
+ * (unless the underlying model returns invalid data).
+ *
+ * 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 structureStream = await streamStructure(
+ *    new OpenAIChatModel({
+ *      model: "gpt-3.5-turbo",
+ *     temperature: 0,
+ *     maxCompletionTokens: 2000,
+ *   }),
+ *   new ZodStructureDefinition({
+ *     name: "generateCharacter",
+ *     description: "Generate character descriptions.",
+ *     schema: z.object({
+ *       characters: z.array(
+ *         z.object({
+ *           name: z.string(),
+ *           class: z
+ *             .string()
+ *             .describe("Character class, e.g. warrior, mage, or thief."),
+ *           description: z.string(),
+ *         })
+ *       ),
+ *     }),
+ *   }),
+ *   [
+ *     OpenAIChatMessage.user(
+ *       "Generate 3 character descriptions for a fantasy role playing game."
+ *     ),
+ *   ]
+ * );
+ *
+ * for await (const part of structureStream) {
+ *   if (!part.isComplete) {
+ *     const unknownPartialStructure = part.value;
+ *     // use your own logic to handle partial structures, e.g. with Zod .deepPartial()
+ *     // it depends on your application at which points you want to act on the partial structures
+ *   } else {
+ *     const fullyTypedStructure = part.value;
+ *     // ...
+ *   }
+ * }
+ *
+ * @param {StructureStreamingModel<PROMPT>} model - The model to use for streaming
+ * @param {StructureDefinition<NAME, STRUCTURE>} structureDefinition - The structure definition to use
+ * @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 {AsyncIterableResultPromise<StructureStreamPart<STRUCTURE>>}
+ * The async iterable result promise.
+ * Each part of the stream is either a partial structure or the final structure.
+ * It contains a isComplete flag to indicate whether the structure is complete,
+ * and a value that is either the partial structure or the final structure.
+ */
 function streamStructure(model, structureDefinition, prompt, options) {
+    // Note: PROMPT must not be a function.
+    const expandedPrompt = typeof prompt === "function"
+        ? prompt(structureDefinition)
+        : prompt;
     let lastStructure;
     let lastFullDelta;
     return new AsyncIterableResultPromise_js_1.AsyncIterableResultPromise((0, executeStreamCall_js_1.executeStreamCall)({
@@ -12,7 +83,7 @@ function streamStructure(model, structureDefinition, prompt, options) {
         input: prompt,
         model,
         options,
-        startStream: async (options) => model.doStreamStructure(structureDefinition, prompt, options),
+        startStream: async (options) => model.doStreamStructure(structureDefinition, expandedPrompt, options),
         processDelta: (delta) => {
             const latestFullDelta = delta.fullDelta;
             const latestStructure = delta.valueDelta;

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

@@ -9,4 +9,71 @@ export type StructureStreamPart<STRUCTURE> = {
     isComplete: true;
     value: STRUCTURE;
 };
-export declare function streamStructure<STRUCTURE, PROMPT, NAME extends string>(model: StructureStreamingModel<PROMPT>, structureDefinition: StructureDefinition<NAME, STRUCTURE>, prompt: PROMPT, options?: FunctionOptions): AsyncIterableResultPromise<StructureStreamPart<STRUCTURE>>;
+/**
+ * Generate and stream an object for a prompt and a structure definition.
+ *
+ * The final object is typed according to the structure definition.
+ * The partial objects are of unknown type,
+ * but are supposed to be partial version of the final object
+ * (unless the underlying model returns invalid data).
+ *
+ * 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 structureStream = await streamStructure(
+ *    new OpenAIChatModel({
+ *      model: "gpt-3.5-turbo",
+ *     temperature: 0,
+ *     maxCompletionTokens: 2000,
+ *   }),
+ *   new ZodStructureDefinition({
+ *     name: "generateCharacter",
+ *     description: "Generate character descriptions.",
+ *     schema: z.object({
+ *       characters: z.array(
+ *         z.object({
+ *           name: z.string(),
+ *           class: z
+ *             .string()
+ *             .describe("Character class, e.g. warrior, mage, or thief."),
+ *           description: z.string(),
+ *         })
+ *       ),
+ *     }),
+ *   }),
+ *   [
+ *     OpenAIChatMessage.user(
+ *       "Generate 3 character descriptions for a fantasy role playing game."
+ *     ),
+ *   ]
+ * );
+ *
+ * for await (const part of structureStream) {
+ *   if (!part.isComplete) {
+ *     const unknownPartialStructure = part.value;
+ *     // use your own logic to handle partial structures, e.g. with Zod .deepPartial()
+ *     // it depends on your application at which points you want to act on the partial structures
+ *   } else {
+ *     const fullyTypedStructure = part.value;
+ *     // ...
+ *   }
+ * }
+ *
+ * @param {StructureStreamingModel<PROMPT>} model - The model to use for streaming
+ * @param {StructureDefinition<NAME, STRUCTURE>} structureDefinition - The structure definition to use
+ * @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 {AsyncIterableResultPromise<StructureStreamPart<STRUCTURE>>}
+ * The async iterable result promise.
+ * Each part of the stream is either a partial structure or the final structure.
+ * It contains a isComplete flag to indicate whether the structure is complete,
+ * and a value that is either the partial structure or the final structure.
+ */
+export declare function streamStructure<STRUCTURE, PROMPT, NAME extends string>(model: StructureStreamingModel<PROMPT>, structureDefinition: StructureDefinition<NAME, STRUCTURE>, prompt: PROMPT | ((structureDefinition: StructureDefinition<NAME, STRUCTURE>) => PROMPT), options?: FunctionOptions): AsyncIterableResultPromise<StructureStreamPart<STRUCTURE>>;

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

@@ -1,7 +1,78 @@
 import { isDeepEqualData } from "../../util/isDeepEqualData.js";
 import { AsyncIterableResultPromise } from "../AsyncIterableResultPromise.js";
 import { executeStreamCall } from "../executeStreamCall.js";
+/**
+ * Generate and stream an object for a prompt and a structure definition.
+ *
+ * The final object is typed according to the structure definition.
+ * The partial objects are of unknown type,
+ * but are supposed to be partial version of the final object
+ * (unless the underlying model returns invalid data).
+ *
+ * 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 structureStream = await streamStructure(
+ *    new OpenAIChatModel({
+ *      model: "gpt-3.5-turbo",
+ *     temperature: 0,
+ *     maxCompletionTokens: 2000,
+ *   }),
+ *   new ZodStructureDefinition({
+ *     name: "generateCharacter",
+ *     description: "Generate character descriptions.",
+ *     schema: z.object({
+ *       characters: z.array(
+ *         z.object({
+ *           name: z.string(),
+ *           class: z
+ *             .string()
+ *             .describe("Character class, e.g. warrior, mage, or thief."),
+ *           description: z.string(),
+ *         })
+ *       ),
+ *     }),
+ *   }),
+ *   [
+ *     OpenAIChatMessage.user(
+ *       "Generate 3 character descriptions for a fantasy role playing game."
+ *     ),
+ *   ]
+ * );
+ *
+ * for await (const part of structureStream) {
+ *   if (!part.isComplete) {
+ *     const unknownPartialStructure = part.value;
+ *     // use your own logic to handle partial structures, e.g. with Zod .deepPartial()
+ *     // it depends on your application at which points you want to act on the partial structures
+ *   } else {
+ *     const fullyTypedStructure = part.value;
+ *     // ...
+ *   }
+ * }
+ *
+ * @param {StructureStreamingModel<PROMPT>} model - The model to use for streaming
+ * @param {StructureDefinition<NAME, STRUCTURE>} structureDefinition - The structure definition to use
+ * @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 {AsyncIterableResultPromise<StructureStreamPart<STRUCTURE>>}
+ * The async iterable result promise.
+ * Each part of the stream is either a partial structure or the final structure.
+ * It contains a isComplete flag to indicate whether the structure is complete,
+ * and a value that is either the partial structure or the final structure.
+ */
 export function streamStructure(model, structureDefinition, prompt, options) {
+    // Note: PROMPT must not be a function.
+    const expandedPrompt = typeof prompt === "function"
+        ? prompt(structureDefinition)
+        : prompt;
     let lastStructure;
     let lastFullDelta;
     return new AsyncIterableResultPromise(executeStreamCall({
@@ -9,7 +80,7 @@ export function streamStructure(model, structureDefinition, prompt, options) {
         input: prompt,
         model,
         options,
-        startStream: async (options) => model.doStreamStructure(structureDefinition, prompt, options),
+        startStream: async (options) => model.doStreamStructure(structureDefinition, expandedPrompt, options),
         processDelta: (delta) => {
             const latestFullDelta = delta.fullDelta;
             const latestStructure = delta.valueDelta;

package/model-function/generate-text/generateText.cjs

@@ -4,17 +4,25 @@ exports.generateText = void 0;
 const executeStandardCall_js_1 = require("../executeStandardCall.cjs");
 const ModelFunctionPromise_js_1 = require("../ModelFunctionPromise.cjs");
 /**
- * Generates a text using a prompt.
- * The prompt format depends on the model.
- * For example, OpenAI text models expect a string prompt, and OpenAI chat models expect an array of chat messages.
+ * Generate text for a prompt and return it as a string.
  *
- * @example
- * const model = new OpenAICompletionModel(...);
+ * The prompt depends on the model used.
+ * For instance, OpenAI completion models expect a string prompt,
+ * whereas OpenAI chat models expect an array of chat messages.
+ *
+ * @see https://modelfusion.dev/guide/function/generate-text
  *
+ * @example
  * const text = await generateText(
- *   model,
+ *   new OpenAICompletionModel(...),
  *   "Write a short story about a robot learning to love:\n\n"
  * );
+ *
+ * @param {TextGenerationModel<PROMPT, TextGenerationModelSettings>} model - The text generation model to use.
+ * @param {PROMPT} prompt - The prompt to use for text generation.
+ * @param {FunctionOptions} [options] - Optional parameters for the function.
+ *
+ * @returns {ModelFunctionPromise<string>} - A promise that resolves to the generated text.
  */
 function generateText(model, prompt, options) {
     return new ModelFunctionPromise_js_1.ModelFunctionPromise((0, executeStandardCall_js_1.executeStandardCall)({

package/model-function/generate-text/generateText.d.ts

@@ -2,16 +2,24 @@ import { FunctionOptions } from "../../core/FunctionOptions.js";
 import { ModelFunctionPromise } from "../ModelFunctionPromise.js";
 import { TextGenerationModel, TextGenerationModelSettings } from "./TextGenerationModel.js";
 /**
- * Generates a text using a prompt.
- * The prompt format depends on the model.
- * For example, OpenAI text models expect a string prompt, and OpenAI chat models expect an array of chat messages.
+ * Generate text for a prompt and return it as a string.
  *
- * @example
- * const model = new OpenAICompletionModel(...);
+ * The prompt depends on the model used.
+ * For instance, OpenAI completion models expect a string prompt,
+ * whereas OpenAI chat models expect an array of chat messages.
+ *
+ * @see https://modelfusion.dev/guide/function/generate-text
  *
+ * @example
  * const text = await generateText(
- *   model,
+ *   new OpenAICompletionModel(...),
  *   "Write a short story about a robot learning to love:\n\n"
  * );
+ *
+ * @param {TextGenerationModel<PROMPT, TextGenerationModelSettings>} model - The text generation model to use.
+ * @param {PROMPT} prompt - The prompt to use for text generation.
+ * @param {FunctionOptions} [options] - Optional parameters for the function.
+ *
+ * @returns {ModelFunctionPromise<string>} - A promise that resolves to the generated text.
  */
 export declare function generateText<PROMPT>(model: TextGenerationModel<PROMPT, TextGenerationModelSettings>, prompt: PROMPT, options?: FunctionOptions): ModelFunctionPromise<string>;