@neutrome/open-ai-router 0.1.0

package/src/router/index.ts

@@ -0,0 +1,33 @@
+export { createRouterRuntime } from "./runtime.ts";
+export {
+  createFetchProviderInvoker,
+  createRouterExecutionRuntime,
+  handleChatCompletions,
+  handleResponses,
+  resolveRequestTarget,
+  RouterError,
+  ProviderHttpError,
+} from "./execute.ts";
+export { listConfiguredModels, resolveInvocationTarget, resolveInvocationTargets } from "./resolve.ts";
+export type {
+  AuthConfig,
+  ExecutorNamespaceConfig,
+  ExecutorRouteConfig,
+  ProviderApiStyle,
+  ProviderTargetConfig,
+  RouterConfig,
+} from "./config.ts";
+export type {
+  CreateRouterOptions,
+  ExecutorRouteRuntime,
+  ExecutorRuntime,
+  ProviderRuntime,
+  RouterRuntime,
+} from "./runtime.ts";
+export type {
+  HandleChatCompletionsOptions,
+  HandleResponsesOptions,
+  RouterExecutionOptions,
+  UsageReport,
+} from "./execute.ts";
+export type { ResolvedTarget } from "./resolve.ts";

package/src/router/resolve.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it } from "vitest";
+import { createRouterRuntime } from "./runtime.ts";
+import { listConfiguredModels, resolveInvocationTarget, resolveInvocationTargets } from "./resolve.ts";
+
+describe("router resolution", () => {
+  it("resolves executor-backed aliases before provider-backed models", () => {
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            exports: ["gemma-*"],
+            catalog: ["gemma-4-31b-it"],
+          },
+        },
+        executors: {
+          enei: {
+            exports: ["enei-*"],
+            models: {
+              "enei-1": { executor: "enei-1" },
+              "enei-1-pro": { executor: "enei-1-pro", transforms: ["reasoning:high"] },
+            },
+          },
+        },
+      },
+    });
+
+    const resolved = resolveInvocationTarget(runtime, "enei-1+slwin:8");
+    expect(resolved.source).toBe("executor");
+    expect(resolved.namespace).toBe("enei");
+    expect(resolved.target).toEqual({
+      kind: "executor",
+      executor: "enei-1",
+      alias: "enei-1",
+      transforms: ["slwin:8"],
+    });
+  });
+
+  it("resolves qualified provider models and preserves suffix transforms", () => {
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            exports: ["google/*"],
+            catalog: ["google/gemma-4-31b-it"],
+          },
+        },
+        executors: {},
+      },
+      knownSuffixes: ["slwin", "kvtools"],
+    });
+
+    const resolved = resolveInvocationTarget(runtime, "openrouter/google/gemma-4-31b-it+kvtools");
+    expect(resolved.source).toBe("provider");
+    expect(resolved.target).toEqual({
+      kind: "provider",
+      provider: "openrouter",
+      model: "google/gemma-4-31b-it",
+      transforms: ["kvtools"],
+    });
+  });
+
+  it("resolves namespace model routes that alias provider targets", () => {
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            exports: ["openai/gpt-4.1-mini"],
+            catalog: ["openai/gpt-4.1-mini"],
+          },
+        },
+        executors: {
+          semantyka: {
+            exports: ["enei-*"],
+            models: {
+              "enei-1": { provider: "openrouter", model: "openai/gpt-4.1-mini" },
+            },
+          },
+        },
+      },
+    });
+
+    const resolved = resolveInvocationTarget(runtime, "semantyka/enei-1");
+    expect(resolved.source).toBe("provider");
+    expect(resolved.namespace).toBe("semantyka");
+    expect(resolved.target).toEqual({
+      kind: "provider",
+      provider: "openrouter",
+      model: "openai/gpt-4.1-mini",
+      transforms: [],
+    });
+  });
+
+  it("lists configured executor and provider models as qualified IDs", () => {
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            exports: ["google/*", "openai/*"],
+            catalog: ["google/gemma-4-31b-it", "openai/gpt-4o", "anthropic/claude-sonnet-4"],
+          },
+        },
+        executors: {
+          enei: {
+            exports: ["enei-*"],
+            models: {
+              "enei-1": { executor: "enei-1" },
+              "enei-1-pro": { executor: "enei-1-pro" },
+            },
+          },
+        },
+      },
+    });
+
+    expect(listConfiguredModels(runtime)).toEqual([
+      "enei/enei-1",
+      "enei/enei-1-pro",
+      "openrouter/google/gemma-4-31b-it",
+      "openrouter/openai/gpt-4o",
+    ]);
+  });
+
+  it("returns multiple candidates for unqualified provider matches", () => {
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            exports: ["gpt-4o"],
+            no_prefix: true,
+          },
+          backup: {
+            api_base_url: "https://backup.example/v1",
+            style: "chat-completions",
+            exports: ["gpt-4o"],
+            no_prefix: true,
+          },
+        },
+        executors: {},
+      },
+    });
+
+    const resolved = resolveInvocationTargets(runtime, "gpt-4o");
+    expect(resolved).toHaveLength(2);
+    expect(resolved.map((item) => item.namespace)).toEqual(["openrouter", "backup"]);
+  });
+});

