Use OpenRouter DeepSeek with Gemini fallback

.env.example

@@ -1,12 +1,16 @@
 # To run the AI Tutor app (FastAPI backend)
+# Default chat path: DeepSeek V4 Flash through OpenRouter, with Gemini 2.5
+# Flash as the local application fallback if the OpenRouter call fails.
+OPENROUTER_API_KEY=...
+GEMINI_API_KEY=...
+# Gemini also accepts GOOGLE_API_KEY instead of GEMINI_API_KEY.
+GOOGLE_API_KEY=...
+
+# Optional alternate providers / utilities
 OPENAI_API_KEY=...
 ANTHROPIC_API_KEY=...
-GEMINI_API_KEY=...
 COHERE_API_KEY=...
-
-# Optional: open-model chat provider for cheap eval runs (e.g. deepseek:deepseek-v4-flash).
-# OpenRouter is an OpenAI-compatible gateway; DEEPSEEK_API_KEY hits the first-party API.
-OPENROUTER_API_KEY=...
+# DEEPSEEK_API_KEY hits the first-party DeepSeek API (not the default path).
 DEEPSEEK_API_KEY=...
 
 # Optional: trace agent/model/tool runs in LangSmith

README.md

@@ -48,7 +48,7 @@ Want to build this AI tutor yourself, end to end? Our [**Full Stack AI Engineer
    cp .env.example .env  # then edit values
    ```
 
-   The chat model is provider-agnostic, configured in `provider:model` format, for example `google-genai:gemini-3.5-flash`. Optional provider keys include `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `GOOGLE_API_KEY`. Anthropic support is wired through the `anthropic` SDK, and Gemini support is wired through Google’s `google-genai` SDK.
+   The chat model is provider-agnostic, configured in `provider:model` format. The default is `openrouter:deepseek/deepseek-v4-flash`, which uses OpenRouter first and falls back in-app to `google-genai:gemini-2.5-flash` when a Gemini key is configured. Set `OPENROUTER_API_KEY` plus `GEMINI_API_KEY` or `GOOGLE_API_KEY` for the default path. Optional provider keys include `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `DEEPSEEK_API_KEY` for non-default provider paths.
    To trace requests in LangSmith, set `LANGSMITH_API_KEY`. The app enables tracing automatically when that key is present unless `LANGSMITH_TRACING=false` is set.
 
 ### LangSmith Agent Tracing

app/chat_service.py

@@ -72,8 +72,10 @@ from .provider_events import (
 from .config import (
     BM25_INDEX_PATH,
     COURSE_SOURCE_KEYS,
+    DEEPSEEK_OPENROUTER_MODEL_NAME,
     DEFAULT_SELECTED_SOURCE_KEYS,
     DOCUMENT_DICT_PATH,
+    GEMINI_FALLBACK_MODEL_NAME,
     SOURCE_KEY_TO_LABEL,
     VECTOR_COLLECTION_NAME,
     VECTOR_DB_DIR,
@@ -787,8 +789,15 @@ def format_tool_args(args: Any) -> str:
     return str(args).strip()
 
 
-def build_chat_model(model_name: str, include_thoughts: bool = False):
-    provider_model = normalize_model_name(model_name)
+def _has_google_genai_key() -> bool:
+    return bool(os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY"))
+
+
+def _has_openrouter_key() -> bool:
+    return bool(os.environ.get("OPENROUTER_API_KEY"))
+
+
+def _build_chat_model_client(provider_model: str, include_thoughts: bool = False):
     provider, _, actual_model = provider_model.partition(":")
 
     if provider == "openai":
@@ -798,10 +807,9 @@ def build_chat_model(model_name: str, include_thoughts: bool = False):
         # stream_usage=True makes the streamed response carry token usage, so
         # context_stats / cost telemetry populates (some OpenAI-compatible
         # endpoints, e.g. Ollama, omit usage and leave token counts at 0).
-        # Routing is left to OpenRouter with fallbacks enabled: pinning a single
-        # provider with allow_fallbacks=False made batches die on a backend's
-        # transient 429 instead of routing around it. Fallback across providers
-        # is what keeps a long eval run reliable.
+        # Routing inside OpenRouter is left with its own fallbacks enabled:
+        # pinning a single provider with allow_fallbacks=False made batches die
+        # on a backend's transient 429 instead of routing around it.
         return ChatOpenAI(
             model=actual_model,
             temperature=1,
@@ -888,6 +896,39 @@ def build_chat_model(model_name: str, include_thoughts: bool = False):
     )
 
 
+def build_chat_model(model_name: str, include_thoughts: bool = False):
+    provider_model = normalize_model_name(model_name)
+    if provider_model != DEEPSEEK_OPENROUTER_MODEL_NAME:
+        return _build_chat_model_client(
+            provider_model,
+            include_thoughts=include_thoughts,
+        )
+    if not _has_openrouter_key() and _has_google_genai_key():
+        logger.warning(
+            "No OPENROUTER_API_KEY is set for %s; using Gemini fallback %s.",
+            DEEPSEEK_OPENROUTER_MODEL_NAME,
+            GEMINI_FALLBACK_MODEL_NAME,
+        )
+        return _build_chat_model_client(
+            GEMINI_FALLBACK_MODEL_NAME,
+            include_thoughts=include_thoughts,
+        )
+    model = _build_chat_model_client(provider_model, include_thoughts=include_thoughts)
+    if not _has_google_genai_key():
+        logger.warning(
+            "Gemini fallback %s is configured for %s, but no GOOGLE_API_KEY or "
+            "GEMINI_API_KEY is set; using OpenRouter only.",
+            GEMINI_FALLBACK_MODEL_NAME,
+            DEEPSEEK_OPENROUTER_MODEL_NAME,
+        )
+        return model
+    fallback = _build_chat_model_client(
+        GEMINI_FALLBACK_MODEL_NAME,
+        include_thoughts=include_thoughts,
+    )
+    return model.with_fallbacks([fallback])
+
+
 class GeminiServerSideToolsMiddleware(AgentMiddleware):
     """Enable server-side tool invocation for Gemini 3 tool combinations.
 

app/config.py

@@ -69,10 +69,16 @@ KB_INDEX_PATH = f"{KB_DIR}/wiki/index.md"
 KB_AGENTS_PATH = f"{KB_DIR}/AGENTS.md"
 # In-git template, copied into data/kb/AGENTS.md by ensure_kb_agents_md().
 KB_AGENTS_TEMPLATE_PATH = "data/scraping_scripts/kb_agents_template.md"
-DEFAULT_MODEL_NAME = "google-genai:gemini-3.5-flash"
+DEEPSEEK_OPENROUTER_MODEL_NAME = "openrouter:deepseek/deepseek-v4-flash"
+GEMINI_FALLBACK_MODEL_NAME = "google-genai:gemini-2.5-flash"
+DEFAULT_MODEL_NAME = DEEPSEEK_OPENROUTER_MODEL_NAME
 
 AVAILABLE_MODELS: tuple[dict[str, str], ...] = (
-    {"id": "google-genai:gemini-3.5-flash", "label": "Gemini 3.5 Flash"},
+    {
+        "id": DEEPSEEK_OPENROUTER_MODEL_NAME,
+        "label": "DeepSeek V4 Flash (OpenRouter)",
+    },
+    {"id": GEMINI_FALLBACK_MODEL_NAME, "label": "Gemini 2.5 Flash"},
     {"id": "anthropic:claude-haiku-4-5", "label": "Claude Haiku 4.5"},
 )
 
@@ -264,6 +270,8 @@ __all__ = [
     "DEFAULT_SELECTED_SOURCE_KEYS",
     "DEFAULT_SELECTED_SOURCES_UI",
     "DEFAULT_MODEL_NAME",
+    "DEEPSEEK_OPENROUTER_MODEL_NAME",
+    "GEMINI_FALLBACK_MODEL_NAME",
     "BM25_INDEX_PATH",
     "DOCUMENT_DICT_PATH",
     "KB_AGENTS_PATH",

tests/manual_e2e_langsmith.md

@@ -13,6 +13,7 @@ Run commands from the repository root.
 Required local artifacts and environment:
 
 - `.env` contains `COHERE_API_KEY`
+- `.env` contains `OPENROUTER_API_KEY`
 - `.env` contains `GEMINI_API_KEY` or `GOOGLE_API_KEY`
 - `.env` contains `LANGSMITH_API_KEY`
 - `.env` has `LANGSMITH_TRACING=true`
@@ -28,6 +29,7 @@ uv run dotenv -f .env run -- python - <<'PY'
 import os
 for key in [
     "COHERE_API_KEY",
+    "OPENROUTER_API_KEY",
     "GEMINI_API_KEY",
     "GOOGLE_API_KEY",
     "LANGSMITH_API_KEY",
@@ -93,7 +95,7 @@ cat >/tmp/ai_tutor_e2e_payload.json <<'JSON'
     "transformers"
   ],
   "enabledTools": [],
-  "model": "google-genai:gemini-3.5-flash",
+  "model": "openrouter:deepseek/deepseek-v4-flash",
   "includeReasoning": true,
   "threadId": ""
 }

tests/test_api.py

@@ -75,10 +75,25 @@ class ApiTestCase(unittest.TestCase):
         )
         self.assertEqual(transformers["label"], "Transformers Docs")
         self.assertEqual(transformers["shortLabel"], "Transformers")
-        # Gemini is the default model, so web search + url reading are present.
+        self.assertEqual(body["model"], "openrouter:deepseek/deepseek-v4-flash")
+        # DeepSeek via OpenRouter is the default model, so only local KB tools
+        # are exposed until a provider with built-in web tools is selected.
         tool_keys = {tool["key"] for tool in tools}
+        self.assertNotIn("web_search", tool_keys)
+        self.assertNotIn("url_context", tool_keys)
+
+    def test_list_tools_for_gemini_model(self) -> None:
+        with TestClient(app) as client:
+            response = client.get(
+                "/api/tools", params={"model": "google-genai:gemini-2.5-flash"}
+            )
+
+        self.assertEqual(response.status_code, 200)
+        tool_keys = {tool["key"] for tool in response.json()["tools"]}
+        self.assertIn("retrieval", tool_keys)
         self.assertIn("web_search", tool_keys)
         self.assertIn("url_context", tool_keys)
+        self.assertNotIn("web_fetch", tool_keys)
 
     def test_list_tools_for_anthropic_model(self) -> None:
         with TestClient(app) as client:
@@ -175,6 +190,7 @@ class ApiTestCase(unittest.TestCase):
             ],
             "sourceKeys": ["langchain", "transformers"],
             "enabledTools": ["web_search", "not_a_real_tool"],
+            "model": "google-genai:gemini-2.5-flash",
             "threadId": "thread_0",
         }
 
@@ -941,7 +957,9 @@ def live_chat_payload(
         "messages": messages,
         "sourceKeys": ["peft", "transformers"],
         "enabledTools": enabled_tools or [],
-        "model": os.getenv("LIVE_API_E2E_MODEL", "google-genai:gemini-3.5-flash"),
+        "model": os.getenv(
+            "LIVE_API_E2E_MODEL", "openrouter:deepseek/deepseek-v4-flash"
+        ),
         "includeReasoning": False,
         "threadId": thread_id,
     }

tests/test_chat_service.py

@@ -7,7 +7,9 @@ import unittest
 from unittest.mock import MagicMock, patch
 
 from langchain_core.messages import AIMessage, AIMessageChunk, HumanMessage, ToolMessage
+from langchain_core.runnables.fallbacks import RunnableWithFallbacks
 
+from app.config import DEEPSEEK_OPENROUTER_MODEL_NAME, GEMINI_FALLBACK_MODEL_NAME
 from app.chat_service import (
     THREAD_IDLE_TTL_SECONDS,
     _claim_kb_command_budget,
@@ -316,6 +318,51 @@ class ChatServiceTestCase(unittest.TestCase):
         self.assertGreater(reasoning.max_tokens, 8192)
         self.assertEqual(reasoning.thinking, {"type": "enabled", "budget_tokens": 2048})
 
+    def test_deepseek_openrouter_default_has_gemini_fallback(self) -> None:
+        with patch.dict(
+            os.environ,
+            {
+                "OPENROUTER_API_KEY": "openrouter-test-key",
+                "GEMINI_API_KEY": "gemini-test-key",
+            },
+            clear=True,
+        ):
+            model = build_chat_model(DEEPSEEK_OPENROUTER_MODEL_NAME)
+
+        self.assertIsInstance(model, RunnableWithFallbacks)
+        self.assertEqual(model.runnable.model_name, "deepseek/deepseek-v4-flash")
+        self.assertEqual(len(model.fallbacks), 1)
+        self.assertEqual(
+            model.fallbacks[0].model,
+            GEMINI_FALLBACK_MODEL_NAME.partition(":")[2],
+        )
+
+    def test_deepseek_openrouter_default_skips_fallback_without_gemini_key(
+        self,
+    ) -> None:
+        with patch.dict(
+            os.environ,
+            {"OPENROUTER_API_KEY": "openrouter-test-key"},
+            clear=True,
+        ):
+            model = build_chat_model(DEEPSEEK_OPENROUTER_MODEL_NAME)
+
+        self.assertNotIsInstance(model, RunnableWithFallbacks)
+        self.assertEqual(model.model_name, "deepseek/deepseek-v4-flash")
+
+    def test_deepseek_openrouter_default_uses_gemini_when_openrouter_key_missing(
+        self,
+    ) -> None:
+        with patch.dict(
+            os.environ,
+            {"GEMINI_API_KEY": "gemini-test-key"},
+            clear=True,
+        ):
+            model = build_chat_model(DEEPSEEK_OPENROUTER_MODEL_NAME)
+
+        self.assertNotIsInstance(model, RunnableWithFallbacks)
+        self.assertEqual(model.model, GEMINI_FALLBACK_MODEL_NAME.partition(":")[2])
+
     def test_kb_command_budget_blocks_after_limit(self) -> None:
         session_id = "test_budget_session"
         _clear_kb_command_budget(session_id)

tests/test_config.py

@@ -11,6 +11,17 @@ import pytest
 from app import config
 
 
+def test_default_chat_model_prefers_deepseek_openrouter_with_gemini_fallback() -> None:
+    assert config.DEFAULT_MODEL_NAME == config.DEEPSEEK_OPENROUTER_MODEL_NAME
+    assert config.DEFAULT_MODEL_NAME == "openrouter:deepseek/deepseek-v4-flash"
+    assert config.GEMINI_FALLBACK_MODEL_NAME == "google-genai:gemini-2.5-flash"
+    assert config.AVAILABLE_MODELS[0]["id"] == config.DEFAULT_MODEL_NAME
+    assert any(
+        model["id"] == config.GEMINI_FALLBACK_MODEL_NAME
+        for model in config.AVAILABLE_MODELS
+    )
+
+
 def _patched_bundle(tmp_path: Path) -> ExitStack:
     db_dir = tmp_path / "chroma"
     kb_dir = tmp_path / "kb"