""" Remote Embeddings Module — Multi-Provider with Fallback Chain TIER 1: OpenRouter Nemotron 3 Embed 1B (free, no limit, 1024d) TIER 2: Cloudflare Workers AI bge-m3 (free 10k/day, 1024d) TIER 3: SentenceTransformer local (offline fallback) All providers produce 1024-dimensional embeddings for compatibility. """ import os import time from typing import List, Optional import numpy as np import requests from loguru import logger # ============================================================ # TIER 1: OpenRouter Nemotron 3 Embed 1B (free, no limit) # ============================================================ class OpenRouterEmbeddings: """ OpenRouter Nemotron 3 Embed 1B — free text embedding model. 1024 dimensions, high quality for RAG/retrieval tasks. API: OpenAI-compatible /v1/embeddings endpoint. """ EMBEDDING_DIM = 1024 MODEL = "nvidia/nemotron-3-embed-1b:free" API_URL = "https://openrouter.ai/api/v1/embeddings" MIN_REQUEST_INTERVAL = 0.1 def __init__(self, api_key: Optional[str] = None): self._api_key = api_key or os.getenv("OPENROUTER_API_KEY") self._last_request_time = 0.0 def is_available(self) -> bool: return bool(self._api_key) def _embed_via_openai(self, input_data, api_key: str) -> Optional[dict]: """Call OpenRouter embeddings endpoint (OpenAI-compatible).""" headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", } payload = { "model": self.MODEL, "input": input_data, } elapsed = time.time() - self._last_request_time if elapsed < self.MIN_REQUEST_INTERVAL: time.sleep(self.MIN_REQUEST_INTERVAL - elapsed) self._last_request_time = time.time() try: resp = requests.post(self.API_URL, headers=headers, json=payload, timeout=30) if not resp.ok: logger.error(f"OpenRouter embeddings HTTP {resp.status_code}: {resp.text[:500]}") return None return resp.json() except Exception as e: logger.error(f"OpenRouter embeddings error: {e}") return None def embed(self, text: str) -> Optional[np.ndarray]: """Embed a single text string → 1024-dim numpy array.""" try: data = self._embed_via_openai(text, self._api_key) if not data: return None emb_list = data.get("data", [{}])[0].get("embedding") if not emb_list: logger.error("OpenRouter embeddings: empty result") return None return np.array(emb_list, dtype=np.float32) except Exception as e: logger.error(f"OpenRouter embed failed: {e}") return None def embed_batch(self, texts: List[str]) -> Optional[np.ndarray]: """Embed multiple texts → (N, 1024) numpy array.""" if not texts: return np.array([], dtype=np.float32).reshape(0, self.EMBEDDING_DIM) try: data = self._embed_via_openai(texts, self._api_key) if not data: return None items = data.get("data", []) vectors = [item.get("embedding", []) for item in items] if not vectors or not vectors[0]: logger.error("OpenRouter embeddings batch: empty result") return None return np.array(vectors, dtype=np.float32) except Exception as e: logger.error(f"OpenRouter embed_batch failed: {e}") return None # ============================================================ # TIER 2: Cloudflare Workers AI bge-m3 (free 10k/day) # ============================================================ class CloudflareEmbeddings: """ Cloudflare Workers AI bge-m3 — multilingual embedding model. 1024 dimensions, optimized for retrieval in 100+ languages. """ EMBEDDING_DIM = 1024 API_URL_TEMPLATE = "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/baai/bge-m3" MIN_REQUEST_INTERVAL = 0.1 def __init__(self, account_id: Optional[str] = None, api_key: Optional[str] = None): self._account_id = account_id or os.getenv("CLOUDFLARE_ACCOUNT_ID") self._api_key = api_key or os.getenv("CLOUDFLARE_API_KEY") or os.getenv("CLOUDFALRE_API_KEY") self._last_request_time = 0.0 def is_available(self) -> bool: return bool(self._account_id and self._api_key) def _rate_limit(self): elapsed = time.time() - self._last_request_time if elapsed < self.MIN_REQUEST_INTERVAL: time.sleep(self.MIN_REQUEST_INTERVAL - elapsed) self._last_request_time = time.time() def _post(self, payload: dict) -> Optional[dict]: if not self.is_available(): return None self._rate_limit() url = self.API_URL_TEMPLATE.format(account_id=self._account_id) headers = {"Authorization": f"Bearer {self._api_key}", "Content-Type": "application/json"} try: resp = requests.post(url, headers=headers, json=payload, timeout=30) resp.raise_for_status() data = resp.json() if not data.get("success"): logger.error(f"Cloudflare API error: {data.get('errors', [])}") return None return data except Exception as e: logger.error(f"Cloudflare embeddings error: {e}") return None def embed(self, text: str) -> Optional[np.ndarray]: try: result = self._post({"input": text}) if not result: return None emb = result.get("result", {}).get("data") if not emb: return None return np.array(emb, dtype=np.float32) except Exception as e: logger.error(f"Cloudflare embed failed: {e}") return None def embed_batch(self, texts: List[str]) -> Optional[np.ndarray]: if not texts: return np.array([], dtype=np.float32).reshape(0, self.EMBEDDING_DIM) try: result = self._post({"input": texts}) if not result: return None data = result.get("result", {}).get("data") if not data: return None return np.array(data, dtype=np.float32) except Exception as e: logger.error(f"Cloudflare embed_batch failed: {e}") return None # ============================================================ # UNIFIED PROVIDER with 3-tier fallback # ============================================================ class RemoteEmbeddings: """ Unified embedding provider with automatic fallback: 1. OpenRouter Nemotron 3 Embed 1B (free, no limit) 2. Cloudflare bge-m3 (free 10k/day) 3. Returns None (caller uses SentenceTransformer local fallback) """ def __init__(self): self._openrouter = OpenRouterEmbeddings() self._cloudflare = CloudflareEmbeddings() self._active_provider = None self._init_provider() def _init_provider(self): if self._openrouter.is_available(): self._active_provider = "openrouter" logger.info("🤗 [EMBEDDINGS] Tier 1: OpenRouter Nemotron 3 Embed 1B (free, no limit)") elif self._cloudflare.is_available(): self._active_provider = "cloudflare" logger.info("🤗 [EMBEDDINGS] Tier 2: Cloudflare bge-m3 (free 10k/day)") else: self._active_provider = None logger.info("🤗 [EMBEDDINGS] No remote provider — using SentenceTransformer local fallback") def is_available(self) -> bool: return self._active_provider is not None def embed(self, text: str) -> Optional[np.ndarray]: """Embed with automatic provider fallback.""" if self._active_provider == "openrouter": result = self._openrouter.embed(text) if result is not None: return result # Fallback to Cloudflare if self._cloudflare.is_available(): result = self._cloudflare.embed(text) if result is not None: self._active_provider = "cloudflare" return result return None if self._active_provider == "cloudflare": result = self._cloudflare.embed(text) if result is not None: return result # Fallback to OpenRouter if available if self._openrouter.is_available(): result = self._openrouter.embed(text) if result is not None: self._active_provider = "openrouter" return result return None return None def embed_batch(self, texts: List[str]) -> Optional[np.ndarray]: """Embed batch with automatic provider fallback.""" if not texts: return None if self._active_provider == "openrouter": result = self._openrouter.embed_batch(texts) if result is not None: return result if self._cloudflare.is_available(): result = self._cloudflare.embed_batch(texts) if result is not None: self._active_provider = "cloudflare" return result return None if self._active_provider == "cloudflare": result = self._cloudflare.embed_batch(texts) if result is not None: return result if self._openrouter.is_available(): result = self._openrouter.embed_batch(texts) if result is not None: self._active_provider = "openrouter" return result return None return None # ============================================================ # Singleton # ============================================================ _remote_embeddings_instance: Optional[RemoteEmbeddings] = None def get_remote_embeddings() -> RemoteEmbeddings: """Get or create the singleton RemoteEmbeddings instance.""" global _remote_embeddings_instance if _remote_embeddings_instance is None: _remote_embeddings_instance = RemoteEmbeddings() return _remote_embeddings_instance # Legacy alias def get_cloudflare_embeddings() -> RemoteEmbeddings: """Legacy alias — returns RemoteEmbeddings with fallback chain.""" return get_remote_embeddings()