genai-lite 0.7.0 → 0.7.2

package/dist/llm/clients/OpenRouterClientAdapter.d.ts

@@ -0,0 +1,103 @@
+import type { LLMResponse, LLMFailureResponse } from "../types";
+import type { ILLMClientAdapter, InternalLLMChatRequest } from "./types";
+/**
+ * Configuration options for OpenRouterClientAdapter
+ */
+export interface OpenRouterClientConfig {
+    /** Base URL of the OpenRouter API (default: https://openrouter.ai/api/v1) */
+    baseURL?: string;
+    /** Your app's URL for rankings attribution (optional) */
+    httpReferer?: string;
+    /** Your app's display name for rankings (optional) */
+    siteTitle?: string;
+}
+/**
+ * Client adapter for OpenRouter API integration
+ *
+ * OpenRouter is an API gateway that provides unified access to 100+ LLM models
+ * from various providers (OpenAI, Anthropic, Google, Meta, Mistral, etc.)
+ * through an OpenAI-compatible API.
+ *
+ * Key features:
+ * - Uses OpenAI-compatible API format
+ * - Single API key for all models
+ * - Model IDs use provider/model format (e.g., "openai/gpt-4", "anthropic/claude-3-opus")
+ * - Optional provider routing for controlling which underlying providers serve requests
+ * - App attribution via HTTP-Referer and X-Title headers
+ *
+ * @example
+ * ```typescript
+ * // Create adapter
+ * const adapter = new OpenRouterClientAdapter({
+ *   httpReferer: 'https://myapp.com',
+ *   siteTitle: 'My App'
+ * });
+ *
+ * // Use via LLMService
+ * const response = await service.sendMessage({
+ *   providerId: 'openrouter',
+ *   modelId: 'google/gemma-3-27b-it:free',
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * });
+ * ```
+ */
+export declare class OpenRouterClientAdapter implements ILLMClientAdapter {
+    private baseURL;
+    private httpReferer?;
+    private siteTitle?;
+    /**
+     * Creates a new OpenRouter client adapter
+     *
+     * @param config Optional configuration for the adapter
+     */
+    constructor(config?: OpenRouterClientConfig);
+    /**
+     * Sends a chat message to OpenRouter API
+     *
+     * @param request - The internal LLM request with applied settings
+     * @param apiKey - The OpenRouter API key
+     * @returns Promise resolving to success or failure response
+     */
+    sendMessage(request: InternalLLMChatRequest, apiKey: string): Promise<LLMResponse | LLMFailureResponse>;
+    /**
+     * Validates OpenRouter API key format
+     *
+     * OpenRouter API keys typically start with 'sk-or-' and have significant length.
+     *
+     * @param apiKey - The API key to validate
+     * @returns True if the key format appears valid
+     */
+    validateApiKey(apiKey: string): boolean;
+    /**
+     * Gets adapter information
+     */
+    getAdapterInfo(): {
+        providerId: "openrouter";
+        name: string;
+        version: string;
+        baseURL: string;
+    };
+    /**
+     * Formats messages for OpenAI-compatible API
+     *
+     * @param request - The internal LLM request
+     * @returns Formatted messages array
+     */
+    private formatMessages;
+    /**
+     * Creates a standardized success response from OpenRouter's response
+     *
+     * @param completion - Raw OpenAI-compatible completion response
+     * @param request - Original request for context
+     * @returns Standardized LLM response
+     */
+    private createSuccessResponse;
+    /**
+     * Creates a standardized error response from an error
+     *
+     * @param error - The error that occurred
+     * @param request - Original request for context
+     * @returns Standardized LLM failure response
+     */
+    private createErrorResponse;
+}

package/dist/llm/clients/OpenRouterClientAdapter.js

