OpenRouter: log when key missing; try more env names; doc HF secret OPENROUTER_API_KEY

DEPLOY.md

@@ -90,7 +90,8 @@ git push hf main
 
 - **SDK**: Gradio (see `README.md` → `sdk: gradio`, `app_file: app.py`).
 - **Secrets**: In the Space **Settings → Repository secrets**, set:
-  - **`gemini_api`**: your Gemini API key (required for chat).
+  - **`gemini_api`**: your Gemini API key (fallback when OpenRouter is not used).
+  - **`OPENROUTER_API_KEY`** *(recommended)*: OpenRouter API key — used first for faster answers and to avoid Gemini rate limits. Get one at [openrouter.ai/keys](https://openrouter.ai/keys).
 - **Hardware**: Default CPU is enough; GPU is optional for faster embedding if you change the app later.
 
 ---

README.md

@@ -65,8 +65,9 @@ Open the local Gradio URL printed in the terminal.
 ## Configuration
 
 ### Environment variables
-- **`gemini_api`** *(required)*: Gemini API key used by `app.py`.
-- **`GEMINI_REQUEST_DELAY`** *(optional)*: minimum seconds between Gemini requests per process (default: `5.0`).
+- **`OPENROUTER_API_KEY`** *(recommended on HF)*: OpenRouter API key — tried first for faster answers and to avoid Gemini rate limits. On Hugging Face, add as Repository secret. Local: set in `.env` as `openRouter_API_KEY` or `OPENROUTER_API_KEY`.
+- **`gemini_api`**: Gemini API key — used when OpenRouter is not set or fails. Required if you don’t use OpenRouter.
+- **`GEMINI_REQUEST_DELAY`** *(optional)*: minimum seconds between Gemini requests per process (default: `0.5`).
 
 ### Rate limiting behavior (important)
 Gemini can return rate limits (HTTP 429). The RAG engine implements:
@@ -116,8 +117,9 @@ CarsRUS/
 
 ## Troubleshooting
 
-### “Configuration Error: Gemini API key is not set”
-- Set `gemini_api` in your environment (local) or in your Hugging Face Space secrets.
+### “Configuration Error” / no API key
+- Set at least one: **OPENROUTER_API_KEY** (recommended on HF: Settings → Repository secrets) or **gemini_api** in your environment or HF Space secrets.
+- If you see “OpenRouter key not set” in logs and get Gemini rate limits, add **OPENROUTER_API_KEY** in the Space secrets so the app uses OpenRouter first.
 
 ### Rate limit / 429 errors
 - Wait a bit and retry (the app also retries automatically).

app.py

@@ -65,9 +65,9 @@ def chat_function(message: str, history: list) -> str:
     if not api_key and not openrouter_key:
         yield """❌ **Configuration Error**
         
-Set at least one API key:
-• **OpenRouter** (faster): secret `OPENROUTER_API_KEY` or `openRouter_API_KEY` — [openrouter.ai](https://openrouter.ai)
-• **Gemini** (fallback): secret `gemini_api` — [Google AI Studio](https://aistudio.google.com/apikey)"""
+Set at least one API key (Space → Settings → Repository secrets):
+• **OpenRouter** (faster, avoids Gemini rate limits): add secret **OPENROUTER_API_KEY** — [openrouter.ai/keys](https://openrouter.ai/keys)
+• **Gemini** (fallback): secret **gemini_api** — [Google AI Studio](https://aistudio.google.com/apikey)"""
         return
     
     if not engine or not agent_graph:

rag_engine.py

@@ -636,13 +636,18 @@ class RAGEngine:
             self.last_request_time = time.time()
 
     def _get_openrouter_key(self) -> Optional[str]:
-        """OpenRouter API key from env (OPENROUTER_API_KEY or openRouter_API_KEY for .env)."""
-        return os.environ.get("OPENROUTER_API_KEY") or os.environ.get("openRouter_API_KEY")
+        """OpenRouter API key from env. HF Spaces: add Secret OPENROUTER_API_KEY. Local: .env openRouter_API_KEY."""
+        for name in ("OPENROUTER_API_KEY", "openRouter_API_KEY", "OPENROUTER_APIKEY", "OPENROUTER_KEY"):
+            v = os.environ.get(name)
+            if v and str(v).strip():
+                return str(v).strip()
+        return None
 
     def _call_openrouter(self, system_prompt: str, prompt: str, timeout_seconds: int = 28) -> Optional[str]:
         """Call OpenRouter API for a fast response. Returns text or None on failure."""
         key = self._get_openrouter_key()
         if not key or not key.strip():
+            PIPELINE_LOG.info("OpenRouter key not set - add Secret OPENROUTER_API_KEY in HF Space settings. Using Gemini.")
             return None
         url = "https://openrouter.ai/api/v1/chat/completions"
         # Prefer fast models on OpenRouter