@effect/ai-openai-compat 4.0.0-beta.0

package/src/OpenAiTelemetry.ts

@@ -0,0 +1,159 @@
+/**
+ * OpenAI telemetry attributes for OpenTelemetry integration.
+ *
+ * Provides OpenAI-specific GenAI telemetry attributes following OpenTelemetry
+ * semantic conventions, extending the base GenAI attributes with OpenAI-specific
+ * request and response metadata.
+ *
+ * @since 1.0.0
+ */
+import { dual } from "effect/Function"
+import * as String from "effect/String"
+import type { Span } from "effect/Tracer"
+import type { Simplify } from "effect/Types"
+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
+ * @category models
+ */
+export type OpenAiTelemetryAttributes = Simplify<
+  & Telemetry.GenAITelemetryAttributes
+  & Telemetry.AttributesWithPrefix<RequestAttributes, "gen_ai.openai.request">
+  & Telemetry.AttributesWithPrefix<ResponseAttributes, "gen_ai.openai.request">
+>
+
+/**
+ * All telemetry attributes which are part of the GenAI specification,
+ * including the OpenAi-specific attributes.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type AllAttributes = Telemetry.AllAttributes & RequestAttributes & ResponseAttributes
+
+/**
+ * Telemetry attributes which are part of the GenAI specification and are
+ * namespaced by `gen_ai.openai.request`.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface RequestAttributes {
+  /**
+   * The response format that is requested.
+   */
+  readonly responseFormat?: (string & {}) | WellKnownResponseFormat | null | undefined
+  /**
+   * The service tier requested. May be a specific tier, `default`, or `auto`.
+   */
+  readonly serviceTier?: (string & {}) | WellKnownServiceTier | null | undefined
+}
+
+/**
+ * Telemetry attributes which are part of the GenAI specification and are
+ * namespaced by `gen_ai.openai.response`.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface ResponseAttributes {
+  /**
+   * The service tier used for the response.
+   */
+  readonly serviceTier?: string | null | undefined
+  /**
+   * A fingerprint to track any eventual change in the Generative AI
+   * environment.
+   */
+  readonly systemFingerprint?: string | null | undefined
+}
+
+/**
+ * The `gen_ai.openai.request.response_format` 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 WellKnownResponseFormat = "json_object" | "json_schema" | "text"
+
+/**
+ * The `gen_ai.openai.request.service_tier` 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 WellKnownServiceTier = "auto" | "default"
+
+/**
+ * @since 1.0.0
+ * @since models
+ */
+export type OpenAiTelemetryAttributeOptions = Telemetry.GenAITelemetryAttributeOptions & {
+  openai?: {
+    request?: RequestAttributes | undefined
+    response?: ResponseAttributes | undefined
+  } | undefined
+}
+
+const addOpenAiRequestAttributes = Telemetry.addSpanAttributes("gen_ai.openai.request", String.camelToSnake)<
+  RequestAttributes
+>
+const addOpenAiResponseAttributes = Telemetry.addSpanAttributes("gen_ai.openai.response", String.camelToSnake)<
+  ResponseAttributes
+>
+
+/**
+ * Applies the specified OpenAi GenAI telemetry attributes to the provided
+ * `Span`.
+ *
+ * **NOTE**: This method will mutate the `Span` **in-place**.
+ *
+ * @since 1.0.0
+ * @since utilities
+ */
+export const addGenAIAnnotations: {
+  /**
+   * Applies the specified OpenAi GenAI telemetry attributes to the provided
+   * `Span`.
+   *
+   * **NOTE**: This method will mutate the `Span` **in-place**.
+   *
+   * @since 1.0.0
+   * @since utilities
+   */
+  (options: OpenAiTelemetryAttributeOptions): (span: Span) => void
+  /**
+   * Applies the specified OpenAi GenAI telemetry attributes to the provided
+   * `Span`.
+   *
+   * **NOTE**: This method will mutate the `Span` **in-place**.
+   *
+   * @since 1.0.0
+   * @since utilities
+   */
+  (span: Span, options: OpenAiTelemetryAttributeOptions): void
+} = dual(2, (span: Span, options: OpenAiTelemetryAttributeOptions) => {
+  Telemetry.addGenAIAnnotations(span, options)
+  if (options.openai != null) {
+    if (options.openai.request != null) {
+      addOpenAiRequestAttributes(span, options.openai.request)
+    }
+    if (options.openai.response != null) {
+      addOpenAiResponseAttributes(span, options.openai.response)
+    }
+  }
+})

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @since 1.0.0
+ */
+
+// @barrel: Auto-generated exports. Do not edit manually.
+
+/**
+ * @since 1.0.0
+ */
+export * as OpenAiClient from "./OpenAiClient.ts"
+
+/**
+ * @since 1.0.0
+ */
+export * as OpenAiConfig from "./OpenAiConfig.ts"
+
+/**
+ * @since 1.0.0
+ */
+export * as OpenAiError from "./OpenAiError.ts"
+
+/**
+ * OpenAI Language Model implementation.
+ *
+ * Provides a LanguageModel implementation for OpenAI's chat completions API,
+ * supporting text generation, structured output, tool calling, and streaming.
+ *
+ * @since 1.0.0
+ */
+export * as OpenAiLanguageModel from "./OpenAiLanguageModel.ts"
+
+/**
+ * OpenAI telemetry attributes for OpenTelemetry integration.
+ *
+ * Provides OpenAI-specific GenAI telemetry attributes following OpenTelemetry
+ * semantic conventions, extending the base GenAI attributes with OpenAI-specific
+ * request and response metadata.
+ *
+ * @since 1.0.0
+ */
+export * as OpenAiTelemetry from "./OpenAiTelemetry.ts"

