@effect-uai/responses 0.5.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/responses",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "OpenAI Responses API provider for @effect-uai/core.",
   "keywords": [
     "ai",
@@ -49,7 +49,7 @@
   "devDependencies": {
     "effect": "4.0.0-beta.57",
     "typescript": "^6.0.3",
-    "@effect-uai/core": "0.5.2"
+    "@effect-uai/core": "0.7.0"
   },
   "peerDependencies": {
     "@effect-uai/core": ">=0.2.0 <1",

package/src/OpenAIEmbedding.ts

@@ -1,6 +1,7 @@
 import { Context, Effect, Layer, Redacted, Schema } from "effect"
 import { HttpClient, HttpClientRequest } from "effect/unstable/http"
 import * as AiError from "@effect-uai/core/AiError"
+import * as Capabilities from "@effect-uai/core/Capabilities"
 import type {
   EmbedContentPart,
   EmbedInput,
@@ -8,6 +9,7 @@ import type {
   Usage,
 } from "@effect-uai/core/Embedding"
 import {
+  assertEncoding,
   type CommonEmbedManyRequest,
   type CommonEmbedRequest,
   type EmbedEncoding,
@@ -17,6 +19,7 @@ import {
   type EmbedResponse,
 } from "@effect-uai/core/EmbeddingModel"
 import type { OpenAIEmbeddingModel } from "./models.js"
+import { type OpenAiRegion, resolveHost } from "./region.js"
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -56,37 +59,36 @@ export class OpenAIEmbedding extends Context.Service<OpenAIEmbedding, OpenAIEmbe
 export type Config = {
   readonly apiKey: Redacted.Redacted
   readonly baseUrl?: string
+  readonly region?: OpenAiRegion
 }
 
 // ---------------------------------------------------------------------------
 // Codec - input flattening to the single string OpenAI expects
 // ---------------------------------------------------------------------------
 
-const imageRejected = (param: string): AiError.AiError =>
-  new AiError.InvalidRequest({
-    provider: "openai",
-    param,
-    raw: "OpenAI embeddings are text-only; pass a string or { text }",
-  })
+// Image input on a text-only embedder is bucket 1: a silently dropped image
+// yields a vector that represents the wrong thing. Reject with `Unsupported`
+// (capability gap), not `InvalidRequest` (which is for wire-shape mismatches).
+// OpenAI's embeddings API remains text-only as of June 2026.
+const imageRejected: AiError.AiError = new AiError.Unsupported({
+  provider: "openai",
+  capability: "imageEmbedding",
+  reason: "OpenAI embeddings are text-only; pass a string or { text }.",
+})
 
-const partToText = (
-  param: string,
-  part: EmbedContentPart,
-): Effect.Effect<string, AiError.AiError> =>
-  "text" in part ? Effect.succeed(part.text) : Effect.fail(imageRejected(param))
+const partToText = (part: EmbedContentPart): Effect.Effect<string, AiError.AiError> =>
+  "text" in part ? Effect.succeed(part.text) : Effect.fail(imageRejected)
 
 /**
  * OpenAI accepts a single string per input. Pure-text `content[]` is
  * concatenated with newlines (treats them as paragraphs of one document);
- * any image part fails with `InvalidRequest`.
+ * any image part fails with `Unsupported`.
  */
 const inputToString = (input: EmbedInput): Effect.Effect<string, AiError.AiError> => {
   if (typeof input === "string") return Effect.succeed(input)
   if ("text" in input) return Effect.succeed(input.text)
-  if ("image" in input) return Effect.fail(imageRejected("input.image"))
-  return Effect.forEach(input.content, (p, i) => partToText(`input.content[${i}].image`, p)).pipe(
-    Effect.map((texts) => texts.join("\n")),
-  )
+  if ("image" in input) return Effect.fail(imageRejected)
+  return Effect.forEach(input.content, partToText).pipe(Effect.map((texts) => texts.join("\n")))
 }
 
 // ---------------------------------------------------------------------------
@@ -176,15 +178,13 @@ const transportFailure = (cause: unknown): AiError.AiError =>
 // HTTP plumbing
 // ---------------------------------------------------------------------------
 
-const baseUrl = (cfg: Config): string => cfg.baseUrl ?? "https://api.openai.com/v1"
-
 const postEmbed = (
   cfg: Config,
   body: WireBody,
 ): Effect.Effect<typeof WireResponse.Type, AiError.AiError, HttpClient.HttpClient> =>
   Effect.gen(function* () {
     const client = yield* HttpClient.HttpClient
-    const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/embeddings`).pipe(
+    const httpRequest = HttpClientRequest.post(`${resolveHost(cfg)}/embeddings`).pipe(
       HttpClientRequest.bearerToken(cfg.apiKey),
       HttpClientRequest.bodyJsonUnsafe(body),
     )
@@ -205,6 +205,16 @@ const postEmbed = (
 
 const usageOf = (u: typeof WireUsage.Type): Usage => ({ inputTokens: u.prompt_tokens })
 
+// `task` is dropped on the generic path (OpenAI has no task parameter on any
+// model, so this is a per-Layer gap, not per-model). Bucket 2: warn, don't fail.
+const warnTaskDropped = (task: CommonEmbedRequest["task"]): Effect.Effect<void> =>
+  Capabilities.warnDroppedWhen(task, {
+    provider: "openai",
+    capability: "task",
+    field: "task",
+    reason: "OpenAI embeddings have no task-type parameter.",
+  })
+
 const embedImpl =
   (cfg: Config) =>
   (
@@ -272,19 +282,24 @@ export const layer = (
     Effect.map(
       make(cfg),
       (s): EmbeddingModelService => ({
-        // OpenAI only emits float32; the cast is sound for the 99% case.
-        // A caller asking for a non-float32 encoding via the generic tag
-        // gets the type they requested but the runtime returns float32.
+        // OpenAI emits float32 only and has no task parameter. Reject a
+        // non-float32 `encoding` (bucket 1, else a float32 vector comes back
+        // mislabeled as the requested type) and warn on a dropped `task`
+        // (bucket 2).
         embed: <E extends EmbedEncoding | undefined = undefined>(
           req: Omit<CommonEmbedRequest, "encoding"> & { readonly encoding?: E },
-        ) => s.embed(req as OpenAIEmbedRequest) as Effect.Effect<EmbedResponse<E>, AiError.AiError>,
+        ) =>
+          assertEncoding(req.encoding, ["float32"], "openai").pipe(
+            Effect.andThen(warnTaskDropped(req.task)),
+            Effect.andThen(s.embed(req as OpenAIEmbedRequest)),
+          ) as Effect.Effect<EmbedResponse<E>, AiError.AiError>,
         embedMany: <E extends EmbedEncoding | undefined = undefined>(
           req: Omit<CommonEmbedManyRequest, "encoding"> & { readonly encoding?: E },
         ) =>
-          s.embedMany(req as OpenAIEmbedManyRequest) as Effect.Effect<
-            EmbedManyResponse<E>,
-            AiError.AiError
-          >,
+          assertEncoding(req.encoding, ["float32"], "openai").pipe(
+            Effect.andThen(warnTaskDropped(req.task)),
+            Effect.andThen(s.embedMany(req as OpenAIEmbedManyRequest)),
+          ) as Effect.Effect<EmbedManyResponse<E>, AiError.AiError>,
       }),
     ),
   )

package/src/Responses.ts

@@ -12,6 +12,7 @@ import * as SSE from "@effect-uai/core/SSE"
 import type { Turn, TurnEvent } from "@effect-uai/core/Turn"
 import { itemsToInput } from "./codec.js"
 import type { OpenAIModel } from "./models.js"
+import { type OpenAiRegion, resolveHost } from "./region.js"
 import {
   KnownProviderEvent,
   ProviderEvent,
@@ -95,6 +96,7 @@ export class Responses extends Context.Service<Responses, ResponsesService>()(
 export type Config = {
   readonly apiKey: Redacted.Redacted
   readonly baseUrl?: string
+  readonly region?: OpenAiRegion
 }
 
 // ---------------------------------------------------------------------------
@@ -222,7 +224,7 @@ const httpStatusError = (status: number, body: string): AiError.AiError => {
 }
 
 const buildNativeStream = (cfg: Config) => {
-  const url = `${cfg.baseUrl ?? "https://api.openai.com/v1"}/responses`
+  const url = `${resolveHost(cfg)}/responses`
   return (
     request: ResponsesRequest,
   ): Stream.Stream<ProviderEvent, AiError.AiError, HttpClient.HttpClient> =>

package/src/codec.ts

@@ -1,5 +1,5 @@
 import { Encoding, Match, Option, Schema } from "effect"
-import type { ContentBlock, InputImage, Item } from "@effect-uai/core/Items"
+import type { ContentBlock, InputImage, HistoryItem } from "@effect-uai/core/Items"
 import type { Turn } from "@effect-uai/core/Turn"
 
 // ---------------------------------------------------------------------------
@@ -137,7 +137,7 @@ export type WireResponseCompleted = typeof WireResponseCompleted.Type
  * verbatim - preserves `encrypted_content`, item ids, and any field this
  * codec doesn't model.
  */
-const passthrough = (item: Item): Record<string, unknown> | undefined =>
+const passthrough = (item: HistoryItem): Record<string, unknown> | undefined =>
   item.providerData !== undefined &&
   typeof item.providerData === "object" &&
   item.providerData !== null
@@ -168,7 +168,7 @@ const contentBlockToInput = Match.type<ContentBlock>().pipe(
   }),
 )
 
-const itemToInput = (item: Item): Record<string, unknown> =>
+const itemToInput = (item: HistoryItem): Record<string, unknown> =>
   passthrough(item) ??
   Match.value(item).pipe(
     Match.discriminatorsExhaustive("type")({
@@ -199,9 +199,10 @@ const itemToInput = (item: Item): Record<string, unknown> =>
     }),
   )
 
-/** Convert our `Item[]` history into the Responses API `input` array. */
-export const itemsToInput = (items: ReadonlyArray<Item>): ReadonlyArray<Record<string, unknown>> =>
-  items.map(itemToInput)
+/** Convert our `HistoryItem[]` history into the Responses API `input` array. */
+export const itemsToInput = (
+  items: ReadonlyArray<HistoryItem>,
+): ReadonlyArray<Record<string, unknown>> => items.map(itemToInput)
 
 // ---------------------------------------------------------------------------
 // Wire output items → our Items
@@ -218,7 +219,7 @@ const wireMessageContentToBlock = Match.type<typeof WireMessageContent.Type>().p
   }),
 )
 
-export const wireItemToItem = (wire: WireOutputItem): Item =>
+export const wireItemToItem = (wire: WireOutputItem): HistoryItem =>
   Match.value(wire).pipe(
     Match.discriminatorsExhaustive("type")({
       message: (m) => ({

package/src/index.ts

@@ -3,3 +3,4 @@ export * as OpenAIEmbedding from "./OpenAIEmbedding.js"
 export * as codec from "./codec.js"
 export * as streamEvents from "./streamEvents.js"
 export * from "./models.js"
+export * from "./region.js"

package/src/region.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest"
+import { resolveHost } from "./region.js"
+
+describe("responses/region.resolveHost", () => {
+  it("returns default host when no region or baseUrl", () => {
+    expect(resolveHost({})).toBe("https://api.openai.com/v1")
+  })
+
+  it("returns default host for region 'default'", () => {
+    expect(resolveHost({ region: "default" })).toBe("https://api.openai.com/v1")
+  })
+
+  it("computes EU host for region 'eu'", () => {
+    expect(resolveHost({ region: "eu" })).toBe("https://eu.api.openai.com/v1")
+  })
+
+  it("passes unknown region through as host prefix", () => {
+    expect(resolveHost({ region: "apac" })).toBe("https://apac.api.openai.com/v1")
+  })
+
+  it("baseUrl wins over region", () => {
+    expect(resolveHost({ baseUrl: "http://localhost:8080/v1", region: "eu" })).toBe(
+      "http://localhost:8080/v1",
+    )
+  })
+})

package/src/region.ts

@@ -0,0 +1,29 @@
+/**
+ * OpenAI regional endpoints. `eu.api.openai.com` covers `/v1/responses`
+ * and `/v1/embeddings` (along with the rest of the REST surface) for
+ * projects with EU data residency enabled. Keys are project-scoped.
+ *
+ * Reference: https://developers.openai.com/api/docs/guides/your-data
+ *
+ * Defined locally in this package rather than imported from
+ * `@effect-uai/openai` to keep the packages decoupled.
+ */
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type OpenAiRegion = "default" | "eu" | (string & {})
+
+const DEFAULT_HOST = "https://api.openai.com/v1"
+
+/**
+ * Resolve the HTTP base URL from a Config. `baseUrl` wins when set;
+ * otherwise the host is computed from `region`. Unknown region strings
+ * pass through as `{region}.api.openai.com/v1` for forward compat.
+ */
+export const resolveHost = (cfg: {
+  readonly baseUrl?: string
+  readonly region?: OpenAiRegion
+}): string => {
+  if (cfg.baseUrl !== undefined) return cfg.baseUrl
+  if (cfg.region === undefined || cfg.region === "default") return DEFAULT_HOST
+  return `https://${cfg.region}.api.openai.com/v1`
+}