ai 6.0.0-beta.69 → 6.0.0-beta.71

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # ai
 
+## 6.0.0-beta.71
+
+### Patch Changes
+
+- 077aea3: feat(ai): stable structured output on generateText, streamText, and ToolLoopAgent
+
+## 6.0.0-beta.70
+
+### Patch Changes
+
+- d7bae86: feat(ai): add Output.choice()
+
 ## 6.0.0-beta.69
 
 ### Patch Changes

package/dist/index.d.mts

@@ -632,9 +632,16 @@ interface GenerateTextResult<TOOLS extends ToolSet, OUTPUT> {
      */
     readonly steps: Array<StepResult<TOOLS>>;
     /**
-  The generated structured output. It uses the `experimental_output` specification.
+  The generated structured output. It uses the `output` specification.
+  
+  @deprecated Use `output` instead.
      */
     readonly experimental_output: OUTPUT;
+    /**
+  The generated structured output. It uses the `output` specification.
+  
+     */
+    readonly output: OUTPUT;
 }
 
 /**
@@ -672,12 +679,14 @@ interface Output<OUTPUT = any, PARTIAL = any> {
 }
 /**
  * Output specification for text generation.
+ * This is the default output mode that generates plain text.
  *
  * @returns An output specification for generating text.
  */
 declare const text: () => Output<string, string>;
 /**
  * Output specification for typed object generation using schemas.
+ * When the model generates a text response, it will return an object that matches the schema.
  *
  * @param schema - The schema of the object to generate.
  *
@@ -686,18 +695,37 @@ declare const text: () => Output<string, string>;
 declare const object: <OUTPUT>({ schema: inputSchema, }: {
     schema: FlexibleSchema<OUTPUT>;
 }) => Output<OUTPUT, DeepPartial<OUTPUT>>;
+/**
+ * Array output specification for text generation.
+ * When the model generates a text response, it will return an array of elements.
+ *
+ * @param element - The schema of the element to generate.
+ * @returns An output specification for generating an array of elements.
+ */
 declare const array: <ELEMENT>({ element: inputElementSchema, }: {
     element: FlexibleSchema<ELEMENT>;
 }) => Output<Array<ELEMENT>, Array<ELEMENT>>;
+/**
+ * Choice output specification for text generation.
+ * When the model generates a text response, it will return a one of the choice options.
+ *
+ * @param options - The options to choose from.
+ * @returns An output specification for generating a choice.
+ */
+declare const choice: <ELEMENT extends string>({ options: choiceOptions, }: {
+    options: Array<ELEMENT>;
+}) => Output<ELEMENT, ELEMENT>;
 
 type output_Output<OUTPUT = any, PARTIAL = any> = Output<OUTPUT, PARTIAL>;
 declare const output_array: typeof array;
