ai 6.0.33 → 6.0.34

package/src/generate-object/inject-json-instruction.test.ts

@@ -0,0 +1,181 @@
+import { JSONSchema7 } from '@ai-sdk/provider';
+import { injectJsonInstruction } from './inject-json-instruction';
+import { describe, it, expect } from 'vitest';
+
+const basicSchema: JSONSchema7 = {
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    age: { type: 'number' },
+  },
+  required: ['name', 'age'],
+};
+
+it('should handle basic case with prompt and schema', () => {
+  const result = injectJsonInstruction({
+    prompt: 'Generate a person',
+    schema: basicSchema,
+  });
+  expect(result).toBe(
+    'Generate a person\n\n' +
+      'JSON schema:\n' +
+      '{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"number"}},"required":["name","age"]}\n' +
+      'You MUST answer with a JSON object that matches the JSON schema above.',
+  );
+});
+
+it('should handle only prompt, no schema', () => {
+  const result = injectJsonInstruction({
+    prompt: 'Generate a person',
+  });
+  expect(result).toBe('Generate a person\n\nYou MUST answer with JSON.');
+});
+
+it('should handle only schema, no prompt', () => {
+  const result = injectJsonInstruction({
+    schema: basicSchema,
+  });
+  expect(result).toBe(
+    'JSON schema:\n' +
+      '{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"number"}},"required":["name","age"]}\n' +
+      'You MUST answer with a JSON object that matches the JSON schema above.',
+  );
+});
+
+it('should handle no prompt, no schema', () => {
+  const result = injectJsonInstruction({});
+  expect(result).toBe('You MUST answer with JSON.');
+});
+
+it('should handle custom schemaPrefix and schemaSuffix', () => {
+  const result = injectJsonInstruction({
+    prompt: 'Generate a person',
+    schema: basicSchema,
+    schemaPrefix: 'Custom prefix:',
+    schemaSuffix: 'Custom suffix',
+  });
+  expect(result).toBe(
+    'Generate a person\n\n' +
+      'Custom prefix:\n' +
+      '{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"number"}},"required":["name","age"]}\n' +
+      'Custom suffix',
+  );
+});
+
+it('should handle empty string prompt', () => {
+  const result = injectJsonInstruction({
+    prompt: '',
+    schema: basicSchema,
+  });
+  expect(result).toBe(
+    'JSON schema:\n' +
+      '{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"number"}},"required":["name","age"]}\n' +
+      'You MUST answer with a JSON object that matches the JSON schema above.',
+  );
+});
+
+it('should handle empty object schema', () => {
+  const result = injectJsonInstruction({
+    prompt: 'Generate something',
+    schema: {},
+  });
+  expect(result).toBe(
+    'Generate something\n\n' +
+      'JSON schema:\n' +
+      '{}\n' +
+      'You MUST answer with a JSON object that matches the JSON schema above.',
+  );
+});
+
+it('should handle complex nested schema', () => {
+  const complexSchema: JSONSchema7 = {
+    type: 'object',
+    properties: {
+      person: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          age: { type: 'number' },
+          address: {
+            type: 'object',
+            properties: {
+              street: { type: 'string' },
+              city: { type: 'string' },
+            },
+          },
+        },
+      },
+    },
+  };
+  const result = injectJsonInstruction({
+    prompt: 'Generate a complex person',
+    schema: complexSchema,
+  });
+  expect(result).toBe(
+    'Generate a complex person\n\n' +
+      'JSON schema:\n' +
+      '{"type":"object","properties":{"person":{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"number"},"address":{"type":"object","properties":{"street":{"type":"string"},"city":{"type":"string"}}}}}}}\n' +
+      'You MUST answer with a JSON object that matches the JSON schema above.',
+  );
+});
+
+it('should handle schema with special characters', () => {
+  const specialSchema: JSONSchema7 = {
+    type: 'object',
+    properties: {
+      'special@property': { type: 'string' },
+      'emoji😊': { type: 'string' },
+    },
+  };
+  const result = injectJsonInstruction({
+    schema: specialSchema,
+  });
+  expect(result).toBe(
+    'JSON schema:\n' +
+      '{"type":"object","properties":{"special@property":{"type":"string"},"emoji😊":{"type":"string"}}}\n' +
+      'You MUST answer with a JSON object that matches the JSON schema above.',
+  );
+});
+
+it('should handle very long prompt and schema', () => {
+  const longPrompt = 'A'.repeat(1000);
+  const longSchema: JSONSchema7 = {
+    type: 'object',
+    properties: {},
+  };
+  for (let i = 0; i < 100; i++) {
+    longSchema.properties![`prop${i}`] = { type: 'string' };
+  }
+  const result = injectJsonInstruction({
+    prompt: longPrompt,
+    schema: longSchema,
+  });
+  expect(result).toBe(
+    longPrompt +
+      '\n\n' +
+      'JSON schema:\n' +
+      JSON.stringify(longSchema) +
+      '\n' +
+      'You MUST answer with a JSON object that matches the JSON schema above.',
+  );
+});
+
+it('should handle null values for optional parameters', () => {
+  const result = injectJsonInstruction({
+    prompt: null as any,
+    schema: null as any,
+    schemaPrefix: null as any,
+    schemaSuffix: null as any,
+  });
+  expect(result).toBe('');
+});
+
+it('should handle undefined values for optional parameters', () => {
+  const result = injectJsonInstruction({
+    prompt: undefined,
+    schema: undefined,
+    schemaPrefix: undefined,
+    schemaSuffix: undefined,
+  });
+  expect(result).toBe('You MUST answer with JSON.');
+});

