modelfusion 0.102.0 → 0.104.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## v0.104.0 - 2023-12-24
+
+### Changed
+
+- **breaking change**: Unified text and multimodal prompt templates. `[Text/MultiModal]InstructionPrompt` is now `InstructionPrompt`, and `[Text/MultiModalChatPrompt]` is now `ChatPrompt`.
+- More flexible chat prompts: The chat prompt validation is now chat template specific and validated at runtime. E.g. the Llama2 prompt template only supports turns of user and assistant messages, whereas other formats are more flexible.
+
+## v0.103.0 - 2023-12-23
+
+### Added
+
+- `finishReason` support for `generateText`.
+
+  The finish reason can be `stop` (the model stopped because it generated a stop sequence), `length` (the model stopped because it generated the maximum number of tokens), `content-filter` (the model stopped because the content filter detected a violation), `tool-calls` (the model stopped because it triggered a tool call), `error` (the model stopped because of an error), `other` (the model stopped for another reason), or `unknown` (the model stop reason is not know or the model does not support finish reasons).
+
+  You can extract it from the full response when using `fullResponse: true`:
+
+  ```ts
+  const { text, finishReason } = await generateText(
+    openai
+      .ChatTextGenerator({ model: "gpt-3.5-turbo", maxGenerationTokens: 200 })
+      .withTextPrompt(),
+    "Write a short story about a robot learning to love:",
+    { fullResponse: true }
+  );
+  ```
+
 ## v0.102.0 - 2023-12-22
 
 ### Added

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

@@ -19,7 +19,7 @@ export declare class PromptTemplateTextGenerationModel<PROMPT, MODEL_PROMPT, SET
     get countPromptTokens(): MODEL["countPromptTokens"] extends undefined ? undefined : (prompt: PROMPT) => PromiseLike<number>;
     doGenerateTexts(prompt: PROMPT, options?: FunctionOptions): PromiseLike<{
         response: unknown;
-        texts: string[];
+        textGenerationResults: import("./TextGenerationResult.js").TextGenerationResult[];
         usage?: {
             promptTokens: number;
             completionTokens: number;

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

@@ -1,2 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.textGenerationModelProperties = void 0;
+exports.textGenerationModelProperties = [
+    "maxGenerationTokens",
+    "stopSequences",
+    "numberOfGenerations",
+    "trimWhitespace",
+];

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

@@ -3,6 +3,8 @@ import { Delta } from "../Delta.js";
 import { Model, ModelSettings } from "../Model.js";
 import { BasicTokenizer, FullTokenizer } from "../tokenize-text/Tokenizer.js";
 import { TextGenerationPromptTemplate } from "./TextGenerationPromptTemplate.js";
+import { TextGenerationResult } from "./TextGenerationResult.js";
+export declare const textGenerationModelProperties: readonly ["maxGenerationTokens", "stopSequences", "numberOfGenerations", "trimWhitespace"];
 export interface TextGenerationModelSettings extends ModelSettings {
     /**
      * Specifies the maximum number of tokens (words, punctuation, parts of words) that the model can generate in a single response.
@@ -62,7 +64,7 @@ export interface TextGenerationModel<PROMPT, SETTINGS extends TextGenerationMode
     readonly countPromptTokens: ((prompt: PROMPT) => PromiseLike<number>) | undefined;
     doGenerateTexts(prompt: PROMPT, options?: FunctionOptions): PromiseLike<{
         response: unknown;
-        texts: string[];
+        textGenerationResults: TextGenerationResult[];
         usage?: {
             promptTokens: number;
             completionTokens: number;

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

@@ -1 +1,6 @@
-export {};
+export const textGenerationModelProperties = [
+    "maxGenerationTokens",
+    "stopSequences",
+    "numberOfGenerations",
+    "trimWhitespace",
+];

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,11 @@
+export type TextGenerationResult = {
+    /**
+     * The generated text.
+     */
+    text: string;
+    /**
+     * The reason why the generation stopped.
+     */
+    finishReason: TextGenerationFinishReason;
+};
+export type TextGenerationFinishReason = "stop" | "length" | "content-filter" | "tool-calls" | "error" | "other" | "unknown";

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

@@ -0,0 +1 @@
+export {};

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

@@ -11,25 +11,30 @@ async function generateText(model, prompt, options) {
         generateResponse: async (options) => {
             const result = await model.doGenerateTexts(prompt, options);
             const shouldTrimWhitespace = model.settings.trimWhitespace ?? true;
-            const texts = shouldTrimWhitespace
-                ? result.texts.map((text) => text.trim())
-                : result.texts;
+            const textGenerationResults = shouldTrimWhitespace
+                ? result.textGenerationResults.map((textGeneration) => ({
+                    text: textGeneration.text.trim(),
+                    finishReason: textGeneration.finishReason,
+                }))
+                : result.textGenerationResults;
             return {
                 response: result.response,
-                extractedValue: texts,
+                extractedValue: textGenerationResults,
                 usage: result.usage,
             };
         },
     });
-    const texts = fullResponse.value;
-    const text = texts[0];
+    const textGenerationResults = fullResponse.value;
+    const firstResult = textGenerationResults[0];
     return options?.fullResponse
         ? {
-            text,
-            texts,
+            text: firstResult.text,
+            finishReason: firstResult.finishReason,
+            texts: textGenerationResults.map((textGeneration) => textGeneration.text),
+            textGenerationResults,
             response: fullResponse.response,
             metadata: fullResponse.metadata,
         }
-        : text;
+        : firstResult.text;
 }
 exports.generateText = generateText;

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

