@neutrome/open-ai-router 0.1.0

package/README.md

@@ -0,0 +1,25 @@
+# `@neutrome/open-ai-router`
+
+Deployable router app and reusable router/runtime library surface built on `lil-core` + `lil-exec`.
+
+```ts
+import { createApp, createRouterRuntime, type RouterConfig } from "@neutrome/open-ai-router";
+```
+
+Primary runtime model:
+
+- client JSON/SSE -> `lil-core` IR
+- target resolution -> `lil-exec`
+- provider transport -> router host
+
+Development commands:
+
+```bash
+pnpm --filter @neutrome/open-ai-router test
+pnpm --filter @neutrome/open-ai-router typecheck
+```
+
+Notes:
+
+- `RouterConfig` is the canonical router config surface.
+- `/v1/models` lists configured executor aliases plus provider `catalog` entries.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@neutrome/open-ai-router",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "cf-typegen": "wrangler types",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "wrangler dev",
+    "preview": "wrangler preview",
+    "deploy": "wrangler deploy"
+  },
+  "dependencies": {
+    "@neutrome/lil-engine": "0.1.0",
+    "hono": "^4.12.18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6",
+    "wrangler": "^4.91.0"
+  }
+}

package/src/app/cors.ts

@@ -0,0 +1,8 @@
+import { cors as honoCors } from "hono/cors";
+
+export const cors = () =>
+  honoCors({
+    origin: "*",
+    allowMethods: ["GET", "POST", "OPTIONS"],
+    allowHeaders: ["Content-Type", "Authorization", "X-OpenAIRouter-Token"],
+  });

package/src/app/handlers.ts