package/src/generate-object/inject-json-instruction.ts

@@ -0,0 +1,30 @@
+import { JSONSchema7 } from '@ai-sdk/provider';
+
+const DEFAULT_SCHEMA_PREFIX = 'JSON schema:';
+const DEFAULT_SCHEMA_SUFFIX =
+  'You MUST answer with a JSON object that matches the JSON schema above.';
+const DEFAULT_GENERIC_SUFFIX = 'You MUST answer with JSON.';
+
+export function injectJsonInstruction({
+  prompt,
+  schema,
+  schemaPrefix = schema != null ? DEFAULT_SCHEMA_PREFIX : undefined,
+  schemaSuffix = schema != null
+    ? DEFAULT_SCHEMA_SUFFIX
+    : DEFAULT_GENERIC_SUFFIX,
+}: {
+  prompt?: string;
+  schema?: JSONSchema7;
+  schemaPrefix?: string;
+  schemaSuffix?: string;
+}): string {
+  return [
+    prompt != null && prompt.length > 0 ? prompt : undefined,
+    prompt != null && prompt.length > 0 ? '' : undefined, // add a newline if prompt is not null
+    schemaPrefix,
+    schema != null ? JSON.stringify(schema) : undefined,
+    schemaSuffix,
+  ]
+    .filter(line => line != null)
+    .join('\n');
+}

package/src/generate-object/output-strategy.ts