@@ -1,6 +1,7 @@
 import { FunctionOptions } from "../../core/FunctionOptions.js";
 import { ModelCallMetadata } from "../ModelCallMetadata.js";
 import { TextGenerationModel, TextGenerationModelSettings } from "./TextGenerationModel.js";
+import { TextGenerationFinishReason, TextGenerationResult } from "./TextGenerationResult.js";
 /**
  * Generate text for a prompt and return it as a string.
  *
@@ -29,7 +30,9 @@ export declare function generateText<PROMPT>(model: TextGenerationModel<PROMPT,
     fullResponse: true;
 }): Promise<{
     text: string;
+    finishReason: TextGenerationFinishReason;
     texts: string[];
+    textGenerationResults: TextGenerationResult[];
     response: unknown;
     metadata: ModelCallMetadata;
 }>;

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

@@ -8,24 +8,29 @@ export async function generateText(model, prompt, options) {
         generateResponse: async (options) => {
             const result = await model.doGenerateTexts(prompt, options);
             const shouldTrimWhitespace = model.settings.trimWhitespace ?? true;
-            const texts = shouldTrimWhitespace
-                ? result.texts.map((text) => text.trim())
-                : result.texts;
+            const textGenerationResults = shouldTrimWhitespace
+                ? result.textGenerationResults.map((textGeneration) => ({
+                    text: textGeneration.text.trim(),
+                    finishReason: textGeneration.finishReason,
+                }))
+                : result.textGenerationResults;
             return {
                 response: result.response,
-                extractedValue: texts,
+                extractedValue: textGenerationResults,
                 usage: result.usage,
             };
         },
     });
-    const texts = fullResponse.value;
-    const text = texts[0];
+    const textGenerationResults = fullResponse.value;
+    const firstResult = textGenerationResults[0];
     return options?.fullResponse
         ? {
-            text,
-            texts,
+            text: firstResult.text,
+            finishReason: firstResult.finishReason,
+            texts: textGenerationResults.map((textGeneration) => textGeneration.text),
+            textGenerationResults,
             response: fullResponse.response,
             metadata: fullResponse.metadata,
         }
-        : text;
+        : firstResult.text;
 }

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

@@ -19,6 +19,7 @@ __exportStar(require("./PromptTemplateTextStreamingModel.cjs"), exports);
 __exportStar(require("./TextGenerationEvent.cjs"), exports);
 __exportStar(require("./TextGenerationModel.cjs"), exports);
 __exportStar(require("./TextGenerationPromptTemplate.cjs"), exports);
+__exportStar(require("./TextGenerationResult.cjs"), exports);
 __exportStar(require("./generateText.cjs"), exports);
 __exportStar(require("./prompt-template/index.cjs"), exports);
 __exportStar(require("./streamText.cjs"), exports);

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

@@ -3,6 +3,7 @@ export * from "./PromptTemplateTextStreamingModel.js";
 export * from "./TextGenerationEvent.js";
 export * from "./TextGenerationModel.js";
 export * from "./TextGenerationPromptTemplate.js";
+export * from "./TextGenerationResult.js";
 export * from "./generateText.js";
 export * from "./prompt-template/index.js";
 export * from "./streamText.js";

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

@@ -3,6 +3,7 @@ export * from "./PromptTemplateTextStreamingModel.js";
 export * from "./TextGenerationEvent.js";
 export * from "./TextGenerationModel.js";
 export * from "./TextGenerationPromptTemplate.js";
+export * from "./TextGenerationResult.js";
 export * from "./generateText.js";
 export * from "./prompt-template/index.js";
 export * from "./streamText.js";

package/model-function/generate-text/prompt-template/AlpacaPromptTemplate.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.instruction = exports.text = void 0;
+const Content_js_1 = require("./Content.cjs");
 const DEFAULT_SYSTEM_PROMPT_INPUT = "Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.";
 const DEFAULT_SYSTEM_PROMPT_NO_INPUT = "Below is an instruction that describes a task. Write a response that appropriately completes the request.";
 /**
@@ -67,7 +68,7 @@ function instruction() {
             if (prompt.system != null) {
                 text += `${prompt.system}\n`;
             }
-            text += prompt.instruction;
+            text += (0, Content_js_1.validateContentIsString)(prompt.instruction, prompt);
             if (prompt.input != null) {
                 text += `\n\n### Input:\n${prompt.input}`;
             }

package/model-function/generate-text/prompt-template/AlpacaPromptTemplate.d.ts

@@ -1,5 +1,5 @@
 import { TextGenerationPromptTemplate } from "../TextGenerationPromptTemplate.js";
-import { TextInstructionPrompt } from "./InstructionPrompt.js";
+import { InstructionPrompt } from "./InstructionPrompt.js";
 /**
  * Formats a text prompt as an Alpaca prompt.
  */
