@kindgi/adapter-model-openai-compat 0.1.4-rc.5 → 0.1.5-rc.0

package/README.md

@@ -1,16 +1,35 @@
 # `@kindgi/adapter-model-openai-compat`
 
-OpenAI-compatible `ModelProvider` for [`@kindgi/capabilities`](../../capabilities/). Wraps the official `openai` SDK client behind the framework's provider-neutral interface and works against any endpoint that speaks the Chat Completions wire format — OpenAI, Ollama, vLLM, llama-server, LM Studio, OpenRouter, Groq, Together, Fireworks, DeepInfra, or a LiteLLM proxy. One adapter, many backends: `baseURL` selects the endpoint.
+OpenAI-compatible `ModelProvider` for [`@kindgi/capabilities`](../../capabilities/). Wraps the official `openai` SDK client behind the framework's provider-neutral interface and works against OpenAI's own API and any endpoint that speaks the Chat Completions wire format — Ollama, vLLM, llama-server, LM Studio, OpenRouter, Groq, Together, Fireworks, DeepInfra, or a LiteLLM proxy. One adapter, many backends: `baseURL` selects the endpoint, and `api` the OpenAI API it speaks.
 
 ## Purpose
 
-Translate between the framework's `ModelCallInput` / `ModelCallResult` and a non-streaming `chat.completions.create` call:
+Translate between the framework's `ModelCallInput` / `ModelCallResult` and one non-streaming call, on one of two OpenAI APIs (`api`):
+
+- **`'responses'`** — OpenAI's Responses API (`responses.create`), the default for a `baseURL` on `api.openai.com` (and its data-residency hosts, such as `eu.api.openai.com`). OpenAI's GPT-6 models call tools only through it.
+- **`'chat-completions'`** — Chat Completions (`chat.completions.create`), the default for every other `baseURL`: the format the OpenAI-compatible servers speak.
+
+### Chat Completions
 
 - Messages map role for role. Assistant `toolCalls` become `tool_calls` with JSON-encoded arguments; `tool` messages carry `tool_call_id`.
 - `tools` become `function` tools; `structuredOutput` becomes `response_format: { type: 'json_schema', json_schema: { name, schema, strict: true } }`; `temperature` and `maxOutputTokens` (as `max_tokens`) are sent only when set.
 - Chat Completions endpoints reject `.` in function names, so tool names are encoded `.` → `__` on send and decoded on receive (`acme.orders.lookup` ↔ `acme__orders__lookup`). Tool ids must not contain a literal `__`. Tool-call arguments that are not valid JSON decode to `{}`.
 - `finish_reason` maps `tool_calls` / `function_call` → `tool-use`, `content_filter` → `content-filter`, `length` → `length`, anything else → `stop`.
-- `costUsd` is computed from the matching `ModelInfo.cost`: prompt and completion tokens, each per 1K tokens. The wire format carries no pricing, so rates come from the caller.
+- `costUsd` is computed from the matching `ModelInfo.cost` (`computeCost`), on both APIs. The wire format carries no pricing, so rates come from the caller (`OpenAICompatCostRates`, the names the Gemini and Anthropic adapters price with):
+  - prompt and completion tokens per 1K tokens (`promptUsdPer1kTokens`, `completionUsdPer1kTokens`);
+  - cached prompt tokens at `cachedPromptMultiplier` of the prompt rate, and cache-write tokens at `promptCacheCreationMultiplier` (each absent: the prompt rate);
+  - `longContext: { thresholdTokens, promptUsdPer1kTokens, completionUsdPer1kTokens }`: past the threshold (cached and cache-write prompt tokens included), the whole call bills at those rates, the cache multipliers applying to the long prompt rate;
+  - `dataResidencyMultiplier`: an uplift on the whole call, only when `baseURL` is a data-residency host (`eu.api.openai.com`; `isDataResidencyHost`).
+  A rate that isn't a finite, non-negative number is ignored. The `openai` preset carries OpenAI's GPT-6 rates. Its `longContext` applies per call, counting all of the call's input tokens (cached and cache-write ones included) past 272,000: that's how we read OpenAI's pricing page, which doesn't spell it out. These costs are estimates from published prices; the provider's invoice is authoritative.
+
+### Responses
+
+- **Stateless:** every call sends the whole conversation with `store: false`, so OpenAI keeps no conversation state for it (no `previous_response_id`).
+- **Input items:** `system` messages go as `developer` messages, `user` and `assistant` as messages, assistant `toolCalls` as `function_call` items, and `tool` messages as `function_call_output` items.
+- **Tools and typed output:** `tools` become flat `function` tools (`strict: false`, the same `.` → `__` name encoding); `structuredOutput` becomes `text.format: { type: 'json_schema', name, schema, strict: true }`; `temperature` and `maxOutputTokens` (as `max_output_tokens`) are sent only when set.
+- **The answer:** its `output_text` (its refusal when it has no text) and its `function_call` items. `incomplete` maps `max_output_tokens` → `length` and `content_filter` → `content-filter`; a `failed` response throws, naming OpenAI's error code and message.
+- **Reasoning between tool calls:** a reasoning model's reasoning items (encrypted by OpenAI), with the item ids and `phase` that tie them to the message and calls after them, are carried in the first tool call's `ModelToolCall.signature` (opaque, versioned `oair1.`). When the conversation continues with the same model, they go back in their original order; for any other model, or a signature that isn't this adapter's, the turn goes back without them. A final answer's `phase` isn't carried (`ModelMessage` has no signature).
+- **Usage:** `input_tokens` / `output_tokens`, with the cached, cache-write and reasoning parts reported apart when given.
 
 ## Exports
 