@@ -0,0 +1,415 @@
+import {
+  isJSONArray,
+  isJSONObject,
+  JSONObject,
+  JSONSchema7,
+  JSONValue,
+  TypeValidationError,
+  UnsupportedFunctionalityError,
+} from '@ai-sdk/provider';
+import {
+  asSchema,
+  FlexibleSchema,
+  safeValidateTypes,
+  Schema,
+  ValidationResult,
+} from '@ai-sdk/provider-utils';
+import { NoObjectGeneratedError } from '../error/no-object-generated-error';
+import {
+  FinishReason,
+  LanguageModelResponseMetadata,
+  LanguageModelUsage,
+} from '../types';
+import {
+  AsyncIterableStream,
+  createAsyncIterableStream,
+} from '../util/async-iterable-stream';
+import { DeepPartial } from '../util/deep-partial';
+import { ObjectStreamPart } from './stream-object-result';
+
+export interface OutputStrategy<PARTIAL, RESULT, ELEMENT_STREAM> {
+  readonly type: 'object' | 'array' | 'enum' | 'no-schema';
+
+  jsonSchema(): Promise<JSONSchema7 | undefined>;
+
+  validatePartialResult({
+    value,
+    textDelta,
+    isFinalDelta,
+  }: {
+    value: JSONValue;
+    textDelta: string;
+    isFirstDelta: boolean;
+    isFinalDelta: boolean;
+    latestObject: PARTIAL | undefined;
+  }): Promise<
+    ValidationResult<{
+      partial: PARTIAL;
+      textDelta: string;
+    }>
+  >;
+  validateFinalResult(
+    value: JSONValue | undefined,
+    context: {
+      text: string;
+      response: LanguageModelResponseMetadata;
+      usage: LanguageModelUsage;
+    },
+  ): Promise<ValidationResult<RESULT>>;
+
+  createElementStream(
+    originalStream: ReadableStream<ObjectStreamPart<PARTIAL>>,
+  ): ELEMENT_STREAM;
+}
+
+const noSchemaOutputStrategy: OutputStrategy<JSONValue, JSONValue, never> = {
+  type: 'no-schema',
+  jsonSchema: async () => undefined,
+
+  async validatePartialResult({ value, textDelta }) {
+    return { success: true, value: { partial: value, textDelta } };
+  },
+
+  async validateFinalResult(
+    value: JSONValue | undefined,
+    context: {
+      text: string;
+      response: LanguageModelResponseMetadata;
+      usage: LanguageModelUsage;
+      finishReason: FinishReason;
+    },
+  ): Promise<ValidationResult<JSONValue>> {
+    return value === undefined
+      ? {
+          success: false,
+          error: new NoObjectGeneratedError({
+            message: 'No object generated: response did not match schema.',
+            text: context.text,
+            response: context.response,
+            usage: context.usage,
+            finishReason: context.finishReason,
+          }),
+        }
+      : { success: true, value };
+  },
+
+  createElementStream() {
+    throw new UnsupportedFunctionalityError({
+      functionality: 'element streams in no-schema mode',
+    });
+  },
+};
+
+const objectOutputStrategy = <OBJECT>(
+  schema: Schema<OBJECT>,
+): OutputStrategy<DeepPartial<OBJECT>, OBJECT, never> => ({
+  type: 'object',
+  jsonSchema: async () => await schema.jsonSchema,
+
+  async validatePartialResult({ value, textDelta }) {
+    return {
+      success: true,
+      value: {
+        // Note: currently no validation of partial results:
+        partial: value as DeepPartial<OBJECT>,
+        textDelta,
+      },
+    };
+  },
+
+  async validateFinalResult(
+    value: JSONValue | undefined,
+  ): Promise<ValidationResult<OBJECT>> {
+    return safeValidateTypes({ value, schema });
+  },
+
+  createElementStream() {
+    throw new UnsupportedFunctionalityError({
+      functionality: 'element streams in object mode',
+    });
+  },
+});
+
+const arrayOutputStrategy = <ELEMENT>(
+  schema: Schema<ELEMENT>,
+): OutputStrategy<ELEMENT[], ELEMENT[], AsyncIterableStream<ELEMENT>> => {
+  return {
+    type: 'array',
+
+    // 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
+    jsonSchema: async () => {
+      // remove $schema from schema.jsonSchema:
+      const { $schema, ...itemSchema } = await schema.jsonSchema;
+
+      return {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        type: 'object',
+        properties: {
+          elements: { type: 'array', items: itemSchema },
+        },
+        required: ['elements'],
+        additionalProperties: false,
+      };
+    },
+
+    async validatePartialResult({
+      value,
+      latestObject,
+      isFirstDelta,
+      isFinalDelta,
+    }) {
+      // check that the value is an object that contains an array of elements:
+      if (!isJSONObject(value) || !isJSONArray(value.elements)) {
+        return {
+          success: false,
+          error: new TypeValidationError({
+            value,
+            cause: 'value must be an object that contains an array of elements',
+          }),
+        };
+      }
+
+      const inputArray = value.elements as Array<JSONObject>;
+      const resultArray: Array<ELEMENT> = [];
+
+      for (let i = 0; i < inputArray.length; i++) {
+        const element = inputArray[i];
+        const result = await safeValidateTypes({ value: element, schema });
+
+        // special treatment for last processed element:
+        // ignore parse or validation failures, since they indicate that the
+        // last element is incomplete and should not be included in the result,
+        // unless it is the final delta
+        if (i === inputArray.length - 1 && !isFinalDelta) {
+          continue;
+        }
+
+        if (!result.success) {
+          return result;
+        }
+
+        resultArray.push(result.value);
+      }
+
+      // calculate delta:
+      const publishedElementCount = latestObject?.length ?? 0;
+
+      let textDelta = '';
+
+      if (isFirstDelta) {
+        textDelta += '[';
+      }
+
+      if (publishedElementCount > 0) {
+        textDelta += ',';
+      }
+
+      textDelta += resultArray
+        .slice(publishedElementCount) // only new elements
+        .map(element => JSON.stringify(element))
+        .join(',');
+
+      if (isFinalDelta) {
+        textDelta += ']';
+      }
+
+      return {
+        success: true,
+        value: {
+          partial: resultArray,
+          textDelta,
+        },
+      };
+    },
+
+    async validateFinalResult(
+      value: JSONValue | undefined,
+    ): Promise<ValidationResult<Array<ELEMENT>>> {
+      // check that the value is an object that contains an array of elements:
+      if (!isJSONObject(value) || !isJSONArray(value.elements)) {
+        return {
+          success: false,
+          error: new TypeValidationError({
+            value,
+            cause: 'value must be an object that contains an array of elements',
+          }),
+        };
+      }
+
+      const inputArray = value.elements as Array<JSONObject>;
+
+      // check that each element in the array is of the correct type:
+      for (const element of inputArray) {
+        const result = await safeValidateTypes({ value: element, schema });
+        if (!result.success) {
+          return result;
+        }
+      }
+
+      return { success: true, value: inputArray as Array<ELEMENT> };
+    },
+
+    createElementStream(
+      originalStream: ReadableStream<ObjectStreamPart<ELEMENT[]>>,
+    ) {
+      let publishedElements = 0;
+
+      return createAsyncIterableStream(
+        originalStream.pipeThrough(
+          new TransformStream<ObjectStreamPart<ELEMENT[]>, ELEMENT>({
+            transform(chunk, controller) {
+              switch (chunk.type) {
+                case 'object': {
+                  const array = chunk.object;
+
+                  // publish new elements one by one:
+                  for (
+                    ;
+                    publishedElements < array.length;
+                    publishedElements++
+                  ) {
+                    controller.enqueue(array[publishedElements]);
+                  }
+
+                  break;
+                }
+
+                case 'text-delta':
+                case 'finish':
+                case 'error': // suppress error (use onError instead)
+                  break;
+
+                default: {
+                  const _exhaustiveCheck: never = chunk;
+                  throw new Error(
+                    `Unsupported chunk type: ${_exhaustiveCheck}`,
+                  );
+                }
+              }
+            },
+          }),
+        ),
+      );
+    },
+  };
+};
+
+const enumOutputStrategy = <ENUM extends string>(
+  enumValues: Array<ENUM>,
+): OutputStrategy<string, ENUM, never> => {
+  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: async () => ({
+      $schema: 'http://json-schema.org/draft-07/schema#',
+      type: 'object',
+      properties: {
+        result: { type: 'string', enum: enumValues },
+      },
+      required: ['result'],
+      additionalProperties: false,
+    }),
+
+    async validateFinalResult(
+      value: JSONValue | undefined,
+    ): Promise<ValidationResult<ENUM>> {
+      // check that the value is an object that contains an array of elements:
+      if (!isJSONObject(value) || typeof value.result !== 'string') {
+        return {
+          success: false,
+          error: new TypeValidationError({
+            value,
+            cause:
+              'value must be an object that contains a string in the "result" property.',
+          }),
+        };
+      }
+
+      const result = value.result as string;
+
+      return enumValues.includes(result as ENUM)
+        ? { success: true, value: result as ENUM }
+        : {
+            success: false,
+            error: new TypeValidationError({
+              value,
+              cause: 'value must be a string in the enum',
+            }),
+          };
+    },
+
+    async validatePartialResult({ value, textDelta }) {
+      if (!isJSONObject(value) || typeof value.result !== 'string') {
+        return {
+          success: false,
+          error: new TypeValidationError({
+            value,
+            cause:
+              'value must be an object that contains a string in the "result" property.',
+          }),
+        };
+      }
+
+      const result = value.result as string;
+      const possibleEnumValues = enumValues.filter(enumValue =>
+        enumValue.startsWith(result),
+      );
+
+      if (value.result.length === 0 || possibleEnumValues.length === 0) {
+        return {
+          success: false,
+          error: new TypeValidationError({
+            value,
+            cause: 'value must be a string in the enum',
+          }),
+        };
+      }
+
+      return {
+        success: true,
+        value: {
+          partial:
+            possibleEnumValues.length > 1 ? result : possibleEnumValues[0],
+          textDelta,
+        },
+      };
+    },
+
+    createElementStream() {
+      // no streaming in enum mode
+      throw new UnsupportedFunctionalityError({
+        functionality: 'element streams in enum mode',
+      });
+    },
+  };
+};
+
+export function getOutputStrategy<SCHEMA>({
+  output,
+  schema,
+  enumValues,
+}: {
+  output: 'object' | 'array' | 'enum' | 'no-schema';
+  schema?: FlexibleSchema<SCHEMA>;
+  enumValues?: Array<SCHEMA>;
+}): OutputStrategy<any, any, any> {
+  switch (output) {
+    case 'object':
+      return objectOutputStrategy(asSchema(schema!));
+    case 'array':
+      return arrayOutputStrategy(asSchema(schema!));
+    case 'enum':
+      return enumOutputStrategy(enumValues! as Array<string>);
+    case 'no-schema':
+      return noSchemaOutputStrategy;
+    default: {
+      const _exhaustiveCheck: never = output;
+      throw new Error(`Unsupported output: ${_exhaustiveCheck}`);
+    }
+  }
+}