feat: Added OpenRouter LLMProvider and setup bootstrapping

packages/llm/src/config.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 
 const LLMConfigSchema = z.object({
   GOOGLE_API_KEY: z.string().optional(),
+  OPENROUTER_API_KEY: z.string().optional(),
 });
 
 export const llmConfig = LLMConfigSchema.parse(process.env);

packages/llm/src/index.ts

@@ -2,4 +2,5 @@ export * from "./llm.js";
 export * from "./config.js";
 export * from "./providers/google-genai.js";
 export * from "./providers/mock.js";
+export * from "./providers/openrouter.js";
 export * from "./provider-manager.js";

packages/llm/src/providers/openrouter.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { ChatOpenRouter } from "@langchain/openrouter";
+import { ILLMProvider, LLMRequest, LLMResponse, LLMCallRecord } from "../llm.js";
+import { llmConfig } from "../config.js";
+import { ProviderManager } from "../provider-manager.js";
+
+export class OpenRouterProvider implements ILLMProvider {
+  providerName = "OpenRouter";
+  private model: ChatOpenRouter;
+  lastCalls: LLMCallRecord[] = [];
+
+  constructor(apiKey?: string, modelName?: string) {
+    let key = apiKey;
+    let model = modelName;
+
+    if (!key) {
+      const active = ProviderManager.getActive();
+      if (active) {
+        key = active.apiKey;
+        if (!model) {
+          model = active.modelName;
+        }
+      }
+    }
+
+    if (!key) {
+      key = llmConfig.OPENROUTER_API_KEY;
+    }
+
+    if (!key) {
+      throw new Error("OPENROUTER_API_KEY is required to initialize OpenRouterProvider");
+    }
+
+    this.model = new ChatOpenRouter({
+      apiKey: key,
+      model: model || "google/gemini-2.5-flash",
+    });
+  }
+
+  async generateStructuredResponse<T extends z.ZodTypeAny>(
+    request: LLMRequest<T>,
+  ): Promise<LLMResponse<z.infer<T>>> {
+    const structuredModel = this.model.withStructuredOutput(request.schema, { includeRaw: true });
+    const result = (await structuredModel.invoke([
+      { role: "system", content: request.systemPrompt },
+      { role: "user", content: request.userContext },
+    ])) as unknown as {
+      parsed?: z.infer<T>;
+      raw?: {
+        usage_metadata?: {
+          input_tokens?: number;
+          output_tokens?: number;
+          total_tokens?: number;
+        };
+      };
+    };
+
+    const parsed = result?.parsed;
+    const raw = result?.raw;
+
+    const usage = raw?.usage_metadata ? {
+      inputTokens: raw.usage_metadata.input_tokens || 0,
+      outputTokens: raw.usage_metadata.output_tokens || 0,
+      totalTokens: raw.usage_metadata.total_tokens || 0,
+    } : undefined;
+
+    this.lastCalls.push({
+      systemPrompt: request.systemPrompt,
+      userContext: request.userContext,
+      usage,
+    });
+
+    return { success: true, data: parsed, usage };
+  }
+}

packages/llm/tests/openrouter.test.ts

@@ -0,0 +1,107 @@
+import { describe, test, expect, vi } from "vitest";
+import { z } from "zod";
+import { OpenRouterProvider } from "../src/providers/openrouter.js";
+import { llmConfig } from "../src/config.js";
+
+// Mock the ChatOpenRouter class
+vi.mock("@langchain/openrouter", () => {
+  return {
+    ChatOpenRouter: class {
+      config: unknown;
+      constructor(config: unknown) {
+        this.config = config;
+      }
+      withStructuredOutput = vi.fn().mockImplementation(() => {
+        return {
+          invoke: vi.fn().mockImplementation(async () => {
+            // Return a mock output that matches the includeRaw: true structure
+            return {
+              parsed: {
+                name: "mocked response",
+                success: true,
+              },
+              raw: {
+                usage_metadata: {
+                  input_tokens: 10,
+                  output_tokens: 5,
+                  total_tokens: 15,
+                },
+              },
+            };
+          }),
+        };
+      });
+    },
+  };
+});
+
+describe("OpenRouterProvider Unit Tests (Tier 1)", () => {
+  test("initializes successfully with a provided apiKey", () => {
+    const provider = new OpenRouterProvider("dummy-key");
+    expect(provider.providerName).toBe("OpenRouter");
+  });
+
+  test("initializes successfully with apiKey from config", () => {
+    // Save current config
+    const originalKey = llmConfig.OPENROUTER_API_KEY;
+    llmConfig.OPENROUTER_API_KEY = "env-dummy-key";
+    
+    try {
+      const provider = new OpenRouterProvider();
+      expect(provider.providerName).toBe("OpenRouter");
+    } finally {
+      llmConfig.OPENROUTER_API_KEY = originalKey;
+    }
+  });
+
+  test("throws error if no API key is provided or in config", () => {
+    // Save current config
+    const originalKey = llmConfig.OPENROUTER_API_KEY;
+    llmConfig.OPENROUTER_API_KEY = undefined;
+
+    try {
+      expect(() => new OpenRouterProvider()).toThrow(
+        "OPENROUTER_API_KEY is required to initialize OpenRouterProvider"
+      );
+    } finally {
+      llmConfig.OPENROUTER_API_KEY = originalKey;
+    }
+  });
+
+  test("generateStructuredResponse invokes the model with structured output, records usage and updates lastCalls", async () => {
+    const provider = new OpenRouterProvider("dummy-key");
+    const TestSchema = z.object({
+      name: z.string(),
+      success: z.boolean(),
+    });
+
+    const response = await provider.generateStructuredResponse({
+      systemPrompt: "system prompt",
+      userContext: "user context",
+      schema: TestSchema,
+    });
+
+    expect(response.success).toBe(true);
+    expect(response.data).toEqual({
+      name: "mocked response",
+      success: true,
+    });
+
+    expect(response.usage).toEqual({
+      inputTokens: 10,
+      outputTokens: 5,
+      totalTokens: 15,
+    });
+
+    expect(provider.lastCalls.length).toBe(1);
+    expect(provider.lastCalls[0]).toEqual({
+      systemPrompt: "system prompt",
+      userContext: "user context",
+      usage: {
+        inputTokens: 10,
+        outputTokens: 5,
+        totalTokens: 15,
+      },
+    });
+  });
+});