From e5944b63e7de387468538a58cefe7ea10416cae7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Wed, 8 Apr 2026 11:24:21 +0200 Subject: [PATCH] feat: add OpenRouter support for LLM, embeddings, and reranking (#930) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: add best practice for filtering recall by memory shape (#856) Add guidance on using entity labels with `tag: true` to deterministically filter recall results when a bank contains different memory shapes (e.g., concise rules vs. detailed procedures). * feat: add OpenRouter support for LLM, embeddings, and reranking OpenRouter is OpenAI-compatible for chat/embeddings and Cohere-compatible for reranking, so no new provider classes are needed. - LLM: added as OpenAICompatibleLLM provider (default model: qwen/qwen3.5-9b) - Embeddings: reuses OpenAIEmbeddings with OpenRouter base URL (default: perplexity/pplx-embed-v1-0.6b) - Reranker: reuses CohereCrossEncoder with OpenRouter rerank endpoint (default: cohere/rerank-v3.5) - API key fallback chain: dedicated key → shared OPENROUTER_API_KEY → LLM_API_KEY * chore: regenerate docs skill references and fix formatting --- hindsight-api-slim/hindsight_api/config.py | 26 +++++++++++++++++++ .../hindsight_api/engine/cross_encoder.py | 12 +++++++++ .../hindsight_api/engine/embeddings.py | 12 +++++++++ .../hindsight_api/engine/llm_wrapper.py | 5 +++- .../engine/providers/openai_compatible_llm.py | 6 +++-- .../docs/developer/configuration.md | 25 +++++++++++++++--- .../references/developer/configuration.md | 25 +++++++++++++++--- 7 files changed, 102 insertions(+), 9 deletions(-) diff --git a/hindsight-api-slim/hindsight_api/config.py b/hindsight-api-slim/hindsight_api/config.py index 8c58f567..aabd61ef 100644 --- a/hindsight-api-slim/hindsight_api/config.py +++ b/hindsight-api-slim/hindsight_api/config.py @@ -194,6 +194,13 @@ ENV_RERANKER_COHERE_API_KEY = "HINDSIGHT_API_RERANKER_COHERE_API_KEY" ENV_RERANKER_COHERE_MODEL = "HINDSIGHT_API_RERANKER_COHERE_MODEL" ENV_RERANKER_COHERE_BASE_URL = "HINDSIGHT_API_RERANKER_COHERE_BASE_URL" +# OpenRouter configuration (embeddings and reranker) +ENV_OPENROUTER_API_KEY = "HINDSIGHT_API_OPENROUTER_API_KEY" +ENV_EMBEDDINGS_OPENROUTER_API_KEY = "HINDSIGHT_API_EMBEDDINGS_OPENROUTER_API_KEY" +ENV_EMBEDDINGS_OPENROUTER_MODEL = "HINDSIGHT_API_EMBEDDINGS_OPENROUTER_MODEL" +ENV_RERANKER_OPENROUTER_API_KEY = "HINDSIGHT_API_RERANKER_OPENROUTER_API_KEY" +ENV_RERANKER_OPENROUTER_MODEL = "HINDSIGHT_API_RERANKER_OPENROUTER_MODEL" + # Deprecated: Legacy shared Cohere API key (for backward compatibility) ENV_COHERE_API_KEY = "HINDSIGHT_API_COHERE_API_KEY" @@ -399,6 +406,7 @@ PROVIDER_DEFAULT_MODELS = { "litellm": "gpt-4o-mini", "bedrock": "us.amazon.nova-2-lite-v1:0", "volcano": "doubao-pro-32k", + "openrouter": "qwen/qwen3.5-9b", } DEFAULT_LLM_MODEL = "gpt-4o-mini" # Fallback if provider not in table DEFAULT_LLM_MAX_CONCURRENT = 32 @@ -443,6 +451,10 @@ DEFAULT_RERANKER_FLASHRANK_CACHE_DIR = None # Use default cache directory DEFAULT_EMBEDDINGS_COHERE_MODEL = "embed-english-v3.0" DEFAULT_RERANKER_COHERE_MODEL = "rerank-english-v3.0" +# OpenRouter defaults +DEFAULT_EMBEDDINGS_OPENROUTER_MODEL = "perplexity/pplx-embed-v1-0.6b" +DEFAULT_RERANKER_OPENROUTER_MODEL = "cohere/rerank-v3.5" + DEFAULT_RERANKER_ZEROENTROPY_MODEL = "zerank-2" DEFAULT_RERANKER_GOOGLE_MODEL = "semantic-ranker-default-004" @@ -724,6 +736,8 @@ class HindsightConfig: embeddings_cohere_api_key: str | None embeddings_cohere_model: str embeddings_cohere_base_url: str | None + embeddings_openrouter_api_key: str | None + embeddings_openrouter_model: str embeddings_litellm_api_base: str embeddings_litellm_api_key: str | None embeddings_litellm_model: str @@ -756,6 +770,8 @@ class HindsightConfig: reranker_cohere_api_key: str | None reranker_cohere_model: str reranker_cohere_base_url: str | None + reranker_openrouter_api_key: str | None + reranker_openrouter_model: str reranker_litellm_api_base: str reranker_litellm_api_key: str | None reranker_litellm_model: str @@ -1189,6 +1205,11 @@ class HindsightConfig: embeddings_cohere_api_key=os.getenv(ENV_EMBEDDINGS_COHERE_API_KEY) or os.getenv(ENV_COHERE_API_KEY), embeddings_cohere_model=os.getenv(ENV_EMBEDDINGS_COHERE_MODEL, DEFAULT_EMBEDDINGS_COHERE_MODEL), embeddings_cohere_base_url=os.getenv(ENV_EMBEDDINGS_COHERE_BASE_URL) or None, + # OpenRouter embeddings (with fallback to shared OpenRouter key, then LLM key) + embeddings_openrouter_api_key=os.getenv(ENV_EMBEDDINGS_OPENROUTER_API_KEY) + or os.getenv(ENV_OPENROUTER_API_KEY) + or os.getenv(ENV_LLM_API_KEY), + embeddings_openrouter_model=os.getenv(ENV_EMBEDDINGS_OPENROUTER_MODEL, DEFAULT_EMBEDDINGS_OPENROUTER_MODEL), # LiteLLM embeddings (with backward-compatible fallback to shared config) embeddings_litellm_api_base=os.getenv(ENV_EMBEDDINGS_LITELLM_API_BASE) or os.getenv(ENV_LITELLM_API_BASE, DEFAULT_LITELLM_API_BASE), @@ -1253,6 +1274,11 @@ class HindsightConfig: reranker_cohere_api_key=os.getenv(ENV_RERANKER_COHERE_API_KEY) or os.getenv(ENV_COHERE_API_KEY), reranker_cohere_model=os.getenv(ENV_RERANKER_COHERE_MODEL, DEFAULT_RERANKER_COHERE_MODEL), reranker_cohere_base_url=os.getenv(ENV_RERANKER_COHERE_BASE_URL) or None, + # OpenRouter reranker (with fallback to shared OpenRouter key, then LLM key) + reranker_openrouter_api_key=os.getenv(ENV_RERANKER_OPENROUTER_API_KEY) + or os.getenv(ENV_OPENROUTER_API_KEY) + or os.getenv(ENV_LLM_API_KEY), + reranker_openrouter_model=os.getenv(ENV_RERANKER_OPENROUTER_MODEL, DEFAULT_RERANKER_OPENROUTER_MODEL), # LiteLLM reranker (with backward-compatible fallback to shared config) reranker_litellm_api_base=os.getenv(ENV_RERANKER_LITELLM_API_BASE) or os.getenv(ENV_LITELLM_API_BASE, DEFAULT_LITELLM_API_BASE), diff --git a/hindsight-api-slim/hindsight_api/engine/cross_encoder.py b/hindsight-api-slim/hindsight_api/engine/cross_encoder.py index edfe6094..2b987bfb 100644 --- a/hindsight-api-slim/hindsight_api/engine/cross_encoder.py +++ b/hindsight-api-slim/hindsight_api/engine/cross_encoder.py @@ -1468,6 +1468,18 @@ def create_cross_encoder_from_env() -> CrossEncoderModel: model=config.reranker_cohere_model, base_url=config.reranker_cohere_base_url, ) + elif provider == "openrouter": + api_key = config.reranker_openrouter_api_key + if not api_key: + raise ValueError( + "HINDSIGHT_API_RERANKER_OPENROUTER_API_KEY, HINDSIGHT_API_OPENROUTER_API_KEY, " + f"or HINDSIGHT_API_LLM_API_KEY is required when {ENV_RERANKER_PROVIDER} is 'openrouter'" + ) + return CohereCrossEncoder( + api_key=api_key, + model=config.reranker_openrouter_model, + base_url="https://openrouter.ai/api/v1/rerank", + ) elif provider == "flashrank": model = os.environ.get(ENV_RERANKER_FLASHRANK_MODEL, DEFAULT_RERANKER_FLASHRANK_MODEL) cache_dir = os.environ.get(ENV_RERANKER_FLASHRANK_CACHE_DIR, DEFAULT_RERANKER_FLASHRANK_CACHE_DIR) diff --git a/hindsight-api-slim/hindsight_api/engine/embeddings.py b/hindsight-api-slim/hindsight_api/engine/embeddings.py index e57ec223..e6dd1e39 100644 --- a/hindsight-api-slim/hindsight_api/engine/embeddings.py +++ b/hindsight-api-slim/hindsight_api/engine/embeddings.py @@ -1101,6 +1101,18 @@ def create_embeddings_from_env() -> Embeddings: model = os.environ.get(ENV_EMBEDDINGS_OPENAI_MODEL, DEFAULT_EMBEDDINGS_OPENAI_MODEL) base_url = os.environ.get(ENV_EMBEDDINGS_OPENAI_BASE_URL) or None return OpenAIEmbeddings(api_key=api_key, model=model, base_url=base_url) + elif provider == "openrouter": + api_key = config.embeddings_openrouter_api_key + if not api_key: + raise ValueError( + "HINDSIGHT_API_EMBEDDINGS_OPENROUTER_API_KEY, HINDSIGHT_API_OPENROUTER_API_KEY, " + f"or {ENV_LLM_API_KEY} is required when {ENV_EMBEDDINGS_PROVIDER} is 'openrouter'" + ) + return OpenAIEmbeddings( + api_key=api_key, + model=config.embeddings_openrouter_model, + base_url="https://openrouter.ai/api/v1", + ) elif provider == "cohere": api_key = config.embeddings_cohere_api_key if not api_key: diff --git a/hindsight-api-slim/hindsight_api/engine/llm_wrapper.py b/hindsight-api-slim/hindsight_api/engine/llm_wrapper.py index 07beab34..24c5efcf 100644 --- a/hindsight-api-slim/hindsight_api/engine/llm_wrapper.py +++ b/hindsight-api-slim/hindsight_api/engine/llm_wrapper.py @@ -263,7 +263,7 @@ def create_llm_provider( reasoning_effort=reasoning_effort, ) - elif provider_lower in ("openai", "groq", "ollama", "lmstudio", "minimax", "volcano"): + elif provider_lower in ("openai", "groq", "ollama", "lmstudio", "minimax", "volcano", "openrouter"): return OpenAICompatibleLLM( provider=provider, api_key=api_key, @@ -342,6 +342,7 @@ class LLMProvider: "litellm", "bedrock", "volcano", + "openrouter", ] if self.provider not in valid_providers: raise ValueError(f"Invalid LLM provider: {self.provider}. Must be one of: {', '.join(valid_providers)}") @@ -356,6 +357,8 @@ class LLMProvider: self.base_url = "http://localhost:1234/v1" elif self.provider == "minimax": self.base_url = "https://api.minimax.io/v1" + elif self.provider == "openrouter": + self.base_url = "https://openrouter.ai/api/v1" # Prepare Vertex AI config (if applicable) vertexai_project_id = None diff --git a/hindsight-api-slim/hindsight_api/engine/providers/openai_compatible_llm.py b/hindsight-api-slim/hindsight_api/engine/providers/openai_compatible_llm.py index e9eefed6..80ee0e87 100644 --- a/hindsight-api-slim/hindsight_api/engine/providers/openai_compatible_llm.py +++ b/hindsight-api-slim/hindsight_api/engine/providers/openai_compatible_llm.py @@ -100,7 +100,7 @@ class OpenAICompatibleLLM(LLMInterface): super().__init__(provider, api_key, base_url, model, reasoning_effort, **kwargs) # Validate provider - valid_providers = ["openai", "groq", "ollama", "lmstudio", "minimax", "volcano"] + valid_providers = ["openai", "groq", "ollama", "lmstudio", "minimax", "volcano", "openrouter"] if self.provider not in valid_providers: raise ValueError(f"OpenAICompatibleLLM only supports: {', '.join(valid_providers)}. Got: {self.provider}") @@ -114,13 +114,15 @@ class OpenAICompatibleLLM(LLMInterface): self.base_url = "http://localhost:1234/v1" elif self.provider == "minimax": self.base_url = "https://api.minimax.io/v1" + elif self.provider == "openrouter": + self.base_url = "https://openrouter.ai/api/v1" # For ollama/lmstudio, use dummy key if not provided if self.provider in ("ollama", "lmstudio") and not self.api_key: self.api_key = "local" # Validate API key for cloud providers - if self.provider in ("openai", "groq", "minimax") and not self.api_key: + if self.provider in ("openai", "groq", "minimax", "openrouter") and not self.api_key: raise ValueError(f"API key is required for {self.provider}") # Service tier configuration (from config, not env vars) diff --git a/hindsight-docs/docs/developer/configuration.md b/hindsight-docs/docs/developer/configuration.md index 06961741..ed2b52a1 100644 --- a/hindsight-docs/docs/developer/configuration.md +++ b/hindsight-docs/docs/developer/configuration.md @@ -161,7 +161,7 @@ To switch between backends: | Variable | Description | Default | |----------|-------------|---------| -| `HINDSIGHT_API_LLM_PROVIDER` | Provider: `openai`, `openai-codex`, `claude-code`, `anthropic`, `gemini`, `groq`, `minimax`, `ollama`, `lmstudio`, `vertexai`, `bedrock`, `litellm`, `volcano`, `none` | `openai` | +| `HINDSIGHT_API_LLM_PROVIDER` | Provider: `openai`, `openai-codex`, `claude-code`, `anthropic`, `gemini`, `groq`, `minimax`, `ollama`, `lmstudio`, `vertexai`, `bedrock`, `litellm`, `volcano`, `openrouter`, `none` | `openai` | | `HINDSIGHT_API_LLM_API_KEY` | API key for LLM provider | - | | `HINDSIGHT_API_LLM_MODEL` | Model name | `gpt-5-mini` | | `HINDSIGHT_API_LLM_BASE_URL` | Custom LLM endpoint | Provider default | @@ -242,6 +242,11 @@ export HINDSIGHT_API_LLM_API_KEY=your-api-key export HINDSIGHT_API_LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3 export HINDSIGHT_API_LLM_MODEL=doubao-pro-32k +# OpenRouter (OpenAI-compatible, access 100+ models) +export HINDSIGHT_API_LLM_PROVIDER=openrouter +export HINDSIGHT_API_LLM_API_KEY=your-openrouter-api-key +export HINDSIGHT_API_LLM_MODEL=qwen/qwen3.5-9b + # AWS Bedrock (native support - no API key needed, uses AWS credentials) export HINDSIGHT_API_LLM_PROVIDER=bedrock export HINDSIGHT_API_LLM_MODEL=us.amazon.nova-2-lite-v1:0 @@ -352,7 +357,7 @@ export HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF=120.0 # Cap at 2min instead of 1m | Variable | Description | Default | |----------|-------------|---------| -| `HINDSIGHT_API_EMBEDDINGS_PROVIDER` | Provider: `local`, `tei`, `openai`, `cohere`, `google`, `litellm`, or `litellm-sdk` | `local` | +| `HINDSIGHT_API_EMBEDDINGS_PROVIDER` | Provider: `local`, `tei`, `openai`, `openrouter`, `cohere`, `google`, `litellm`, or `litellm-sdk` | `local` | | `HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL` | Model for local provider | `BAAI/bge-small-en-v1.5` | | `HINDSIGHT_API_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE` | Allow loading models with custom code (security risk, disabled by default) | `false` | | `HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU` | Force CPU mode for local embeddings (avoids MPS/XPC issues on macOS) | `false` | @@ -360,6 +365,8 @@ export HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF=120.0 # Cap at 2min instead of 1m | `HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY` | OpenAI API key (falls back to `HINDSIGHT_API_LLM_API_KEY`) | - | | `HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL` | OpenAI embedding model | `text-embedding-3-small` | | `HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL` | Custom base URL for OpenAI-compatible API (e.g., Azure OpenAI) | - | +| `HINDSIGHT_API_EMBEDDINGS_OPENROUTER_API_KEY` | OpenRouter API key for embeddings (falls back to `HINDSIGHT_API_OPENROUTER_API_KEY`, then `HINDSIGHT_API_LLM_API_KEY`) | - | +| `HINDSIGHT_API_EMBEDDINGS_OPENROUTER_MODEL` | OpenRouter embedding model | `perplexity/pplx-embed-v1-0.6b` | | `HINDSIGHT_API_EMBEDDINGS_COHERE_API_KEY` | Cohere API key for embeddings | - | | `HINDSIGHT_API_EMBEDDINGS_COHERE_MODEL` | Cohere embedding model | `embed-english-v3.0` | | `HINDSIGHT_API_EMBEDDINGS_COHERE_BASE_URL` | Custom base URL for Cohere-compatible API (e.g., Azure-hosted) | - | @@ -403,6 +410,11 @@ export HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL=https://your-resource.openai.azu export HINDSIGHT_API_EMBEDDINGS_PROVIDER=tei export HINDSIGHT_API_EMBEDDINGS_TEI_URL=http://localhost:8080 +# OpenRouter - access 100+ embedding models +export HINDSIGHT_API_EMBEDDINGS_PROVIDER=openrouter +export HINDSIGHT_API_EMBEDDINGS_OPENROUTER_API_KEY=your-openrouter-api-key # or reuses HINDSIGHT_API_LLM_API_KEY +export HINDSIGHT_API_EMBEDDINGS_OPENROUTER_MODEL=perplexity/pplx-embed-v1-0.6b + # Cohere - cloud-based embeddings export HINDSIGHT_API_EMBEDDINGS_PROVIDER=cohere export HINDSIGHT_API_EMBEDDINGS_COHERE_API_KEY=your-api-key @@ -472,7 +484,7 @@ Google's `gemini-embedding-001` produces 3072 dimensions natively but supports c | Variable | Description | Default | |----------|-------------|---------| -| `HINDSIGHT_API_RERANKER_PROVIDER` | Provider: `local`, `tei`, `cohere`, `zeroentropy`, `google`, `flashrank`, `litellm`, `litellm-sdk`, `jina-mlx`, or `rrf` | `local` | +| `HINDSIGHT_API_RERANKER_PROVIDER` | Provider: `local`, `tei`, `cohere`, `openrouter`, `zeroentropy`, `google`, `flashrank`, `litellm`, `litellm-sdk`, `jina-mlx`, or `rrf` | `local` | | `HINDSIGHT_API_RERANKER_LOCAL_MODEL` | Model for local provider | `cross-encoder/ms-marco-MiniLM-L-6-v2` | | `HINDSIGHT_API_RERANKER_LOCAL_MAX_CONCURRENT` | Max concurrent local reranking (prevents CPU thrashing under load) | `4` | | `HINDSIGHT_API_RERANKER_LOCAL_TRUST_REMOTE_CODE` | Allow loading models with custom code (security risk, disabled by default) | `false` | @@ -483,6 +495,8 @@ Google's `gemini-embedding-001` produces 3072 dimensions natively but supports c | `HINDSIGHT_API_RERANKER_TEI_URL` | TEI server URL | - | | `HINDSIGHT_API_RERANKER_TEI_BATCH_SIZE` | Batch size for TEI reranking | `128` | | `HINDSIGHT_API_RERANKER_TEI_MAX_CONCURRENT` | Max concurrent TEI reranking requests | `8` | +| `HINDSIGHT_API_RERANKER_OPENROUTER_API_KEY` | OpenRouter API key for reranking (falls back to `HINDSIGHT_API_OPENROUTER_API_KEY`, then `HINDSIGHT_API_LLM_API_KEY`) | - | +| `HINDSIGHT_API_RERANKER_OPENROUTER_MODEL` | OpenRouter rerank model | `cohere/rerank-v3.5` | | `HINDSIGHT_API_RERANKER_COHERE_API_KEY` | Cohere API key for reranking | - | | `HINDSIGHT_API_RERANKER_COHERE_MODEL` | Cohere rerank model | `rerank-english-v3.0` | | `HINDSIGHT_API_RERANKER_COHERE_BASE_URL` | Custom base URL for Cohere-compatible API (e.g., Azure-hosted) | - | @@ -518,6 +532,11 @@ export HINDSIGHT_API_RERANKER_LOCAL_TRUST_REMOTE_CODE=true export HINDSIGHT_API_RERANKER_PROVIDER=tei export HINDSIGHT_API_RERANKER_TEI_URL=http://localhost:8081 +# OpenRouter - access reranking models via OpenRouter +export HINDSIGHT_API_RERANKER_PROVIDER=openrouter +export HINDSIGHT_API_RERANKER_OPENROUTER_API_KEY=your-openrouter-api-key # or reuses HINDSIGHT_API_LLM_API_KEY +export HINDSIGHT_API_RERANKER_OPENROUTER_MODEL=cohere/rerank-v3.5 + # Cohere - cloud-based reranking export HINDSIGHT_API_RERANKER_PROVIDER=cohere export HINDSIGHT_API_RERANKER_COHERE_API_KEY=your-api-key diff --git a/skills/hindsight-docs/references/developer/configuration.md b/skills/hindsight-docs/references/developer/configuration.md index 54bc51ef..0156def6 100644 --- a/skills/hindsight-docs/references/developer/configuration.md +++ b/skills/hindsight-docs/references/developer/configuration.md @@ -161,7 +161,7 @@ To switch between backends: | Variable | Description | Default | |----------|-------------|---------| -| `HINDSIGHT_API_LLM_PROVIDER` | Provider: `openai`, `openai-codex`, `claude-code`, `anthropic`, `gemini`, `groq`, `minimax`, `ollama`, `lmstudio`, `vertexai`, `bedrock`, `litellm`, `volcano`, `none` | `openai` | +| `HINDSIGHT_API_LLM_PROVIDER` | Provider: `openai`, `openai-codex`, `claude-code`, `anthropic`, `gemini`, `groq`, `minimax`, `ollama`, `lmstudio`, `vertexai`, `bedrock`, `litellm`, `volcano`, `openrouter`, `none` | `openai` | | `HINDSIGHT_API_LLM_API_KEY` | API key for LLM provider | - | | `HINDSIGHT_API_LLM_MODEL` | Model name | `gpt-5-mini` | | `HINDSIGHT_API_LLM_BASE_URL` | Custom LLM endpoint | Provider default | @@ -242,6 +242,11 @@ export HINDSIGHT_API_LLM_API_KEY=your-api-key export HINDSIGHT_API_LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3 export HINDSIGHT_API_LLM_MODEL=doubao-pro-32k +# OpenRouter (OpenAI-compatible, access 100+ models) +export HINDSIGHT_API_LLM_PROVIDER=openrouter +export HINDSIGHT_API_LLM_API_KEY=your-openrouter-api-key +export HINDSIGHT_API_LLM_MODEL=qwen/qwen3.5-9b + # AWS Bedrock (native support - no API key needed, uses AWS credentials) export HINDSIGHT_API_LLM_PROVIDER=bedrock export HINDSIGHT_API_LLM_MODEL=us.amazon.nova-2-lite-v1:0 @@ -352,7 +357,7 @@ export HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF=120.0 # Cap at 2min instead of 1m | Variable | Description | Default | |----------|-------------|---------| -| `HINDSIGHT_API_EMBEDDINGS_PROVIDER` | Provider: `local`, `tei`, `openai`, `cohere`, `google`, `litellm`, or `litellm-sdk` | `local` | +| `HINDSIGHT_API_EMBEDDINGS_PROVIDER` | Provider: `local`, `tei`, `openai`, `openrouter`, `cohere`, `google`, `litellm`, or `litellm-sdk` | `local` | | `HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL` | Model for local provider | `BAAI/bge-small-en-v1.5` | | `HINDSIGHT_API_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE` | Allow loading models with custom code (security risk, disabled by default) | `false` | | `HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU` | Force CPU mode for local embeddings (avoids MPS/XPC issues on macOS) | `false` | @@ -360,6 +365,8 @@ export HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF=120.0 # Cap at 2min instead of 1m | `HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY` | OpenAI API key (falls back to `HINDSIGHT_API_LLM_API_KEY`) | - | | `HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL` | OpenAI embedding model | `text-embedding-3-small` | | `HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL` | Custom base URL for OpenAI-compatible API (e.g., Azure OpenAI) | - | +| `HINDSIGHT_API_EMBEDDINGS_OPENROUTER_API_KEY` | OpenRouter API key for embeddings (falls back to `HINDSIGHT_API_OPENROUTER_API_KEY`, then `HINDSIGHT_API_LLM_API_KEY`) | - | +| `HINDSIGHT_API_EMBEDDINGS_OPENROUTER_MODEL` | OpenRouter embedding model | `perplexity/pplx-embed-v1-0.6b` | | `HINDSIGHT_API_EMBEDDINGS_COHERE_API_KEY` | Cohere API key for embeddings | - | | `HINDSIGHT_API_EMBEDDINGS_COHERE_MODEL` | Cohere embedding model | `embed-english-v3.0` | | `HINDSIGHT_API_EMBEDDINGS_COHERE_BASE_URL` | Custom base URL for Cohere-compatible API (e.g., Azure-hosted) | - | @@ -403,6 +410,11 @@ export HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL=https://your-resource.openai.azu export HINDSIGHT_API_EMBEDDINGS_PROVIDER=tei export HINDSIGHT_API_EMBEDDINGS_TEI_URL=http://localhost:8080 +# OpenRouter - access 100+ embedding models +export HINDSIGHT_API_EMBEDDINGS_PROVIDER=openrouter +export HINDSIGHT_API_EMBEDDINGS_OPENROUTER_API_KEY=your-openrouter-api-key # or reuses HINDSIGHT_API_LLM_API_KEY +export HINDSIGHT_API_EMBEDDINGS_OPENROUTER_MODEL=perplexity/pplx-embed-v1-0.6b + # Cohere - cloud-based embeddings export HINDSIGHT_API_EMBEDDINGS_PROVIDER=cohere export HINDSIGHT_API_EMBEDDINGS_COHERE_API_KEY=your-api-key @@ -472,7 +484,7 @@ Google's `gemini-embedding-001` produces 3072 dimensions natively but supports c | Variable | Description | Default | |----------|-------------|---------| -| `HINDSIGHT_API_RERANKER_PROVIDER` | Provider: `local`, `tei`, `cohere`, `zeroentropy`, `google`, `flashrank`, `litellm`, `litellm-sdk`, `jina-mlx`, or `rrf` | `local` | +| `HINDSIGHT_API_RERANKER_PROVIDER` | Provider: `local`, `tei`, `cohere`, `openrouter`, `zeroentropy`, `google`, `flashrank`, `litellm`, `litellm-sdk`, `jina-mlx`, or `rrf` | `local` | | `HINDSIGHT_API_RERANKER_LOCAL_MODEL` | Model for local provider | `cross-encoder/ms-marco-MiniLM-L-6-v2` | | `HINDSIGHT_API_RERANKER_LOCAL_MAX_CONCURRENT` | Max concurrent local reranking (prevents CPU thrashing under load) | `4` | | `HINDSIGHT_API_RERANKER_LOCAL_TRUST_REMOTE_CODE` | Allow loading models with custom code (security risk, disabled by default) | `false` | @@ -483,6 +495,8 @@ Google's `gemini-embedding-001` produces 3072 dimensions natively but supports c | `HINDSIGHT_API_RERANKER_TEI_URL` | TEI server URL | - | | `HINDSIGHT_API_RERANKER_TEI_BATCH_SIZE` | Batch size for TEI reranking | `128` | | `HINDSIGHT_API_RERANKER_TEI_MAX_CONCURRENT` | Max concurrent TEI reranking requests | `8` | +| `HINDSIGHT_API_RERANKER_OPENROUTER_API_KEY` | OpenRouter API key for reranking (falls back to `HINDSIGHT_API_OPENROUTER_API_KEY`, then `HINDSIGHT_API_LLM_API_KEY`) | - | +| `HINDSIGHT_API_RERANKER_OPENROUTER_MODEL` | OpenRouter rerank model | `cohere/rerank-v3.5` | | `HINDSIGHT_API_RERANKER_COHERE_API_KEY` | Cohere API key for reranking | - | | `HINDSIGHT_API_RERANKER_COHERE_MODEL` | Cohere rerank model | `rerank-english-v3.0` | | `HINDSIGHT_API_RERANKER_COHERE_BASE_URL` | Custom base URL for Cohere-compatible API (e.g., Azure-hosted) | - | @@ -518,6 +532,11 @@ export HINDSIGHT_API_RERANKER_LOCAL_TRUST_REMOTE_CODE=true export HINDSIGHT_API_RERANKER_PROVIDER=tei export HINDSIGHT_API_RERANKER_TEI_URL=http://localhost:8081 +# OpenRouter - access reranking models via OpenRouter +export HINDSIGHT_API_RERANKER_PROVIDER=openrouter +export HINDSIGHT_API_RERANKER_OPENROUTER_API_KEY=your-openrouter-api-key # or reuses HINDSIGHT_API_LLM_API_KEY +export HINDSIGHT_API_RERANKER_OPENROUTER_MODEL=cohere/rerank-v3.5 + # Cohere - cloud-based reranking export HINDSIGHT_API_RERANKER_PROVIDER=cohere export HINDSIGHT_API_RERANKER_COHERE_API_KEY=your-api-key