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

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**
+ *
+ * - 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"
@@ -35,8 +62,8 @@ import * as InternalUtilities from "./internal/utilities.ts"
 /**
  * The available Anthropic Claude model identifiers.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Model = typeof Generated.Model.Type
 
@@ -47,13 +74,15 @@ export type Model = typeof Generated.Model.Type
 /**
  * Configuration options for the Anthropic language model.
  *
+ * **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 +102,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 +117,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 +137,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 +157,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 +177,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 +197,16 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for text prompt parts.
+   *
+   * **When to use**
+   *
+   * 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 +216,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 +251,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 +281,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.
        *
+       * **When to use**
+       *
        * Useful for 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 +322,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 +341,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 +360,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 +381,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 +412,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 +435,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 +465,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 +494,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 +519,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 +563,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 +592,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 +612,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
@@ -401,20 +636,20 @@ declare module "effect/unstable/ai/Response" {
 /**
  * Creates an Anthropic language model that can be used with `AiModel.provide`.
  *
- * @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.
  *
- * @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 +658,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 +704,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 +729,14 @@ 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
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly model: (string & {}) | Model
@@ -514,37 +747,37 @@ export const layer = (options: {
 /**
  * Provides config overrides for Anthropic language model operations.
  *
- * @since 1.0.0
  * @category configuration
+ * @since 4.0.0
  */
 export const withConfigOverride: {
   /**
    * Provides config overrides for Anthropic language model operations.
    *
-   * @since 1.0.0
    * @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
    * @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
    * @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
    * @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) =>
@@ -964,19 +1197,21 @@ const prepareMessages = Effect.fnUntraced(
 /**
  * Represents a user-defined tool that can be passed to the Anthropic API.
  *
- * @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 +1268,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 +1483,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 +3007,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

package/src/AnthropicTelemetry.ts

@@ -5,7 +5,7 @@
  * semantic conventions, extending the base GenAI attributes with Anthropic-specific
  * request and response metadata.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import { dual } from "effect/Function"
 import * as String from "effect/String"
@@ -17,10 +17,9 @@ import * as Telemetry from "effect/unstable/ai/Telemetry"
  * The attributes used to describe telemetry in the context of Generative
  * Artificial Intelligence (GenAI) Models requests and responses.
  *
- * {@see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/}
- *
- * @since 1.0.0
+ * @see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/
  * @category models
+ * @since 4.0.0
  */
 export type AnthropicTelemetryAttributes = Simplify<
   & Telemetry.GenAITelemetryAttributes
@@ -32,8 +31,8 @@ export type AnthropicTelemetryAttributes = Simplify<
  * All telemetry attributes which are part of the GenAI specification,
  * including the Anthropic-specific attributes.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AllAttributes = Telemetry.AllAttributes & RequestAttributes & ResponseAttributes
 
@@ -41,8 +40,8 @@ export type AllAttributes = Telemetry.AllAttributes & RequestAttributes & Respon
  * Telemetry attributes which are part of the GenAI specification and are
  * namespaced by `gen_ai.anthropic.request`.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface RequestAttributes {
   /**
@@ -59,8 +58,8 @@ export interface RequestAttributes {
  * Telemetry attributes which are part of the GenAI specification and are
  * namespaced by `gen_ai.anthropic.response`.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ResponseAttributes {
   /**
@@ -78,8 +77,10 @@ export interface ResponseAttributes {
 }
 
 /**
- * @since 1.0.0
+ * Options accepted by `addGenAIAnnotations`, combining standard GenAI telemetry attributes with optional Anthropic request and response attributes.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AnthropicTelemetryAttributeOptions = Telemetry.GenAITelemetryAttributeOptions & {
   anthropic?: {
@@ -99,30 +100,36 @@ const addAnthropicResponseAttributes = Telemetry.addSpanAttributes("gen_ai.anthr
  * Applies the specified Anthropic GenAI telemetry attributes to the provided
  * `Span`.
  *
- * **NOTE**: This method will mutate the `Span` **in-place**.
+ * **Gotchas**
+ *
+ * This method mutates the `Span` in place.
  *
- * @since 1.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const addGenAIAnnotations: {
   /**
    * Applies the specified Anthropic GenAI telemetry attributes to the provided
    * `Span`.
    *
-   * **NOTE**: This method will mutate the `Span` **in-place**.
+   * **Gotchas**
    *
-   * @since 1.0.0
-   * @category utilities
+   * This method mutates the `Span` in place.
+   *
+   * @category utils
+   * @since 4.0.0
    */
   (options: AnthropicTelemetryAttributeOptions): (span: Span) => void
   /**
    * Applies the specified Anthropic GenAI telemetry attributes to the provided
    * `Span`.
    *
-   * **NOTE**: This method will mutate the `Span` **in-place**.
+   * **Gotchas**
+   *
+   * This method mutates the `Span` in place.
    *
-   * @since 1.0.0
-   * @category utilities
+   * @category utils
+   * @since 4.0.0
    */
   (span: Span, options: AnthropicTelemetryAttributeOptions): void
 } = dual(2, (span: Span, options: AnthropicTelemetryAttributeOptions) => {