effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/unstable/ai/AiError.ts

@@ -115,6 +115,8 @@ const redactHeaders = (headers: Record<string, string>): Record<string, string>
 /**
  * Error indicating a network-level failure before receiving a response.
  *
+ * **Details**
+ *
  * This error is raised when issues arise before receiving an HTTP response,
  * such as network connectivity problems, request encoding issues, or invalid
  * URLs.
@@ -243,13 +245,20 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
 /**
  * Schema for provider-specific metadata which can be attached to error reasons.
  *
- * Provider-specific metadata is namespaced by provider and has the structure:
+ * **Details**
  *
- * ```
- * {
- *   "<provider-name>": {
- *     // Provider-specific metadata (e.g. errorCode, requestId, etc.)
- *   }
+ * Provider-specific metadata is namespaced by provider name. Each provider
+ * value can contain arbitrary mutable JSON metadata or `null`.
+ *
+ * **Example** (Metadata shape)
+ *
+ * ```ts
+ * const metadata = {
+ *   openai: {
+ *     errorCode: "rate_limit_exceeded",
+ *     requestId: "req_123"
+ *   },
+ *   anthropic: null
  * }
  * ```
  *
@@ -264,6 +273,8 @@ export const ProviderMetadata: Schema.$Record<
 /**
  * Type of provider-specific metadata attached to AI error reasons.
  *
+ * **Details**
+ *
  * Metadata is keyed by provider name, and each provider value is either mutable
  * JSON metadata or `null`.
  *
@@ -383,6 +394,8 @@ export const HttpContext = Schema.Struct({
 /**
  * Error indicating the request was rate limited.
  *
+ * **Details**
+ *
  * Rate limit errors are always retryable. When `retryAfter` is provided,
  * callers should wait that duration before retrying.
  *
@@ -437,6 +450,8 @@ export class RateLimitError extends Schema.ErrorClass<RateLimitError>(
 /**
  * Error indicating account or billing limits have been reached.
  *
+ * **Details**
+ *
  * Quota exhausted errors are not retryable without user action.
  *
  * **Example** (Creating a quota exhausted error)
@@ -488,6 +503,8 @@ export class QuotaExhaustedError extends Schema.ErrorClass<QuotaExhaustedError>(
 /**
  * Error indicating authentication or authorization failure.
  *
+ * **Details**
+ *
  * Authentication errors are never retryable without credential changes.
  *
  * **Example** (Creating an authentication error)
@@ -546,6 +563,8 @@ export class AuthenticationError extends Schema.ErrorClass<AuthenticationError>(
 /**
  * Error indicating content policy violation.
  *
+ * **Details**
+ *
  * Content policy errors are never retryable without content changes.
  *
  * **Example** (Creating a content policy error)
@@ -597,6 +616,8 @@ export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
 /**
  * Error indicating the request had invalid or malformed parameters.
  *
+ * **Details**
+ *
  * Invalid request errors require fixing the request and are not retryable.
  *
  * **Example** (Creating an invalid request error)
@@ -656,6 +677,8 @@ export class InvalidRequestError extends Schema.ErrorClass<InvalidRequestError>(
 /**
  * Error indicating the AI provider experienced an internal error.
  *
+ * **Details**
+ *
  * Internal provider errors are typically transient and are retryable.
  *
  * **Example** (Creating an internal provider error)
@@ -707,6 +730,8 @@ export class InternalProviderError extends Schema.ErrorClass<InternalProviderErr
 /**
  * Error indicating failure to parse or validate LLM output.
  *
+ * **Details**
+ *
  * Invalid output errors are retryable since LLM outputs are non-deterministic.
  *
  * **Example** (Creating an invalid output error)
@@ -781,6 +806,8 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
  * Error indicating the LLM generated text that does not conform to the
  * requested structured output schema.
  *
+ * **Details**
+ *
  * Structured output errors are retryable since LLM outputs are non-deterministic.
  *
  * **Example** (Creating a structured output error)
@@ -859,6 +886,8 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
  * Error indicating a codec transformer rejected a schema because it contains
  * unsupported constructs.
  *
+ * **Details**
+ *
  * Unsupported schema errors are not retryable because they indicate a
  * programmer error where the schema is incompatible with the provider.
  *
@@ -910,6 +939,8 @@ export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaE
 /**
  * Catch-all error for unknown or unexpected errors.
  *
+ * **Details**
+ *
  * Unknown errors are not retryable by default since the cause is unknown.
  *
  * **Example** (Creating an unknown error)
@@ -965,6 +996,8 @@ export class UnknownError extends Schema.ErrorClass<UnknownError>(
 /**
  * Error indicating the model requested a tool that doesn't exist in the toolkit.
  *
+ * **Details**
+ *
  * This error is retryable because the model may self-correct when provided
  * with the list of available tools.
  *
@@ -1018,6 +1051,8 @@ export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
 /**
  * Error indicating the model's tool call parameters failed schema validation.
  *
+ * **Details**
+ *
  * This error is retryable because the model may correct its parameters
  * on subsequent attempts.
  *
@@ -1073,6 +1108,8 @@ export class ToolParameterValidationError extends Schema.ErrorClass<ToolParamete
  * Error indicating the tool handler returned an invalid result that does not
  * match the tool's schema.
  *
+ * **Details**
+ *
  * This error is not retryable because invalid results indicate a bug in the
  * tool handler implementation.
  *
@@ -1125,6 +1162,8 @@ export class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultE
 /**
  * Error indicating the tool result cannot be encoded for sending back to the model.
  *
+ * **Details**
+ *
  * This error is not retryable because encoding failures indicate a bug in the
  * tool schema definitions.
  *
@@ -1179,6 +1218,8 @@ export class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodin
 /**
  * Error indicating a provider-defined tool was configured with invalid arguments.
  *
+ * **Details**
+ *
  * This error is not retryable because it indicates a programming error in the
  * tool configuration that must be fixed in code.
  *
@@ -1231,6 +1272,8 @@ export class ToolConfigurationError extends Schema.ErrorClass<ToolConfigurationE
 /**
  * Error indicating an operation requires a toolkit but none was provided.
  *
+ * **Details**
+ *
  * This error occurs when tool approval responses are present in the prompt
  * but no toolkit was provided to resolve them.
  *
@@ -1283,6 +1326,8 @@ export class ToolkitRequiredError extends Schema.ErrorClass<ToolkitRequiredError
 /**
  * Error indicating the user provided invalid input in their prompt.
  *
+ * **Details**
+ *
  * This error is raised when the prompt contains content that is structurally
  * valid but not supported by the provider (e.g., unsupported media types,
  * unsupported file formats, etc.).
@@ -1338,6 +1383,8 @@ export class InvalidUserInputError extends Schema.ErrorClass<InvalidUserInputErr
 /**
  * Union type of all semantic error reasons that can occur during AI operations.
  *
+ * **Details**
+ *
  * Every reason carries a semantic `_tag`, a human-readable message, and an
  * `isRetryable` getter. Provider-facing reasons may also include retry timing,
  * provider metadata, usage information, or HTTP context.
@@ -1420,12 +1467,14 @@ const TypeId = "~effect/unstable/ai/AiError/AiError" as const
 /**
  * Top-level AI error wrapper using the `reason` pattern.
  *
- * This error wraps semantic error reasons and provides:
- * - `module` and `method` context for where the error occurred
- * - `reason` field containing the semantic error type
- * - Delegated `isRetryable` and `retryAfter` to the underlying reason
+ * **When to use**
  *
- * Use with `Effect.catchReason` for ergonomic error handling:
+ * Use with `Effect.catchReason` for ergonomic error handling.
+ *
+ * **Details**
+ *
+ * This error stores `module` and `method` context, the semantic `reason`, and
+ * delegates `isRetryable` and `retryAfter` to the underlying reason.
  *
  * **Example** (Handling an AI error by tag)
  *
@@ -1568,6 +1617,8 @@ export const make = (params: {
 /**
  * Maps HTTP status codes to semantic error reasons.
  *
+ * **When to use**
+ *
  * Provider packages can use this as a base for provider-specific mapping.
  *
  * **Example** (Mapping an HTTP status to a reason)

package/src/unstable/ai/AnthropicStructuredOutput.ts

@@ -25,11 +25,11 @@ import * as Transformation from "../../SchemaTransformation.ts"
 import * as Tool from "./Tool.ts"
 
 /**
- * Transforms a `Schema.Codec` into a form compatible with Anthropic's
- * structured output constraints.
+ * Transforms a `Schema.Codec` into a form compatible with Anthropic's structured output constraints.
  *
- * The transformation walks the schema AST and rewrites constructs that
- * Anthropic does not support natively:
+ * **Details**
+ *
+ * The transformation walks the schema AST and rewrites constructs that Anthropic does not support natively:
  *
  * - **Tuples** are converted to objects with numeric string keys (e.g.
  *   `"0"`, `"1"`) since Anthropic does not support tuple schemas. Rest

package/src/unstable/ai/Chat.ts

@@ -71,6 +71,8 @@ import type * as Tool from "./Tool.ts"
 /**
  * The `Chat` service tag for dependency injection.
  *
+ * **Details**
+ *
  * This tag provides access to chat functionality throughout your application,
  * enabling persistent conversational AI interactions with full context
  * management.
@@ -107,6 +109,8 @@ export interface Service {
   /**
    * Reference to the chat history.
    *
+   * **Details**
+   *
    * Provides direct access to the conversation history for advanced use cases
    * like custom history manipulation or inspection.
    *
@@ -129,6 +133,8 @@ export interface Service {
   /**
    * Exports the chat history into a structured format.
    *
+   * **Details**
+   *
    * Returns the complete conversation history as a structured object
    * that can be stored, transmitted, or processed by other systems.
    *
@@ -154,6 +160,8 @@ export interface Service {
   /**
    * Exports the chat history as a JSON string.
    *
+   * **Details**
+   *
    * Provides a convenient way to serialize the entire conversation
    * for storage or transmission in JSON format.
    *
@@ -181,6 +189,8 @@ export interface Service {
   /**
    * Generate text using a language model for the specified prompt.
    *
+   * **Details**
+   *
    * If a toolkit is specified, the language model will have access to tools
    * for function calling and enhanced capabilities. Both input and output
    * messages are automatically added to the chat history.
@@ -247,6 +257,8 @@ export interface Service {
   /**
    * Generate text using a language model with streaming output.
    *
+   * **Details**
+   *
    * Returns a stream of response parts that are emitted as soon as they're
    * available from the model. Supports tool calling and maintains chat history.
    *
@@ -311,6 +323,8 @@ export interface Service {
   /**
    * Generate a structured object using a language model and schema.
    *
+   * **Details**
+   *
    * Forces the model to return data that conforms to the specified schema,
    * enabling structured data extraction and type-safe responses. The
    * conversation history is maintained across calls.
@@ -465,6 +479,8 @@ const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
 /**
  * Creates a new Chat service with empty conversation history.
  *
+ * **When to use**
+ *
  * This is the most common way to start a fresh chat session without
  * any initial context or system prompts.
  *
@@ -495,6 +511,8 @@ export const empty: Effect.Effect<Service> = Effect.sync(() => makeUnsafe(Ref.ma
 /**
  * Creates a new Chat service from an initial prompt.
  *
+ * **Details**
+ *
  * This is the primary constructor for creating chat instances. It initializes
  * a new conversation with the provided prompt as the starting context.
  *
@@ -558,6 +576,8 @@ export const fromPrompt = (prompt: Prompt.RawInput) =>
 /**
  * Creates a Chat service from previously exported chat data.
  *
+ * **Details**
+ *
  * Restores a chat session from structured data that was previously exported
  * using the `export` method. Useful for persisting and restoring conversation
  * state.
@@ -609,6 +629,8 @@ export const fromExport = (data: unknown): Effect.Effect<
 /**
  * Creates a Chat service from previously exported JSON chat data.
  *
+ * **Details**
+ *
  * Restores a chat session from JSON string that was previously exported
  * using the `exportJson` method. This is the most convenient way to
  * persist and restore chat sessions to/from storage systems.
@@ -715,6 +737,8 @@ export declare namespace Persistence {
 /**
  * Represents a `Chat` that is backed by persistence.
  *
+ * **Details**
+ *
  * When calling a text generation method (e.g. `generateText`), the previous
  * chat history as well as the relevent response parts will be saved to the
  * backing persistence store.
@@ -737,6 +761,8 @@ export interface Persisted extends Service {
 /**
  * Creates a new chat persistence service.
  *
+ * **Details**
+ *
  * The provided store identifier will be used to indicate which "store" the
  * backing persistence should load chats from.
  *
@@ -888,7 +914,9 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
 })
 
 /**
- * Creates a `Layer` new chat persistence service.
+ * Creates a `Layer` for a new chat persistence service.
+ *
+ * **Details**
  *
  * The provided store identifier will be used to indicate which "store" the
  * backing persistence should load chats from.

package/src/unstable/ai/IdGenerator.ts

@@ -57,6 +57,8 @@ import * as Random from "../../Random.ts"
 /**
  * The `IdGenerator` service tag for dependency injection.
  *
+ * **Details**
+ *
  * This tag is used to provide and access ID generation functionality throughout
  * the application. It follows Effect's standard service pattern for type-safe
  * dependency injection.
@@ -84,6 +86,8 @@ export class IdGenerator extends Context.Service<IdGenerator, Service>()(
 /**
  * The service interface for ID generation.
  *
+ * **Details**
+ *
  * Defines the contract that all ID generator implementations must fulfill.
  * The service provides a single method for generating unique identifiers
  * in an effectful context.
@@ -183,6 +187,8 @@ const makeGenerator = ({
 /**
  * Default ID generator service implementation.
  *
+ * **Details**
+ *
  * Uses the standard configuration with "id" prefix and generates IDs in the
  * format "id_XXXXXXXXXXXXXXXX" where X represents random alphanumeric
  * characters.
@@ -218,6 +224,8 @@ export const defaultIdGenerator: Service = {
 /**
  * Creates a custom ID generator service with the specified options.
  *
+ * **Details**
+ *
  * Validates the configuration to ensure the separator is not part of the
  * alphabet, which would cause ambiguity in parsing generated IDs.
  *
@@ -291,6 +299,8 @@ export const make = Effect.fnUntraced(function*({
  * Creates a Layer that provides the IdGenerator service with custom
  * configuration.
  *
+ * **When to use**
+ *
  * This is the recommended way to provide ID generation capabilities to your
  * application. The layer will fail during construction if the configuration is
  * invalid.

package/src/unstable/ai/LanguageModel.ts

@@ -82,11 +82,7 @@ import * as Toolkit from "./Toolkit.ts"
 // =============================================================================
 
 /**
- * The `LanguageModel` service key for dependency injection.
- *
- * This provides access to language model functionality throughout your
- * application, enabling text generation, streaming, and structured output
- * capabilities.
+ * The `LanguageModel` service key for dependency injection, providing access to text generation, streaming, and structured output capabilities throughout an application.
  *
  * **Example** (Accessing the language model service)
  *
@@ -111,10 +107,7 @@ export class LanguageModel extends Context.Service<LanguageModel, Service>()(
 ) {}
 
 /**
- * The service interface for language model operations.
- *
- * Defines the contract that all language model implementations must fulfill,
- * providing text generation, structured output, and streaming capabilities.
+ * The service interface for language model operations, defining the contract that all language model implementations must fulfill.
  *
  * @category models
  * @since 4.0.0
@@ -221,8 +214,9 @@ export interface Service {
 }
 
 /**
- * A function that transforms a `Schema.Codec` into a provider-compatible form
- * for structured output generation.
+ * A function that transforms a `Schema.Codec` into a provider-compatible form for structured output generation.
+ *
+ * **Details**
  *
  * Different language model providers have varying constraints on the JSON
  * schemas they accept. A `CodecTransformer` rewrites a codec's encoded side to
@@ -288,15 +282,13 @@ export interface GenerateTextOptions<Tools extends Record<string, Tool.Any>> {
   readonly concurrency?: Concurrency | undefined
 
   /**
-   * When set to `true`, tool calls requested by the large language model
-   * will not be auto-resolved by the framework.
+   * When set to `true`, tool calls requested by the large language model are not auto-resolved by the framework.
+   *
+   * **When to use**
    *
-   * This option is useful when:
-   *   1. The user wants to include tool call definitions from an `AiToolkit`
-   *      in requests to the large language model so that the model has the
-   *      capability to call tools
-   *   2. The user wants to control the execution of tool call resolvers
-   *      instead of having the framework handle tool call resolution
+   * Use this when you want to include tool call definitions from an `AiToolkit`
+   * in requests to the large language model, while controlling tool call
+   * resolver execution yourself.
    */
   readonly disableToolCallResolution?: boolean | undefined
 }
