@fondation-io/ai 7.0.0-beta.45

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}`);
+    }
+  }
+}

package/src/generate-object/parse-and-validate-object-result.ts

@@ -0,0 +1,111 @@
+import { JSONParseError, TypeValidationError } from '@ai-sdk/provider';
+import { safeParseJSON } from '@ai-sdk/provider-utils';
+import { NoObjectGeneratedError } from '../error/no-object-generated-error';
+import type {
+  FinishReason,
+  LanguageModelResponseMetadata,
+  LanguageModelUsage,
+} from '../types';
+import type { OutputStrategy } from './output-strategy';
+import { RepairTextFunction } from './repair-text';
+
+/**
+ * Parses and validates a result string by parsing it as JSON and validating against the output strategy.
+ *
+ * @param result - The result string to parse and validate
+ * @param outputStrategy - The output strategy containing validation logic
+ * @param context - Additional context for error reporting
+ * @returns The validated result
+ * @throws NoObjectGeneratedError if parsing or validation fails
+ */
+async function parseAndValidateObjectResult<RESULT>(
+  result: string,
+  outputStrategy: OutputStrategy<any, RESULT, any>,
+  context: {
+    response: LanguageModelResponseMetadata;
+    usage: LanguageModelUsage;
+    finishReason: FinishReason;
+  },
+): Promise<RESULT> {
+  const parseResult = await safeParseJSON({ text: result });
+
+  if (!parseResult.success) {
+    throw new NoObjectGeneratedError({
+      message: 'No object generated: could not parse the response.',
+      cause: parseResult.error,
+      text: result,
+      response: context.response,
+      usage: context.usage,
+      finishReason: context.finishReason,
+    });
+  }
+
+  const validationResult = await outputStrategy.validateFinalResult(
+    parseResult.value,
+    {
+      text: result,
+      response: context.response,
+      usage: context.usage,
+    },
+  );
+
+  if (!validationResult.success) {
+    throw new NoObjectGeneratedError({
+      message: 'No object generated: response did not match schema.',
+      cause: validationResult.error,
+      text: result,
+      response: context.response,
+      usage: context.usage,
+      finishReason: context.finishReason,
+    });
+  }
+
+  return validationResult.value;
+}
+
+/**
+ * Parses and validates a result string by parsing it as JSON and validating against the output strategy.
+ * If the result cannot be parsed, it attempts to repair the result using the repairText function.
+ *
+ * @param result - The result string to parse and validate
+ * @param outputStrategy - The output strategy containing validation logic
+ * @param repairText - A function that attempts to repair the result string
+ * @param context - Additional context for error reporting
+ * @returns The validated result
+ * @throws NoObjectGeneratedError if parsing or validation fails
+ */
+export async function parseAndValidateObjectResultWithRepair<RESULT>(
+  result: string,
+  outputStrategy: OutputStrategy<any, RESULT, any>,
+  repairText: RepairTextFunction | undefined,
+  context: {
+    response: LanguageModelResponseMetadata;
+    usage: LanguageModelUsage;
+    finishReason: FinishReason;
+  },
+): Promise<RESULT> {
+  try {
+    return await parseAndValidateObjectResult(result, outputStrategy, context);
+  } catch (error) {
+    if (
+      repairText != null &&
+      NoObjectGeneratedError.isInstance(error) &&
+      (JSONParseError.isInstance(error.cause) ||
+        TypeValidationError.isInstance(error.cause))
+    ) {
+      const repairedText = await repairText({
+        text: result,
+        error: error.cause,
+      });
+      if (repairedText === null) {
+        throw error;
+      }
+      return await parseAndValidateObjectResult(
+        repairedText,
+        outputStrategy,
+        context,
+      );
+    }
+    throw error;
+  }
+}

package/src/generate-object/repair-text.ts

@@ -0,0 +1,12 @@
+import { JSONParseError, TypeValidationError } from '@ai-sdk/provider';
+
+/**
+ * A function that attempts to repair the raw output of the model
+ * to enable JSON parsing.
+ *
+ * Should return the repaired text or null if the text cannot be repaired.
+ */
+export type RepairTextFunction = (options: {
+  text: string;
+  error: JSONParseError | TypeValidationError;
+}) => Promise<string | null>;

package/src/generate-object/stream-object-result.ts

@@ -0,0 +1,120 @@
+import { ServerResponse } from 'http';
+import { AsyncIterableStream } from '../util/async-iterable-stream';
+import {
+  CallWarning,
+  FinishReason,
+  LanguageModelRequestMetadata,
+  LanguageModelResponseMetadata,
+  ProviderMetadata,
+} from '../types';
+import { LanguageModelUsage } from '../types/usage';
+
+/**
+ * The result of a `streamObject` call that contains the partial object stream and additional information.
+ */
+export interface StreamObjectResult<PARTIAL, RESULT, ELEMENT_STREAM> {
+  /**
+   * Warnings from the model provider (e.g. unsupported settings)
+   */
+  readonly warnings: Promise<CallWarning[] | undefined>;
+
+  /**
+   * The token usage of the generated response. Resolved when the response is finished.
+   */
+  readonly usage: Promise<LanguageModelUsage>;
+
+  /**
+   * Additional provider-specific metadata. They are passed through
+   * from the provider to the AI SDK and enable provider-specific
+   * results that can be fully encapsulated in the provider.
+   */
+  readonly providerMetadata: Promise<ProviderMetadata | undefined>;
+
+  /**
+   * Additional request information from the last step.
+   */
+  readonly request: Promise<LanguageModelRequestMetadata>;
+
+  /**
+   * Additional response information.
+   */
+  readonly response: Promise<LanguageModelResponseMetadata>;
+
+  /**
+   * The reason why the generation finished. Taken from the last step.
+   *
+   * Resolved when the response is finished.
+   */
+  readonly finishReason: Promise<FinishReason>;
+
+  /**
+   * The generated object (typed according to the schema). Resolved when the response is finished.
+   */
+  readonly object: Promise<RESULT>;
+
+  /**
+   * Stream of partial objects. It gets more complete as the stream progresses.
+   *
+   * Note that the partial object is not validated.
+   * If you want to be certain that the actual content matches your schema, you need to implement your own validation for partial results.
+   */
+  readonly partialObjectStream: AsyncIterableStream<PARTIAL>;
+
+  /**
+   * Stream over complete array elements. Only available if the output strategy is set to `array`.
+   */
+  readonly elementStream: ELEMENT_STREAM;
+
+  /**
+   * Text stream of the JSON representation of the generated object. It contains text chunks.
+   * When the stream is finished, the object is valid JSON that can be parsed.
+   */
+  readonly textStream: AsyncIterableStream<string>;
+
+  /**
+   * Stream of different types of events, including partial objects, errors, and finish events.
+   * Only errors that stop the stream, such as network errors, are thrown.
+   */
+  readonly fullStream: AsyncIterableStream<ObjectStreamPart<PARTIAL>>;
+
+  /**
+   * Writes text delta output to a Node.js response-like object.
+   * It sets a `Content-Type` header to `text/plain; charset=utf-8` and
+   * writes each text delta as a separate chunk.
+   *
+   * @param response A Node.js response-like object (ServerResponse).
+   * @param init Optional headers, status code, and status text.
+   */
+  pipeTextStreamToResponse(response: ServerResponse, init?: ResponseInit): void;
+
+  /**
+   * Creates a simple text stream response.
+   * The response has a `Content-Type` header set to `text/plain; charset=utf-8`.
+   * Each text delta is encoded as UTF-8 and sent as a separate chunk.
+   * Non-text-delta events are ignored.
+   *
+   * @param init Optional headers, status code, and status text.
+   */
+  toTextStreamResponse(init?: ResponseInit): Response;
+}
+
+export type ObjectStreamPart<PARTIAL> =
+  | {
+      type: 'object';
+      object: PARTIAL;
+    }
+  | {
+      type: 'text-delta';
+      textDelta: string;
+    }
+  | {
+      type: 'error';
+      error: unknown;
+    }
+  | {
+      type: 'finish';
+      finishReason: FinishReason;
+      usage: LanguageModelUsage;
+      response: LanguageModelResponseMetadata;
+      providerMetadata?: ProviderMetadata;
+    };