+declare const output_choice: typeof choice;
 declare const output_object: typeof object;
 declare const output_text: typeof text;
 declare namespace output {
   export {
     output_Output as Output,
     output_array as array,
+    output_choice as choice,
     output_object as object,
     output_text as text,
   };
@@ -1071,7 +1099,7 @@ If set and supported by the model, calls will generate deterministic results.
 @returns
 A result object that contains the generated text, the results of the tool calls, and additional information.
  */
-declare function generateText<TOOLS extends ToolSet, OUTPUT = never, OUTPUT_PARTIAL = never>({ model: modelArg, tools, toolChoice, system, prompt, messages, maxRetries: maxRetriesArg, abortSignal, headers, stopWhen, experimental_output: output, experimental_telemetry: telemetry, providerOptions, experimental_activeTools, activeTools, experimental_prepareStep, prepareStep, experimental_repairToolCall: repairToolCall, experimental_download: download, experimental_context, _internal: { generateId, currentDate, }, onStepFinish, onFinish, ...settings }: CallSettings & Prompt & {
+declare function generateText<TOOLS extends ToolSet, OUTPUT = never, PARTIAL_OUTPUT = never>({ model: modelArg, tools, toolChoice, system, prompt, messages, maxRetries: maxRetriesArg, abortSignal, headers, stopWhen, experimental_output, output, experimental_telemetry: telemetry, providerOptions, experimental_activeTools, activeTools, experimental_prepareStep, prepareStep, experimental_repairToolCall: repairToolCall, experimental_download: download, experimental_context, _internal: { generateId, currentDate, }, onStepFinish, onFinish, ...settings }: CallSettings & Prompt & {
     /**
 The language model to use.
      */
@@ -1113,7 +1141,13 @@ changing the tool call and result types in the result.
     /**
 Optional specification for parsing structured outputs from the LLM response.
      */
-    experimental_output?: Output<OUTPUT, OUTPUT_PARTIAL>;
+    output?: Output<OUTPUT, PARTIAL_OUTPUT>;
+    /**
+Optional specification for parsing structured outputs from the LLM response.
+
+@deprecated Use `output` instead.
+     */
+    experimental_output?: Output<OUTPUT, PARTIAL_OUTPUT>;
     /**
 Custom download function to use for URLs.
 
@@ -1311,7 +1345,7 @@ If set and supported by the model, calls will generate deterministic results.
 @return
 A result object for accessing different stream types and additional information.
  */
-declare function streamText<TOOLS extends ToolSet, OUTPUT = never, PARTIAL_OUTPUT = never>({ model, tools, toolChoice, system, prompt, messages, maxRetries, abortSignal, headers, stopWhen, experimental_output: output, experimental_telemetry: telemetry, prepareStep, providerOptions, experimental_activeTools, activeTools, experimental_repairToolCall: repairToolCall, experimental_transform: transform, experimental_download: download, includeRawChunks, onChunk, onError, onFinish, onAbort, onStepFinish, experimental_context, _internal: { now, generateId, currentDate, }, ...settings }: CallSettings & Prompt & {
+declare function streamText<TOOLS extends ToolSet, OUTPUT = never, PARTIAL_OUTPUT = never>({ model, tools, toolChoice, system, prompt, messages, maxRetries, abortSignal, headers, stopWhen, experimental_output, output, experimental_telemetry: telemetry, prepareStep, providerOptions, experimental_activeTools, activeTools, experimental_repairToolCall: repairToolCall, experimental_transform: transform, experimental_download: download, includeRawChunks, onChunk, onError, onFinish, onAbort, onStepFinish, experimental_context, _internal: { now, generateId, currentDate, }, ...settings }: CallSettings & Prompt & {
     /**
 The language model to use.
      */
@@ -1353,6 +1387,12 @@ functionality that can be fully encapsulated in the provider.
     /**
 Optional specification for parsing structured outputs from the LLM response.
      */
+    output?: Output<OUTPUT, PARTIAL_OUTPUT>;
+    /**
+Optional specification for parsing structured outputs from the LLM response.
+
+@deprecated Use `output` instead.
+ */
     experimental_output?: Output<OUTPUT, PARTIAL_OUTPUT>;
     /**
 Optional function that you can use to provide different settings for a step.
@@ -2280,10 +2320,16 @@ interface StreamTextResult<TOOLS extends ToolSet, PARTIAL_OUTPUT> {
        */
     readonly fullStream: AsyncIterableStream<TextStreamPart<TOOLS>>;
     /**
-  A stream of partial outputs. It uses the `experimental_output` specification.
+     * A stream of partial outputs. It uses the `output` specification.
+     *
+     * @deprecated Use `partialOutputStream` instead.
      */
     readonly experimental_partialOutputStream: AsyncIterableStream<PARTIAL_OUTPUT>;
     /**
+     * A stream of partial outputs. It uses the `output` specification.
+     */
+    readonly partialOutputStream: AsyncIterableStream<PARTIAL_OUTPUT>;
+    /**
   Consumes the stream without processing the parts.
   This is useful to force the stream to finish.
   It effectively removes the backpressure and allows the stream to finish,
@@ -2532,9 +2578,9 @@ type ToolLoopAgentSettings<CALL_OPTIONS = never, TOOLS extends ToolSet = {}, OUT
      */
     activeTools?: Array<keyof NoInfer<TOOLS>>;
     /**
-  Optional specification for parsing structured outputs from the LLM response.
+  Optional specification for generating structured outputs.
      */
-    experimental_output?: OUTPUT;
+    output?: OUTPUT;
     /**
   Optional function that you can use to provide different settings for a step.
     */

package/dist/index.d.ts

@@ -632,9 +632,16 @@ interface GenerateTextResult<TOOLS extends ToolSet, OUTPUT> {
      */
     readonly steps: Array<StepResult<TOOLS>>;
     /**
-  The generated structured output. It uses the `experimental_output` specification.
+  The generated structured output. It uses the `output` specification.
+  
+  @deprecated Use `output` instead.
      */
     readonly experimental_output: OUTPUT;
+    /**
+  The generated structured output. It uses the `output` specification.
+  
+     */
+    readonly output: OUTPUT;
 }
 
 /**
@@ -672,12 +679,14 @@ interface Output<OUTPUT = any, PARTIAL = any> {
 }
 /**
  * Output specification for text generation.
+ * This is the default output mode that generates plain text.
  *
  * @returns An output specification for generating text.
  */
 declare const text: () => Output<string, string>;
 /**
  * Output specification for typed object generation using schemas.
+ * When the model generates a text response, it will return an object that matches the schema.
  *
  * @param schema - The schema of the object to generate.
  *
@@ -686,18 +695,37 @@ declare const text: () => Output<string, string>;
 declare const object: <OUTPUT>({ schema: inputSchema, }: {
     schema: FlexibleSchema<OUTPUT>;
 }) => Output<OUTPUT, DeepPartial<OUTPUT>>;
+/**
+ * Array output specification for text generation.
+ * When the model generates a text response, it will return an array of elements.
+ *
+ * @param element - The schema of the element to generate.
+ * @returns An output specification for generating an array of elements.
+ */
 declare const array: <ELEMENT>({ element: inputElementSchema, }: {
     element: FlexibleSchema<ELEMENT>;
 }) => Output<Array<ELEMENT>, Array<ELEMENT>>;
+/**
+ * Choice output specification for text generation.
+ * When the model generates a text response, it will return a one of the choice options.
+ *
+ * @param options - The options to choose from.
+ * @returns An output specification for generating a choice.
+ */
+declare const choice: <ELEMENT extends string>({ options: choiceOptions, }: {
+    options: Array<ELEMENT>;
+}) => Output<ELEMENT, ELEMENT>;
 
 type output_Output<OUTPUT = any, PARTIAL = any> = Output<OUTPUT, PARTIAL>;
 declare const output_array: typeof array;
+declare const output_choice: typeof choice;
 declare const output_object: typeof object;
 declare const output_text: typeof text;
 declare namespace output {
   export {
     output_Output as Output,
     output_array as array,
+    output_choice as choice,
     output_object as object,
     output_text as text,
   };
@@ -1071,7 +1099,7 @@ If set and supported by the model, calls will generate deterministic results.
 @returns
 A result object that contains the generated text, the results of the tool calls, and additional information.
  */
-declare function generateText<TOOLS extends ToolSet, OUTPUT = never, OUTPUT_PARTIAL = never>({ model: modelArg, tools, toolChoice, system, prompt, messages, maxRetries: maxRetriesArg, abortSignal, headers, stopWhen, experimental_output: output, experimental_telemetry: telemetry, providerOptions, experimental_activeTools, activeTools, experimental_prepareStep, prepareStep, experimental_repairToolCall: repairToolCall, experimental_download: download, experimental_context, _internal: { generateId, currentDate, }, onStepFinish, onFinish, ...settings }: CallSettings & Prompt & {
+declare function generateText<TOOLS extends ToolSet, OUTPUT = never, PARTIAL_OUTPUT = never>({ model: modelArg, tools, toolChoice, system, prompt, messages, maxRetries: maxRetriesArg, abortSignal, headers, stopWhen, experimental_output, output, experimental_telemetry: telemetry, providerOptions, experimental_activeTools, activeTools, experimental_prepareStep, prepareStep, experimental_repairToolCall: repairToolCall, experimental_download: download, experimental_context, _internal: { generateId, currentDate, }, onStepFinish, onFinish, ...settings }: CallSettings & Prompt & {
     /**
 The language model to use.
      */
@@ -1113,7 +1141,13 @@ changing the tool call and result types in the result.
     /**
 Optional specification for parsing structured outputs from the LLM response.
      */
-    experimental_output?: Output<OUTPUT, OUTPUT_PARTIAL>;
+    output?: Output<OUTPUT, PARTIAL_OUTPUT>;
+    /**
+Optional specification for parsing structured outputs from the LLM response.
+
+@deprecated Use `output` instead.
+     */
+    experimental_output?: Output<OUTPUT, PARTIAL_OUTPUT>;
     /**
 Custom download function to use for URLs.
 
@@ -1311,7 +1345,7 @@ If set and supported by the model, calls will generate deterministic results.
 @return
 A result object for accessing different stream types and additional information.
  */
-declare function streamText<TOOLS extends ToolSet, OUTPUT = never, PARTIAL_OUTPUT = never>({ model, tools, toolChoice, system, prompt, messages, maxRetries, abortSignal, headers, stopWhen, experimental_output: output, experimental_telemetry: telemetry, prepareStep, providerOptions, experimental_activeTools, activeTools, experimental_repairToolCall: repairToolCall, experimental_transform: transform, experimental_download: download, includeRawChunks, onChunk, onError, onFinish, onAbort, onStepFinish, experimental_context, _internal: { now, generateId, currentDate, }, ...settings }: CallSettings & Prompt & {
+declare function streamText<TOOLS extends ToolSet, OUTPUT = never, PARTIAL_OUTPUT = never>({ model, tools, toolChoice, system, prompt, messages, maxRetries, abortSignal, headers, stopWhen, experimental_output, output, experimental_telemetry: telemetry, prepareStep, providerOptions, experimental_activeTools, activeTools, experimental_repairToolCall: repairToolCall, experimental_transform: transform, experimental_download: download, includeRawChunks, onChunk, onError, onFinish, onAbort, onStepFinish, experimental_context, _internal: { now, generateId, currentDate, }, ...settings }: CallSettings & Prompt & {
     /**
 The language model to use.
      */
@@ -1353,6 +1387,12 @@ functionality that can be fully encapsulated in the provider.
     /**
 Optional specification for parsing structured outputs from the LLM response.
      */
+    output?: Output<OUTPUT, PARTIAL_OUTPUT>;
+    /**
+Optional specification for parsing structured outputs from the LLM response.
+
+@deprecated Use `output` instead.
+ */
     experimental_output?: Output<OUTPUT, PARTIAL_OUTPUT>;
     /**
 Optional function that you can use to provide different settings for a step.
@@ -2280,10 +2320,16 @@ interface StreamTextResult<TOOLS extends ToolSet, PARTIAL_OUTPUT> {
        */
     readonly fullStream: AsyncIterableStream<TextStreamPart<TOOLS>>;
     /**
-  A stream of partial outputs. It uses the `experimental_output` specification.
+     * A stream of partial outputs. It uses the `output` specification.
+     *
+     * @deprecated Use `partialOutputStream` instead.
      */
     readonly experimental_partialOutputStream: AsyncIterableStream<PARTIAL_OUTPUT>;
     /**
+     * A stream of partial outputs. It uses the `output` specification.
+     */
+    readonly partialOutputStream: AsyncIterableStream<PARTIAL_OUTPUT>;
+    /**
   Consumes the stream without processing the parts.
   This is useful to force the stream to finish.
   It effectively removes the backpressure and allows the stream to finish,
@@ -2532,9 +2578,9 @@ type ToolLoopAgentSettings<CALL_OPTIONS = never, TOOLS extends ToolSet = {}, OUT
      */
     activeTools?: Array<keyof NoInfer<TOOLS>>;
     /**
-  Optional specification for parsing structured outputs from the LLM response.
+  Optional specification for generating structured outputs.
      */
-    experimental_output?: OUTPUT;
+    output?: OUTPUT;
     /**
   Optional function that you can use to provide different settings for a step.
     */

package/dist/index.js

@@ -876,7 +876,7 @@ function detectMediaType({
 var import_provider_utils2 = require("@ai-sdk/provider-utils");
 
 // src/version.ts
-var VERSION = true ? "6.0.0-beta.69" : "0.0.0-test";
+var VERSION = true ? "6.0.0-beta.71" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({ url }) => {
@@ -2647,7 +2647,8 @@ async function generateText({
   abortSignal,
   headers,
   stopWhen = stepCountIs(1),
-  experimental_output: output,
+  experimental_output,
+  output = experimental_output,
   experimental_telemetry: telemetry,
   providerOptions,
   experimental_activeTools,
@@ -3158,6 +3159,9 @@ var DefaultGenerateTextResult = class {
     return this.finalStep.usage;
   }
   get experimental_output() {
+    return this.output;
+  }
+  get output() {
     if (this.resolvedOutput == null) {
       throw new NoOutputSpecifiedError();
     }
@@ -4937,7 +4941,8 @@ function streamText({
   abortSignal,
   headers,
   stopWhen = stepCountIs(1),
-  experimental_output: output,
+  experimental_output,
+  output = experimental_output,
   experimental_telemetry: telemetry,
   prepareStep,
   providerOptions,
@@ -5988,6 +5993,9 @@ var DefaultStreamTextResult = class {
     }
   }
   get experimental_partialOutputStream() {
+    return this.partialOutputStream;
+  }
+  get partialOutputStream() {
     if (this.output == null) {
       throw new NoOutputSpecifiedError();
     }
@@ -9120,6 +9128,7 @@ var DefaultSpeechResult = class {
 var output_exports = {};
 __export(output_exports, {
   array: () => array,
+  choice: () => choice,
   object: () => object,
   text: () => text
 });
@@ -9201,7 +9210,7 @@ var array = ({
   const elementSchema = (0, import_provider_utils29.asSchema)(inputElementSchema);
   return {
     type: "object",
-    // returns a JSON schema that describes an array of elements:
+    // JSON schema that describes an array of elements:
     responseFormat: (0, import_provider_utils29.resolve)(elementSchema.jsonSchema).then((jsonSchema3) => {
       const { $schema, ...itemSchema } = jsonSchema3;
       return {
@@ -9295,6 +9304,82 @@ var array = ({
     }
   };
 };
+var choice = ({
+  options: choiceOptions
+}) => {
+  return {
+    type: "object",
+    // JSON schema that describes an enumeration:
+    responseFormat: Promise.resolve({
+      type: "json",
+      schema: {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        type: "object",
+        properties: {
+          result: { type: "string", enum: choiceOptions }
+        },
+        required: ["result"],
+        additionalProperties: false
+      }
+    }),
+    async parseOutput({ text: text2 }, context) {
+      const parseResult = await (0, import_provider_utils29.safeParseJSON)({ text: text2 });
+      if (!parseResult.success) {
+        throw new NoObjectGeneratedError({
+          message: "No object generated: could not parse the response.",
+          cause: parseResult.error,
+          text: text2,
+          response: context.response,
+          usage: context.usage,
+          finishReason: context.finishReason
+        });
+      }
+      const outerValue = parseResult.value;
+      if (outerValue == null || typeof outerValue !== "object" || !("result" in outerValue) || typeof outerValue.result !== "string" || !choiceOptions.includes(outerValue.result)) {
+        throw new NoObjectGeneratedError({
+          message: "No object generated: response did not match schema.",
+          cause: new import_provider28.TypeValidationError({
+            value: outerValue,
+            cause: "response must be an object that contains a choice value."
+          }),
+          text: text2,
+          response: context.response,
+          usage: context.usage,
+          finishReason: context.finishReason
+        });
+      }
+      return outerValue.result;
+    },
+    async parsePartial({ text: text2 }) {
+      const result = await parsePartialJson(text2);
+      switch (result.state) {
+        case "failed-parse":
+        case "undefined-input": {
+          return void 0;
+        }
+        case "repaired-parse":
+        case "successful-parse": {
+          const outerValue = result.value;
+          if (outerValue == null || typeof outerValue !== "object" || !("result" in outerValue) || typeof outerValue.result !== "string") {
+            return void 0;
+          }
+          const potentialMatches = choiceOptions.filter(
+            (choiceOption) => choiceOption.startsWith(outerValue.result)
+          );
+          if (result.state === "successful-parse") {
+            return potentialMatches.includes(outerValue.result) ? { partial: outerValue.result } : void 0;
+          } else {
+            return potentialMatches.length === 1 ? { partial: potentialMatches[0] } : void 0;
+          }
+        }
+        default: {
+          const _exhaustiveCheck = result.state;
+          throw new Error(`Unsupported parse state: ${_exhaustiveCheck}`);
+        }
+      }
+    }
+  };
+};
 
 // src/generate-text/prune-messages.ts
 function pruneMessages({