effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/unstable/ai/AiError.ts

@@ -55,7 +55,7 @@ const redactHeaders = (headers: Record<string, string>): Record<string, string>
  *
  * **Example** (Creating a network error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.NetworkError({
@@ -70,12 +70,10 @@ const redactHeaders = (headers: Record<string, string>): Record<string, string>
  *   description: "Connection timeout after 30 seconds"
  * })
  *
- * console.log(error.isRetryable) // true
- * console.log(error.message)
- * // "Transport: Connection timeout after 30 seconds (POST https://api.openai.com/v1/completions)"
+ * const result = [error.reason, error.isRetryable] // => ["TransportError", true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class NetworkError extends Schema.ErrorClass<NetworkError>(
@@ -107,13 +105,17 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
    *
    * **Example** (Creating a network error from a request error)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { AiError } from "effect/unstable/ai"
-   * import type { HttpClientError } from "effect/unstable/http"
+   * import { HttpClientError, HttpClientRequest } from "effect/unstable/http"
    *
-   * declare const platformError: HttpClientError.RequestError
+   * const platformError = new HttpClientError.TransportError({
+   *   request: HttpClientRequest.get("https://example.com/models"),
+   *   description: "Connection refused"
+   * })
    *
    * const aiError = AiError.NetworkError.fromRequestError(platformError)
+   * aiError.reason // => "TransportError"
    * ```
    *
    * @since 4.0.0
@@ -184,7 +186,7 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
  *
  * **Example** (Inspecting metadata shape)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * const metadata = {
  *   openai: {
  *     errorCode: "rate_limit_exceeded",
@@ -192,6 +194,8 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
  *   },
  *   anthropic: null
  * }
+ *
+ * Array.of(metadata.openai.errorCode, metadata.anthropic) // => ["rate_limit_exceeded", null]
  * ```
  *
  * @category schemas
@@ -351,7 +355,7 @@ export const HttpContext = Schema.Struct({
  *
  * **Example** (Creating a rate limit error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
  *
@@ -359,11 +363,10 @@ export const HttpContext = Schema.Struct({
  *   retryAfter: Duration.seconds(60)
  * })
  *
- * console.log(rateLimitError.isRetryable) // true
- * console.log(rateLimitError.message) // "Rate limit exceeded. Retry after 1 minute"
+ * const result = [rateLimitError._tag, rateLimitError.isRetryable] // => ["RateLimitError", true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class RateLimitError extends Schema.ErrorClass<RateLimitError>(
@@ -406,17 +409,15 @@ export class RateLimitError extends Schema.ErrorClass<RateLimitError>(
  *
  * **Example** (Creating a quota exhausted error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const quotaError = new AiError.QuotaExhaustedError({})
  *
- * console.log(quotaError.isRetryable) // false
- * console.log(quotaError.message)
- * // "Quota exhausted. Check your account billing and usage limits."
+ * const result = [quotaError._tag, quotaError.isRetryable] // => ["QuotaExhaustedError", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class QuotaExhaustedError extends Schema.ErrorClass<QuotaExhaustedError>(
@@ -459,19 +460,17 @@ export class QuotaExhaustedError extends Schema.ErrorClass<QuotaExhaustedError>(
  *
  * **Example** (Creating an authentication error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const authError = new AiError.AuthenticationError({
  *   kind: "InvalidKey"
  * })
  *
- * console.log(authError.isRetryable) // false
- * console.log(authError.message)
- * // "InvalidKey: Verify your API key is correct"
+ * const result = [authError.kind, authError.isRetryable] // => ["InvalidKey", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class AuthenticationError extends Schema.ErrorClass<AuthenticationError>(
@@ -519,19 +518,17 @@ export class AuthenticationError extends Schema.ErrorClass<AuthenticationError>(
  *
  * **Example** (Creating a content policy error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const policyError = new AiError.ContentPolicyError({
  *   description: "Input contains prohibited content"
  * })
  *
- * console.log(policyError.isRetryable) // false
- * console.log(policyError.message)
- * // "Content policy violation: Input contains prohibited content"
+ * const result = [policyError.description, policyError.isRetryable] // => ["Input contains prohibited content", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
@@ -572,7 +569,7 @@ export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
  *
  * **Example** (Creating an invalid request error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const invalidRequestError = new AiError.InvalidRequestError({
@@ -581,12 +578,10 @@ export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
  *   description: "Temperature value 5 is out of range"
  * })
  *
- * console.log(invalidRequestError.isRetryable) // false
- * console.log(invalidRequestError.message)
- * // "Invalid request: parameter 'temperature' must be between 0 and 2. Temperature value 5 is out of range"
+ * const result = [invalidRequestError.parameter, invalidRequestError.isRetryable] // => ["temperature", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class InvalidRequestError extends Schema.ErrorClass<InvalidRequestError>(
@@ -633,19 +628,17 @@ export class InvalidRequestError extends Schema.ErrorClass<InvalidRequestError>(
  *
  * **Example** (Creating an internal provider error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const providerError = new AiError.InternalProviderError({
  *   description: "Server encountered an unexpected error"
  * })
  *
- * console.log(providerError.isRetryable) // true
- * console.log(providerError.message)
- * // "Internal provider error: Server encountered an unexpected error"
+ * const result = [providerError.description, providerError.isRetryable] // => ["Server encountered an unexpected error", true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class InternalProviderError extends Schema.ErrorClass<InternalProviderError>(
@@ -686,19 +679,17 @@ export class InternalProviderError extends Schema.ErrorClass<InternalProviderErr
  *
  * **Example** (Creating an invalid output error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const parseError = new AiError.InvalidOutputError({
  *   description: "Expected a string but received a number"
  * })
  *
- * console.log(parseError.isRetryable) // true
- * console.log(parseError.message)
- * // "Invalid output: Expected a string but received a number"
+ * const result = [parseError.description, parseError.isRetryable] // => ["Expected a string but received a number", true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
@@ -730,13 +721,15 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
    *
    * **Example** (Creating an invalid output error from a schema error)
    *
-   * ```ts
-   * import { Schema } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, Schema } from "effect"
    * import { AiError } from "effect/unstable/ai"
    *
-   * declare const schemaError: Schema.SchemaError
-   *
+   * const schemaError = await Effect.runPromise(
+   *   Schema.decodeUnknownEffect(Schema.Number)("not a number").pipe(Effect.flip)
+   * )
    * const parseError = AiError.InvalidOutputError.fromSchemaError(schemaError)
+   * parseError.description // => "Expected number"
    * ```
    *
    * @since 4.0.0
@@ -762,7 +755,7 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
  *
  * **Example** (Creating a structured output error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.StructuredOutputError({
@@ -770,12 +763,10 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
  *   responseText: "{\"foo\":}"
  * })
  *
- * console.log(error.isRetryable) // true
- * console.log(error.message)
- * // "Structured output validation failed: Expected a valid JSON object"
+ * const result = [error.description, error.responseText, error.isRetryable] // => ["Expected a valid JSON object", '{"foo":}', true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputError>(
@@ -808,14 +799,15 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
    *
    * **Example** (Creating a structured output error from a schema error)
    *
-   * ```ts
-   * import { Schema } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, Schema } from "effect"
    * import { AiError } from "effect/unstable/ai"
    *
-   * declare const schemaError: Schema.SchemaError
-   * declare const rawText: string
-   *
-   * const parseError = AiError.StructuredOutputError.fromSchemaError(schemaError, rawText)
+   * 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
@@ -843,19 +835,17 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
  *
  * **Example** (Creating an unsupported schema error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.UnsupportedSchemaError({
  *   description: "Unions are not supported in Anthropic structured output"
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Unsupported schema: Unions are not supported in Anthropic structured output"
+ * const result = [error.description, error.isRetryable] // => ["Unions are not supported in Anthropic structured output", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaError>(
@@ -895,19 +885,17 @@ export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaE
  *
  * **Example** (Creating an unknown error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const unknownError = new AiError.UnknownError({
  *   description: "An unexpected error occurred"
  * })
  *
- * console.log(unknownError.isRetryable) // false
- * console.log(unknownError.message)
- * // "An unexpected error occurred"
+ * const result = [unknownError.description, unknownError.isRetryable] // => ["An unexpected error occurred", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class UnknownError extends Schema.ErrorClass<UnknownError>(
@@ -953,7 +941,7 @@ export class UnknownError extends Schema.ErrorClass<UnknownError>(
  *
  * **Example** (Creating a tool not found error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolNotFoundError({
@@ -961,12 +949,10 @@ export class UnknownError extends Schema.ErrorClass<UnknownError>(
  *   availableTools: ["GetWeather", "GetTime"]
  * })
  *
- * console.log(error.isRetryable) // true
- * console.log(error.message)
- * // "Tool 'unknownTool' not found. Available tools: GetWeather, GetTime"
+ * const result = [error.toolName, error.availableTools, error.isRetryable] // => ["unknownTool", ["GetWeather", "GetTime"], true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
@@ -1008,7 +994,7 @@ export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
  *
  * **Example** (Creating a tool parameter validation error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolParameterValidationError({
@@ -1017,12 +1003,10 @@ export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
  *   description: "Expected string, got number"
  * })
  *
- * console.log(error.isRetryable) // true
- * console.log(error.message)
- * // "Invalid parameters for tool 'GetWeather': Expected string, got number"
+ * const result = [error.toolName, error.description, error.isRetryable] // => ["GetWeather", "Expected string, got number", true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class ToolParameterValidationError extends Schema.ErrorClass<ToolParameterValidationError>(
@@ -1065,7 +1049,7 @@ export class ToolParameterValidationError extends Schema.ErrorClass<ToolParamete
  *
  * **Example** (Creating an invalid tool result error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.InvalidToolResultError({
@@ -1073,12 +1057,10 @@ export class ToolParameterValidationError extends Schema.ErrorClass<ToolParamete
  *   description: "Tool handler returned invalid result: missing 'temperature' field"
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Tool 'GetWeather' returned invalid result: missing 'temperature' field"
+ * const result = [error.toolName, error.isRetryable] // => ["GetWeather", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultError>(
@@ -1119,7 +1101,7 @@ export class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultE
  *
  * **Example** (Creating a tool result encoding error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolResultEncodingError({
@@ -1128,12 +1110,10 @@ export class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultE
  *   description: "Cannot encode bigint values as JSON"
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Failed to encode result for tool 'GetWeather': Cannot encode bigint values as JSON"
+ * const result = [error.toolName, error.description, error.isRetryable] // => ["GetWeather", "Cannot encode bigint values as JSON", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodingError>(
@@ -1175,7 +1155,7 @@ export class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodin
  *
  * **Example** (Creating a tool configuration error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolConfigurationError({
@@ -1183,12 +1163,10 @@ export class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodin
  *   description: "Invalid container ID format"
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Invalid configuration for tool 'OpenAiCodeInterpreter': Invalid container ID format"
+ * const result = [error.toolName, error.description, error.isRetryable] // => ["OpenAiCodeInterpreter", "Invalid container ID format", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class ToolConfigurationError extends Schema.ErrorClass<ToolConfigurationError>(
@@ -1229,19 +1207,17 @@ export class ToolConfigurationError extends Schema.ErrorClass<ToolConfigurationE
  *
  * **Example** (Creating a toolkit required error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolkitRequiredError({
  *   pendingApprovals: ["GetWeather", "SendEmail"]
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Toolkit required to resolve pending tool approvals: GetWeather, SendEmail"
+ * const result = [error.pendingApprovals, error.isRetryable] // => [["GetWeather", "SendEmail"], false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class ToolkitRequiredError extends Schema.ErrorClass<ToolkitRequiredError>(
@@ -1284,19 +1260,17 @@ export class ToolkitRequiredError extends Schema.ErrorClass<ToolkitRequiredError
  *
  * **Example** (Creating an invalid user input error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.InvalidUserInputError({
  *   description: "Unsupported media type 'video/mp4'. Supported types include images, application/pdf, text/plain"
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Invalid user input: Unsupported media type 'video/mp4'. Supported types include images, application/pdf, text/plain"
+ * const result = [error._tag, error.isRetryable] // => ["InvalidUserInputError", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export class InvalidUserInputError extends Schema.ErrorClass<InvalidUserInputError>(
@@ -1339,7 +1313,7 @@ export class InvalidUserInputError extends Schema.ErrorClass<InvalidUserInputErr
  * `isRetryable` getter. Provider-facing reasons may also include retry timing,
  * provider metadata, usage information, or HTTP context.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export type AiErrorReason =
@@ -1439,11 +1413,15 @@ const TypeId = "~effect/unstable/ai/AiError/AiError" as const
  *
  * **Example** (Handling an AI error by tag)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Duration, Effect } from "effect"
  * import { AiError } from "effect/unstable/ai"
  *
- * declare const aiOperation: Effect.Effect<string, AiError.AiError>
+ * const aiOperation = Effect.fail(new AiError.AiError({
+ *   module: "OpenAI",
+ *   method: "generateText",
+ *   reason: new AiError.RateLimitError({ retryAfter: Duration.seconds(30) })
+ * }))
  *
  * // Handle specific reason types
  * const handled = aiOperation.pipe(
@@ -1454,6 +1432,8 @@ const TypeId = "~effect/unstable/ai/AiError/AiError" as const
  *     return Effect.fail(error)
  *   })
  * )
+ *
+ * await Effect.runPromise(handled) // => "Retry after 30000 millis"
  * ```
  *
  * @category schemas
@@ -1506,7 +1486,7 @@ export type AiErrorEncoded = typeof AiError["Encoded"]
  *
  * **Example** (Checking for an AI error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const someError = new Error("generic error")
@@ -1516,8 +1496,7 @@ export type AiErrorEncoded = typeof AiError["Encoded"]
  *   reason: new AiError.RateLimitError({})
  * })
  *
- * console.log(AiError.isAiError(someError)) // false
- * console.log(AiError.isAiError(aiError)) // true
+ * const result = [AiError.isAiError(someError), AiError.isAiError(aiError)] // => [false, true]
  * ```
  *
  * @category guards
@@ -1530,14 +1509,13 @@ export const isAiError = (u: unknown): u is AiError => Predicate.hasProperty(u,
  *
  * **Example** (Checking for an AI error reason)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const rateLimitError = new AiError.RateLimitError({})
  * const genericError = new Error("generic error")
  *
- * console.log(AiError.isAiErrorReason(rateLimitError)) // true
- * console.log(AiError.isAiErrorReason(genericError)) // false
+ * const result = [AiError.isAiErrorReason(rateLimitError), AiError.isAiErrorReason(genericError)] // => [true, false]
  * ```
  *
  * @category guards
@@ -1550,7 +1528,7 @@ export const isAiErrorReason = (u: unknown): u is AiErrorReason => Predicate.has
  *
  * **Example** (Creating an AI error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1562,8 +1540,7 @@ export const isAiErrorReason = (u: unknown): u is AiErrorReason => Predicate.has
  *   })
  * })
  *
- * console.log(error.message)
- * // "OpenAI.completion: Rate limit exceeded. Retry after 1 minute"
+ * const result = [error.module, error.method, error.reason._tag] // => ["OpenAI", "completion", "RateLimitError"]
  * ```
  *
  * @category constructors
@@ -1585,7 +1562,7 @@ export const make = (params: {
  *
  * **Example** (Mapping an HTTP status to a reason)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const reason = AiError.reasonFromHttpStatus({
@@ -1593,7 +1570,7 @@ export const make = (params: {
  *   body: { error: "Rate limit exceeded" }
  * })
  *
- * console.log(reason._tag) // "RateLimitError"
+ * reason._tag // => "RateLimitError"
  * ```
  *
  * @category constructors

package/src/unstable/ai/AnthropicStructuredOutput.ts

@@ -48,7 +48,7 @@ import * as OpenAiStructuredOutput from "./OpenAiStructuredOutput.ts"
  * @see {@link LanguageModel.CodecTransformer} for the structured-output transformer contract
  * @see {@link OpenAiStructuredOutput.toCodecOpenAI} for the OpenAI-specific transformer
  *
- * @category Codec Transformation
+ * @category transforming
  * @since 4.0.0
  */
 export function toCodecAnthropic<T, E, RD, RE>(