@kindgi/adapter-model-openai-compat 0.0.0-bootstrap.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Kindgi Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,88 @@
-# @kindgi/adapter-model-openai-compat
+# `@kindgi/adapter-model-openai-compat`
 
-A placeholder. Releases come from https://github.com/kindgi/kindgi-sdk.
+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.
+
+## Purpose
+
+Translate between the framework's `ModelCallInput` / `ModelCallResult` and a non-streaming `chat.completions.create` call:
+
+- 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.
+
+## Exports
+
+- **`createOpenAICompatModelProvider(options)`** — returns a `ModelProvider` whose `metadata` is `options.metadata` unchanged. The SDK client is created on the first `invoke()` and reused while the key stays the same. `invoke()` throws when `input.model` is not one of `metadata.models[].name`, and passes the turn's `abortSignal` to the request, so a cancelled turn cancels the call.
+- **`OpenAICompatProviderOptions`**:
+  - `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.
+  - `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.
+- **`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`.
+
+## Example
+
+```ts
+import { createProviderRegistry } from '@kindgi/capabilities';
+import { BASE_URLS, createOpenAICompatModelProvider } from '@kindgi/adapter-model-openai-compat';
+
+const apiKey = process.env.OPENAI_API_KEY;
+if (apiKey === undefined) throw new Error('OPENAI_API_KEY is not set');
+
+const openai = createOpenAICompatModelProvider({
+  baseURL: BASE_URLS.OPENAI,
+  apiKey,
+  metadata: {
+    id: 'openai',
+    region: 'us',
+    models: [
+      {
+        name: 'gpt-4o-mini',
+        contextWindow: 128_000,
+        features: ['tool-use', 'structured-output'],
+        // Rates from the provider's published pricing.
+        cost: { promptUsdPer1kTokens: 0.00015, completionUsdPer1kTokens: 0.0006 },
+      },
+    ],
+  },
+  clientOptions: { timeout: 30_000 },
+});
+
+const { registry } = createProviderRegistry();
+registry.register(tenantId, openai);
+
+const result = await openai.invoke({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'What is the status of order 1042?' }],
+  tools: [
+    {
+      name: 'acme.orders.lookup',
+      description: 'Fetch an order by id.',
+      inputSchema: { type: 'object', properties: { orderId: { type: 'string' } }, required: ['orderId'] },
+    },
+  ],
+});
+for (const call of result.message.toolCalls ?? []) {
+  console.log(call.name, call.arguments); // acme.orders.lookup { orderId: '1042' }
+}
+console.log(result.finishReason, result.costUsd);
+```
+
+A local runner uses the same factory: `baseURL: BASE_URLS.OLLAMA_LOCAL`, `apiKey: 'unused'`, and zero cost rates in `metadata`.
+
+## Non-goals
+
+- **Streaming.** Requests are sent with `stream: false`; `invoke()` resolves with the complete response.
+- **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
+
+- [`@kindgi/capabilities`](../../capabilities/) — `ModelProvider`, `ProviderMetadata`, and the provider registry.
+- [`@kindgi/adapter-model-anthropic`](../model-anthropic/) — the Anthropic Messages API adapter, with a lazily resolved API key.
+- [`@kindgi/adapter-model-in-process`](../model-in-process/) — local models inside the Node.js process, no HTTP endpoint.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+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 type { ModelProvider } from '@kindgi/capabilities';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// 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';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/provider.d.ts

