modelfusion 0.125.0 → 0.126.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v0.126.0 - 2024-01-15
+
+### Changed
+
+- **breaking change**: rename `useTool` to `runTool` and `useTools` to `runTools` to avoid confusion with React hooks.
+
 ## v0.125.0 - 2024-01-14
 
 ### Added

package/README.md

@@ -372,12 +372,12 @@ Tools are functions (and associated metadata) that can be executed by an AI mode
 
 ModelFusion offers several tools out-of-the-box: [Math.js](https://modelfusion.dev/guide/tools/available-tools/mathjs), [MediaWiki Search](https://modelfusion.dev/guide/tools/available-tools/mediawiki-search), [SerpAPI](https://modelfusion.dev/guide/tools/available-tools/serpapi), [Google Custom Search](https://modelfusion.dev/guide/tools/available-tools/google-custom-search). You can also create [custom tools](https://modelfusion.dev/guide/tools).
 
-#### [useTool](https://modelfusion.dev/guide/tools/use-tool)
+#### [runTool](https://modelfusion.dev/guide/tools/run-tool)
 
-With `useTool`, you can ask a tool-compatible language model (e.g. OpenAI chat) to invoke a single tool. `useTool` first generates a tool call and then executes the tool with the arguments.
+With `runTool`, you can ask a tool-compatible language model (e.g. OpenAI chat) to invoke a single tool. `runTool` first generates a tool call and then executes the tool with the arguments.
 
 ```ts
-const { tool, toolCall, args, ok, result } = await useTool({
+const { tool, toolCall, args, ok, result } = await runTool({
   model: openai.ChatTextGenerator({ model: "gpt-3.5-turbo" }),
   too: calculator,
   prompt: [openai.ChatMessage.user("What's fourteen times twelve?")],
@@ -390,12 +390,12 @@ console.log(`Ok:`, ok);
 console.log(`Result or Error:`, result);
 ```
 
-#### [useTools](https://modelfusion.dev/guide/tools/use-tools)
+#### [runTools](https://modelfusion.dev/guide/tools/run-tools)
 
-With `useTools`, you can ask a language model to generate several tool calls as well as text. The model will choose which tools (if any) should be called with which arguments. Both the text and the tool calls are optional. This function executes the tools.
+With `runTools`, you can ask a language model to generate several tool calls as well as text. The model will choose which tools (if any) should be called with which arguments. Both the text and the tool calls are optional. This function executes the tools.
 
 ```ts
-const { text, toolResults } = await useTools({
+const { text, toolResults } = await runTools({
   model: openai.ChatTextGenerator({ model: "gpt-3.5-turbo" }),
   tools: [calculator /* ... */],
   prompt: [openai.ChatMessage.user("What's fourteen times twelve?")],
@@ -404,7 +404,7 @@ const { text, toolResults } = await useTools({
 
 #### [Agent Loop](https://modelfusion.dev/guide/tools/agent-loop)
 
-You can use `useTools` to implement an agent loop that responds to user messages and executes tools. [Learn more](https://modelfusion.dev/guide/tools/agent-loop).
+You can use `runTools` to implement an agent loop that responds to user messages and executes tools. [Learn more](https://modelfusion.dev/guide/tools/agent-loop).
 
 ### [Vector Indices](https://modelfusion.dev/guide/vector-index)
 
@@ -580,8 +580,8 @@ modelfusion.setLogFormat("detailed-object"); // log full events
   - [Embed Value](https://modelfusion.dev/guide/function/embed)
   - [Classify Value](https://modelfusion.dev/guide/function/classify)
 - [Tools](https://modelfusion.dev/guide/tools)
-  - [Use Tool](https://modelfusion.dev/guide/tools/use-tool)
-  - [Use Tools](https://modelfusion.dev/guide/tools/use-tools)
+  - [Use Tool](https://modelfusion.dev/guide/tools/run-tool)
+  - [Use Tools](https://modelfusion.dev/guide/tools/run-tools)
   - [Agent Loop](https://modelfusion.dev/guide/tools/agent-loop)
   - [Available Tools](https://modelfusion.dev/guide/tools/available-tools/)
   - [Custom Tools](https://modelfusion.dev/guide/tools/custom-tools)

package/core/FunctionEvent.d.ts

@@ -1,8 +1,8 @@
 import { ModelCallFinishedEvent, ModelCallStartedEvent } from "../model-function/ModelCallEvent.js";
 import { RetrieveFinishedEvent, RetrieveStartedEvent } from "../retriever/RetrieveEvent.js";
 import { ExecuteToolFinishedEvent, ExecuteToolStartedEvent } from "../tool/execute-tool/ExecuteToolEvent.js";
-import { UseToolFinishedEvent, UseToolStartedEvent } from "../tool/use-tool/UseToolEvent.js";
-import { useToolsFinishedEvent, useToolsStartedEvent } from "../tool/use-tools/UseToolsEvent.js";
+import { runToolFinishedEvent, runToolStartedEvent } from "../tool/run-tool/RunToolEvent.js";
+import { runToolsFinishedEvent, runToolsStartedEvent } from "../tool/run-tools/RunToolsEvent.js";
 import { UpsertIntoVectorIndexFinishedEvent, UpsertIntoVectorIndexStartedEvent } from "../vector-index/UpsertIntoVectorIndexEvent.js";
 import { ExecuteFunctionFinishedEvent, ExecuteFunctionStartedEvent } from "./ExecuteFunctionEvent.js";
 import { ExtensionFunctionFinishedEvent, ExtensionFunctionStartedEvent } from "./ExtensionFunctionEvent.js";
@@ -82,4 +82,4 @@ export interface BaseFunctionFinishedEvent extends BaseFunctionEvent {
      */
     result: BaseFunctionFinishedEventResult;
 }
-export type FunctionEvent = ExecuteFunctionStartedEvent | ExecuteFunctionFinishedEvent | ExecuteToolStartedEvent | ExecuteToolFinishedEvent | ExtensionFunctionStartedEvent | ExtensionFunctionFinishedEvent | ModelCallStartedEvent | ModelCallFinishedEvent | RetrieveStartedEvent | RetrieveFinishedEvent | UpsertIntoVectorIndexStartedEvent | UpsertIntoVectorIndexFinishedEvent | UseToolStartedEvent | UseToolFinishedEvent | useToolsStartedEvent | useToolsFinishedEvent;
+export type FunctionEvent = ExecuteFunctionStartedEvent | ExecuteFunctionFinishedEvent | ExecuteToolStartedEvent | ExecuteToolFinishedEvent | ExtensionFunctionStartedEvent | ExtensionFunctionFinishedEvent | ModelCallStartedEvent | ModelCallFinishedEvent | RetrieveStartedEvent | RetrieveFinishedEvent | UpsertIntoVectorIndexStartedEvent | UpsertIntoVectorIndexFinishedEvent | runToolStartedEvent | runToolFinishedEvent | runToolsStartedEvent | runToolsFinishedEvent;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "modelfusion",
   "description": "The TypeScript library for building AI applications.",
-  "version": "0.125.0",
+  "version": "0.126.0",
   "author": "Lars Grammel",
   "license": "MIT",
   "keywords": [

package/tool/index.cjs

@@ -27,5 +27,5 @@ __exportStar(require("./WebSearchTool.cjs"), exports);
 __exportStar(require("./execute-tool/index.cjs"), exports);
 __exportStar(require("./generate-tool-call/index.cjs"), exports);
 __exportStar(require("./generate-tool-calls/index.cjs"), exports);
-__exportStar(require("./use-tool/index.cjs"), exports);
-__exportStar(require("./use-tools/index.cjs"), exports);
+__exportStar(require("./run-tool/index.cjs"), exports);
+__exportStar(require("./run-tools/index.cjs"), exports);

package/tool/index.d.ts

@@ -11,5 +11,5 @@ export * from "./WebSearchTool.js";
 export * from "./execute-tool/index.js";
 export * from "./generate-tool-call/index.js";
 export * from "./generate-tool-calls/index.js";
-export * from "./use-tool/index.js";
-export * from "./use-tools/index.js";
+export * from "./run-tool/index.js";
+export * from "./run-tools/index.js";

package/tool/index.js

@@ -11,5 +11,5 @@ export * from "./WebSearchTool.js";
 export * from "./execute-tool/index.js";
 export * from "./generate-tool-call/index.js";
 export * from "./generate-tool-calls/index.js";
-export * from "./use-tool/index.js";
-export * from "./use-tools/index.js";
+export * from "./run-tool/index.js";
+export * from "./run-tools/index.js";

package/tool/run-tool/RunToolEvent.d.ts

@@ -0,0 +1,7 @@
+import { BaseFunctionFinishedEvent, BaseFunctionStartedEvent } from "../../core/FunctionEvent.js";
+export interface runToolStartedEvent extends BaseFunctionStartedEvent {
+    functionType: "run-tool";
+}
+export interface runToolFinishedEvent extends BaseFunctionFinishedEvent {
+    functionType: "run-tool";
+}

package/tool/{use-tool → run-tool}/index.cjs

@@ -14,5 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./UseToolEvent.cjs"), exports);
-__exportStar(require("./useTool.cjs"), exports);
+__exportStar(require("./RunToolEvent.cjs"), exports);
+__exportStar(require("./runTool.cjs"), exports);

package/tool/run-tool/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./RunToolEvent.js";
+export * from "./runTool.js";

package/tool/run-tool/index.js

@@ -0,0 +1,2 @@
+export * from "./RunToolEvent.js";
+export * from "./runTool.js";

package/tool/{use-tool/useTool.cjs → run-tool/runTool.cjs}

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useTool = void 0;
+exports.runTool = void 0;
 const executeFunctionCall_js_1 = require("../../core/executeFunctionCall.cjs");
 const safeExecuteToolCall_js_1 = require("../execute-tool/safeExecuteToolCall.cjs");
 const generateToolCall_js_1 = require("../generate-tool-call/generateToolCall.cjs");
 /**
- * `useTool` uses `generateToolCall` to generate parameters for a tool and
+ * `runTool` uses `generateToolCall` to generate parameters for a tool and
  * then executes the tool with the parameters using `executeTool`.
  *
  * @returns The result contains the name of the tool (`tool` property),
@@ -15,7 +15,7 @@ const generateToolCall_js_1 = require("../generate-tool-call/generateToolCall.cj
  * @see {@link generateToolCall}
  * @see {@link executeTool}
  */
-async function useTool({ model, tool, prompt, ...options }) {
+async function runTool({ model, tool, prompt, ...options }) {
     // Note: PROMPT must not be a function.
     const expandedPrompt = typeof prompt === "function"
         ? prompt(tool)
@@ -23,8 +23,8 @@ async function useTool({ model, tool, prompt, ...options }) {
     return (0, executeFunctionCall_js_1.executeFunctionCall)({
         options,
         input: expandedPrompt,
-        functionType: "use-tool",
+        functionType: "run-tool",
         execute: async (options) => (0, safeExecuteToolCall_js_1.safeExecuteToolCall)(tool, await (0, generateToolCall_js_1.generateToolCall)({ model, tool, prompt: expandedPrompt, ...options }), options),
     });
 }
-exports.useTool = useTool;
+exports.runTool = runTool;

package/tool/{use-tool/useTool.d.ts → run-tool/runTool.d.ts}

@@ -3,7 +3,7 @@ import { Tool } from "../Tool.js";
 import { ToolCallResult } from "../ToolCallResult.js";
 import { ToolCallGenerationModel, ToolCallGenerationModelSettings } from "../generate-tool-call/ToolCallGenerationModel.js";
 /**
- * `useTool` uses `generateToolCall` to generate parameters for a tool and
+ * `runTool` uses `generateToolCall` to generate parameters for a tool and
  * then executes the tool with the parameters using `executeTool`.
  *
  * @returns The result contains the name of the tool (`tool` property),
@@ -13,7 +13,7 @@ import { ToolCallGenerationModel, ToolCallGenerationModelSettings } from "../gen
  * @see {@link generateToolCall}
  * @see {@link executeTool}
  */
-export declare function useTool<PROMPT, TOOL extends Tool<string, any, any>>({ model, tool, prompt, ...options }: {
+export declare function runTool<PROMPT, TOOL extends Tool<string, any, any>>({ model, tool, prompt, ...options }: {
     model: ToolCallGenerationModel<PROMPT, ToolCallGenerationModelSettings>;
     tool: TOOL;
     prompt: PROMPT | ((tool: TOOL) => PROMPT);

package/tool/{use-tool/useTool.js → run-tool/runTool.js}

@@ -2,7 +2,7 @@ import { executeFunctionCall } from "../../core/executeFunctionCall.js";
 import { safeExecuteToolCall } from "../execute-tool/safeExecuteToolCall.js";
 import { generateToolCall } from "../generate-tool-call/generateToolCall.js";
 /**
- * `useTool` uses `generateToolCall` to generate parameters for a tool and
+ * `runTool` uses `generateToolCall` to generate parameters for a tool and
  * then executes the tool with the parameters using `executeTool`.
  *
  * @returns The result contains the name of the tool (`tool` property),
@@ -12,7 +12,7 @@ import { generateToolCall } from "../generate-tool-call/generateToolCall.js";
  * @see {@link generateToolCall}
  * @see {@link executeTool}
  */
-export async function useTool({ model, tool, prompt, ...options }) {
+export async function runTool({ model, tool, prompt, ...options }) {
     // Note: PROMPT must not be a function.
     const expandedPrompt = typeof prompt === "function"
         ? prompt(tool)
@@ -20,7 +20,7 @@ export async function useTool({ model, tool, prompt, ...options }) {
     return executeFunctionCall({
         options,
         input: expandedPrompt,
-        functionType: "use-tool",
+        functionType: "run-tool",
         execute: async (options) => safeExecuteToolCall(tool, await generateToolCall({ model, tool, prompt: expandedPrompt, ...options }), options),
     });
 }

package/tool/run-tools/RunToolsEvent.d.ts

@@ -0,0 +1,7 @@
+import { BaseFunctionFinishedEvent, BaseFunctionStartedEvent } from "../../core/FunctionEvent.js";
+export interface runToolsStartedEvent extends BaseFunctionStartedEvent {
+    functionType: "run-tools";
+}
+export interface runToolsFinishedEvent extends BaseFunctionFinishedEvent {
+    functionType: "run-tools";
+}

package/tool/{use-tools → run-tools}/index.cjs

@@ -14,5 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./UseToolsEvent.cjs"), exports);
-__exportStar(require("./useTools.cjs"), exports);
+__exportStar(require("./RunToolsEvent.cjs"), exports);
+__exportStar(require("./runTools.cjs"), exports);

package/tool/run-tools/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./RunToolsEvent.js";
+export * from "./runTools.js";

package/tool/run-tools/index.js

@@ -0,0 +1,2 @@
+export * from "./RunToolsEvent.js";
+export * from "./runTools.js";

package/tool/{use-tools/useTools.cjs → run-tools/runTools.cjs}

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useTools = void 0;
+exports.runTools = void 0;
 const executeFunctionCall_js_1 = require("../../core/executeFunctionCall.cjs");
 const ToolCallError_js_1 = require("../ToolCallError.cjs");
 const safeExecuteToolCall_js_1 = require("../execute-tool/safeExecuteToolCall.cjs");
 const generateToolCalls_js_1 = require("../generate-tool-calls/generateToolCalls.cjs");
-async function useTools({ model, tools, prompt, ...options }) {
+async function runTools({ model, tools, prompt, ...options }) {
     // Note: PROMPT must not be a function.
     const expandedPrompt = typeof prompt === "function"
         ? prompt(tools)
@@ -13,7 +13,7 @@ async function useTools({ model, tools, prompt, ...options }) {
     return (0, executeFunctionCall_js_1.executeFunctionCall)({
         options,
         input: expandedPrompt,
-        functionType: "use-tools",
+        functionType: "run-tools",
         execute: async (options) => {
             const modelResponse = await (0, generateToolCalls_js_1.generateToolCalls)({
                 model,
@@ -51,4 +51,4 @@ async function useTools({ model, tools, prompt, ...options }) {
         },
     });
 }
-exports.useTools = useTools;
+exports.runTools = runTools;

package/tool/{use-tools/useTools.d.ts → run-tools/runTools.d.ts}

@@ -11,7 +11,7 @@ type ToToolCallUnion<T> = {
     [KEY in StringKeys<T>]: T[KEY] extends Tool<any, infer PARAMETERS, infer OUTPUT> ? ToolCallResult<KEY, PARAMETERS, OUTPUT> : never;
 }[StringKeys<T>];
 type ToOutputValue<TOOLS extends ToolArray<Tool<any, any, any>[]>> = ToToolCallUnion<ToToolMap<TOOLS>>;
-export declare function useTools<PROMPT, TOOLS extends Array<Tool<any, any, any>>>({ model, tools, prompt, ...options }: {
+export declare function runTools<PROMPT, TOOLS extends Array<Tool<any, any, any>>>({ model, tools, prompt, ...options }: {
     model: ToolCallsGenerationModel<PROMPT, ToolCallsGenerationModelSettings>;
     tools: TOOLS;
     prompt: PROMPT | ((tools: TOOLS) => PROMPT);

package/tool/{use-tools/useTools.js → run-tools/runTools.js}

@@ -2,7 +2,7 @@ import { executeFunctionCall } from "../../core/executeFunctionCall.js";
 import { ToolCallError } from "../ToolCallError.js";
 import { safeExecuteToolCall } from "../execute-tool/safeExecuteToolCall.js";
 import { generateToolCalls } from "../generate-tool-calls/generateToolCalls.js";
-export async function useTools({ model, tools, prompt, ...options }) {
+export async function runTools({ model, tools, prompt, ...options }) {
     // Note: PROMPT must not be a function.
     const expandedPrompt = typeof prompt === "function"
         ? prompt(tools)
@@ -10,7 +10,7 @@ export async function useTools({ model, tools, prompt, ...options }) {
     return executeFunctionCall({
         options,
         input: expandedPrompt,
-        functionType: "use-tools",
+        functionType: "run-tools",
         execute: async (options) => {
             const modelResponse = await generateToolCalls({
                 model,

package/tool/use-tool/UseToolEvent.d.ts

@@ -1,7 +0,0 @@
-import { BaseFunctionFinishedEvent, BaseFunctionStartedEvent } from "../../core/FunctionEvent.js";
-export interface UseToolStartedEvent extends BaseFunctionStartedEvent {
-    functionType: "use-tool";
-}
-export interface UseToolFinishedEvent extends BaseFunctionFinishedEvent {
-    functionType: "use-tool";
-}

package/tool/use-tool/index.d.ts

@@ -1,2 +0,0 @@
-export * from "./UseToolEvent.js";
-export * from "./useTool.js";

package/tool/use-tool/index.js

@@ -1,2 +0,0 @@
-export * from "./UseToolEvent.js";
-export * from "./useTool.js";

package/tool/use-tools/UseToolsEvent.d.ts

@@ -1,7 +0,0 @@
-import { BaseFunctionFinishedEvent, BaseFunctionStartedEvent } from "../../core/FunctionEvent.js";
-export interface useToolsStartedEvent extends BaseFunctionStartedEvent {
-    functionType: "use-tools";
-}
-export interface useToolsFinishedEvent extends BaseFunctionFinishedEvent {
-    functionType: "use-tools";
-}

package/tool/use-tools/index.d.ts

@@ -1,2 +0,0 @@
-export * from "./UseToolsEvent.js";
-export * from "./useTools.js";

package/tool/use-tools/index.js

@@ -1,2 +0,0 @@
-export * from "./UseToolsEvent.js";
-export * from "./useTools.js";