@@ -0,0 +1,192 @@
+import type { Context } from "hono";
+import type { Executor, ProgramTransform } from "@neutrome/lil-engine";
+import type { RequestContext } from "../auth/types.ts";
+import {
+  handleChatCompletions,
+  handleResponses,
+  listConfiguredModels,
+  type RouterExecutionOptions,
+  type RouterRuntime,
+} from "../router/index.ts";
+
+type OpenAiModel = {
+  id: string;
+  object: "model";
+  created: number;
+  owned_by: string;
+};
+
+export type ChatCompletionsHandlerOptions = RouterExecutionOptions & {
+  executors?: Readonly<Record<string, Executor>>;
+  transforms?: Readonly<Record<string, ProgramTransform>>;
+};
+
+export type ResponsesHandlerOptions = ChatCompletionsHandlerOptions;
+
+export function listModelsHandler(runtime: RouterRuntime) {
+  return async (c: Context) => {
+    const modelIds = await listAvailableModels(runtime);
+    const models: OpenAiModel[] = modelIds.map((id) => ({
+      id,
+      object: "model",
+      created: 0,
+      owned_by: ownerFromModelId(id),
+    }));
+    return c.json({ object: "list", data: models });
+  };
+}
+
+async function listAvailableModels(runtime: RouterRuntime): Promise<string[]> {
+  const seen = new Set<string>();
+  const models: string[] = [];
+
+  for (const id of listConfiguredModels(runtime)) {
+    addModel(id);
+  }
+
+  await Promise.all(runtime.providerOrder.map(async (namespace) => {
+    const provider = runtime.providers.get(namespace);
+    if (!provider || provider.catalog.length > 0) {
+      return;
+    }
+
+    for (const model of await fetchProviderCatalog(runtime, provider.apiBaseUrl)) {
+      if (provider.exportsMatcher(model)) {
+        addModel(`${namespace}/${model}`);
+      }
+    }
+  }));
+
+  return models;
+
+  function addModel(id: string): void {
+    if (seen.has(id)) {
+      return;
+    }
+    seen.add(id);
+    models.push(id);
+  }
+}
+
+async function fetchProviderCatalog(runtime: RouterRuntime, apiBaseUrl: string): Promise<string[]> {
+  try {
+    const response = await runtime.fetchImpl(`${apiBaseUrl}/models`, {
+      method: "GET",
+      headers: { accept: "application/json" },
+    });
+    if (!response.ok) {
+      return [];
+    }
+
+    const raw = await response.json() as { data?: unknown };
+    const data = raw.data;
+    if (!Array.isArray(data)) {
+      return [];
+    }
+
+    return data
+      .map((model) => (model as { id?: unknown } | null | undefined)?.id)
+      .filter((id): id is string => typeof id === "string");
+  } catch {
+    return [];
+  }
+}
+
+export function chatCompletionsHandler(
+  runtime: RouterRuntime,
+  options: ChatCompletionsHandlerOptions = {},
+) {
+  return async (c: Context) => {
+    const ctx = createRequestContext(c);
+    collectIncomingAuth(ctx, runtime);
+    const handlerOptions = {
+      runtime,
+      ctx,
+    } as Parameters<typeof handleChatCompletions>[0];
+
+    if (options.executors) {
+      handlerOptions.executors = options.executors;
+    }
+    if (options.resolveExecutor) {
+      handlerOptions.resolveExecutor = options.resolveExecutor;
+    }
+    if (options.transforms) {
+      handlerOptions.transforms = options.transforms;
+    }
+    if (options.observe) {
+      handlerOptions.observe = options.observe;
+    }
+    if (options.requestIdFactory) {
+      handlerOptions.requestIdFactory = options.requestIdFactory;
+    }
+    if (options.executionIdFactory) {
+      handlerOptions.executionIdFactory = options.executionIdFactory;
+    }
+    if (options.upstreamTimeoutMs !== undefined) {
+      handlerOptions.upstreamTimeoutMs = options.upstreamTimeoutMs;
+    }
+
+    return handleChatCompletions(handlerOptions);
+  };
+}
+
+export function responsesHandler(
+  runtime: RouterRuntime,
+  options: ResponsesHandlerOptions = {},
+) {
+  return async (c: Context) => {
+    const ctx = createRequestContext(c);
+    collectIncomingAuth(ctx, runtime);
+    const handlerOptions = {
+      runtime,
+      ctx,
+    } as Parameters<typeof handleResponses>[0];
+
+    if (options.executors) {
+      handlerOptions.executors = options.executors;
+    }
+    if (options.resolveExecutor) {
+      handlerOptions.resolveExecutor = options.resolveExecutor;
+    }
+    if (options.transforms) {
+      handlerOptions.transforms = options.transforms;
+    }
+    if (options.observe) {
+      handlerOptions.observe = options.observe;
+    }
+    if (options.requestIdFactory) {
+      handlerOptions.requestIdFactory = options.requestIdFactory;
+    }
+    if (options.executionIdFactory) {
+      handlerOptions.executionIdFactory = options.executionIdFactory;
+    }
+    if (options.upstreamTimeoutMs !== undefined) {
+      handlerOptions.upstreamTimeoutMs = options.upstreamTimeoutMs;
+    }
+
+    return handleResponses(handlerOptions);
+  };
+}
+
+function createRequestContext(c: Context): RequestContext {
+  return {
+    request: c.req.raw,
+    incomingAuth: new Map(),
+    env: (c.env ?? {}) as Record<string, unknown>,
+    state: new Map(),
+  };
+}
+
+function collectIncomingAuth(ctx: RequestContext, runtime: RouterRuntime): void {
+  for (const driver of runtime.authChain) {
+    driver.collectIncoming?.(ctx);
+  }
+}
+
+function ownerFromModelId(id: string): string {
+  const slash = id.indexOf("/");
+  if (slash <= 0) {
+    return "unknown";
+  }
+  return id.slice(0, slash);
+}

package/src/app/health.ts

@@ -0,0 +1,5 @@
+import type { Context } from "hono";
+
+export function healthHandler() {
+  return (c: Context) => c.text("OK");
+}

package/src/auth/config.ts

@@ -0,0 +1,10 @@
+export type AuthConfigShape = {
+  order?: string[];
+  proxy?: {
+    headers?: string[];
+  };
+  env?: {
+    suffix?: string;
+    prefix?: string;
+  };
+};

package/src/auth/env.ts

@@ -0,0 +1,16 @@
+import type { AuthDriver, TargetAuthContext, AuthResult } from "./types.ts";
+
+export function envAuthDriver(suffix = "_API_KEY", prefix = ""): AuthDriver {
+  return {
+    name: "env",
+    collectTarget(ctx: TargetAuthContext): AuthResult | null {
+      const key =
+        ctx.env[`${prefix}${ctx.providerName.toUpperCase()}${suffix}`];
+      if (typeof key !== "string" || !key) return null;
+      return {
+        headers: { authorization: `Bearer ${key}` },
+        source: "env",
+      };
+    },
+  };
+}

package/src/auth/proxy.ts

@@ -0,0 +1,21 @@
+import type { AuthDriver, RequestContext, TargetAuthContext, AuthResult } from "./types.ts";
+
+export function proxyAuthDriver(headers: string[]): AuthDriver {
+  return {
+    name: "proxy",
+    collectIncoming(ctx: RequestContext) {
+      for (const name of headers) {
+        const value = ctx.request.headers.get(name);
+        if (value) ctx.incomingAuth.set(name.toLowerCase(), value);
+      }
+    },
+    collectTarget(ctx: TargetAuthContext): AuthResult | null {
+      const authHeader = ctx.incomingAuth.get("authorization");
+      if (!authHeader) return null;
+      return {
+        headers: { authorization: authHeader },
+        source: "proxy",
+      };
+    },
+  };
+}

