Merge pull request coleam00#852 from coleam00/feature/openrouter-embeddings-support

Add OpenRouter Embeddings Support

Author: sean-esk

.env.example

@@ -124,7 +124,8 @@ PROD=false
 # Run the credentials_setup.sql file in your Supabase SQL editor to set up the credentials table.
 # Then use the Settings page in the web UI to manage:
 # - OPENAI_API_KEY (encrypted)
-# - MODEL_CHOICE 
+# - OPENROUTER_API_KEY (encrypted, format: sk-or-v1-..., get from https://openrouter.ai/keys)
+# - MODEL_CHOICE
 # - TRANSPORT settings
 # - RAG strategy flags (USE_CONTEXTUAL_EMBEDDINGS, USE_HYBRID_SEARCH, etc.)
 # - Crawler settings:

archon-ui-main/src/components/settings/RAGSettings.tsx

@@ -15,7 +15,7 @@ import OllamaModelSelectionModal from './OllamaModelSelectionModal';
 type ProviderKey = 'openai' | 'google' | 'ollama' | 'anthropic' | 'grok' | 'openrouter';
 
 // Providers that support embedding models
-const EMBEDDING_CAPABLE_PROVIDERS: ProviderKey[] = ['openai', 'google', 'ollama'];
+const EMBEDDING_CAPABLE_PROVIDERS: ProviderKey[] = ['openai', 'google', 'openrouter', 'ollama'];
 
 interface ProviderModels {
   chatModel: string;
@@ -42,7 +42,7 @@ const getDefaultModels = (provider: ProviderKey): ProviderModels => {
     anthropic: 'text-embedding-3-small', // Fallback to OpenAI
     google: 'text-embedding-004',
     grok: 'text-embedding-3-small', // Fallback to OpenAI
-    openrouter: 'text-embedding-3-small',
+    openrouter: 'openai/text-embedding-3-small', // MUST include provider prefix for OpenRouter
     ollama: 'nomic-embed-text'
   };
 
@@ -1291,7 +1291,7 @@ const manualTestConnection = async (
             Select {activeSelection === 'chat' ? 'Chat' : 'Embedding'} Provider
           </label>
           <div className={`grid gap-3 mb-4 ${
-            activeSelection === 'chat' ? 'grid-cols-6' : 'grid-cols-3'
+            activeSelection === 'chat' ? 'grid-cols-6' : 'grid-cols-4'
           }`}>
             {[
               { key: 'openai', name: 'OpenAI', logo: '/img/OpenAI.png', color: 'green' },

archon-ui-main/src/services/openrouterService.ts

@@ -0,0 +1,244 @@
+/**
+ * OpenRouter Service Client
+ *
+ * Provides frontend API client for OpenRouter model discovery.
+ */
+
+import { getApiUrl } from "../config/api";
+
+// Type definitions for OpenRouter API responses
+export interface OpenRouterEmbeddingModel {
+	id: string;
+	provider: string;
+	name: string;
+	dimensions: number;
+	context_length: number;
+	pricing_per_1m_tokens: number;
+	supports_dimension_reduction: boolean;
+}
+
+export interface OpenRouterModelListResponse {
+	embedding_models: OpenRouterEmbeddingModel[];
+	total_count: number;
+}
+
+class OpenRouterService {
+	private getBaseUrl = () => getApiUrl();
+	private cacheKey = "openrouter_models_cache";
+	private cacheTTL = 5 * 60 * 1000; // 5 minutes
+
+	private handleApiError(error: unknown, context: string): Error {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+
+		// Check for network errors
+		if (
+			errorMessage.toLowerCase().includes("network") ||
+			errorMessage.includes("fetch") ||
+			errorMessage.includes("Failed to fetch")
+		) {
+			return new Error(
+				`Network error while ${context.toLowerCase()}: ${errorMessage}. ` +
+					"Please check your connection.",
+			);
+		}
+
+		// Check for timeout errors
+		if (errorMessage.includes("timeout") || errorMessage.includes("AbortError")) {
+			return new Error(
+				`Timeout error while ${context.toLowerCase()}: The server may be slow to respond.`,
+			);
+		}
+
+		// Return original error with context
+		return new Error(`${context} failed: ${errorMessage}`);
+	}
+
+	/**
+	 * Type guard to validate cache entry structure
+	 */
+	private isCacheEntry(
+		value: unknown,
+	): value is { data: OpenRouterModelListResponse; timestamp: number } {
+		if (typeof value !== "object" || value === null) {
+			return false;
+		}
+
+		const obj = value as Record<string, unknown>;
+
+		// Validate timestamp is a number
+		if (typeof obj.timestamp !== "number") {
+			return false;
+		}
+
+		// Validate data property exists and is an object
+		if (typeof obj.data !== "object" || obj.data === null) {
+			return false;
+		}
+
+		const data = obj.data as Record<string, unknown>;
+
+		// Validate OpenRouterModelListResponse structure
+		if (!Array.isArray(data.embedding_models)) {
+			return false;
+		}
+
+		if (typeof data.total_count !== "number") {
+			return false;
+		}
+
+		// Validate each model in the array has required fields
+		for (const model of data.embedding_models) {
+			if (typeof model !== "object" || model === null) {
+				return false;
+			}
+			const m = model as Record<string, unknown>;
+			if (
+				typeof m.id !== "string" ||
+				typeof m.provider !== "string" ||
+				typeof m.name !== "string" ||
+				typeof m.dimensions !== "number" ||
+				typeof m.context_length !== "number" ||
+				typeof m.pricing_per_1m_tokens !== "number" ||
+				typeof m.supports_dimension_reduction !== "boolean"
+			) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+	/**
+	 * Get cached models if available and not expired
+	 */
+	private getCachedModels(): OpenRouterModelListResponse | null {
+		try {
+			const cached = sessionStorage.getItem(this.cacheKey);
+			if (!cached) return null;
+
+			const parsed: unknown = JSON.parse(cached);
+
+			// Validate cache structure
+			if (!this.isCacheEntry(parsed)) {
+				// Cache is corrupted, remove it to avoid repeated failures
+				sessionStorage.removeItem(this.cacheKey);
+				return null;
+			}
+
+			const now = Date.now();
+
+			// Check expiration
+			if (now - parsed.timestamp > this.cacheTTL) {
+				sessionStorage.removeItem(this.cacheKey);
+				return null;
+			}
+
+			return parsed.data;
+		} catch {
+			// JSON parsing failed or other error, clear cache
+			sessionStorage.removeItem(this.cacheKey);
+			return null;
+		}
+	}
+
+	/**
+	 * Cache models for the TTL duration
+	 */
+	private cacheModels(data: OpenRouterModelListResponse): void {
+		try {
+			const cacheData = {
+				data,
+				timestamp: Date.now(),
+			};
+			sessionStorage.setItem(this.cacheKey, JSON.stringify(cacheData));
+		} catch {
+			// Ignore cache errors
+		}
+	}
+
+	/**
+	 * Discover available OpenRouter embedding models
+	 */
+	async discoverModels(): Promise<OpenRouterModelListResponse> {
+		try {
+			// Check cache first
+			const cached = this.getCachedModels();
+			if (cached) {
+				return cached;
+			}
+
+			const response = await fetch(`${this.getBaseUrl()}/api/openrouter/models`, {
+				method: "GET",
+				headers: {
+					"Content-Type": "application/json",
+				},
+			});
+
+			if (!response.ok) {
+				const errorText = await response.text();
+				throw new Error(`HTTP ${response.status}: ${errorText}`);
+			}
+
+			const data = await response.json();
+
+			// Validate response structure
+			if (!data.embedding_models || !Array.isArray(data.embedding_models)) {
+				throw new Error("Invalid response structure: missing or invalid embedding_models array");
+			}
+
+			if (typeof data.total_count !== "number" || data.total_count < 0) {
+				throw new Error("Invalid response structure: total_count must be a non-negative number");
+			}
+
+			if (data.total_count !== data.embedding_models.length) {
+				throw new Error(
+					`Response structure mismatch: total_count (${data.total_count}) does not match embedding_models length (${data.embedding_models.length})`,
+				);
+			}
+
+			// Validate at least one model has required fields
+			if (data.embedding_models.length > 0) {
+				const firstModel = data.embedding_models[0];
+				if (
+					!firstModel.id ||
+					typeof firstModel.id !== "string" ||
+					!firstModel.provider ||
+					typeof firstModel.provider !== "string" ||
+					typeof firstModel.dimensions !== "number" ||
+					firstModel.dimensions <= 0
+				) {
+					throw new Error(
+						"Invalid model structure: models must have id (string), provider (string), and positive dimensions",
+					);
+				}
+
+				// Validate provider name is from expected set
+				const validProviders = ["openai", "google", "qwen", "mistralai"];
+				if (!validProviders.includes(firstModel.provider)) {
+					throw new Error(`Invalid provider name: ${firstModel.provider}`);
+				}
+			}
+
+			// Cache the successful response
+			this.cacheModels(data);
+
+			return data;
+		} catch (error) {
+			throw this.handleApiError(error, "Model discovery");
+		}
+	}
+
+	/**
+	 * Clear the models cache
+	 */
+	clearCache(): void {
+		try {
+			sessionStorage.removeItem(this.cacheKey);
+		} catch {
+			// Ignore cache clearing errors
+		}
+	}
+}
+
+// Export singleton instance
+export const openrouterService = new OpenRouterService();

python/src/server/api_routes/openrouter_api.py

@@ -0,0 +1,27 @@
+"""
+OpenRouter API routes.
+
+Endpoints for OpenRouter model discovery and configuration.
+"""
+
+from fastapi import APIRouter
+
+from ..services.openrouter_discovery_service import OpenRouterModelListResponse, openrouter_discovery_service
+
+router = APIRouter(prefix="/api/openrouter", tags=["openrouter"])
+
+
+@router.get("/models", response_model=OpenRouterModelListResponse)
+async def get_openrouter_models() -> OpenRouterModelListResponse:
+    """
+    Get available OpenRouter embedding models.
+
+    Returns a list of embedding models available through OpenRouter,
+    including models from OpenAI, Google, Qwen, and Mistral providers.
+
+    Returns:
+        OpenRouterModelListResponse: List of embedding models with metadata
+    """
+    models = await openrouter_discovery_service.discover_embedding_models()
+
+    return OpenRouterModelListResponse(embedding_models=models, total_count=len(models))

python/src/server/config/config.py

@@ -66,6 +66,19 @@ def validate_openai_api_key(api_key: str) -> bool:
     return True
 
 
+def validate_openrouter_api_key(api_key: str) -> bool:
+    """Validate OpenRouter API key format."""
+    if not api_key:
+        raise ConfigurationError("OpenRouter API key cannot be empty")
+
+    if not api_key.startswith("sk-or-v1-"):
+        raise ConfigurationError(
+            "OpenRouter API key must start with 'sk-or-v1-'. " "Get your key at https://openrouter.ai/keys"
+        )
+
+    return True
+
+
 def validate_supabase_key(supabase_key: str) -> tuple[bool, str]:
     """Validate Supabase key type and return validation result.
 

python/src/server/main.py

@@ -26,6 +26,7 @@
 from .api_routes.mcp_api import router as mcp_router
 from .api_routes.migration_api import router as migration_router
 from .api_routes.ollama_api import router as ollama_router
+from .api_routes.openrouter_api import router as openrouter_router
 from .api_routes.pages_api import router as pages_router
 from .api_routes.progress_api import router as progress_router
 from .api_routes.projects_api import router as projects_router
@@ -187,6 +188,7 @@ async def skip_health_check_logs(request, call_next):
 app.include_router(knowledge_router)
 app.include_router(pages_router)
 app.include_router(ollama_router)
+app.include_router(openrouter_router)
 app.include_router(projects_router)
 app.include_router(progress_router)
 app.include_router(agent_chat_router)

python/src/server/services/credential_service.py

@@ -443,7 +443,7 @@ async def get_active_provider(self, service_type: str = "llm") -> dict[str, Any]
                 explicit_embedding_provider = rag_settings.get("EMBEDDING_PROVIDER")
 
                 # Validate that embedding provider actually supports embeddings
-                embedding_capable_providers = {"openai", "google", "ollama"}
+                embedding_capable_providers = {"openai", "google", "openrouter", "ollama"}
 
                 if (explicit_embedding_provider and
                     explicit_embedding_provider != "" and