@galdor/provider-openai 0.3.0

package/src/embed.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Tests for the OpenAI embedder, each pointing the embedder at an ephemeral
+ * local server that impersonates the `/embeddings` endpoint.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { newEmbedder } from "./embed.ts";
+
+let server: { stop(): void; url: string } | undefined;
+
+afterEach(() => {
+  server?.stop();
+  server = undefined;
+});
+
+function serve(handler: (req: Request) => Response | Promise<Response>): string {
+  const s = Bun.serve({ port: 0, fetch: handler });
+  server = { stop: () => s.stop(true), url: `http://localhost:${s.port}` };
+  return server.url;
+}
+
+describe("OpenAIEmbedder", () => {
+  test("posts model + input and returns vectors in input order", async () => {
+    let received: any;
+    let auth = "";
+    const url = serve(async (req) => {
+      received = await req.json();
+      auth = req.headers.get("authorization") ?? "";
+      // Return out of order to prove the embedder reorders by `index`.
+      return Response.json({
+        model: "text-embedding-3-small",
+        data: [
+          { index: 1, embedding: [0.3, 0.4] },
+          { index: 0, embedding: [0.1, 0.2] },
+        ],
+      });
+    });
+
+    const embedder = newEmbedder({ apiKey: "sk-test", baseURL: url });
+    const vecs = await embedder.embed(["first", "second"]);
+
+    expect(auth).toBe("Bearer sk-test");
+    expect(received.model).toBe("text-embedding-3-small");
+    expect(received.input).toEqual(["first", "second"]);
+    expect(received.dimensions).toBeUndefined(); // not sent unless explicitly configured
+    expect(vecs).toEqual([
+      [0.1, 0.2],
+      [0.3, 0.4],
+    ]);
+  });
+
+  test("dimensions(): default is 1536; explicit dim is sent and reported", async () => {
+    expect(newEmbedder({ apiKey: "k" }).dimensions()).toBe(1536);
+
+    let received: any;
+    const url = serve(async (req) => {
+      received = await req.json();
+      return Response.json({ data: [{ index: 0, embedding: [1, 2, 3, 4] }] });
+    });
+    const embedder = newEmbedder({ apiKey: "k", dimensions: 4, baseURL: url });
+    expect(embedder.dimensions()).toBe(4);
+    await embedder.embed(["x"]);
+    expect(received.dimensions).toBe(4);
+  });
+
+  test("empty input is a no-op (no request)", async () => {
+    let called = false;
+    const url = serve(() => {
+      called = true;
+      return Response.json({ data: [] });
+    });
+    const out = await newEmbedder({ apiKey: "k", baseURL: url }).embed([]);
+    expect(out).toEqual([]);
+    expect(called).toBe(false);
+  });
+
+  test("throws on a non-2xx response", async () => {
+    const url = serve(() => new Response(JSON.stringify({ error: { message: "bad" } }), { status: 401 }));
+    await expect(newEmbedder({ apiKey: "k", baseURL: url }).embed(["x"])).rejects.toThrow();
+  });
+
+  test("throws when the count of returned vectors is wrong", async () => {
+    const url = serve(() => Response.json({ data: [{ index: 0, embedding: [1] }] }));
+    await expect(newEmbedder({ apiKey: "k", baseURL: url }).embed(["a", "b"])).rejects.toThrow(/1 vectors for 2/);
+  });
+
+  test("requires an apiKey", () => {
+    expect(() => newEmbedder({ apiKey: "" })).toThrow(/apiKey/);
+  });
+});

package/src/embed.ts

