@effect/ai-anthropic 4.0.0-beta.66 → 4.0.0-beta.68

package/src/AnthropicError.ts

@@ -4,14 +4,14 @@
  * Provides Anthropic-specific metadata fields for AI error types through module
  * augmentation, enabling typed access to Anthropic error details.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
  * Anthropic-specific error metadata fields.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnthropicErrorMetadata = {
   /**
@@ -30,8 +30,8 @@ export type AnthropicErrorMetadata = {
  * Extends base error metadata with rate limit specific information from
  * Anthropic's rate limit headers.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnthropicRateLimitMetadata = AnthropicErrorMetadata & {
   /**
@@ -61,42 +61,132 @@ export type AnthropicRateLimitMetadata = AnthropicErrorMetadata & {
 }
 
 declare module "effect/unstable/ai/AiError" {
+  /**
+   * Anthropic metadata attached to `RateLimitError` values.
+   *
+   * Includes request identifiers, Anthropic error types, and parsed request or
+   * token limit headers when the provider rejects a request due to rate limits.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface RateLimitErrorMetadata {
     readonly anthropic?: AnthropicRateLimitMetadata | null
   }
 
+  /**
+   * Anthropic metadata attached to `QuotaExhaustedError` values.
+   *
+   * Captures the Anthropic error type and request identifier for failures where
+   * the account or workspace has exhausted its available quota.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface QuotaExhaustedErrorMetadata {
     readonly anthropic?: AnthropicErrorMetadata | null
   }
 
+  /**
+   * Anthropic metadata attached to `AuthenticationError` values.
+   *
+   * Preserves Anthropic error details for missing, invalid, or unauthorized API
+   * credentials while keeping the error in the shared AI error model.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface AuthenticationErrorMetadata {
     readonly anthropic?: AnthropicErrorMetadata | null
   }
 
+  /**
+   * Anthropic metadata attached to `ContentPolicyError` values.
+   *
+   * Records Anthropic error details returned when a request or response is
+   * rejected by Anthropic safety or content policy enforcement.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface ContentPolicyErrorMetadata {
     readonly anthropic?: AnthropicErrorMetadata | null
   }
 
+  /**
+   * Anthropic metadata attached to `InvalidRequestError` values.
+   *
+   * Provides the Anthropic error type and request identifier for malformed or
+   * unsupported requests rejected before model execution.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface InvalidRequestErrorMetadata {
     readonly anthropic?: AnthropicErrorMetadata | null
   }
 
+  /**
+   * Anthropic metadata attached to `InternalProviderError` values.
+   *
+   * Preserves Anthropic request correlation data for provider-side failures
+   * that should be reported or investigated with Anthropic support.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface InternalProviderErrorMetadata {
     readonly anthropic?: AnthropicErrorMetadata | null
   }
 
+  /**
+   * Anthropic metadata attached to `InvalidOutputError` values.
+   *
+   * Describes Anthropic-specific context for responses that could not be
+   * decoded or interpreted as valid AI output.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface InvalidOutputErrorMetadata {
     readonly anthropic?: AnthropicErrorMetadata | null
   }
 
+  /**
+   * Anthropic metadata attached to `StructuredOutputError` values.
+   *
+   * Captures Anthropic error details for structured-output failures, including
+   * request correlation data useful when diagnosing schema-related responses.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface StructuredOutputErrorMetadata {
     readonly anthropic?: AnthropicErrorMetadata | null
   }
 
+  /**
+   * Anthropic metadata attached to `UnsupportedSchemaError` values.
+   *
+   * Provides Anthropic error details for schemas that cannot be represented by
+   * or submitted to the Anthropic API.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface UnsupportedSchemaErrorMetadata {
     readonly anthropic?: AnthropicErrorMetadata | null
   }
 
+  /**
+   * Anthropic metadata attached to `UnknownError` values.
+   *
+   * Retains the Anthropic error type and request identifier when a provider
+   * response cannot be classified as a more specific AI error.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface UnknownErrorMetadata {
     readonly anthropic?: AnthropicErrorMetadata | null
   }

package/src/AnthropicLanguageModel.ts

@@ -1,5 +1,31 @@
 /**
- * @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.
+ *
+ * **Common tasks**
+ *
+ * - 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"
@@ -36,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
 
@@ -51,8 +77,8 @@ export type Model = typeof Generated.Model.Type
  * 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 Context.Service<
   Config,
@@ -87,6 +113,15 @@ export class Config extends Context.Service<
 // =============================================================================
 
 declare module "effect/unstable/ai/Prompt" {
+  /**
+   * Anthropic-specific options for system messages.
+   *
+   * 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?: {
       /**
@@ -96,6 +131,15 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for user messages.
+   *
+   * 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?: {
       /**
@@ -105,6 +149,15 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for assistant messages.
+   *
+   * 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?: {
       /**
@@ -114,6 +167,15 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for tool messages.
+   *
+   * 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?: {
       /**
@@ -123,6 +185,14 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for text prompt parts.
+   *
+   * 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?: {
       /**
@@ -132,6 +202,15 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for reasoning prompt parts.
+   *
+   * 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?: {
@@ -156,6 +235,15 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for file prompt parts.
+   *
+   * 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?: {
       /**
@@ -181,6 +269,15 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for tool call prompt parts.
+   *
+   * 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?: {
@@ -203,6 +300,14 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for tool result prompt parts.
+   *
+   * Controls Anthropic prompt caching for tool result content.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolResultPartOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -212,6 +317,14 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for tool approval request prompt parts.
+   *
+   * Controls prompt caching for human approval requests in conversations.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolApprovalRequestPartOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -221,6 +334,14 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * Anthropic-specific options for tool approval response prompt parts.
+   *
+   * Controls prompt caching for human approval responses in conversations.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolApprovalResponsePartOptions extends ProviderOptions {
     readonly anthropic?: {
       /**
@@ -232,6 +353,15 @@ declare module "effect/unstable/ai/Prompt" {
 }
 
 declare module "effect/unstable/ai/Response" {
+  /**
+   * Anthropic metadata attached when a reasoning block begins.
+   *
+   * 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?: {
@@ -252,6 +382,14 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to streaming reasoning deltas.
+   *
+   * 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?: {
@@ -265,6 +403,14 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to completed reasoning parts.
+   *
+   * 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?: {
@@ -285,6 +431,15 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to tool call response parts.
+   *
+   * 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?: {
@@ -303,6 +458,15 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to tool result response parts.
+   *
+   * Identifies MCP tool metadata associated with provider-executed tool
+   * results.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ToolResultPartMetadata extends ProviderMetadata {
     readonly anthropic?: {
       /**
@@ -317,6 +481,14 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata for document citations in model responses.
+   *
+   * 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"
@@ -351,6 +523,14 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata for URL and web citations in model responses.
+   *
+   * 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"
@@ -370,6 +550,15 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to the finish part of a response.
+   *
+   * 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
@@ -379,6 +568,14 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * Anthropic metadata attached to error response parts.
+   *
+   * 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
@@ -393,8 +590,8 @@ 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,
@@ -405,8 +602,8 @@ export const model = (
 /**
  * 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
@@ -492,8 +689,8 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
 /**
  * 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
@@ -504,37 +701,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) =>
@@ -954,8 +1151,8 @@ 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
 
@@ -965,8 +1162,8 @@ export type AnthropicUserDefinedTool = typeof Generated.BetaTool.Encoded
  * 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

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"
@@ -19,8 +19,8 @@ import * as Telemetry from "effect/unstable/ai/Telemetry"
  *
  * {@see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/}
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnthropicTelemetryAttributes = Simplify<
   & Telemetry.GenAITelemetryAttributes
@@ -32,8 +32,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 +41,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 +59,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 +78,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?: {
@@ -101,8 +103,8 @@ const addAnthropicResponseAttributes = Telemetry.addSpanAttributes("gen_ai.anthr
  *
  * **NOTE**: This method will mutate the `Span` **in-place**.
  *
- * @since 1.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const addGenAIAnnotations: {
   /**
@@ -111,8 +113,8 @@ export const addGenAIAnnotations: {
    *
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
-   * @since 1.0.0
-   * @category utilities
+   * @category utils
+   * @since 4.0.0
    */
   (options: AnthropicTelemetryAttributeOptions): (span: Span) => void
   /**
@@ -121,8 +123,8 @@ export const addGenAIAnnotations: {
    *
    * **NOTE**: This method will mutate 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) => {