package/src/auth/registry.ts

@@ -0,0 +1,25 @@
+import type { AuthConfigShape } from "./config.ts";
+import type { AuthDriver } from "./types.ts";
+import { proxyAuthDriver } from "./proxy.ts";
+import { envAuthDriver } from "./env.ts";
+
+export function buildAuthChain(config?: AuthConfigShape): AuthDriver[] {
+  if (!config) return [proxyAuthDriver(["authorization"]), envAuthDriver()];
+  const order = config.order ?? ["proxy", "env"];
+  const drivers: AuthDriver[] = [];
+  for (const name of order) {
+    switch (name) {
+      case "proxy":
+        drivers.push(
+          proxyAuthDriver(config.proxy?.headers ?? ["authorization"]),
+        );
+        break;
+      case "env":
+        drivers.push(
+          envAuthDriver(config.env?.suffix ?? "_API_KEY", config.env?.prefix),
+        );
+        break;
+    }
+  }
+  return drivers;
+}

package/src/auth/types.ts

@@ -0,0 +1,23 @@
+export type AuthResult = {
+  headers: HeadersInit;
+  source: string;
+};
+
+export type RequestContext = {
+  request: Request;
+  incomingAuth: Map<string, string>;
+  env: Record<string, unknown>;
+  state?: Map<string, unknown>;
+};
+
+export type TargetAuthContext = RequestContext & {
+  providerName: string;
+};
+
+export interface AuthDriver {
+  name: string;
+  collectIncoming?(ctx: RequestContext): void;
+  collectTarget(
+    ctx: TargetAuthContext,
+  ): Promise<AuthResult | null> | AuthResult | null;
+}

package/src/example.test.ts

@@ -0,0 +1,229 @@
+import { describe, expect, it, vi } from "vitest";
+import { createApp } from "./example.ts";
+
+const decoder = new TextDecoder();
+
+describe("open-ai-router createApp", () => {
+  it("lists configured provider catalog entries and executor aliases", async () => {
+    const app = createApp({
+      config: {
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            exports: ["gpt-4o"],
+            catalog: ["gpt-4o"],
+          },
+        },
+        executors: {
+          semantyka: {
+            exports: ["enei-*"],
+            models: {
+              "enei-1": { executor: "enei-1" },
+            },
+          },
+        },
+      },
+    });
+
+    const response = await app.request("/v1/models");
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({
+      object: "list",
+      data: [
+        { id: "semantyka/enei-1", object: "model", created: 0, owned_by: "semantyka" },
+        { id: "openrouter/gpt-4o", object: "model", created: 0, owned_by: "openrouter" },
+      ],
+    });
+  });
+
+  it("lists provider /models entries when provider catalog is not configured", async () => {
+    const app = createApp({
+      config: {
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            exports: ["*:free"],
+          },
+        },
+        executors: {},
+      },
+      fetchImpl: vi.fn(async () =>
+        new Response(
+          JSON.stringify({
+            data: [
+              { id: "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free" },
+              { id: "openai/gpt-4.1-mini" },
+            ],
+          }),
+          {
+            headers: { "content-type": "application/json; charset=utf-8" },
+          },
+        )
+      ),
+    });
+
+    const response = await app.request("/v1/models");
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({
+      object: "list",
+      data: [
+        {
+          id: "openrouter/nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
+          object: "model",
+          created: 0,
+          owned_by: "openrouter",
+        },
+      ],
+    });
+  });
+
+  it("serves provider-backed chat completions through the app surface", async () => {
+    let capturedBody: Record<string, unknown> | null = null;
+
+    const app = createApp({
+      config: {
+        auth: {
+          order: ["proxy"],
+          proxy: {
+            headers: ["authorization"],
+          },
+        },
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            exports: ["gpt-4o"],
+            allow_anonymous: false,
+            no_prefix: true,
+          },
+        },
+        executors: {},
+      },
+      fetchImpl: vi.fn(async (_input, init) => {
+        capturedBody = JSON.parse(decoder.decode(new Uint8Array(init?.body as ArrayBuffer)));
+        return new Response(
+          JSON.stringify({
+            id: "resp_1",
+            model: "gpt-4o",
+            choices: [
+              {
+                index: 0,
+                message: { role: "assistant", content: "hello" },
+                finish_reason: "stop",
+              },
+            ],
+          }),
+          {
+            headers: {
+              "content-type": "application/json; charset=utf-8",
+            },
+          },
+        );
+      }),
+    });
+
+    const response = await app.request("/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-key",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        model: "gpt-4o",
+        messages: [{ role: "user", content: "hi" }],
+      }),
+    });
+
+    expect(response.status).toBe(200);
+    expect(capturedBody).toEqual({
+      model: "gpt-4o",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    expect(response.headers.get("x-openairouter-provider-id")).toBe("openrouter");
+    expect(await response.json()).toEqual({
+      object: "chat.completion",
+      id: "resp_1",
+      model: "gpt-4o",
+      choices: [
+        {
+          index: 0,
+          message: { role: "assistant", content: "hello" },
+          finish_reason: "stop",
+        },
+      ],
+    });
+  });
+
+  it("serves responses through chat-completions provider transport", async () => {
+    let capturedBody: Record<string, unknown> | null = null;
+
+    const app = createApp({
+      config: {
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            allow_anonymous: true,
+            exports: ["gpt-4o"],
+            no_prefix: true,
+          },
+        },
+        executors: {},
+      },
+      fetchImpl: vi.fn(async (_input, init) => {
+        capturedBody = JSON.parse(decoder.decode(new Uint8Array(init?.body as ArrayBuffer)));
+        return new Response(
+          JSON.stringify({
+            id: "resp_2",
+            model: "gpt-4o",
+            choices: [
+              {
+                index: 0,
+                message: { role: "assistant", content: "hello" },
+                finish_reason: "stop",
+              },
+            ],
+          }),
+          {
+            headers: {
+              "content-type": "application/json; charset=utf-8",
+            },
+          },
+        );
+      }),
+    });
+
+    const response = await app.request("/v1/responses", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        model: "gpt-4o",
+        input: [{ role: "user", content: "hi" }],
+      }),
+    });
+
+    expect(response.status).toBe(200);
+    expect(capturedBody).toEqual({
+      model: "gpt-4o",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    expect(await response.json()).toEqual({
+      id: "resp_2",
+      model: "gpt-4o",
+      output: [
+        {
+          type: "message",
+          role: "assistant",
+          status: "completed",
+          content: [{ type: "output_text", text: "hello" }],
+        },
+      ],
+    });
+  });
+});

