@effect/ai 0.14.1 → 0.16.0

package/src/AiTelemetry.ts

@@ -1,12 +1,14 @@
 /**
  * @since 1.0.0
  */
-
+import * as Context from "effect/Context"
 import { dual } from "effect/Function"
 import * as Predicate from "effect/Predicate"
 import * as String from "effect/String"
 import type { Span } from "effect/Tracer"
 import type { Simplify } from "effect/Types"
+import type { AiLanguageModelOptions } from "./AiLanguageModel.js"
+import type { AiResponse } from "./AiResponse.js"
 
 /**
  * The attributes used to describe telemetry in the context of Generative
@@ -15,219 +17,213 @@ import type { Simplify } from "effect/Types"
  * {@see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/}
  *
  * @since 1.0.0
- * @category models
+ * @category Models
  */
 export type GenAITelemetryAttributes = Simplify<
-  & GenAI.AttributesWithPrefix<GenAI.BaseAttributes, "gen_ai">
-  & GenAI.AttributesWithPrefix<GenAI.OperationAttributes, "gen_ai.operation">
-  & GenAI.AttributesWithPrefix<GenAI.TokenAttributes, "gen_ai.token">
-  & GenAI.AttributesWithPrefix<GenAI.UsageAttributes, "gen_ai.usage">
-  & GenAI.AttributesWithPrefix<GenAI.RequestAttributes, "gen_ai.request">
-  & GenAI.AttributesWithPrefix<GenAI.ResponseAttributes, "gen_ai.response">
+  & AttributesWithPrefix<BaseAttributes, "gen_ai">
+  & AttributesWithPrefix<OperationAttributes, "gen_ai.operation">
+  & AttributesWithPrefix<TokenAttributes, "gen_ai.token">
+  & AttributesWithPrefix<UsageAttributes, "gen_ai.usage">
+  & AttributesWithPrefix<RequestAttributes, "gen_ai.request">
+  & AttributesWithPrefix<ResponseAttributes, "gen_ai.response">
 >
 
 /**
+ * All telemetry attributes which are part of the GenAI specification.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export type AllAttributes =
+  & BaseAttributes
+  & OperationAttributes
+  & TokenAttributes
+  & UsageAttributes
+  & RequestAttributes
+  & ResponseAttributes
+
+/**
+ * Telemetry attributes which are part of the GenAI specification and are
+ * namespaced by `gen_ai`.
+ *
  * @since 1.0.0
- * @category models
+ * @category Models
  */