@@ -19,9 +38,11 @@ Translate between the framework's `ModelCallInput` / `ModelCallResult` and a non
   - `baseURL: string` — endpoint root, e.g. `BASE_URLS.OLLAMA_LOCAL`.
   - `apiKey: string | (() => string | Promise<string>)` — a static key, or a resolver called on every `invoke()`: a rotated key takes effect on the next call. Local runners that ignore keys still need a non-empty string such as `'unused'`.
   - `metadata: ProviderMetadata` — surfaced to the router. `models[]` must list every model invoked through this connection, with its per-1K-token cost.
+  - `api?: 'responses' | 'chat-completions'` (`OPENAI_COMPAT_APIS`) — the OpenAI API to speak. Absent: `defaultOpenAICompatApi(baseURL)`, `'responses'` for `api.openai.com` and its subdomains, `'chat-completions'` for any other. Another value is refused at construction.
   - `clientOptions?` — other `openai` client options (`timeout`, `maxRetries`, `defaultHeaders`, `fetch`, …); `apiKey` and `baseURL` are excluded.
-  - `extraBody?` — fields merged into every request body: settings an endpoint takes that the OpenAI format has no field for. A Qwen thinking model served by vLLM, SGLang or llama-server needs `{ chat_template_kwargs: { enable_thinking: false } }`, or its answer starts with its thinking and a typed (JSON) answer fails. The fields the adapter sets (`EXTRA_BODY_RESERVED`: `model`, `messages`, `tools`, `response_format`, `temperature`, `max_tokens`, `stream`) are refused.
-- **`openAICompatAdapterFactory`** (`OPENAI_COMPAT_ADAPTER_ID`) — the `AdapterFactory` a runtime registers. A provider registration names its endpoint in `adapter_config.baseURL` (an http(s) URL; `openAICompatBaseUrl` reads and checks it), any extra request fields as `extraBody.*` keys (`adapter_config` is flat, so one key per field and dots nest: `"extraBody.chat_template_kwargs.enable_thinking": false`; `openAICompatExtraBody` expands and checks them), and, for an endpoint that needs a key, its secret in `secret_ref`; without one the adapter sends `'unused'`, as local runners expect.
+  - `extraBody?` — fields merged into every request body: settings an endpoint takes that the OpenAI format has no field for. A Qwen thinking model served by vLLM, SGLang or llama-server needs `{ chat_template_kwargs: { enable_thinking: false } }`, or its answer starts with its thinking and a typed (JSON) answer fails. The fields the adapter sets are refused: on Chat Completions `EXTRA_BODY_RESERVED` (`model`, `messages`, `tools`, `response_format`, `temperature`, `max_tokens`, `stream`), on Responses `EXTRA_BODY_RESERVED_RESPONSES` (`model`, `input`, `tools`, `text`, `temperature`, `max_output_tokens`, `stream`, `store`). On Responses, `{ reasoning: { effort: 'low' } }` sets a reasoning model's effort.
+- **`openAICompatAdapterFactory`** (`OPENAI_COMPAT_ADAPTER_ID`) — the `AdapterFactory` a runtime registers. A provider registration names its endpoint in `adapter_config.baseURL` (an http(s) URL; `openAICompatBaseUrl` reads and checks it), the OpenAI API in `adapter_config.api` (`openAICompatApi` reads and checks it, with the base URL's default when absent), any extra request fields as `extraBody.*` keys (`adapter_config` is flat, so one key per field and dots nest: `"extraBody.chat_template_kwargs.enable_thinking": false`; `openAICompatExtraBody` expands and checks them), and, for an endpoint that needs a key, its secret in `secret_ref`; without one the adapter sends `'unused'`, as local runners expect.
+- **`openAICompatAdapterEntry`** — the `AdapterFactoryEntry` a runtime registers: `openAICompatAdapterFactory` plus **`openAICompatCheckConfig(input)`**, which reports every problem the factory would throw on (`adapter_config.baseURL`, `adapter_config.api`, each `adapter_config.extraBody.*` key), with the factory's own messages, without building anything.
 - **`BASE_URLS`** — well-known endpoints: `OPENAI`, `OLLAMA_LOCAL`, `VLLM_LOCAL`, `LLAMA_SERVER_LOCAL`, `LM_STUDIO_LOCAL`, `OPENROUTER`, `GROQ`, `TOGETHER`, `FIREWORKS`, `DEEPINFRA`, `LITELLM_LOCAL`. Any other URL works too.
 - **`ModelProvider`** — type re-export from `@kindgi/capabilities`.
 
@@ -78,8 +99,8 @@ A local runner uses the same factory: `baseURL: BASE_URLS.OLLAMA_LOCAL`, `apiKey
 ## Non-goals
 
 - **Streaming.** Requests are sent with `stream: false`; `invoke()` resolves with the complete response.
+- **Server-side conversation state** (Responses `previous_response_id`, `store: true`). Every call carries its whole conversation.
 - **Pricing discovery.** Cost rates are caller-supplied per model.
-- **Cached-token accounting.** `usage` reports prompt and completion tokens only; all prompt tokens are billed at `promptUsdPer1kTokens`.
 
 ## Related
 

package/dist/embedding.d.ts

@@ -0,0 +1,37 @@
+import OpenAI from 'openai';
+import type { EmbeddingProvider } from '@kindgi/embedding';
+/**
+ * An embeddings endpoint that speaks OpenAI's `POST /embeddings`: OpenAI
+ * itself, Ollama (`nomic-embed-text`), vLLM, Hugging Face TEI, LM Studio,
+ * llama-server, a LiteLLM proxy. Same `baseURL` as for chat
+ * (`BASE_URLS`), with the `/v1` suffix.
+ */
+export interface OpenAICompatEmbeddingOptions {
+    readonly baseURL: string;
+    /** The embedding model the endpoint serves (`text-embedding-3-small`, `nomic-embed-text`, …). */
+    readonly model: string;
+    /**
+     * The key, or a resolver called before each request (a rotated key
+     * takes effect on the next one). Absent: the endpoint takes none
+     * (Ollama, a local TEI); the SDK sends a placeholder.
+     */
+    readonly apiKey?: string | (() => string | Promise<string>);
+    /** The vector length, when known; otherwise learned by `probe()` or the first `embed()`. */
+    readonly dimensions?: number;
+    /** HTTP overrides passed through to the OpenAI SDK (`fetch`, `timeout`, `maxRetries`, …). */
+    readonly clientOptions?: Omit<NonNullable<ConstructorParameters<typeof OpenAI>[0]>, 'apiKey' | 'baseURL'>;
+}
+export interface OpenAICompatEmbeddingProvider extends EmbeddingProvider {
+    /**
+     * Embed a short text once: checks the endpoint answers with this model,
+     * and learns the dimensions. Call it at boot, before `dimensions()`.
+     */
+    probe(): Promise<number>;
+}
+/**
+ * Create an `EmbeddingProvider` over an OpenAI-compatible embeddings
+ * endpoint. The SDK client is built on first use (and rebuilt when the
+ * key rotates), so construction has no side effects.
+ */
+export declare function createOpenAICompatEmbeddingProvider(options: OpenAICompatEmbeddingOptions): OpenAICompatEmbeddingProvider;
+//# sourceMappingURL=embedding.d.ts.map

package/dist/embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../src/embedding.ts"],"names":[],"mappings":"AAGA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,4FAA4F;IAC5F,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAC3B,WAAW,CAAC,qBAAqB,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EACpD,QAAQ,GAAG,SAAS,CACrB,CAAC;CACH;AAED,MAAM,WAAW,6BAA8B,SAAQ,iBAAiB;IACtE;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAKD;;;;GAIG;AACH,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,4BAA4B,GACpC,6BAA6B,CAuD/B"}

package/dist/embedding.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import OpenAI from 'openai';
+import { OPENAI_COMPAT_ADAPTER_ID } from './provider.js';
+/** The SDK needs a non-empty key; endpoints that take none ignore it. */
+const NO_KEY = 'unused';
+/**
+ * Create an `EmbeddingProvider` over an OpenAI-compatible embeddings
+ * endpoint. The SDK client is built on first use (and rebuilt when the
+ * key rotates), so construction has no side effects.
+ */
+export function createOpenAICompatEmbeddingProvider(options) {
+    let dims = options.dimensions;
+    let cached;
+    async function client() {
+        const resolved = typeof options.apiKey === 'function' ? await options.apiKey() : options.apiKey;
+        const key = resolved === undefined || resolved === '' ? NO_KEY : resolved;
+        if (cached !== undefined && cached.key === key)
+            return cached.client;
+        const fresh = new OpenAI({
+            apiKey: key,
+            baseURL: options.baseURL,
+            ...(options.clientOptions ?? {}),
+        });
+        cached = { key, client: fresh };
+        return fresh;
+    }
+    async function embed(text) {
+        const response = await (await client()).embeddings.create({
+            model: options.model,
+            input: text,
+            encoding_format: 'float',
+        });
+        const values = response.data[0]?.embedding;
+        if (!Array.isArray(values) || values.length === 0) {
+            throw new Error(`${OPENAI_COMPAT_ADAPTER_ID}: the embeddings endpoint ${options.baseURL} returned no vector for model "${options.model}".`);
+        }
+        if (dims === undefined)
+            dims = values.length;
+        if (values.length !== dims) {
+            throw new Error(`${OPENAI_COMPAT_ADAPTER_ID}: model "${options.model}" returned a ${values.length}-dimension vector, expected ${dims}.`);
+        }
+        return Float32Array.from(values);
+    }
+    return {
+        embed,
+        async probe() {
+            return (await embed('dimension probe')).length;
+        },
+        dimensions() {
+            if (dims === undefined) {
+                throw new Error(`${OPENAI_COMPAT_ADAPTER_ID}: the dimensions of "${options.model}" aren't known yet; call probe() first.`);
+            }
+            return dims;
+        },
+        describe() {
+            return { name: OPENAI_COMPAT_ADAPTER_ID, version: '1', model: options.model };
+        },
+    };
+}
+//# sourceMappingURL=embedding.js.map

