Class StructuredOutputError

packages/effect/src/unstable/ai/AiError.ts:772–825

 * @since 4.0.0
 */
export class StructuredOutputError extends Schema.Error<StructuredOutputError>(
  "effect/ai/AiError/StructuredOutputError"
)({
  _tag: Schema.tag("StructuredOutputError"),
  description: Schema.String,
  responseText: Schema.String,
  metadata: providerMetadataWithDefaults<StructuredOutputErrorMetadata>(),
  usage: Schema.optional(UsageInfo)
}) {
  /**
   * Marks `StructuredOutputError` as a semantic AI error reason for runtime guards.
   *
   * @since 4.0.0
   */
  readonly [ReasonTypeId] = ReasonTypeId

  /**
   * Structured output errors are retryable since LLM outputs are non-deterministic.
   *
   * @since 4.0.0
   */
  get isRetryable(): boolean {
    return true
  }

  /**
   * Creates a StructuredOutputError from a Schema error.
   *
   * **Example** (Creating a structured output error from a schema error)
   *
   * ```ts import.meta.vitest
   * import { Effect, Schema } from "effect"
   * import { AiError } from "effect/unstable/ai"
   *
   * const schemaError = await Effect.runPromise(
   *   Schema.decodeUnknownEffect(Schema.Struct({ name: Schema.String }))({}).pipe(Effect.flip)
   * )
   * const parseError = AiError.StructuredOutputError.fromSchemaError(schemaError, "{}")
   * parseError.responseText // => "{}"
   * ```
   *
   * @since 4.0.0
   */
  static fromSchemaError(error: Schema.SchemaError, responseText: string): StructuredOutputError {
    return new StructuredOutputError({
      description: error.message,
      responseText
    })
  }

  override get message(): string {
    return `Structured output validation failed: ${this.description}`
  }
}

/**
 * Error indicating a codec transformer rejected a schema because it contains