@effect/ai-anthropic 4.0.0-beta.7 → 4.0.0-beta.71

package/src/AnthropicLanguageModel.ts

@@ -1,18 +1,45 @@
 /**
- * @since 1.0.0
+ * The `AnthropicLanguageModel` module provides the Anthropic implementation of
+ * Effect AI's `LanguageModel` service. It turns Effect AI prompts, tools, files,
+ * reasoning parts, and provider options into Anthropic Messages API requests,
+ * and converts Anthropic responses and streams back into Effect AI response
+ * parts with Anthropic-specific metadata.
+ *
+ * **When to use**
+ *
+ * Use when create an Anthropic-backed model with {@link model}
+ * - Build or provide a `LanguageModel.LanguageModel` layer with {@link layer}
+ *   or {@link make}
+ * - Supply default request options through {@link Config}
+ * - Override configuration for a scoped operation with {@link withConfigOverride}
+ * - Attach Anthropic provider options for prompt caching, document citations,
+ *   reasoning signatures, MCP metadata, and server-side tools
+ *
+ * **Gotchas**
+ *
+ * - Prompt files are translated to Anthropic image or document blocks; only the
+ *   supported media types can be sent to the provider.
+ * - Structured output support depends on the selected Claude model, so this
+ *   module may use Anthropic's native structured output or fall back to a JSON
+ *   response tool.
+ * - Some features require Anthropic beta headers, which are added
+ *   automatically from the selected tools, files, and model capabilities.
+ *
+ * @since 4.0.0
  */
 /** @effect-diagnostics preferSchemaOverJson:skip-file */
 import * as Arr from "effect/Array"
+import * as Context from "effect/Context"
 import * as DateTime from "effect/DateTime"
 import * as Effect from "effect/Effect"
 import * as Encoding from "effect/Encoding"
 import { dual } from "effect/Function"
 import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
 import * as Predicate from "effect/Predicate"
 import * as Redactable from "effect/Redactable"
 import * as Schema from "effect/Schema"
 import * as SchemaAST from "effect/SchemaAST"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 import type { Span } from "effect/Tracer"
 import type { Mutable, Simplify } from "effect/Types"
@@ -33,10 +60,16 @@ import type * as Generated from "./Generated.ts"
 import * as InternalUtilities from "./internal/utilities.ts"
 
 /**
- * The available Anthropic Claude model identifiers.
+ * Known Anthropic Claude model identifiers exposed by the generated Anthropic schema.
+ *
+ * **Details**
+ *
+ * The Anthropic language model constructors accept `Model` values and custom
+ * string model ids, so this type is best used for autocomplete and type checking
+ * of known Claude ids.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Model = typeof Generated.Model.Type
 
@@ -47,13 +80,20 @@ export type Model = typeof Generated.Model.Type
 /**
  * Configuration options for the Anthropic language model.
  *
+ * **When to use**
+ *
+ * Use when you need to provide or override Anthropic model configuration on a
+ * per-request basis via `Context.Service`.
+ *
+ * **Details**
+ *
  * This service can be used to provide default configuration values or to
  * override configuration on a per-request basis.
  *
- * @since 1.0.0
  * @category configuration
+ * @since 4.0.0
  */
-export class Config extends ServiceMap.Service<
+export class Config extends Context.Service<
   Config,
   Simplify<
     & Partial<
@@ -73,6 +113,8 @@ export class Config extends ServiceMap.Service<
       /**
        * Whether to use strict JSON schema validation for tool calls.
        *
+       * **Details**
+       *
        * Only applies to models that support structured outputs. Defaults to
        * `true` when structured outputs are supported.
        */