@@ -40,7 +40,7 @@ export declare function text(): TextGenerationPromptTemplate<string, string>;
  *
  * @see https://github.com/tatsu-lab/stanford_alpaca#data-release
  */
-export declare function instruction(): TextGenerationPromptTemplate<TextInstructionPrompt & {
+export declare function instruction(): TextGenerationPromptTemplate<InstructionPrompt & {
     input?: string;
 }, // optional input supported by Alpaca
 string>;

package/model-function/generate-text/prompt-template/AlpacaPromptTemplate.js

@@ -1,3 +1,4 @@
+import { validateContentIsString } from "./Content.js";
 const DEFAULT_SYSTEM_PROMPT_INPUT = "Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.";
 const DEFAULT_SYSTEM_PROMPT_NO_INPUT = "Below is an instruction that describes a task. Write a response that appropriately completes the request.";
 /**
@@ -63,7 +64,7 @@ export function instruction() {
             if (prompt.system != null) {
                 text += `${prompt.system}\n`;
             }
-            text += prompt.instruction;
+            text += validateContentIsString(prompt.instruction, prompt);
             if (prompt.input != null) {
                 text += `\n\n### Input:\n${prompt.input}`;
             }

package/model-function/generate-text/prompt-template/ChatMLPromptTemplate.cjs

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.chat = exports.instruction = exports.text = void 0;
-const ChatPrompt_js_1 = require("./ChatPrompt.cjs");
+const Content_js_1 = require("./Content.cjs");
 const START_SEGMENT = "<|im_start|>";
 const END_SEGMENT = "<|im_end|>";
 function segmentStart(role) {
@@ -40,8 +40,9 @@ function instruction() {
     return {
         stopSequences: [END_SEGMENT],
         format(prompt) {
+            const instruction = (0, Content_js_1.validateContentIsString)(prompt.instruction, prompt);
             return (segment("system", prompt.system) +
-                segment("user", prompt.instruction) +
+                segment("user", instruction) +
                 segmentStart("assistant") +
                 (prompt.responsePrefix ?? ""));
         },
@@ -64,12 +65,12 @@ exports.instruction = instruction;
 function chat() {
     return {
         format(prompt) {
-            (0, ChatPrompt_js_1.validateChatPrompt)(prompt);
             let text = prompt.system != null ? segment("system", prompt.system) : "";
             for (const { role, content } of prompt.messages) {
                 switch (role) {
                     case "user": {
-                        text += segment("user", content);
+                        const textContent = (0, Content_js_1.validateContentIsString)(content, prompt);
+                        text += segment("user", textContent);
                         break;
                     }
                     case "assistant": {

package/model-function/generate-text/prompt-template/ChatMLPromptTemplate.d.ts

@@ -1,6 +1,6 @@
 import { TextGenerationPromptTemplate } from "../TextGenerationPromptTemplate.js";
-import { TextChatPrompt } from "./ChatPrompt.js";
-import { TextInstructionPrompt } from "./InstructionPrompt.js";
+import { ChatPrompt } from "./ChatPrompt.js";
+import { InstructionPrompt } from "./InstructionPrompt.js";
 /**
  * Formats a text prompt using the ChatML format.
  */
@@ -18,7 +18,7 @@ export declare function text(): TextGenerationPromptTemplate<string, string>;
  * ${response prefix}
  * ```
  */
-export declare function instruction(): TextGenerationPromptTemplate<TextInstructionPrompt, string>;
+export declare function instruction(): TextGenerationPromptTemplate<InstructionPrompt, string>;
 /**
  * Formats a chat prompt using the ChatML format.
  *
@@ -32,4 +32,4 @@ export declare function instruction(): TextGenerationPromptTemplate<TextInstruct
  * Paris<|im_end|>
  * ```
  */
-export declare function chat(): TextGenerationPromptTemplate<TextChatPrompt, string>;
+export declare function chat(): TextGenerationPromptTemplate<ChatPrompt, string>;

package/model-function/generate-text/prompt-template/ChatMLPromptTemplate.js

@@ -1,4 +1,4 @@
-import { validateChatPrompt } from "./ChatPrompt.js";
+import { validateContentIsString } from "./Content.js";
 const START_SEGMENT = "<|im_start|>";
 const END_SEGMENT = "<|im_end|>";
 function segmentStart(role) {
@@ -36,8 +36,9 @@ export function instruction() {
     return {
         stopSequences: [END_SEGMENT],
         format(prompt) {
+            const instruction = validateContentIsString(prompt.instruction, prompt);
             return (segment("system", prompt.system) +
-                segment("user", prompt.instruction) +
+                segment("user", instruction) +
                 segmentStart("assistant") +
                 (prompt.responsePrefix ?? ""));
         },
@@ -59,12 +60,12 @@ export function instruction() {
 export function chat() {
     return {
         format(prompt) {
-            validateChatPrompt(prompt);
             let text = prompt.system != null ? segment("system", prompt.system) : "";
             for (const { role, content } of prompt.messages) {
                 switch (role) {
                     case "user": {
-                        text += segment("user", content);
+                        const textContent = validateContentIsString(content, prompt);
+                        text += segment("user", textContent);
                         break;
                     }
                     case "assistant": {

package/model-function/generate-text/prompt-template/ChatPrompt.cjs

@@ -1,26 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateChatPrompt = void 0;
-const InvalidPromptError_js_1 = require("./InvalidPromptError.cjs");
-/**
- * Checks if a chat prompt is valid. Throws a {@link ChatPromptValidationError} if it's not.
- *
- * @throws {@link ChatPromptValidationError}
- */
-function validateChatPrompt(chatPrompt) {
-    const messages = chatPrompt.messages;
-    if (messages.length < 1) {
-        throw new InvalidPromptError_js_1.InvalidPromptError("ChatPrompt should have at least one message.", chatPrompt);
-    }
-    for (let i = 0; i < messages.length; i++) {
-        const expectedRole = i % 2 === 0 ? "user" : "assistant";
-        const role = messages[i].role;
-        if (role !== expectedRole) {
-            throw new InvalidPromptError_js_1.InvalidPromptError(`Message at index ${i} should have role '${expectedRole}', but has role '${role}'.`, chatPrompt);
-        }
-    }
-    if (messages.length % 2 === 0) {
-        throw new InvalidPromptError_js_1.InvalidPromptError("The last message must be a user message.", chatPrompt);
-    }
-}
-exports.validateChatPrompt = validateChatPrompt;

package/model-function/generate-text/prompt-template/ChatPrompt.d.ts

@@ -1,15 +1,10 @@
-import { MultiModalInput } from "./Content.js";
+import { Content } from "./Content.js";
 /**
- * A textual chat prompt is a combination of a system message and a list of messages with the following constraints:
+ * A chat prompt is a combination of a system message and a list of user and assistant messages.
  *
- * - A chat prompt can optionally have a system message.
- * - The first message of the chat must be a user message.
- * - Then it must be alternating between an assistant message and a user message.
- * - The last message must always be a user message (when submitting to a model).
+ * The user messages can contain multi-modal content.
  *
- * You can use a ChatPrompt without an final user message when you e.g. want to display the current state of a conversation.
- *
- * The type checking is done at runtime when you submit a chat prompt to a model with a prompt template.
+ * Note: Not all models and prompt formats support multi-modal inputs.
  *
  * @example
  * ```ts
@@ -22,38 +17,20 @@ import { MultiModalInput } from "./Content.js";
  *  ],
  * };
  * ```
- *
- * @see validateChatPrompt
  */
-export interface TextChatPrompt {
+export interface ChatPrompt {
     system?: string;
-    messages: Array<TextChatMessage>;
+    messages: Array<ChatMessage>;
 }
 /**
- * A text message in a chat prompt.
- * @see TextChatPrompt
+ * A message in a chat prompt.
+ *
+ * @see ChatPrompt
  */
-export type TextChatMessage = {
-    role: "user";
-    content: string;
-} | {
-    role: "assistant";
-    content: string;
-};
-export interface MultiModalChatPrompt {
-    system?: string;
-    messages: Array<MultiModalChatMessage>;
-}
-export type MultiModalChatMessage = {
+export type ChatMessage = {
     role: "user";
-    content: MultiModalInput;
+    content: Content;
 } | {
     role: "assistant";
     content: string;
 };
-/**
- * Checks if a chat prompt is valid. Throws a {@link ChatPromptValidationError} if it's not.
- *
- * @throws {@link ChatPromptValidationError}
- */
-export declare function validateChatPrompt(chatPrompt: TextChatPrompt | MultiModalChatPrompt): void;

package/model-function/generate-text/prompt-template/ChatPrompt.js

@@ -1,22 +1 @@
-import { InvalidPromptError } from "./InvalidPromptError.js";
-/**
- * Checks if a chat prompt is valid. Throws a {@link ChatPromptValidationError} if it's not.
- *
- * @throws {@link ChatPromptValidationError}
- */
-export function validateChatPrompt(chatPrompt) {
-    const messages = chatPrompt.messages;
-    if (messages.length < 1) {
-        throw new InvalidPromptError("ChatPrompt should have at least one message.", chatPrompt);
-    }
-    for (let i = 0; i < messages.length; i++) {
-        const expectedRole = i % 2 === 0 ? "user" : "assistant";
-        const role = messages[i].role;
-        if (role !== expectedRole) {
-            throw new InvalidPromptError(`Message at index ${i} should have role '${expectedRole}', but has role '${role}'.`, chatPrompt);
-        }
-    }
-    if (messages.length % 2 === 0) {
-        throw new InvalidPromptError("The last message must be a user message.", chatPrompt);
-    }
-}
+export {};

package/model-function/generate-text/prompt-template/Content.cjs

@@ -1,2 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateContentIsString = void 0;
+const InvalidPromptError_js_1 = require("./InvalidPromptError.cjs");
+function validateContentIsString(content, prompt) {
+    if (typeof content !== "string") {
+        throw new InvalidPromptError_js_1.InvalidPromptError("only text prompts are are supported by this prompt template", prompt);
+    }
+    return content;
+}
+exports.validateContentIsString = validateContentIsString;

package/model-function/generate-text/prompt-template/Content.d.ts

@@ -1,13 +1,17 @@
-export type MultiModalInput = Array<Content>;
-export type Content = TextContent | ImageContent;
-export interface TextContent {
+/**
+ * Content can either be a simple text content (`string`) or a
+ * complex multi-modal content that is a mix of text parts and
+ * image parts.
+ */
+export type Content = string | Array<TextPart | ImagePart>;
+export interface TextPart {
     type: "text";
     /**
      * The text content.
      */
     text: string;
 }
-export interface ImageContent {
+export interface ImagePart {
     type: "image";
     /**
      * Base-64 encoded image.
@@ -18,3 +22,4 @@ export interface ImageContent {
      */
     mimeType?: string;
 }
+export declare function validateContentIsString(content: Content, prompt: unknown): string;

package/model-function/generate-text/prompt-template/Content.js

@@ -1 +1,7 @@
-export {};
+import { InvalidPromptError } from "./InvalidPromptError.js";
+export function validateContentIsString(content, prompt) {
+    if (typeof content !== "string") {
+        throw new InvalidPromptError("only text prompts are are supported by this prompt template", prompt);
+    }
+    return content;
+}

package/model-function/generate-text/prompt-template/InstructionPrompt.d.ts

@@ -1,24 +1,10 @@
-import { MultiModalInput } from "./Content.js";
-/**
- * A single multi-modal instruction prompt. It can contain an optional system message to define
- * the role and behavior of the language model.
- * The instruction is a multi-model input (`array` of content).
- */
-export interface MultiModalInstructionPrompt {
-    /**
-     * Optional system message to provide context for the language model. Note that for some models,
-     * changing the system message can impact the results, because the model may be trained on the default system message.
-     */
-    system?: string;
-    /**
-     * The multi-modal instruction for the model.
-     */
-    instruction: MultiModalInput;
-}
+import { Content } from "./Content.js";
 /**
  * A single text instruction prompt. It can contain an optional system message to define
  * the role and behavior of the language model.
  *
+ * The instruction can be a text instruction or a multi-modal instruction.
+ *
  * @example
  * ```ts
  * {
@@ -27,21 +13,19 @@ export interface MultiModalInstructionPrompt {
  * }
  * ```
  */
-export interface TextInstructionPrompt {
+export interface InstructionPrompt {
     /**
      * Optional system message to provide context for the language model. Note that for some models,
      * changing the system message can impact the results, because the model may be trained on the default system message.
      */
     system?: string;
     /**
-     * The text instruction for the model.
+     * The instruction for the model.
      */
-    instruction: string;
+    instruction: Content;
     /**
      * Response prefix that will be injected in the prompt at the beginning of the response.
      * This is useful for guiding the model by starting its response with a specific text.
-     *
-     * Note: Not all models support this feature. E.g. it is not supported by OpenAI chat models.
      */
     responsePrefix?: string;
 }