package/dist/embedding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.js","sourceRoot":"","sources":["../src/embedding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,MAAM,MAAM,QAAQ,CAAC;AAI5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAmCzD,yEAAyE;AACzE,MAAM,MAAM,GAAG,QAAQ,CAAC;AAExB;;;;GAIG;AACH,MAAM,UAAU,mCAAmC,CACjD,OAAqC;IAErC,IAAI,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC;IAC9B,IAAI,MAAqE,CAAC;IAE1E,KAAK,UAAU,MAAM;QACnB,MAAM,QAAQ,GAAG,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;QAChG,MAAM,GAAG,GAAG,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC1E,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,KAAK,GAAG;YAAE,OAAO,MAAM,CAAC,MAAM,CAAC;QACrE,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC;YACvB,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,GAAG,CAAC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;SACjC,CAAC,CAAC;QACH,MAAM,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,UAAU,KAAK,CAAC,IAAY;QAC/B,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;YACxD,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,KAAK,EAAE,IAAI;YACX,eAAe,EAAE,OAAO;SACzB,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;QAC3C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CACb,GAAG,wBAAwB,6BAA6B,OAAO,CAAC,OAAO,kCAAkC,OAAO,CAAC,KAAK,IAAI,CAC3H,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,KAAK,SAAS;YAAE,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7C,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,GAAG,wBAAwB,YAAY,OAAO,CAAC,KAAK,gBAAgB,MAAM,CAAC,MAAM,+BAA+B,IAAI,GAAG,CACxH,CAAC;QACJ,CAAC;QACD,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,OAAO;QACL,KAAK;QACL,KAAK,CAAC,KAAK;YACT,OAAO,CAAC,MAAM,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC;QACjD,CAAC;QACD,UAAU;YACR,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CACb,GAAG,wBAAwB,wBAAwB,OAAO,CAAC,KAAK,yCAAyC,CAC1G,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,QAAQ;YACN,OAAO,EAAE,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAChF,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,9 @@
-export { BASE_URLS, EXTRA_BODY_PREFIX, EXTRA_BODY_RESERVED, OPENAI_COMPAT_ADAPTER_ID, createOpenAICompatModelProvider, openAICompatAdapterFactory, openAICompatBaseUrl, openAICompatExtraBody, } from './provider.js';
-export type { OpenAICompatProviderOptions } from './provider.js';
+export { BASE_URLS, EXTRA_BODY_PREFIX, EXTRA_BODY_RESERVED, OPENAI_COMPAT_ADAPTER_ID, OPENAI_COMPAT_APIS, createOpenAICompatModelProvider, openAICompatAdapterEntry, openAICompatCheckConfig, defaultOpenAICompatApi, isDataResidencyHost, openAICompatAdapterFactory, openAICompatApi, openAICompatBaseUrl, openAICompatExtraBody, } from './provider.js';
+export { EXTRA_BODY_RESERVED_RESPONSES } from './responses.js';
+export { computeCost } from './wire.js';
+export type { OpenAICompatCostRates, OpenAICompatModelInfo } from './wire.js';
+export type { OpenAICompatApi, OpenAICompatProviderOptions } from './provider.js';
+export { createOpenAICompatEmbeddingProvider } from './embedding.js';
+export type { OpenAICompatEmbeddingOptions, OpenAICompatEmbeddingProvider, } from './embedding.js';
 export type { ModelProvider } from '@kindgi/capabilities';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,+BAA+B,EAC/B,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AACjE,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,+BAA+B,EAC/B,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,EACnB,0BAA0B,EAC1B,eAAe,EACf,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC9E,YAAY,EAAE,eAAe,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,mCAAmC,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EACV,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,4 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
