@kindgi/adapter-model-openai-compat 0.0.0-stage → 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 @@
-# Temporary Holding Version
+# `@kindgi/adapter-model-openai-compat`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,MAAM,MAAM,QAAQ,CAAC;AAgB5B;;;;;;;;;;;GAWG;AACH,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAiDD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,OAAO;IACP,UAAU;IACV,OAAO;IACP,iBAAiB;IACjB,aAAa;IACb,YAAY;IACZ,QAAQ;CACA,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,+BAA+B,CAC7C,OAAoC;IAEpC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACpD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,GAAG,wBAAwB,eAAe,QAAQ,CAAC,EAAE,MAAM,OAAO,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;IAC1C,MAAM,YAAY,GAAG,IAAI,GAAG,CAAoB,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAU,CAAC,CAAC,CAAC;IAClG,qEAAqE;IACrE,gEAAgE;IAChE,IAAI,MAAqE,CAAC;IAC1E,KAAK,UAAU,aAAa;QAC1B,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;QAC3F,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,KAAK,GAAG;YAAE,OAAO,MAAM,CAAC,MAAM,CAAC;QACrE,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;YACxB,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,CAAC;QACzB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO;QACL,QAAQ;QACR,KAAK,CAAC,MAAM,CAAC,KAAqB;YAChC,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAChD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CACb,kDAAkD,QAAQ,CAAC,EAAE,4BAA4B,KAAK,CAAC,KAAK,KAAK;oBACvG,cAAc,CAAC,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,GAAG,CACnE,CAAC;YACJ,CAAC;YACD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,MAAM,aAAa,EAAE,CAAC;YAErC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;YACrD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;YAE7C,MAAM,cAAc,GAAG,KAAK,CAAC,gBAAgB;gBAC3C,CAAC,CAAC;oBACE,IAAI,EAAE,aAAsB;oBAC5B,WAAW,EAAE;wBACX,IAAI,EAAE,KAAK,CAAC,gBAAgB,CAAC,IAAI;wBACjC,MAAM,EAAE,KAAK,CAAC,gBAAgB,CAAC,MAAM;wBACrC,MAAM,EAAE,IAAI;qBACb;iBACF;gBACH,CAAC,CAAC,SAAS,CAAC;YAEd,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CACrD;gBACE,GAAG,SAAS;gBACZ,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,QAAQ;gBACR,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;gBACzD,GAAG,CAAC,cAAc,KAAK,SAAS,IAAI,EAAE,eAAe,EAAE,cAAc,EAAE,CAAC;gBACxE,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;gBAC1E,GAAG,CAAC,KAAK,CAAC,eAAe,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC;gBACjF,MAAM,EAAE,KAAK;aACd,EACD,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CAC5E,CAAC;YAEF,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACrC,MAAM,WAAW,GAAG,MAAM,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;YAClD,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;YAC/D,MAAM,eAAe,GAAiB;gBACpC,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE,WAAW;gBACpB,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;aAC3C,CAAC;YAEF,MAAM,YAAY,GAAG,UAAU,CAAC,KAAK,EAAE,aAAa,IAAI,CAAC,CAAC;YAC1D,MAAM,gBAAgB,GAAG,UAAU,CAAC,KAAK,EAAE,iBAAiB,IAAI,CAAC,CAAC;YAElE,OAAO;gBACL,OAAO,EAAE,eAAe;gBACxB,YAAY,EAAE,eAAe,CAAC,MAAM,EAAE,aAAa,CAAC;gBACpD,KAAK,EAAE,EAAE,YAAY,EAAE,gBAAgB,EAAE;gBACzC,OAAO,EAAE,WAAW,CAAC,SAAS,EAAE,YAAY,EAAE,gBAAgB,CAAC;gBAC/D,UAAU;gBACV,QAAQ,EAAE,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;aAClD,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,CAAe;IACtC,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,YAAY,EAAE,CAAC,CAAC,UAAU,IAAI,EAAE;SACjC,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClF,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,UAAU,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;gBACnC,EAAE,EAAE,EAAE,CAAC,EAAE;gBACT,IAAI,EAAE,UAAmB;gBACzB,QAAQ,EAAE;oBACR,wDAAwD;oBACxD,4CAA4C;oBAC5C,IAAI,EAAE,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC;oBAC7B,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC;iBACxC;aACF,CAAC,CAAC;SACJ,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACvE,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACnE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;AACnD,CAAC;AAED,SAAS,YAAY,CAAC,IAAyB;IAC7C,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE;YACR,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;YAC/B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,CAAC,WAAsC;SACxD;KACF,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CACvB,GAAwE;IAExE,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrD,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,IAAI,EAAE,CAAC,IAAI,KAAK,UAAU;YAAE,SAAS;QACrC,IAAI,IAA6B,CAAC;QAClC,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,SAAS,CAA4B,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,EAAE,CAAC;QACZ,CAAC;QACD,2DAA2D;QAC3D,qCAAqC;QACrC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,eAAe,CAAC,MAAiC;IACxD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,YAAY,CAAC;QAClB,KAAK,eAAe;YAClB,OAAO,UAAU,CAAC;QACpB,KAAK,gBAAgB;YACnB,OAAO,gBAAgB,CAAC;QAC1B;YACE,OAAO,MAAM,CAAC;IAClB,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,SAAoB,EAAE,YAAoB,EAAE,gBAAwB;IACvF,MAAM,UAAU,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,oBAAoB,CAAC;IAC/E,MAAM,cAAc,GAAG,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,wBAAwB,CAAC;IAC3F,OAAO,UAAU,GAAG,cAAc,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,MAAM,EAAE,2BAA2B;IACnC,YAAY,EAAE,2BAA2B;IACzC,UAAU,EAAE,0BAA0B;IACtC,kBAAkB,EAAE,0BAA0B;IAC9C,eAAe,EAAE,0BAA0B;IAC3C,UAAU,EAAE,8BAA8B;IAC1C,IAAI,EAAE,gCAAgC;IACtC,QAAQ,EAAE,6BAA6B;IACvC,SAAS,EAAE,uCAAuC;IAClD,SAAS,EAAE,qCAAqC;IAChD,aAAa,EAAE,0BAA0B;CACjC,CAAC;AAIX,uDAAuD;AACvD,MAAM,CAAC,MAAM,wBAAwB,GAAG,qCAAqC,CAAC;AAE9E,0EAA0E;AAC1E,MAAM,MAAM,GAAG,QAAQ,CAAC;AAExB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAmB,CAAC,KAAK,EAAE,EAAE;IAClE,MAAM,SAAS,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,+BAA+B,CAAC;QACrC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,mBAAmB,CAAC,KAAK,CAAC;QACnC,MAAM,EAAE,KAAK,CAAC,aAAa,IAAI,MAAM;QACrC,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,mEAAmE;QACnE,0DAA0D;QAC1D,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;KAC5E,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,UAAU,mBAAmB,CAAC,KAA0B;IAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CACb,GAAG,wBAAwB,eAAe,KAAK,CAAC,QAAQ,CAAC,EAAE,wDAAwD,SAAS,CAAC,MAAM,IAAI,CACxI,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAE9C,6EAA6E;AAC7E,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAA0B;IAE1B,MAAM,IAAI,GAAG,CAAC,OAAe,EAAS,EAAE;QACtC,MAAM,IAAI,KAAK,CAAC,GAAG,wBAAwB,eAAe,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,OAAO,EAAE,CAAC,CAAC;IAC9F,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC;IAClC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,CAAC;QACvC,IAAI,CACF,2DAA2D,iBAAiB,+BAA+B,iBAAiB,8CAA8C,CAC3K,CAAC;IACJ,CAAC;IACD,IAAI,IAAyC,CAAC;IAC9C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC;YAAE,SAAS;QACjD,IAAI,KAAK,EAAE,CAAC;QACZ,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QACtF,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,mBAAmB,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,kEAAkE;AAClE,SAAS,QAAQ,CAAC,IAA6B,EAAE,IAAuB,EAAE,KAAc;IACtF,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,EAAE,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACnE,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IACD,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAClE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,KAAK,GAA4B,EAAE,CAAC;YAC1C,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;YACpB,IAAI,GAAG,KAAK,CAAC;QACf,CAAC;aAAM,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACrD,IAAI,GAAG,IAA+B,CAAC;QACzC,CAAC;aAAM,CAAC;YACN,OAAO,sCAAsC,CAAC;QAChD,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAW,CAAC;IAC7C,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,2BAA2B,CAAC;IAClE,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACnB,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,0GAA0G,CAAC;IACpH,CAAC;IACD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;IAChF,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC;QACxB,CAAC,CAAC,uBAAuB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,sBAAsB,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE;QACzG,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@kindgi/adapter-model-openai-compat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+    "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;
+}