Switch the default chat model to DeepSeek V4 Flash via OpenRouter

The first-party DeepSeek account is deliberately unfunded and the team is
standardizing on OpenRouter, whose cheap endpoints also price a typical
agentic turn ~40-70% below first-party rates: output and cache-miss input
dominate our bill, and DeepSeek's ~31x first-party cache-hit discount does
not pass through OpenRouter's third-party hosts anyway (verified against
OpenRouter's endpoint listing, 2026-08-25).

- DEFAULT_MODEL_NAME / AVAILABLE_MODELS -> openrouter:deepseek/deepseek-v4-flash;
the first-party deepseek: path stays supported for experiments
- New TutorChatOpenRouter adapter preserves OpenRouter's unified streamed
`reasoning` field (mapped into the DeepSeek-style reasoning_content slot)
and the client sends the model-agnostic reasoning toggle explicitly
- "openrouter" joins PRODUCTION_LONG_CONTEXT_PROVIDERS so prod_v2 serves
the default path instead of silently downgrading to the legacy preset
- MODEL_PRICING OpenRouter row refreshed to the verified headline endpoint
rate (checked 2026-08-25); docs, runbook, and env templates updated

Verified live: reasoning streams interleaved with run_kb_command calls,
prompt caching passes through (cached_tokens populated in context_stats),
thread continuation works, and the live E2E suite passes. The Space needs
the OPENROUTER_API_KEY secret; until it is set, key substitution serves
the Gemini fallback.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.env.example

@@ -1,17 +1,18 @@
 # To run the AI Tutor app (FastAPI backend)
 # COHERE_API_KEY is always required (embeddings + rerank for retrieval).
 COHERE_API_KEY=...
-# Default chat path: DeepSeek V4 Flash through the first-party DeepSeek API,
-# with Gemini 3.5 Flash Lite as the local application fallback if DeepSeek fails.
-DEEPSEEK_API_KEY=...
+# Default chat path: DeepSeek V4 Flash via OpenRouter, with Gemini 3.5 Flash
+# Lite as the local application fallback if OpenRouter fails.
+OPENROUTER_API_KEY=...
 GEMINI_API_KEY=...
 # Gemini also accepts GOOGLE_API_KEY instead of GEMINI_API_KEY.
 GOOGLE_API_KEY=...
 
-# Optional alternate providers
+# Optional alternate providers (DEEPSEEK_API_KEY is the retired first-party
+# DeepSeek path, kept for experiments)
 OPENAI_API_KEY=...
 ANTHROPIC_API_KEY=...
-OPENROUTER_API_KEY=...
+DEEPSEEK_API_KEY=...
 
 # Optional: Slack-compatible incoming-webhook URL for ops alerts (provider
 # outages and account-state errors like an unfunded or revoked key). Alerts

AGENTS.md

