fix(embedding): make OpenRouter auth and headers conditional — unblock 100% local usage (#7)

- 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

@@ -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)

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:

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