-export { BASE_URLS, EXTRA_BODY_PREFIX, EXTRA_BODY_RESERVED, OPENAI_COMPAT_ADAPTER_ID, createOpenAICompatModelProvider, openAICompatAdapterFactory, openAICompatBaseUrl, openAICompatExtraBody, } from './provider.js';
+export { BASE_URLS, EXTRA_BODY_PREFIX, EXTRA_BODY_RESERVED, OPENAI_COMPAT_ADAPTER_ID, OPENAI_COMPAT_APIS, createOpenAICompatModelProvider, openAICompatAdapterEntry, openAICompatCheckConfig, defaultOpenAICompatApi, isDataResidencyHost, openAICompatAdapterFactory, openAICompatApi, openAICompatBaseUrl, openAICompatExtraBody, } from './provider.js';
+export { EXTRA_BODY_RESERVED_RESPONSES } from './responses.js';
+export { computeCost } from './wire.js';
+export { createOpenAICompatEmbeddingProvider } from './embedding.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,+BAA+B,EAC/B,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,+BAA+B,EAC/B,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,EACnB,0BAA0B,EAC1B,eAAe,EACf,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGxC,OAAO,EAAE,mCAAmC,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/provider.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import type { AdapterFactory, AdapterFactoryInput, Feature, ModelProvider, ProviderMetadata } from '@kindgi/capabilities';
+import type { AdapterConfigCheckInput, AdapterConfigProblem, AdapterFactory, AdapterFactoryEntry, AdapterFactoryInput, Feature, ModelProvider, ProviderMetadata } from '@kindgi/capabilities';
 /**
  * Configuration for an OpenAI-compatible ModelProvider. `baseURL` is the
  * key — same adapter, different endpoints (the well-known ones are
@@ -37,16 +37,38 @@ export interface OpenAICompatProviderOptions {
     /** Optional HTTP overrides passed through to the OpenAI SDK. */
     readonly clientOptions?: Omit<NonNullable<ConstructorParameters<typeof OpenAI>[0]>, 'apiKey' | 'baseURL'>;
     /**
-     * Fields merged into every Chat Completions request body: settings an
-     * endpoint takes that the OpenAI format has no field for. A Qwen
-     * thinking model served by vLLM, SGLang or llama-server answers with its
-     * thinking first unless asked not to:
-     * `{ chat_template_kwargs: { enable_thinking: false } }`. The fields the
-     * adapter sets itself (`EXTRA_BODY_RESERVED`) are refused.
+     * Which OpenAI API the adapter speaks (`OPENAI_COMPAT_APIS`):
+     *   - `'responses'`: OpenAI's Responses API, the one OpenAI's GPT-6
+     *     models call tools through. Stateless: every call sends
+     *     `store: false`, so OpenAI keeps no conversation state.
+     *   - `'chat-completions'`: Chat Completions, the format the
+     *     OpenAI-compatible servers (Ollama, vLLM, Groq, OpenRouter, …) speak.
+     * Absent: `'responses'` for a `baseURL` on `api.openai.com` (or one of
+     * its data-residency hosts, `eu.api.openai.com`), `'chat-completions'`
+     * for any other (`defaultOpenAICompatApi`).
+     */
+    readonly api?: OpenAICompatApi;
+    /**
+     * Fields merged into every request body: settings an endpoint takes
+     * that the OpenAI format has no field for. A Qwen thinking model served
+     * by vLLM, SGLang or llama-server answers with its thinking first unless
+     * asked not to: `{ chat_template_kwargs: { enable_thinking: false } }`.
+     * The fields the adapter sets itself are refused: `EXTRA_BODY_RESERVED`
+     * on Chat Completions, `EXTRA_BODY_RESERVED_RESPONSES` on Responses.
      */
     readonly extraBody?: Readonly<Record<string, unknown>>;
 }