@@ -6,7 +6,7 @@ This is the **canonical, tool-agnostic** instruction file for the repo. `CLAUDE.
 
 AI tutor for applied AI, LLMs, RAG, and Python. **Agentic RAG**: a LangChain/LangGraph agent grounds answers in a curated corpus of course + library docs, can browse a local file-based knowledge base, and (optionally) search the live web. One frontend: a **Next.js** UI (`frontend/`), served by a **FastAPI** backend (`app/api.py`) that streams in the Vercel AI SDK UI-message protocol. (A Gradio UI existed historically; it was removed to keep one rendering path.)
 
-ChromaDB for vectors; Cohere for embeddings/rerank; chat model is provider-configurable (DeepSeek V4 Flash through the first-party API by default, with a rescue-only in-app fallback to Gemini 3.5 Flash Lite when a Gemini key is set; Anthropic, OpenAI, and OpenRouter-compatible models are supported in code but not user-selectable). **A conversation cannot change model mid-thread** — checkpoints store provider-native message blocks that no other provider can replay; see `build_chat_model` in `app/chat_service.py`. Python ≥3.13, managed with `uv`.
+ChromaDB for vectors; Cohere for embeddings/rerank; chat model is provider-configurable (DeepSeek V4 Flash via OpenRouter by default, with a rescue-only in-app fallback to Gemini 3.5 Flash Lite when a Gemini key is set; the first-party DeepSeek API, Anthropic, and OpenAI remain supported in code but are not user-selectable). **A conversation cannot change model mid-thread** — checkpoints store provider-native message blocks that no other provider can replay; see `build_chat_model` in `app/chat_service.py`. Python ≥3.13, managed with `uv`.
 
 ## Key URLs
 
@@ -62,7 +62,7 @@ Runtime guidance the agent follows is in `data/kb/AGENTS.md` (injected into the
 
 ## Sources & config
 
-`data/scraping_scripts/source_registry.py` is the **single source of truth** for sources (`SOURCE_CONFIGS`, key groupings, UI labels, defaults); `app/config.py` re-exports them and the frontend derives the picker from it (via `/api/tools`). Docs sources ingest via the GitHub API or `llms.txt`; course sources are Notion exports. To add a source: add it to the registry (+ the relevant grouping tuples), then run the matching workflow — no separate UI edit needed. Models live in `config.AVAILABLE_MODELS` (currently only the default `deepseek:deepseek-v4-flash`; Anthropic Claude Haiku 4.5 and OpenAI remain supported in code but are not selectable). **`FALLBACK_MODEL_NAME` (`google-genai:gemini-3.5-flash-lite`) is deliberately NOT in `AVAILABLE_MODELS`**: it serves real traffic as the DeepSeek rescue path but is not user-selectable. Unlike the previous fallback (`gemini-2.5-flash`, a pre-Gemini-3 model that could not combine Gemini's built-in web tools with our two custom tools and so was one web-search toggle from a 400 if ever selected), 3.5 Flash Lite is a Gemini 3-series model with "tool context circulation", so keeping it fallback-only is now a product choice (one selectable model plus a rescue path), not an API constraint. Either way the fallback never receives web tools: they are bound from the requested model (DeepSeek), which has none. `build_chat_model` in `app/chat_service.py` builds exactly ONE provider's client (it accepts `deepseek:` for the first-party API, `openrouter:` for compatible experiment models, and `ollama:` for local SLM experiments, with pricing in `app/telemetry.MODEL_PRICING`); no fallback is wired at the client layer. The rescue is turn-level in `stream_chat`: an outage-class failure (connectivity/timeout/429/5xx) before the first streamed chunk retries the turn on `FALLBACK_MODEL_NAME` through the plain-text thread branch, so the pairing is free to be ANY two provider:model strings. `resolve_served_model_name` substitutes the fallback outright when the default model's provider key is missing.
+`data/scraping_scripts/source_registry.py` is the **single source of truth** for sources (`SOURCE_CONFIGS`, key groupings, UI labels, defaults); `app/config.py` re-exports them and the frontend derives the picker from it (via `/api/tools`). Docs sources ingest via the GitHub API or `llms.txt`; course sources are Notion exports. To add a source: add it to the registry (+ the relevant grouping tuples), then run the matching workflow — no separate UI edit needed. Models live in `config.AVAILABLE_MODELS` (currently only the default `openrouter:deepseek/deepseek-v4-flash` — DeepSeek V4 Flash via OpenRouter, which routes across third-party hosts; the first-party `deepseek:` path, Anthropic Claude Haiku 4.5, and OpenAI remain supported in code but are not selectable. The first-party DeepSeek account is deliberately unfunded since 2026-08, when its 402s hard-failed prod and the team standardized on OpenRouter — also cheaper per agentic turn at OpenRouter's cheap endpoints, though DeepSeek's ~31x first-party cache-hit discount does not pass through; see `MODEL_PRICING`). **`FALLBACK_MODEL_NAME` (`google-genai:gemini-3.5-flash-lite`) is deliberately NOT in `AVAILABLE_MODELS`**: it serves real traffic as the default model's rescue path but is not user-selectable. Unlike the previous fallback (`gemini-2.5-flash`, a pre-Gemini-3 model that could not combine Gemini's built-in web tools with our two custom tools and so was one web-search toggle from a 400 if ever selected), 3.5 Flash Lite is a Gemini 3-series model with "tool context circulation", so keeping it fallback-only is now a product choice (one selectable model plus a rescue path), not an API constraint. Either way the fallback never receives web tools: they are bound from the requested model (DeepSeek via OpenRouter), which has none. `build_chat_model` in `app/chat_service.py` builds exactly ONE provider's client (it accepts `openrouter:` for the OpenRouter gateway — served by `TutorChatOpenRouter`, which preserves OpenRouter's unified streamed `reasoning` field and sends its model-agnostic `reasoning` toggle — plus `deepseek:` for the first-party API and `ollama:` for local SLM experiments, with pricing in `app/telemetry.MODEL_PRICING`); no fallback is wired at the client layer. The rescue is turn-level in `stream_chat`: an outage-class failure (connectivity/timeout/429/5xx) or an account-state failure (401/402/403 — an unfunded or revoked key, see `is_account_state_error`) before the first streamed chunk retries the turn on `FALLBACK_MODEL_NAME` through the plain-text thread branch, so the pairing is free to be ANY two provider:model strings. Both failure classes page ops through `app/alerts.py` (Slack-compatible webhook via `AI_TUTOR_ALERT_WEBHOOK_URL`, throttled per class), and each turn's `context_stats` reports `requested_model`/`served_model`/`rescued` so a fallback-served turn is never invisible. `resolve_served_model_name` substitutes the fallback outright when the default model's provider key is missing.
 
 Memory policy is deliberately owned by `app/memory_presets.py`, not `app/config.py`. `PRODUCTION_MEMORY_PRESET` is the single primary-policy switch, `PRODUCTION_FALLBACK_MEMORY_PRESET` covers providers that cannot use it safely, and `PRODUCTION_LONG_CONTEXT_PROVIDERS` defines the model-aware allowlist. Keep historical presets immutable because saved eval runs refer to them by name.
 
@@ -97,7 +97,7 @@ uv run -m data.scraping_scripts.retire_source_workflow --sources KEY [--dry-run
 
 ## Environment variables
 
-Chat runtime: `COHERE_API_KEY` (retrieval; always required), `DEEPSEEK_API_KEY` for the default model plus `GEMINI_API_KEY`/`GOOGLE_API_KEY` to enable its in-app Gemini 3.5 Flash Lite fallback, and the corresponding provider key when selecting another model (`GEMINI_API_KEY`/`GOOGLE_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENAI_API_KEY`; `OPENROUTER_API_KEY` is used by OpenRouter experiment models), plus `HF_TOKEN` for first-start download of the full private bundle. Without `HF_TOKEN`, cold start falls back to the public docs-only bundle (documentation sources only, course content hidden). Optional: `LANGSMITH_*` (tracing), `AI_TUTOR_API_PORT`/`HOST`/`CORS_ALLOW_ORIGINS`, `AI_TUTOR_KB_DIR`, and `NEXT_PUBLIC_AI_TUTOR_API_BASE_URL`. `AI_TUTOR_MEMORY_PRESET` is an optional deployment-wide override, not the normal default; leave it unset to retain model-aware production selection. Data workflows also need `GITHUB_TOKEN` and `GEMINI_API_KEY`/`GOOGLE_API_KEY` (context generation). See `.env.example`.
+Chat runtime: `COHERE_API_KEY` (retrieval; always required), `OPENROUTER_API_KEY` for the default model plus `GEMINI_API_KEY`/`GOOGLE_API_KEY` to enable its in-app Gemini 3.5 Flash Lite fallback, and the corresponding provider key when selecting another model (`GEMINI_API_KEY`/`GOOGLE_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `DEEPSEEK_API_KEY` for the retired first-party path), plus `HF_TOKEN` for first-start download of the full private bundle. Without `HF_TOKEN`, cold start falls back to the public docs-only bundle (documentation sources only, course content hidden). Optional: `AI_TUTOR_ALERT_WEBHOOK_URL` (Slack-compatible webhook for provider outage/account-state ops alerts; unset = log-only), `LANGSMITH_*` (tracing), `AI_TUTOR_API_PORT`/`HOST`/`CORS_ALLOW_ORIGINS`, `AI_TUTOR_KB_DIR`, and `NEXT_PUBLIC_AI_TUTOR_API_BASE_URL`. `AI_TUTOR_MEMORY_PRESET` is an optional deployment-wide override, not the normal default; leave it unset to retain model-aware production selection. Data workflows also need `GITHUB_TOKEN` and `GEMINI_API_KEY`/`GOOGLE_API_KEY` (context generation). See `.env.example`.
 
 ## Deployment
 