@@ -358,11 +350,7 @@ export type ToolChoice<ToolName extends string> =
   }
 
 /**
- * Response class for text generation operations.
- *
- * Contains the generated content and provides convenient accessors for
- * extracting different types of response parts like text, tool calls, and usage
- * information.
+ * Response class for text generation operations, with accessors for extracting text, tool calls, usage information, and other response parts from generated content.
  *
  * **Example** (Inspecting a text response)
  *
@@ -544,6 +532,8 @@ export type ToolkitOption<
 /**
  * The supported toolkit input shapes for language model operation options.
  *
+ * **Details**
+ *
  * Unlike `ToolkitOption`, this type does not distribute over unions. It is
  * intended for call-site assignability, while `ToolkitOption` remains the
  * distributive helper used for extraction and inference.
@@ -624,6 +614,8 @@ type ExtractToolkitResolutionServices<ToolkitValue> = ToolkitValue extends Effec
 /**
  * Utility type that extracts the error type from LanguageModel options.
  *
+ * **Details**
+ *
  * Automatically infers the possible error types based on toolkit configuration
  * and tool call resolution settings.
  *
@@ -645,6 +637,8 @@ export type ExtractError<Options> = Options extends {
 /**
  * Utility type that extracts the context requirements from LanguageModel options.
  *
+ * **Details**
+ *
  * Automatically infers the required services based on the toolkit configuration.
  *
  * @category utility types
@@ -663,8 +657,9 @@ export type ExtractServices<Options> = Options extends {
 // =============================================================================
 
 /**
- * Configuration options passed along to language model provider
- * implementations.
+ * Configuration options passed along to language model provider implementations.
+ *
+ * **Details**
  *
  * This interface defines the normalized options that are passed to the
  * underlying provider implementation, regardless of the specific provider being
@@ -686,15 +681,14 @@ export interface ProviderOptions {
   readonly tools: ReadonlyArray<Tool.Any>
 
   /**
-   * The format which the response should be provided in.
+   * The format the response should be provided in.
    *
-   * If `"text"` is specified, the large language model response will be
-   * returned as text.
+   * **Details**
    *
-   * If `"json"` is specified, the large language model respose will be provided
-   * as an JSON object that conforms to the shape of the specified schema.
-   *
-   * Defaults to `{ type: "text" }`.
+   * If `"text"` is specified, the large language model response is returned as
+   * text. If `"json"` is specified, the large language model response is
+   * provided as a JSON object that conforms to the shape of the specified schema.
+   * The default is `{ type: "text" }`.
    */
   readonly responseFormat:
     | {
@@ -740,31 +734,21 @@ export interface ProviderOptions {
 }
 
 /**
- * Creates a LanguageModel service from provider-specific implementations.
- *
- * This constructor takes provider-specific implementations for text generation
- * and streaming text generation and returns a LanguageModel service.
+ * Creates a LanguageModel service from provider-specific text generation and streaming implementations.
  *
  * @category constructors
  * @since 4.0.0
  */
 export const make: (params: {
   /**
-   * A method which requests text generation from the large language model
-   * provider.
-   *
-   * The final result is returned when the large language model provider
-   * finishes text generation.
+   * A method that requests text generation from the large language model provider and returns the final result when generation finishes.
    */
   readonly generateText: (
     options: ProviderOptions
   ) => Effect.Effect<Array<Response.PartEncoded>, AiError.AiError, IdGenerator>
 
   /**
-   * A method which requests text generation from the large language model
-   * provider.
-   *
-   * Intermediate results are streamed from the large language model provider.
+   * A method that requests text generation from the large language model provider and streams intermediate results.
    */
   readonly streamText: (
     options: ProviderOptions
@@ -1721,6 +1705,8 @@ export const generateObject = <
 /**
  * Generate text using a language model with streaming output.
  *
+ * **Details**
+ *
  * Returns a stream of response parts that are emitted as soon as they are
  * available from the model, enabling real-time text generation experiences.
  *