package/src/example.ts

@@ -0,0 +1,62 @@
+import { Hono } from "hono";
+import { cors } from "./app/cors.ts";
+import {
+  chatCompletionsHandler,
+  listModelsHandler,
+  responsesHandler,
+  type ChatCompletionsHandlerOptions,
+} from "./app/handlers.ts";
+import { healthHandler } from "./app/health.ts";
+import { createRouterRuntime, type CreateRouterOptions } from "./router/index.ts";
+
+export type CreateAppOptions = CreateRouterOptions & ChatCompletionsHandlerOptions;
+
+export function createApp(options: CreateAppOptions) {
+  const routerOptions = {
+    config: options.config,
+  } as CreateRouterOptions;
+
+  if (options.fetchImpl) {
+    routerOptions.fetchImpl = options.fetchImpl;
+  }
+  if (options.knownSuffixes) {
+    routerOptions.knownSuffixes = options.knownSuffixes;
+  }
+
+  const runtime = createRouterRuntime(routerOptions);
+  const app = new Hono();
+
+  const handlerOptions = {} as ChatCompletionsHandlerOptions;
+  if (options.executors) {
+    handlerOptions.executors = options.executors;
+  }
+  if (options.transforms) {
+    handlerOptions.transforms = options.transforms;
+  }
+  if (options.observe) {
+    handlerOptions.observe = options.observe;
+  }
+  if (options.requestIdFactory) {
+    handlerOptions.requestIdFactory = options.requestIdFactory;
+  }
+  if (options.executionIdFactory) {
+    handlerOptions.executionIdFactory = options.executionIdFactory;
+  }
+  if (options.upstreamTimeoutMs !== undefined) {
+    handlerOptions.upstreamTimeoutMs = options.upstreamTimeoutMs;
+  }
+
+  app.use("/v1/models", cors());
+  app.get("/v1/models", listModelsHandler(runtime));
+
+  app.use("/v1/chat/completions", cors());
+  app.post("/v1/chat/completions", chatCompletionsHandler(runtime, handlerOptions));
+
+  app.use("/v1/responses", cors());
+  app.post("/v1/responses", responsesHandler(runtime, handlerOptions));
+
+  app.get("/health", healthHandler());
+  app.all("*", (c) => c.text("Not Found", 404));
+
+  return app;
+}