@@ -86,6 +128,17 @@ export class Config extends ServiceMap.Service<
 // =============================================================================
 
 declare module "effect/unstable/ai/Prompt" {
+  /**
+   * Anthropic-specific options for system messages.
+   *
+   * **Details**
+   *
+   * These options are used when translating system messages into Anthropic
+   * request content.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface SystemMessageOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -95,6 +148,17 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for user messages.
+   *
+   * **Details**
+   *
+   * These options are used when translating user messages into Anthropic
+   * request content.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface UserMessageOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -104,6 +168,17 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for assistant messages.
+   *
+   * **Details**
+   *
+   * These options are used when replaying assistant messages in Anthropic
+   * conversation history.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface AssistantMessageOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -113,6 +188,17 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for tool messages.
+   *
+   * **Details**
+   *
+   * These options are used when converting tool results into Anthropic user
+   * content blocks.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolMessageOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -122,6 +208,16 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for text prompt parts.
+   *
+   * **When to use**
+   *
+   * Use when you use these options to control how text blocks are sent to Anthropic.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface TextPartOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -131,6 +227,17 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for reasoning prompt parts.
+   *
+   * **Details**
+   *
+   * Preserves Claude thinking metadata when reasoning content is sent back to
+   * Anthropic in later turns.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ReasoningPartOptions extends ProviderOptions {
     readonly anthropic?: {
       readonly info?: {
@@ -155,6 +262,17 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for file prompt parts.
+   *
+   * **Details**
+   *
+   * Controls document metadata, citations, and prompt caching for files sent to
+   * Anthropic.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface FilePartOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -174,12 +292,25 @@ declare module "effect/unstable/ai/Prompt" {
        * Additional context about the document that will be forwarded to the
        * large language model, but will not be used towards cited content.
        *
-       * Useful for storing additional document metadata as text or stringified JSON.
+       * **When to use**
+       *
+       * Use when storing additional document metadata as text or stringified JSON.
        */
       readonly documentContext?: string | null
     } | null
   }
 