@@ -0,0 +1,104 @@
+import OpenAI from 'openai';
+import type { AdapterFactory, 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
+ * exported as `BASE_URLS`):
+ *
+ *   - OpenAI proper:  `https://api.openai.com/v1`
+ *   - Ollama:         `http://localhost:11434/v1`
+ *   - vLLM:           `http://localhost:8000/v1`
+ *   - llama-server:   `http://localhost:8080/v1`
+ *   - LM Studio:      `http://localhost:1234/v1`
+ *   - OpenRouter:     `https://openrouter.ai/api/v1`
+ *   - Groq:           `https://api.groq.com/openai/v1`
+ *   - Together:       `https://api.together.xyz/v1`
+ *   - Fireworks:      `https://api.fireworks.ai/inference/v1`
+ *   - DeepInfra:      `https://api.deepinfra.com/v1/openai`
+ *   - LiteLLM proxy:  `http://localhost:4000/v1`
+ *
+ * `apiKey` is required by most hosted endpoints; some local runners
+ * (Ollama, vLLM, llama-server) accept a placeholder or none — the SDK
+ * still needs a non-empty string so pass anything like `'unused'`. It
+ * may be a resolver, called on every invoke, so a rotated key takes
+ * effect on the next call (the client is rebuilt when the key changes).
+ *
+ * `metadata.models[]` MUST list every model the caller expects to
+ * invoke through this connection; the adapter picks the right entry
+ * at invoke time based on `ModelCallInput.model`. Cost per 1K tokens
+ * is caller-supplied per model — the OpenAI wire format doesn't
+ * expose pricing, and each provider bills differently.
+ */
+export interface OpenAICompatProviderOptions {
+    readonly baseURL: string;
+    readonly apiKey: string | (() => string | Promise<string>);
+    /** Metadata surfaced to the router — required. */
+    readonly metadata: ProviderMetadata;
+    /** Optional HTTP overrides passed through to the OpenAI SDK. */
+    readonly clientOptions?: Omit<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.
+     */
+    readonly extraBody?: Readonly<Record<string, unknown>>;
+}
+/** Request fields the adapter sets itself; `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
+ * instantiated lazily at first invoke — construction cost is minimal
+ * but we want to keep import-side effects zero for shape tests.
+ */
+export declare function createOpenAICompatModelProvider(options: OpenAICompatProviderOptions): ModelProvider;
+/**
+ * Well-known base URLs — surfaced as constants so callers can import
+ * without typos. Adding a new alias here doesn't lock anyone in; the
+ * adapter accepts any `baseURL` string.
+ */
+export declare const BASE_URLS: {
+    readonly OPENAI: "https://api.openai.com/v1";
+    readonly OLLAMA_LOCAL: "http://localhost:11434/v1";
+    readonly VLLM_LOCAL: "http://localhost:8000/v1";
+    readonly LLAMA_SERVER_LOCAL: "http://localhost:8080/v1";
+    readonly LM_STUDIO_LOCAL: "http://localhost:1234/v1";
+    readonly OPENROUTER: "https://openrouter.ai/api/v1";
+    readonly GROQ: "https://api.groq.com/openai/v1";
+    readonly TOGETHER: "https://api.together.xyz/v1";
+    readonly FIREWORKS: "https://api.fireworks.ai/inference/v1";
+    readonly DEEPINFRA: "https://api.deepinfra.com/v1/openai";
+    readonly LITELLM_LOCAL: "http://localhost:4000/v1";
+};
+export type Feature_ = Feature;
+/** The id the runtime registers this adapter under. */
+export declare const OPENAI_COMPAT_ADAPTER_ID = "@kindgi/adapter-model-openai-compat";
+/**
+ * The runtime's factory. A provider registration names its endpoint in
+ * `adapter_config.baseURL` (an http(s) URL; `BASE_URLS` has the
+ * well-known ones) and, for an endpoint that needs a key, its secret in
+ * `secret_ref` (resolved on every call). Without one, the adapter sends
+ * 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`).
+ */
+export declare const openAICompatAdapterFactory: AdapterFactory;
+/** The endpoint a registration names (see `openAICompatAdapterFactory`). */
+export declare function openAICompatBaseUrl(input: AdapterFactoryInput): string;
+/**
+ * The `adapter_config` key prefix for extra request fields. `adapter_config`
+ * is flat, so each field is its own key and dots nest:
+ * `"extraBody.chat_template_kwargs.enable_thinking": false` sends
+ * `{ "chat_template_kwargs": { "enable_thinking": false } }`.
+ */
+export declare const EXTRA_BODY_PREFIX = "extraBody.";
+/**
+ * A registration's extra request fields: its `adapter_config` keys under
+ * `EXTRA_BODY_PREFIX`, expanded into the body they add. `undefined` when it
+ * has none. Throws, naming the key, on an empty or unsafe field name, two
+ * keys that collide, or a field the adapter sets.
+ */
+export declare function openAICompatExtraBody(input: AdapterFactoryInput): Readonly<Record<string, unknown>> | undefined;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +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,EACjB,MAAM,sBAAsB,CAAC;AAsB9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CAAC,qBAAqB,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC;IAC7F;;;;;;;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,CAuFf;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"}

package/dist/provider.js