-/** Request fields the adapter sets itself; `extraBody` can't override them. */
+/** The OpenAI APIs the adapter speaks (`OpenAICompatProviderOptions.api`). */
+export declare const OPENAI_COMPAT_APIS: readonly ["responses", "chat-completions"];
+export type OpenAICompatApi = (typeof OPENAI_COMPAT_APIS)[number];
+/** The API a provider speaks when it doesn't say (`OpenAICompatProviderOptions.api`). */
+export declare function defaultOpenAICompatApi(baseURL: string): OpenAICompatApi;
+/**
+ * Whether a base URL is one of OpenAI's data-residency hosts
+ * (`eu.api.openai.com`), where a model's `dataResidencyMultiplier` applies.
+ */
+export declare function isDataResidencyHost(baseURL: string): boolean;
+/** Request fields the adapter sets itself on Chat Completions; `extraBody` can't override them. */
 export declare const EXTRA_BODY_RESERVED: readonly ["model", "messages", "tools", "response_format", "temperature", "max_tokens", "stream"];
 /**
  * Create an OpenAI-compatible `ModelProvider`. The OpenAI SDK is
@@ -83,10 +105,26 @@ export declare const OPENAI_COMPAT_ADAPTER_ID = "@kindgi/adapter-model-openai-co
  * a placeholder key, as local runners (Ollama, vLLM, llama-server)
  * expect. Its `extraBody.*` keys (`EXTRA_BODY_PREFIX`) are extra request
  * fields, merged into every request (`OpenAICompatProviderOptions.extraBody`).
+ * Its `adapter_config.api` picks the OpenAI API (`openAICompatApi`).
  */
 export declare const openAICompatAdapterFactory: AdapterFactory;
+/**
+ * What's wrong with a registration for this adapter, read without building
+ * it (`AdapterFactoryEntry.checkConfig`): its base URL, its API and its
+ * extra request fields. Each problem's message is the error the factory
+ * throws for it: both read the registration through the same functions.
+ */
+export declare function openAICompatCheckConfig(input: AdapterConfigCheckInput): readonly AdapterConfigProblem[];
+/** The entry a runtime registers: the factory, and its static check. */
+export declare const openAICompatAdapterEntry: AdapterFactoryEntry;
 /** The endpoint a registration names (see `openAICompatAdapterFactory`). */
 export declare function openAICompatBaseUrl(input: AdapterFactoryInput): string;