@@ -0,0 +1,285 @@
+"use strict";
+// AI Summary: Client adapter for OpenRouter API gateway using OpenAI-compatible API.
+// Provides unified access to 100+ LLM models from various providers through a single API.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenRouterClientAdapter = void 0;
+const openai_1 = __importDefault(require("openai"));
+const types_1 = require("./types");
+const errorUtils_1 = require("../../shared/adapters/errorUtils");
+const systemMessageUtils_1 = require("../../shared/adapters/systemMessageUtils");
+const defaultLogger_1 = require("../../logging/defaultLogger");
+const logger = (0, defaultLogger_1.createDefaultLogger)();
+/**
+ * Client adapter for OpenRouter API integration
+ *
+ * OpenRouter is an API gateway that provides unified access to 100+ LLM models
+ * from various providers (OpenAI, Anthropic, Google, Meta, Mistral, etc.)
+ * through an OpenAI-compatible API.
+ *
+ * Key features:
+ * - Uses OpenAI-compatible API format
+ * - Single API key for all models
+ * - Model IDs use provider/model format (e.g., "openai/gpt-4", "anthropic/claude-3-opus")
+ * - Optional provider routing for controlling which underlying providers serve requests
+ * - App attribution via HTTP-Referer and X-Title headers
+ *
+ * @example
+ * ```typescript
+ * // Create adapter
+ * const adapter = new OpenRouterClientAdapter({
+ *   httpReferer: 'https://myapp.com',
+ *   siteTitle: 'My App'
+ * });
+ *
+ * // Use via LLMService
+ * const response = await service.sendMessage({
+ *   providerId: 'openrouter',
+ *   modelId: 'google/gemma-3-27b-it:free',
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * });
+ * ```
+ */
+class OpenRouterClientAdapter {
+    /**
+     * Creates a new OpenRouter client adapter
+     *
+     * @param config Optional configuration for the adapter
+     */
+    constructor(config) {
+        this.baseURL = config?.baseURL || 'https://openrouter.ai/api/v1';
+        this.httpReferer = config?.httpReferer || process.env.OPENROUTER_HTTP_REFERER;
+        this.siteTitle = config?.siteTitle || process.env.OPENROUTER_SITE_TITLE;
+    }
+    /**
+     * Sends a chat message to OpenRouter API
+     *
+     * @param request - The internal LLM request with applied settings
+     * @param apiKey - The OpenRouter API key
+     * @returns Promise resolving to success or failure response
+     */
+    async sendMessage(request, apiKey) {
+        try {
+            // Initialize OpenAI client with OpenRouter base URL and custom headers
+            const openai = new openai_1.default({
+                apiKey,
+                baseURL: this.baseURL,
+                defaultHeaders: {
+                    ...(this.httpReferer && { 'HTTP-Referer': this.httpReferer }),
+                    ...(this.siteTitle && { 'X-Title': this.siteTitle }),
+                },
+            });
+            // Format messages for OpenAI-compatible API
+            const messages = this.formatMessages(request);
+            // Prepare API call parameters
+            const completionParams = {
+                model: request.modelId,
+                messages: messages,
+                temperature: request.settings.temperature,
+                max_tokens: request.settings.maxTokens,
+                top_p: request.settings.topP,
+                ...(request.settings.stopSequences.length > 0 && {
+                    stop: request.settings.stopSequences,
+                }),
+                ...(request.settings.frequencyPenalty !== 0 && {
+                    frequency_penalty: request.settings.frequencyPenalty,
+                }),
+                ...(request.settings.presencePenalty !== 0 && {
+                    presence_penalty: request.settings.presencePenalty,
+                }),
+            };
+            // Add OpenRouter-specific provider routing if configured
+            const providerSettings = request.settings.openRouterProvider;
+            if (providerSettings) {
+                const provider = {};
+                if (providerSettings.order) {
+                    provider.order = providerSettings.order;
+                }
+                if (providerSettings.ignore) {
+                    provider.ignore = providerSettings.ignore;
+                }
+                if (providerSettings.allow) {
+                    provider.allow = providerSettings.allow;
+                }
+                if (providerSettings.dataCollection) {
+                    provider.data_collection = providerSettings.dataCollection;
+                }
+                if (providerSettings.requireParameters !== undefined) {
+                    provider.require_parameters = providerSettings.requireParameters;
+                }
+                if (Object.keys(provider).length > 0) {
+                    completionParams.provider = provider;
+                }
+            }
+            logger.debug(`OpenRouter API parameters:`, {
+                baseURL: this.baseURL,
+                model: completionParams.model,
+                temperature: completionParams.temperature,
+                max_tokens: completionParams.max_tokens,
+                top_p: completionParams.top_p,
+                hasProviderRouting: !!completionParams.provider,
+            });
+            logger.info(`Making OpenRouter API call for model: ${request.modelId}`);
+            // Make the API call
+            const completion = await openai.chat.completions.create(completionParams);
+            // Type guard to ensure we have a non-streaming response
+            if ('id' in completion && 'choices' in completion) {
+                logger.info(`OpenRouter API call successful, response ID: ${completion.id}`);
+                return this.createSuccessResponse(completion, request);
+            }
+            else {
+                throw new Error('Unexpected streaming response from OpenRouter');
+            }
+        }
+        catch (error) {
+            logger.error("OpenRouter API error:", error);
+            return this.createErrorResponse(error, request);
+        }
+    }
+    /**
+     * Validates OpenRouter API key format
+     *
+     * OpenRouter API keys typically start with 'sk-or-' and have significant length.
+     *
+     * @param apiKey - The API key to validate
+     * @returns True if the key format appears valid
+     */
+    validateApiKey(apiKey) {
+        // OpenRouter keys start with 'sk-or-' (may include version like 'sk-or-v1-')
+        return apiKey.startsWith('sk-or-') && apiKey.length >= 40;
+    }
+    /**
+     * Gets adapter information
+     */
+    getAdapterInfo() {
+        return {
+            providerId: "openrouter",
+            name: "OpenRouter Client Adapter",
+            version: "1.0.0",
+            baseURL: this.baseURL,
+        };
+    }
+    /**
+     * Formats messages for OpenAI-compatible API
+     *
+     * @param request - The internal LLM request
+     * @returns Formatted messages array
+     */
+    formatMessages(request) {
+        const messages = [];
+        const inlineSystemMessages = [];
+        // Check if model supports system messages (default true for most OpenRouter models)
+        const supportsSystem = request.settings.supportsSystemMessage !== false;
+        // Add conversation messages (collecting system messages separately)
+        for (const message of request.messages) {
+            if (message.role === "system") {
+                // Collect inline system messages
+                inlineSystemMessages.push(message.content);
+            }
+            else if (message.role === "user") {
+                messages.push({
+                    role: "user",
+                    content: message.content,
+                });
+            }
+            else if (message.role === "assistant") {
+                messages.push({
+                    role: "assistant",
+                    content: message.content,
+                });
+            }
+        }
+        // Use shared utility to collect and combine system content
+        const { combinedSystemContent, useNativeSystemMessage } = (0, systemMessageUtils_1.collectSystemContent)(request.systemMessage, inlineSystemMessages, supportsSystem);
+        if (combinedSystemContent) {
+            if (useNativeSystemMessage) {
+                // Model supports system messages - add as system role at the start
+                messages.unshift({
+                    role: "system",
+                    content: combinedSystemContent,
+                });
+            }
+            else {
+                // Model doesn't support system messages - prepend to first user message
+                const simpleMessages = messages.map((m) => ({
+                    role: m.role,
+                    content: m.content,
+                }));
+                const modifiedIndex = (0, systemMessageUtils_1.prependSystemToFirstUserMessage)(simpleMessages, combinedSystemContent, request.settings.systemMessageFallback);
+                if (modifiedIndex !== -1) {
+                    messages[modifiedIndex].content = simpleMessages[modifiedIndex].content;
+                    logger.debug(`Model ${request.modelId} doesn't support system messages - prepended to first user message`);
+                }
+            }
+        }
+        return messages;
+    }
+    /**
+     * Creates a standardized success response from OpenRouter's response
+     *
+     * @param completion - Raw OpenAI-compatible completion response
+     * @param request - Original request for context
+     * @returns Standardized LLM response
+     */
+    createSuccessResponse(completion, request) {
+        const choice = completion.choices[0];
+        if (!choice || !choice.message) {
+            throw new Error("No valid choices in OpenRouter completion response");
+        }
+        return {
+            id: completion.id,
+            provider: request.providerId,
+            model: completion.model || request.modelId,
+            created: completion.created,
+            choices: completion.choices.map((c) => ({
+                message: {
+                    role: "assistant",
+                    content: c.message.content || "",
+                },
+                finish_reason: c.finish_reason,
+                index: c.index,
+            })),
+            usage: completion.usage
+                ? {
+                    prompt_tokens: completion.usage.prompt_tokens,
+                    completion_tokens: completion.usage.completion_tokens,
+                    total_tokens: completion.usage.total_tokens,
+                }
+                : undefined,
+            object: "chat.completion",
+        };
+    }
+    /**
+     * Creates a standardized error response from an error
+     *
+     * @param error - The error that occurred
+     * @param request - Original request for context
+     * @returns Standardized LLM failure response
+     */
+    createErrorResponse(error, request) {
+        // Use common error mapping
+        const mappedError = (0, errorUtils_1.getCommonMappedErrorDetails)(error);
+        // OpenRouter-specific error refinements
+        if (mappedError.status === 400) {
+            const errorMessage = (error?.message || '').toLowerCase();
+            if (errorMessage.includes('model') && (errorMessage.includes('not available') || errorMessage.includes('not found'))) {
+                mappedError.errorCode = types_1.ADAPTER_ERROR_CODES.MODEL_NOT_FOUND;
+            }
+        }
+        return {
+            provider: request.providerId,
+            model: request.modelId,
+            error: {
+                message: mappedError.errorMessage,
+                code: mappedError.errorCode,
+                type: mappedError.errorType,
+                ...(mappedError.status && { status: mappedError.status }),
+                providerError: error,
+            },
+            object: "error",
+        };
+    }
+}
+exports.OpenRouterClientAdapter = OpenRouterClientAdapter;