package/src/router/resolve.ts

@@ -0,0 +1,171 @@
+import type { ExecutionTarget } from "@neutrome/lil-engine";
+import { parseModelSyntax, type ModelSuffixSpec } from "../util/model-syntax.ts";
+import type { RouterRuntime } from "./runtime.ts";
+
+export type ResolvedTarget = {
+  requestedModel: string;
+  target: ExecutionTarget;
+  suffixes: ModelSuffixSpec[];
+  namespace: string;
+  source: "provider" | "executor";
+};
+
+export function resolveInvocationTarget(
+  runtime: RouterRuntime,
+  requestedModel: string,
+): ResolvedTarget {
+  const candidates = resolveInvocationTargets(runtime, requestedModel);
+  if (candidates.length === 0) {
+    throw new Error(
+      `The model \`${requestedModel}\` does not exist or you do not have access to it.`,
+    );
+  }
+  return candidates[0]!;
+}
+
+export function resolveInvocationTargets(
+  runtime: RouterRuntime,
+  requestedModel: string,
+): ResolvedTarget[] {
+  const parsed = parseModelSyntax(requestedModel, runtime.knownSuffixes);
+  const qualified = splitQualified(parsed.baseModel);
+  if (qualified) {
+    return resolveQualified(runtime, requestedModel, qualified.namespace, qualified.model, parsed.suffixes);
+  }
+
+  const matches: ResolvedTarget[] = [];
+  for (const namespace of runtime.executorOrder) {
+    const executor = runtime.executors.get(namespace)!;
+    const route = executor.routes.get(parsed.baseModel);
+    if (route && executor.exportsMatcher(parsed.baseModel)) {
+      matches.push({
+        requestedModel,
+        namespace,
+        source: route.target.kind,
+        suffixes: parsed.suffixes,
+        target: withSuffixTransforms(route.target, parsed.suffixes),
+      });
+    }
+  }
+
+  for (const namespace of runtime.providerOrder) {
+    const provider = runtime.providers.get(namespace)!;
+    if (!provider.noPrefix) continue;
+    if (provider.exportsMatcher(parsed.baseModel)) {
+      matches.push({
+        requestedModel,
+        namespace,
+        source: "provider",
+        suffixes: parsed.suffixes,
+        target: {
+          kind: "provider",
+          provider: namespace,
+          model: parsed.baseModel,
+          transforms: parsed.suffixes.map((suffix) => suffix.raw),
+        },
+      });
+    }
+  }
+
+  return matches;
+}
+
+export function listConfiguredModels(runtime: RouterRuntime): string[] {
+  const models: string[] = [];
+  const seen = new Set<string>();
+
+  for (const namespace of runtime.executorOrder) {
+    const executor = runtime.executors.get(namespace)!;
+    for (const alias of executor.routes.keys()) {
+      if (executor.exportsMatcher(alias)) {
+        models.push(`${namespace}/${alias}`);
+      }
+    }
+  }
+
+  for (const namespace of runtime.providerOrder) {
+    const provider = runtime.providers.get(namespace)!;
+    for (const model of provider.catalog) {
+      if (provider.exportsMatcher(model)) {
+        models.push(`${namespace}/${model}`);
+        if (provider.noPrefix && !seen.has(model)) {
+          seen.add(model);
+          models.push(model);
+        }
+      }
+    }
+  }
+
+  return models;
+}
+
+function resolveQualified(
+  runtime: RouterRuntime,
+  requestedModel: string,
+  namespace: string,
+  model: string,
+  suffixes: ModelSuffixSpec[],
+): ResolvedTarget[] {
+  const provider = runtime.providers.get(namespace);
+  const executor = runtime.executors.get(namespace);
+
+  if (provider && executor) {
+    throw new Error(`Ambiguous namespace \`${namespace}\`: both provider and executor are registered`);
+  }
+
+  if (executor) {
+    const route = executor.routes.get(model);
+    if (!route || !executor.exportsMatcher(model)) {
+      return [];
+    }
+    return [{
+      requestedModel,
+      namespace,
+      source: route.target.kind,
+      suffixes,
+      target: withSuffixTransforms(route.target, suffixes),
+    }];
+  }
+
+  if (provider) {
+    if (!provider.exportsMatcher(model)) {
+      return [];
+    }
+    return [{
+      requestedModel,
+      namespace,
+      source: "provider",
+      suffixes,
+      target: {
+        kind: "provider",
+        provider: namespace,
+        model,
+        transforms: suffixes.map((suffix) => suffix.raw),
+      },
+    }];
+  }
+
+  return [];
+}
+
+function withSuffixTransforms(
+  target: ExecutionTarget,
+  suffixes: ModelSuffixSpec[],
+): ExecutionTarget {
+  return {
+    ...target,
+    transforms: [...(target.transforms ?? []), ...suffixes.map((suffix) => suffix.raw)],
+  };
+}
+
+function splitQualified(model: string): { namespace: string; model: string } | null {
+  const index = model.indexOf("/");
+  if (index <= 0) {
+    return null;
+  }
+
+  return {
+    namespace: model.slice(0, index).toLowerCase(),
+    model: model.slice(index + 1),
+  };
+}