+/**
+ * The API a registration speaks: its `adapter_config.api` (`OPENAI_COMPAT_APIS`),
+ * or without one, the default for its base URL (`defaultOpenAICompatApi`).
+ * Throws, naming the key, on an API the adapter doesn't speak.
+ */
+export declare function openAICompatApi(input: AdapterFactoryInput): OpenAICompatApi;
 /**
  * The `adapter_config` key prefix for extra request fields. `adapter_config`
  * is flat, so each field is its own key and dots nest:

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAGA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,OAAO,EAKP,aAAa,EAGb,gBAAgB,EAEjB,MAAM,sBAAsB,CAAC;AAuB9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3D,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAC3B,WAAW,CAAC,qBAAqB,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EACpD,QAAQ,GAAG,SAAS,CACrB,CAAC;IACF;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxD;AAED,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,mGAQtB,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,2BAA2B,GACnC,aAAa,CAuGf;AAoFD;;;;GAIG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;CAYZ,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC;AAE/B,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,wCAAwC,CAAC;AAK9E;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,EAAE,cAWxC,CAAC;AAEF,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAQtE;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAK9C;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,GACzB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAoB/C"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAGA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACpB,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,OAAO,EAKP,aAAa,EAGb,gBAAgB,EAEjB,MAAM,sBAAsB,CAAC;AAQ9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3D,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAC3B,WAAW,CAAC,qBAAqB,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EACpD,QAAQ,GAAG,SAAS,CACrB,CAAC;IACF;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,eAAe,CAAC;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxD;AAED,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,4CAA6C,CAAC;AAC7E,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAGvE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE5D;AAaD,mGAAmG;AACnG,eAAO,MAAM,mBAAmB,mGAQtB,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,2BAA2B,GACnC,aAAa,CAkJf;AA8ED;;;;GAIG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;CAYZ,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC;AAE/B,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,wCAAwC,CAAC;AAK9E;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAE,cAYxC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,uBAAuB,GAC7B,SAAS,oBAAoB,EAAE,CAIjC;AAED,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,EAAE,mBAKtC,CAAC;AAWF,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAGtE;AAWD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,eAAe,CAG3E;AAmBD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAK9C;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,GACzB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAI/C"}

package/dist/provider.js

@@ -1,26 +1,38 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 import OpenAI from 'openai';
+import { adapterConfigError, samplingFor } from '@kindgi/capabilities';
 import { createAttemptCounter } from '@kindgi/capabilities/attempts';
+import { nameToolsAsSent } from '@kindgi/capabilities/tool-names';
+import { EXTRA_BODY_RESERVED_RESPONSES, invokeResponses, requestOptions } from './responses.js';
+import { computeCost, decodeToolName, encodeToolName } from './wire.js';
+/** The OpenAI APIs the adapter speaks (`OpenAICompatProviderOptions.api`). */
+export const OPENAI_COMPAT_APIS = ['responses', 'chat-completions'];
+/** The API a provider speaks when it doesn't say (`OpenAICompatProviderOptions.api`). */
+export function defaultOpenAICompatApi(baseURL) {
+    // OpenAI's own API, its data-residency hosts (`eu.api.openai.com`) included.
+    return openAIHostOf(baseURL) !== undefined ? 'responses' : 'chat-completions';
+}
 /**
- * OpenAI (and every downstream compat endpoint — Ollama, vLLM, Groq,
- * OpenRouter, Together, Fireworks, LiteLLM, ...) constrains
- * `function.name` to `^[a-zA-Z0-9_-]{1,128}$` — dots are rejected.
- * The framework's tool id convention is `<pack>.<tool>`, so this
- * adapter transparently encodes on send and decodes on receive.
- *
- * See the sibling comment in
- * `packages/adapters/model-anthropic/src/translate.ts` — same
- * substitution (`.` → `__`), same reversibility caveat (authors
- * should not put literal `__` in tool ids).
+ * Whether a base URL is one of OpenAI's data-residency hosts
+ * (`eu.api.openai.com`), where a model's `dataResidencyMultiplier` applies.
  */
-function encodeToolName(name) {
-    return name.replace(/\./g, '__');
+export function isDataResidencyHost(baseURL) {
+    return openAIHostOf(baseURL) === 'data-residency';
 }
-function decodeToolName(name) {
-    return name.replace(/__/g, '.');
+function openAIHostOf(baseURL) {
+    let host;
+    try {
+        host = new URL(baseURL).hostname;
+    }
+    catch {
+        return undefined;
+    }
+    if (host === 'api.openai.com')
+        return 'global';
+    return host.endsWith('.api.openai.com') ? 'data-residency' : undefined;
 }
-/** Request fields the adapter sets itself; `extraBody` can't override them. */
+/** Request fields the adapter sets itself on Chat Completions; `extraBody` can't override them. */
 export const EXTRA_BODY_RESERVED = [
     'model',
     'messages',
@@ -37,7 +49,13 @@ export const EXTRA_BODY_RESERVED = [
  */
 export function createOpenAICompatModelProvider(options) {
     const metadata = options.metadata;
-    const problem = extraBodyProblem(options.extraBody);
+    if (options.api !== undefined && !OPENAI_COMPAT_APIS.includes(options.api)) {
+        // A caller outside TypeScript can pass anything.
+        throw new Error(`${OPENAI_COMPAT_ADAPTER_ID}: provider "${metadata.id}": api must be one of ${OPENAI_COMPAT_APIS.join(', ')}`);
+    }
+    const api = options.api ?? defaultOpenAICompatApi(options.baseURL);
+    const dataResidency = isDataResidencyHost(options.baseURL);
+    const problem = extraBodyProblem(options.extraBody, api);
     if (problem !== undefined) {
         throw new Error(`${OPENAI_COMPAT_ADAPTER_ID}: provider "${metadata.id}": ${problem}`);
     }
@@ -72,7 +90,33 @@ export function createOpenAICompatModelProvider(options) {
             }
             const startedAt = Date.now();
             const openai = await clientForCall();
-            const messages = input.messages.map(toOpenAiMessage);
+            // The system prompt names the call's tools as they're sent (`acme__lookup_order`):
+            // a model told to call `acme.lookup_order` calls a name it wasn't given.
+            const toolIds = input.tools?.map((t) => t.name) ?? [];
+            const sent = input.messages.map((m) => m.role === 'system'
+                ? { ...m, content: nameToolsAsSent(m.content, toolIds, encodeToolName) }
+                : m);
+            const sampling = samplingFor(modelInfo, input);
+            // A caller that wants as little thinking as the model allows (a judge).
+            const lowestThinking = input.thinking === 'lowest' && modelInfo.thinking !== undefined
+                ? modelInfo.thinking.lowest
+                : undefined;
+            if (api === 'responses') {
+                return invokeResponses({
+                    client: openai,
+                    attempts,
+                    input: { ...input, messages: sent },
+                    modelInfo,
+                    providerId: metadata.id,
+                    extraBody,
+                    dataResidency,
+                    ...(sampling.temperature !== undefined && { temperature: sampling.temperature }),
+                    ...(lowestThinking !== undefined && { reasoningEffort: lowestThinking }),
+                    warnings: sampling.warnings,
+                    startedAt,
+                });
+            }
+            const messages = sent.map(toOpenAiMessage);
             const tools = input.tools?.map(toOpenAiTool);
             const responseFormat = input.structuredOutput
                 ? {
@@ -90,10 +134,13 @@ export function createOpenAICompatModelProvider(options) {
                 messages,
                 ...(tools !== undefined && tools.length > 0 && { tools }),
                 ...(responseFormat !== undefined && { response_format: responseFormat }),
-                ...(input.temperature !== undefined && { temperature: input.temperature }),
+                ...(sampling.temperature !== undefined && { temperature: sampling.temperature }),
+                ...(lowestThinking !== undefined && {
+                    reasoning_effort: lowestThinking,
+                }),
                 ...(input.maxOutputTokens !== undefined && { max_tokens: input.maxOutputTokens }),
                 stream: false,
-            }, input.abortSignal !== undefined ? { signal: input.abortSignal } : undefined));
+            }, requestOptions(input)));
             const completion = counted.value;
             const durationMs = Date.now() - startedAt;
             const choice = completion.choices[0];
@@ -109,7 +156,7 @@ export function createOpenAICompatModelProvider(options) {
                 message: responseMessage,
                 finishReason: mapFinishReason(choice?.finish_reason),
                 usage,
-                costUsd: computeCost(modelInfo, usage.promptTokens, usage.completionTokens),
+                costUsd: computeCost(modelInfo, usage, { dataResidency }),
                 durationMs,
                 provider: { id: metadata.id, model: input.model },
                 ...(completion.model !== undefined &&
@@ -122,6 +169,7 @@ export function createOpenAICompatModelProvider(options) {
                 // An injected client sends with its own fetch: nothing was counted.
                 ...(counted.attempts > 0 && { attempts: counted.attempts }),
                 ...(completion.usage !== undefined && { rawUsage: { ...completion.usage } }),
+                ...(sampling.warnings.length > 0 && { warnings: sampling.warnings }),
             };
         },
     };
@@ -201,11 +249,6 @@ function mapFinishReason(reason) {
             return 'stop';
     }
 }