package/dist/llm/config.js

@@ -16,10 +16,10 @@ const OpenAIClientAdapter_1 = require("./clients/OpenAIClientAdapter");
 const AnthropicClientAdapter_1 = require("./clients/AnthropicClientAdapter");
 const GeminiClientAdapter_1 = require("./clients/GeminiClientAdapter");
 const LlamaCppClientAdapter_1 = require("./clients/LlamaCppClientAdapter");
+const OpenRouterClientAdapter_1 = require("./clients/OpenRouterClientAdapter");
+const MistralClientAdapter_1 = require("./clients/MistralClientAdapter");
 const defaultLogger_1 = require("../logging/defaultLogger");
 const logger = (0, defaultLogger_1.createDefaultLogger)();
-// Placeholder for future imports:
-// import { MistralClientAdapter } from './clients/MistralClientAdapter';
 /**
  * Mapping from provider IDs to their corresponding adapter constructor classes
  * This enables dynamic registration of client adapters in LLMServiceMain
@@ -29,7 +29,8 @@ exports.ADAPTER_CONSTRUCTORS = {
     anthropic: AnthropicClientAdapter_1.AnthropicClientAdapter,
     gemini: GeminiClientAdapter_1.GeminiClientAdapter,
     llamacpp: LlamaCppClientAdapter_1.LlamaCppClientAdapter,
-    // 'mistral': MistralClientAdapter, // Uncomment and add when Mistral adapter is ready
+    openrouter: OpenRouterClientAdapter_1.OpenRouterClientAdapter,
+    mistral: MistralClientAdapter_1.MistralClientAdapter,
 };
 /**
  * Optional configuration objects for each adapter
@@ -45,8 +46,12 @@ exports.ADAPTER_CONFIGS = {
     llamacpp: {
         baseURL: process.env.LLAMACPP_API_BASE_URL || 'http://localhost:8080',
     },
-    // 'gemini': { /* ... Gemini specific config ... */ },
-    // 'mistral': { /* ... Mistral specific config ... */ },
+    openrouter: {
+        baseURL: process.env.OPENROUTER_API_BASE_URL || 'https://openrouter.ai/api/v1',
+    },
+    mistral: {
+        baseURL: process.env.MISTRAL_API_BASE_URL || undefined,
+    },
 };
 /**
  * Default settings applied to all LLM requests unless overridden
@@ -59,6 +64,11 @@ exports.DEFAULT_LLM_SETTINGS = {
     frequencyPenalty: 0.0,
     presencePenalty: 0.0,
     supportsSystemMessage: true,
+    systemMessageFallback: {
+        format: 'xml',
+        tagName: 'system',
+        separator: '\n\n---\n\n',
+    },
     user: undefined, // Will be filtered out when undefined
     geminiSafetySettings: [
         { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_NONE" },
@@ -77,6 +87,7 @@ exports.DEFAULT_LLM_SETTINGS = {
         tagName: 'thinking',
         enforce: false
     },
+    openRouterProvider: undefined, // Optional, only used with OpenRouter provider
 };
 /**
  * Per-provider default setting overrides
@@ -130,6 +141,11 @@ exports.SUPPORTED_PROVIDERS = [
         name: "llama.cpp",
         allowUnknownModels: true, // Users load arbitrary GGUF models with custom names
     },
+    {
+        id: "openrouter",
+        name: "OpenRouter",
+        allowUnknownModels: true, // OpenRouter provides 100+ models dynamically
+    },
     {
         id: "mock",
         name: "Mock Provider",
@@ -591,6 +607,7 @@ exports.SUPPORTED_MODELS = [
         },
     },
     // Google Gemma 3 Models (Open weights, free via Gemini API)
+    // Note: Gemma models don't support system instructions - system content is prepended to user message
     {
         id: "gemma-3-27b-it",
         name: "Gemma 3 27B",
@@ -602,6 +619,7 @@ exports.SUPPORTED_MODELS = [
         maxTokens: 8192,
         supportsImages: true,
         supportsPromptCache: false,
+        supportsSystemMessage: false,
     },
     // OpenAI Models - GPT-5 Series
     {
@@ -742,6 +760,30 @@ exports.SUPPORTED_MODELS = [
         cacheReadsPrice: 0.025,
     },
     // Mistral AI Models
+    {
+        id: "mistral-small-latest",
+        name: "Mistral Small",
+        providerId: "mistral",
+        contextWindow: 128000,
+        inputPrice: 0.1,
+        outputPrice: 0.3,
+        description: "Cost-effective model for general tasks",
+        maxTokens: 128000,
+        supportsImages: false,
+        supportsPromptCache: false,
+    },
+    {
+        id: "mistral-large-2512",
+        name: "Mistral Large 3",
+        providerId: "mistral",
+        contextWindow: 256000,
+        inputPrice: 0.5,
+        outputPrice: 1.5,
+        description: "Mistral's frontier model with 256K context",
+        maxTokens: 256000,
+        supportsImages: false,
+        supportsPromptCache: false,
+    },
     {
         id: "codestral-2501",
         name: "Codestral",
@@ -779,6 +821,31 @@ exports.SUPPORTED_MODELS = [
         supportsImages: false,
         supportsPromptCache: false,
     },
+    // OpenRouter Models (Free Tier)
+    {
+        id: "google/gemma-3-27b-it:free",
+        name: "Gemma 3 27B (Free)",
+        providerId: "openrouter",
+        contextWindow: 96000,
+        inputPrice: 0.0,
+        outputPrice: 0.0,
+        description: "Google's Gemma 3 27B instruction-tuned model via OpenRouter (free tier)",
+        maxTokens: 8192,
+        supportsImages: true,
+        supportsPromptCache: false,
+    },
+    {
+        id: "mistralai/mistral-small-3.1-24b-instruct:free",
+        name: "Mistral Small 3.1 24B (Free)",
+        providerId: "openrouter",
+        contextWindow: 96000,
+        inputPrice: 0.0,
+        outputPrice: 0.0,
+        description: "Mistral Small 3.1 24B instruction model via OpenRouter (free tier)",
+        maxTokens: 8192,
+        supportsImages: false,
+        supportsPromptCache: false,
+    },
 ];
 /**
  * Gets provider information by ID

package/dist/llm/services/SettingsManager.js

@@ -32,6 +32,10 @@ class SettingsManager {
             user: requestSettings?.user ?? modelDefaults.user,
             supportsSystemMessage: requestSettings?.supportsSystemMessage ??
                 modelDefaults.supportsSystemMessage,
+            systemMessageFallback: {
+                ...modelDefaults.systemMessageFallback,
+                ...requestSettings?.systemMessageFallback,
+            },
             geminiSafetySettings: requestSettings?.geminiSafetySettings ??
                 modelDefaults.geminiSafetySettings,
             reasoning: {
@@ -42,6 +46,7 @@ class SettingsManager {
                 ...modelDefaults.thinkingTagFallback,
                 ...requestSettings?.thinkingTagFallback,
             },
+            openRouterProvider: requestSettings?.openRouterProvider ?? modelDefaults.openRouterProvider,
         };
         // Log the final settings for debugging
         this.logger.debug(`Merged settings for ${providerId}/${modelId}:`, {

package/dist/llm/types.d.ts

@@ -83,6 +83,74 @@ export interface LLMThinkingTagFallbackSettings {
      */
     enforce?: boolean;
 }