package/src/router/runtime.ts

@@ -0,0 +1,146 @@
+import type { ExecutionTarget } from "@neutrome/lil-engine";
+import type { AuthDriver } from "../auth/types.ts";
+import { buildAuthChain } from "../auth/registry.ts";
+import { createExportsMatcher } from "../util/glob.ts";
+import type {
+  ExecutorNamespaceConfig,
+  ExecutorRouteConfig,
+  ProviderTargetConfig,
+  RouterConfig,
+} from "./config.ts";
+
+export type ProviderRuntime = {
+  name: string;
+  style: ProviderTargetConfig["style"];
+  apiBaseUrl: string;
+  endpointPath: string;
+  allowAnonymous: boolean;
+  noPrefix: boolean;
+  headers: Readonly<Record<string, string>>;
+  exportsMatcher: (model: string) => boolean;
+  catalog: readonly string[];
+};
+
+export type ExecutorRouteRuntime = {
+  requestedAlias: string;
+  target: ExecutionTarget;
+  transforms: readonly string[];
+};
+
+export type ExecutorRuntime = {
+  name: string;
+  exportsMatcher: (model: string) => boolean;
+  routes: ReadonlyMap<string, ExecutorRouteRuntime>;
+};
+
+export type RouterRuntime = {
+  config: RouterConfig;
+  providers: ReadonlyMap<string, ProviderRuntime>;
+  providerOrder: readonly string[];
+  executors: ReadonlyMap<string, ExecutorRuntime>;
+  executorOrder: readonly string[];
+  authChain: readonly AuthDriver[];
+  knownSuffixes: ReadonlySet<string>;
+  fetchImpl: typeof fetch;
+};
+
+export type CreateRouterOptions = {
+  config: RouterConfig;
+  fetchImpl?: typeof fetch;
+  knownSuffixes?: string[];
+  authDrivers?: readonly AuthDriver[];
+};
+
+export function createRouterRuntime(options: CreateRouterOptions): RouterRuntime {
+  const providers = new Map<string, ProviderRuntime>();
+  const executors = new Map<string, ExecutorRuntime>();
+  const providerOrder: string[] = [];
+  const executorOrder: string[] = [];
+
+  for (const [name, config] of Object.entries(options.config.providers)) {
+    providerOrder.push(name);
+    providers.set(name, buildProviderRuntime(name, config));
+  }
+
+  for (const [name, config] of Object.entries(options.config.executors)) {
+    executorOrder.push(name);
+    executors.set(name, buildExecutorRuntime(name, config));
+  }
+
+  return {
+    config: options.config,
+    providers,
+    providerOrder,
+    executors,
+    executorOrder,
+    authChain: options.authDrivers ?? buildAuthChain(options.config.auth),
+    knownSuffixes: new Set(options.knownSuffixes ?? ["slwin", "kvtools"]),
+    fetchImpl: options.fetchImpl ?? globalThis.fetch.bind(globalThis),
+  };
+}
+
+function buildProviderRuntime(name: string, config: ProviderTargetConfig): ProviderRuntime {
+  return {
+    name,
+    style: config.style,
+    apiBaseUrl: config.api_base_url,
+    endpointPath: config.endpoint_path ?? defaultEndpointPath(config.style),
+    allowAnonymous: config.allow_anonymous ?? false,
+    noPrefix: config.no_prefix ?? false,
+    headers: config.headers ?? {},
+    exportsMatcher: createExportsMatcher(config.exports),
+    catalog: config.catalog ?? [],
+  };
+}
+
+function buildExecutorRuntime(name: string, config: ExecutorNamespaceConfig): ExecutorRuntime {
+  const routes = new Map<string, ExecutorRouteRuntime>();
+  for (const [alias, route] of Object.entries(config.models)) {
+    routes.set(alias, buildExecutorRoute(alias, route));
+  }
+
+  return {
+    name,
+    exportsMatcher: createExportsMatcher(config.exports),
+    routes,
+  };
+}
+
+function buildExecutorRoute(alias: string, route: ExecutorRouteConfig): ExecutorRouteRuntime {
+  if ("provider" in route) {
+    return {
+      requestedAlias: alias,
+      transforms: route.transforms ?? [],
+      target: {
+        kind: "provider",
+        provider: route.provider,
+        model: route.model,
+        transforms: route.transforms ?? [],
+      },
+    };
+  }
+
+  return {
+    requestedAlias: alias,
+    transforms: route.transforms ?? [],
+    target: {
+      kind: "executor",
+      executor: route.executor,
+      alias: route.alias ?? alias,
+      transforms: route.transforms ?? [],
+    },
+  };
+}
+
+function defaultEndpointPath(style: ProviderTargetConfig["style"]): string {
+  switch (style) {
+    case "chat-completions":
+      return "/chat/completions";
+    case "responses":
+      return "/responses";
+    case "anthropic-messages":
+      return "/v1/messages";
+    case "google-genai":
+      return "";
+  }
+}

