ai 3.3.30 → 3.3.31

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # ai
 
+## 3.3.31
+
+### Patch Changes
+
+- 561fd7e: feat (ai/core): add output: enum to generateObject
+
 ## 3.3.30
 
 ### 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.

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.

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";
   }