modelfusion 0.130.1 → 0.131.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## v0.131.0 - 2024-01-23
+
+### Added
+
+- `ObjectStreamResponse` and `ObjectStreamFromResponse` serialization functions for using server-generated object streams in web applications.
+
+  Server example:
+
+  ```ts
+  export async function POST(req: Request) {
+    const { myArgs } = await req.json();
+
+    const objectStream = await streamObject({
+      // ...
+    });
+
+    // serialize the object stream to a response:
+    return new ObjectStreamResponse(objectStream);
+  }
+  ```
+
+  Client example:
+
+  ```ts
+  const response = await fetch("/api/stream-object-openai", {
+    method: "POST",
+    body: JSON.stringify({ myArgs }),
+  });
+
+  // deserialize (result object is simpler than the full response)
+  const stream = ObjectStreamFromResponse({
+    schema: itinerarySchema,
+    response,
+  });
+
+  for await (const { partialObject } of stream) {
+    // do something, e.g. setting a React state
+  }
+  ```
+
+### Changed
+
+- **breaking change**: rename `generateStructure` to `generateObject` and `streamStructure` to `streamObject`. Related names have been changed accordingly.
+- **breaking change**: the `streamObject` result stream contains additional data. You need to use `stream.partialObject` or destructuring to access it:
+
+  ```ts
+  const objectStream = await streamObject({
+    // ...
+  });
+
+  for await (const { partialObject } of objectStream) {
+    console.clear();
+    console.log(partialObject);
+  }
+  ```
+
+- **breaking change**: the result from successful `Schema` validations is stored in the `value` property (before: `data`).
+
 ## v0.130.1 - 2024-01-22
 
 ### Fixed

package/README.md

@@ -12,7 +12,7 @@
 
 ## Introduction
 
-**ModelFusion** is an abstraction layer for integrating AI models into JavaScript and TypeScript applications, unifying the API for common operations such as **text streaming**, **structure generation**, and **tool usage**. It provides features to support production environments, including observability hooks, logging, and automatic retries. You can use ModelFusion to build AI applications, chatbots, and agents.
+**ModelFusion** is an abstraction layer for integrating AI models into JavaScript and TypeScript applications, unifying the API for common operations such as **text streaming**, **object generation**, and **tool usage**. It provides features to support production environments, including observability hooks, logging, and automatic retries. You can use ModelFusion to build AI applications, chatbots, and agents.
 
 - **Vendor-neutral**: ModelFusion is a non-commercial open source project that is community-driven. You can use it with any supported provider.
 - **Multi-modal**: ModelFusion supports a wide range of models including text generation, image generation, vision, text-to-speech, speech-to-text, and embedding models.
