modelfusion 0.53.0 → 0.53.2

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

@@ -1,17 +1,25 @@
 import { executeStandardCall } from "../executeStandardCall.js";
 import { ModelFunctionPromise } from "../ModelFunctionPromise.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 function generateText(model, prompt, options) {
     return new ModelFunctionPromise(executeStandardCall({

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

@@ -3,6 +3,31 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.streamText = void 0;
 const AsyncIterableResultPromise_js_1 = require("../AsyncIterableResultPromise.cjs");
 const executeStreamCall_js_1 = require("../executeStreamCall.cjs");
+/**
+ * Stream the generated text for a prompt as an async iterable.
+ *
+ * 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 textStream = await streamText(
+ *   new OpenAICompletionModel(...),
+ *   "Write a short story about a robot learning to love:\n\n"
+ * );
+ *
+ * for await (const textPart of textStream) {
+ *   // ...
+ * }
+ *
+ * @param {TextStreamingModel<PROMPT>} model - The model to stream text from.
+ * @param {PROMPT} prompt - The prompt to use for text generation.
+ * @param {FunctionOptions} [options] - Optional parameters for the function.
+ *
+ * @returns {AsyncIterableResultPromise<string>} An async iterable promise that yields the generated text.
+ */
 function streamText(model, prompt, options) {
     let accumulatedText = "";
     let lastFullDelta;

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

@@ -1,4 +1,29 @@
 import { FunctionOptions } from "../../core/FunctionOptions.js";
 import { AsyncIterableResultPromise } from "../AsyncIterableResultPromise.js";
 import { TextStreamingModel } from "./TextGenerationModel.js";
+/**
+ * Stream the generated text for a prompt as an async iterable.
+ *
+ * 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 textStream = await streamText(
+ *   new OpenAICompletionModel(...),
+ *   "Write a short story about a robot learning to love:\n\n"
+ * );
+ *
+ * for await (const textPart of textStream) {
+ *   // ...
+ * }
+ *
+ * @param {TextStreamingModel<PROMPT>} model - The model to stream text from.
+ * @param {PROMPT} prompt - The prompt to use for text generation.
+ * @param {FunctionOptions} [options] - Optional parameters for the function.
+ *
+ * @returns {AsyncIterableResultPromise<string>} An async iterable promise that yields the generated text.
+ */
 export declare function streamText<PROMPT>(model: TextStreamingModel<PROMPT>, prompt: PROMPT, options?: FunctionOptions): AsyncIterableResultPromise<string>;

package/model-function/generate-text/streamText.js

@@ -1,5 +1,30 @@
 import { AsyncIterableResultPromise } from "../AsyncIterableResultPromise.js";
 import { executeStreamCall } from "../executeStreamCall.js";
+/**
+ * Stream the generated text for a prompt as an async iterable.
+ *
+ * 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 textStream = await streamText(
+ *   new OpenAICompletionModel(...),
+ *   "Write a short story about a robot learning to love:\n\n"
+ * );
+ *
+ * for await (const textPart of textStream) {
+ *   // ...
+ * }
+ *
+ * @param {TextStreamingModel<PROMPT>} model - The model to stream text from.
+ * @param {PROMPT} prompt - The prompt to use for text generation.
+ * @param {FunctionOptions} [options] - Optional parameters for the function.
+ *
+ * @returns {AsyncIterableResultPromise<string>} An async iterable promise that yields the generated text.
+ */
 export function streamText(model, prompt, options) {
     let accumulatedText = "";
     let lastFullDelta;

package/model-function/generate-transcription/generateTranscription.cjs

@@ -4,18 +4,23 @@ exports.generateTranscription = void 0;
 const executeStandardCall_js_1 = require("../executeStandardCall.cjs");
 const ModelFunctionPromise_js_1 = require("../ModelFunctionPromise.cjs");
 /**
- * Transcribe audio data into text.
+ * Transcribe audio data into text. Also called speech-to-text (STT) or automatic speech recognition (ASR).
+ *
+ * @see https://modelfusion.dev/guide/function/generate-transcription
  *
  * @example
  * const data = await fs.promises.readFile("data/test.mp3");
  *
  * const transcription = await generateTranscription(
  *   new OpenAITranscriptionModel({ model: "whisper-1" }),
- *   {
- *     type: "mp3",
- *     data,
- *   }
+ *   { type: "mp3", data }
  * );
+ *
+ * @param {TranscriptionModel<DATA, TranscriptionModelSettings>} model - The model to use for transcription.
+ * @param {DATA} data - The data to transcribe.
+ * @param {FunctionOptions} [options] - Optional parameters for the function.
+ *
+ * @returns {ModelFunctionPromise<string>} A promise that resolves to the transcribed text.
  */
 function generateTranscription(model, data, options) {
     return new ModelFunctionPromise_js_1.ModelFunctionPromise((0, executeStandardCall_js_1.executeStandardCall)({

package/model-function/generate-transcription/generateTranscription.d.ts

@@ -2,17 +2,22 @@ import { FunctionOptions } from "../../core/FunctionOptions.js";
 import { ModelFunctionPromise } from "../ModelFunctionPromise.js";
 import { TranscriptionModel, TranscriptionModelSettings } from "./TranscriptionModel.js";
 /**
- * Transcribe audio data into text.
+ * Transcribe audio data into text. Also called speech-to-text (STT) or automatic speech recognition (ASR).
+ *
+ * @see https://modelfusion.dev/guide/function/generate-transcription
  *
  * @example
  * const data = await fs.promises.readFile("data/test.mp3");
  *
  * const transcription = await generateTranscription(
  *   new OpenAITranscriptionModel({ model: "whisper-1" }),
- *   {
- *     type: "mp3",
- *     data,
- *   }
+ *   { type: "mp3", data }
  * );
+ *
+ * @param {TranscriptionModel<DATA, TranscriptionModelSettings>} model - The model to use for transcription.
+ * @param {DATA} data - The data to transcribe.
+ * @param {FunctionOptions} [options] - Optional parameters for the function.
+ *
+ * @returns {ModelFunctionPromise<string>} A promise that resolves to the transcribed text.
  */
 export declare function generateTranscription<DATA>(model: TranscriptionModel<DATA, TranscriptionModelSettings>, data: DATA, options?: FunctionOptions): ModelFunctionPromise<string>;

package/model-function/generate-transcription/generateTranscription.js

@@ -1,18 +1,23 @@
 import { executeStandardCall } from "../executeStandardCall.js";
 import { ModelFunctionPromise } from "../ModelFunctionPromise.js";
 /**
- * Transcribe audio data into text.
+ * Transcribe audio data into text. Also called speech-to-text (STT) or automatic speech recognition (ASR).
+ *
+ * @see https://modelfusion.dev/guide/function/generate-transcription
  *
  * @example
  * const data = await fs.promises.readFile("data/test.mp3");
  *
  * const transcription = await generateTranscription(
  *   new OpenAITranscriptionModel({ model: "whisper-1" }),
- *   {
- *     type: "mp3",
- *     data,
- *   }
+ *   { type: "mp3", data }
  * );
+ *
+ * @param {TranscriptionModel<DATA, TranscriptionModelSettings>} model - The model to use for transcription.
+ * @param {DATA} data - The data to transcribe.
+ * @param {FunctionOptions} [options] - Optional parameters for the function.
+ *
+ * @returns {ModelFunctionPromise<string>} A promise that resolves to the transcribed text.
  */
 export function generateTranscription(model, data, options) {
     return new ModelFunctionPromise(executeStandardCall({

package/model-function/tokenize-text/Tokenizer.d.ts

@@ -1,19 +1,43 @@
+/**
+ * Interface for a basic tokenizer capable of converting text into tokens.
+ *
+ * This serves as the base for tokenization functionalities where the focus is on the transformation of input text into a series of numeric tokens.
+ */
 export interface BasicTokenizer {
     /**
-     * Get the tokens that represent the given text.
+     * Asynchronously tokenize the given text into a sequence of numeric tokens.
+     *
+     * @param text - Input text string that needs to be tokenized.
+     * @returns A promise containing an array of numbers, where each number is a token representing a part or the whole of the input text.
      */
     tokenize: (text: string) => PromiseLike<Array<number>>;
 }
+/**
+ * Interface for a comprehensive tokenizer that extends the basic tokenization capabilities.
+ *
+ * In addition to basic tokenization, this interface provides methods for detokenization and
+ * retrieving the original text corresponding to each token, enabling a more informative and reversible transformation process.
+ */
 export interface FullTokenizer extends BasicTokenizer {
     /**
-     * Get the tokens that represent the given text and the text for each token.
+     * Asynchronously tokenize the given text, providing both the numeric tokens and their corresponding text.
+     *
+     * @param text - Input text string to be tokenized.
+     * @returns A promise containing an object with two arrays:
+     *          1. `tokens` - An array of numbers where each number is a token.
+     *          2. `tokenTexts` - An array of strings where each string represents the original text corresponding to each token.
      */
     tokenizeWithTexts: (text: string) => PromiseLike<{
         tokens: Array<number>;
         tokenTexts: Array<string>;
     }>;
     /**
-     * Get the text that represents the given tokens.
+     * Asynchronously revert a sequence of numeric tokens back into the original text.
+     * Detokenization is the process of transforming tokens back to a human-readable format, and it's essential in scenarios
+     * where the output needs to be interpretable or when the tokenization process has to be reversible.
+     *
+     * @param tokens - An array of numeric tokens to be converted back to text.
+     * @returns A promise containing a string that represents the original text corresponding to the sequence of input tokens.
      */
     detokenize: (tokens: Array<number>) => PromiseLike<string>;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "modelfusion",
   "description": "Build multimodal applications, chatbots, and agents with JavaScript and TypeScript.",
-  "version": "0.53.0",
+  "version": "0.53.2",
   "author": "Lars Grammel",
   "license": "MIT",
   "keywords": [

package/util/AsyncQueue.cjs

@@ -22,7 +22,7 @@ class AsyncQueue {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: []
+            value: Array()
         });
         Object.defineProperty(this, "pendingResolvers", {
             enumerable: true,
@@ -37,6 +37,11 @@ class AsyncQueue {
             value: false
         });
     }
+    processPendingResolvers() {
+        while (this.pendingResolvers.length > 0) {
+            this.pendingResolvers.shift()?.();
+        }
+    }
     /**
      * Pushes an element onto the queue. If the queue is closed, an error is thrown.
      *
@@ -47,12 +52,17 @@ class AsyncQueue {
      */
     push(value) {
         if (this.closed) {
-            throw new Error("Cannot push value to closed queue. The queue has been closed and is no longer accepting new items.");
+            throw new Error("Cannot push value to closed queue.");
         }
-        this.values.push(value);
-        while (this.pendingResolvers.length > 0) {
-            this.pendingResolvers.shift()?.();
+        this.values.push({ type: "value", value });
+        this.processPendingResolvers();
+    }
+    error(error) {
+        if (this.closed) {
+            throw new Error("Cannot push error to closed queue.");
         }
+        this.values.push({ type: "error", error });
+        this.processPendingResolvers();
     }
     /**
      * Closes the queue, preventing more elements from being pushed onto it.
@@ -62,9 +72,7 @@ class AsyncQueue {
      */
     close() {
         this.closed = true;
-        while (this.pendingResolvers.length > 0) {
-            this.pendingResolvers.shift()?.();
-        }
+        this.processPendingResolvers();
     }
     /**
      * Creates and returns an async iterator that allows the queue to be consumed.
@@ -81,11 +89,18 @@ class AsyncQueue {
     [Symbol.asyncIterator]() {
         let position = 0;
         return {
-            next: () => new Promise((resolve) => {
+            next: () => new Promise((resolve, reject) => {
                 const attemptResolve = () => {
                     if (position < this.values.length) {
-                        // There's an available value, resolve it immediately.
-                        resolve({ value: this.values[position++], done: false });
+                        const entry = this.values[position++];
+                        switch (entry.type) {
+                            case "value":
+                                resolve({ value: entry.value, done: false });
+                                break;
+                            case "error":
+                                reject(entry.error);
+                                break;
+                        }
                     }
                     else if (this.closed) {
                         // The queue is closed, and there are no more values. Complete the iteration.

package/util/AsyncQueue.d.ts

@@ -17,6 +17,7 @@ export declare class AsyncQueue<T> implements AsyncIterable<T> {
     private values;
     private pendingResolvers;
     private closed;
+    private processPendingResolvers;
     /**
      * Pushes an element onto the queue. If the queue is closed, an error is thrown.
      *
@@ -26,6 +27,7 @@ export declare class AsyncQueue<T> implements AsyncIterable<T> {
      * queue.push(2);
      */
     push(value: T): void;
+    error(error: unknown): void;
     /**
      * Closes the queue, preventing more elements from being pushed onto it.
      *

package/util/AsyncQueue.js

@@ -19,7 +19,7 @@ export class AsyncQueue {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: []
+            value: Array()
         });
         Object.defineProperty(this, "pendingResolvers", {
             enumerable: true,
@@ -34,6 +34,11 @@ export class AsyncQueue {
             value: false
         });
     }
+    processPendingResolvers() {
+        while (this.pendingResolvers.length > 0) {
+            this.pendingResolvers.shift()?.();
+        }
+    }
     /**
      * Pushes an element onto the queue. If the queue is closed, an error is thrown.
      *
@@ -44,12 +49,17 @@ export class AsyncQueue {
      */
     push(value) {
         if (this.closed) {
-            throw new Error("Cannot push value to closed queue. The queue has been closed and is no longer accepting new items.");
+            throw new Error("Cannot push value to closed queue.");
         }
-        this.values.push(value);
-        while (this.pendingResolvers.length > 0) {
-            this.pendingResolvers.shift()?.();
+        this.values.push({ type: "value", value });
+        this.processPendingResolvers();
+    }
+    error(error) {
+        if (this.closed) {
+            throw new Error("Cannot push error to closed queue.");
         }
+        this.values.push({ type: "error", error });
+        this.processPendingResolvers();
     }
     /**
      * Closes the queue, preventing more elements from being pushed onto it.
@@ -59,9 +69,7 @@ export class AsyncQueue {
      */
     close() {
         this.closed = true;
-        while (this.pendingResolvers.length > 0) {
-            this.pendingResolvers.shift()?.();
-        }
+        this.processPendingResolvers();
     }
     /**
      * Creates and returns an async iterator that allows the queue to be consumed.
@@ -78,11 +86,18 @@ export class AsyncQueue {
     [Symbol.asyncIterator]() {
         let position = 0;
         return {
-            next: () => new Promise((resolve) => {
+            next: () => new Promise((resolve, reject) => {
                 const attemptResolve = () => {
                     if (position < this.values.length) {
-                        // There's an available value, resolve it immediately.
-                        resolve({ value: this.values[position++], done: false });
+                        const entry = this.values[position++];
+                        switch (entry.type) {
+                            case "value":
+                                resolve({ value: entry.value, done: false });
+                                break;
+                            case "error":
+                                reject(entry.error);
+                                break;
+                        }
                     }
                     else if (this.closed) {
                         // The queue is closed, and there are no more values. Complete the iteration.

package/util/AsyncQueue.test.cjs

@@ -134,5 +134,5 @@ const AsyncQueue_js_1 = require("./AsyncQueue.cjs");
 (0, vitest_1.test)("throw error when pushing to a closed queue", async () => {
     const asyncQueue = new AsyncQueue_js_1.AsyncQueue();
     asyncQueue.close();
-    (0, vitest_1.expect)(() => asyncQueue.push(1)).toThrowError("Cannot push value to closed queue. The queue has been closed and is no longer accepting new items.");
+    (0, vitest_1.expect)(() => asyncQueue.push(1)).toThrowError("Cannot push value to closed queue.");
 });

package/util/AsyncQueue.test.js

@@ -132,5 +132,5 @@ test("each consumer receives all pushed values under varying conditions", async
 test("throw error when pushing to a closed queue", async () => {
     const asyncQueue = new AsyncQueue();
     asyncQueue.close();
-    expect(() => asyncQueue.push(1)).toThrowError("Cannot push value to closed queue. The queue has been closed and is no longer accepting new items.");
+    expect(() => asyncQueue.push(1)).toThrowError("Cannot push value to closed queue.");
 });

package/util/delay.cjs

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.delay = void 0;
-async function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+async function delay(delayInMs) {
+    return new Promise((resolve) => setTimeout(resolve, delayInMs));
 }
 exports.delay = delay;

package/util/delay.d.ts

@@ -1 +1 @@
-export declare function delay(ms: number): Promise<void>;
+export declare function delay(delayInMs: number): Promise<void>;

package/util/delay.js

@@ -1,3 +1,3 @@
-export async function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+export async function delay(delayInMs) {
+    return new Promise((resolve) => setTimeout(resolve, delayInMs));
 }

package/util/index.cjs

@@ -17,5 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./AsyncQueue.cjs"), exports);
 __exportStar(require("./JSONParseError.cjs"), exports);
 __exportStar(require("./cosineSimilarity.cjs"), exports);
+__exportStar(require("./delay.cjs"), exports);
 __exportStar(require("./getAudioFileExtension.cjs"), exports);
 __exportStar(require("./parseJSON.cjs"), exports);

package/util/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./AsyncQueue.js";
 export * from "./JSONParseError.js";
 export * from "./cosineSimilarity.js";
+export * from "./delay.js";
 export * from "./getAudioFileExtension.js";
 export * from "./parseJSON.js";

package/util/index.js

@@ -1,5 +1,6 @@
 export * from "./AsyncQueue.js";
 export * from "./JSONParseError.js";
 export * from "./cosineSimilarity.js";
+export * from "./delay.js";
 export * from "./getAudioFileExtension.js";
 export * from "./parseJSON.js";