-function computeCost(modelInfo, promptTokens, completionTokens) {
-    const promptCost = (promptTokens / 1000) * modelInfo.cost.promptUsdPer1kTokens;
-    const completionCost = (completionTokens / 1000) * modelInfo.cost.completionUsdPer1kTokens;
-    return promptCost + completionCost;
-}
 /**
  * Well-known base URLs — surfaced as constants so callers can import
  * without typos. Adding a new alias here doesn't lock anyone in; the
@@ -236,12 +279,14 @@ const NO_KEY = 'unused';
  * a placeholder key, as local runners (Ollama, vLLM, llama-server)
  * expect. Its `extraBody.*` keys (`EXTRA_BODY_PREFIX`) are extra request
  * fields, merged into every request (`OpenAICompatProviderOptions.extraBody`).
+ * Its `adapter_config.api` picks the OpenAI API (`openAICompatApi`).
  */
 export const openAICompatAdapterFactory = (input) => {
     const extraBody = openAICompatExtraBody(input);
     return createOpenAICompatModelProvider({
         metadata: input.metadata,
         baseURL: openAICompatBaseUrl(input),
+        api: openAICompatApi(input),
         apiKey: input.resolveApiKey ?? NO_KEY,
         ...(extraBody !== undefined && { extraBody }),
         // The registration chose the endpoint: the runtime's fetch decides
@@ -249,13 +294,66 @@ export const openAICompatAdapterFactory = (input) => {
         ...(input.fetch !== undefined && { clientOptions: { fetch: input.fetch } }),
     });
 };
+/**
+ * What's wrong with a registration for this adapter, read without building
+ * it (`AdapterFactoryEntry.checkConfig`): its base URL, its API and its
+ * extra request fields. Each problem's message is the error the factory
+ * throws for it: both read the registration through the same functions.
+ */
+export function openAICompatCheckConfig(input) {
+    return [baseUrlProblem(input), apiProblem(input), ...readExtraBody(input).problems].filter((problem) => problem !== undefined);
+}
+/** The entry a runtime registers: the factory, and its static check. */
+export const openAICompatAdapterEntry = {
+    adapterId: OPENAI_COMPAT_ADAPTER_ID,
+    capabilityKind: 'llm-inference',
+    factory: openAICompatAdapterFactory,
+    checkConfig: openAICompatCheckConfig,
+};
+function throwIf(input, problem) {
+    if (problem !== undefined) {
+        throw adapterConfigError(OPENAI_COMPAT_ADAPTER_ID, input.metadata.id, problem);
+    }
+}
 /** The endpoint a registration names (see `openAICompatAdapterFactory`). */
 export function openAICompatBaseUrl(input) {
+    throwIf(input, baseUrlProblem(input));
+    return input.config?.baseURL;
+}
+function baseUrlProblem(input) {
     const value = input.config?.baseURL;
-    if (typeof value !== 'string' || !/^https?:\/\/[^\s/]+/.test(value)) {
-        throw new Error(`${OPENAI_COMPAT_ADAPTER_ID}: provider "${input.metadata.id}" needs adapter_config.baseURL, an http(s) URL (e.g. ${BASE_URLS.OPENAI}).`);
-    }
-    return value;
+    if (typeof value === 'string' && /^https?:\/\/[^\s/]+/.test(value))
+        return undefined;
+    return {
+        path: '/adapter_config/baseURL',
+        message: `needs adapter_config.baseURL, an http(s) URL (e.g. ${BASE_URLS.OPENAI}).`,
+    };
+}
+/**
+ * The API a registration speaks: its `adapter_config.api` (`OPENAI_COMPAT_APIS`),
+ * or without one, the default for its base URL (`defaultOpenAICompatApi`).
+ * Throws, naming the key, on an API the adapter doesn't speak.
+ */
+export function openAICompatApi(input) {
+    throwIf(input, apiProblem(input));
+    return apiOf(input);
+}
+function apiProblem(input) {
+    const value = input.config?.api;
+    if (value === undefined || OPENAI_COMPAT_APIS.some((known) => known === value))
+        return undefined;
+    return {
+        path: '/adapter_config/api',
+        message: `adapter_config.api must be one of ${OPENAI_COMPAT_APIS.join(', ')}.`,
+    };
+}
+/** The registration's API; its base URL's default when `api` is absent or not one the adapter speaks. */
+function apiOf(input) {
+    const api = OPENAI_COMPAT_APIS.find((known) => known === input.config?.api);
+    if (api !== undefined)
+        return api;
+    const baseURL = input.config?.baseURL;
+    return defaultOpenAICompatApi(typeof baseURL === 'string' ? baseURL : '');
 }
 /**
  * The `adapter_config` key prefix for extra request fields. `adapter_config`
@@ -273,12 +371,17 @@ const UNSAFE_FIELDS = new Set(['__proto__', 'constructor', 'prototype']);
  * keys that collide, or a field the adapter sets.
  */
 export function openAICompatExtraBody(input) {
-    const fail = (problem) => {
-        throw new Error(`${OPENAI_COMPAT_ADAPTER_ID}: provider "${input.metadata.id}": ${problem}`);
-    };
+    const { body, problems } = readExtraBody(input);
+    throwIf(input, problems[0]);
+    return body;
+}
+/** A registration's extra request fields, and what's wrong with them (`openAICompatExtraBody`). */
+function readExtraBody(input) {
+    const problems = [];
+    const at = (path, problem) => problems.push({ path, message: problem });
     const config = input.config ?? {};
     if (Object.hasOwn(config, 'extraBody')) {
-        fail(`adapter_config takes extra request fields one per key, "${EXTRA_BODY_PREFIX}<field>" (dots nest), e.g. "${EXTRA_BODY_PREFIX}chat_template_kwargs.enable_thinking": false`);
+        at('/adapter_config/extraBody', `adapter_config takes extra request fields one per key, "${EXTRA_BODY_PREFIX}<field>" (dots nest), e.g. "${EXTRA_BODY_PREFIX}chat_template_kwargs.enable_thinking": false`);
     }
     let body;
     for (const [key, value] of Object.entries(config)) {
@@ -287,12 +390,17 @@ export function openAICompatExtraBody(input) {
         body ??= {};
         const problem = setField(body, key.slice(EXTRA_BODY_PREFIX.length).split('.'), value);
         if (problem !== undefined)
-            fail(`adapter_config "${key}" ${problem}`);
+            at(pointerTo(key), `adapter_config "${key}" ${problem}`);
     }
-    const problem = extraBodyProblem(body);
-    if (problem !== undefined)
-        fail(`adapter_config ${problem}`);
-    return body;
+    const reserved = reservedIn(body, apiOf(input));
+    if (reserved.length > 0) {
+        at(pointerTo(`${EXTRA_BODY_PREFIX}${reserved[0]}`), `adapter_config ${reservedProblem(reserved)}`);
+    }
+    return { ...(body !== undefined && { body }), problems };
+}
+/** The JSON pointer to a flat `adapter_config` key (its dots stay in one token). */
+function pointerTo(key) {
+    return `/adapter_config/${key.replace(/~/g, '~0').replace(/\//g, '~1')}`;
 }
 /** Set `path` in `body` to `value`; what's wrong, if anything. */
 function setField(body, path, value) {
@@ -320,16 +428,24 @@ function setField(body, path, value) {
     node[leaf] = value;
     return undefined;
 }
-function extraBodyProblem(value) {
+function extraBodyProblem(value, api) {
     if (value === undefined)
         return undefined;
     if (value === null || typeof value !== 'object' || Array.isArray(value)) {
         return 'extraBody must be an object of request fields, e.g. { chat_template_kwargs: { enable_thinking: false } }';
     }
-    const reserved = EXTRA_BODY_RESERVED.filter((key) => Object.hasOwn(value, key));
-    return reserved.length > 0
-        ? `extraBody can't set ${reserved.join(', ')}: the adapter sets ${reserved.length === 1 ? 'it' : 'them'}`
-        : undefined;
+    const reserved = reservedIn(value, api);
+    return reserved.length > 0 ? reservedProblem(reserved) : undefined;
+}
+/** The fields of `body` the adapter sets itself on `api`. */
+function reservedIn(body, api) {
+    if (body === undefined)
+        return [];
+    const fields = api === 'responses' ? EXTRA_BODY_RESERVED_RESPONSES : EXTRA_BODY_RESERVED;
+    return fields.filter((key) => Object.hasOwn(body, key));
+}
+function reservedProblem(reserved) {
+    return `extraBody can't set ${reserved.join(', ')}: the adapter sets ${reserved.length === 1 ? 'it' : 'them'}`;
 }
 /**
  * The completion's usage as the framework's counters. The endpoint's