From 384270f785eda0d34c24428a1e711ca4e228faa9 Mon Sep 17 00:00:00 2001
From: Prathik Shetty <prathikshetty1411@gmail.com>
Date: Thu, 2 Jul 2026 23:57:07 +0530
Subject: [PATCH 1/7] feat(backend): add OpenRouter as a selectable AI provider
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce an OpenRouter provider (AI_PROVIDER=openrouter) that routes chat
completions through openrouter.ai using the OpenAI-compatible API, so one
OPENROUTER_API_KEY unlocks many underlying models by slug (Anthropic, OpenAI,
Google, Meta). It mirrors the existing provider contract — streaming chat and
JSON-mode test-case generation — and is dispatched from services/ai.py.

Because the interviewer, tutor, and voice mode all stream through the same
ai.stream_chat path, selecting OpenRouter makes the entire app model-agnostic.

- services/providers/openrouter_provider.py: new provider (base_url, key,
  optional HTTP-Referer / X-Title attribution headers, curated model list)
- services/ai.py: dispatch AI_PROVIDER=openrouter
- config.py: OPENROUTER_* settings and defaults
- .env.example: document the provider and its keys

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 backend/.env.example                          |  26 ++++-
 backend/config.py                             |  17 ++-
 backend/services/ai.py                        |   4 +-
 .../services/providers/openrouter_provider.py | 108 ++++++++++++++++++
 4 files changed, 147 insertions(+), 8 deletions(-)
 create mode 100644 backend/services/providers/openrouter_provider.py

diff --git a/backend/.env.example b/backend/.env.example
index 1fd6d84..6ad415f 100644
--- a/backend/.env.example
+++ b/backend/.env.example
@@ -9,9 +9,10 @@ DATABASE_URL=postgresql+psycopg://o1prep:o1prep@localhost:5433/o1prep
 # deployment, e.g.: python -c "import secrets; print(secrets.token_hex(32))"
 SECRET_KEY=dev-secret-change-me
 
-# AI engine for text interviews and the tutor:
-#   claude  -> uses your local Claude Code CLI and existing login (no API key)
-#   openai  -> uses the OpenAI API (requires OPENAI_API_KEY below)
+# AI engine for text interviews, the tutor, and voice mode:
+#   claude      -> uses your local Claude Code CLI and existing login (no API key)
+#   openai      -> uses the OpenAI API (requires OPENAI_API_KEY below)
+#   openrouter  -> uses openrouter.ai; one key unlocks many models (see below)
 AI_PROVIDER=claude
 
 # --- Claude engine (AI_PROVIDER=claude) ---
@@ -21,10 +22,27 @@ AI_PROVIDER=claude
 # CLAUDE_BIN=claude
 # CLAUDE_TIMEOUT=180
 
-# --- OpenAI (AI_PROVIDER=openai, and always required for Voice mode) ---
+# --- OpenAI (AI_PROVIDER=openai) ---
 # Get a key at https://platform.openai.com/api-keys
 OPENAI_API_KEY=your-api-key-here
 
+# --- OpenRouter (AI_PROVIDER=openrouter) ---
+# One key for many models (Anthropic, OpenAI, Google, Meta, ...).
+# Get a key at https://openrouter.ai/keys and browse slugs at
+# https://openrouter.ai/models. Voice mode's STT -> LLM -> TTS pipeline uses
+# this same provider, so voice runs through OpenRouter when it's selected.
+OPENROUTER_API_KEY=your-openrouter-key-here
+# Optional overrides:
+# OPENROUTER_MODEL=anthropic/claude-3.5-sonnet
+# OPENROUTER_SITE_URL=https://your-deployment.example.com
+# OPENROUTER_SITE_NAME=O(1) Prep
+
+# --- Voice mode ---
+# Speech-to-text and text-to-speech run in the browser (Web Speech API), so no
+# extra keys are needed. The spoken interview is powered by AI_PROVIDER above.
+# The legacy OpenAI Realtime path (routes/realtime.py) still requires
+# OPENAI_API_KEY if you use it instead.
+
 # --- Code execution (multi-language) ---
 # Python runs via the app's interpreter. JavaScript needs Node.js and TypeScript
 # needs a TS runner; override these only if they are not on PATH.
diff --git a/backend/config.py b/backend/config.py
index 276f4e8..990d209 100644
--- a/backend/config.py
+++ b/backend/config.py
@@ -22,9 +22,12 @@
 # random value in any real deployment.
 SECRET_KEY = os.environ.get("SECRET_KEY", "dev-secret-change-me")
 
-# AI provider for text interviews and the tutor: 'claude' drives the locally
-# installed Claude Code CLI using your existing login (no API key); 'openai'
-# uses the OpenAI API. Voice mode always uses OpenAI Realtime regardless.
+# AI provider for text interviews, the tutor, and voice mode:
+#   'claude'     -> local Claude Code CLI using your existing login (no API key)
+#   'openai'     -> the OpenAI API (OPENAI_API_KEY)
+#   'openrouter' -> openrouter.ai, one key for many models (OPENROUTER_API_KEY)
+# Voice mode reuses the same text-streaming path, so it runs on whichever
+# provider is selected here (the STT -> LLM -> TTS pipeline calls this LLM).
 AI_PROVIDER = os.environ.get("AI_PROVIDER", "claude").strip().lower()
 
 # Claude Code CLI provider
@@ -38,6 +41,14 @@
 REALTIME_MODEL = "gpt-4o-realtime-preview"
 TRANSCRIPTION_MODEL = "gpt-4o-mini-transcribe"
 
+# OpenRouter (AI_PROVIDER=openrouter). One key, many models by slug; browse them
+# at https://openrouter.ai/models. SITE_URL/SITE_NAME are optional attribution
+# headers OpenRouter uses for its dashboard and model rankings.
+OPENROUTER_API_URL = "https://openrouter.ai/api/v1"
+OPENROUTER_MODEL = os.environ.get("OPENROUTER_MODEL", "anthropic/claude-3.5-sonnet").strip()
+OPENROUTER_SITE_URL = os.environ.get("OPENROUTER_SITE_URL", "").strip()
+OPENROUTER_SITE_NAME = os.environ.get("OPENROUTER_SITE_NAME", "O(1) Prep").strip()
+
 # Chat parameters
 CHAT_TEMPERATURE = 0.7
 CHAT_MAX_TOKENS = 4000
diff --git a/backend/services/ai.py b/backend/services/ai.py
index 05ca5fe..51db07a 100644
--- a/backend/services/ai.py
+++ b/backend/services/ai.py
@@ -14,12 +14,14 @@
 import json
 
 import config
-from services.providers import claude_provider, openai_provider
+from services.providers import claude_provider, openai_provider, openrouter_provider
 
 
 def _provider():
     if config.AI_PROVIDER == "claude":
         return claude_provider
+    if config.AI_PROVIDER == "openrouter":
+        return openrouter_provider
     return openai_provider
 
 
diff --git a/backend/services/providers/openrouter_provider.py b/backend/services/providers/openrouter_provider.py
new file mode 100644
index 0000000..f69d6b9
--- /dev/null
+++ b/backend/services/providers/openrouter_provider.py
@@ -0,0 +1,108 @@
+"""OpenRouter provider — routes chat completions through openrouter.ai.
+
+OpenRouter exposes an OpenAI-compatible API, so this reuses the OpenAI SDK
+pointed at OpenRouter's base URL. The single OPENROUTER_API_KEY unlocks many
+underlying models (Anthropic, OpenAI, Google, Meta, ...) selectable by slug.
+
+Because both the text interviewer/tutor and voice mode stream through the same
+`ai.stream_chat` path, selecting AI_PROVIDER=openrouter makes the entire app —
+including the STT -> LLM -> TTS voice pipeline — OpenRouter-powered.
+"""
+
+import json
+import os
+
+import config
+
+# Curated models offered in the UI settings modal. OpenRouter has hundreds more
+# (see https://openrouter.ai/models); override the default via OPENROUTER_MODEL.
+# Reasoning-effort is model-specific on OpenRouter and not exposed here.
+MODELS = [
+    {"id": "anthropic/claude-3.5-sonnet", "label": "Claude 3.5 Sonnet"},
+    {"id": "openai/gpt-4o", "label": "GPT-4o"},
+    {"id": "openai/gpt-4o-mini", "label": "GPT-4o mini — faster"},
+    {"id": "google/gemini-2.0-flash-001", "label": "Gemini 2.0 Flash"},
+    {"id": "meta-llama/llama-3.3-70b-instruct", "label": "Llama 3.3 70B"},
+]
+EFFORTS = []
+SUPPORTS_EFFORT = False
+
+
+def default_model():
+    return config.OPENROUTER_MODEL
+
+
+def default_effort():
+    return None
+
+
+def valid_model(model):
+    # Accept any curated model, plus whatever the deployment configured as the
+    # default (so OPENROUTER_MODEL can point at a slug not in the short list).
+    return model == config.OPENROUTER_MODEL or any(m["id"] == model for m in MODELS)
+
+
+def _extra_headers():
+    # Optional attribution headers OpenRouter uses for its dashboard/rankings.
+    headers = {}
+    if config.OPENROUTER_SITE_URL:
+        headers["HTTP-Referer"] = config.OPENROUTER_SITE_URL
+    if config.OPENROUTER_SITE_NAME:
+        headers["X-Title"] = config.OPENROUTER_SITE_NAME
+    return headers
+
+
+class OpenRouterClient:
+    def __init__(self, api_key, model=None):
+        from openai import OpenAI  # lazy: only needed when this provider is used
+
+        self._client = OpenAI(
+            api_key=api_key,
+            base_url=config.OPENROUTER_API_URL,
+            default_headers=_extra_headers() or None,
+        )
+        self.model = model or config.OPENROUTER_MODEL
+
+    def stream_chat(self, messages, temperature=None, max_tokens=None):
+        stream = self._client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            stream=True,
+            temperature=temperature if temperature is not None else config.CHAT_TEMPERATURE,
+            max_tokens=max_tokens if max_tokens is not None else config.CHAT_MAX_TOKENS,
+        )
+        for chunk in stream:
+            if not chunk.choices:
+                continue
+            delta = chunk.choices[0].delta
+            if delta and delta.content:
+                yield delta.content
+
+    def generate_test_cases(self, messages):
+        try:
+            response = self._client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": config.TEST_GEN_PROMPT},
+                    *[m for m in messages if m["role"] != "system"],
+                ],
+                response_format={"type": "json_object"},
+                temperature=config.TEST_GEN_TEMPERATURE,
+                max_tokens=config.TEST_GEN_MAX_TOKENS,
+            )
+            result = json.loads(response.choices[0].message.content)
+            fn = result.get("function_name")
+            cases = result.get("test_cases", [])
+            if not fn or not cases:
+                return None, []
+            return fn, cases
+        except Exception:
+            return None, []
+
+
+def get_client(model=None, effort=None):
+    api_key = os.environ.get("OPENROUTER_API_KEY", "")
+    if not api_key:
+        return None
+    m = model if valid_model(model) else config.OPENROUTER_MODEL
+    return OpenRouterClient(api_key, m)

