From 8e8ea9545886dbccd0a14abf5216a083fbfd6fc4 Mon Sep 17 00:00:00 2001
From: Claudio Drews <c14u6106r3w50891@gmail.com>
Date: Tue, 2 Jun 2026 13:05:12 -0300
Subject: [PATCH] =?UTF-8?q?fix(embedding):=20make=20OpenRouter=20auth=20an?=
 =?UTF-8?q?d=20headers=20conditional=20=E2=80=94=20unblock=20100%=20local?=
 =?UTF-8?q?=20usage=20(#7)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove unconditional OPENROUTER_API_KEY check that blocked local providers
  (Ollama, vLLM, llama.cpp) from running without an API key
- Send OpenRouter-specific headers (HTTP-Referer, X-Title) only when
  EMBEDDING_API_BASE contains 'openrouter'
- Stop sending empty Authorization header to non-OpenRouter endpoints
- Update .env.example and setup/install.md to clarify that
  OPENROUTER_API_KEY is only required for OpenRouter

Closes #1

Co-authored-by: ClaudioDrews <claudio@drews.com.br>
---
 .env.example                        |  3 ++-
 docker/worker/services/embedding.py | 17 ++++++++---------
 setup/install.md                    |  5 ++++-
 3 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/.env.example b/.env.example
index 69d894d..ce8e222 100644
--- a/.env.example
+++ b/.env.example
@@ -4,7 +4,8 @@
 
 # ── Required ──────────────────────────────────────────
 
-# OpenRouter API key (for embeddings and LLM extraction)
+# OpenRouter API key — REQUIRED only when EMBEDDING_API_BASE points to OpenRouter.
+# For local providers (Ollama, vLLM, llama.cpp) leave unset or comment out.
 OPENROUTER_API_KEY=sk-or-...
 
 # Redis password (generate with: openssl rand -hex 16)
diff --git a/docker/worker/services/embedding.py b/docker/worker/services/embedding.py
index 57c45c2..b9d6ee6 100644
--- a/docker/worker/services/embedding.py
+++ b/docker/worker/services/embedding.py
@@ -25,20 +25,19 @@ async def get_embedding(text: str) -> list[float]:
     Generates embedding via the configured backend.
     Validates that the returned dimensions match EMBEDDING_DIMS.
     """
-    if not OPENROUTER_API_KEY:
-        raise RuntimeError("OPENROUTER_API_KEY is not configured")
+    headers = {"Content-Type": "application/json"}
 
-    headers = {
-        "Authorization": f"Bearer {OPENROUTER_API_KEY}",
-        "Content-Type": "application/json",
-        "HTTP-Referer": "https://localhost",
-        "X-Title": "Cognitive-Agent-MaaS",
-    }
+    if "openrouter" in EMBEDDING_API_BASE.lower():
+        if not OPENROUTER_API_KEY:
+            raise RuntimeError("OPENROUTER_API_KEY is required for OpenRouter")
+        headers["Authorization"] = f"Bearer {OPENROUTER_API_KEY}"
+        headers["HTTP-Referer"] = "https://localhost"
+        headers["X-Title"] = "Cognitive-Agent-MaaS"
 
     payload = {
         "model": EMBEDDING_MODEL,
         "input": text,
-        "dimensions": EMBEDDING_DIMS,
+        "dimensions": EMBEDDING_DIMS,  # OpenAI/OpenRouter-specific; ignored by Ollama/vLLM
     }
 
     async with httpx.AsyncClient(timeout=60) as client:
diff --git a/setup/install.md b/setup/install.md
index f0a9421..de172b9 100644
--- a/setup/install.md
+++ b/setup/install.md
@@ -7,7 +7,7 @@
 - Hermes Agent 0.14.0+ (tested on 0.15.2)
 - Python 3.11+
 - Docker 24.0+
-- OpenRouter API key (or configured embedding backend — see [Layer 5: Qdrant](../layers/05-qdrant.md))
+- OpenRouter API key **only if using OpenRouter as embedding backend** (Ollama/vLLM/llama.cpp local providers do not require a key — see [Layer 5: Qdrant](../layers/05-qdrant.md))
 - 16 GB RAM recommended (8 GB minimum)
 
 ## Installation
@@ -51,6 +51,7 @@ cd ~/memory-os
 
 # Create .env with required variables
 cat > .env << EOF
+# Required only for OpenRouter embedding backend; safe to leave empty for local providers
 OPENROUTER_API_KEY=sk-or-...
 REDIS_PASSWORD=$(openssl rand -hex 16)
 EMBEDDING_DIMS=4096
@@ -73,6 +74,8 @@ Add to your Hermes profile `.env` (e.g. `~/.hermes/.env`):
 ```bash
 # Required
 FABRIC_DIR=/home/your-user/vault/fabric
+
+# Required only when using OpenRouter as embedding backend
 OPENROUTER_API_KEY=sk-or-...
 
 # Strongly recommended