@@ -0,0 +1,162 @@
+/**
+ * OpenAI embeddings — a galdor {@link Embedder} over the `/embeddings` endpoint.
+ *
+ * Works against the OpenAI API and any OpenAI-compatible endpoint (Mistral,
+ * Together, MiniMax, vLLM, Ollama, …) by pointing {@link EmbedderConfig.baseURL}
+ * at it. Construct one with {@link newEmbedder}.
+ */
+
+import type { Embedder } from "@galdor/core/memory";
+import { normalizeHTTPError } from "./errors.ts";
+
+/** OpenAI's default embedding model and its native dimensionality. */
+const DEFAULT_MODEL = "text-embedding-3-small";
+const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+
+/** Native vector size for a model when no explicit `dimensions` is configured. */
+function nativeDim(model: string): number {
+  return model === "text-embedding-3-large" ? 3072 : 1536;
+}
+
+/** Configuration for an {@link OpenAIEmbedder}. */
+export interface EmbedderConfig {
+  /** Authenticates against the API. Required. */
+  apiKey: string;
+  /** Embedding model id. Defaults to `"text-embedding-3-small"`. */
+  model?: string;
+  /**
+   * Vector size. Defaults to the model's native size (1536 for
+   * `text-embedding-3-small`). When set and the model supports it (the
+   * `text-embedding-3-*` family), it is sent as `dimensions` to truncate output.
+   */
+  dimensions?: number;
+  /** Overrides the API endpoint. Default `https://api.openai.com/v1`; the `/v1` segment is part of it. */
+  baseURL?: string;
+  /** Sent as `openai-organization` when non-empty. */
+  organization?: string;
+  /** Sent as `openai-project` when non-empty. */
+  project?: string;
+  /** Sent as the `User-Agent` header when non-empty. */
+  userAgent?: string;
+  /** Per-request timeout in milliseconds. Defaults to 60000; `0` disables it. */
+  timeoutMs?: number;
+}
+
+/** Wire shape of an `/embeddings` response. */
+interface EmbeddingResponse {
+  data?: { index: number; embedding: number[] }[];
+  model?: string;
+}
+
+/**
+ * A galdor {@link Embedder} backed by the OpenAI embeddings API.
+ *
+ * @example
+ * ```ts
+ * const embedder = newEmbedder({ apiKey: process.env.OPENAI_API_KEY! });
+ * const [vec] = await embedder.embed(["quito ecuador capital"]);
+ * ```
+ */
+export class OpenAIEmbedder implements Embedder {
+  readonly #apiKey: string;
+  readonly #model: string;
+  /** Configured size, or learned from the first response when not configured. 0 = unknown. */
+  #dim: number;
+  readonly #explicitDim: boolean;
+  readonly #baseURL: string;
+  readonly #organization: string;
+  readonly #project: string;
+  readonly #userAgent: string;
+  readonly #timeoutMs: number;
+
+  /**
+   * @param cfg - Embedder configuration; `apiKey` is required.
+   * @throws {Error} When `apiKey` is missing or blank.
+   */
+  constructor(cfg: EmbedderConfig) {
+    if (!cfg.apiKey || cfg.apiKey.trim() === "") throw new Error("openai: apiKey is required");
+    this.#apiKey = cfg.apiKey;
+    this.#model = cfg.model && cfg.model.trim() !== "" ? cfg.model : DEFAULT_MODEL;
+    this.#explicitDim = typeof cfg.dimensions === "number" && cfg.dimensions > 0;
+    // Leave 0 (unknown) when not configured; the first response fills it in.
+    this.#dim = this.#explicitDim ? cfg.dimensions! : 0;
+    this.#baseURL = (cfg.baseURL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#organization = cfg.organization ?? "";
+    this.#project = cfg.project ?? "";
+    this.#userAgent = cfg.userAgent ?? "";
+    this.#timeoutMs = cfg.timeoutMs ?? 60_000;
+  }
+
+  /** @returns The embedding model id. */
+  model(): string {
+    return this.#model;
+  }
+
+  /**
+   * @returns The embedding vector size: the configured/learned size when known,
+   *   otherwise the model's native default until the first response sets it.
+   */
+  dimensions(): number {
+    return this.#dim > 0 ? this.#dim : nativeDim(this.#model);
+  }
+
+  /**
+   * Embed each input text, preserving order: `out[i]` is the vector for `texts[i]`.
+   *
+   * @param texts - Inputs to embed; an empty array returns `[]`.
+   * @returns One vector per input, ordered to match `texts`.
+   * @throws {Error} On a non-2xx response, or when the API returns the wrong number of vectors.
+   */
+  async embed(texts: string[], signal?: AbortSignal): Promise<number[][]> {
+    if (texts.length === 0) return [];
+    const body: Record<string, unknown> = { model: this.#model, input: texts, encoding_format: "float" };
+    // Only the text-embedding-3-* family accepts an explicit `dimensions`.
+    if (this.#explicitDim) body.dimensions = this.#dim;
+
+    // Bound the whole request; a caller signal aborts alongside the timeout.
+    const timeout = this.#timeoutMs > 0 ? AbortSignal.timeout(this.#timeoutMs) : undefined;
+    const sig = signal && timeout ? AbortSignal.any([signal, timeout]) : (signal ?? timeout);
+    const res = await fetch(`${this.#baseURL}/embeddings`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${this.#apiKey}`,
+        "content-type": "application/json",
+        ...(this.#organization ? { "openai-organization": this.#organization } : {}),
+        ...(this.#project ? { "openai-project": this.#project } : {}),
+        ...(this.#userAgent ? { "user-agent": this.#userAgent } : {}),
+      },
+      body: JSON.stringify(body),
+      ...(sig ? { signal: sig } : {}),
+    });
+    if (Math.floor(res.status / 100) !== 2) throw await normalizeHTTPError(res);
+
+    const parsed = (await res.json()) as EmbeddingResponse;
+    const data = parsed.data ?? [];
+    if (data.length !== texts.length) {
+      throw new Error(`openai: embeddings returned ${data.length} vectors for ${texts.length} inputs`);
+    }
+    // The API may return out-of-order; place each vector at its reported index.
+    const out = new Array<number[]>(texts.length);
+    for (const item of data) {
+      if (item.index < 0 || item.index >= texts.length) {
+        throw new Error(`openai: embedding index ${item.index} out of range`);
+      }
+      out[item.index] = item.embedding;
+    }
+    // Cache the native dimensionality from the first successful response so
+    // dimensions() doesn't lie; a configured Dim stays authoritative.
+    if (this.#dim === 0 && out[0]) this.#dim = out[0].length;
+    return out;
+  }
+}
+
+/**
+ * Construct an {@link OpenAIEmbedder}.
+ *
+ * @param cfg - Embedder configuration; `apiKey` is required.
+ * @returns A ready embedder.
+ * @throws {Error} When `apiKey` is missing or blank.
+ */
+export function newEmbedder(cfg: EmbedderConfig): OpenAIEmbedder {
+  return new OpenAIEmbedder(cfg);
+}

package/src/errors.ts

@@ -0,0 +1,103 @@
+/**
+ * Normalizes failed OpenAI HTTP responses into galdor's typed {@link APIError}
+ * hierarchy. Maps the raw status code to an {@link ErrorKind}, then refines that
+ * kind from OpenAI's structured `error.type` / `error.code` body when present,
+ * and surfaces any `Retry-After` hint.
+ */
+
+import { APIError, classify, type ErrorKind, parseRetryAfter } from "@galdor/core/provider";
+
+const PROVIDER_NAME = "openai";
+
+interface OpenAIErrorBody {
+  error?: { type?: string; code?: string; param?: string; message?: string };
+}
+
+/** Map a bare HTTP status code to a coarse {@link ErrorKind}. */
+function kindForStatus(code: number): ErrorKind {
+  if (code === 401 || code === 403) return "auth";
+  if (code === 429) return "rate_limited";
+  if (code >= 500) return "server";
+  if (code >= 400) return "invalid_request";
+  return "server";
+}
+
+/**
+ * Refine an error classification from OpenAI's structured `error.type` and
+ * `error.code` fields, used when the bare status code is too ambiguous to
+ * classify on its own — for example, some OpenAI-compatible backends report a
+ * blown context window as a generic 400.
+ *
+ * @param t - The OpenAI `error.type` discriminator, if any.
+ * @param code - The OpenAI `error.code` discriminator, if any.
+ * @returns The refined {@link ErrorKind}, or `undefined` when neither field is
+ * recognized and the caller should fall back to the status-based kind.
+ */
+export function kindForType(t: string | undefined, code: string | undefined): ErrorKind | undefined {
+  switch (t) {
+    case "invalid_request_error":
+      return code === "context_length_exceeded" ? "context_window" : "invalid_request";
+    case "authentication_error":
+    case "permission_error":
+      return "auth";
+    case "rate_limit_error":
+    case "tokens_exceeded":
+      return "rate_limited";
+    case "server_error":
+    case "internal_server_error":
+      return "server";
+  }
+  switch (code) {
+    case "context_length_exceeded":
+      return "context_window";
+    case "rate_limit_exceeded":
+      return "rate_limited";
+    case "invalid_api_key":
+      return "auth";
+  }
+  return undefined;
+}
+
+/**
+ * Minimal structural view of an HTTP response that {@link normalizeHTTPError}
+ * needs: the status code, a header accessor, and a text body reader. Any Fetch
+ * `Response` satisfies this shape.
+ */
+export interface ResponseLike {
+  status: number;
+  headers: { get(name: string): string | null };
+  text(): Promise<string>;
+}
+
+/**
+ * Convert a non-2xx OpenAI response into a typed, classified galdor
+ * {@link APIError}.
+ *
+ * @param res - The failed HTTP response (status, headers, body).
+ * @returns A classified {@link APIError} carrying the provider name, status
+ * code, best-effort message, and any parsed `Retry-After` delay.
+ * @example
+ * ```ts
+ * const res = await fetch(url, opts);
+ * if (Math.floor(res.status / 100) !== 2) throw await normalizeHTTPError(res);
+ * ```
+ */
+export async function normalizeHTTPError(res: ResponseLike): Promise<APIError> {
+  const text = await res.text().catch(() => "");
+  let kind = kindForStatus(res.status);
+  let message = `openai: HTTP ${res.status}`;
+  if (text) {
+    try {
+      const body = JSON.parse(text) as OpenAIErrorBody;
+      if (body.error?.message) message = body.error.message;
+      const k = kindForType(body.error?.type, body.error?.code);
+      if (k) kind = k;
+    } catch {
+      /* non-JSON body: keep the status-based kind */
+    }
+  }
+  const retryAfter = parseRetryAfter(res.headers.get("retry-after") ?? "", new Date());
+  return classify(
+    new APIError({ kind, provider: PROVIDER_NAME, statusCode: res.status, message, ...(retryAfter !== null ? { retryAfter } : {}) }),
+  );
+}

package/src/index.ts

@@ -0,0 +1,198 @@
+/**
+ * @galdor/provider-openai — OpenAI (Chat Completions API) adapter.
+ *
+ * Implements the galdor {@link Provider} interface over /chat/completions, with
+ * tool calling, vision input, structured output (`response_format` json_schema)
+ * and SSE streaming.
+ *
+ * Because the OpenAI Chat Completions surface is the de facto wire standard, the
+ * same adapter targets any OpenAI-compatible provider (Groq, Together, MiniMax,
+ * Mistral, DeepSeek, vLLM, Ollama, ...) by pointing the `baseURL` config field at
+ * their endpoint. The primary entry point is {@link newOpenAI}.
+ */
+
+import {
+  APIError,
+  type Capabilities,
+  classify,
+  type Event,
+  fetchWithHeaderTimeout,
+  type Provider,
+  type Request,
+  type Response,
+  type RunContext,
+  validateRequest,
+} from "@galdor/core/provider";
+import { buildRequest, type ChatResponse, responseFromWire } from "./convert.ts";
+import { normalizeHTTPError } from "./errors.ts";
+import { streamChat } from "./stream.ts";
+
+const PROVIDER_NAME = "openai";
+
+/**
+ * Default production API endpoint. It already includes the `/v1` path segment,
+ * so the adapter only appends `/chat/completions` — the convention used by the
+ * official OpenAI client libraries and by every OpenAI-compatible provider's
+ * documentation.
+ */
+const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+
+/** Configuration for an {@link OpenAIProvider}. */
+export interface Config {
+  /** Authenticates against the OpenAI API. Required. */
+  apiKey: string;
+  /**
+   * Overrides the API endpoint. Default https://api.openai.com/v1. Set this to
+   * point at an OpenAI-compatible provider (Groq, Together, MiniMax, Mistral,
+   * DeepSeek, vLLM, Ollama, ...). The /v1 segment is part of the baseURL.
+   */
+  baseURL?: string;
+  /** Sent as openai-organization when non-empty. */
+  organization?: string;
+  /** Sent as openai-project when non-empty. */
+  project?: string;
+  /** Appended to the default user-agent when non-empty. */
+  userAgent?: string;
+  /**
+   * Response-header timeout in milliseconds: abort if the server doesn't return
+   * headers in time. Streaming bodies are NOT cut off once headers arrive.
+   * Defaults to 60000 (60 s); `0` disables it. Also settable via
+   * `LLM_HTTP_TIMEOUT` through providerset.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * galdor {@link Provider} backed by the OpenAI Chat Completions API (or any
+ * OpenAI-compatible endpoint selected via {@link Config.baseURL}).
+ *
+ * Use {@link newOpenAI} to construct one, or instantiate directly.
+ *
+ * @example
+ * ```ts
+ * const provider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! });
+ * const res = await provider.generate({ model: "gpt-4o-mini", messages });
+ * ```
+ */
+export class OpenAIProvider implements Provider {
+  readonly #apiKey: string;
+  readonly #baseURL: string;
+  readonly #organization: string;
+  readonly #project: string;
+  readonly #userAgent: string;
+  readonly #timeoutMs: number;
+
+  /**
+   * @param cfg - Provider configuration; `apiKey` is required.
+   * @throws {Error} When `apiKey` is missing or blank.
+   */
+  constructor(cfg: Config) {
+    if (!cfg.apiKey || cfg.apiKey.trim() === "") throw new Error("openai: apiKey is required");
+    this.#apiKey = cfg.apiKey;
+    this.#baseURL = (cfg.baseURL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#organization = cfg.organization ?? "";
+    this.#project = cfg.project ?? "";
+    this.#userAgent = cfg.userAgent ?? "";
+    this.#timeoutMs = cfg.timeoutMs ?? 60_000;
+  }
+
+  /** @returns The provider's stable identifier, `"openai"`. */
+  name(): string {
+    return PROVIDER_NAME;
+  }
+
+  /** @returns The feature set this adapter supports. */
+  capabilities(): Capabilities {
+    // promptCaching is false: OpenAI's caching is automatic and ignores
+    // CacheControl hints. maxContextTokens reflects the gpt-4o long-context tier.
+    return {
+      streaming: true,
+      toolCalling: true,
+      structuredOutput: true,
+      promptCaching: false,
+      visionInput: true,
+      reasoning: true,
+      maxContextTokens: 128_000,
+    };
+  }
+
+  #headers(): Record<string, string> {
+    let ua = "galdor-openai/0.1";
+    if (this.#userAgent) ua += ` ${this.#userAgent}`;
+    return {
+      authorization: `Bearer ${this.#apiKey}`,
+      "content-type": "application/json",
+      "user-agent": ua,
+      ...(this.#organization ? { "openai-organization": this.#organization } : {}),
+      ...(this.#project ? { "openai-project": this.#project } : {}),
+    };
+  }
+
+  /**
+   * Run a single non-streaming completion.
+   *
+   * @param req - The galdor request to send.
+   * @param ctx - Optional run context; its `signal` cancels the request.
+   * @returns The decoded galdor {@link Response}.
+   * @throws {APIError} When the API returns a non-2xx status, or when the body
+   * cannot be decoded as JSON.
+   */
+  async generate(req: Request, ctx?: RunContext): Promise<Response> {
+    const capErr = validateRequest(this.capabilities(), req);
+    if (capErr) throw capErr;
+    const wire = buildRequest(req, false);
+    const res = await fetchWithHeaderTimeout(
+      `${this.#baseURL}/chat/completions`,
+      { method: "POST", headers: this.#headers(), body: JSON.stringify(wire) },
+      this.#timeoutMs,
+      ctx?.signal,
+    );
+    if (Math.floor(res.status / 100) !== 2) throw await normalizeHTTPError(res);
+
+    const raw = new Uint8Array(await res.arrayBuffer());
+    let body: ChatResponse;
+    try {
+      body = JSON.parse(new TextDecoder().decode(raw)) as ChatResponse;
+    } catch (e) {
+      throw classify(
+        new APIError({ kind: "server", provider: PROVIDER_NAME, statusCode: res.status, message: `decode response: ${(e as Error).message}` }),
+      );
+    }
+    return responseFromWire(body, raw);
+  }
+
+  /**
+   * Run a streaming completion, yielding provider {@link Event}s as they arrive.
+   *
+   * @param req - The galdor request to send.
+   * @param ctx - Optional run context; its `signal` cancels the stream.
+   * @returns An async iterable of provider events ending in MessageStop.
+   * @throws {APIError} When the initial response is non-2xx or an in-stream
+   * error frame is received (surfaced while iterating).
+   */
+  stream(req: Request, ctx?: RunContext): AsyncIterable<Event> {
+    const capErr = validateRequest(this.capabilities(), req);
+    if (capErr) throw capErr;
+    const wire = buildRequest(req, true);
+    return streamChat(`${this.#baseURL}/chat/completions`, this.#headers(), wire, ctx?.signal, this.#timeoutMs);
+  }
+}
+
+/**
+ * Construct an {@link OpenAIProvider}.
+ *
+ * @param cfg - Provider configuration; `apiKey` is required.
+ * @returns A ready-to-use provider instance.
+ * @throws {Error} When `apiKey` is missing or blank.
+ * @example
+ * ```ts
+ * const provider = newOpenAI({ apiKey: process.env.OPENAI_API_KEY! });
+ * const res = await provider.generate({ model: "gpt-4o-mini", messages });
+ * ```
+ */
+export function newOpenAI(cfg: Config): OpenAIProvider {
+  return new OpenAIProvider(cfg);
+}
+
+export { normalizeHTTPError } from "./errors.ts";
+export { type EmbedderConfig, newEmbedder, OpenAIEmbedder } from "./embed.ts";