@@ -0,0 +1,319 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import OpenAI from 'openai';
+/**
+ * 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).
+ */
+function encodeToolName(name) {
+    return name.replace(/\./g, '__');
+}
+function decodeToolName(name) {
+    return name.replace(/__/g, '.');
+}
+/** Request fields the adapter sets itself; `extraBody` can't override them. */
+export const EXTRA_BODY_RESERVED = [
+    'model',
+    'messages',
+    'tools',
+    'response_format',
+    'temperature',
+    'max_tokens',
+    'stream',
+];
+/**
+ * Create an OpenAI-compatible `ModelProvider`. The OpenAI SDK is
+ * instantiated lazily at first invoke — construction cost is minimal
+ * but we want to keep import-side effects zero for shape tests.
+ */
+export function createOpenAICompatModelProvider(options) {
+    const metadata = options.metadata;
+    const problem = extraBodyProblem(options.extraBody);
+    if (problem !== undefined) {
+        throw new Error(`${OPENAI_COMPAT_ADAPTER_ID}: provider "${metadata.id}": ${problem}`);
+    }
+    const extraBody = options.extraBody ?? {};
+    const modelsByName = new Map(metadata.models.map((m) => [m.name, m]));
+    // One client per key: reused while the resolver returns the same key
+    // (the SDK keeps its connection pool), rebuilt when it rotates.
+    let cached;
+    async function clientForCall() {
+        const key = typeof options.apiKey === 'function' ? await options.apiKey() : options.apiKey;
+        if (cached !== undefined && cached.key === key)
+            return cached.client;
+        const client = new OpenAI({
+            apiKey: key,
+            baseURL: options.baseURL,
+            ...(options.clientOptions ?? {}),
+        });
+        cached = { key, client };
+        return client;
+    }
+    return {
+        metadata,
+        async invoke(input) {
+            const modelInfo = modelsByName.get(input.model);
+            if (modelInfo === undefined) {
+                throw new Error(`@kindgi/adapter-model-openai-compat: provider "${metadata.id}" does not expose model "${input.model}". ` +
+                    `Available: ${[...modelsByName.keys()].join(', ') || '<none>'}.`);
+            }
+            const startedAt = Date.now();
+            const openai = await clientForCall();
+            const messages = input.messages.map(toOpenAiMessage);
+            const tools = input.tools?.map(toOpenAiTool);
+            const responseFormat = input.structuredOutput
+                ? {
+                    type: 'json_schema',
+                    json_schema: {
+                        name: input.structuredOutput.name,
+                        schema: input.structuredOutput.schema,
+                        strict: true,
+                    },
+                }
+                : undefined;
+            const completion = await openai.chat.completions.create({
+                ...extraBody,
+                model: input.model,
+                messages,
+                ...(tools !== undefined && tools.length > 0 && { tools }),
+                ...(responseFormat !== undefined && { response_format: responseFormat }),
+                ...(input.temperature !== undefined && { temperature: input.temperature }),
+                ...(input.maxOutputTokens !== undefined && { max_tokens: input.maxOutputTokens }),
+                stream: false,
+            }, input.abortSignal !== undefined ? { signal: input.abortSignal } : undefined);
+            const durationMs = Date.now() - startedAt;
+            const choice = completion.choices[0];
+            const contentText = choice?.message.content ?? '';
+            const toolCalls = extractToolCalls(choice?.message.tool_calls);
+            const responseMessage = {
+                role: 'assistant',
+                content: contentText,
+                ...(toolCalls.length > 0 && { toolCalls }),
+            };
+            const promptTokens = completion.usage?.prompt_tokens ?? 0;
+            const completionTokens = completion.usage?.completion_tokens ?? 0;
+            return {
+                message: responseMessage,
+                finishReason: mapFinishReason(choice?.finish_reason),
+                usage: { promptTokens, completionTokens },
+                costUsd: computeCost(modelInfo, promptTokens, completionTokens),
+                durationMs,
+                provider: { id: metadata.id, model: input.model },
+            };
+        },
+    };
+}
+function toOpenAiMessage(m) {
+    if (m.role === 'tool') {
+        return {
+            role: 'tool',
+            content: m.content,
+            tool_call_id: m.toolCallId ?? '',
+        };
+    }
+    if (m.role === 'assistant' && m.toolCalls !== undefined && m.toolCalls.length > 0) {
+        return {
+            role: 'assistant',
+            content: m.content,
+            tool_calls: m.toolCalls.map((tc) => ({
+                id: tc.id,
+                type: 'function',
+                function: {
+                    // Encode when replaying prior assistant turns — see the
+                    // module-level comment on `encodeToolName`.
+                    name: encodeToolName(tc.name),
+                    arguments: JSON.stringify(tc.arguments),
+                },
+            })),
+        };
+    }
+    if (m.role === 'system')
+        return { role: 'system', content: m.content };
+    if (m.role === 'user')
+        return { role: 'user', content: m.content };
+    return { role: 'assistant', content: m.content };
+}
+function toOpenAiTool(tool) {
+    return {
+        type: 'function',
+        function: {
+            name: encodeToolName(tool.name),
+            description: tool.description,
+            parameters: tool.inputSchema,
+        },
+    };
+}
+function extractToolCalls(raw) {
+    if (raw === undefined || raw.length === 0)
+        return [];
+    const out = [];
+    for (const tc of raw) {
+        if (tc.type !== 'function')
+            continue;
+        let args;
+        try {
+            args = JSON.parse(tc.function.arguments);
+        }
+        catch {
+            args = {};
+        }
+        // Decode: the wire returns the encoded name; the framework
+        // expects the canonical dotted form.
+        out.push({ id: tc.id, name: decodeToolName(tc.function.name), arguments: args });
+    }
+    return out;
+}
+function mapFinishReason(reason) {
+    switch (reason) {
+        case 'stop':
+            return 'stop';
+        case 'length':
+            return 'length';
+        case 'tool_calls':
+        case 'function_call':
+            return 'tool-use';
+        case 'content_filter':
+            return 'content-filter';
+        default:
+            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
+ * adapter accepts any `baseURL` string.
+ */
+export const BASE_URLS = {
+    OPENAI: 'https://api.openai.com/v1',
+    OLLAMA_LOCAL: 'http://localhost:11434/v1',
+    VLLM_LOCAL: 'http://localhost:8000/v1',
+    LLAMA_SERVER_LOCAL: 'http://localhost:8080/v1',
+    LM_STUDIO_LOCAL: 'http://localhost:1234/v1',
+    OPENROUTER: 'https://openrouter.ai/api/v1',
+    GROQ: 'https://api.groq.com/openai/v1',
+    TOGETHER: 'https://api.together.xyz/v1',
+    FIREWORKS: 'https://api.fireworks.ai/inference/v1',
+    DEEPINFRA: 'https://api.deepinfra.com/v1/openai',
+    LITELLM_LOCAL: 'http://localhost:4000/v1',
+};
+/** The id the runtime registers this adapter under. */
+export const OPENAI_COMPAT_ADAPTER_ID = '@kindgi/adapter-model-openai-compat';
+/** The key sent when a registration has none: local runners ignore it. */
+const NO_KEY = 'unused';
+/**
+ * The runtime's factory. A provider registration names its endpoint in
+ * `adapter_config.baseURL` (an http(s) URL; `BASE_URLS` has the
+ * well-known ones) and, for an endpoint that needs a key, its secret in
+ * `secret_ref` (resolved on every call). Without one, the adapter sends
+ * 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`).
+ */
+export const openAICompatAdapterFactory = (input) => {
+    const extraBody = openAICompatExtraBody(input);
+    return createOpenAICompatModelProvider({
+        metadata: input.metadata,
+        baseURL: openAICompatBaseUrl(input),
+        apiKey: input.resolveApiKey ?? NO_KEY,
+        ...(extraBody !== undefined && { extraBody }),
+        // The registration chose the endpoint: the runtime's fetch decides
+        // which hosts it may reach (`AdapterFactoryInput.fetch`).
+        ...(input.fetch !== undefined && { clientOptions: { fetch: input.fetch } }),
+    });
+};
+/** The endpoint a registration names (see `openAICompatAdapterFactory`). */
+export function openAICompatBaseUrl(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;
+}
+/**
+ * The `adapter_config` key prefix for extra request fields. `adapter_config`
+ * is flat, so each field is its own key and dots nest:
+ * `"extraBody.chat_template_kwargs.enable_thinking": false` sends
+ * `{ "chat_template_kwargs": { "enable_thinking": false } }`.
+ */
+export const EXTRA_BODY_PREFIX = 'extraBody.';
+/** Names that would reach an object's prototype; never a field name here. */
+const UNSAFE_FIELDS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * A registration's extra request fields: its `adapter_config` keys under
+ * `EXTRA_BODY_PREFIX`, expanded into the body they add. `undefined` when it
+ * has none. Throws, naming the key, on an empty or unsafe field name, two
+ * 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 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`);
+    }
+    let body;
+    for (const [key, value] of Object.entries(config)) {
+        if (!key.startsWith(EXTRA_BODY_PREFIX))
+            continue;
+        body ??= {};
+        const problem = setField(body, key.slice(EXTRA_BODY_PREFIX.length).split('.'), value);
+        if (problem !== undefined)
+            fail(`adapter_config "${key}" ${problem}`);
+    }
+    const problem = extraBodyProblem(body);
+    if (problem !== undefined)
+        fail(`adapter_config ${problem}`);
+    return body;
+}
+/** Set `path` in `body` to `value`; what's wrong, if anything. */
+function setField(body, path, value) {
+    if (path.some((field) => field === '' || UNSAFE_FIELDS.has(field))) {
+        return "isn't a field path";
+    }
+    let node = body;
+    for (const field of path.slice(0, -1)) {
+        const next = Object.hasOwn(node, field) ? node[field] : undefined;
+        if (next === undefined) {
+            const child = {};
+            node[field] = child;
+            node = child;
+        }
+        else if (typeof next === 'object' && next !== null) {
+            node = next;
+        }
+        else {
+            return 'nests under a field another key sets';
+        }
+    }
+    const leaf = path[path.length - 1];
+    if (Object.hasOwn(node, leaf))
+        return 'collides with another key';
+    node[leaf] = value;
+    return undefined;
+}
+function extraBodyProblem(value) {
+    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;
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,51 @@
 {
   "name": "@kindgi/adapter-model-openai-compat",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.0",
+  "description": "OpenAI-compatible ModelProvider for @kindgi/capabilities. Points at any endpoint speaking the OpenAI Chat Completions wire format — OpenAI proper, Ollama (/v1), vLLM, llama-server, LM Studio, OpenRouter, Groq, Together, Fireworks, DeepInfra, LiteLLM proxy (base URLs exported as BASE_URLS), or any other compatible endpoint. One adapter, many backends. Cost per 1K tokens is supplied by the caller (from the provider's public pricing) since the API surface itself doesn't expose it.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/adapters/model-openai-compat"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/adapters/model-openai-compat#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kindgi/capabilities": "0.1.0",
+    "openai": "^7.17.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// 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 type { OpenAICompatProviderOptions } from './provider.js';
+export type { ModelProvider } from '@kindgi/capabilities';

package/src/provider.ts

@@ -0,0 +1,410 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import OpenAI from 'openai';
+
+import type {
+  AdapterFactory,
+  AdapterFactoryInput,
+  Feature,
+  ModelCallInput,
+  ModelCallResult,
+  ModelInfo,
+  ModelMessage,
+  ModelProvider,
+  ModelToolCall,
+  ModelToolDefinition,
+  ProviderMetadata,
+} from '@kindgi/capabilities';
+
+/**
+ * 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).
+ */
+function encodeToolName(name: string): string {
+  return name.replace(/\./g, '__');
+}
+
+function decodeToolName(name: string): string {
+  return name.replace(/__/g, '.');
+}
+
+/**
+ * Configuration for an OpenAI-compatible ModelProvider. `baseURL` is the
+ * key — same adapter, different endpoints (the well-known ones are
+ * exported as `BASE_URLS`):
+ *
+ *   - OpenAI proper:  `https://api.openai.com/v1`
+ *   - Ollama:         `http://localhost:11434/v1`
+ *   - vLLM:           `http://localhost:8000/v1`
+ *   - llama-server:   `http://localhost:8080/v1`
+ *   - LM Studio:      `http://localhost:1234/v1`
+ *   - OpenRouter:     `https://openrouter.ai/api/v1`
+ *   - Groq:           `https://api.groq.com/openai/v1`
+ *   - Together:       `https://api.together.xyz/v1`
+ *   - Fireworks:      `https://api.fireworks.ai/inference/v1`
+ *   - DeepInfra:      `https://api.deepinfra.com/v1/openai`
+ *   - LiteLLM proxy:  `http://localhost:4000/v1`
+ *
+ * `apiKey` is required by most hosted endpoints; some local runners
+ * (Ollama, vLLM, llama-server) accept a placeholder or none — the SDK
+ * still needs a non-empty string so pass anything like `'unused'`. It
+ * may be a resolver, called on every invoke, so a rotated key takes
+ * effect on the next call (the client is rebuilt when the key changes).
+ *
+ * `metadata.models[]` MUST list every model the caller expects to
+ * invoke through this connection; the adapter picks the right entry
+ * at invoke time based on `ModelCallInput.model`. Cost per 1K tokens
+ * is caller-supplied per model — the OpenAI wire format doesn't
+ * expose pricing, and each provider bills differently.
+ */
+export interface OpenAICompatProviderOptions {
+  readonly baseURL: string;
+  readonly apiKey: string | (() => string | Promise<string>);
+  /** Metadata surfaced to the router — required. */
+  readonly metadata: ProviderMetadata;
+  /** Optional HTTP overrides passed through to the OpenAI SDK. */
+  readonly clientOptions?: Omit<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.
+   */
+  readonly extraBody?: Readonly<Record<string, unknown>>;
+}
+
+/** Request fields the adapter sets itself; `extraBody` can't override them. */
+export const EXTRA_BODY_RESERVED = [
+  'model',
+  'messages',
+  'tools',
+  'response_format',
+  'temperature',
+  'max_tokens',
+  'stream',
+] as const;
+
+/**
+ * Create an OpenAI-compatible `ModelProvider`. The OpenAI SDK is
+ * instantiated lazily at first invoke — construction cost is minimal
+ * but we want to keep import-side effects zero for shape tests.
+ */
+export function createOpenAICompatModelProvider(
+  options: OpenAICompatProviderOptions,
+): ModelProvider {
+  const metadata = options.metadata;
+  const problem = extraBodyProblem(options.extraBody);
+  if (problem !== undefined) {
+    throw new Error(`${OPENAI_COMPAT_ADAPTER_ID}: provider "${metadata.id}": ${problem}`);
+  }
+  const extraBody = options.extraBody ?? {};
+  const modelsByName = new Map<string, ModelInfo>(metadata.models.map((m) => [m.name, m] as const));
+  // One client per key: reused while the resolver returns the same key
+  // (the SDK keeps its connection pool), rebuilt when it rotates.
+  let cached: { readonly key: string; readonly client: OpenAI } | undefined;
+  async function clientForCall(): Promise<OpenAI> {
+    const key = typeof options.apiKey === 'function' ? await options.apiKey() : options.apiKey;
+    if (cached !== undefined && cached.key === key) return cached.client;
+    const client = new OpenAI({
+      apiKey: key,
+      baseURL: options.baseURL,
+      ...(options.clientOptions ?? {}),
+    });
+    cached = { key, client };
+    return client;
+  }
+
+  return {
+    metadata,
+    async invoke(input: ModelCallInput): Promise<ModelCallResult> {
+      const modelInfo = modelsByName.get(input.model);
+      if (modelInfo === undefined) {
+        throw new Error(
+          `@kindgi/adapter-model-openai-compat: provider "${metadata.id}" does not expose model "${input.model}". ` +
+            `Available: ${[...modelsByName.keys()].join(', ') || '<none>'}.`,
+        );
+      }
+      const startedAt = Date.now();
+      const openai = await clientForCall();
+
+      const messages = input.messages.map(toOpenAiMessage);
+      const tools = input.tools?.map(toOpenAiTool);
+
+      const responseFormat = input.structuredOutput
+        ? {
+            type: 'json_schema' as const,
+            json_schema: {
+              name: input.structuredOutput.name,
+              schema: input.structuredOutput.schema,
+              strict: true,
+            },
+          }
+        : undefined;
+
+      const completion = await openai.chat.completions.create(
+        {
+          ...extraBody,
+          model: input.model,
+          messages,
+          ...(tools !== undefined && tools.length > 0 && { tools }),
+          ...(responseFormat !== undefined && { response_format: responseFormat }),
+          ...(input.temperature !== undefined && { temperature: input.temperature }),
+          ...(input.maxOutputTokens !== undefined && { max_tokens: input.maxOutputTokens }),
+          stream: false,
+        },
+        input.abortSignal !== undefined ? { signal: input.abortSignal } : undefined,
+      );
+
+      const durationMs = Date.now() - startedAt;
+      const choice = completion.choices[0];
+      const contentText = choice?.message.content ?? '';
+      const toolCalls = extractToolCalls(choice?.message.tool_calls);
+      const responseMessage: ModelMessage = {
+        role: 'assistant',
+        content: contentText,
+        ...(toolCalls.length > 0 && { toolCalls }),
+      };
+
+      const promptTokens = completion.usage?.prompt_tokens ?? 0;
+      const completionTokens = completion.usage?.completion_tokens ?? 0;
+
+      return {
+        message: responseMessage,
+        finishReason: mapFinishReason(choice?.finish_reason),
+        usage: { promptTokens, completionTokens },
+        costUsd: computeCost(modelInfo, promptTokens, completionTokens),
+        durationMs,
+        provider: { id: metadata.id, model: input.model },
+      };
+    },
+  };
+}
+
+function toOpenAiMessage(m: ModelMessage): OpenAI.Chat.Completions.ChatCompletionMessageParam {
+  if (m.role === 'tool') {
+    return {
+      role: 'tool',
+      content: m.content,
+      tool_call_id: m.toolCallId ?? '',
+    };
+  }
+  if (m.role === 'assistant' && m.toolCalls !== undefined && m.toolCalls.length > 0) {
+    return {
+      role: 'assistant',
+      content: m.content,
+      tool_calls: m.toolCalls.map((tc) => ({
+        id: tc.id,
+        type: 'function' as const,
+        function: {
+          // Encode when replaying prior assistant turns — see the
+          // module-level comment on `encodeToolName`.
+          name: encodeToolName(tc.name),
+          arguments: JSON.stringify(tc.arguments),
+        },
+      })),
+    };
+  }
+  if (m.role === 'system') return { role: 'system', content: m.content };
+  if (m.role === 'user') return { role: 'user', content: m.content };
+  return { role: 'assistant', content: m.content };
+}
+
+function toOpenAiTool(tool: ModelToolDefinition): OpenAI.Chat.Completions.ChatCompletionTool {
+  return {
+    type: 'function',
+    function: {
+      name: encodeToolName(tool.name),
+      description: tool.description,
+      parameters: tool.inputSchema as Record<string, unknown>,
+    },
+  };
+}
+
+function extractToolCalls(
+  raw: OpenAI.Chat.Completions.ChatCompletionMessageToolCall[] | undefined,
+): ModelToolCall[] {
+  if (raw === undefined || raw.length === 0) return [];
+  const out: ModelToolCall[] = [];
+  for (const tc of raw) {
+    if (tc.type !== 'function') continue;
+    let args: Record<string, unknown>;
+    try {
+      args = JSON.parse(tc.function.arguments) as Record<string, unknown>;
+    } catch {
+      args = {};
+    }
+    // Decode: the wire returns the encoded name; the framework
+    // expects the canonical dotted form.
+    out.push({ id: tc.id, name: decodeToolName(tc.function.name), arguments: args });
+  }
+  return out;
+}
+
+function mapFinishReason(reason: string | null | undefined): ModelCallResult['finishReason'] {
+  switch (reason) {
+    case 'stop':
+      return 'stop';
+    case 'length':
+      return 'length';
+    case 'tool_calls':
+    case 'function_call':
+      return 'tool-use';
+    case 'content_filter':
+      return 'content-filter';
+    default:
+      return 'stop';
+  }
+}
+
+function computeCost(modelInfo: ModelInfo, promptTokens: number, completionTokens: number): number {
+  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
+ * adapter accepts any `baseURL` string.
+ */
+export const BASE_URLS = {
+  OPENAI: 'https://api.openai.com/v1',
+  OLLAMA_LOCAL: 'http://localhost:11434/v1',
+  VLLM_LOCAL: 'http://localhost:8000/v1',
+  LLAMA_SERVER_LOCAL: 'http://localhost:8080/v1',
+  LM_STUDIO_LOCAL: 'http://localhost:1234/v1',
+  OPENROUTER: 'https://openrouter.ai/api/v1',
+  GROQ: 'https://api.groq.com/openai/v1',
+  TOGETHER: 'https://api.together.xyz/v1',
+  FIREWORKS: 'https://api.fireworks.ai/inference/v1',
+  DEEPINFRA: 'https://api.deepinfra.com/v1/openai',
+  LITELLM_LOCAL: 'http://localhost:4000/v1',
+} as const;
+
+export type Feature_ = Feature; // local alias; not exported from the package entry (src/index.ts)
+
+/** The id the runtime registers this adapter under. */
+export const OPENAI_COMPAT_ADAPTER_ID = '@kindgi/adapter-model-openai-compat';
+
+/** The key sent when a registration has none: local runners ignore it. */
+const NO_KEY = 'unused';
+
+/**
+ * The runtime's factory. A provider registration names its endpoint in
+ * `adapter_config.baseURL` (an http(s) URL; `BASE_URLS` has the
+ * well-known ones) and, for an endpoint that needs a key, its secret in
+ * `secret_ref` (resolved on every call). Without one, the adapter sends
+ * 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`).
+ */
+export const openAICompatAdapterFactory: AdapterFactory = (input) => {
+  const extraBody = openAICompatExtraBody(input);
+  return createOpenAICompatModelProvider({
+    metadata: input.metadata,
+    baseURL: openAICompatBaseUrl(input),
+    apiKey: input.resolveApiKey ?? NO_KEY,
+    ...(extraBody !== undefined && { extraBody }),
+    // The registration chose the endpoint: the runtime's fetch decides
+    // which hosts it may reach (`AdapterFactoryInput.fetch`).
+    ...(input.fetch !== undefined && { clientOptions: { fetch: input.fetch } }),
+  });
+};
+
+/** The endpoint a registration names (see `openAICompatAdapterFactory`). */
+export function openAICompatBaseUrl(input: AdapterFactoryInput): string {
+  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;
+}
+
+/**
+ * The `adapter_config` key prefix for extra request fields. `adapter_config`
+ * is flat, so each field is its own key and dots nest:
+ * `"extraBody.chat_template_kwargs.enable_thinking": false` sends
+ * `{ "chat_template_kwargs": { "enable_thinking": false } }`.
+ */
+export const EXTRA_BODY_PREFIX = 'extraBody.';
+
+/** Names that would reach an object's prototype; never a field name here. */
+const UNSAFE_FIELDS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * A registration's extra request fields: its `adapter_config` keys under
+ * `EXTRA_BODY_PREFIX`, expanded into the body they add. `undefined` when it
+ * has none. Throws, naming the key, on an empty or unsafe field name, two
+ * keys that collide, or a field the adapter sets.
+ */
+export function openAICompatExtraBody(
+  input: AdapterFactoryInput,
+): Readonly<Record<string, unknown>> | undefined {
+  const fail = (problem: string): never => {
+    throw new Error(`${OPENAI_COMPAT_ADAPTER_ID}: provider "${input.metadata.id}": ${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`,
+    );
+  }
+  let body: Record<string, unknown> | undefined;
+  for (const [key, value] of Object.entries(config)) {
+    if (!key.startsWith(EXTRA_BODY_PREFIX)) continue;
+    body ??= {};
+    const problem = setField(body, key.slice(EXTRA_BODY_PREFIX.length).split('.'), value);
+    if (problem !== undefined) fail(`adapter_config "${key}" ${problem}`);
+  }
+  const problem = extraBodyProblem(body);
+  if (problem !== undefined) fail(`adapter_config ${problem}`);
+  return body;
+}
+
+/** Set `path` in `body` to `value`; what's wrong, if anything. */
+function setField(body: Record<string, unknown>, path: readonly string[], value: unknown) {
+  if (path.some((field) => field === '' || UNSAFE_FIELDS.has(field))) {
+    return "isn't a field path";
+  }
+  let node = body;
+  for (const field of path.slice(0, -1)) {
+    const next = Object.hasOwn(node, field) ? node[field] : undefined;
+    if (next === undefined) {
+      const child: Record<string, unknown> = {};
+      node[field] = child;
+      node = child;
+    } else if (typeof next === 'object' && next !== null) {
+      node = next as Record<string, unknown>;
+    } else {
+      return 'nests under a field another key sets';
+    }
+  }
+  const leaf = path[path.length - 1] as string;
+  if (Object.hasOwn(node, leaf)) return 'collides with another key';
+  node[leaf] = value;
+  return undefined;
+}
+
+function extraBodyProblem(value: unknown): string | undefined {
+  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;
+}