modelfusion 0.71.0 → 0.73.0

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

@@ -1,97 +0,0 @@
-import { FunctionOptions } from "../../core/FunctionOptions.js";
-import { StructureDefinition } from "../../core/schema/StructureDefinition.js";
-import { ModelCallMetadata } from "../ModelCallMetadata.js";
-import { StructureOrTextGenerationModel, StructureOrTextGenerationModelSettings } from "./StructureOrTextGenerationModel.js";
-type StructureDefinitionArray<T extends StructureDefinition<any, any>[]> = T;
-type ToStructureDefinitionMap<T extends StructureDefinitionArray<StructureDefinition<any, any>[]>> = {
-    [K in T[number]["name"]]: Extract<T[number], StructureDefinition<K, any>>;
-};
-type ToStructureUnion<T> = {
-    [KEY in keyof T]: T[KEY] extends StructureDefinition<any, infer STRUCTURE> ? {
-        structure: KEY;
-        value: STRUCTURE;
-        text: string | null;
-    } : 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 {Promise<{ 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 & {
-    returnType?: "structure";
-}): Promise<{
-    structure: null;
-    value: null;
-    text: string;
-} | ToOutputValue<STRUCTURES>>;
-export declare function generateStructureOrText<STRUCTURES extends StructureDefinition<any, any>[], PROMPT>(model: StructureOrTextGenerationModel<PROMPT, StructureOrTextGenerationModelSettings>, structureDefinitions: STRUCTURES, prompt: PROMPT | ((structureDefinitions: STRUCTURES) => PROMPT), options: FunctionOptions & {
-    returnType?: "full";
-}): Promise<{
-    value: {
-        structure: null;
-        value: null;
-        text: string;
-    } | ToOutputValue<STRUCTURES>;
-    response: unknown;
-    metadata: ModelCallMetadata;
-}>;
-export {};

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

@@ -1,50 +0,0 @@
-import { executeStandardCall } from "../executeStandardCall.js";
-import { NoSuchStructureError } from "./NoSuchStructureError.js";
-import { StructureValidationError } from "./StructureValidationError.js";
-export async function generateStructureOrText(model, structureDefinitions, prompt, options) {
-    // Note: PROMPT must not be a function.
-    const expandedPrompt = typeof prompt === "function"
-        ? prompt(structureDefinitions)
-        : prompt;
-    const fullResponse = await executeStandardCall({
-        functionType: "generate-structure-or-text",
-        input: expandedPrompt,
-        model,
-        options,
-        generateResponse: async (options) => {
-            const result = await model.doGenerateStructureOrText(structureDefinitions, expandedPrompt, options);
-            const { structure, value, text } = result.structureAndText;
-            // text generation:
-            if (structure == null) {
-                return {
-                    response: result.response,
-                    extractedValue: { structure, value, text },
-                    usage: result.usage,
-                };
-            }
-            const definition = structureDefinitions.find((d) => d.name === structure);
-            if (definition == undefined) {
-                throw new NoSuchStructureError(structure);
-            }
-            const parseResult = definition.schema.validate(value);
-            if (!parseResult.success) {
-                throw new StructureValidationError({
-                    structureName: structure,
-                    value,
-                    valueText: result.structureAndText.valueText,
-                    cause: parseResult.error,
-                });
-            }
-            return {
-                response: result.response,
-                extractedValue: {
-                    structure: structure,
-                    value: parseResult.data,
-                    text: text, // text is string | null, which is part of the response for schema values
-                },
-                usage: result.usage,
-            };
-        },
-    });
-    return options?.returnType === "full" ? fullResponse : fullResponse.value;
-}

package/model-function/generate-tool-call/ToolCall.d.ts

@@ -1,5 +0,0 @@
-export interface ToolCall<NAME extends string, PARAMETERS> {
-    id: string;
-    name: NAME;
-    parameters: PARAMETERS;
-}

package/model-function/generate-tool-call/index.d.ts

@@ -1,10 +0,0 @@
-export * from "./ToolCall.js";
-export * from "./ToolCallGenerationError.js";
-export * from "./ToolCallGenerationEvent.js";
-export * from "./ToolCallGenerationModel.js";
-export * from "./ToolCallParametersValidationError.js";
-export * from "./ToolCallsOrTextGenerationEvent.js";
-export * from "./ToolCallsOrTextGenerationModel.js";
-export * from "./ToolDefinition.js";
-export * from "./generateToolCall.js";
-export * from "./generateToolCallsOrText.js";

package/model-function/generate-tool-call/index.js

@@ -1,10 +0,0 @@
-export * from "./ToolCall.js";
-export * from "./ToolCallGenerationError.js";
-export * from "./ToolCallGenerationEvent.js";
-export * from "./ToolCallGenerationModel.js";
-export * from "./ToolCallParametersValidationError.js";
-export * from "./ToolCallsOrTextGenerationEvent.js";
-export * from "./ToolCallsOrTextGenerationModel.js";
-export * from "./ToolDefinition.js";
-export * from "./generateToolCall.js";
-export * from "./generateToolCallsOrText.js";

package/tool/NoSuchToolError.cjs

@@ -1,25 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.NoSuchToolError = void 0;
-class NoSuchToolError extends Error {
-    constructor(toolName) {
-        super(`No such tool: ${toolName}`);
-        Object.defineProperty(this, "toolName", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        this.name = "NoSuchToolError";
-        this.toolName = toolName;
-    }
-    toJSON() {
-        return {
-            name: this.name,
-            toolName: this.toolName,
-            message: this.message,
-            stack: this.stack,
-        };
-    }
-}
-exports.NoSuchToolError = NoSuchToolError;

package/tool/NoSuchToolError.d.ts

@@ -1,10 +0,0 @@
-export declare class NoSuchToolError extends Error {
-    readonly toolName: string;
-    constructor(toolName: string);
-    toJSON(): {
-        name: string;
-        toolName: string;
-        message: string;
-        stack: string | undefined;
-    };
-}

package/tool/NoSuchToolError.js

@@ -1,21 +0,0 @@
-export class NoSuchToolError extends Error {
-    constructor(toolName) {
-        super(`No such tool: ${toolName}`);
-        Object.defineProperty(this, "toolName", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        this.name = "NoSuchToolError";
-        this.toolName = toolName;
-    }
-    toJSON() {
-        return {
-            name: this.name,
-            toolName: this.toolName,
-            message: this.message,
-            stack: this.stack,
-        };
-    }
-}

package/tool/UseToolOrGenerateTextEvent.d.ts

@@ -1,7 +0,0 @@
-import { BaseFunctionFinishedEvent, BaseFunctionStartedEvent } from "../core/FunctionEvent.js";
-export interface UseToolOrGenerateTextStartedEvent extends BaseFunctionStartedEvent {
-    functionType: "use-tool-or-generate-text";
-}
-export interface UseToolOrGenerateTextFinishedEvent extends BaseFunctionFinishedEvent {
-    functionType: "use-tool-or-generate-text";
-}

package/tool/useTool.cjs

@@ -1,40 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.useTool = void 0;
-const executeFunctionCall_js_1 = require("../core/executeFunctionCall.cjs");
-const generateStructure_js_1 = require("../model-function/generate-structure/generateStructure.cjs");
-const executeTool_js_1 = require("./executeTool.cjs");
-/**
- * `useTool` uses `generateStructure` to generate parameters for a tool and then executes the tool with the parameters.
- *
- * @returns The result contains the name of the tool (`tool` property),
- * the parameters (`parameters` property, typed),
- * and the result of the tool execution (`result` property, typed).
- */
-async function useTool(model, tool, prompt, options) {
-    // Note: PROMPT must not be a function.
-    const expandedPrompt = typeof prompt === "function"
-        ? prompt(tool)
-        : prompt;
-    return (0, executeFunctionCall_js_1.executeFunctionCall)({
-        options,
-        input: expandedPrompt,
-        functionType: "use-tool",
-        execute: async (options) => {
-            const { value } = await (0, generateStructure_js_1.generateStructure)(model, {
-                name: tool.name,
-                description: tool.description,
-                schema: tool.inputSchema,
-            }, expandedPrompt, {
-                ...options,
-                returnType: "full",
-            });
-            return {
-                tool: tool.name,
-                parameters: value,
-                result: await (0, executeTool_js_1.executeTool)(tool, value, options),
-            };
-        },
-    });
-}
-exports.useTool = useTool;

package/tool/useTool.d.ts

@@ -1,15 +0,0 @@
-import { FunctionOptions } from "../core/FunctionOptions.js";
-import { StructureGenerationModel, StructureGenerationModelSettings } from "../model-function/generate-structure/StructureGenerationModel.js";
-import { Tool } from "./Tool.js";
-/**
- * `useTool` uses `generateStructure` to generate parameters for a tool and then executes the tool with the parameters.
- *
- * @returns The result contains the name of the tool (`tool` property),
- * the parameters (`parameters` property, typed),
- * and the result of the tool execution (`result` property, typed).
- */
-export declare function useTool<PROMPT, TOOL extends Tool<any, any, any>>(model: StructureGenerationModel<PROMPT, StructureGenerationModelSettings>, tool: TOOL, prompt: PROMPT | ((tool: TOOL) => PROMPT), options?: FunctionOptions): Promise<{
-    tool: TOOL["name"];
-    parameters: TOOL["inputSchema"];
-    result: Awaited<ReturnType<TOOL["execute"]>>;
-}>;

package/tool/useTool.js

@@ -1,36 +0,0 @@
-import { executeFunctionCall } from "../core/executeFunctionCall.js";
-import { generateStructure } from "../model-function/generate-structure/generateStructure.js";
-import { executeTool } from "./executeTool.js";
-/**
- * `useTool` uses `generateStructure` to generate parameters for a tool and then executes the tool with the parameters.
- *
- * @returns The result contains the name of the tool (`tool` property),
- * the parameters (`parameters` property, typed),
- * and the result of the tool execution (`result` property, typed).
- */
-export async function useTool(model, tool, prompt, options) {
-    // Note: PROMPT must not be a function.
-    const expandedPrompt = typeof prompt === "function"
-        ? prompt(tool)
-        : prompt;
-    return executeFunctionCall({
-        options,
-        input: expandedPrompt,
-        functionType: "use-tool",
-        execute: async (options) => {
-            const { value } = await generateStructure(model, {
-                name: tool.name,
-                description: tool.description,
-                schema: tool.inputSchema,
-            }, expandedPrompt, {
-                ...options,
-                returnType: "full",
-            });
-            return {
-                tool: tool.name,
-                parameters: value,
-                result: await executeTool(tool, value, options),
-            };
-        },
-    });
-}

package/tool/useToolOrGenerateText.cjs

@@ -1,50 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.useToolOrGenerateText = void 0;
-const executeFunctionCall_js_1 = require("../core/executeFunctionCall.cjs");
-const generateStructureOrText_js_1 = require("../model-function/generate-structure/generateStructureOrText.cjs");
-const NoSuchToolError_js_1 = require("./NoSuchToolError.cjs");
-const executeTool_js_1 = require("./executeTool.cjs");
-async function useToolOrGenerateText(model, tools, prompt, options) {
-    // Note: PROMPT must not be a function.
-    const expandedPrompt = typeof prompt === "function"
-        ? prompt(tools)
-        : prompt;
-    return (0, executeFunctionCall_js_1.executeFunctionCall)({
-        options,
-        input: expandedPrompt,
-        functionType: "use-tool-or-generate-text",
-        execute: async (options) => {
-            const modelResponse = await (0, generateStructureOrText_js_1.generateStructureOrText)(model, tools.map((tool) => ({
-                name: tool.name,
-                description: tool.description,
-                schema: tool.inputSchema,
-            })), expandedPrompt, {
-                ...options,
-                returnType: "structure",
-            });
-            const { structure, text } = modelResponse;
-            if (structure == null) {
-                return {
-                    tool: null,
-                    parameters: null,
-                    result: null,
-                    text,
-                };
-            }
-            const tool = tools.find((tool) => tool.name === structure);
-            if (tool == null) {
-                throw new NoSuchToolError_js_1.NoSuchToolError(structure.toString());
-            }
-            const toolParameters = modelResponse.value;
-            const result = await (0, executeTool_js_1.executeTool)(tool, toolParameters, options);
-            return {
-                tool: structure,
-                result,
-                parameters: toolParameters,
-                text: text, // string | null is the expected value here
-            };
-        },
-    });
-}
-exports.useToolOrGenerateText = useToolOrGenerateText;

package/tool/useToolOrGenerateText.d.ts

@@ -1,23 +0,0 @@
-import { FunctionOptions } from "../core/FunctionOptions.js";
-import { StructureOrTextGenerationModel, StructureOrTextGenerationModelSettings } from "../model-function/generate-structure/StructureOrTextGenerationModel.js";
-import { Tool } from "./Tool.js";
-type ToolArray<T extends Tool<any, any, any>[]> = T;
-type ToToolMap<T extends ToolArray<Tool<any, any, any>[]>> = {
-    [K in T[number]["name"]]: Extract<T[number], Tool<K, any, any>>;
-};
-type ToToolUnion<T> = {
-    [KEY in keyof T]: T[KEY] extends Tool<any, infer INPUT, infer OUTPUT> ? {
-        tool: KEY;
-        parameters: INPUT;
-        result: OUTPUT;
-        text: string | null;
-    } : never;
-}[keyof T];
-type ToOutputValue<TOOLS extends ToolArray<Tool<any, any, any>[]>> = ToToolUnion<ToToolMap<TOOLS>>;
-export declare function useToolOrGenerateText<PROMPT, SETTINGS extends StructureOrTextGenerationModelSettings, TOOLS extends Array<Tool<any, any, any>>>(model: StructureOrTextGenerationModel<PROMPT, SETTINGS>, tools: TOOLS, prompt: PROMPT | ((tools: TOOLS) => PROMPT), options?: FunctionOptions): Promise<{
-    tool: null;
-    parameters: null;
-    result: null;
-    text: string;
-} | ToOutputValue<TOOLS>>;
-export {};

package/tool/useToolOrGenerateText.js

@@ -1,46 +0,0 @@
-import { executeFunctionCall } from "../core/executeFunctionCall.js";
-import { generateStructureOrText } from "../model-function/generate-structure/generateStructureOrText.js";
-import { NoSuchToolError } from "./NoSuchToolError.js";
-import { executeTool } from "./executeTool.js";
-export async function useToolOrGenerateText(model, tools, prompt, options) {
-    // Note: PROMPT must not be a function.
-    const expandedPrompt = typeof prompt === "function"
-        ? prompt(tools)
-        : prompt;
-    return executeFunctionCall({
-        options,
-        input: expandedPrompt,
-        functionType: "use-tool-or-generate-text",
-        execute: async (options) => {
-            const modelResponse = await generateStructureOrText(model, tools.map((tool) => ({
-                name: tool.name,
-                description: tool.description,
-                schema: tool.inputSchema,
-            })), expandedPrompt, {
-                ...options,
-                returnType: "structure",
-            });
-            const { structure, text } = modelResponse;
-            if (structure == null) {
-                return {
-                    tool: null,
-                    parameters: null,
-                    result: null,
-                    text,
-                };
-            }
-            const tool = tools.find((tool) => tool.name === structure);
-            if (tool == null) {
-                throw new NoSuchToolError(structure.toString());
-            }
-            const toolParameters = modelResponse.value;
-            const result = await executeTool(tool, toolParameters, options);
-            return {
-                tool: structure,
-                result,
-                parameters: toolParameters,
-                text: text, // string | null is the expected value here
-            };
-        },
-    });
-}