From 25afe3c57c1e3fafb159eb12b6e7f57cfbb69d7f Mon Sep 17 00:00:00 2001
From: Prathik Shetty <prathikshetty1411@gmail.com>
Date: Thu, 2 Jul 2026 23:57:26 +0530
Subject: [PATCH 2/7] feat(frontend): add turn-based voice mode (browser STT,
 LLM, TTS)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a voice interview mode that wraps the existing text pipeline in a
speech loop: mic -> STT -> useInterview.send() -> streamed LLM reply -> TTS.
The LLM turn is not re-implemented — send()/start() run the same streamSSE
path, and a registered voice sink speaks assistant tokens as they arrive, so
voice runs on whichever AI_PROVIDER is configured (OpenAI, Claude, OpenRouter).

STT and TTS use the browser Web Speech API (Chrome/Edge, no extra keys) behind
a thin seam so a premium provider (Deepgram/ElevenLabs) can drop in later.

- lib/voice/stt.ts, tts.ts: Web Speech adapters; TTS is sentence-buffered for
  low latency and strips markdown so it doesn't read backticks aloud
- lib/voice/sink.ts: one-slot registry decoupling the interview store from voice
- store/voice.ts: listening -> thinking -> speaking state machine; mic pauses
  while the interviewer speaks to avoid echo
- store/interview.ts: feed streamed assistant deltas to the sink (no-op in text)
- components/interview/VoiceControls.tsx: status strip, interim transcript, mute
- components/interview/InterviewTopBar.tsx: voice toggle; ChatPanel.tsx: mount

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/components/interview/ChatPanel.tsx    |   3 +
 .../components/interview/InterviewTopBar.tsx  |  10 ++
 .../components/interview/VoiceControls.tsx    |  93 ++++++++++++
 frontend/src/lib/voice/sink.ts                |  24 +++
 frontend/src/lib/voice/stt.ts                 | 118 +++++++++++++++
 frontend/src/lib/voice/tts.ts                 | 130 +++++++++++++++++
 frontend/src/store/interview.ts               |  23 ++-
 frontend/src/store/voice.ts                   | 138 ++++++++++++++++++
 8 files changed, 536 insertions(+), 3 deletions(-)
 create mode 100644 frontend/src/components/interview/VoiceControls.tsx
 create mode 100644 frontend/src/lib/voice/sink.ts
 create mode 100644 frontend/src/lib/voice/stt.ts
 create mode 100644 frontend/src/lib/voice/tts.ts
 create mode 100644 frontend/src/store/voice.ts

diff --git a/frontend/src/components/interview/ChatPanel.tsx b/frontend/src/components/interview/ChatPanel.tsx
index 5aaf075..9bdedc3 100644
--- a/frontend/src/components/interview/ChatPanel.tsx
+++ b/frontend/src/components/interview/ChatPanel.tsx
@@ -4,6 +4,7 @@ import { useEffect, useRef, useState } from "react";
 import { useInterview, type ChatItem } from "@/store/interview";
 import { Markdown } from "./Markdown";
 import { TestResults } from "./TestResults";