-export declare namespace GenAI {
+export interface BaseAttributes {
   /**
-   * All telemetry attributes which are part of the GenAI specification.
-   *
-   * @since 1.0.0
-   * @category models
+   * The Generative AI product as identified by the client or server
+   * instrumentation.
    */
-  export type AllAttributes =
-    & BaseAttributes
-    & OperationAttributes
-    & TokenAttributes
-    & UsageAttributes
-    & RequestAttributes
-    & ResponseAttributes
+  readonly system?: (string & {}) | WellKnownSystem | null | undefined
+}
+
+/**
+ * Telemetry attributes which are part of the GenAI specification and are
+ * namespaced by `gen_ai.operation`.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface OperationAttributes {
+  readonly name?: (string & {}) | WellKnownOperationName | null | undefined
+}
+
+/**
+ * Telemetry attributes which are part of the GenAI specification and are
+ * namespaced by `gen_ai.token`.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface TokenAttributes {
+  readonly type?: string | null | undefined
+}
+
+/**
+ * Telemetry attributes which are part of the GenAI specification and are
+ * namespaced by `gen_ai.usage`.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface UsageAttributes {
+  readonly inputTokens?: number | null | undefined
+  readonly outputTokens?: number | null | undefined
+}
 
+/**
+ * Telemetry attributes which are part of the GenAI specification and are
+ * namespaced by `gen_ai.request`.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface RequestAttributes {
   /**
-   * Telemetry attributes which are part of the GenAI specification and are
-   * namespaced by `gen_ai`.
-   *
-   * @since 1.0.0
-   * @category models
+   * The name of the GenAI model a request is being made to.
    */
-  export interface BaseAttributes {
-    /**
-     * The Generative AI product as identified by the client or server
-     * instrumentation.
-     */
-    readonly system?: (string & {}) | WellKnownSystem | null | undefined
-  }
-
+  readonly model?: string | null | undefined
   /**
-   * Telemetry attributes which are part of the GenAI specification and are
-   * namespaced by `gen_ai.operation`.
-   *
-   * @since 1.0.0
-   * @category models
+   * The temperature setting for the GenAI request.
    */
-  export interface OperationAttributes {
-    readonly name?: (string & {}) | WellKnownOperationName | null | undefined
-  }
-
+  readonly temperature?: number | null | undefined
   /**
-   * Telemetry attributes which are part of the GenAI specification and are
-   * namespaced by `gen_ai.token`.
-   *
-   * @since 1.0.0
-   * @category models
+   * The temperature setting for the GenAI request.
    */
-  export interface TokenAttributes {
-    readonly type?: string | null | undefined
-  }
-
+  readonly topK?: number | null | undefined
   /**
-   * Telemetry attributes which are part of the GenAI specification and are
-   * namespaced by `gen_ai.usage`.
-   *
-   * @since 1.0.0
-   * @category models
+   * The top_k sampling setting for the GenAI request.
    */
-  export interface UsageAttributes {
-    readonly inputTokens?: number | null | undefined
-    readonly outputTokens?: number | null | undefined
-  }
-
+  readonly topP?: number | null | undefined
   /**
-   * Telemetry attributes which are part of the GenAI specification and are
-   * namespaced by `gen_ai.request`.
-   *
-   * @since 1.0.0
-   * @category models
+   * The top_p sampling setting for the GenAI request.
    */
-  export interface RequestAttributes {
-    /**
-     * The name of the GenAI model a request is being made to.
-     */
-    readonly model?: string | null | undefined
-    /**
-     * The temperature setting for the GenAI request.
-     */
-    readonly temperature?: number | null | undefined
-    /**
-     * The temperature setting for the GenAI request.
-     */
-    readonly topK?: number | null | undefined
-    /**
-     * The top_k sampling setting for the GenAI request.
-     */
-    readonly topP?: number | null | undefined
-    /**
-     * The top_p sampling setting for the GenAI request.
-     */
-    readonly maxTokens?: number | null | undefined
-    /**
-     * The encoding formats requested in an embeddings operation, if specified.
-     */
-    readonly encodingFormats?: ReadonlyArray<string> | null | undefined
-    /**
-     * List of sequences that the model will use to stop generating further
-     * tokens.
-     */
-    readonly stopSequences?: ReadonlyArray<string> | null | undefined
-    /**
-     * The frequency penalty setting for the GenAI request.
-     */
-    readonly frequencyPenalty?: number | null | undefined
-    /**
-     * The presence penalty setting for the GenAI request.
-     */
-    readonly presencePenalty?: number | null | undefined
-    /**
-     * The seed setting for the GenAI request. Requests with same seed value
-     * are more likely to return same result.
-     */
-    readonly seed?: number | null | undefined
-  }
-
+  readonly maxTokens?: number | null | undefined
   /**
-   * Telemetry attributes which are part of the GenAI specification and are
-   * namespaced by `gen_ai.response`.
-   *
-   * @since 1.0.0
-   * @category models
+   * The encoding formats requested in an embeddings operation, if specified.
    */
-  export interface ResponseAttributes {
-    /**
-     * The unique identifier for the completion.
-     */
-    readonly id?: string | null | undefined
-    /**
-     * The name of the model that generated the response.
-     */
-    readonly model?: string | null | undefined
-    /**
-     * Array of reasons the model stopped generating tokens, corresponding to
-     * each generation received.
-     */
-    readonly finishReasons?: ReadonlyArray<string> | null | undefined
-  }
-
+  readonly encodingFormats?: ReadonlyArray<string> | null | undefined
   /**
-   * The `gen_ai.operation.name` attribute has the following list of well-known
-   * values.
-   *
-   * If one of them applies, then the respective value **MUST** be used;
-   * otherwise, a custom value **MAY** be used.
-   *
-   * @since 1.0.0
-   * @category models
+   * List of sequences that the model will use to stop generating further
+   * tokens.
    */
-  export type WellKnownOperationName = "chat" | "embeddings" | "text_completion"
-
+  readonly stopSequences?: ReadonlyArray<string> | null | undefined
   /**
-   * The `gen_ai.system` attribute has the following list of well-known values.
-   *
-   * If one of them applies, then the respective value **MUST** be used;
-   * otherwise, a custom value **MAY** be used.
-   *
-   * @since 1.0.0
-   * @category models
+   * The frequency penalty setting for the GenAI request.
    */
-  export type WellKnownSystem =
-    | "anthropic"
-    | "aws.bedrock"
-    | "az.ai.inference"
-    | "az.ai.openai"
-    | "cohere"
-    | "deepseek"
-    | "gemini"
-    | "groq"
-    | "ibm.watsonx.ai"
-    | "mistral_ai"
-    | "openai"
-    | "perplexity"
-    | "vertex_ai"
-    | "xai"
-
+  readonly frequencyPenalty?: number | null | undefined
   /**
-   * @since 1.0.0
-   * @category models
+   * The presence penalty setting for the GenAI request.
    */
-  export type AttributesWithPrefix<Attributes extends Record<string, any>, Prefix extends string> = {
-    [Name in keyof Attributes as `${Prefix}.${FormatAttributeName<Name>}`]: Attributes[Name]
-  }
+  readonly presencePenalty?: number | null | undefined
+  /**
+   * The seed setting for the GenAI request. Requests with same seed value
+   * are more likely to return same result.
+   */
+  readonly seed?: number | null | undefined
+}
 