@@ -108,30 +108,30 @@ for await (const textPart of textStream) {
 
 Providers: [OpenAI](https://modelfusion.dev/integration/model-provider/openai), [OpenAI compatible](https://modelfusion.dev/integration/model-provider/openaicompatible), [Llama.cpp](https://modelfusion.dev/integration/model-provider/llamacpp), [Ollama](https://modelfusion.dev/integration/model-provider/ollama)
 
-### [Generate Structure](https://modelfusion.dev/guide/function/generate-structure)
+### [Generate Object](https://modelfusion.dev/guide/function/generate-object)
 
 Generate typed objects using a language model and a schema.
 
-#### generateStructure
+#### generateObject
 
-Generate a structure that matches a schema.
+Generate an object that matches a schema.
 
 ```ts
 import {
   ollama,
   zodSchema,
-  generateStructure,
-  jsonStructurePrompt,
+  generateObject,
+  jsonObjectPrompt,
 } from "modelfusion";
 
-const sentiment = await generateStructure({
+const sentiment = await generateObject({
   model: ollama
     .ChatTextGenerator({
       model: "openhermes2.5-mistral",
       maxGenerationTokens: 1024,
       temperature: 0,
     })
-    .asStructureGenerationModel(jsonStructurePrompt.instruction()),
+    .asObjectGenerationModel(jsonObjectPrompt.instruction()),
 
   schema: zodSchema(
     z.object({
@@ -154,17 +154,17 @@ const sentiment = await generateStructure({
 
 Providers: [OpenAI](https://modelfusion.dev/integration/model-provider/openai), [Ollama](https://modelfusion.dev//integration/model-provider/ollama), [Llama.cpp](https://modelfusion.dev//integration/model-provider/llama.cpp)
 
-#### streamStructure
+#### streamObject
 
-Stream a structure that matches a schema. Partial structures before the final part are untyped JSON.
+Stream a object that matches a schema. Partial objects before the final part are untyped JSON.
 
 ```ts
-import { zodSchema, openai, streamStructure } from "modelfusion";
+import { zodSchema, openai, streamObject } from "modelfusion";
 
-const structureStream = await streamStructure({
+const objectStream = await streamObject({
   model: openai
     .ChatTextGenerator(/* ... */)
-    .asFunctionCallStructureGenerationModel({
+    .asFunctionCallObjectGenerationModel({
       fnName: "generateCharacter",
       fnDescription: "Generate character descriptions.",
     })
@@ -187,9 +187,9 @@ const structureStream = await streamStructure({
   prompt: "Generate 3 character descriptions for a fantasy role playing game.",
 });
 
-for await (const partialStructure of structureStream) {
+for await (const { partialObject } of objectStream) {
   console.clear();
-  console.log(partialStructure);
+  console.log(partialObject);
 }
 ```
 
@@ -575,7 +575,7 @@ const text = await generateText({
 
 - [Model Functions](https://modelfusion.dev/guide/function/)
   - [Generate text](https://modelfusion.dev/guide/function/generate-text)
-  - [Generate structure](https://modelfusion.dev/guide/function/generate-structure)
+  - [Generate object](https://modelfusion.dev/guide/function/generate-object)
   - [Generate image](https://modelfusion.dev/guide/function/generate-image)
   - [Generate speech](https://modelfusion.dev/guide/function/generate-speech)
   - [Generate transcription](https://modelfusion.dev/guide/function/generation-transcription)
@@ -627,7 +627,7 @@ Examples for almost all of the individual functions and objects. Highly recommen
 
 ### [StoryTeller](https://github.com/lgrammel/storyteller)
 
-> _multi-modal_, _structure streaming_, _image generation_, _text to speech_, _speech to text_, _text generation_, _structure generation_, _embeddings_
+> _multi-modal_, _object streaming_, _image generation_, _text to speech_, _speech to text_, _text generation_, _object generation_, _embeddings_
 
 StoryTeller is an exploratory web application that creates short audio stories for pre-school kids.
 
@@ -645,13 +645,13 @@ Ask questions about a PDF document and get answers from the document.
 
 ### [Next.js / ModelFusion Demos](https://github.com/lgrammel/modelfusion/tree/main/examples/nextjs)
 
-> _Next.js app_, _image generation_, _transcription_, _structure streaming_, _OpenAI_, _Stability AI_, _Ollama_
+> _Next.js app_, _image generation_, _transcription_, _object streaming_, _OpenAI_, _Stability AI_, _Ollama_
 
 Examples of using ModelFusion with Next.js 14 (App Router):
 
 - image generation
 - voice recording & transcription
-- structure streaming (client-side)
+- object streaming
 
 ### [Duplex Speech Streaming (using Vite/React & ModelFusion Server/Fastify)](https://github.com/lgrammel/modelfusion/tree/main/examples/speech-streaming-vite-react-fastify)
 

package/core/api/postToApi.cjs

@@ -73,7 +73,7 @@ const createJsonResponseHandler = (responseSchema) => async ({ response, url, re
             requestBodyValues,
         });
     }
-    return parsedResult.data;
+    return parsedResult.value;
 };
 exports.createJsonResponseHandler = createJsonResponseHandler;
 const createTextResponseHandler = () => async ({ response }) => response.text();

package/core/api/postToApi.js

@@ -68,7 +68,7 @@ export const createJsonResponseHandler = (responseSchema) => async ({ response,
             requestBodyValues,
         });
     }
-    return parsedResult.data;
+    return parsedResult.value;
 };
 export const createTextResponseHandler = () => async ({ response }) => response.text();
 export const createAudioMpegResponseHandler = () => async ({ response, url, requestBodyValues }) => {

package/core/schema/JsonSchemaProducer.d.ts

@@ -1,5 +1,5 @@
 /**
- * Schema defines a structure for a JSON object.
+ * A schema defines the typed structure of a JSON object.
  */
 export interface JsonSchemaProducer {
     /**

package/core/schema/Schema.d.ts

@@ -1,14 +1,14 @@
 /**
- * Validates that the structure of `data` matches the structure of this schema.
+ * Validates that the structure of a value matches this schema.
  */
-export interface Schema<STRUCTURE> {
+export interface Schema<OBJECT> {
     /**
-     * Validates that the structure of `data` matches the structure of this schema,
-     * and returns a typed version of data if it does.
+     * Validates that the structure of a value matches this schema,
+     * and returns a typed version of the value if it does.
      */
-    validate(data: unknown): {
+    validate(value: unknown): {
         success: true;
-        data: STRUCTURE;
+        value: OBJECT;
     } | {
         success: false;
         error: unknown;
@@ -16,5 +16,5 @@ export interface Schema<STRUCTURE> {
     /**
      * Only used for type inference.
      */
-    readonly _type: STRUCTURE;
+    readonly _type: OBJECT;
 }

package/core/schema/TypeValidationError.cjs

@@ -3,11 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TypeValidationError = void 0;
 const getErrorMessage_js_1 = require("../../util/getErrorMessage.cjs");
 class TypeValidationError extends Error {
-    constructor({ structure, cause }) {
+    constructor({ value, cause }) {
         super(`Type validation failed: ` +
-            `Structure: ${JSON.stringify(structure)}.\n` +
+            `Value: ${JSON.stringify(value)}.\n` +
             `Error message: ${(0, getErrorMessage_js_1.getErrorMessage)(cause)}`);
-        Object.defineProperty(this, "structure", {
+        Object.defineProperty(this, "value", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -21,7 +21,7 @@ class TypeValidationError extends Error {
         });
         this.name = "TypeValidationError";
         this.cause = cause;
-        this.structure = structure;
+        this.value = value;
     }
     toJSON() {
         return {
@@ -29,7 +29,7 @@ class TypeValidationError extends Error {
             message: this.message,
             cause: this.cause,
             stack: this.stack,
-            object: this.structure,
+            value: this.value,
         };
     }
 }

package/core/schema/TypeValidationError.d.ts

@@ -1,8 +1,8 @@
 export declare class TypeValidationError extends Error {
-    readonly structure: unknown;
+    readonly value: unknown;
     readonly cause: unknown;
-    constructor({ structure, cause }: {
-        structure: unknown;
+    constructor({ value, cause }: {
+        value: unknown;
         cause: unknown;
     });
     toJSON(): {
@@ -10,6 +10,6 @@ export declare class TypeValidationError extends Error {
         message: string;
         cause: unknown;
         stack: string | undefined;
-        object: unknown;
+        value: unknown;
     };
 }

package/core/schema/TypeValidationError.js

@@ -1,10 +1,10 @@
 import { getErrorMessage } from "../../util/getErrorMessage.js";
 export class TypeValidationError extends Error {
-    constructor({ structure, cause }) {
+    constructor({ value, cause }) {
         super(`Type validation failed: ` +
-            `Structure: ${JSON.stringify(structure)}.\n` +
+            `Value: ${JSON.stringify(value)}.\n` +
             `Error message: ${getErrorMessage(cause)}`);
-        Object.defineProperty(this, "structure", {
+        Object.defineProperty(this, "value", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -18,7 +18,7 @@ export class TypeValidationError extends Error {
         });
         this.name = "TypeValidationError";
         this.cause = cause;
-        this.structure = structure;
+        this.value = value;
     }
     toJSON() {
         return {
@@ -26,7 +26,7 @@ export class TypeValidationError extends Error {
             message: this.message,
             cause: this.cause,
             stack: this.stack,
-            object: this.structure,
+            value: this.value,
         };
     }
 }

package/core/schema/UncheckedSchema.cjs

@@ -20,8 +20,8 @@ class UncheckedSchema {
             value: void 0
         });
     }
-    validate(data) {
-        return { success: true, data: data };
+    validate(value) {
+        return { success: true, value: value };
     }
     getJsonSchema() {
         return this.jsonSchema;

package/core/schema/UncheckedSchema.d.ts

@@ -1,16 +1,16 @@
 import { JsonSchemaProducer } from "./JsonSchemaProducer.js";
 import { Schema } from "./Schema.js";
-export declare function uncheckedSchema<STRUCTURE>(jsonSchema?: unknown): UncheckedSchema<STRUCTURE>;
-export declare class UncheckedSchema<STRUCTURE> implements Schema<STRUCTURE>, JsonSchemaProducer {
+export declare function uncheckedSchema<OBJECT>(jsonSchema?: unknown): UncheckedSchema<OBJECT>;
+export declare class UncheckedSchema<OBJECT> implements Schema<OBJECT>, JsonSchemaProducer {
     private readonly jsonSchema?;
     constructor(jsonSchema?: unknown);
-    validate(data: unknown): {
+    validate(value: unknown): {
         success: true;
-        data: STRUCTURE;
+        value: OBJECT;
     } | {
         success: false;
         error: unknown;
     };
     getJsonSchema(): unknown;
-    readonly _type: STRUCTURE;
+    readonly _type: OBJECT;
 }

package/core/schema/UncheckedSchema.js

@@ -16,8 +16,8 @@ export class UncheckedSchema {
             value: void 0
         });
     }
-    validate(data) {
-        return { success: true, data: data };
+    validate(value) {
+        return { success: true, value: value };
     }
     getJsonSchema() {
         return this.jsonSchema;

package/core/schema/ZodSchema.cjs

@@ -34,8 +34,11 @@ class ZodSchema {
         });
         this.zodSchema = zodSchema;
     }
-    validate(data) {
-        return this.zodSchema.safeParse(data);
+    validate(value) {
+        const result = this.zodSchema.safeParse(value);
+        return result.success
+            ? { success: true, value: result.data }
+            : { success: false, error: result.error };
     }
     getJsonSchema() {
         return (0, zod_to_json_schema_1.zodToJsonSchema)(this.zodSchema);

package/core/schema/ZodSchema.d.ts

@@ -2,13 +2,13 @@ import { z } from "zod";
 import { JsonSchemaProducer } from "./JsonSchemaProducer.js";
 import { Schema } from "./Schema.js";
 import { PartialDeep } from "type-fest";
-export declare function zodSchema<STRUCTURE>(zodSchema: z.Schema<STRUCTURE>): ZodSchema<STRUCTURE>;
-export declare class ZodSchema<STRUCTURE> implements Schema<STRUCTURE>, JsonSchemaProducer {
-    readonly zodSchema: z.Schema<STRUCTURE>;
-    constructor(zodSchema: z.Schema<STRUCTURE>);
-    validate(data: unknown): {
+export declare function zodSchema<OBJECT>(zodSchema: z.Schema<OBJECT>): ZodSchema<OBJECT>;
+export declare class ZodSchema<OBJECT> implements Schema<OBJECT>, JsonSchemaProducer {
+    readonly zodSchema: z.Schema<OBJECT>;
+    constructor(zodSchema: z.Schema<OBJECT>);
+    validate(value: unknown): {
         success: true;
-        data: STRUCTURE;
+        value: OBJECT;
     } | {
         success: false;
         error: unknown;
@@ -17,11 +17,11 @@ export declare class ZodSchema<STRUCTURE> implements Schema<STRUCTURE>, JsonSche
     /**
      * Use only for typing purposes. The value is always `undefined`.
      */
-    readonly _type: STRUCTURE;
+    readonly _type: OBJECT;
     /**
      * Use only for typing purposes. The value is always `undefined`.
      */
-    readonly _partialType: PartialDeep<STRUCTURE, {
+    readonly _partialType: PartialDeep<OBJECT, {
         recurseIntoArrays: true;
     }>;
 }

package/core/schema/ZodSchema.js

@@ -30,8 +30,11 @@ export class ZodSchema {
         });
         this.zodSchema = zodSchema;
     }
-    validate(data) {
-        return this.zodSchema.safeParse(data);
+    validate(value) {
+        const result = this.zodSchema.safeParse(value);
+        return result.success
+            ? { success: true, value: result.data }
+            : { success: false, error: result.error };
     }
     getJsonSchema() {
         return zodToJsonSchema(this.zodSchema);

package/core/schema/parseJSON.cjs

@@ -10,11 +10,11 @@ const validateTypes_js_1 = require("./validateTypes.cjs");
 const TypeValidationError_js_1 = require("./TypeValidationError.cjs");
 function parseJSON({ text, schema, }) {
     try {
-        const json = secure_json_parse_1.default.parse(text);
+        const value = secure_json_parse_1.default.parse(text);
         if (schema == null) {
-            return json;
+            return value;
         }
-        return (0, validateTypes_js_1.validateTypes)({ structure: json, schema });
+        return (0, validateTypes_js_1.validateTypes)({ value, schema });
     }
     catch (error) {
         if (error instanceof JSONParseError_js_1.JSONParseError ||
@@ -27,14 +27,14 @@ function parseJSON({ text, schema, }) {
 exports.parseJSON = parseJSON;
 function safeParseJSON({ text, schema, }) {
     try {
-        const json = secure_json_parse_1.default.parse(text);
+        const value = secure_json_parse_1.default.parse(text);
         if (schema == null) {
             return {
                 success: true,
-                data: json,
+                value: value,
             };
         }
-        return (0, validateTypes_js_1.safeValidateTypes)({ structure: json, schema });
+        return (0, validateTypes_js_1.safeValidateTypes)({ value, schema });
     }
     catch (error) {
         return {

package/core/schema/parseJSON.d.ts

@@ -32,13 +32,13 @@ export declare function safeParseJSON({ text, }: {
     text: string;
 }): {
     success: true;
-    data: unknown;
+    value: unknown;
 } | {
     success: false;
     error: JSONParseError | TypeValidationError;
 };
 /**
- * Safely parses a JSON string into a strongly-typed object, using a provided schema to validate the structure.
+ * Safely parses a JSON string into a strongly-typed object, using a provided schema to validate the object.
  *
  * @template T - The type of the object to parse the JSON into.
  * @param {string} text - The JSON string to parse.
@@ -50,7 +50,7 @@ export declare function safeParseJSON<T>({ text, schema, }: {
     schema: Schema<T>;
 }): {
     success: true;
-    data: T;
+    value: T;
 } | {
     success: false;
     error: JSONParseError | TypeValidationError;

package/core/schema/parseJSON.js

@@ -4,11 +4,11 @@ import { safeValidateTypes, validateTypes } from "./validateTypes.js";
 import { TypeValidationError } from "./TypeValidationError.js";
 export function parseJSON({ text, schema, }) {
     try {
-        const json = SecureJSON.parse(text);
+        const value = SecureJSON.parse(text);
         if (schema == null) {
-            return json;
+            return value;
         }
-        return validateTypes({ structure: json, schema });
+        return validateTypes({ value, schema });
     }
     catch (error) {
         if (error instanceof JSONParseError ||
@@ -20,14 +20,14 @@ export function parseJSON({ text, schema, }) {
 }
 export function safeParseJSON({ text, schema, }) {
     try {
-        const json = SecureJSON.parse(text);
+        const value = SecureJSON.parse(text);
         if (schema == null) {
             return {
                 success: true,
-                data: json,
+                value: value,
             };
         }
-        return safeValidateTypes({ structure: json, schema });
+        return safeValidateTypes({ value, schema });
     }
     catch (error) {
         return {

package/core/schema/validateTypes.cjs

@@ -7,26 +7,26 @@ const TypeValidationError_js_1 = require("./TypeValidationError.cjs");
  * return a strongly-typed object.
  *
  * @template T - The type of the object to validate.
- * @param {string} structure - The JSON structure to validate.
- * @param {Schema<T>} schema - The schema to use for validating the JSON.
+ * @param {string} options.value - The object to validate.
+ * @param {Schema<T>} options.schema - The schema to use for validating the JSON.
  * @returns {T} - The typed object.
  */
-function validateTypes({ structure, schema, }) {
+function validateTypes({ value, schema, }) {
     try {
-        const validationResult = schema.validate(structure);
+        const validationResult = schema.validate(value);
         if (!validationResult.success) {
             throw new TypeValidationError_js_1.TypeValidationError({
-                structure,
+                value,
                 cause: validationResult.error,
             });
         }
-        return validationResult.data;
+        return validationResult.value;
     }
     catch (error) {
         if (error instanceof TypeValidationError_js_1.TypeValidationError) {
             throw error;
         }
-        throw new TypeValidationError_js_1.TypeValidationError({ structure: structure, cause: error });
+        throw new TypeValidationError_js_1.TypeValidationError({ value, cause: error });
     }
 }
 exports.validateTypes = validateTypes;
@@ -35,20 +35,20 @@ exports.validateTypes = validateTypes;
  * return a strongly-typed object.
  *
  * @template T - The type of the object to validate.
- * @param {string} structure - The JSON object to validate.
- * @param {Schema<T>} schema - The schema to use for validating the JSON.
+ * @param {string} options.value - The JSON object to validate.
+ * @param {Schema<T>} options.schema - The schema to use for validating the JSON.
  * @returns An object with either a `success` flag and the parsed and typed data, or a `success` flag and an error object.
  */
-function safeValidateTypes({ structure, schema, }) {
+function safeValidateTypes({ value, schema, }) {
     try {
-        const validationResult = schema.validate(structure);
+        const validationResult = schema.validate(value);
         if (validationResult.success) {
             return validationResult;
         }
         return {
             success: false,
             error: new TypeValidationError_js_1.TypeValidationError({
-                structure: structure,
+                value,
                 cause: validationResult.error,
             }),
         };
@@ -58,7 +58,7 @@ function safeValidateTypes({ structure, schema, }) {
             success: false,
             error: error instanceof TypeValidationError_js_1.TypeValidationError
                 ? error
-                : new TypeValidationError_js_1.TypeValidationError({ structure: structure, cause: error }),
+                : new TypeValidationError_js_1.TypeValidationError({ value, cause: error }),
         };
     }
 }

package/core/schema/validateTypes.d.ts

@@ -5,12 +5,12 @@ import { TypeValidationError } from "./TypeValidationError.js";
  * return a strongly-typed object.
  *
  * @template T - The type of the object to validate.
- * @param {string} structure - The JSON structure to validate.
- * @param {Schema<T>} schema - The schema to use for validating the JSON.
+ * @param {string} options.value - The object to validate.
+ * @param {Schema<T>} options.schema - The schema to use for validating the JSON.
  * @returns {T} - The typed object.
  */
-export declare function validateTypes<T>({ structure, schema, }: {
-    structure: unknown;
+export declare function validateTypes<T>({ value, schema, }: {
+    value: unknown;
     schema: Schema<T>;
 }): T;
 /**
@@ -18,16 +18,16 @@ export declare function validateTypes<T>({ structure, schema, }: {
  * return a strongly-typed object.
  *
  * @template T - The type of the object to validate.
- * @param {string} structure - The JSON object to validate.
- * @param {Schema<T>} schema - The schema to use for validating the JSON.
+ * @param {string} options.value - The JSON object to validate.
+ * @param {Schema<T>} options.schema - The schema to use for validating the JSON.
  * @returns An object with either a `success` flag and the parsed and typed data, or a `success` flag and an error object.
  */
-export declare function safeValidateTypes<T>({ structure, schema, }: {
-    structure: unknown;
+export declare function safeValidateTypes<T>({ value, schema, }: {
+    value: unknown;
     schema: Schema<T>;
 }): {
     success: true;
-    data: T;
+    value: T;
 } | {
     success: false;
     error: TypeValidationError;