ai 3.3.29 → 3.3.31

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # ai
 
+## 3.3.31
+
+### Patch Changes
+
+- 561fd7e: feat (ai/core): add output: enum to generateObject
+
+## 3.3.30
+
+### Patch Changes
+
+- 6ee1f8e: feat (ai/core): add toDataStream to streamText result
+
 ## 3.3.29
 
 ### Patch Changes

package/dist/index.d.mts

@@ -770,6 +770,50 @@ Optional telemetry configuration (experimental).
     };
 }): Promise<GenerateObjectResult<Array<ELEMENT>>>;
 /**
+Generate a value from an enum (limited list of string values) using a language model.
+
+This function does not stream the output.
+
+@return
+A result object that contains the generated value, the finish reason, the token usage, and additional information.
+ */
+declare function generateObject<ENUM extends string>(options: Omit<CallSettings, 'stopSequences'> & Prompt & {
+    output: 'enum';
+    /**
+The language model to use.
+   */
+    model: LanguageModel;
+    /**
+The enum values that the model should use.
+   */
+    enum: Array<ENUM>;
+    /**
+The mode to use for object generation.
+
+The schema is converted in a JSON schema and used in one of the following ways
+
+- 'auto': The provider will choose the best mode for the model.
+- 'tool': A tool with the JSON schema as parameters is is provided and the provider is instructed to use it.
+- 'json': The JSON schema and an instruction is injected into the prompt. If the provider supports JSON mode, it is enabled. If the provider supports JSON grammars, the grammar is used.
+
+Please note that most providers do not support all modes.
+
+Default and recommended: 'auto' (best mode for the model).
+   */
+    mode?: 'auto' | 'json' | 'tool';
+    /**
+Optional telemetry configuration (experimental).
+   */
+    experimental_telemetry?: TelemetrySettings;
+    /**
+     * Internal. For test use only. May change without notice.
+     */
+    _internal?: {
+        generateId?: () => string;
+        currentDate?: () => Date;
+    };
+}): Promise<GenerateObjectResult<ENUM>>;
+/**
 Generate JSON with any schema for a given prompt using a language model.
 
 This function does not stream the output. If you want to stream the output, use `streamObject` instead.
@@ -1519,10 +1563,22 @@ interface StreamTextResult<TOOLS extends Record<string, CoreTool>> {
   
     @returns A data stream.
   
-    @deprecated Use `toDataStreamResponse` instead.
+    @deprecated Use `toDataStream` instead.
        */
     toAIStream(callbacks?: AIStreamCallbacksAndOptions): ReadableStream<Uint8Array>;
     /**
+    Converts the result to a data stream.
+  
+    @param data an optional StreamData object that will be merged into the stream.
+    @param getErrorMessage an optional function that converts an error to an error message.
+  
+    @return A data stream.
+       */
+    toDataStream(options?: {
+        data?: StreamData;
+        getErrorMessage?: (error: unknown) => string;
+    }): ReadableStream<Uint8Array>;
+    /**
     Writes stream data output to a Node.js response-like object.
     It sets a `Content-Type` header to `text/plain; charset=utf-8` and
     writes each stream data part as a separate chunk.

package/dist/index.d.ts

@@ -770,6 +770,50 @@ Optional telemetry configuration (experimental).
     };
 }): Promise<GenerateObjectResult<Array<ELEMENT>>>;
 /**
+Generate a value from an enum (limited list of string values) using a language model.
+
+This function does not stream the output.
+
+@return
+A result object that contains the generated value, the finish reason, the token usage, and additional information.
+ */
+declare function generateObject<ENUM extends string>(options: Omit<CallSettings, 'stopSequences'> & Prompt & {
+    output: 'enum';
+    /**
+The language model to use.
+   */
+    model: LanguageModel;
+    /**
+The enum values that the model should use.
+   */
+    enum: Array<ENUM>;
+    /**
+The mode to use for object generation.
+
+The schema is converted in a JSON schema and used in one of the following ways
+
+- 'auto': The provider will choose the best mode for the model.
+- 'tool': A tool with the JSON schema as parameters is is provided and the provider is instructed to use it.
+- 'json': The JSON schema and an instruction is injected into the prompt. If the provider supports JSON mode, it is enabled. If the provider supports JSON grammars, the grammar is used.
+
+Please note that most providers do not support all modes.
+
+Default and recommended: 'auto' (best mode for the model).
+   */
+    mode?: 'auto' | 'json' | 'tool';
+    /**
+Optional telemetry configuration (experimental).
+   */
+    experimental_telemetry?: TelemetrySettings;
+    /**
+     * Internal. For test use only. May change without notice.
+     */
+    _internal?: {
+        generateId?: () => string;
+        currentDate?: () => Date;
+    };
+}): Promise<GenerateObjectResult<ENUM>>;
+/**
 Generate JSON with any schema for a given prompt using a language model.
 
 This function does not stream the output. If you want to stream the output, use `streamObject` instead.
@@ -1519,10 +1563,22 @@ interface StreamTextResult<TOOLS extends Record<string, CoreTool>> {
   
     @returns A data stream.
   
-    @deprecated Use `toDataStreamResponse` instead.
+    @deprecated Use `toDataStream` instead.
        */
     toAIStream(callbacks?: AIStreamCallbacksAndOptions): ReadableStream<Uint8Array>;
     /**
+    Converts the result to a data stream.
+  
+    @param data an optional StreamData object that will be merged into the stream.
+    @param getErrorMessage an optional function that converts an error to an error message.
+  
+    @return A data stream.
+       */
+    toDataStream(options?: {
+        data?: StreamData;
+        getErrorMessage?: (error: unknown) => string;
+    }): ReadableStream<Uint8Array>;
+    /**
     Writes stream data output to a Node.js response-like object.
     It sets a `Content-Type` header to `text/plain; charset=utf-8` and
     writes each stream data part as a separate chunk.

package/dist/index.js

@@ -1537,7 +1537,7 @@ var objectOutputStrategy = (schema) => ({
 var arrayOutputStrategy = (schema) => {
   const { $schema, ...itemSchema } = schema.jsonSchema;
   return {
-    type: "array",
+    type: "enum",
     // wrap in object that contains array of elements, since most LLMs will not
     // be able to generate an array directly:
     // possible future optimization: use arrays directly when model supports grammar-guided generation
@@ -1641,15 +1641,64 @@ var arrayOutputStrategy = (schema) => {
     }
   };
 };
+var enumOutputStrategy = (enumValues) => {
+  return {
+    type: "enum",
+    // wrap in object that contains result, since most LLMs will not
+    // be able to generate an enum value directly:
+    // possible future optimization: use enums directly when model supports top-level enums
+    jsonSchema: {
+      $schema: "http://json-schema.org/draft-07/schema#",
+      type: "object",
+      properties: {
+        result: { type: "string", enum: enumValues }
+      },
+      required: ["result"],
+      additionalProperties: false
+    },
+    validateFinalResult(value) {
+      if (!(0, import_provider9.isJSONObject)(value) || typeof value.result !== "string") {
+        return {
+          success: false,
+          error: new import_provider9.TypeValidationError({
+            value,
+            cause: 'value must be an object that contains a string in the "result" property.'
+          })
+        };
+      }
+      const result = value.result;
+      return enumValues.includes(result) ? { success: true, value: result } : {
+        success: false,
+        error: new import_provider9.TypeValidationError({
+          value,
+          cause: "value must be a string in the enum"
+        })
+      };
+    },
+    validatePartialResult() {
+      throw new import_provider9.UnsupportedFunctionalityError({
+        functionality: "partial results in enum mode"
+      });
+    },
+    createElementStream() {
+      throw new import_provider9.UnsupportedFunctionalityError({
+        functionality: "element streams in enum mode"
+      });
+    }
+  };
+};
 function getOutputStrategy({
   output,
-  schema
+  schema,
+  enumValues
 }) {
   switch (output) {
     case "object":
       return objectOutputStrategy((0, import_ui_utils.asSchema)(schema));
     case "array":
       return arrayOutputStrategy((0, import_ui_utils.asSchema)(schema));
+    case "enum":
+      return enumOutputStrategy(enumValues);
     case "no-schema":
       return noSchemaOutputStrategy;
     default: {
@@ -1665,9 +1714,10 @@ function validateObjectGenerationInput({
   mode,
   schema,
   schemaName,
-  schemaDescription
+  schemaDescription,
+  enumValues
 }) {
-  if (output != null && output !== "object" && output !== "array" && output !== "no-schema") {
+  if (output != null && output !== "object" && output !== "array" && output !== "enum" && output !== "no-schema") {
     throw new InvalidArgumentError({
       parameter: "output",
       value: output,
@@ -1703,6 +1753,13 @@ function validateObjectGenerationInput({
         message: "Schema name is not supported for no-schema output."
       });
     }
+    if (enumValues != null) {
+      throw new InvalidArgumentError({
+        parameter: "enumValues",
+        value: enumValues,
+        message: "Enum values are not supported for no-schema output."
+      });
+    }
   }
   if (output === "object") {
     if (schema == null) {
@@ -1712,6 +1769,13 @@ function validateObjectGenerationInput({
         message: "Schema is required for object output."
       });
     }
+    if (enumValues != null) {
+      throw new InvalidArgumentError({
+        parameter: "enumValues",
+        value: enumValues,
+        message: "Enum values are not supported for object output."
+      });
+    }
   }
   if (output === "array") {
     if (schema == null) {
@@ -1721,6 +1785,52 @@ function validateObjectGenerationInput({
         message: "Element schema is required for array output."
       });
     }
+    if (enumValues != null) {
+      throw new InvalidArgumentError({
+        parameter: "enumValues",
+        value: enumValues,
+        message: "Enum values are not supported for array output."
+      });
+    }
+  }
+  if (output === "enum") {
+    if (schema != null) {
+      throw new InvalidArgumentError({
+        parameter: "schema",
+        value: schema,
+        message: "Schema is not supported for enum output."
+      });
+    }
+    if (schemaDescription != null) {
+      throw new InvalidArgumentError({
+        parameter: "schemaDescription",
+        value: schemaDescription,
+        message: "Schema description is not supported for enum output."
+      });
+    }
+    if (schemaName != null) {
+      throw new InvalidArgumentError({
+        parameter: "schemaName",
+        value: schemaName,
+        message: "Schema name is not supported for enum output."
+      });
+    }
+    if (enumValues == null) {
+      throw new InvalidArgumentError({
+        parameter: "enumValues",
+        value: enumValues,
+        message: "Enum values are required for enum output."
+      });
+    }
+    for (const value of enumValues) {
+      if (typeof value !== "string") {
+        throw new InvalidArgumentError({
+          parameter: "enumValues",
+          value,
+          message: "Enum values must be strings."
+        });
+      }
+    }
   }
 }
 
@@ -1728,6 +1838,8 @@ function validateObjectGenerationInput({
 var originalGenerateId = (0, import_provider_utils6.createIdGenerator)({ prefix: "aiobj-", length: 24 });
 async function generateObject({
   model,
+  enum: enumValues,
+  // rename bc enum is reserved by typescript
   schema: inputSchema,
   schemaName,
   schemaDescription,
@@ -1752,9 +1864,14 @@ async function generateObject({
     mode,
     schema: inputSchema,
     schemaName,
-    schemaDescription
+    schemaDescription,
+    enumValues
+  });
+  const outputStrategy = getOutputStrategy({
+    output,
+    schema: inputSchema,
+    enumValues
   });
-  const outputStrategy = getOutputStrategy({ output, schema: inputSchema });
   if (outputStrategy.type === "no-schema" && mode === void 0) {
     mode = "json";
   }
@@ -4056,9 +4173,9 @@ var DefaultStreamTextResult = class {
     });
   }
   toAIStream(callbacks = {}) {
-    return this.toDataStream({ callbacks });
+    return this.toDataStreamInternal({ callbacks });
   }
-  toDataStream({
+  toDataStreamInternal({
     callbacks = {},
     getErrorMessage: getErrorMessage4 = () => ""
     // mask error messages for safety by default
@@ -4182,7 +4299,7 @@ var DefaultStreamTextResult = class {
         contentType: "text/plain; charset=utf-8",
         dataStreamVersion: "v1"
       }),
-      stream: data ? mergeStreams(data.stream, this.toDataStream({ getErrorMessage: getErrorMessage4 })) : this.toDataStream({ getErrorMessage: getErrorMessage4 })
+      stream: this.toDataStream({ data, getErrorMessage: getErrorMessage4 })
     });
   }
   pipeTextStreamToResponse(response, init) {
@@ -4199,6 +4316,12 @@ var DefaultStreamTextResult = class {
   toAIStreamResponse(options) {
     return this.toDataStreamResponse(options);
   }
+  toDataStream(options) {
+    const stream = this.toDataStreamInternal({
+      getErrorMessage: options == null ? void 0 : options.getErrorMessage
+    });
+    return (options == null ? void 0 : options.data) ? mergeStreams(options == null ? void 0 : options.data.stream, stream) : stream;
+  }
   toDataStreamResponse(options) {
     var _a11;
     const init = options == null ? void 0 : "init" in options ? options.init : {
@@ -4208,8 +4331,7 @@ var DefaultStreamTextResult = class {
     };
     const data = options == null ? void 0 : "data" in options ? options.data : void 0;
     const getErrorMessage4 = options == null ? void 0 : "getErrorMessage" in options ? options.getErrorMessage : void 0;
-    const stream = data ? mergeStreams(data.stream, this.toDataStream({ getErrorMessage: getErrorMessage4 })) : this.toDataStream({ getErrorMessage: getErrorMessage4 });
-    return new Response(stream, {
+    return new Response(this.toDataStream({ data, getErrorMessage: getErrorMessage4 }), {
       status: (_a11 = init == null ? void 0 : init.status) != null ? _a11 : 200,
       statusText: init == null ? void 0 : init.statusText,
       headers: prepareResponseHeaders(init, {