+/**
+ * Telemetry attributes which are part of the GenAI specification and are
+ * namespaced by `gen_ai.response`.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface ResponseAttributes {
   /**
-   * @since 1.0.0
-   * @category models
+   * The unique identifier for the completion.
+   */
+  readonly id?: string | null | undefined
+  /**
+   * The name of the model that generated the response.
    */
-  export type FormatAttributeName<T extends string | number | symbol> = T extends string ?
-    T extends `${infer First}${infer Rest}`
-      ? `${First extends Uppercase<First> ? "_" : ""}${Lowercase<First>}${FormatAttributeName<Rest>}`
-    : T :
-    never
+  readonly model?: string | null | undefined
+  /**
+   * Array of reasons the model stopped generating tokens, corresponding to
+   * each generation received.
+   */
+  readonly finishReasons?: ReadonlyArray<string> | null | undefined
+}
+
+/**
+ * The `gen_ai.operation.name` attribute has the following list of well-known
+ * values.
+ *
+ * If one of them applies, then the respective value **MUST** be used;
+ * otherwise, a custom value **MAY** be used.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export type WellKnownOperationName = "chat" | "embeddings" | "text_completion"
+
+/**
+ * The `gen_ai.system` attribute has the following list of well-known values.
+ *
+ * If one of them applies, then the respective value **MUST** be used;
+ * otherwise, a custom value **MAY** be used.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export type WellKnownSystem =
+  | "anthropic"
+  | "aws.bedrock"
+  | "az.ai.inference"
+  | "az.ai.openai"
+  | "cohere"
+  | "deepseek"
+  | "gemini"
+  | "groq"
+  | "ibm.watsonx.ai"
+  | "mistral_ai"
+  | "openai"
+  | "perplexity"
+  | "vertex_ai"
+  | "xai"
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export type AttributesWithPrefix<Attributes extends Record<string, any>, Prefix extends string> = {
+  [Name in keyof Attributes as `${Prefix}.${FormatAttributeName<Name>}`]: Attributes[Name]
 }
 
 /**
  * @since 1.0.0
- * @category utilities
+ * @category Utility Types
+ */
+export type FormatAttributeName<T extends string | number | symbol> = T extends string ?
+  T extends `${infer First}${infer Rest}`
+    ? `${First extends Uppercase<First> ? "_" : ""}${Lowercase<First>}${FormatAttributeName<Rest>}`
+  : T :
+  never
+
+/**
+ * @since 1.0.0
+ * @category Utilities
  */
 export const addSpanAttributes = (
   keyPrefix: string,
@@ -241,23 +237,23 @@ export const addSpanAttributes = (
   }
 }
 