+/**
+ * Format options for prepending system content when model doesn't support system messages.
+ * - 'xml': Wrap in XML tags (default) - `<system>content</system>\n\n{user message}`
+ * - 'separator': Use a simple separator - `{content}\n\n---\n\n{user message}`
+ * - 'plain': Just prepend with double newline - `{content}\n\n{user message}`
+ */
+export type SystemMessageFallbackFormat = 'xml' | 'separator' | 'plain';
+/**
+ * Settings for handling system messages when the model doesn't support them natively.
+ * When a model has `supportsSystemMessage: false`, these settings control how
+ * system content is formatted when prepended to the first user message.
+ */
+export interface SystemMessageFallbackSettings {
+    /**
+     * Format to use when prepending system content to user message.
+     * @default 'xml'
+     */
+    format?: SystemMessageFallbackFormat;
+    /**
+     * Tag name to use when format is 'xml'.
+     * @default 'system'
+     * @example tagName: 'instructions' produces `<instructions>content</instructions>`
+     */
+    tagName?: string;
+    /**
+     * Separator string to use when format is 'separator'.
+     * @default '---'
+     */
+    separator?: string;
+}
+/**
+ * OpenRouter-specific provider routing settings
+ *
+ * These settings allow controlling which underlying providers serve requests
+ * when using OpenRouter. All fields are optional - by default, OpenRouter
+ * automatically selects the best provider based on price, latency, and availability.
+ *
+ * @see https://openrouter.ai/docs/provider-routing
+ */
+export interface OpenRouterProviderSettings {
+    /**
+     * Provider priority order. OpenRouter will try providers in this order.
+     * @example order: ["Together", "Fireworks", "Lepton"]
+     */
+    order?: string[];
+    /**
+     * Providers to exclude from serving this request.
+     * @example ignore: ["Azure", "OpenAI"]
+     */
+    ignore?: string[];
+    /**
+     * Providers to allow exclusively. If set, only these providers can serve the request.
+     * @example allow: ["Together", "Fireworks"]
+     */
+    allow?: string[];
+    /**
+     * Control whether providers can use your prompts for training.
+     * Set to 'deny' to opt out of data collection by providers.
+     * @default undefined (provider's default behavior)
+     */
+    dataCollection?: 'deny' | 'allow';
+    /**
+     * If true, only route to providers that support all parameters in your request.
+     * Useful when using provider-specific features.
+     * @default false
+     */
+    requireParameters?: boolean;
+}
 /**
  * Configurable settings for LLM requests
  */
@@ -103,6 +171,11 @@ export interface LLMSettings {
     user?: string;
     /** Whether the LLM supports system message (almost all LLMs do nowadays) */
     supportsSystemMessage?: boolean;
+    /**
+     * Settings for handling system messages when the model doesn't support them.
+     * Controls how system content is formatted when prepended to user messages.
+     */
+    systemMessageFallback?: SystemMessageFallbackSettings;
     /** Gemini-specific safety settings for content filtering */
     geminiSafetySettings?: GeminiSafetySetting[];
     /** Universal reasoning/thinking configuration */
@@ -121,6 +194,12 @@ export interface LLMSettings {
      * The library only extracts them - it doesn't generate them automatically.
      */
     thinkingTagFallback?: LLMThinkingTagFallbackSettings;
+    /**
+     * OpenRouter-specific provider routing settings.
+     * Only used when providerId is 'openrouter'.
+     * @see OpenRouterProviderSettings
+     */
+    openRouterProvider?: OpenRouterProviderSettings;
 }
 /**
  * Request structure for chat completion