Document OpenRouter as a supported LLM_BASE_URL provider

Send usage: { include: true } on every chat completion request (an
OpenRouter-specific extension - requires Usage Accounting enabled on
the OpenRouter account; other OpenAI-compatible providers generally
ignore unknown top-level request fields). When the response includes
OpenRouter's own usage.cost, forward it to Langfuse as
costDetails.total, so cost is the real per-request figure OpenRouter
billed rather than a guess from Langfuse's model price list (which
has no entry for proxied/aggregated OpenRouter model names anyway).

Verified: full suite (84/84) passing, tsc/eslint clean, docker
compose build succeeds. Per Langfuse's OpenRouter integration guide:
https://langfuse.com/integrations/gateways/openrouter

.env.example

@@ -4,7 +4,12 @@ JELLYFIN_API_KEY=
 JELLYFIN_USER_ID=
 TMDB_API_KEY=
 
-# LLM (disabled by default — works with Ollama, OpenAI, LM Studio, etc.)
+# LLM (disabled by default — any OpenAI-compatible endpoint: Ollama, OpenAI,
+# LM Studio, OpenRouter, etc.)
+# For OpenRouter specifically: LLM_BASE_URL=https://openrouter.ai/api/v1,
+# LLM_API_KEY=<your OpenRouter key>, LLM_MODEL=<an OpenRouter model slug>.
+# Enable "Usage Accounting" on the OpenRouter account to get real per-request
+# cost reported back to Langfuse instead of a price-list estimate.
 LLM_ENABLED=false
 LLM_BASE_URL=http://localhost:11434/v1
 LLM_API_KEY=

src/core/langfuse/LangfuseTracer.ts

@@ -73,6 +73,7 @@ export class LangfuseTracer extends Tracer {
             generation.update({
               output: output.output,
               usageDetails: toUsageDetails(output.usage) as Record<string, number> | undefined,
+              costDetails: output.usage?.cost !== undefined ? { total: output.usage.cost } : undefined,
               metadata: output.metadata,
             });
             generation.end();

src/core/llm/LlmClient.ts

@@ -1,4 +1,6 @@
 import OpenAI from 'openai';
+import type { ChatCompletionCreateParamsNonStreaming } from 'openai/resources/chat/completions';
+import type { CompletionUsage } from 'openai/resources/completions';
 
 export interface ChatMessage {
   role: 'system' | 'user' | 'assistant';
@@ -18,9 +20,23 @@ export interface ChatResult {
     completionTokens?: number;
     totalTokens?: number;
     cachedTokens?: number;
+    cost?: number;
   };
 }
 
+/**
+ * OpenRouter-specific request/response extensions, not part of OpenAI's
+ * official schema. `usage.include` asks OpenRouter to report its own real
+ * per-request cost (requires Usage Accounting enabled on the OpenRouter
+ * account); other OpenAI-compatible providers generally ignore unknown
+ * top-level request fields. See:
+ * https://langfuse.com/integrations/gateways/openrouter
+ */
+type OpenRouterChatCompletionCreateParams = ChatCompletionCreateParamsNonStreaming & {
+  usage?: { include: boolean };
+};
+type OpenRouterCompletionUsage = CompletionUsage & { cost?: number };
+
 export class LlmClient {
   private readonly client: OpenAI;
 
@@ -34,21 +50,25 @@ export class LlmClient {
       temperature: options.temperature,
       max_tokens: options.maxTokens,
       messages,
-    });
+      usage: { include: true },
+    } as OpenRouterChatCompletionCreateParams);
 
     const choice = response.choices[0];
     if (!choice) {
       throw new Error('LLM returned no choices');
     }
 
+    const usage = response.usage as OpenRouterCompletionUsage | undefined;
+
     return {
       content: choice.message?.content ?? '',
-      usage: response.usage
+      usage: usage
         ? {
-            promptTokens: response.usage.prompt_tokens,
-            completionTokens: response.usage.completion_tokens,
-            totalTokens: response.usage.total_tokens,
-            cachedTokens: response.usage.prompt_tokens_details?.cached_tokens,
+            promptTokens: usage.prompt_tokens,
+            completionTokens: usage.completion_tokens,
+            totalTokens: usage.total_tokens,
+            cachedTokens: usage.prompt_tokens_details?.cached_tokens,
+            cost: usage.cost,
           }
         : undefined,
     };

src/core/llm/Tracer.ts

@@ -12,6 +12,7 @@ export interface GenerationOutput {
     completionTokens?: number;
     totalTokens?: number;
     cachedTokens?: number;
+    cost?: number;
   };
   metadata?: Record<string, unknown>;
 }

test/core/langfuse/LangfuseTracer.test.ts

@@ -73,11 +73,26 @@ describe('LangfuseTracer', () => {
       expect.objectContaining({
         output: 'done',
         usageDetails: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+        costDetails: undefined,
       })
     );
     expect(generationEnd).toHaveBeenCalledTimes(1);
   });
 
+  it('forwards an explicit cost (e.g. from OpenRouter) as costDetails.total instead of relying on price-list lookup', () => {
+    const tracer = new LangfuseTracer({ publicKey: 'pk', secretKey: 'sk', baseUrl: 'http://lf' });
+    const handle = tracer.startTrace('my-pipeline');
+    const gen = handle.startGeneration({ name: 'step-1', model: 'openrouter/auto', input: ['hi'] });
+    gen.end({
+      output: 'done',
+      usage: { promptTokens: 10, completionTokens: 5, totalTokens: 15, cost: 0.00042 },
+    });
+
+    expect(generationUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({ costDetails: { total: 0.00042 } })
+    );
+  });
+
   it('maps cachedTokens to the OpenAI-native nested prompt_tokens_details.cached_tokens, not a mixed flat key', () => {
     const tracer = new LangfuseTracer({ publicKey: 'pk', secretKey: 'sk', baseUrl: 'http://lf' });
     const handle = tracer.startTrace('my-pipeline');

test/core/llm/LlmClient.test.ts

@@ -29,6 +29,24 @@ describe('LlmClient', () => {
       temperature: 0.7,
       max_tokens: undefined,
       messages: [{ role: 'user', content: 'hi' }],
+      usage: { include: true },
+    });
+  });
+
+  it('extracts OpenRouter cost from the response usage when present', async () => {
+    createMock.mockResolvedValue({
+      choices: [{ message: { content: 'hello' } }],
+      usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15, cost: 0.00042 },
+    });
+
+    const client = new LlmClient({ baseUrl: 'https://openrouter.ai/api/v1', apiKey: 'key' });
+    const result = await client.chat([{ role: 'user', content: 'hi' }], { model: 'openrouter/auto' });
+
+    expect(result.usage).toEqual({
+      promptTokens: 10,
+      completionTokens: 5,
+      totalTokens: 15,
+      cost: 0.00042,
     });
   });