+import { VoiceControls } from "./VoiceControls";
 
 function MessageBlock({ item }: { item: ChatItem }) {
   if (item.role === "tests") {
@@ -72,6 +73,8 @@ export function ChatPanel() {
         )}
       </div>
 
+      <VoiceControls />
+
       <div className="border-t border-line p-3">
         <textarea
           value={text}
diff --git a/frontend/src/components/interview/InterviewTopBar.tsx b/frontend/src/components/interview/InterviewTopBar.tsx
index 4c9f679..b9f1fe1 100644
--- a/frontend/src/components/interview/InterviewTopBar.tsx
+++ b/frontend/src/components/interview/InterviewTopBar.tsx
@@ -3,6 +3,7 @@
 import { useEffect, useState } from "react";
 import { useRouter } from "next/navigation";
 import { useInterview } from "@/store/interview";
+import { useVoice } from "@/store/voice";
 
 function useTimer() {
   const [s, setS] = useState(0);
@@ -21,6 +22,8 @@ export function InterviewTopBar() {
   const toggleTutor = useInterview((s) => s.toggleTutor);
   const tutorOpen = useInterview((s) => s.tutorOpen);
   const end = useInterview((s) => s.end);
+  const voiceActive = useVoice((s) => s.active);
+  const toggleVoice = useVoice((s) => s.toggle);
   const time = useTimer();
 
   const leave = () => router.push("/");
@@ -38,6 +41,13 @@ export function InterviewTopBar() {
         <span className="truncate text-[13px] text-text">{title}</span>
       </div>
       <div className="flex items-center gap-2">
+        <button
+          onClick={toggleVoice}
+          className={`tbtn ${voiceActive ? "is-active" : ""}`}
+          title="Toggle voice mode"
+        >
+          {voiceActive ? "🎙 voice on" : "🎙 voice"}
+        </button>
         <button
           onClick={toggleTutor}
           className={`tbtn ${tutorOpen ? "is-active" : ""}`}
diff --git a/frontend/src/components/interview/VoiceControls.tsx b/frontend/src/components/interview/VoiceControls.tsx
new file mode 100644
index 0000000..6764016
--- /dev/null
+++ b/frontend/src/components/interview/VoiceControls.tsx
@@ -0,0 +1,93 @@
+"use client";
+
+import { useEffect } from "react";
+import { useVoice, type VoiceStatus } from "@/store/voice";
+
+const STATUS_LABEL: Record<VoiceStatus, string> = {
+  off: "",
+  listening: "listening…",
+  thinking: "thinking…",
+  speaking: "interviewer speaking…",
+  idle: "muted",
+  error: "",
+};
+
+// Colour + pulse per state so the candidate always knows whose turn it is.
+const STATUS_TONE: Record<VoiceStatus, string> = {
+  off: "text-text-faint",
+  listening: "text-green",
+  thinking: "text-amber-dim",
+  speaking: "text-amber",
+  idle: "text-text-faint",
+  error: "text-red",
+};
+
+/**
+ * Voice-mode status strip. Renders above the chat composer only while voice is
+ * active; the transcript itself reuses the normal ChatPanel message list. On
+ * unmount (leaving the interview) it tears the pipeline down so the mic stops.
+ */
+export function VoiceControls() {
+  const active = useVoice((s) => s.active);
+  const status = useVoice((s) => s.status);
+  const muted = useVoice((s) => s.muted);
+  const interim = useVoice((s) => s.interim);
+  const error = useVoice((s) => s.error);
+  const toggleMute = useVoice((s) => s.toggleMute);
+  const disable = useVoice((s) => s.disable);
+
+  // Stop the mic/synth if the component unmounts while a session is live.
+  useEffect(() => () => useVoice.getState().disable(), []);
+
+  if (error && !active) {
+    return (
+      <div className="border-t border-red/40 bg-red/5 px-3 py-2 text-[11px] text-red">
+        ✕ {error}
+      </div>
+    );
+  }
+
+  if (!active) return null;
+
+  const pulsing = status === "listening" || status === "speaking";
+
+  return (
+    <div className="border-t border-line bg-bg-raised px-3 py-2">
+      <div className="flex items-center gap-2">
+        <span
+          className={`inline-block h-2 w-2 rounded-full ${
+            status === "listening"
+              ? "bg-green"
+              : status === "speaking"
+                ? "bg-amber"
+                : status === "thinking"
+                  ? "bg-amber-dim"
+                  : "bg-text-faint"
+          } ${pulsing ? "animate-pulse" : ""}`}
+        />
+        <span className={`label ${STATUS_TONE[status]}`}>{STATUS_LABEL[status]}</span>
+
+        <div className="ml-auto flex items-center gap-2">
+          <button onClick={toggleMute} className="tbtn" title={muted ? "Unmute mic" : "Mute mic"}>
+            {muted ? "▶ unmute" : "❚❚ mute"}
+          </button>
+          <button
+            onClick={disable}
+            className="tbtn"
+            style={{ color: "var(--red)", borderColor: "var(--red-dim)" }}
+            title="Exit voice mode"
+          >
+            ■ voice off
+          </button>
+        </div>
+      </div>
+
+      {interim && (
+        <div className="mt-1.5 truncate text-[12px] text-text-dim">
+          <span className="text-text-faint">$ </span>
+          {interim}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/lib/voice/sink.ts b/frontend/src/lib/voice/sink.ts
new file mode 100644
index 0000000..fa153ef
--- /dev/null
+++ b/frontend/src/lib/voice/sink.ts
@@ -0,0 +1,24 @@
+/**
+ * A one-slot registry that decouples the interview store from voice mode.
+ *
+ * The interview store owns the single LLM streaming path (`start`/`send`/
+ * `submitCode` via streamSSE). When voice mode is active it registers a sink
+ * here; the store feeds every assistant token delta to `pushText` and calls
+ * `flush` when the turn ends. In text mode the sink is null and the store's
+ * calls are no-ops — so there is exactly one code path for the model turn.
+ */
+
+export interface VoiceSink {
+  pushText: (delta: string) => void;
+  flush: () => void;
+}
+
+let active: VoiceSink | null = null;
+
+export function setVoiceSink(sink: VoiceSink | null) {
+  active = sink;
+}
+
+export function getVoiceSink(): VoiceSink | null {
+  return active;
+}
diff --git a/frontend/src/lib/voice/stt.ts b/frontend/src/lib/voice/stt.ts
new file mode 100644
index 0000000..f705076
--- /dev/null
+++ b/frontend/src/lib/voice/stt.ts
@@ -0,0 +1,118 @@
+/**
+ * Speech-to-text adapter over the browser Web Speech API (SpeechRecognition).
+ *
+ * The "STT" leg of the STT -> LLM -> TTS voice pipeline. Behind the same kind of
+ * thin surface as the Speaker, so a server-side STT (Deepgram/Whisper) can drop
+ * in later. Chrome/Edge implement this natively; Safari/Firefox are spotty —
+ * callers should gate on `sttSupported()` and fall back to text mode.
+ */
+
+// The API ships under a webkit-prefixed constructor in Chromium.
+type SpeechRecognitionCtor = new () => SpeechRecognitionLike;
+
+interface SpeechRecognitionLike {
+  lang: string;
+  continuous: boolean;
+  interimResults: boolean;
+  start: () => void;
+  stop: () => void;
+  abort: () => void;
+  onresult: ((e: SpeechRecognitionEventLike) => void) | null;
+  onerror: ((e: { error: string }) => void) | null;
+  onend: (() => void) | null;
+}
+
+interface SpeechRecognitionEventLike {
+  resultIndex: number;
+  results: ArrayLike<{ 0: { transcript: string }; isFinal: boolean }>;
+}
+
+function ctor(): SpeechRecognitionCtor | null {
+  if (typeof window === "undefined") return null;
+  const w = window as unknown as {
+    SpeechRecognition?: SpeechRecognitionCtor;
+    webkitSpeechRecognition?: SpeechRecognitionCtor;
+  };
+  return w.SpeechRecognition ?? w.webkitSpeechRecognition ?? null;
+}
+
+export function sttSupported(): boolean {
+  return ctor() !== null;
+}
+
+export interface RecognizerCallbacks {
+  /** Interim (non-final) transcript, for live display while the user speaks. */
+  onInterim?: (text: string) => void;
+  /** A completed utterance the user finished speaking. */
+  onFinal?: (text: string) => void;
+  /** Non-fatal recognition error (e.g. "no-speech"); caller may restart. */
+  onError?: (error: string) => void;
+}
+
+export class Recognizer {
+  private rec: SpeechRecognitionLike | null = null;
+  private cb: RecognizerCallbacks;
+  private running = false;
+
+  constructor(cb: RecognizerCallbacks = {}, lang = "en-US") {
+    this.cb = cb;
+    const C = ctor();
+    if (!C) return;
+    const rec = new C();
+    rec.lang = lang;
+    rec.continuous = false; // one utterance per turn — resolves on a pause
+    rec.interimResults = true;
+    rec.onresult = (e) => {
+      let interim = "";
+      let final = "";
+      for (let i = e.resultIndex; i < e.results.length; i++) {
+        const r = e.results[i];
+        if (r.isFinal) final += r[0].transcript;
+        else interim += r[0].transcript;
+      }
+      if (interim) this.cb.onInterim?.(interim);
+      if (final.trim()) this.cb.onFinal?.(final.trim());
+    };
+    rec.onerror = (e) => {
+      this.running = false;
+      this.cb.onError?.(e.error);
+    };
+    rec.onend = () => {
+      this.running = false;
+    };
+    this.rec = rec;
+  }
+
+  start() {
+    if (!this.rec || this.running) return;
+    try {
+      this.rec.start();
+      this.running = true;
+    } catch {
+      /* start() throws if already started; ignore */
+    }
+  }
+
+  stop() {
+    if (!this.rec) return;
+    try {
+      this.rec.stop();
+    } catch {
+      /* ignore */
+    }
+    this.running = false;
+  }
+
+  dispose() {
+    if (!this.rec) return;
+    this.rec.onresult = null;
+    this.rec.onerror = null;
+    this.rec.onend = null;
+    try {
+      this.rec.abort();
+    } catch {
+      /* ignore */
+    }
+    this.rec = null;
+  }
+}
diff --git a/frontend/src/lib/voice/tts.ts b/frontend/src/lib/voice/tts.ts
new file mode 100644
index 0000000..ce6d76c
--- /dev/null
+++ b/frontend/src/lib/voice/tts.ts
@@ -0,0 +1,130 @@
+/**
+ * Text-to-speech adapter over the browser Web Speech API (SpeechSynthesis).
+ *
+ * This is the "TTS" leg of the STT -> LLM -> TTS voice pipeline. It is written
+ * behind a tiny surface (`pushText`, `flush`, `interrupt`, callbacks) so a
+ * premium provider (ElevenLabs/Cartesia) can replace it later without the voice
+ * store knowing the difference.
+ *
+ * Streaming-friendly: `pushText` receives assistant token deltas and speaks
+ * complete sentences as soon as they form, so audio starts before the model has
+ * finished — the rest is spoken on `flush`.
+ */
+
+export function ttsSupported(): boolean {
+  return typeof window !== "undefined" && "speechSynthesis" in window;
+}
+
+// Break the buffer at sentence boundaries so we can start speaking early while
+// keeping natural prosody. Keeps trailing text (no boundary yet) buffered.
+const SENTENCE_RE = /[^.!?\n]+[.!?\n]+(\s|$)|[^.!?\n]+$/g;
+
+// Strip markdown so the synth doesn't read "asterisk asterisk" or backticks.
+// Fenced code blocks are announced rather than spelled out character by char.
+function cleanForSpeech(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, " (code block) ")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/[*_#>~]/g, "")
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export interface SpeakerCallbacks {
+  /** Fired when playback transitions from silent to speaking. */
+  onSpeakingStart?: () => void;
+  /** Fired when the queue drains after having spoken (nothing left to say). */
+  onDrain?: () => void;
+}
+
+export class Speaker {
+  private buffer = "";
+  private queue: string[] = [];
+  private speaking = false;
+  private finished = false; // flush() called: drain when queue empties
+  private cb: SpeakerCallbacks;
+  private voice: SpeechSynthesisVoice | null = null;
+
+  constructor(cb: SpeakerCallbacks = {}) {
+    this.cb = cb;
+    // Pick a stable English voice if one is available; getVoices can be async.
+    const pick = () => {
+      const voices = window.speechSynthesis.getVoices();
+      this.voice = voices.find((v) => v.lang?.startsWith("en")) ?? voices[0] ?? null;
+    };
+    pick();
+    if (typeof window !== "undefined") window.speechSynthesis.onvoiceschanged = pick;
+  }
+
+  /** Feed a streamed token delta; speaks whole sentences as they complete. */
+  pushText(delta: string) {
+    this.finished = false;
+    this.buffer += delta;
+    this.drainSentences(false);
+  }
+
+  /** Signal the turn is complete; speak whatever remains in the buffer. */
+  flush() {
+    this.finished = true;
+    this.drainSentences(true);
+    // Nothing was ever queued (e.g. empty response) — report drain immediately.
+    if (!this.speaking && this.queue.length === 0) this.cb.onDrain?.();
+  }
+
+  /** Stop immediately and discard anything pending (barge-in / disable). */
+  interrupt() {
+    this.buffer = "";
+    this.queue = [];
+    this.speaking = false;
+    this.finished = false;
+    if (ttsSupported()) window.speechSynthesis.cancel();
+  }
+
+  private drainSentences(toEnd: boolean) {
+    const matches = this.buffer.match(SENTENCE_RE) ?? [];
+    if (matches.length === 0) return;
+
+    // Unless flushing, keep the last fragment buffered until it's terminated.
+    const lastTerminated = /[.!?\n]\s*$/.test(this.buffer);
+    const take = toEnd || lastTerminated ? matches.length : matches.length - 1;
+
+    let consumed = 0;
+    for (let i = 0; i < take; i++) {
+      const sentence = matches[i].trim();
+      consumed += matches[i].length;
+      if (sentence) this.queue.push(sentence);
+    }
+    this.buffer = this.buffer.slice(consumed);
+    this.pump();
+  }
+
+  private pump() {
+    if (this.speaking || this.queue.length === 0 || !ttsSupported()) return;
+    const raw = this.queue.shift()!;
+    const text = cleanForSpeech(raw);
+    if (!text) {
+      // Nothing speakable (e.g. a lone code fence) — skip without stalling.
+      if (this.queue.length > 0) this.pump();
+      else if (this.finished) this.cb.onDrain?.();
+      return;
+    }
+    const u = new SpeechSynthesisUtterance(text);
+    if (this.voice) u.voice = this.voice;
+    u.rate = 1.05;
+    const wasSilent = !this.speaking;
+    this.speaking = true;
+    if (wasSilent) this.cb.onSpeakingStart?.();
+
+    u.onend = () => {
+      this.speaking = false;
+      if (this.queue.length > 0) {
+        this.pump();
+      } else if (this.finished) {
+        this.cb.onDrain?.();
+      }
+    };
+    u.onerror = u.onend;
+    window.speechSynthesis.speak(u);
+  }
+}
diff --git a/frontend/src/store/interview.ts b/frontend/src/store/interview.ts
index c69b8e8..e0b0c04 100644
--- a/frontend/src/store/interview.ts
+++ b/frontend/src/store/interview.ts
@@ -2,6 +2,7 @@ import { create } from "zustand";
 import type { EngineConfig, FullProblem, RunResult, TestResults } from "@/lib/types";
 import * as api from "@/lib/api";
 import { streamSSE } from "@/lib/sse";
+import { getVoiceSink } from "@/lib/voice/sink";
 import { requestSettings, useSettings } from "@/store/settings";
 
 export type ChatItem =
@@ -215,12 +216,18 @@ export const useInterview = create<InterviewState>((set, get) => ({
       await streamSSE(
         `/sessions/${sessionId}/start`,
         {},
-        { onContent: (full) => set((s) => ({ items: upsertAssistant(s.items, aid, full) })) },
+        {
+          onContent: (full, delta) => {
+            set((s) => ({ items: upsertAssistant(s.items, aid, full) }));
+            getVoiceSink()?.pushText(delta);
+          },
+        },
       );
     } catch (e) {
       const msg = e instanceof Error ? e.message : "stream error";
       set((s) => ({ items: upsertAssistant(s.items, aid, `_Error: ${msg}_`) }));
     } finally {
+      getVoiceSink()?.flush();
       set({ streaming: false });
     }
   },
@@ -237,12 +244,18 @@ export const useInterview = create<InterviewState>((set, get) => ({
       await streamSSE(
         `/sessions/${sessionId}/chat`,
         { message: text },
-        { onContent: (full) => set((s) => ({ items: upsertAssistant(s.items, aid, full) })) },
+        {
+          onContent: (full, delta) => {
+            set((s) => ({ items: upsertAssistant(s.items, aid, full) }));
+            getVoiceSink()?.pushText(delta);
+          },
+        },
       );
     } catch (e) {
       const msg = e instanceof Error ? e.message : "stream error";
       set((s) => ({ items: upsertAssistant(s.items, aid, `_Error: ${msg}_`) }));
     } finally {
+      getVoiceSink()?.flush();
       set({ streaming: false });
     }
   },
@@ -264,13 +277,17 @@ export const useInterview = create<InterviewState>((set, get) => ({
         {
           onTestResults: (tests) =>
             set((s) => ({ items: [...s.items, { id: nextId(), role: "tests", tests }] })),
-          onContent: (full) => set((s) => ({ items: upsertAssistant(s.items, aid, full) })),
+          onContent: (full, delta) => {
+            set((s) => ({ items: upsertAssistant(s.items, aid, full) }));
+            getVoiceSink()?.pushText(delta);
+          },
         },
       );
     } catch (e) {
       const msg = e instanceof Error ? e.message : "stream error";
       set((s) => ({ items: upsertAssistant(s.items, aid, `_Error: ${msg}_`) }));
     } finally {
+      getVoiceSink()?.flush();
       set({ streaming: false });
     }
   },
diff --git a/frontend/src/store/voice.ts b/frontend/src/store/voice.ts
new file mode 100644
index 0000000..43dadf6
--- /dev/null
+++ b/frontend/src/store/voice.ts
@@ -0,0 +1,138 @@
+import { create } from "zustand";
+import { useInterview } from "@/store/interview";
+import { Recognizer, sttSupported } from "@/lib/voice/stt";
+import { Speaker, ttsSupported } from "@/lib/voice/tts";
+import { setVoiceSink } from "@/lib/voice/sink";
+
+/**
+ * Voice-mode orchestrator: the turn loop around the existing text interview.
+ *
+ *   mic -> STT (Recognizer) -> useInterview.send() -> LLM stream -> TTS (Speaker)
+ *
+ * The LLM turn is NOT re-implemented here: send() runs the same streamSSE path
+ * as text mode and, because we register a Speaker as the voice sink, its tokens
+ * are spoken as they arrive. This store only drives the state machine:
+ *
+ *   listening -> thinking -> speaking -> listening
+ *
+ * We deliberately stop the mic while thinking/speaking (no barge-in) to avoid
+ * the synth's own audio echoing back into recognition.
+ */
+
+export type VoiceStatus = "off" | "listening" | "thinking" | "speaking" | "idle" | "error";
+
+interface VoiceState {
+  active: boolean;
+  status: VoiceStatus;
+  muted: boolean;
+  interim: string;
+  error: string | null;
+  enable: () => void;
+  disable: () => void;
+  toggle: () => void;
+  toggleMute: () => void;
+}
+
+// Held outside the store: these are imperative browser objects, not UI state.
+let speaker: Speaker | null = null;
+let recognizer: Recognizer | null = null;
+
+export const useVoice = create<VoiceState>((set, get) => {
+  const beginListening = () => {
+    if (!get().active || get().muted) return;
+    set({ status: "listening", interim: "" });
+    recognizer?.start();
+  };
+
+  const handleFinal = async (text: string) => {
+    if (!get().active) return;
+    recognizer?.stop();
+    set({ status: "thinking", interim: "" });
+    // send() feeds the Speaker via the sink; onSpeakingStart/onDrain advance the
+    // machine. Await guards the case where send is a no-op or produces no speech.
+    await useInterview
+      .getState()
+      .send(text)
+      .catch(() => {});
+    if (get().active && get().status === "thinking") beginListening();
+  };
+
+  const handleRecError = (err: string) => {
+    // "no-speech"/"aborted" are benign — just keep listening. Mic permission
+    // problems are terminal for voice mode.
+    if (err === "not-allowed" || err === "service-not-allowed") {
+      get().disable();
+      set({ status: "error", error: "Microphone blocked. Allow mic access to use voice mode." });
+      return;
+    }
+    if (get().active && !get().muted && get().status === "listening") beginListening();
+  };
+
+  return {
+    active: false,
+    status: "off",
+    muted: false,
+    interim: "",
+    error: null,
+
+    enable: () => {
+      if (get().active) return;
+      if (!sttSupported() || !ttsSupported()) {
+        set({
+          status: "error",
+          error: "Voice mode needs the Web Speech API (Chrome or Edge). Use text mode instead.",
+        });
+        return;
+      }
+
+      speaker = new Speaker({
+        onSpeakingStart: () => set({ status: "speaking", interim: "" }),
+        onDrain: () => beginListening(),
+      });
+      setVoiceSink(speaker);
+      recognizer = new Recognizer({
+        onInterim: (t) => set({ interim: t }),
+        onFinal: (t) => handleFinal(t),
+        onError: (e) => handleRecError(e),
+      });
+
+      set({ active: true, status: "thinking", muted: false, interim: "", error: null });
+
+      // Speak the interviewer's opening if it's already on screen; if it's still
+      // streaming, the in-flight tokens will feed the freshly-registered sink.
+      const iv = useInterview.getState();
+      const lastAssistant = [...iv.items].reverse().find((m) => m.role === "assistant");
+      if (!iv.streaming && lastAssistant && lastAssistant.role === "assistant") {
+        speaker.pushText(lastAssistant.content);
+        speaker.flush();
+      } else if (!iv.streaming) {
+        beginListening();
+      }
+    },
+
+    disable: () => {
+      recognizer?.dispose();
+      recognizer = null;
+      speaker?.interrupt();
+      setVoiceSink(null);
+      speaker = null;
+      set({ active: false, status: "off", interim: "", muted: false });
+    },
+
+    toggle: () => {
+      if (get().active) get().disable();
+      else get().enable();
+    },
+
+    toggleMute: () => {
+      const muted = !get().muted;
+      set({ muted });
+      if (muted) {
+        recognizer?.stop();
+        if (get().status === "listening") set({ status: "idle", interim: "" });
+      } else if (get().status === "idle") {
+        beginListening();
+      }
+    },
+  };
+});

From c259b43640c5bcb5debf48039c27b6b5910a8e9d Mon Sep 17 00:00:00 2001
From: Prathik Shetty <prathikshetty1411@gmail.com>
Date: Sat, 4 Jul 2026 07:20:49 +0530
Subject: [PATCH 3/7] chore(frontend): disable voice mode pending neural TTS
 integration

---
 frontend/src/components/interview/ChatPanel.tsx   |  5 +++--
 .../src/components/interview/InterviewTopBar.tsx  | 15 ++++++++++++---
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/frontend/src/components/interview/ChatPanel.tsx b/frontend/src/components/interview/ChatPanel.tsx
index 9bdedc3..f75d1fc 100644
--- a/frontend/src/components/interview/ChatPanel.tsx
+++ b/frontend/src/components/interview/ChatPanel.tsx
@@ -4,7 +4,8 @@ import { useEffect, useRef, useState } from "react";
 import { useInterview, type ChatItem } from "@/store/interview";
 import { Markdown } from "./Markdown";
 import { TestResults } from "./TestResults";
-import { VoiceControls } from "./VoiceControls";
+// TODO(voice): disabled pending a natural TTS provider (see InterviewTopBar).
+// import { VoiceControls } from "./VoiceControls";
 
 function MessageBlock({ item }: { item: ChatItem }) {
   if (item.role === "tests") {
@@ -73,7 +74,7 @@ export function ChatPanel() {
         )}
       </div>
 
-      <VoiceControls />
+      {/* TODO(voice): re-enable when neural TTS lands. <VoiceControls /> */}
 
       <div className="border-t border-line p-3">
         <textarea
diff --git a/frontend/src/components/interview/InterviewTopBar.tsx b/frontend/src/components/interview/InterviewTopBar.tsx
index b9f1fe1..c43aaeb 100644
--- a/frontend/src/components/interview/InterviewTopBar.tsx
+++ b/frontend/src/components/interview/InterviewTopBar.tsx
@@ -3,7 +3,13 @@
 import { useEffect, useState } from "react";
 import { useRouter } from "next/navigation";
 import { useInterview } from "@/store/interview";
-import { useVoice } from "@/store/voice";
+// TODO(voice): voice mode is disabled pending a natural-sounding TTS provider.
+// The browser Web Speech synth sounds robotic; deep research favours proxying a
+// neural TTS (Deepgram Aura-2 / ElevenLabs Flash / OpenAI gpt-4o-mini-tts /
+// self-hosted Kokoro) through Flask behind the existing Speaker seam. The full
+// pipeline (store/voice.ts, lib/voice/*, VoiceControls.tsx) is intact — re-enable
+// by uncommenting the voice toggle below and the <VoiceControls/> mount in ChatPanel.
+// import { useVoice } from "@/store/voice";
 
 function useTimer() {
   const [s, setS] = useState(0);
@@ -22,8 +28,9 @@ export function InterviewTopBar() {
   const toggleTutor = useInterview((s) => s.toggleTutor);
   const tutorOpen = useInterview((s) => s.tutorOpen);
   const end = useInterview((s) => s.end);
-  const voiceActive = useVoice((s) => s.active);
-  const toggleVoice = useVoice((s) => s.toggle);
+  // TODO(voice): re-enable when neural TTS lands.
+  // const voiceActive = useVoice((s) => s.active);
+  // const toggleVoice = useVoice((s) => s.toggle);
   const time = useTimer();
 
   const leave = () => router.push("/");
@@ -41,6 +48,7 @@ export function InterviewTopBar() {
         <span className="truncate text-[13px] text-text">{title}</span>
       </div>
       <div className="flex items-center gap-2">
+        {/* TODO(voice): voice mode disabled until a natural TTS provider is wired.
         <button
           onClick={toggleVoice}
           className={`tbtn ${voiceActive ? "is-active" : ""}`}
@@ -48,6 +56,7 @@ export function InterviewTopBar() {
         >
           {voiceActive ? "🎙 voice on" : "🎙 voice"}
         </button>
+        */}
         <button
           onClick={toggleTutor}
           className={`tbtn ${tutorOpen ? "is-active" : ""}`}

From 9dce7890400ce451e3092d4a4ec07b22779285dd Mon Sep 17 00:00:00 2001
From: Prathik Shetty <prathikshetty1411@gmail.com>
Date: Thu, 9 Jul 2026 23:27:10 +0530
Subject: [PATCH 4/7] feat(backend): live OpenRouter model catalog with
 server-side search

Replace the hardcoded OpenRouter model list with the live public /models
catalog (~300+ models, no API key needed), cached in-process with a 1h TTL and
an offline seed fallback. The UI receives only a curated "popular few"; the full
catalog is searched server-side and returned bounded, so the client never holds
the whole list.

- openrouter_provider.py: cached catalog(), curated models() resolved against
  live data (stale slugs drop off), ranked bounded search_models(), and
  self-healing default_model()/valid_model() that validate against the catalog
  so a retired default (e.g. claude-3.5-sonnet -> claude-sonnet-5) auto-recovers
- openai_provider.py / claude_provider.py: uniform models()/search_models()
  over their small static lists (filtered, no live search)
- ai.py: search_models dispatch + supports_search flag in config_info
- routes/models.py: GET /api/models/search?q=&limit= (login-gated, bounded)
- config.py: OPENROUTER_MODELS_URL

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 backend/config.py                             |   2 +
 backend/routes/__init__.py                    |   2 +
 backend/routes/models.py                      |  27 ++++
 backend/services/ai.py                        |   9 +-
 backend/services/providers/claude_provider.py |  12 ++
 backend/services/providers/openai_provider.py |  13 ++
 .../services/providers/openrouter_provider.py | 150 ++++++++++++++++--
 7 files changed, 199 insertions(+), 16 deletions(-)
 create mode 100644 backend/routes/models.py

diff --git a/backend/config.py b/backend/config.py
index 990d209..1a481df 100644
--- a/backend/config.py
+++ b/backend/config.py
@@ -45,6 +45,8 @@
 # at https://openrouter.ai/models. SITE_URL/SITE_NAME are optional attribution
 # headers OpenRouter uses for its dashboard and model rankings.
 OPENROUTER_API_URL = "https://openrouter.ai/api/v1"
+# Public catalog endpoint (no API key required) used to populate the model list.
+OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models"
 OPENROUTER_MODEL = os.environ.get("OPENROUTER_MODEL", "anthropic/claude-3.5-sonnet").strip()
 OPENROUTER_SITE_URL = os.environ.get("OPENROUTER_SITE_URL", "").strip()
 OPENROUTER_SITE_NAME = os.environ.get("OPENROUTER_SITE_NAME", "O(1) Prep").strip()
diff --git a/backend/routes/__init__.py b/backend/routes/__init__.py
index f88be6b..d7f3616 100644
--- a/backend/routes/__init__.py
+++ b/backend/routes/__init__.py
@@ -1,5 +1,6 @@
 from routes.auth import bp as auth_bp
 from routes.code import bp as code_bp
+from routes.models import bp as models_bp
 from routes.problems import bp as problems_bp
 from routes.realtime import bp as realtime_bp
 from routes.research import bp as research_bp
@@ -10,6 +11,7 @@
     problems_bp,
     sessions_bp,
     code_bp,
+    models_bp,
     realtime_bp,
     research_bp,
 ]
diff --git a/backend/routes/models.py b/backend/routes/models.py
new file mode 100644
index 0000000..841baaf
--- /dev/null
+++ b/backend/routes/models.py
@@ -0,0 +1,27 @@
+"""Model catalog search.
+
+Backs the settings-modal model picker. The OpenRouter catalog is ~300+ models,
+so the client never receives the whole list: it renders the curated 'popular
+few' from /api/config and calls this endpoint (debounced) to search the rest.
+Filtering happens server-side against the in-process catalog cache; results are
+bounded by `limit`.
+"""
+
+from flask import Blueprint, jsonify, request
+from flask_login import login_required
+
+from services import ai
+
+bp = Blueprint("models", __name__)
+
+
+@bp.route("/api/models/search", methods=["GET"])
+@login_required
+def search():
+    query = request.args.get("q", "")
+    try:
+        limit = int(request.args.get("limit", 25))
+    except (TypeError, ValueError):
+        limit = 25
+    limit = max(1, min(limit, 50))
+    return jsonify({"models": ai.search_models(query, limit)})
diff --git a/backend/services/ai.py b/backend/services/ai.py
index 51db07a..c457812 100644
--- a/backend/services/ai.py
+++ b/backend/services/ai.py
@@ -35,14 +35,21 @@ def config_info():
     p = _provider()
     return {
         "provider": config.AI_PROVIDER,
-        "models": p.MODELS,
+        "models": p.models(),
         "default_model": p.default_model(),
         "supports_effort": p.SUPPORTS_EFFORT,
         "efforts": p.EFFORTS,
         "default_effort": p.default_effort(),
+        "supports_search": getattr(p, "SUPPORTS_SEARCH", False),
     }
 
 
+def search_models(query, limit=25):
+    """Bounded, provider-aware model search for the settings UI. For OpenRouter
+    this filters the live catalog; other providers filter their static list."""
+    return _provider().search_models(query, limit)
+
+
 def missing_client_message():
     """Human-readable reason the current provider isn't usable, for API errors."""
     if config.AI_PROVIDER == "claude":
diff --git a/backend/services/providers/claude_provider.py b/backend/services/providers/claude_provider.py
index 6b80284..316e2b1 100644
--- a/backend/services/providers/claude_provider.py
+++ b/backend/services/providers/claude_provider.py
@@ -49,6 +49,18 @@
 ]
 EFFORTS = ["low", "medium", "high", "max"]
 SUPPORTS_EFFORT = True
+# Fixed three-model list, filtered client-side; no live search endpoint needed.
+SUPPORTS_SEARCH = False
+
+
+def models():
+    return MODELS
+
+
+def search_models(query, limit=25):
+    q = (query or "").strip().lower()
+    hits = [m for m in MODELS if not q or q in m["id"].lower() or q in m["label"].lower()]
+    return hits[:limit]
 
 
 def available():
diff --git a/backend/services/providers/openai_provider.py b/backend/services/providers/openai_provider.py
index f149457..0c3f30d 100644
--- a/backend/services/providers/openai_provider.py
+++ b/backend/services/providers/openai_provider.py
@@ -16,6 +16,19 @@
 ]
 EFFORTS = []
 SUPPORTS_EFFORT = False
+# OpenAI's list is tiny and static, so the UI filters it client-side; no live
+# search endpoint is needed (unlike OpenRouter's ~300-model catalog).
+SUPPORTS_SEARCH = False
+
+
+def models():
+    return MODELS
+
+
+def search_models(query, limit=25):
+    q = (query or "").strip().lower()
+    hits = [m for m in MODELS if not q or q in m["id"].lower() or q in m["label"].lower()]
+    return hits[:limit]
 
 
 def default_model():
diff --git a/backend/services/providers/openrouter_provider.py b/backend/services/providers/openrouter_provider.py
index f69d6b9..147137f 100644
--- a/backend/services/providers/openrouter_provider.py
+++ b/backend/services/providers/openrouter_provider.py
@@ -4,42 +4,162 @@
 pointed at OpenRouter's base URL. The single OPENROUTER_API_KEY unlocks many
 underlying models (Anthropic, OpenAI, Google, Meta, ...) selectable by slug.
 
-Because both the text interviewer/tutor and voice mode stream through the same
-`ai.stream_chat` path, selecting AI_PROVIDER=openrouter makes the entire app —
-including the STT -> LLM -> TTS voice pipeline — OpenRouter-powered.
+Model list is fetched LIVE from OpenRouter's public /models catalog (no key
+needed) and cached in-process. The UI shows only a curated "popular few"; the
+full ~300+ catalog is searched server-side (see search_models) so the client
+never has to hold the whole list. If the catalog fetch fails we fall back to a
+small hardcoded seed so the app keeps working offline.
+
+Because the interviewer, tutor, and voice mode all stream through the same
+ai.stream_chat path, selecting OpenRouter makes the entire app model-agnostic.
 """
 
 import json
 import os
+import time
+
+import requests as http_requests
 
 import config
 
-# Curated models offered in the UI settings modal. OpenRouter has hundreds more
-# (see https://openrouter.ai/models); override the default via OPENROUTER_MODEL.
-# Reasoning-effort is model-specific on OpenRouter and not exposed here.
-MODELS = [
+# OpenRouter's public /models list carries no popularity ranking, so "popular"
+# is a curated, ordered allowlist of prominent slugs. It is resolved against the
+# live catalog (fresh names/context/pricing); slugs no longer offered drop off.
+POPULAR_SLUGS = [
+    "anthropic/claude-sonnet-5",
+    "anthropic/claude-3.7-sonnet",
+    "anthropic/claude-3.5-sonnet",
+    "anthropic/claude-3.5-haiku",
+    "openai/gpt-4o",
+    "openai/gpt-4o-mini",
+    "google/gemini-2.5-pro",
+    "google/gemini-2.5-flash",
+    "meta-llama/llama-3.3-70b-instruct",
+    "deepseek/deepseek-chat",
+    "mistralai/mistral-large",
+]
+
+# Offline fallback used only when the live catalog can't be fetched.
+SEED_MODELS = [
     {"id": "anthropic/claude-3.5-sonnet", "label": "Claude 3.5 Sonnet"},
     {"id": "openai/gpt-4o", "label": "GPT-4o"},
-    {"id": "openai/gpt-4o-mini", "label": "GPT-4o mini — faster"},
-    {"id": "google/gemini-2.0-flash-001", "label": "Gemini 2.0 Flash"},
+    {"id": "openai/gpt-4o-mini", "label": "GPT-4o mini"},
+    {"id": "google/gemini-2.5-flash", "label": "Gemini 2.5 Flash"},
     {"id": "meta-llama/llama-3.3-70b-instruct", "label": "Llama 3.3 70B"},
 ]
+
 EFFORTS = []
 SUPPORTS_EFFORT = False
+SUPPORTS_SEARCH = True
 
+CATALOG_TTL = 3600  # seconds
+_catalog_cache = {"ts": 0.0, "models": None}  # models: list[dict] | None
+
+
+def _fetch_catalog():
+    resp = http_requests.get(config.OPENROUTER_MODELS_URL, timeout=10)
+    resp.raise_for_status()
+    return resp.json().get("data", [])
+
+
+def catalog():
+    """The live OpenRouter model catalog, cached with a TTL. Returns [] if it
+    has never been fetched successfully (callers then use SEED_MODELS)."""
+    now = time.time()
+    fresh = _catalog_cache["models"] is not None and now - _catalog_cache["ts"] <= CATALOG_TTL
+    if not fresh:
+        try:
+            _catalog_cache["models"] = _fetch_catalog()
+            _catalog_cache["ts"] = now
+        except Exception:
+            # Keep any stale cache; only fall through to [] if we never had one.
+            if _catalog_cache["models"] is None:
+                return []
+    return _catalog_cache["models"] or []
+
+
+def _price_per_million(pricing):
+    # OpenRouter prices are per-token USD strings; surface $/1M tokens for the UI.
+    try:
+        prompt = round(float(pricing.get("prompt", 0)) * 1_000_000, 2)
+        completion = round(float(pricing.get("completion", 0)) * 1_000_000, 2)
+        return {"prompt": prompt, "completion": completion}
+    except (TypeError, ValueError):
+        return None
 
-def default_model():
-    return config.OPENROUTER_MODEL
+
+def _to_option(m):
+    return {
+        "id": m["id"],
+        "label": m.get("name") or m["id"],
+        "context_length": m.get("context_length"),
+        "pricing": _price_per_million(m.get("pricing") or {}),
+    }
+
+
+def models():
+    """The curated 'popular few', resolved against the live catalog."""
+    cat = catalog()
+    if not cat:
+        return SEED_MODELS
+    by_id = {m["id"]: m for m in cat}
+    out = [_to_option(by_id[slug]) for slug in POPULAR_SLUGS if slug in by_id]
+    # Always surface the configured default, even if it's not in the curated set.
+    if config.OPENROUTER_MODEL in by_id and not any(o["id"] == config.OPENROUTER_MODEL for o in out):
+        out.insert(0, _to_option(by_id[config.OPENROUTER_MODEL]))
+    return out or SEED_MODELS
+
+
+def search_models(query, limit=25):
+    """Substring search over the live catalog, ranked prefix/family-first and
+    bounded to `limit` so the client never receives the whole list. An empty
+    query returns the curated popular few."""
+    q = (query or "").strip().lower()
+    cat = catalog()
+    if not cat:
+        return [m for m in SEED_MODELS if not q or q in m["id"].lower() or q in m["label"].lower()][:limit]
+    if not q:
+        return models()
+
+    scored = []
+    for m in cat:
+        mid = m["id"].lower()
+        name = (m.get("name") or "").lower()
+        if q not in mid and q not in name:
+            continue
+        if mid.startswith(q) or name.startswith(q):
+            score = 2
+        elif q in mid.rsplit("/", 1)[-1] or q in name:
+            score = 1
+        else:
+            score = 0
+        scored.append((score, m))
+    scored.sort(key=lambda t: (-t[0], t[1]["id"]))
+    return [_to_option(m) for _, m in scored[:limit]]
 
 
 def default_effort():
     return None
 
 
+def default_model():
+    cat = catalog()
+    if cat and any(m["id"] == config.OPENROUTER_MODEL for m in cat):
+        return config.OPENROUTER_MODEL
+    # Self-heal: the configured default was retired — fall back to the first
+    # curated model that still exists (or the configured value when offline).
+    ms = models()
+    return ms[0]["id"] if ms else config.OPENROUTER_MODEL
+
+
 def valid_model(model):
-    # Accept any curated model, plus whatever the deployment configured as the
-    # default (so OPENROUTER_MODEL can point at a slug not in the short list).
-    return model == config.OPENROUTER_MODEL or any(m["id"] == model for m in MODELS)
+    if not model:
+        return False
+    cat = catalog()
+    if cat:
+        return any(m["id"] == model for m in cat)
+    # Offline: accept the configured default or any seed slug.
+    return model == config.OPENROUTER_MODEL or any(s["id"] == model for s in SEED_MODELS)
 
 
 def _extra_headers():
@@ -104,5 +224,5 @@ def get_client(model=None, effort=None):
     api_key = os.environ.get("OPENROUTER_API_KEY", "")
     if not api_key:
         return None
-    m = model if valid_model(model) else config.OPENROUTER_MODEL
+    m = model if valid_model(model) else default_model()
     return OpenRouterClient(api_key, m)

From 66ffa259d7b275650d150acb4d545587ec283eb1 Mon Sep 17 00:00:00 2001
From: Prathik Shetty <prathikshetty1411@gmail.com>
Date: Thu, 9 Jul 2026 23:27:28 +0530
Subject: [PATCH 5/7] feat(frontend): searchable model picker with live catalog
 search
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the static model <select> in engine settings with a searchable
combobox. It shows the curated popular few by default and, for providers that
support it (OpenRouter), runs a debounced server-side search against the live
catalog — so the client only ever holds the popular few plus a bounded result
page, never the full ~300-model list.

- ModelCombobox.tsx: debounced (250ms) search, latest-query-wins race guard,
  keyboard nav (up/down/enter/esc), click-outside close; results are derived
  (empty/filter cases) with only async server results held in state; each row
  shows a context-length / $-per-Mtok subtitle
- SettingsModal.tsx: use the combobox for the model field
- api.ts: searchModels() -> GET /api/models/search
- types.ts: ModelOption context_length/pricing + EngineConfig.supports_search

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/components/ModelCombobox.tsx | 176 ++++++++++++++++++++++
 frontend/src/components/SettingsModal.tsx |  14 +-
 frontend/src/lib/api.ts                   |  12 ++
 frontend/src/lib/types.ts                 |   5 +
 4 files changed, 200 insertions(+), 7 deletions(-)
 create mode 100644 frontend/src/components/ModelCombobox.tsx

diff --git a/frontend/src/components/ModelCombobox.tsx b/frontend/src/components/ModelCombobox.tsx
new file mode 100644
index 0000000..3843d48
--- /dev/null
+++ b/frontend/src/components/ModelCombobox.tsx
@@ -0,0 +1,176 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import type { ModelOption } from "@/lib/types";
+import { searchModels } from "@/lib/api";
+
+function fmtCtx(n?: number | null): string | null {
+  if (!n) return null;
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, "")}M ctx`;
+  if (n >= 1000) return `${Math.round(n / 1000)}K ctx`;
+  return `${n} ctx`;
+}
+
+function fmtPrice(p?: { prompt: number; completion: number } | null): string | null {
+  if (!p) return null;
+  return `$${p.prompt}/$${p.completion} per M`;
+}
+
+interface Props {
+  value: string;
+  onChange: (id: string) => void;
+  /** The curated "popular few" from /api/config — the default list. */
+  options: ModelOption[];
+  /** When true, typing hits the live server-side catalog search. */
+  supportsSearch: boolean;
+}
+
+/**
+ * Searchable model picker. Shows the popular few by default; typing runs a
+ * debounced server search (OpenRouter's ~300-model catalog) that returns a
+ * bounded result set, so the client never holds the full list. Falls back to
+ * client-side filtering of `options` when the provider has no search endpoint.
+ */
+export function ModelCombobox({ value, onChange, options, supportsSearch }: Props) {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [serverResults, setServerResults] = useState<ModelOption[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [highlight, setHighlight] = useState(0);
+  const [selectedLabel, setSelectedLabel] = useState(
+    () => options.find((m) => m.id === value)?.label ?? value,
+  );
+  const rootRef = useRef<HTMLDivElement>(null);
+  const seq = useRef(0); // latest-query-wins guard for async results
+
+  const trimmed = query.trim();
+  // Results are derived, not stored: only the async server search needs state.
+  const results: ModelOption[] = !trimmed
+    ? options
+    : supportsSearch
+      ? serverResults
+      : options.filter((m) => {
+          const lc = trimmed.toLowerCase();
+          return m.id.toLowerCase().includes(lc) || m.label.toLowerCase().includes(lc);
+        });
+  const activeIdx = results.length ? Math.min(highlight, results.length - 1) : -1;
+  const searching = loading && !!trimmed && supportsSearch;
+
+  // Close when clicking outside the widget.
+  useEffect(() => {
+    if (!open) return;
+    const onDoc = (e: MouseEvent) => {
+      if (rootRef.current && !rootRef.current.contains(e.target as Node)) setOpen(false);
+    };
+    document.addEventListener("mousedown", onDoc);
+    return () => document.removeEventListener("mousedown", onDoc);
+  }, [open]);
+
+  // Debounced live catalog search. All state writes happen inside the timeout /
+  // promise callbacks, so the effect body itself never sets state synchronously.
+  useEffect(() => {
+    if (!open || !supportsSearch || !trimmed) return;
+    const mine = ++seq.current;
+    const timer = setTimeout(() => {
+      setLoading(true);
+      searchModels(trimmed, 25)
+        .then((r) => {
+          if (mine !== seq.current) return;
+          setServerResults(r);
+          setHighlight(0);
+        })
+        .catch(() => {
+          if (mine === seq.current) setServerResults([]);
+        })
+        .finally(() => {
+          if (mine === seq.current) setLoading(false);
+        });
+    }, 250);
+    return () => clearTimeout(timer);
+  }, [trimmed, open, supportsSearch]);
+
+  const openPanel = () => {
+    setQuery("");
+    setHighlight(0);
+    setOpen(true);
+  };
+
+  const pick = (m: ModelOption) => {
+    onChange(m.id);
+    setSelectedLabel(m.label);
+    setOpen(false);
+  };
+
+  const onKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setHighlight((h) => Math.min(h + 1, results.length - 1));
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setHighlight((h) => Math.max(h - 1, 0));
+    } else if (e.key === "Enter") {
+      e.preventDefault();
+      const m = results[activeIdx];
+      if (m) pick(m);
+    } else if (e.key === "Escape") {
+      setOpen(false);
+    }
+  };
+
+  return (
+    <div ref={rootRef} className="relative min-w-[180px]">
+      <button
+        type="button"
+        onClick={() => (open ? setOpen(false) : openPanel())}
+        className="flex w-full items-center justify-between gap-2 border border-line bg-bg-inset px-2 py-1.5 text-[12px] text-text focus:border-amber focus:outline-none"
+      >
+        <span className="truncate">{selectedLabel}</span>
+        <span className="text-text-faint">▾</span>
+      </button>
+
+      {open && (
+        <div className="absolute right-0 z-50 mt-1 w-[280px] border border-line bg-bg-raised shadow-lg">
+          <input
+            autoFocus
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onKeyDown={onKeyDown}
+            placeholder={supportsSearch ? "search models…" : "filter models…"}
+            className="w-full border-b border-line bg-bg-inset px-2 py-1.5 text-[12px] text-text placeholder:text-text-faint focus:outline-none"
+          />
+          <ul className="max-h-[240px] overflow-y-auto">
+            {searching && <li className="px-2 py-2 text-[11px] text-text-faint">searching…</li>}
+            {!searching && results.length === 0 && (
+              <li className="px-2 py-2 text-[11px] text-text-faint">no models found</li>
+            )}
+            {!searching &&
+              results.map((m, i) => {
+                const sub = [fmtCtx(m.context_length), fmtPrice(m.pricing)]
+                  .filter(Boolean)
+                  .join(" · ");
+                const active = m.id === value;
+                return (
+                  <li key={m.id}>
+                    <button
+                      type="button"
+                      onMouseEnter={() => setHighlight(i)}
+                      onClick={() => pick(m)}
+                      className={`flex w-full flex-col items-start gap-0.5 px-2 py-1.5 text-left ${
+                        i === activeIdx ? "bg-amber/10" : ""
+                      }`}
+                    >
+                      <span className={`text-[12px] ${active ? "text-amber" : "text-text"}`}>
+                        {active ? "✓ " : ""}
+                        {m.label}
+                      </span>
+                      {sub && <span className="text-[10px] text-text-faint">{sub}</span>}
+                    </button>
+                  </li>
+                );
+              })}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/components/SettingsModal.tsx b/frontend/src/components/SettingsModal.tsx
index e51abe3..ec85af8 100644
--- a/frontend/src/components/SettingsModal.tsx
+++ b/frontend/src/components/SettingsModal.tsx
@@ -5,6 +5,7 @@ import type { EngineConfig } from "@/lib/types";
 import { useSettings } from "@/store/settings";
 import { useUI } from "@/store/ui";
 import { Modal } from "./Modal";
+import { ModelCombobox } from "./ModelCombobox";
 
 function Field({ label, children }: { label: string; children: React.ReactNode }) {
   return (
@@ -53,13 +54,12 @@ function SettingsForm({ config, onClose }: { config: EngineConfig; onClose: () =
         </Field>
 
         <Field label="model">
-          <select value={model} onChange={(e) => setModel(e.target.value)} className={selectClass}>
-            {config.models.map((m) => (
-              <option key={m.id} value={m.id}>
-                {m.label}
-              </option>
-            ))}
-          </select>
+          <ModelCombobox
+            value={model}
+            onChange={setModel}
+            options={config.models}
+            supportsSearch={config.supports_search}
+          />
         </Field>
 
         {config.supports_effort && config.efforts.length > 0 && (
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 365a1f2..22f66c4 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -1,6 +1,7 @@
 import type {
   EngineConfig,
   FullProblem,
+  ModelOption,
   ProblemSummary,
   RunResult,
   SessionDetail,
@@ -93,6 +94,17 @@ export function getConfig(): Promise<EngineConfig> {
   return apiGet<EngineConfig>("/config");
 }
 
+/**
+ * Search the provider's model catalog. For OpenRouter this hits the live
+ * ~300-model catalog server-side and returns a bounded result set, so the
+ * client never holds the whole list. An empty query returns the popular few.
+ */
+export async function searchModels(query: string, limit = 25): Promise<ModelOption[]> {
+  const q = encodeURIComponent(query);
+  const res = await apiGet<{ models: ModelOption[] }>(`/models/search?q=${q}&limit=${limit}`);
+  return res.models;
+}
+
 export function getProblem(id: number, language?: string): Promise<FullProblem> {
   const q = language ? `?language=${encodeURIComponent(language)}` : "";
   return apiGet<FullProblem>(`/problems/${id}${q}`);
diff --git a/frontend/src/lib/types.ts b/frontend/src/lib/types.ts
index 4cf7565..f235407 100644
--- a/frontend/src/lib/types.ts
+++ b/frontend/src/lib/types.ts
@@ -101,6 +101,9 @@ export interface LanguageMeta {
 export interface ModelOption {
   id: string;
   label: string;
+  /** Present for OpenRouter models fetched from the live catalog. */
+  context_length?: number | null;
+  pricing?: { prompt: number; completion: number } | null;
 }
 
 export interface EngineConfig {
@@ -110,6 +113,8 @@ export interface EngineConfig {
   supports_effort: boolean;
   efforts: string[];
   default_effort: string;
+  /** True when the provider backs a live /api/models/search (OpenRouter). */
+  supports_search: boolean;
   languages: LanguageMeta[];
   default_language: string;
 }

From c0d8c9a68bf9736a9c929865668ff81f0d71a457 Mon Sep 17 00:00:00 2001
From: Prathik Shetty <prathikshetty1411@gmail.com>
Date: Thu, 9 Jul 2026 23:52:21 +0530
Subject: [PATCH 6/7] fix(frontend): hide document overflow and use dvh on
 large screens

Prevents a dead scrollbar track and sub-pixel gap by hiding html/body overflow. Also switches to dvh for dynamic viewport height.
---
 frontend/src/app/globals.css | 12 ++++++++++++
 frontend/src/app/page.tsx    |  2 +-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/frontend/src/app/globals.css b/frontend/src/app/globals.css
index a7abb4f..fbbf21d 100644
--- a/frontend/src/app/globals.css
+++ b/frontend/src/app/globals.css
@@ -80,6 +80,18 @@ html {
   scrollbar-gutter: stable;
 }
 
+/* On large screens the app shell pins to the viewport (lg:h-dvh) and each panel
+   scrolls on its own, so the document itself must never scroll. Without this the
+   reserved gutter renders as a dead scrollbar track and sub-pixel rounding of the
+   viewport-height shell leaves a thin strip of empty space below the fold. On
+   small screens the page still scrolls normally. */
+@media (min-width: 64rem) {
+  html,
+  body {
+    overflow: hidden;
+  }
+}
+
 /* During the cold-boot caret flight the logo holds an empty (invisible) caret
    slot — the travelling cursor IS the only caret on screen until it lands. */
 html.caret-flying .caret {
diff --git a/frontend/src/app/page.tsx b/frontend/src/app/page.tsx
index ffa6002..be560a3 100644
--- a/frontend/src/app/page.tsx
+++ b/frontend/src/app/page.tsx
@@ -34,7 +34,7 @@ export default function Home() {
   }, []);
 
   return (
-    <main className="flex min-h-screen flex-col lg:h-screen lg:min-h-0 lg:overflow-hidden">
+    <main className="flex min-h-dvh flex-col lg:h-dvh lg:min-h-0 lg:overflow-hidden">
       <TopBar />
       {/* On desktop the page is pinned to the viewport and each panel scrolls
           on its own; on mobile it falls back to normal page scroll. */}

From 624fcfb5f653813fe98f26db5a0eb2f33c71fbcb Mon Sep 17 00:00:00 2001
From: Prathik Shetty <prathikshetty1411@gmail.com>
Date: Thu, 9 Jul 2026 23:55:30 +0530
Subject: [PATCH 7/7] feat(docs): update README for multi-AI engine support and
 UI updates

- Default to Claude Code CLI (no API key needed), add OpenAI/OpenRouter as options
- Switch npm to pnpm, update setup instructions
- Add resizable panels with remembered widths, narrow-screen tabs
- Mark voice mode as temporarily unavailable, note TTS rework
- Update FAQ for AI models, pricing, data storage
- Fix LinkedIn link
---
 README.md | 55 ++++++++++++++++++++++++-------------------------------
 1 file changed, 24 insertions(+), 31 deletions(-)

diff --git a/README.md b/README.md
index f8d2e96..1ea718d 100644
--- a/README.md
+++ b/README.md
@@ -3,10 +3,10 @@
 <div align="center">
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Next.js](https://img.shields.io/badge/next.js-16-000000?logo=nextdotjs&logoColor=white)](https://nextjs.org/)
 [![PostgreSQL](https://img.shields.io/badge/postgres-16-336791?logo=postgresql&logoColor=white)](https://www.postgresql.org/)
-[![Powered by GPT-4o](https://img.shields.io/badge/powered%20by-GPT--4o-412991?logo=openai&logoColor=white)](https://platform.openai.com/)
+[![AI: Claude / OpenAI / OpenRouter](https://img.shields.io/badge/AI-Claude%20%2F%20OpenAI%20%2F%20OpenRouter-ffb000)]()
 [![Self-hostable](https://img.shields.io/badge/self--hostable-brightgreen?logo=docker&logoColor=white)]()
-[![Voice support](https://img.shields.io/badge/voice-WebRTC-blueviolet?logo=googlemeet&logoColor=white)]()
 
 </div>
 
@@ -19,7 +19,7 @@ Most interview platforms are puzzle grinders. O(1) Prep puts you in a real inter
 - **A back-and-forth, not a quiz** - the interviewer follows up, pushes back on your reasoning, and adds constraints mid-session just like a real one would
 - **Feedback that actually tells you something** - you get written scores and specific critique on your approach, code quality, communication, and tradeoffs - not just pass/fail
 - **Your own account** - sign in and your sessions, history, and code are saved to your account in the app's database; self-host it and the data stays on infrastructure you control
-- **Practice out loud** - voice mode lets you talk through your solution the way you would in an actual interview
+- **Bring your own engine** - runs on your local Claude Code CLI by default (no API key), or point it at OpenAI or OpenRouter (one key, hundreds of models)
 - **150+ problems grounded in real engineering** - each one has a real-world scenario, not just "given an array..."
 
 ---
@@ -38,12 +38,14 @@ python3 -m venv venv && source venv/bin/activate
 pip install -r requirements.txt
 ```
 
-Copy `backend/.env.example` to `backend/.env` and set your values (database URL, a secret key, and your OpenAI key):
+Copy `backend/.env.example` to `backend/.env` and set your values. By default the AI engine is your local **Claude Code CLI** — no API key, just run `claude` once to sign in. Set `AI_PROVIDER` to `openai` or `openrouter` to use those instead (see `.env.example` for their keys).
 
 ```
 DATABASE_URL=postgresql+psycopg://o1prep:o1prep@localhost:5433/o1prep
 SECRET_KEY=change-me
-OPENAI_API_KEY=sk-your-key-here
+AI_PROVIDER=claude              # claude (default) | openai | openrouter
+# OPENAI_API_KEY=sk-...         # only when AI_PROVIDER=openai
+# OPENROUTER_API_KEY=sk-or-...  # only when AI_PROVIDER=openrouter
 ```
 
 Create the schema, load the problems, and run — all from `backend/`:
@@ -64,20 +66,20 @@ API. In a second terminal:
 
 ```bash
 cd frontend
-npm install
-npm run dev                           # http://localhost:3000
+pnpm install
+pnpm dev                              # http://localhost:3000
 ```
 
 Open **http://localhost:3000**. The dev server proxies `/api/*` to Flask on
 `127.0.0.1:5000` (see `frontend/next.config.ts`), so the session cookie stays
 same-origin and auth works with no CORS setup. Point it elsewhere with
-`API_ORIGIN=http://host:port npm run dev`.
+`API_ORIGIN=http://host:port pnpm dev`.
 
 > On macOS, the AirPlay Receiver squats on port 5000 over IPv6 — the proxy
 > targets `127.0.0.1` (IPv4) specifically to avoid it. If you change the Flask
 > port, update `API_ORIGIN`.
 
-> **Prerequisites:** Python 3.11+, Node.js 20+, Docker (for PostgreSQL), a paid OpenAI API key, and a modern browser (Chrome/Firefox/Safari).
+> **Prerequisites:** Python 3.11+, Node.js 20+ and [pnpm](https://pnpm.io), Docker (for PostgreSQL), an AI engine (the Claude Code CLI needs no key; OpenAI/OpenRouter need an API key), and a modern browser (Chrome/Firefox/Safari).
 
 ---
 
@@ -138,7 +140,7 @@ Read a problem fully and chat with an AI tutor before you practice - useful when
 
 ![Study mode with problem details and research chat](docs/screenshots/StudyMode.png)
 
-Two resizable panels side by side. The left panel has the full problem - scenario, constraints, examples, key skills, and follow-up challenges. The right panel is a tutor chat where you can ask anything about the problem without being handed the solution.
+Two panels side by side — drag the divider to resize the tutor chat, and its width is remembered. The left panel has the full problem - scenario, constraints, examples, key skills, and follow-up challenges. The right panel is a tutor chat where you can ask anything about the problem without being handed the solution.
 
 Good things to ask the tutor:
 
@@ -154,7 +156,7 @@ When you're ready, go back and hit **Practice** to start the interview.
 
 ![Interview mode with chat, code editor, test results, and tutor sidebar](docs/screenshots/PracticeAndEvaluateResult.png)
 
-Three panels: the interviewer chat on the left, your code editor in the center, and an optional tutor sidebar on the right. All dividers are draggable.
+Three panels: the interviewer chat on the left, your code editor in the center, and an optional tutor sidebar on the right. On a narrow screen, tabs switch between the chat and the editor.
 
 The interview runs like a real one - you'll clarify the problem, talk through your approach, then implement. The interviewer watches what you submit and responds to it. You can submit code multiple times; each submission gets reviewed.
 
@@ -178,27 +180,15 @@ The interviewer gives a structured debrief with a hire/no-hire rating, scores ac
 
 ## Voice Interviews
 
-Practice talking through your solution the way you actually would in an interview.
+> **Status: temporarily unavailable in the web client.** Voice mode is being reworked to route through a natural-sounding neural TTS provider — the browser's built-in speech synthesis sounded too robotic for a realistic interview. The pipeline (browser speech-to-text → your chosen LLM → text-to-speech) is in place behind the scenes and will return once a good TTS voice is wired in.
 
-![Voice interview mode with live transcript banner](docs/screenshots/VoiceModeToEmulateRealInterviews.png)
-
-Switch to **Voice** mode in the toggle before starting. Once the interview begins, allow microphone access and wait for the connection. Your speech is transcribed live, the interviewer responds through your speakers, and everything is saved to your history just like a text session.
-
-You can still write and submit code while in voice mode - just click **Submit Code** as normal.
-
-### Troubleshooting
-
-**Mic access denied** - Go to browser site settings for `localhost`, allow microphone, then reload.
-
-**No audio from interviewer** - Check system audio output. Audio routes through the browser.
-
-**Connection drops** - End the session and start a new one. Your previous session is preserved in History.
+The intent: switch to **Voice** mode before starting and talk through your solution out loud — your speech is transcribed live, the interviewer replies through your speakers, and the whole session is saved to your history just like a text one, all while you can still write and **Submit Code**.
 
 ---
 
 ## Code Editor & Execution
 
-Multi-language editor (Python or JavaScript, picked from the language selector) with syntax highlighting, auto-closing brackets, line numbers, and smart indentation. Switching language loads that language's starter code and runs against its test suite. Your code is auto-saved every 2 seconds - you won't lose it if you navigate away.
+A CodeMirror editor (Python, JavaScript, or TypeScript, picked from the language selector) with syntax highlighting, auto-closing brackets, line numbers, and smart indentation. Switching language loads that language's starter code and runs against its test suite. Your code is auto-saved as you type - you won't lose it if you navigate away.
 
 | Button    | What it does                                                       |
 | --------- | ------------------------------------------------------------------ |
@@ -313,11 +303,11 @@ Each category shows a progress bar and lists the problems you've attempted with
 
 ## FAQ
 
-**Do I need a paid OpenAI account?**
-Yes. The interviewer uses GPT-4o, which requires a paid API key. Voice mode additionally uses the Realtime API.
+**Do I need a paid AI account?**
+Not necessarily. The default engine is your local **Claude Code CLI**, which runs on your existing Claude sign-in with no separate API key. If you prefer, set `AI_PROVIDER=openai` or `openrouter` and supply that key instead.
 
 **How much does each interview cost?**
-Roughly $0.10-$0.50 per text session depending on length. Voice sessions cost more due to Realtime API audio pricing.
+On the default Claude CLI engine it draws on your Claude usage rather than a per-call charge. On OpenAI or OpenRouter it's pay-per-token — roughly $0.10-$0.50 per text session depending on length and the model you pick.
 
 **Can I use other programming languages?**
 Yes. Pick Python or JavaScript from the language selector in the editor; the code
@@ -326,6 +316,9 @@ it, or set `NODE_BIN`). TypeScript is also wired up (via `tsx`/`TS_CMD`).
 Problems are translated per language, so the selector offers whichever languages
 a given problem has been authored for.
 
+**Can I pick a different model?**
+Yes. The **Settings** (gear) menu lets you choose the model and reasoning effort for new interviews and tutor chats. On OpenRouter you can search its live catalog of hundreds of models; on Claude and OpenAI you pick from that provider's list.
+
 **What happens if I close the browser mid-interview?**
 The session is auto-saved every time you send a message or submit code. Open History to resume from where you left off.
 
@@ -336,7 +329,7 @@ Yes. Multiple sessions on the same problem are tracked separately. The status do
 That's what makes it useful. Vague feedback doesn't help you improve. The debrief is written the way a hiring committee would actually talk about your performance.
 
 **Where is my data stored?**
-In the application's PostgreSQL database, scoped to your account. If you self-host, that database runs on infrastructure you control. Your messages and code are sent to OpenAI's API to power the interviewer.
+In the application's PostgreSQL database, scoped to your account. If you self-host, that database runs on infrastructure you control. Your messages and code are sent to your configured AI provider (Claude, OpenAI, or OpenRouter) to power the interviewer.
 
 **Can I add my own problems?**
 Yes - see [CONTRIBUTING.md](CONTRIBUTING.md) for the full problem YAML format.
@@ -353,4 +346,4 @@ This project is a fork of [codingprep](https://github.com/amrutha97/codingprep)
 
 ## Contact
 
-Questions or feedback? Reach out on [LinkedIn](https://github.com/shettydev).
+Questions or feedback? Reach out on [LinkedIn](https://www.linkedin.com/in/shettydev/).