@markbrutx/promptbook-openrouter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 markbrutx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @markbrutx/promptbook-openrouter
+
+OpenRouter `ModelAdapter` for [`@markbrutx/promptbook-core`](https://www.npmjs.com/package/@markbrutx/promptbook-core)
+eval. The network lives here so the core stays pure. Part of
+[promptbook](https://github.com/markbrutx/promptbook).
+
+```
+npm i @markbrutx/promptbook-openrouter
+```
+
+## Usage
+
+```ts
+import { evaluate } from "@markbrutx/promptbook-core";
+import { openRouterAdapter } from "@markbrutx/promptbook-openrouter";
+
+const adapter = openRouterAdapter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+  model: "openai/gpt-4o-mini",
+});
+
+const report = await evaluate({ promptsDir: "./prompts", adapter /* … */ });
+```
+
+`core` only ever sees the `ModelAdapter` interface; this package maps a request
+to OpenRouter's HTTP API and back. Swap it for any provider by implementing the
+same interface.
+
+## License
+
+[MIT](./LICENSE)

package/dist/adapter.d.ts

@@ -0,0 +1,22 @@
+import type { ModelAdapter } from "@markbrutx/promptbook-core";
+export interface OpenRouterOptions {
+    /** Default model id, e.g. "openai/gpt-4o-mini". Overridable per request. */
+    model: string;
+    /** API key; falls back to `process.env.OPENROUTER_API_KEY` at call time. */
+    apiKey?: string;
+    /** Override the API base URL (e.g. a proxy). */
+    baseUrl?: string;
+    /** Inject a `fetch` implementation; defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Build a {@link ModelAdapter} backed by OpenRouter's chat-completions API.
+ *
+ * This is the one piece that performs network IO; the eval engine in
+ * `@markbrutx/promptbook-core` only sees the adapter interface. The request maps
+ * `{ system, input }` to `system`/`user` messages and parses the first
+ * choice's content back into `{ text, usage, raw }`. A missing key (option or
+ * env) or a non-2xx response raises a clear error.
+ */
+export declare function openRouterAdapter(options: OpenRouterOptions): ModelAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA2C,MAAM,4BAA4B,CAAC;AAQxG,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAsCD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,YAAY,CA6C1E"}

package/dist/adapter.js

@@ -0,0 +1,78 @@
+/** OpenRouter chat-completions base URL (no trailing slash). */
+const DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
+/** Environment variable consulted when no explicit `apiKey` is given. */
+const API_KEY_ENV = "OPENROUTER_API_KEY";
+function mapUsage(usage) {
+    if (!usage) {
+        return undefined;
+    }
+    const mapped = {};
+    if (typeof usage.prompt_tokens === "number") {
+        mapped.promptTokens = usage.prompt_tokens;
+    }
+    if (typeof usage.completion_tokens === "number") {
+        mapped.completionTokens = usage.completion_tokens;
+    }
+    if (typeof usage.total_tokens === "number") {
+        mapped.totalTokens = usage.total_tokens;
+    }
+    return mapped;
+}
+async function readErrorBody(response) {
+    try {
+        const body = (await response.text()).trim();
+        return body.length > 0 ? `: ${body}` : "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Build a {@link ModelAdapter} backed by OpenRouter's chat-completions API.
+ *
+ * This is the one piece that performs network IO; the eval engine in
+ * `@markbrutx/promptbook-core` only sees the adapter interface. The request maps
+ * `{ system, input }` to `system`/`user` messages and parses the first
+ * choice's content back into `{ text, usage, raw }`. A missing key (option or
+ * env) or a non-2xx response raises a clear error.
+ */
+export function openRouterAdapter(options) {
+    const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const doFetch = options.fetch ?? globalThis.fetch;
+    return {
+        async complete(request) {
+            const apiKey = options.apiKey ?? process.env[API_KEY_ENV];
+            if (!apiKey) {
+                throw new Error(`OpenRouter API key missing: pass { apiKey } or set the ${API_KEY_ENV} environment variable.`);
+            }
+            const messages = [];
+            if (request.system.length > 0) {
+                messages.push({ role: "system", content: request.system });
+            }
+            messages.push({ role: "user", content: request.input });
+            const response = await doFetch(`${baseUrl}/chat/completions`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({ model: request.model ?? options.model, messages }),
+            });
+            if (!response.ok) {
+                const body = await readErrorBody(response);
+                throw new Error(`OpenRouter request failed: ${response.status} ${response.statusText}${body}`);
+            }
+            const data = (await response.json());
+            const result = {
+                text: data.choices?.[0]?.message?.content ?? "",
+                raw: data,
+            };
+            const usage = mapUsage(data.usage);
+            if (usage !== undefined) {
+                result.usage = usage;
+            }
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { OpenRouterOptions } from "./adapter.js";
+export { openRouterAdapter } from "./adapter.js";
+//# 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":"AAAA,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { openRouterAdapter } from "./adapter.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":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@markbrutx/promptbook-openrouter",
+  "version": "0.1.0",
+  "description": "OpenRouter ModelAdapter for @markbrutx/promptbook-core eval. Network lives here; core stays pure.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
+    "test": "vitest --run",
+    "check": "biome check ."
+  },
+  "dependencies": {
+    "@markbrutx/promptbook-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "latest",
+    "@types/node": "^20.14.0",
+    "@typescript/native-preview": "latest",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20.6"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,110 @@
+import type { ModelAdapter, ModelRequest, ModelResponse, ModelUsage } from "@markbrutx/promptbook-core";
+
+/** OpenRouter chat-completions base URL (no trailing slash). */
+const DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
+
+/** Environment variable consulted when no explicit `apiKey` is given. */
+const API_KEY_ENV = "OPENROUTER_API_KEY";
+
+export interface OpenRouterOptions {
+  /** Default model id, e.g. "openai/gpt-4o-mini". Overridable per request. */
+  model: string;
+  /** API key; falls back to `process.env.OPENROUTER_API_KEY` at call time. */
+  apiKey?: string;
+  /** Override the API base URL (e.g. a proxy). */
+  baseUrl?: string;
+  /** Inject a `fetch` implementation; defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+}
+
+/** Shape of the fields we read from an OpenRouter chat-completions reply. */
+interface ChatCompletion {
+  choices?: { message?: { content?: string } }[];
+  usage?: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+  };
+}
+
+function mapUsage(usage: ChatCompletion["usage"]): ModelUsage | undefined {
+  if (!usage) {
+    return undefined;
+  }
+  const mapped: ModelUsage = {};
+  if (typeof usage.prompt_tokens === "number") {
+    mapped.promptTokens = usage.prompt_tokens;
+  }
+  if (typeof usage.completion_tokens === "number") {
+    mapped.completionTokens = usage.completion_tokens;
+  }
+  if (typeof usage.total_tokens === "number") {
+    mapped.totalTokens = usage.total_tokens;
+  }
+  return mapped;
+}
+
+async function readErrorBody(response: Response): Promise<string> {
+  try {
+    const body = (await response.text()).trim();
+    return body.length > 0 ? `: ${body}` : "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Build a {@link ModelAdapter} backed by OpenRouter's chat-completions API.
+ *
+ * This is the one piece that performs network IO; the eval engine in
+ * `@markbrutx/promptbook-core` only sees the adapter interface. The request maps
+ * `{ system, input }` to `system`/`user` messages and parses the first
+ * choice's content back into `{ text, usage, raw }`. A missing key (option or
+ * env) or a non-2xx response raises a clear error.
+ */
+export function openRouterAdapter(options: OpenRouterOptions): ModelAdapter {
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const doFetch = options.fetch ?? globalThis.fetch;
+
+  return {
+    async complete(request: ModelRequest): Promise<ModelResponse> {
+      const apiKey = options.apiKey ?? process.env[API_KEY_ENV];
+      if (!apiKey) {
+        throw new Error(
+          `OpenRouter API key missing: pass { apiKey } or set the ${API_KEY_ENV} environment variable.`,
+        );
+      }
+
+      const messages: { role: string; content: string }[] = [];
+      if (request.system.length > 0) {
+        messages.push({ role: "system", content: request.system });
+      }
+      messages.push({ role: "user", content: request.input });
+
+      const response = await doFetch(`${baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({ model: request.model ?? options.model, messages }),
+      });
+
+      if (!response.ok) {
+        const body = await readErrorBody(response);
+        throw new Error(`OpenRouter request failed: ${response.status} ${response.statusText}${body}`);
+      }
+
+      const data = (await response.json()) as ChatCompletion;
+      const result: ModelResponse = {
+        text: data.choices?.[0]?.message?.content ?? "",
+        raw: data,
+      };
+      const usage = mapUsage(data.usage);
+      if (usage !== undefined) {
+        result.usage = usage;
+      }
+      return result;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export type { OpenRouterOptions } from "./adapter.js";
+export { openRouterAdapter } from "./adapter.js";