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

package/src/AnthropicLanguageModel.ts

@@ -7,7 +7,7 @@
  *
  * **When to use**
  *
- * - Create an Anthropic-backed model with {@link model}
+ * 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}
@@ -60,7 +60,13 @@ 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.
  *
  * @category models
  * @since 4.0.0
@@ -72,7 +78,12 @@ export type Model = typeof Generated.Model.Type
 // =============================================================================
 
 /**
- * Configuration options for the Anthropic language model.
+ * Context service for Anthropic language model configuration.
+ *
+ * **When to use**
+ *
+ * Use when you need to provide or override Anthropic model configuration on a
+ * per-request basis via `Context.Service`.
  *
  * **Details**
  *
@@ -202,7 +213,7 @@ declare module "effect/unstable/ai/Prompt" {
    *
    * **When to use**
    *
-   * Use these options to control how text blocks are sent to Anthropic.
+   * Use when you use these options to control how text blocks are sent to Anthropic.
    *
    * @category request
    * @since 4.0.0
@@ -283,7 +294,7 @@ declare module "effect/unstable/ai/Prompt" {
        *
        * **When to use**
        *
-       * Useful for storing additional document metadata as text or stringified JSON.
+       * Use when storing additional document metadata as text or stringified JSON.
        */
       readonly documentContext?: string | null
     } | null
@@ -634,7 +645,15 @@ 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
  *
  * @category constructors
  * @since 4.0.0
@@ -646,7 +665,21 @@ export const model = (
   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`
  *
  * @category constructors
  * @since 4.0.0
@@ -735,6 +768,15 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
 /**
  * Creates a layer for the Anthropic language model.
  *
+ * **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
  */
@@ -747,6 +789,20 @@ export const layer = (options: {
 /**
  * Provides config overrides for Anthropic language model operations.
  *
+ * **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
  */
@@ -754,6 +810,20 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for Anthropic language model operations.
    *
+   * **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
    */
@@ -761,6 +831,20 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for Anthropic language model operations.
    *
+   * **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
    */
@@ -769,6 +853,20 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for Anthropic language model operations.
    *
+   * **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
    */
@@ -776,6 +874,20 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for Anthropic language model operations.
    *
+   * **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
    */
@@ -1195,7 +1307,21 @@ 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
  *
  * @category tools
  * @since 4.0.0
@@ -2779,7 +2905,7 @@ const groupMessages = (prompt: Prompt.Prompt): Array<ContentGroup> => {
 }
 
 /**
- * Checks if data is a URL (either a URL object or a URL string).
+ * Checks whether data is a URL (either a URL object or a URL string).
  */
 const isUrlData = (
   data: typeof Prompt.FilePart.Type["data"]

package/src/AnthropicTelemetry.ts

@@ -1,9 +1,38 @@
 /**
- * Anthropic telemetry attributes for OpenTelemetry integration.
+ * The `AnthropicTelemetry` module adds Anthropic-specific attributes to the
+ * provider-neutral GenAI telemetry model. It keeps the standard
+ * `Telemetry.addGenAIAnnotations` attributes and adds Anthropic request and
+ * response metadata under the `gen_ai.anthropic.*` OpenTelemetry namespaces.
  *
- * Provides Anthropic-specific GenAI telemetry attributes following OpenTelemetry
- * semantic conventions, extending the base GenAI attributes with Anthropic-specific
- * request and response metadata.
+ * **Mental model**
+ *
+ * - Standard GenAI attributes come from `effect/unstable/ai/Telemetry`
+ * - Anthropic request attributes are written under
+ *   `gen_ai.anthropic.request.*`
+ * - Anthropic response attributes are written under
+ *   `gen_ai.anthropic.response.*`
+ * - Attribute option keys are written in camelCase and converted to
+ *   OpenTelemetry snake_case attribute names
+ * - {@link addGenAIAnnotations} mutates the supplied span by adding any
+ *   non-nullish attributes from the option object
+ *
+ * **Common tasks**
+ *
+ * - Use {@link AnthropicTelemetryAttributes} when typing the complete set of
+ *   standard and Anthropic-specific span attributes
+ * - Pass `anthropic.request` data for options such as extended thinking and
+ *   thinking budget tokens
+ * - Pass `anthropic.response` data for response details such as stop reason and
+ *   cache token counts
+ * - Use {@link addGenAIAnnotations} from an Anthropic model span to keep
+ *   standard GenAI and provider-specific annotations together
+ *
+ * **Gotchas**
+ *
+ * - This module only annotates spans; it does not start spans or export traces
+ * - Null and undefined attribute values are skipped instead of being written
+ * - The helper accepts both direct and data-last forms because it is built with
+ *   `dual`
  *
  * @since 4.0.0
  */
@@ -17,7 +46,12 @@ 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/
+ * **Details**
+ *
+ * These attributes follow the OpenTelemetry generative AI semantic
+ * conventions:
+ * https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/
+ *
  * @category models
  * @since 4.0.0
  */
@@ -100,6 +134,11 @@ const addAnthropicResponseAttributes = Telemetry.addSpanAttributes("gen_ai.anthr
  * Applies the specified Anthropic GenAI telemetry attributes to the provided
  * `Span`.
  *
+ * **When to use**
+ *
+ * Use to annotate an Anthropic model span with standard GenAI telemetry
+ * attributes and Anthropic-specific request or response metadata.
+ *
  * **Gotchas**
  *
  * This method mutates the `Span` in place.
@@ -112,6 +151,11 @@ export const addGenAIAnnotations: {
    * Applies the specified Anthropic GenAI telemetry attributes to the provided
    * `Span`.
    *
+   * **When to use**
+   *
+   * Use to annotate an Anthropic model span with standard GenAI telemetry
+   * attributes and Anthropic-specific request or response metadata.
+   *
    * **Gotchas**
    *
    * This method mutates the `Span` in place.
@@ -124,6 +168,11 @@ export const addGenAIAnnotations: {
    * Applies the specified Anthropic GenAI telemetry attributes to the provided
    * `Span`.
    *
+   * **When to use**
+   *
+   * Use to annotate an Anthropic model span with standard GenAI telemetry
+   * attributes and Anthropic-specific request or response metadata.
+   *
    * **Gotchas**
    *
    * This method mutates the `Span` in place.