Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

refactor(providers): extract OpenAI transport into shared module (#371) (#462)

Rohit Ghumare06248fd199fc
diff --git a/src/providers/_openai-shared.ts b/src/providers/_openai-shared.ts
new file mode 100644
index 00000000..b35cca99
--- /dev/null
+++ b/src/providers/_openai-shared.ts
@@ -0,0 +1,138 @@
+// Shared transport helpers for the OpenAI-compatible LLM + embedding
+// providers. Both surfaces (chat completions, embeddings) speak the
+// same wire shape on the standard OpenAI path. Azure OpenAI ships
+// two URL styles and we support both:
+//
+// - Legacy/stable: `/openai/deployments/<deployment>/chat/completions`
+// with mandatory `api-version=<date>` query param. The deployment
+// name lives in the URL path. Required api-version moves with
+// every Azure date-stamped revision; we keep the
+// `OPENAI_API_VERSION` env knob + `DEFAULT_AZURE_API_VERSION`
+// fallback so existing configs don't break on upgrade.
+//
+// - v1 (GA Apr-2025): `/openai/v1/chat/completions`. No
+// api-version query param, no `/deployments/` segment. Deployment
+// name is passed in the request body as `model`. This matches
+// the OpenAI wire shape one-for-one which is the whole point of
+// v1 — drop-in compatibility.
+//
+// Auto-detection runs off the URL shape, not a flag: if the path
+// already carries `/deployments/`, we route through the legacy
+// builder; otherwise v1. Users opt into v1 by stripping the
+// `/openai/deployments/<deployment>` suffix from their
+// OPENAI_BASE_URL (or never adding it). See azureStyleOf().
+
+export const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com";
+
+// Default api-version for the legacy Azure URL pattern. Only used
+// when the configured base URL carries `/deployments/` AND
+// OPENAI_API_VERSION is unset. The v1 path ignores this entirely.
+export const DEFAULT_AZURE_API_VERSION = "2024-08-01-preview";
+
+type AzureStyle = "legacy" | "v1";
+
+// Azure resource URLs land at <resource>.openai.azure.com.
+export function detectAzure(baseUrl: string): boolean {
+ try {
+ const u = new URL(baseUrl);
+ return u.hostname.endsWith(".openai.azure.com");
+ } catch {
+ return false;
+ }
+}
+
+// Pick the Azure URL style off the base URL's path shape. We only
+// consult this when detectAzure(baseUrl) has already returned true.
+function azureStyleOf(baseUrl: string): AzureStyle {
+ try {
+ const u = new URL(baseUrl);
+ // `/openai/deployments/<deployment>` (with or without a trailing
+ // segment) signals the legacy URL pattern. Anything else — a
+ // bare resource host, an `/openai/v1` prefix, an empty path —
+ // routes through v1.
+ if (/\/openai\/deployments\//.test(u.pathname)) return "legacy";
+ return "v1";
+ } catch {
+ return "v1";
+ }
+}
+
+// Legacy Azure: append the route to the existing deployment path,
+// set api-version via searchParams. URL-API composition keeps any
+// pre-existing query params on the base URL intact.
+function legacyAzureUrl(
+ baseUrl: string,
+ path: string,
+ apiVersion: string,
+): string {
+ const url = new URL(baseUrl);
+ const existing = url.pathname.replace(/\/+$/, "");
+ const route = path.startsWith("/") ? path : `/${path}`;
+ url.pathname = `${existing}${route}`;
+ url.searchParams.set("api-version", apiVersion);
+ return url.toString();
+}
+
+// v1 Azure: route through `/openai/v1/<path>`. Preserve any existing
+// query params on the base URL (corporate proxy, diagnostics tokens)
+// but never append api-version — v1 doesn't accept it.
+function v1AzureUrl(baseUrl: string, path: string): string {
+ const url = new URL(baseUrl);
+ const route = path.startsWith("/") ? path.slice(1) : path;
+ // Strip any trailing `/openai`, `/openai/`, or `/openai/v1` so a
+ // user who configures OPENAI_BASE_URL with a partial prefix still
+ // gets a single, correct path.
+ const base = url.pathname.replace(/\/?openai(?:\/v1)?\/?$/, "");
+ url.pathname = `${base.replace(/\/+$/, "")}/openai/v1/${route}`;
+ return url.toString();
+}
+
+export function buildChatUrl(
+ baseUrl: string,
+ isAzure: boolean,
+ azureApiVersion: string,
+): string {
+ if (isAzure) {
+ return azureStyleOf(baseUrl) === "legacy"
+ ? legacyAzureUrl(baseUrl, "/chat/completions", azureApiVersion)
+ : v1AzureUrl(baseUrl, "/chat/completions");
+ }
+ return `${baseUrl}/v1/chat/completions`;
+}
+
+export function buildEmbeddingUrl(
+ baseUrl: string,
+ isAzure: boolean,
+ azureApiVersion: string,
+): string {
+ if (isAzure) {
+ return azureStyleOf(baseUrl) === "legacy"
+ ? legacyAzureUrl(baseUrl, "/embeddings", azureApiVersion)
+ : v1AzureUrl(baseUrl, "/embeddings");
+ }
+ return `${baseUrl}/v1/embeddings`;
+}
+
+// Azure key-auth uses `api-key: <KEY>`; standard OpenAI-compatible
+// endpoints use `Authorization: Bearer <KEY>`. Azure also accepts
+// Bearer when AAD-auth is configured upstream, but the api-key path
+// is the default and what our config block documents.
+export function buildAuthHeaders(
+ apiKey: string,
+ isAzure: boolean,
+): Record<string, string> {
+ if (isAzure) {
+ return {
+ "Content-Type": "application/json",
+ "api-key": apiKey,
+ };
+ }
+ return {
+ "Content-Type": "application/json",
+ Authorization: `Bearer ${apiKey}`,
+ };
+}
+
+export function normalizeBaseUrl(raw: string | undefined): string {
+ return (raw || DEFAULT_OPENAI_BASE_URL).replace(/\/+$/, "");
+}
diff --git a/src/providers/embedding/openai.ts b/src/providers/embedding/openai.ts
index bbc0f9f5..ea5a0efa 100644
--- a/src/providers/embedding/openai.ts
+++ b/src/providers/embedding/openai.ts
@@ -1,8 +1,14 @@
import type { EmbeddingProvider } from "../../types.js";
import { getEnvVar } from "../../config.js";
import { fetchWithTimeout } from "../_fetch.js";
+import {
+ DEFAULT_AZURE_API_VERSION,
+ buildAuthHeaders,
+ buildEmbeddingUrl,
+ detectAzure,
+ normalizeBaseUrl,
+} from "../_openai-shared.js";
-const DEFAULT_BASE_URL = "https://api.openai.com";
const DEFAULT_MODEL = "text-embedding-3-small";
/**
@@ -34,11 +40,20 @@ function resolveDimensions(model: string, override: string | undefined): number
/**
* OpenAI-compatible embedding provider.
*
+ * Shares transport (URL builder, auth header, Azure detection) with
+ * the OpenAI LLM provider via `_openai-shared` (#371). Same env knobs
+ * pick up automatically: when `OPENAI_BASE_URL` points at an Azure
+ * resource (`.openai.azure.com` hostname) the embedding request uses
+ * Azure's `/embeddings` path with the `api-version` query param and
+ * `api-key` header instead of `Authorization: Bearer`.
+ *
* Required env vars:
* OPENAI_API_KEY — API key
*
* Optional:
- * OPENAI_BASE_URL — base URL without path (default: https://api.openai.com)
+ * OPENAI_BASE_URL — base URL without path (default: https://api.openai.com).
+ * Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+ * OPENAI_API_VERSION — Azure api-version query param (default: 2024-08-01-preview)
* OPENAI_EMBEDDING_MODEL — model name (default: text-embedding-3-small)
* OPENAI_EMBEDDING_DIMENSIONS — override reported dimensions (required for
* custom / self-hosted models not in the
@@ -50,18 +65,21 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
private apiKey: string;
private baseUrl: string;
private model: string;
+ private isAzure: boolean;
+ private azureApiVersion: string;
constructor(apiKey?: string) {
this.apiKey = apiKey || getEnvVar("OPENAI_API_KEY") || "";
if (!this.apiKey) throw new Error("OPENAI_API_KEY is required");
- this.baseUrl =
- getEnvVar("OPENAI_BASE_URL") || DEFAULT_BASE_URL;
- this.model =
- getEnvVar("OPENAI_EMBEDDING_MODEL") || DEFAULT_MODEL;
+ this.baseUrl = normalizeBaseUrl(getEnvVar("OPENAI_BASE_URL"));
+ this.model = getEnvVar("OPENAI_EMBEDDING_MODEL") || DEFAULT_MODEL;
this.dimensions = resolveDimensions(
this.model,
getEnvVar("OPENAI_EMBEDDING_DIMENSIONS"),
);
+ this.isAzure = detectAzure(this.baseUrl);
+ this.azureApiVersion =
+ getEnvVar("OPENAI_API_VERSION") || DEFAULT_AZURE_API_VERSION;
}
async embed(text: string): Promise<Float32Array> {
@@ -70,13 +88,14 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
}
async embedBatch(texts: string[]): Promise<Float32Array[]> {
- const url = `${this.baseUrl}/v1/embeddings`;
+ const url = buildEmbeddingUrl(
+ this.baseUrl,
+ this.isAzure,
+ this.azureApiVersion,
+ );
const response = await fetchWithTimeout(url, {
method: "POST",
- headers: {
- Authorization: `Bearer ${this.apiKey}`,
- "Content-Type": "application/json",
- },
+ headers: buildAuthHeaders(this.apiKey, this.isAzure),
body: JSON.stringify({
model: this.model,
input: texts,
diff --git a/src/providers/openai.ts b/src/providers/openai.ts
index 2bb92781..bca2370f 100644
--- a/src/providers/openai.ts
+++ b/src/providers/openai.ts
@@ -1,11 +1,16 @@
import type { MemoryProvider } from "../types.js";
import { getEnvVar } from "../config.js";
import { fetchWithTimeout } from "./_fetch.js";
+import {
+ DEFAULT_AZURE_API_VERSION,
+ buildAuthHeaders,
+ buildChatUrl,
+ detectAzure,
+ normalizeBaseUrl,
+} from "./_openai-shared.js";
-const DEFAULT_BASE_URL = "https://api.openai.com";
const DEFAULT_MODEL = "gpt-4o-mini";
const DEFAULT_TIMEOUT_MS = 60_000;
-const DEFAULT_AZURE_API_VERSION = "2024-08-01-preview";
/**
* OpenAI-compatible LLM provider.
@@ -54,11 +59,7 @@ export class OpenAIProvider implements MemoryProvider {
this.apiKey = apiKey;
this.model = model;
this.maxTokens = maxTokens;
- this.baseUrl = (
- baseURL ||
- getEnvVar("OPENAI_BASE_URL") ||
- DEFAULT_BASE_URL
- ).replace(/\/+$/, "");
+ this.baseUrl = normalizeBaseUrl(baseURL || getEnvVar("OPENAI_BASE_URL"));
this.reasoningEffort = getEnvVar("OPENAI_REASONING_EFFORT") || undefined;
this.timeoutMs = resolveTimeout();
this.azureApiVersion =
@@ -74,33 +75,8 @@ export class OpenAIProvider implements MemoryProvider {
return this.call(systemPrompt, userPrompt);
}
- private buildUrl(): string {
- // Azure OpenAI carries the deployment in the path and requires
- // `api-version` as a query param. Standard OpenAI-compatible
- // endpoints append /v1/chat/completions to the base.
- if (this.isAzure) {
- const sep = this.baseUrl.includes("?") ? "&" : "?";
- return `${this.baseUrl}/chat/completions${sep}api-version=${encodeURIComponent(this.azureApiVersion)}`;
- }
- return `${this.baseUrl}/v1/chat/completions`;
- }
-
- private buildHeaders(): Record<string, string> {
- // Azure uses `api-key: <KEY>`; everyone else uses `Authorization: Bearer <KEY>`.
- if (this.isAzure) {
- return {
- "Content-Type": "application/json",
- "api-key": this.apiKey,
- };
- }
- return {
- "Content-Type": "application/json",
- Authorization: `Bearer ${this.apiKey}`,
- };
- }
-
private async call(systemPrompt: string, userPrompt: string): Promise<string> {
- const url = this.buildUrl();
+ const url = buildChatUrl(this.baseUrl, this.isAzure, this.azureApiVersion);
const body: Record<string, unknown> = {
model: this.model,
max_tokens: this.maxTokens,
@@ -125,7 +101,7 @@ export class OpenAIProvider implements MemoryProvider {
url,
{
method: "POST",
- headers: this.buildHeaders(),
+ headers: buildAuthHeaders(this.apiKey, this.isAzure),
body: JSON.stringify(body),
},
this.timeoutMs,
@@ -193,14 +169,3 @@ function parsePositiveInt(raw: string | null | undefined): number | undefined {
return Number.isFinite(n) && n > 0 ? n : undefined;
}
-function detectAzure(baseUrl: string): boolean {
- // Azure resource URLs land at <resource>.openai.azure.com. The
- // `OPENAI_BASE_URL=https://<r>.openai.azure.com/openai/deployments/<d>`
- // shape is the documented opt-in path.
- try {
- const u = new URL(baseUrl);
- return u.hostname.endsWith(".openai.azure.com");
- } catch {
- return false;
- }
-}
diff --git a/test/openai-shared.test.ts b/test/openai-shared.test.ts
new file mode 100644
index 00000000..7240e10c
--- /dev/null
+++ b/test/openai-shared.test.ts
@@ -0,0 +1,261 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+ buildAuthHeaders,
+ buildChatUrl,
+ buildEmbeddingUrl,
+ detectAzure,
+ normalizeBaseUrl,
+} from "../src/providers/_openai-shared.js";
+import { OpenAIEmbeddingProvider } from "../src/providers/embedding/openai.js";
+
+describe("_openai-shared — detectAzure", () => {
+ it("detects standard Azure resource hostname", () => {
+ expect(
+ detectAzure(
+ "https://myresource.openai.azure.com/openai/deployments/mydeploy",
+ ),
+ ).toBe(true);
+ });
+
+ it("does not flag api.openai.com", () => {
+ expect(detectAzure("https://api.openai.com")).toBe(false);
+ });
+
+ it("does not flag DeepSeek / SiliconFlow / Ollama / vLLM", () => {
+ expect(detectAzure("https://api.deepseek.com/v1")).toBe(false);
+ expect(detectAzure("https://api.siliconflow.cn")).toBe(false);
+ expect(detectAzure("http://localhost:11434/v1")).toBe(false);
+ expect(detectAzure("http://localhost:8000/v1")).toBe(false);
+ });
+
+ it("returns false for malformed URLs", () => {
+ expect(detectAzure("not-a-url")).toBe(false);
+ expect(detectAzure("")).toBe(false);
+ });
+});
+
+describe("_openai-shared — buildChatUrl", () => {
+ it("appends /v1/chat/completions for standard OpenAI", () => {
+ expect(buildChatUrl("https://api.openai.com", false, "2024-08-01-preview")).toBe(
+ "https://api.openai.com/v1/chat/completions",
+ );
+ });
+
+ it("appends /chat/completions + api-version for Azure", () => {
+ const url = buildChatUrl(
+ "https://myresource.openai.azure.com/openai/deployments/mydeploy",
+ true,
+ "2024-08-01-preview",
+ );
+ expect(url).toBe(
+ "https://myresource.openai.azure.com/openai/deployments/mydeploy/chat/completions?api-version=2024-08-01-preview",
+ );
+ });
+
+ it("URL-encodes the api-version", () => {
+ const url = buildChatUrl(
+ "https://r.openai.azure.com/openai/deployments/d",
+ true,
+ "preview/with/slashes",
+ );
+ expect(url).toContain("api-version=preview%2Fwith%2Fslashes");
+ });
+
+ it("preserves pre-existing query params on the base URL (CodeRabbit catch)", () => {
+ // A corporate proxy or diagnostics endpoint might already carry
+ // query parameters on the base URL. String-concat would have
+ // interpolated the route path into the query string; URL-API
+ // composition keeps the query intact and adds api-version
+ // alongside.
+ const url = buildChatUrl(
+ "https://proxy.example.com/openai/deployments/d?tenant=acme",
+ true,
+ "2024-08-01-preview",
+ );
+ const parsed = new URL(url);
+ expect(parsed.pathname).toBe("/openai/deployments/d/chat/completions");
+ expect(parsed.searchParams.get("tenant")).toBe("acme");
+ expect(parsed.searchParams.get("api-version")).toBe("2024-08-01-preview");
+ });
+
+ it("strips trailing slashes from base path before joining route", () => {
+ const url = buildChatUrl(
+ "https://r.openai.azure.com/openai/deployments/d/",
+ true,
+ "2024-08-01-preview",
+ );
+ expect(new URL(url).pathname).toBe("/openai/deployments/d/chat/completions");
+ });
+
+ it("routes through /openai/v1 when the base URL has no /deployments/ segment (Azure v1 GA)", () => {
+ // Azure shipped a v1 URL pattern that mirrors the OpenAI shape:
+ // /openai/v1/chat/completions, deployment passed in the body as
+ // `model`. No api-version query param.
+ const url = buildChatUrl(
+ "https://r.openai.azure.com",
+ true,
+ "2024-08-01-preview", // ignored on v1
+ );
+ const parsed = new URL(url);
+ expect(parsed.pathname).toBe("/openai/v1/chat/completions");
+ expect(parsed.searchParams.get("api-version")).toBeNull();
+ });
+
+ it("strips a trailing /openai or /openai/v1 prefix when composing v1 URLs", () => {
+ // Users may pre-configure OPENAI_BASE_URL with the /openai/v1
+ // suffix already present. We should not double it.
+ const fromOpenai = buildChatUrl(
+ "https://r.openai.azure.com/openai",
+ true,
+ "ignored",
+ );
+ expect(new URL(fromOpenai).pathname).toBe("/openai/v1/chat/completions");
+
+ const fromV1 = buildChatUrl(
+ "https://r.openai.azure.com/openai/v1",
+ true,
+ "ignored",
+ );
+ expect(new URL(fromV1).pathname).toBe("/openai/v1/chat/completions");
+ });
+});
+
+describe("_openai-shared — buildEmbeddingUrl", () => {
+ it("appends /v1/embeddings for standard OpenAI", () => {
+ expect(
+ buildEmbeddingUrl("https://api.openai.com", false, "2024-08-01-preview"),
+ ).toBe("https://api.openai.com/v1/embeddings");
+ });
+
+ it("appends /embeddings + api-version for Azure legacy (no /v1/ prefix)", () => {
+ const url = buildEmbeddingUrl(
+ "https://r.openai.azure.com/openai/deployments/embed-deploy",
+ true,
+ "2024-08-01-preview",
+ );
+ expect(url).toBe(
+ "https://r.openai.azure.com/openai/deployments/embed-deploy/embeddings?api-version=2024-08-01-preview",
+ );
+ });
+
+ it("routes through /openai/v1/embeddings on Azure v1 (no api-version)", () => {
+ const url = buildEmbeddingUrl(
+ "https://r.openai.azure.com",
+ true,
+ "2024-08-01-preview", // ignored on v1
+ );
+ const parsed = new URL(url);
+ expect(parsed.pathname).toBe("/openai/v1/embeddings");
+ expect(parsed.searchParams.get("api-version")).toBeNull();
+ });
+});
+
+describe("_openai-shared — buildAuthHeaders", () => {
+ it("emits Authorization: Bearer for standard OpenAI", () => {
+ expect(buildAuthHeaders("sk-test", false)).toEqual({
+ "Content-Type": "application/json",
+ Authorization: "Bearer sk-test",
+ });
+ });
+
+ it("emits api-key header for Azure", () => {
+ expect(buildAuthHeaders("azure-key", true)).toEqual({
+ "Content-Type": "application/json",
+ "api-key": "azure-key",
+ });
+ });
+});
+
+describe("_openai-shared — normalizeBaseUrl", () => {
+ it("returns default when no value passed", () => {
+ expect(normalizeBaseUrl(undefined)).toBe("https://api.openai.com");
+ expect(normalizeBaseUrl("")).toBe("https://api.openai.com");
+ });
+
+ it("strips trailing slashes", () => {
+ expect(normalizeBaseUrl("https://api.deepseek.com/v1///")).toBe(
+ "https://api.deepseek.com/v1",
+ );
+ });
+
+ it("returns explicit values unchanged otherwise", () => {
+ expect(normalizeBaseUrl("https://api.deepseek.com/v1")).toBe(
+ "https://api.deepseek.com/v1",
+ );
+ });
+});
+
+// ─────────────────────────────────────────────────────────────
+// OpenAIEmbeddingProvider — Azure transport (#371)
+// Verifies the embedding path now uses the shared Azure helpers:
+// hits /embeddings (not /v1/embeddings), includes api-version, uses
+// api-key header instead of Authorization: Bearer.
+// ─────────────────────────────────────────────────────────────
+describe("OpenAIEmbeddingProvider — Azure auto-detection (#371)", () => {
+ const ORIGINAL_BASE = process.env["OPENAI_BASE_URL"];
+ const ORIGINAL_VERSION = process.env["OPENAI_API_VERSION"];
+
+ beforeEach(() => {
+ vi.restoreAllMocks();
+ });
+
+ afterEach(() => {
+ if (ORIGINAL_BASE === undefined) delete process.env["OPENAI_BASE_URL"];
+ else process.env["OPENAI_BASE_URL"] = ORIGINAL_BASE;
+ if (ORIGINAL_VERSION === undefined) delete process.env["OPENAI_API_VERSION"];
+ else process.env["OPENAI_API_VERSION"] = ORIGINAL_VERSION;
+ vi.restoreAllMocks();
+ });
+
+ it("uses Azure shape when OPENAI_BASE_URL points at *.openai.azure.com", async () => {
+ process.env["OPENAI_BASE_URL"] =
+ "https://myres.openai.azure.com/openai/deployments/embed-d";
+ process.env["OPENAI_API_VERSION"] = "2024-08-01-preview";
+
+ let capturedUrl = "";
+ let capturedHeaders = new Headers();
+ vi.spyOn(globalThis, "fetch").mockImplementation(
+ async (url: string | URL | Request, init?: RequestInit) => {
+ capturedUrl = String(url);
+ capturedHeaders = new Headers(init?.headers);
+ return new Response(
+ JSON.stringify({ data: [{ embedding: [0.1, 0.2, 0.3] }] }),
+ { status: 200 },
+ );
+ },
+ );
+
+ const provider = new OpenAIEmbeddingProvider("azure-key");
+ await provider.embedBatch(["hello"]);
+
+ expect(capturedUrl).toBe(
+ "https://myres.openai.azure.com/openai/deployments/embed-d/embeddings?api-version=2024-08-01-preview",
+ );
+ expect(capturedHeaders.get("api-key")).toBe("azure-key");
+ expect(capturedHeaders.get("Authorization")).toBeNull();
+ });
+
+ it("uses standard shape when OPENAI_BASE_URL points at api.openai.com", async () => {
+ process.env["OPENAI_BASE_URL"] = "https://api.openai.com";
+
+ let capturedUrl = "";
+ let capturedHeaders = new Headers();
+ vi.spyOn(globalThis, "fetch").mockImplementation(
+ async (url: string | URL | Request, init?: RequestInit) => {
+ capturedUrl = String(url);
+ capturedHeaders = new Headers(init?.headers);
+ return new Response(
+ JSON.stringify({ data: [{ embedding: [0.4, 0.5, 0.6] }] }),
+ { status: 200 },
+ );
+ },
+ );
+
+ const provider = new OpenAIEmbeddingProvider("sk-test");
+ await provider.embedBatch(["hello"]);
+
+ expect(capturedUrl).toBe("https://api.openai.com/v1/embeddings");
+ expect(capturedHeaders.get("Authorization")).toBe("Bearer sk-test");
+ expect(capturedHeaders.get("api-key")).toBeNull();
+ });
+});