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

package/dist/AnthropicTelemetry.d.ts

@@ -5,26 +5,30 @@ 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/
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnthropicTelemetryAttributes = Simplify<Telemetry.GenAITelemetryAttributes & Telemetry.AttributesWithPrefix<RequestAttributes, "gen_ai.anthropic.request"> & Telemetry.AttributesWithPrefix<ResponseAttributes, "gen_ai.anthropic.response">>;
 /**
  * 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;
 /**
  * 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 {
     /**
@@ -40,8 +44,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 {
     /**
@@ -58,8 +62,10 @@ export interface ResponseAttributes {
     readonly cacheReadInputTokens?: number | null | undefined;
 }
 /**
- * @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?: {
@@ -71,30 +77,51 @@ export type AnthropicTelemetryAttributeOptions = Telemetry.GenAITelemetryAttribu
  * Applies the specified Anthropic GenAI telemetry attributes to the provided
  * `Span`.
  *
- * **NOTE**: This method will mutate the `Span` **in-place**.
+ * **When to use**
+ *
+ * Use to annotate an Anthropic model span with standard GenAI telemetry
+ * attributes and Anthropic-specific request or response metadata.
  *
- * @since 1.0.0
- * @category utilities
+ * **Gotchas**
+ *
+ * This method mutates the `Span` in place.
+ *
+ * @category utils
+ * @since 4.0.0
  */
 export declare const addGenAIAnnotations: {
     /**
      * Applies the specified Anthropic GenAI telemetry attributes to the provided
      * `Span`.
      *
-     * **NOTE**: This method will mutate the `Span` **in-place**.
+     * **When to use**
+     *
+     * Use to annotate an Anthropic model span with standard GenAI telemetry
+     * attributes and Anthropic-specific request or response metadata.
      *
-     * @since 1.0.0
-     * @category utilities
+     * **Gotchas**
+     *
+     * 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**.
+     * **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.
      *
-     * @since 1.0.0
-     * @category utilities
+     * @category utils
+     * @since 4.0.0
      */
     (span: Span, options: AnthropicTelemetryAttributeOptions): void;
 };