+  /**
+   * Anthropic-specific options for tool call prompt parts.
+   *
+   * **Details**
+   *
+   * Carries Anthropic tool caller metadata, MCP metadata, and cache control for
+   * tool use blocks.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolCallPartOptions extends ProviderOptions {
     readonly anthropic?: {
       readonly caller?: {
@@ -202,6 +333,16 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for tool result prompt parts.
+   *
+   * **Details**
+   *
+   * Controls Anthropic prompt caching for tool result content.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolResultPartOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -211,6 +352,16 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for tool approval request prompt parts.
+   *
+   * **Details**
+   *
+   * Controls prompt caching for human approval requests in conversations.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolApprovalRequestPartOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -220,15 +371,16 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
-  export interface ToolApprovalResponsePartOptions extends ProviderOptions {
-    readonly anthropic?: {
-      /**
-       * A breakpoint which marks the end of reusable content eligible for caching.
-       */
-      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
-    } | null
-  }
-
+  /**
+   * Anthropic-specific options for tool approval response prompt parts.
+   *
+   * **Details**
+   *
+   * Controls prompt caching for human approval responses in conversations.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolApprovalResponsePartOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -240,6 +392,17 @@ declare module "effect/unstable/ai/Prompt" {
 }
 
 declare module "effect/unstable/ai/Response" {
+  /**
+   * Anthropic metadata attached when a reasoning block begins.
+   *
+   * **Details**
+   *
+   * Includes Claude thinking metadata needed to continue reasoning-aware
+   * conversations.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningStartPartMetadata extends ProviderMetadata {
     readonly anthropic?: {
       readonly info?: {
@@ -260,6 +423,16 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to streaming reasoning deltas.
+   *
+   * **Details**
+   *
+   * Includes the signature for streamed Claude thinking content when available.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
     readonly anthropic?: {
       readonly info?: {
@@ -273,6 +446,16 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to completed reasoning parts.
+   *
+   * **Details**
+   *
+   * Preserves Claude thinking or redacted thinking information for later turns.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningPartMetadata extends ProviderMetadata {
     readonly anthropic?: {
       readonly info?: {
@@ -293,6 +476,17 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to tool call response parts.
+   *
+   * **Details**
+   *
+   * Identifies Anthropic caller details and MCP tool metadata emitted by the
+   * provider.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ToolCallPartMetadata extends ProviderMetadata {
     readonly anthropic?: {
       readonly caller?: {
@@ -311,6 +505,17 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to tool result response parts.
+   *
+   * **Details**
+   *
+   * Identifies MCP tool metadata associated with provider-executed tool
+   * results.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ToolResultPartMetadata extends ProviderMetadata {
     readonly anthropic?: {
       /**
@@ -325,6 +530,16 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata for document citations in model responses.
+   *
+   * **Details**
+   *
+   * Records the cited document span by character position or page number.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface DocumentSourcePartMetadata extends ProviderMetadata {
     readonly anthropic?: {
       readonly source: "document"
@@ -359,6 +574,16 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata for URL and web citations in model responses.
+   *
+   * **Details**
+   *
+   * Records cited URL text or web-search source freshness information.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface UrlSourcePartMetadata extends ProviderMetadata {
     readonly anthropic?: {
       readonly source: "url"
@@ -378,6 +603,17 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to the finish part of a response.
+   *
+   * **Details**
+   *
+   * Includes container state, context management information, stop details, and
+   * token usage reported by Anthropic.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface FinishPartMetadata extends ProviderMetadata {
     readonly anthropic?: {
       readonly container: typeof Generated.BetaContainer.Encoded | null
@@ -387,6 +623,16 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to error response parts.
+   *
+   * **Details**
+   *
+   * Includes the provider request identifier when Anthropic returns one.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ErrorPartMetadata extends ProviderMetadata {
     readonly anthropic?: {
       requestId?: string | null
@@ -399,22 +645,44 @@ declare module "effect/unstable/ai/Response" {
 // =============================================================================
 
 /**
- * Creates an Anthropic language model that can be used with `AiModel.provide`.
+ * Creates an Anthropic model descriptor that can be provided with `Effect.provide`.
+ *
+ * **When to use**
+ *
+ * Use when you want an Anthropic Claude model value that carries provider and
+ * model metadata and can be supplied directly to an Effect program.
+ *
+ * @see {@link layer} for creating a `LanguageModel.LanguageModel` layer directly
+ * @see {@link make} for constructing the language model service effectfully
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const model = (
   model: (string & {}) | Model,
   config?: Omit<typeof Config.Service, "model">
 ): AiModel.Model<"anthropic", LanguageModel.LanguageModel, AnthropicClient> =>
-  AiModel.make("anthropic", layer({ model, config }))
+  AiModel.make("anthropic", model, layer({ model, config }))
 
 /**
- * Creates an Anthropic language model service.
+ * Creates an Anthropic `LanguageModel` service from a model identifier and optional request defaults.
+ *
+ * **When to use**
+ *
+ * Use when an Effect needs to construct a `LanguageModel.Service` value backed
+ * by `AnthropicClient`.
+ *
+ * **Details**
+ *
+ * The returned effect requires `AnthropicClient`. Request defaults from the
+ * `config` option are merged with any `Config` service in the context, with
+ * context values taking precedence.
+ *
+ * @see {@link layer} for providing the service as a `Layer`
+ * @see {@link model} for creating a model descriptor for `AiModel.provide`
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
   readonly model: (string & {}) | Model
@@ -423,7 +691,7 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
   const client = yield* AnthropicClient
 
   const makeConfig: Effect.Effect<typeof Config.Service & { readonly model: string }> = Effect.gen(function*() {
-    const services = yield* Effect.services<never>()
+    const services = yield* Effect.context<never>()
     return { model, ...providerConfig, ...services.mapUnsafe.get(Config.key) }
   })
 
@@ -469,6 +737,7 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
   )
 
   return yield* LanguageModel.make({
+    codecTransformer: toCodecAnthropic,
     generateText: Effect.fnUntraced(function*(options) {
       const config = yield* makeConfig
       const toolNameMapper = new Tool.NameMapper(options.tools)
@@ -493,17 +762,23 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
           return response
         })
       ))
-  }).pipe(Effect.provideService(
-    LanguageModel.CurrentCodecTransformer,
-    toCodecAnthropic
-  ))
+  })
 })
 
 /**
  * Creates a layer for the Anthropic language model.
  *
- * @since 1.0.0
+ * **When to use**
+ *
+ * Use when composing application layers and you want Anthropic to satisfy
+ * `LanguageModel.LanguageModel` while supplying `AnthropicClient` from another
+ * layer.
+ *
+ * @see {@link make} for constructing the language model service effectfully
+ * @see {@link model} for creating a model service directly
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly model: (string & {}) | Model
@@ -514,37 +789,107 @@ export const layer = (options: {
 /**
  * Provides config overrides for Anthropic language model operations.
  *
- * @since 1.0.0
+ * **When to use**
+ *
+ * Use to apply Anthropic request configuration to one effect without changing
+ * the model's default configuration.
+ *
+ * **Details**
+ *
+ * The overrides are merged with any existing `Config` service for the duration
+ * of the supplied effect. Fields in `overrides` take precedence over existing
+ * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+ * and `withConfigOverride(effect, overrides)`.
+ *
+ * @see {@link Config} for available Anthropic request configuration fields
+ *
  * @category configuration
+ * @since 4.0.0
  */
 export const withConfigOverride: {
   /**
    * Provides config overrides for Anthropic language model operations.
    *
-   * @since 1.0.0
+   * **When to use**
+   *
+   * Use to apply Anthropic request configuration to one effect without changing
+   * the model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available Anthropic request configuration fields
+   *
    * @category configuration
+   * @since 4.0.0
    */
   (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
   /**
    * Provides config overrides for Anthropic language model operations.
    *
-   * @since 1.0.0
+   * **When to use**
+   *
+   * Use to apply Anthropic request configuration to one effect without changing
+   * the model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available Anthropic request configuration fields
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
 } = dual<
   /**
    * Provides config overrides for Anthropic language model operations.
    *
-   * @since 1.0.0
+   * **When to use**
+   *
+   * Use to apply Anthropic request configuration to one effect without changing
+   * the model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available Anthropic request configuration fields
+   *
    * @category configuration
+   * @since 4.0.0
    */
   (overrides: typeof Config.Service) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
   /**
    * Provides config overrides for Anthropic language model operations.
    *
-   * @since 1.0.0
+   * **When to use**
+   *
+   * Use to apply Anthropic request configuration to one effect without changing
+   * the model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available Anthropic request configuration fields
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
 >(2, (self, overrides) =>
@@ -962,21 +1307,37 @@ const prepareMessages = Effect.fnUntraced(
 // =============================================================================
 
 /**
- * Represents a user-defined tool that can be passed to the Anthropic API.
+ * Encoded Anthropic custom tool definition that can be sent in a Messages API request.
+ *
+ * **When to use**
+ *
+ * Use when you need to type or inspect the provider-specific request payload for
+ * a custom Anthropic tool.
+ *
+ * **Details**
+ *
+ * This type aliases the encoded `Generated.BetaTool` schema used for Effect
+ * user-defined and dynamic tools after conversion. It contains the tool `name`,
+ * optional `description`, and `input_schema`, plus Anthropic-specific fields
+ * such as `strict` and `cache_control`.
+ *
+ * @see {@link AnthropicProviderDefinedTool} for the request shape used by Anthropic built-in provider tools
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export type AnthropicUserDefinedTool = typeof Generated.BetaTool.Encoded
 
 /**
  * Represents a provider-defined tool that can be passed to the Anthropic API.
  *
+ * **Details**
+ *
  * These include Anthropic's built-in tools like computer use, code execution,
  * web search, and text editing.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export type AnthropicProviderDefinedTool =
   | typeof Generated.BetaBashTool_20241022.Encoded
@@ -1033,9 +1394,9 @@ const prepareTools = Effect.fnUntraced(
     const providerTools: Array<AnthropicProviderDefinedTool> = []
 
     for (const tool of options.tools) {
-      if (Tool.isUserDefined(tool)) {
+      if (Tool.isUserDefined(tool) || Tool.isDynamic(tool)) {
         const description = Tool.getDescription(tool)
-        const input_schema = yield* tryJsonSchema(tool.parametersSchema, "prepareTools")
+        const input_schema = yield* tryToolJsonSchema(tool, "prepareTools")
         const toolStrict = Tool.getStrictMode(tool)
         const strict = capabilities.supportsStructuredOutput
           ? (toolStrict ?? config.strictJsonSchema ?? true)
@@ -1248,7 +1609,7 @@ const buildHttpRequestDetails = (
   method: request.method,
   url: request.url,
   urlParams: Array.from(request.urlParams),
-  hash: request.hash,
+  hash: Option.getOrUndefined(request.hash),
   headers: Redactable.redact(request.headers) as Record<string, string>
 })
 
@@ -2772,6 +3133,12 @@ const tryJsonSchema = <S extends Schema.Top>(schema: S, method: string) =>
     catch: (error) => unsupportedSchemaError(error, method)
   })
 
+const tryToolJsonSchema = <T extends Tool.Any | Tool.AnyDynamic>(tool: T, method: string) =>
+  Effect.try({
+    try: () => Tool.getJsonSchema(tool, { transformer: toCodecAnthropic }),
+    catch: (error) => unsupportedSchemaError(error, method)
+  })
+
 const getOutputFormat = Effect.fnUntraced(function*({ capabilities, options }: {
   readonly capabilities: ModelCapabilities
   readonly options: LanguageModel.ProviderOptions