package/src/internal/errors.ts

@@ -0,0 +1,327 @@
+import * as Arr from "effect/Array"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import { dual } from "effect/Function"
+import * as Number from "effect/Number"
+import * as Option from "effect/Option"
+import * as Redactable from "effect/Redactable"
+import * as Schema from "effect/Schema"
+import * as SchemaTransformation from "effect/SchemaTransformation"
+import * as String from "effect/String"
+import * as AiError from "effect/unstable/ai/AiError"
+import type * as Response from "effect/unstable/ai/Response"
+import type * as HttpClientError from "effect/unstable/http/HttpClientError"
+import type * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import type * as HttpClientResponse from "effect/unstable/http/HttpClientResponse"
+import type { OpenAiErrorMetadata } from "../OpenAiError.ts"
+
+/** @internal */
+export const OpenAiErrorBody = Schema.Struct({
+  error: Schema.Struct({
+    message: Schema.String,
+    type: Schema.optional(Schema.NullOr(Schema.String)),
+    status: Schema.optional(Schema.NullOr(Schema.String)),
+    param: Schema.optional(Schema.NullOr(Schema.String)),
+    code: Schema.optional(Schema.NullOr(Schema.Union([Schema.String, Schema.Number])))
+  })
+})
+const OpenAiErrorBodyJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Union([
+  OpenAiErrorBody,
+  Schema.NonEmptyArray(OpenAiErrorBody).pipe(
+    Schema.decodeTo(
+      Schema.toType(OpenAiErrorBody),
+      SchemaTransformation.transform({
+        decode: Arr.headNonEmpty,
+        encode: (item) => [item]
+      })
+    )
+  )
+])))
+
+/** @internal */
+export const mapSchemaError = dual<
+  (method: string) => (error: Schema.SchemaError) => AiError.AiError,
+  (error: Schema.SchemaError, method: string) => AiError.AiError
+>(2, (error, method) =>
+  AiError.make({
+    module: "OpenAiClient",
+    method,
+    reason: AiError.InvalidOutputError.fromSchemaError(error)
+  }))
+
+/** @internal */
+export const mapHttpClientError = dual<
+  (method: string) => (error: HttpClientError.HttpClientError) => Effect.Effect<never, AiError.AiError>,
+  (error: HttpClientError.HttpClientError, method: string) => Effect.Effect<never, AiError.AiError>
+>(2, (error, method) => {
+  const reason = error.reason
+  switch (reason._tag) {
+    case "TransportError": {
+      return Effect.fail(AiError.make({
+        module: "OpenAiClient",
+        method,
+        reason: new AiError.NetworkError({
+          reason: "TransportError",
+          description: reason.description,
+          request: buildHttpRequestDetails(reason.request)
+        })
+      }))
+    }
+    case "EncodeError": {
+      return Effect.fail(AiError.make({
+        module: "OpenAiClient",
+        method,
+        reason: new AiError.NetworkError({
+          reason: "EncodeError",
+          description: reason.description,
+          request: buildHttpRequestDetails(reason.request)
+        })
+      }))
+    }
+    case "InvalidUrlError": {
+      return Effect.fail(AiError.make({
+        module: "OpenAiClient",
+        method,
+        reason: new AiError.NetworkError({
+          reason: "InvalidUrlError",
+          description: reason.description,
+          request: buildHttpRequestDetails(reason.request)
+        })
+      }))
+    }
+    case "StatusCodeError": {
+      return mapStatusCodeError(reason, method)
+    }
+    case "DecodeError": {
+      return Effect.fail(AiError.make({
+        module: "OpenAiClient",
+        method,
+        reason: new AiError.InvalidOutputError({
+          description: reason.description ?? "Failed to decode response"
+        })
+      }))
+    }
+    case "EmptyBodyError": {
+      return Effect.fail(AiError.make({
+        module: "OpenAiClient",
+        method,
+        reason: new AiError.InvalidOutputError({
+          description: reason.description ?? "Response body was empty"
+        })
+      }))
+    }
+  }
+})
+
+/** @internal */
+const mapStatusCodeError = Effect.fnUntraced(function*(
+  error: HttpClientError.StatusCodeError,
+  method: string
+) {
+  const { request, response, description } = error
+  const status = response.status
+  const headers = response.headers as Record<string, string>
+  const requestId = headers["x-request-id"]
+
+  let body = yield* response.text.pipe(
+    Effect.catchCause(() => Effect.succeed(description?.startsWith("{") ? description : undefined))
+  )
+  const decoded = OpenAiErrorBodyJson(body)
+
+  const reason = mapStatusCodeToReason({
+    status,
+    headers,
+    message: Option.isSome(decoded) ? decoded.value.error.message : undefined,
+    http: buildHttpContext({ request, response, body }),
+    metadata: {
+      errorCode: Option.isSome(decoded) ? decoded.value.error.code?.toString() ?? null : null,
+      errorType: decoded.pipe(
+        Option.flatMapNullishOr((d) => d.error.type ?? d.error.status),
+        Option.map(String.toLowerCase),
+        Option.getOrNull
+      ),
+      requestId: requestId ?? null
+    }
+  })
+
+  return yield* AiError.make({ module: "OpenAiClient", method, reason })
+})
+
+/** @internal */
+export const parseRateLimitHeaders = (headers: Record<string, string>) => {
+  const retryAfterRaw = headers["retry-after"]
+  let retryAfter: Duration.Duration | undefined
+  if (retryAfterRaw !== undefined) {
+    const parsed = Number.parse(retryAfterRaw)
+    if (parsed !== undefined) {
+      retryAfter = Duration.seconds(parsed)
+    }
+  }
+  const remainingRaw = headers["x-ratelimit-remaining-requests"]
+  const remaining = remainingRaw !== undefined ? Number.parse(remainingRaw) ?? null : null
+  return {
+    retryAfter,
+    limit: headers["x-ratelimit-limit-requests"] ?? null,
+    remaining,
+    resetRequests: headers["x-ratelimit-reset-requests"] ?? null,
+    resetTokens: headers["x-ratelimit-reset-tokens"] ?? null
+  }
+}
+
+/** @internal */
+export const buildHttpRequestDetails = (
+  request: HttpClientRequest.HttpClientRequest
+): typeof Response.HttpRequestDetails.Type => ({
+  method: request.method,
+  url: request.url,
+  urlParams: Array.from(request.urlParams),
+  hash: request.hash,
+  headers: Redactable.redact(request.headers) as Record<string, string>
+})
+
+/** @internal */
+export const buildHttpContext = (params: {
+  readonly request: HttpClientRequest.HttpClientRequest
+  readonly response?: HttpClientResponse.HttpClientResponse
+  readonly body?: string | undefined
+}): typeof AiError.HttpContext.Type => ({
+  request: buildHttpRequestDetails(params.request),
+  response: params.response !== undefined
+    ? {
+      status: params.response.status,
+      headers: Redactable.redact(params.response.headers) as Record<string, string>
+    }
+    : undefined,
+  body: params.body
+})
+
+const buildInvalidRequestDescription = (params: {
+  readonly status: number
+  readonly message: string | undefined
+  readonly method: string
+  readonly url: string
+  readonly errorCode: string | null
+  readonly errorType: string | null
+  readonly requestId: string | null
+  readonly body: string | undefined
+}): string => {
+  const parts: Array<string> = []
+
+  if (params.message) {
+    parts.push(params.message)
+  } else {
+    parts.push(`HTTP ${params.status}`)
+  }
+
+  parts.push(`(${params.method} ${params.url})`)
+
+  if (params.errorCode) {
+    parts.push(`[code: ${params.errorCode}]`)
+  } else if (params.errorType) {
+    parts.push(`[type: ${params.errorType}]`)
+  }
+
+  if (params.requestId) {
+    parts.push(`[requestId: ${params.requestId}]`)
+  }
+
+  if (!params.message && params.body) {
+    const truncated = params.body.length > 200
+      ? params.body.slice(0, 200) + "..."
+      : params.body
+    parts.push(`Response: ${truncated}`)
+  }
+
+  return parts.join(" ")
+}
+
+/** @internal */
+export const mapStatusCodeToReason = ({ status, headers, message, metadata, http }: {
+  readonly status: number
+  readonly headers: Record<string, string>
+  readonly message: string | undefined
+  readonly metadata: OpenAiErrorMetadata
+  readonly http: typeof AiError.HttpContext.Type
+}): AiError.AiErrorReason => {
+  const invalidRequestDescription = buildInvalidRequestDescription({
+    status,
+    message,
+    method: http.request.method,
+    url: http.request.url,
+    errorCode: metadata.errorCode,
+    errorType: metadata.errorType,
+    requestId: metadata.requestId,
+    body: http.body
+  })
+
+  switch (status) {
+    case 400:
+      return new AiError.InvalidRequestError({
+        description: invalidRequestDescription,
+        metadata: { openai: metadata },
+        http
+      })
+    case 401:
+      return new AiError.AuthenticationError({
+        kind: "InvalidKey",
+        metadata,
+        http
+      })
+    case 403:
+      return new AiError.AuthenticationError({
+        kind: "InsufficientPermissions",
+        metadata,
+        http
+      })
+    case 404:
+      return new AiError.InvalidRequestError({
+        description: invalidRequestDescription,
+        metadata: { openai: metadata },
+        http
+      })
+    case 409:
+    case 422:
+      return new AiError.InvalidRequestError({
+        description: invalidRequestDescription,
+        metadata: { openai: metadata },
+        http
+      })
+    case 429: {
+      if (
+        metadata.errorCode === "insufficient_quota" ||
+        metadata.errorType === "insufficient_quota" ||
+        metadata.errorType?.includes("quota") ||
+        metadata.errorType?.includes("exhausted")
+      ) {
+        return new AiError.QuotaExhaustedError({
+          metadata: { openai: metadata },
+          http
+        })
+      }
+      const { retryAfter, ...rateLimitMetadata } = parseRateLimitHeaders(headers)
+      return new AiError.RateLimitError({
+        retryAfter,
+        metadata: {
+          openai: {
+            ...metadata,
+            ...rateLimitMetadata
+          }
+        },
+        http
+      })
+    }
+    default:
+      if (status >= 500) {
+        return new AiError.InternalProviderError({
+          description: message ?? "Server error",
+          metadata,
+          http
+        })
+      }
+      return new AiError.UnknownError({
+        description: message,
+        metadata,
+        http
+      })
+  }
+}

package/src/internal/utilities.ts

@@ -0,0 +1,33 @@
+import type * as Response from "effect/unstable/ai/Response"
+
+/** @internal */
+export const ProviderOptionsKey = "@effect/ai-openai-compat/OpenAiLanguageModel/ProviderOptions"
+
+/** @internal */
+export const ProviderMetadataKey = "@effect/ai-openai-compat/OpenAiLanguageModel/ProviderMetadata"
+
+const finishReasonMap: Record<string, Response.FinishReason> = {
+  content_filter: "content-filter",
+  function_call: "tool-calls",
+  length: "length",
+  stop: "stop",
+  tool_calls: "tool-calls"
+}
+
+/** @internal */
+export const escapeJSONDelta = (delta: string): string => JSON.stringify(delta).slice(1, -1)
+
+/** @internal */
+export const resolveFinishReason = (
+  finishReason: string | null | undefined,
+  hasToolCalls: boolean
+): Response.FinishReason => {
+  if (finishReason == null) {
+    return hasToolCalls ? "tool-calls" : "stop"
+  }
+  const reason = finishReasonMap[finishReason]
+  if (reason == null) {
+    return hasToolCalls ? "tool-calls" : "unknown"
+  }
+  return reason
+}