@@ -106,7 +106,7 @@ One HF Space runs the image (`Dockerfile`: FastAPI + Next.js static export, `rip
 - **Prod — `ai-tutor-chatbot`** (public): `.github/workflows/sync-to-hf.yml` force-pushes on **every push to `main`** (docs/markdown-only and scraping-script-only pushes are skipped via `paths-ignore`). Merging to `main` IS deploying to public prod: keep `main` releasable and verify before merging (`uv run pytest`, and the live E2E suite for agent/API changes).
 - **Manual redeploy**: `.github/workflows/deploy-prod-to-hf.yml` (Actions tab → "Redeploy prod to Hugging Face (manual)") force-pushes a chosen ref without a new commit — for secret rotations, retrying a failed sync run, or rolling back to an older branch/tag.
 
-The Space needs the runtime secrets (`COHERE_API_KEY`, model provider key, `HF_TOKEN`, optional `LANGSMITH_*`) configured in its HF settings.
+The Space needs the runtime secrets (`COHERE_API_KEY`, `OPENROUTER_API_KEY`, `GEMINI_API_KEY`, `HF_TOKEN`, optional `LANGSMITH_*` and `AI_TUTOR_ALERT_WEBHOOK_URL`) configured in its HF settings.
 
 ## Conventions
 
@@ -115,7 +115,7 @@ The Space needs the runtime secrets (`COHERE_API_KEY`, model provider key, `HF_T
 
 ## Gotchas
 
-- **One thread is one provider — a conversation cannot mix models while keeping tool outputs and thought signatures.** A thread's checkpoint stores *provider-native* messages: Gemini reasoning parts carry thought signatures, Anthropic thinking blocks carry a required cryptographic `signature`, and each provider's server-side tool calls are its own block types. Replaying one provider's history to another is a hard 400, not a degraded answer — verified both ways (Gemini history → DeepSeek 400s; Gemini history → Anthropic 400s with `messages.1.content.0.thinking.signature: Field required`). So you cannot "just send the payload to another provider": a fallback, a retry-on-another-provider, or mid-conversation switching **must not** be wired at the model/client layer (a `with_fallbacks` client only works for pairings whose primary happens to write lowest-common-denominator output — an overfit trap this repo shipped once and removed). The only safe path is `sync_thread_with_history`'s branch to a fresh thread seeded with plain text, which drops the unportable state (tool outputs, summaries, thinking) on purpose — and it is the ONE mechanism for all cross-provider movement: the turn-level outage rescue in `stream_chat`, a config repoint, a model deprecation. The frontend model picker locks after the first message for this reason. The backend enforces it independently: `sync_thread_with_history` records which provider actually served each turn (`_THREAD_PROVIDERS`, taken from the served model, since rescue and key substitution mean served ≠ requested) and branches to a fresh plain-text thread when the next turn's provider differs — so a rescued turn's Gemini-owned thread returns to DeepSeek on the next healthy turn instead of stranding on the pricier provider (roughly 3x on output; see `MODEL_PRICING` in `app/telemetry.py`).
+- **One thread is one provider — a conversation cannot mix models while keeping tool outputs and thought signatures.** A thread's checkpoint stores *provider-native* messages: Gemini reasoning parts carry thought signatures, Anthropic thinking blocks carry a required cryptographic `signature`, and each provider's server-side tool calls are its own block types. Replaying one provider's history to another is a hard 400, not a degraded answer — verified both ways (Gemini history → DeepSeek 400s; Gemini history → Anthropic 400s with `messages.1.content.0.thinking.signature: Field required`). So you cannot "just send the payload to another provider": a fallback, a retry-on-another-provider, or mid-conversation switching **must not** be wired at the model/client layer (a `with_fallbacks` client only works for pairings whose primary happens to write lowest-common-denominator output — an overfit trap this repo shipped once and removed). The only safe path is `sync_thread_with_history`'s branch to a fresh thread seeded with plain text, which drops the unportable state (tool outputs, summaries, thinking) on purpose — and it is the ONE mechanism for all cross-provider movement: the turn-level outage/account-state rescue in `stream_chat`, a config repoint, a model deprecation. The frontend model picker locks after the first message for this reason. The backend enforces it independently: `sync_thread_with_history` records which provider actually served each turn (`_THREAD_PROVIDERS`, taken from the served model, since rescue and key substitution mean served ≠ requested) and branches to a fresh plain-text thread when the next turn's provider differs — so a rescued turn's Gemini-owned thread returns to the default model on the next healthy turn instead of stranding on the pricier provider (see `MODEL_PRICING` in `app/telemetry.py`).
 - **Provider-native web tools are bound from the requested model, and not every model can mix them with our custom tools.** Gemini needs "tool context circulation" (Gemini 3+) to combine `google_search`/`url_context` with function tools, so pre-3 Gemini gets no web toggles (`supports_gemini_tool_combination`). Anthropic combines them natively, but `allowed_callers: ["direct"]` is load-bearing — without it Haiku 4.5 400s on programmatic tool calling.
 - **Context generation uses Gemini**; embeddings/rerank use **Cohere**; the chat model is provider-configurable. OpenAI is required only when explicitly selected.
 - `data/kb/` and `data/chroma-db-all_sources/` are build artifacts — never commit or hand-edit; regenerate or re-download.

app/chat_service.py

@@ -44,6 +44,7 @@ from .agent_tracing import langsmith_deployment_identity
 from .chat_types import ChatEvent, ChatRequest, ChatTurn, SourceMatch
 from .alerts import send_ops_alert
 from .deepseek_chat import TutorChatDeepSeek
+from .openrouter_chat import TutorChatOpenRouter
 from .memory_presets import (
     MemoryConfig,
     resolve_memory_preset,
@@ -960,6 +961,12 @@ def is_deepseek_model(model_name: str) -> bool:
     return provider == "deepseek"
 
 
+def is_openrouter_model(model_name: str) -> bool:
+    provider_model = normalize_model_name(model_name)
+    provider, _, _actual_model = provider_model.partition(":")
+    return provider == "openrouter"
+
+
 def supports_gemini_tool_combination(model_name: str) -> bool:
     """True when a Gemini model can mix built-in tools with function tools.
 
@@ -1032,12 +1039,17 @@ def _build_chat_model_client(provider_model: str, include_thoughts: bool = False
         # 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(
+        # ``reasoning`` is OpenRouter's model-agnostic thinking toggle; sending
+        # it explicitly (rather than omitting it) pins the behavior across the
+        # gateway's per-host defaults, and the adapter preserves the streamed
+        # thought text that plain ChatOpenAI would discard.
+        return TutorChatOpenRouter(
             model=actual_model,
             temperature=1,
             base_url="https://openrouter.ai/api/v1",
             api_key=os.environ.get("OPENROUTER_API_KEY"),
             stream_usage=True,
+            extra_body={"reasoning": {"enabled": bool(include_thoughts)}},
             # Long agentic sessions fire hundreds of calls against OpenRouter's
             # shared pool; bump retries (with the client's exponential backoff)
             # to ride out transient upstream 429s instead of failing a whole
@@ -2876,6 +2888,9 @@ async def stream_chat(request: ChatRequest) -> AsyncIterator[ChatEvent]:
             is_google_genai_model(serving_model_name)
             or is_anthropic_model(serving_model_name)
             or is_deepseek_model(serving_model_name)
+            # OpenRouter's unified `reasoning` request field works across the
+            # models it routes; hosts that don't support it ignore it.
+            or is_openrouter_model(serving_model_name)
         )
         # Gemini streams each thought summary as one complete block; Anthropic
         # streams partial fragments of a single thought. The encoder uses this

app/config.py

@@ -70,7 +70,14 @@ 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"
 DEEPSEEK_DIRECT_MODEL_NAME = "deepseek:deepseek-v4-flash"
-DEFAULT_MODEL_NAME = DEEPSEEK_DIRECT_MODEL_NAME
+# DeepSeek V4 Flash via OpenRouter is the default chat path since 2026-08:
+# the first-party DeepSeek account is deliberately unfunded (its 402s
+# hard-failed prod for two days), and OpenRouter's cheap endpoints price a
+# typical agentic turn well below first-party rates anyway. OpenRouter serves
+# this model only through third-party hosts, so DeepSeek's ~31x first-party
+# cache-hit discount does NOT apply there; see MODEL_PRICING in app/telemetry.
+OPENROUTER_DEEPSEEK_MODEL_NAME = "openrouter:deepseek/deepseek-v4-flash"
+DEFAULT_MODEL_NAME = OPENROUTER_DEEPSEEK_MODEL_NAME
 
 # Two distinct roles, deliberately kept apart:
 #
@@ -96,7 +103,7 @@ FALLBACK_MODEL_NAME = "google-genai:gemini-3.5-flash-lite"
 
 AVAILABLE_MODELS: tuple[dict[str, str], ...] = (
     {
-        "id": DEEPSEEK_DIRECT_MODEL_NAME,
+        "id": OPENROUTER_DEEPSEEK_MODEL_NAME,
         "label": "DeepSeek V4 Flash",
     },
 )
@@ -294,6 +301,7 @@ __all__ = [
     "DEFAULT_MODEL_NAME",
     "DEEPSEEK_DIRECT_MODEL_NAME",
     "FALLBACK_MODEL_NAME",
+    "OPENROUTER_DEEPSEEK_MODEL_NAME",
     "BM25_INDEX_PATH",
     "DOCUMENT_DICT_PATH",
     "KB_AGENTS_PATH",

app/memory_presets.py

@@ -357,7 +357,13 @@ MEMORY_PRESETS: dict[str, MemoryConfig] = {
 # example, has a 200k input window and cannot safely wait for an 800k trigger).
 PRODUCTION_MEMORY_PRESET = "prod_v2"
 PRODUCTION_FALLBACK_MEMORY_PRESET = "prod"
-PRODUCTION_LONG_CONTEXT_PROVIDERS = frozenset({"deepseek", "google-genai"})
+# "openrouter" is here for the default DeepSeek-via-OpenRouter chat model.
+# The gate is provider-granular, so any openrouter:* model resolves to the
+# long-context production preset by default; eval runs pin presets by name,
+# so in practice this only decides the served chat path.
+PRODUCTION_LONG_CONTEXT_PROVIDERS = frozenset(
+    {"deepseek", "google-genai", "openrouter"}
+)
 
 # Backward-compatible import for callers that need a single default name. New
 # runtime code should call resolve_memory_preset(..., model_name=...) so model

app/openrouter_chat.py

@@ -0,0 +1,44 @@
+"""OpenRouter chat-model compatibility helpers.
+
+OpenRouter normalizes reasoning across the models it routes: requests take a
+unified ``reasoning`` object (``{"enabled": ...}``) regardless of the
+underlying model, and streamed deltas carry the thought text in a
+``reasoning`` field (verified live against ``deepseek/deepseek-v4-flash``,
+2026-08-25). The stock ``ChatOpenAI`` wrapper drops that nonstandard delta
+field, so this subclass maps it into
+``additional_kwargs["reasoning_content"]`` -- the same slot the DeepSeek
+adapter uses -- and ``provider_events.extract_reasoning_deltas`` then works
+unchanged for either provider.
+"""
+
+from __future__ import annotations
+
+from langchain_core.messages import AIMessageChunk
+from langchain_core.outputs import ChatGenerationChunk
+from langchain_openai import ChatOpenAI
+
+
+class TutorChatOpenRouter(ChatOpenAI):
+    """ChatOpenAI that preserves OpenRouter's streamed ``reasoning`` field."""
+
+    def _convert_chunk_to_generation_chunk(
+        self,
+        chunk: dict,
+        default_chunk_class: type,
+        base_generation_info: dict | None,
+    ) -> ChatGenerationChunk | None:
+        generation_chunk = super()._convert_chunk_to_generation_chunk(
+            chunk,
+            default_chunk_class,
+            base_generation_info,
+        )
+        if generation_chunk is None:
+            return None
+        choices = chunk.get("choices") or []
+        if choices and isinstance(generation_chunk.message, AIMessageChunk):
+            reasoning = (choices[0].get("delta") or {}).get("reasoning")
+            if reasoning:
+                generation_chunk.message.additional_kwargs["reasoning_content"] = (
+                    reasoning
+                )
+        return generation_chunk

app/telemetry.py

@@ -256,11 +256,18 @@ MODEL_PRICING: dict[str, ModelPricing] = {
     "gpt-5.6-luna": ModelPricing(
         input=0.20, output=1.20, cache_read=0.02, cache_write=0.25
     ),
-    # DeepSeek-V4-Flash via OpenRouter (slug "deepseek/deepseek-v4-flash").
-    # Kept for the openrouter provider path; unused now that evals run on the
-    # first-party API. Note OpenRouter's own list price differs ($0.09/$0.18).
+    # DeepSeek-V4-Flash via OpenRouter (slug "deepseek/deepseek-v4-flash") --
+    # the DEFAULT chat path since 2026-08. OpenRouter routes across ~17
+    # third-party hosts whose prices vary widely (input $0.068-$0.44, output
+    # $0.168-$1.32 per 1M); default routing favors the cheap end, so this row
+    # stores the headline (cheapest-endpoint) rate and expensive-host turns
+    # are underestimated. Caching is implicit with no write surcharge; cache
+    # reads bill at the endpoint's own rate (~0.25x its input price), NOT
+    # DeepSeek first-party's ~31x discount -- DeepSeek does not serve this
+    # model on OpenRouter. Checked 2026-08-25 against
+    # openrouter.ai/api/v1/models/deepseek/deepseek-v4-flash/endpoints.
     "deepseek/deepseek-v4-flash": ModelPricing(
-        input=0.14, output=0.28, cache_read=0.0028
+        input=0.0679, output=0.168, cache_read=0.0168
     ),
     # DeepSeek-V4-Flash, DeepSeek FIRST-PARTY API (base https://api.deepseek.com,
     # model id "deepseek-v4-flash" — the id the API echoes back, so this is the

frontend/components/chat-shell.test.tsx

@@ -151,7 +151,7 @@ vi.mock("@/components/chat-message", () => ({
 
 import { ChatShell } from "@/components/chat-shell";
 
-const DEFAULT_MODEL = "deepseek:deepseek-v4-flash";
+const DEFAULT_MODEL = "openrouter:deepseek/deepseek-v4-flash";
 const CLAUDE_MODEL = "anthropic:claude-haiku-4-5";
 
 const toolsResponse = {

tests/manual_e2e_langsmith.md

@@ -13,7 +13,7 @@ Run commands from the repository root.
 Required local artifacts and environment:
 
 - `.env` contains `COHERE_API_KEY`
-- `.env` contains `DEEPSEEK_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`
@@ -31,7 +31,7 @@ uv run dotenv -f .env run -- python - <<'PY'
 import os
 for key in [
     "COHERE_API_KEY",
-    "DEEPSEEK_API_KEY",
+    "OPENROUTER_API_KEY",
     "GEMINI_API_KEY",
     "GOOGLE_API_KEY",
     "LANGSMITH_API_KEY",
@@ -97,7 +97,7 @@ cat >/tmp/ai_tutor_e2e_payload.json <<'JSON'
     "transformers"
   ],
   "enabledTools": [],
-  "model": "deepseek:deepseek-v4-flash",
+  "model": "openrouter:deepseek/deepseek-v4-flash",
   "includeReasoning": true,
   "threadId": ""
 }

tests/test_api.py

@@ -75,7 +75,7 @@ class ApiTestCase(unittest.TestCase):
         )
         self.assertEqual(transformers["label"], "Transformers Docs")
         self.assertEqual(transformers["shortLabel"], "Transformers")
-        self.assertEqual(body["model"], "deepseek:deepseek-v4-flash")
+        self.assertEqual(body["model"], "openrouter:deepseek/deepseek-v4-flash")
         # DeepSeek direct 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}
@@ -1226,7 +1226,9 @@ def live_chat_payload(
         "messages": messages,
         "sourceKeys": ["peft", "transformers"],
         "enabledTools": enabled_tools or [],
-        "model": os.getenv("LIVE_API_E2E_MODEL", "deepseek:deepseek-v4-flash"),
+        "model": os.getenv(
+            "LIVE_API_E2E_MODEL", "openrouter:deepseek/deepseek-v4-flash"
+        ),
         "includeReasoning": False,
         "threadId": thread_id,
     }

tests/test_chat_service.py

@@ -8,8 +8,14 @@ from unittest.mock import MagicMock, patch
 
 from langchain_core.messages import AIMessage, AIMessageChunk, HumanMessage, ToolMessage
 
-from app.config import DEEPSEEK_DIRECT_MODEL_NAME, FALLBACK_MODEL_NAME
+from app.config import (
+    DEEPSEEK_DIRECT_MODEL_NAME,
+    DEFAULT_MODEL_NAME,
+    FALLBACK_MODEL_NAME,
+    OPENROUTER_DEEPSEEK_MODEL_NAME,
+)
 from app.deepseek_chat import TutorChatDeepSeek
+from app.openrouter_chat import TutorChatOpenRouter
 from app.chat_service import (
     THREAD_IDLE_TTL_SECONDS,
     _claim_kb_command_budget,
@@ -602,6 +608,50 @@ class ChatServiceTestCase(unittest.TestCase):
             {"thinking": {"type": "enabled"}},
         )
 
+    def test_openrouter_model_uses_adapter_with_explicit_reasoning_toggle(
+        self,
+    ) -> None:
+        with patch.dict(
+            os.environ,
+            {"OPENROUTER_API_KEY": "openrouter-test-key"},
+            clear=True,
+        ):
+            plain = build_chat_model(OPENROUTER_DEEPSEEK_MODEL_NAME)
+            thinking = build_chat_model(
+                OPENROUTER_DEEPSEEK_MODEL_NAME, include_thoughts=True
+            )
+
+        self.assertIsInstance(plain, TutorChatOpenRouter)
+        self.assertEqual(plain.model_name, "deepseek/deepseek-v4-flash")
+        self.assertEqual(plain.extra_body, {"reasoning": {"enabled": False}})
+        self.assertEqual(thinking.extra_body, {"reasoning": {"enabled": True}})
+
+    def test_openrouter_stream_preserves_reasoning_deltas(self) -> None:
+        model = TutorChatOpenRouter(
+            model="deepseek/deepseek-v4-flash",
+            api_key="openrouter-test-key",
+            base_url="https://openrouter.ai/api/v1",
+        )
+        # The delta shape OpenRouter actually streams (verified live
+        # 2026-08-25): thought text arrives in `reasoning`, not DeepSeek's
+        # `reasoning_content`.
+        chunk = {
+            "id": "gen-1",
+            "model": "deepseek/deepseek-v4-flash",
+            "choices": [
+                {"index": 0, "delta": {"content": "", "reasoning": "We compute "}}
+            ],
+        }
+
+        generation_chunk = model._convert_chunk_to_generation_chunk(
+            chunk, AIMessageChunk, None
+        )
+
+        self.assertEqual(
+            generation_chunk.message.additional_kwargs["reasoning_content"],
+            "We compute ",
+        )
+
     def test_deepseek_thinking_tool_call_replays_reasoning_content(self) -> None:
         model = TutorChatDeepSeek(
             model="deepseek-v4-flash",
@@ -641,7 +691,7 @@ class ChatServiceTestCase(unittest.TestCase):
             {"GEMINI_API_KEY": "gemini-test-key"},
             clear=True,
         ):
-            served = resolve_served_model_name(DEEPSEEK_DIRECT_MODEL_NAME)
+            served = resolve_served_model_name(DEFAULT_MODEL_NAME)
             model = build_chat_model(served)
 
         self.assertEqual(served, FALLBACK_MODEL_NAME)
@@ -650,33 +700,33 @@ class ChatServiceTestCase(unittest.TestCase):
     def test_resolve_served_model_name_keeps_default_when_key_present(self) -> None:
         with patch.dict(
             os.environ,
-            {"DEEPSEEK_API_KEY": "deepseek-test-key"},
+            {"OPENROUTER_API_KEY": "openrouter-test-key"},
             clear=True,
         ):
             self.assertEqual(
-                resolve_served_model_name(DEEPSEEK_DIRECT_MODEL_NAME),
-                DEEPSEEK_DIRECT_MODEL_NAME,
+                resolve_served_model_name(DEFAULT_MODEL_NAME),
+                DEFAULT_MODEL_NAME,
             )
 
     def test_rescue_model_covers_only_the_default_model(self) -> None:
         with patch.dict(
             os.environ,
             {
-                "DEEPSEEK_API_KEY": "deepseek-test-key",
+                "OPENROUTER_API_KEY": "openrouter-test-key",
                 "GEMINI_API_KEY": "gemini-test-key",
             },
             clear=True,
         ):
-            self.assertEqual(
-                rescue_model_for(DEEPSEEK_DIRECT_MODEL_NAME), FALLBACK_MODEL_NAME
-            )
-            # A deliberately selected non-default model must fail visibly.
+            self.assertEqual(rescue_model_for(DEFAULT_MODEL_NAME), FALLBACK_MODEL_NAME)
+            # A deliberately selected non-default model must fail visibly --
+            # including the retired first-party DeepSeek path.
             self.assertIsNone(rescue_model_for("anthropic:claude-haiku-4-5"))
+            self.assertIsNone(rescue_model_for(DEEPSEEK_DIRECT_MODEL_NAME))
         with patch.dict(
-            os.environ, {"DEEPSEEK_API_KEY": "deepseek-test-key"}, clear=True
+            os.environ, {"OPENROUTER_API_KEY": "openrouter-test-key"}, clear=True
         ):
             # No fallback key, no rescue.
-            self.assertIsNone(rescue_model_for(DEEPSEEK_DIRECT_MODEL_NAME))
+            self.assertIsNone(rescue_model_for(DEFAULT_MODEL_NAME))
 
     def test_provider_outage_classification(self) -> None:
         class ServerError(Exception):
@@ -1031,7 +1081,7 @@ class ChatServiceTestCase(unittest.TestCase):
         request = ChatRequest(
             query="ls the kb",
             source_keys=("peft",),
-            model_name=DEEPSEEK_DIRECT_MODEL_NAME,
+            model_name=DEFAULT_MODEL_NAME,
             include_reasoning=False,
             enabled_tools=(),
         )
@@ -1042,7 +1092,7 @@ class ChatServiceTestCase(unittest.TestCase):
         with (
             patch.dict(
                 os.environ,
-                {"DEEPSEEK_API_KEY": "k1", "GEMINI_API_KEY": "k2"},
+                {"OPENROUTER_API_KEY": "k1", "GEMINI_API_KEY": "k2"},
                 clear=False,
             ),
             patch("app.chat_service.build_agent", side_effect=fake_build_agent),
@@ -1051,9 +1101,7 @@ class ChatServiceTestCase(unittest.TestCase):
             events = asyncio.run(collect_events())
 
         # The turn restarted on the fallback model and completed normally.
-        self.assertEqual(
-            built_models, [DEEPSEEK_DIRECT_MODEL_NAME, FALLBACK_MODEL_NAME]
-        )
+        self.assertEqual(built_models, [DEFAULT_MODEL_NAME, FALLBACK_MODEL_NAME])
         types = [event.type for event in events]
         self.assertIn("thread_started", types)
         self.assertIn("context_stats", types)
@@ -1075,7 +1123,7 @@ class ChatServiceTestCase(unittest.TestCase):
         request = ChatRequest(
             query="ls the kb",
             source_keys=("peft",),
-            model_name=DEEPSEEK_DIRECT_MODEL_NAME,
+            model_name=DEFAULT_MODEL_NAME,
             include_reasoning=False,
             enabled_tools=(),
         )
@@ -1086,7 +1134,7 @@ class ChatServiceTestCase(unittest.TestCase):
         with (
             patch.dict(
                 os.environ,
-                {"DEEPSEEK_API_KEY": "k1", "GEMINI_API_KEY": "k2"},
+                {"OPENROUTER_API_KEY": "k1", "GEMINI_API_KEY": "k2"},
                 clear=False,
             ),
             patch("app.chat_service.build_agent", side_effect=fake_build_agent),
@@ -1099,14 +1147,12 @@ class ChatServiceTestCase(unittest.TestCase):
             events = asyncio.run(collect_events())
 
         # The unfunded account rescued onto the fallback model and paged ops.
-        self.assertEqual(
-            built_models, [DEEPSEEK_DIRECT_MODEL_NAME, FALLBACK_MODEL_NAME]
-        )
+        self.assertEqual(built_models, [DEFAULT_MODEL_NAME, FALLBACK_MODEL_NAME])
         self.assertEqual(len(alerts), 1)
         self.assertEqual(alerts[0][0], "account-state")
         self.assertIn("Insufficient Balance", alerts[0][1])
         stats = next(event for event in events if event.type == "context_stats")
-        self.assertEqual(stats.data["requested_model"], DEEPSEEK_DIRECT_MODEL_NAME)
+        self.assertEqual(stats.data["requested_model"], DEFAULT_MODEL_NAME)
         self.assertEqual(stats.data["served_model"], FALLBACK_MODEL_NAME)
         self.assertTrue(stats.data["rescued"])
 
@@ -1125,7 +1171,7 @@ class ChatServiceTestCase(unittest.TestCase):
         request = ChatRequest(
             query="ls the kb",
             source_keys=("peft",),
-            model_name=DEEPSEEK_DIRECT_MODEL_NAME,
+            model_name=DEFAULT_MODEL_NAME,
             include_reasoning=False,
             enabled_tools=(),
         )
@@ -1136,7 +1182,7 @@ class ChatServiceTestCase(unittest.TestCase):
         with (
             patch.dict(
                 os.environ,
-                {"DEEPSEEK_API_KEY": "k1", "GEMINI_API_KEY": "k2"},
+                {"OPENROUTER_API_KEY": "k1", "GEMINI_API_KEY": "k2"},
                 clear=False,
             ),
             patch("app.chat_service.build_agent", side_effect=fake_build_agent),
@@ -1146,7 +1192,7 @@ class ChatServiceTestCase(unittest.TestCase):
                 asyncio.run(collect_events())
 
         # 4xx never reaches the fallback; the primary was the only attempt.
-        self.assertEqual(built_models, [DEEPSEEK_DIRECT_MODEL_NAME])
+        self.assertEqual(built_models, [DEFAULT_MODEL_NAME])
 
     def test_stream_chat_emits_deepseek_reasoning_content(self) -> None:
         agent = FakeDeepSeekReasoningAgent([])
@@ -1155,7 +1201,7 @@ class ChatServiceTestCase(unittest.TestCase):
         request = ChatRequest(
             query="Find the course repository",
             source_keys=("peft",),
-            model_name=DEEPSEEK_DIRECT_MODEL_NAME,
+            model_name=DEFAULT_MODEL_NAME,
             include_reasoning=True,
             enabled_tools=(),
         )
@@ -1188,7 +1234,7 @@ class ChatServiceTestCase(unittest.TestCase):
         request = ChatRequest(
             query="Where should I store API keys?",
             source_keys=("langchain",),
-            model_name=DEEPSEEK_DIRECT_MODEL_NAME,
+            model_name=DEFAULT_MODEL_NAME,
             include_reasoning=False,
             enabled_tools=(),
         )

tests/test_config.py

@@ -11,11 +11,14 @@ import pytest
 from app import config
 
 
-def test_default_chat_model_prefers_deepseek_direct_with_gemini_fallback() -> None:
-    assert config.DEFAULT_MODEL_NAME == config.DEEPSEEK_DIRECT_MODEL_NAME
-    assert config.DEFAULT_MODEL_NAME == "deepseek:deepseek-v4-flash"
+def test_default_chat_model_is_openrouter_deepseek_with_gemini_fallback() -> None:
+    assert config.DEFAULT_MODEL_NAME == config.OPENROUTER_DEEPSEEK_MODEL_NAME
+    assert config.DEFAULT_MODEL_NAME == "openrouter:deepseek/deepseek-v4-flash"
     assert config.FALLBACK_MODEL_NAME == "google-genai:gemini-3.5-flash-lite"
     assert config.AVAILABLE_MODELS[0]["id"] == config.DEFAULT_MODEL_NAME
+    # The retired first-party path stays addressable for experiments but is
+    # neither the default nor selectable.
+    assert config.DEEPSEEK_DIRECT_MODEL_NAME == "deepseek:deepseek-v4-flash"
 
 
 def test_gemini_fallback_model_is_deliberately_not_selectable() -> None:
@@ -25,12 +28,12 @@ def test_gemini_fallback_model_is_deliberately_not_selectable() -> None:
     our custom tools) this is a product choice, one selectable model plus a
     rescue path, rather than the hard API constraint it was for 2.5-flash. The
     fallback still never receives web tools: build_agent binds them from the
-    requested model (DeepSeek), which has none.
+    requested model (DeepSeek via OpenRouter), which has none.
     """
     selectable = [model["id"] for model in config.AVAILABLE_MODELS]
 
     assert config.FALLBACK_MODEL_NAME not in selectable
-    assert selectable == ["deepseek:deepseek-v4-flash"]
+    assert selectable == ["openrouter:deepseek/deepseek-v4-flash"]
 
 
 def _patched_bundle(tmp_path: Path) -> ExitStack:

tests/test_memory_presets.py

@@ -90,11 +90,24 @@ class MemoryPresetResolutionTests(unittest.TestCase):
                 production_memory_preset_name("openai:gpt-5.6"),
                 PRODUCTION_FALLBACK_MEMORY_PRESET,
             )
+            self.assertEqual(
+                resolve_memory_preset(
+                    None, model_name="openrouter:deepseek/deepseek-v4-flash"
+                ).name,
+                "prod_v2",
+            )
 
     def test_prod_v2_rejects_short_context_providers(self) -> None:
         self.assertTrue(
             memory_preset_supports_model("prod_v2", "deepseek:deepseek-v4-flash")
         )
+        # The default chat path serves DeepSeek through OpenRouter; prod_v2
+        # must not silently downgrade it to the legacy preset.
+        self.assertTrue(
+            memory_preset_supports_model(
+                "prod_v2", "openrouter:deepseek/deepseek-v4-flash"
+            )
+        )
         self.assertTrue(
             memory_preset_supports_model(
                 "prod_v2", "google-genai:gemini-3.5-flash-lite"