package/src/util/glob.ts

@@ -0,0 +1,15 @@
+export function matchesGlob(value: string, pattern: string): boolean {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+  return regex.test(value);
+}
+
+export function createExportsMatcher(
+  patterns: readonly string[] | null | undefined,
+): (model: string) => boolean {
+  if (patterns === null) return () => true;
+  if (patterns === undefined) return () => true;
+  if (patterns.length === 0) return () => false;
+  return (value: string) =>
+    patterns.some((pattern) => matchesGlob(value, pattern));
+}

package/src/util/headers.ts

@@ -0,0 +1,27 @@
+const HOP_BY_HOP = new Set([
+  "connection",
+  "content-length",
+  "host",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+export function cloneForwardHeaders(source: Headers): Headers {
+  const headers = new Headers();
+  source.forEach((value, key) => {
+    if (!HOP_BY_HOP.has(key.toLowerCase())) headers.set(key, value);
+  });
+  return headers;
+}
+
+export function isSse(headers: Headers): boolean {
+  return (
+    headers.get("content-type")?.toLowerCase().includes("text/event-stream") ??
+    false
+  );
+}

package/src/util/model-syntax.ts

@@ -0,0 +1,26 @@
+export type ModelSuffixSpec = {
+  name: string;
+  args: string[];
+  raw: string;
+};
+
+export type ParsedModelSyntax = {
+  baseModel: string;
+  suffixes: ModelSuffixSpec[];
+};
+
+export function parseModelSyntax(
+  model: string,
+  knownSuffixes?: ReadonlySet<string>,
+): ParsedModelSyntax {
+  const [baseModel = "", ...suffixParts] = model.split("+");
+  const suffixes = suffixParts.filter(Boolean).map((part) => {
+    const [namePart = "", ...args] = part.split(":");
+    const name = decodeURIComponent(namePart).toLowerCase();
+    if (knownSuffixes && !knownSuffixes.has(name)) {
+      throw new Error(`Unknown model suffix: ${name}`);
+    }
+    return { name, args: args.map(decodeURIComponent), raw: part };
+  });
+  return { baseModel, suffixes };
+}

package/src/util/sse.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { eventDataLines, splitSseEvents } from "./sse.ts";
+
+describe("SSE parsing", () => {
+  it("removes only the optional separator after data:", () => {
+    expect(eventDataLines("data:  leading")).toEqual([" leading"]);
+    expect(eventDataLines("data:leading")).toEqual(["leading"]);
+  });
+
+  it("splits complete events without trimming payload whitespace", () => {
+    const split = splitSseEvents("data: one\n\ndata:  two\n\n");
+
+    expect(split.events).toHaveLength(2);
+    expect(eventDataLines(split.events[0]!)).toEqual(["one"]);
+    expect(eventDataLines(split.events[1]!)).toEqual([" two"]);
+    expect(split.remainder).toBe("");
+  });
+});

package/src/util/sse.ts

@@ -0,0 +1,23 @@
+export function splitSseEvents(buffer: string): {
+  events: string[];
+  remainder: string;
+} {
+  const normalized = buffer.replace(/\r\n/g, "\n");
+  const parts = normalized.split("\n\n");
+  const remainder = parts.pop() ?? "";
+  return { events: parts, remainder };
+}
+
+export function eventDataLines(event: string): string[] {
+  return event
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .filter((line) => line.startsWith("data:"))
+    .map((line) => {
+      let data = line.slice(5);
+      if (data.startsWith(" ")) {
+        data = data.slice(1);
+      }
+      return data;
+    });
+}

package/src/worker.ts

@@ -0,0 +1,42 @@
+import type { RouterConfig } from "./router/index.ts";
+import { createApp } from "./example.ts";
+
+const config: RouterConfig = {
+  trace: true,
+  auth: {
+    order: ["proxy", "env"],
+    proxy: {
+      headers: ["authorization", "x-openairouter-token"],
+    },
+  },
+  providers: {
+    openrouter: {
+      api_base_url: "https://openrouter.ai/api/v1",
+      style: "chat-completions",
+      allow_anonymous: false,
+      exports: ["*:free"],
+    },
+  },
+  executors: {},
+};
+
+let appPromise: Promise<ReturnType<typeof createApp>> | undefined;
+
+async function getApp() {
+  return createApp({ config });
+}
+
+export default {
+  async fetch(
+    request: Request,
+    env: Record<string, unknown>,
+    ctx: ExecutionContext,
+  ): Promise<Response> {
+    appPromise ??= getApp().catch((error) => {
+      appPromise = undefined;
+      throw error;
+    });
+    const app = await appPromise;
+    return app.fetch(request, env, ctx);
+  },
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["node", "./worker-configuration.d.ts", "vitest/globals"],
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts"],
+  "exclude": ["test", "dist", "node_modules"],
+}

package/vitest.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({});