-const addSpanBaseAttributes = addSpanAttributes("gen_ai", String.camelToSnake)<GenAI.BaseAttributes>
-const addSpanOperationAttributes = addSpanAttributes("gen_ai.operation", String.camelToSnake)<GenAI.OperationAttributes>
-const addSpanRequestAttributes = addSpanAttributes("gen_ai.request", String.camelToSnake)<GenAI.RequestAttributes>
-const addSpanResponseAttributes = addSpanAttributes("gen_ai.response", String.camelToSnake)<GenAI.ResponseAttributes>
-const addSpanTokenAttributes = addSpanAttributes("gen_ai.token", String.camelToSnake)<GenAI.TokenAttributes>
-const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToSnake)<GenAI.UsageAttributes>
+const addSpanBaseAttributes = addSpanAttributes("gen_ai", String.camelToSnake)<BaseAttributes>
+const addSpanOperationAttributes = addSpanAttributes("gen_ai.operation", String.camelToSnake)<OperationAttributes>
+const addSpanRequestAttributes = addSpanAttributes("gen_ai.request", String.camelToSnake)<RequestAttributes>
+const addSpanResponseAttributes = addSpanAttributes("gen_ai.response", String.camelToSnake)<ResponseAttributes>
+const addSpanTokenAttributes = addSpanAttributes("gen_ai.token", String.camelToSnake)<TokenAttributes>
+const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToSnake)<UsageAttributes>
 
 /**
  * @since 1.0.0
- * @since models
+ * @since Models
  */
-export type GenAITelemetryAttributeOptions = GenAI.BaseAttributes & {
-  readonly operation?: GenAI.OperationAttributes | undefined
-  readonly request?: GenAI.RequestAttributes | undefined
-  readonly response?: GenAI.ResponseAttributes | undefined
-  readonly token?: GenAI.TokenAttributes | undefined
-  readonly usage?: GenAI.UsageAttributes | undefined
+export type GenAITelemetryAttributeOptions = BaseAttributes & {
+  readonly operation?: OperationAttributes | undefined
+  readonly request?: RequestAttributes | undefined
+  readonly response?: ResponseAttributes | undefined
+  readonly token?: TokenAttributes | undefined
+  readonly usage?: UsageAttributes | undefined
 }
 
 /**
@@ -266,7 +262,7 @@ export type GenAITelemetryAttributeOptions = GenAI.BaseAttributes & {
  * **NOTE**: This method will mutate the `Span` **in-place**.
  *
  * @since 1.0.0
- * @since utilities
+ * @since Utilities
  */
 export const addGenAIAnnotations: {
   /**
@@ -275,7 +271,7 @@ export const addGenAIAnnotations: {
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
    * @since 1.0.0
-   * @since utilities
+   * @since Utilities
    */
   (options: GenAITelemetryAttributeOptions): (span: Span) => void
   /**
@@ -284,7 +280,7 @@ export const addGenAIAnnotations: {
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
    * @since 1.0.0
-   * @since utilities
+   * @since Utilities
    */
   (span: Span, options: GenAITelemetryAttributeOptions): void
 } = dual<
@@ -294,7 +290,7 @@ export const addGenAIAnnotations: {
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
    * @since 1.0.0
-   * @since utilities
+   * @since Utilities
    */
   (options: GenAITelemetryAttributeOptions) => (span: Span) => void,
   /**
@@ -303,7 +299,7 @@ export const addGenAIAnnotations: {
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
    * @since 1.0.0
-   * @since utilities
+   * @since Utilities
    */
   (span: Span, options: GenAITelemetryAttributeOptions) => void
 >(2, (span, options) => {
@@ -314,3 +310,24 @@ export const addGenAIAnnotations: {
   if (Predicate.isNotNullable(options.token)) addSpanTokenAttributes(span, options.token)
   if (Predicate.isNotNullable(options.usage)) addSpanUsageAttributes(span, options.usage)
 })
+
+/**
+ * Represents a method which receives the elements of the request / response to
+ * a large language model and can be used to modify the span used to trace the
+ * API call.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface SpanTransformer {
+  (options: AiLanguageModelOptions & { readonly response: AiResponse }): void
+}
+
+/**
+ * @since 1.0.0
+ * @category Context
+ */
+export class CurrentSpanTransformer extends Context.Tag("@effect/ai/AiTelemetry/CurrentSpanTransformer")<
+  CurrentSpanTransformer,
+  SpanTransformer
+>() {}