package/dist/AnthropicTelemetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnthropicTelemetry.d.ts","sourceRoot":"","sources":["../src/AnthropicTelemetry.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,SAAS,MAAM,8BAA8B,CAAA;AAEzD;;;;;;;;GAQG;AACH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAC/C,SAAS,CAAC,wBAAwB,GAClC,SAAS,CAAC,oBAAoB,CAAC,iBAAiB,EAAE,0BAA0B,CAAC,GAC7E,SAAS,CAAC,oBAAoB,CAAC,kBAAkB,EAAE,2BAA2B,CAAC,CAClF,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,aAAa,GAAG,iBAAiB,GAAG,kBAAkB,CAAA;AAE5F;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAAA;IACtD;;OAEG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAC1D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IAC/C;;OAEG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IAC7D;;OAEG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAC1D;AAED;;;GAGG;AACH,MAAM,MAAM,kCAAkC,GAAG,SAAS,CAAC,8BAA8B,GAAG;IAC1F,SAAS,CAAC,EAAE;QACV,OAAO,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;QACvC,QAAQ,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAA;KAC1C,GAAG,SAAS,CAAA;CACd,CAAA;AASD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE;IAChC;;;;;;;;OAQG;IACH,CAAC,OAAO,EAAE,kCAAkC,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAA;IACnE;;;;;;;;OAQG;IACH,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,kCAAkC,GAAG,IAAI,CAAA;CAW/D,CAAA"}
+{"version":3,"file":"AnthropicTelemetry.d.ts","sourceRoot":"","sources":["../src/AnthropicTelemetry.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,SAAS,MAAM,8BAA8B,CAAA;AAEzD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAC/C,SAAS,CAAC,wBAAwB,GAClC,SAAS,CAAC,oBAAoB,CAAC,iBAAiB,EAAE,0BAA0B,CAAC,GAC7E,SAAS,CAAC,oBAAoB,CAAC,kBAAkB,EAAE,2BAA2B,CAAC,CAClF,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,aAAa,GAAG,iBAAiB,GAAG,kBAAkB,CAAA;AAE5F;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAAA;IACtD;;OAEG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAC1D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IAC/C;;OAEG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IAC7D;;OAEG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAC1D;AAED;;;;;GAKG;AACH,MAAM,MAAM,kCAAkC,GAAG,SAAS,CAAC,8BAA8B,GAAG;IAC1F,SAAS,CAAC,EAAE;QACV,OAAO,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;QACvC,QAAQ,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAA;KAC1C,GAAG,SAAS,CAAA;CACd,CAAA;AASD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,EAAE;IAChC;;;;;;;;;;;;;;;OAeG;IACH,CAAC,OAAO,EAAE,kCAAkC,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAA;IACnE;;;;;;;;;;;;;;;OAeG;IACH,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,kCAAkC,GAAG,IAAI,CAAA;CAW/D,CAAA"}

package/dist/AnthropicTelemetry.js

@@ -1,11 +1,40 @@
 /**
- * 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**
  *
- * @since 1.0.0
+ * - 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
  */
 import { dual } from "effect/Function";
 import * as String from "effect/String";
@@ -16,10 +45,17 @@ const addAnthropicResponseAttributes = /*#__PURE__*/Telemetry.addSpanAttributes(
  * Applies the specified Anthropic GenAI telemetry attributes to the provided
  * `Span`.
  *
- * **NOTE**: This method will mutate the `Span` **in-place**.
+ * **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.
  *
- * @since 1.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const addGenAIAnnotations = /*#__PURE__*/dual(2, (span, options) => {
   Telemetry.addGenAIAnnotations(span, options);

package/dist/AnthropicTelemetry.js.map

@@ -1 +1 @@
-{"version":3,"file":"AnthropicTelemetry.js","names":["dual","String","Telemetry","addAnthropicRequestAttributes","addSpanAttributes","camelToSnake","addAnthropicResponseAttributes","addGenAIAnnotations","span","options","anthropic","request","response"],"sources":["../src/AnthropicTelemetry.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;AASA,SAASA,IAAI,QAAQ,iBAAiB;AACtC,OAAO,KAAKC,MAAM,MAAM,eAAe;AAGvC,OAAO,KAAKC,SAAS,MAAM,8BAA8B;AA6EzD,MAAMC,6BAA6B,gBAAGD,SAAS,CAACE,iBAAiB,CAAC,0BAA0B,EAAEH,MAAM,CAACI,YAAY,CAEhH;AACD,MAAMC,8BAA8B,gBAAGJ,SAAS,CAACE,iBAAiB,CAAC,2BAA2B,EAAEH,MAAM,CAACI,YAAY,CAElH;AAED;;;;;;;;;AASA,OAAO,MAAME,mBAAmB,gBAqB5BP,IAAI,CAAC,CAAC,EAAE,CAACQ,IAAU,EAAEC,OAA2C,KAAI;EACtEP,SAAS,CAACK,mBAAmB,CAACC,IAAI,EAAEC,OAAO,CAAC;EAC5C,IAAIA,OAAO,CAACC,SAAS,IAAI,IAAI,EAAE;IAC7B,IAAID,OAAO,CAACC,SAAS,CAACC,OAAO,IAAI,IAAI,EAAE;MACrCR,6BAA6B,CAACK,IAAI,EAAEC,OAAO,CAACC,SAAS,CAACC,OAAO,CAAC;IAChE;IACA,IAAIF,OAAO,CAACC,SAAS,CAACE,QAAQ,IAAI,IAAI,EAAE;MACtCN,8BAA8B,CAACE,IAAI,EAAEC,OAAO,CAACC,SAAS,CAACE,QAAQ,CAAC;IAClE;EACF;AACF,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"AnthropicTelemetry.js","names":["dual","String","Telemetry","addAnthropicRequestAttributes","addSpanAttributes","camelToSnake","addAnthropicResponseAttributes","addGenAIAnnotations","span","options","anthropic","request","response"],"sources":["../src/AnthropicTelemetry.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAASA,IAAI,QAAQ,iBAAiB;AACtC,OAAO,KAAKC,MAAM,MAAM,eAAe;AAGvC,OAAO,KAAKC,SAAS,MAAM,8BAA8B;AAmFzD,MAAMC,6BAA6B,gBAAGD,SAAS,CAACE,iBAAiB,CAAC,0BAA0B,EAAEH,MAAM,CAACI,YAAY,CAEhH;AACD,MAAMC,8BAA8B,gBAAGJ,SAAS,CAACE,iBAAiB,CAAC,2BAA2B,EAAEH,MAAM,CAACI,YAAY,CAElH;AAED;;;;;;;;;;;;;;;;AAgBA,OAAO,MAAME,mBAAmB,gBAmC5BP,IAAI,CAAC,CAAC,EAAE,CAACQ,IAAU,EAAEC,OAA2C,KAAI;EACtEP,SAAS,CAACK,mBAAmB,CAACC,IAAI,EAAEC,OAAO,CAAC;EAC5C,IAAIA,OAAO,CAACC,SAAS,IAAI,IAAI,EAAE;IAC7B,IAAID,OAAO,CAACC,SAAS,CAACC,OAAO,IAAI,IAAI,EAAE;MACrCR,6BAA6B,CAACK,IAAI,EAAEC,OAAO,CAACC,SAAS,CAACC,OAAO,CAAC;IAChE;IACA,IAAIF,OAAO,CAACC,SAAS,CAACE,QAAQ,IAAI,IAAI,EAAE;MACtCN,8BAA8B,CAACE,IAAI,EAAEC,OAAO,CAACC,SAAS,CAACE,QAAQ,CAAC;IAClE;EACF;AACF,CAAC,CAAC","ignoreList":[]}