claude code; tavily; bugs fix..

app.py

@@ -67,6 +67,11 @@ class ApiKeyRequest(BaseModel):
     key: str
 
 
+class TavilyKeyRequest(BaseModel):
+    user_id: str
+    key: str
+
+
 class ProfileRequest(BaseModel):
     user_id: str
     profile: str
@@ -135,7 +140,8 @@ def google_login(req: GoogleAuthRequest):
         picture=idinfo.get("picture", ""),
     )
     has_key = bool(db.get_user_api_key(idinfo["sub"]))
-    return {"user": user, "has_api_key": has_key}
+    has_tavily = bool(db.get_tavily_key(idinfo["sub"]))
+    return {"user": user, "has_api_key": has_key, "has_tavily_key": has_tavily}
 
 
 @app.get("/auth/me")
@@ -146,7 +152,11 @@ def get_me(user_id: str = ""):
     user = db.get_user(user_id)
     if not user:
         return JSONResponse({"error": "User not found"}, status_code=404)
-    return {"user": user, "has_api_key": bool(user.get("openrouter_key"))}
+    return {
+        "user": user,
+        "has_api_key": bool(user.get("openrouter_key")),
+        "has_tavily_key": bool(user.get("tavily_key")),
+    }
 
 
 @app.get("/auth/client_id")
@@ -163,6 +173,12 @@ def save_api_key(req: ApiKeyRequest):
     return {"ok": True}
 
 
+@app.post("/user/tavilykey")
+def save_tavily_key(req: TavilyKeyRequest):
+    db.save_tavily_key(req.user_id, req.key)
+    return {"ok": True, "has_tavily_key": bool(req.key.strip())}
+
+
 @app.post("/user/profile")
 def save_profile(req: ProfileRequest):
     db.save_student_profile(req.user_id, req.profile)
@@ -255,9 +271,11 @@ def chat(request: ChatRequest, req: Request):
 
     # Resolve user-specific data
     user_api_key = ""
+    tavily_key = ""
     student_profile = ""
     if request.user_id:
         user_api_key = db.get_user_api_key(request.user_id)
+        tavily_key = db.get_tavily_key(request.user_id)
         user_data = db.get_user(request.user_id)
         if user_data:
             student_profile = user_data.get("student_profile", "")
@@ -302,7 +320,7 @@ def chat(request: ChatRequest, req: Request):
         if web_search_enabled:
             yield sse_tool_event("tool_start", "web_search")
             try:
-                web_results = run_web_search(clean_message)
+                web_results = run_web_search(clean_message, api_key=tavily_key)
                 print(f"[WEB SEARCH] Fetched {len(web_results)} chars for: {clean_message[:60]}", flush=True)
                 context += f"\n\n[Web Search Results]\n{web_results}\n[End Web Search Results]\n"
             except Exception as e:

config.py

@@ -8,6 +8,9 @@ GOOGLE_CLIENT_ID  = os.environ.get("GOOGLE_CLIENT_ID", "")
 # Optional: shared fallback key (users bring their own via BYOK)
 OPENROUTER_API_KEY = os.environ.get("OPENROUTER_API_KEY", "")
 
+# Optional: shared Tavily web-search fallback key (users bring their own via BYOK)
+TAVILY_API_KEY = os.environ.get("TAVILY_API_KEY", "")
+
 # --- LangSmith (tracing & analytics) ---
 os.environ["LANGCHAIN_TRACING_V2"] = os.environ.get("LANGSMITH_TRACING", "true")
 os.environ["LANGCHAIN_API_KEY"] = os.environ.get("LANGSMITH_API_KEY", "")

db.py

@@ -19,12 +19,19 @@ conn.execute("""
         name            TEXT NOT NULL,
         picture         TEXT,
         openrouter_key  TEXT,
+        tavily_key      TEXT,
         student_profile TEXT,
         created_at      REAL NOT NULL,
         last_login      REAL NOT NULL
     )
 """)
 
+# Upgrade path: add tavily_key column to pre-existing databases.
+try:
+    conn.execute("ALTER TABLE users ADD COLUMN tavily_key TEXT")
+except sqlite3.OperationalError:
+    pass  # column already exists
+
 conn.execute("""
     CREATE TABLE IF NOT EXISTS thread_titles (
         thread_id   TEXT PRIMARY KEY,
@@ -63,7 +70,7 @@ def upsert_user(google_id: str, email: str, name: str, picture: str = "") -> dic
 
 def get_user(google_id: str) -> dict | None:
     row = conn.execute(
-        "SELECT google_id, email, name, picture, openrouter_key, student_profile "
+        "SELECT google_id, email, name, picture, openrouter_key, student_profile, tavily_key "
         "FROM users WHERE google_id = ?",
         (google_id,),
     ).fetchone()
@@ -73,6 +80,7 @@ def get_user(google_id: str) -> dict | None:
         "google_id": row[0], "email": row[1], "name": row[2],
         "picture": row[3], "openrouter_key": row[4] or "",
         "student_profile": row[5] or "",
+        "tavily_key": row[6] or "",
     }
 
 
@@ -83,6 +91,20 @@ def save_user_api_key(google_id: str, key: str):
     conn.commit()
 
 
+def save_tavily_key(google_id: str, key: str):
+    conn.execute(
+        "UPDATE users SET tavily_key = ? WHERE google_id = ?", (key, google_id)
+    )
+    conn.commit()
+
+
+def get_tavily_key(google_id: str) -> str:
+    row = conn.execute(
+        "SELECT tavily_key FROM users WHERE google_id = ?", (google_id,)
+    ).fetchone()
+    return row[0] if row and row[0] else ""
+
+
 def save_student_profile(google_id: str, profile: str):
     conn.execute(
         "UPDATE users SET student_profile = ? WHERE google_id = ?", (profile, google_id)

graph.py

@@ -23,6 +23,7 @@ from typing import TypedDict, Annotated
 import sqlite3
 import time
 import json
+import base64
 import urllib.request
 import threading
 from langgraph.checkpoint.sqlite import SqliteSaver  # type:ignore
@@ -30,14 +31,68 @@ from config import OPENROUTER_API_KEY, DB_PATH, LLM_TIMEOUT
 import prompts
 
 
+# ── LangSmith document attachment (surfaces the raw uploaded file) ──
+# Optional: only active if the installed langsmith SDK supports attachments.
+try:
+    from langsmith import traceable
+    try:
+        from langsmith import Attachment  # type:ignore
+    except ImportError:
+        from langsmith.schemas import Attachment  # type:ignore
+    _LANGSMITH_ATTACH = True
+except Exception:
+    traceable = None       # type:ignore
+    Attachment = None      # type:ignore
+    _LANGSMITH_ATTACH = False
+
+_MIME_BY_EXT = {
+    "pdf":  "application/pdf",
+    "docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "doc":  "application/msword",
+    "txt":  "text/plain",
+    "md":   "text/markdown",
+    "csv":  "text/csv",
+    "json": "application/json",
+}
+
+
+def _guess_mime(filename: str) -> str:
+    ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+    return _MIME_BY_EXT.get(ext, "application/octet-stream")
+
+
+if _LANGSMITH_ATTACH:
+    @traceable(name="uploaded_document")
+    def _trace_document(filename: str, document) -> str:  # noqa: ANN001
+        """Nested run that carries the raw user-uploaded file as a LangSmith attachment."""
+        return f"Attached document: {filename}"
+
+
+def _attach_document(doc_name: str, doc_bytes_b64: str) -> None:
+    """Surface the original uploaded document in the active LangSmith trace.
+
+    Best-effort: any failure (old SDK, no API key, decode error) is swallowed so
+    tracing can never break the chat response.
+    """
+    if not (_LANGSMITH_ATTACH and doc_bytes_b64):
+        return
+    try:
+        raw = base64.b64decode(doc_bytes_b64)
+        name = doc_name or "uploaded_document"
+        _trace_document(name, Attachment(mime_type=_guess_mime(name), data=raw))
+    except Exception as exc:
+        print(f"[LANGSMITH ATTACH] skipped: {exc}", flush=True)
+
+
 # ── Checkpointer ──────────────────────────────────────────────
 _conn = sqlite3.connect(DB_PATH, check_same_thread=False)
 checkpointer = SqliteSaver(conn=_conn)
 
 
 # ── Constants ─────────────────────────────────────────────────
-DEFAULT_MODEL = "openai/gpt-oss-120b:free"
-MODELS_TTL    = 10 * 60   # seconds
+DEFAULT_MODEL        = "openai/gpt-oss-120b:free"          # pinned default for text
+DEFAULT_VISION_MODEL = "nvidia/nemotron-nano-12b-v2-vl:free"  # pinned default for vision
+MODELS_TTL           = 10 * 60   # seconds
 
 
 def _is_guardrail(model_id: str) -> bool:
@@ -84,7 +139,7 @@ _SCIENCE_KW = [
     "wave", "wavelength", "frequency", "amplitude",
     "light", "optics", "lens", "mirror", "refraction", "reflection",
     "electric", "magnetic", "electromagnetic", "circuit", "resistance",
-    "gravity", "gravitational", "newton", "coulomb",
+    "gravity", "gravitational", "newton", "coulomb", "charge",
     "reaction", "compound", "element", "bond", "orbital",
     "hybridisation", "hybridization", "valence",
     "thermodynamics", "entropy", "enthalpy",
@@ -143,6 +198,12 @@ _lock = threading.Lock()
 _counters: dict[str, int] = {}
 
 
+def _ensure_pinned(pool: list, pinned_id: str, vision: bool = False) -> list:
+    """Guarantee the pinned default model sits at the front of a pool."""
+    rest = [e for e in pool if e["id"] != pinned_id]
+    return [{"id": pinned_id, "score": 999, "vision": vision}] + rest
+
+
 def _fetch_pools() -> dict:
     """Fetch free models, detect vision support, build sorted pools."""
     global _cache, _cache_at
@@ -185,11 +246,11 @@ def _fetch_pools() -> dict:
         vision_all.sort(key=lambda x: x["score"], reverse=True)
 
         pools = {
-            "reasoning": text_all[:6],
-            "science":   text_all[:8],
-            "general":   text_all[:10],
+            "reasoning": _ensure_pinned(text_all[:6],  DEFAULT_MODEL),
+            "science":   _ensure_pinned(text_all[:8],  DEFAULT_MODEL),
+            "general":   _ensure_pinned(text_all[:10], DEFAULT_MODEL),
             "casual":    text_all[-5:][::-1] if len(text_all) >= 5 else text_all[:3],
-            "vision":    vision_all,
+            "vision":    _ensure_pinned(vision_all, DEFAULT_VISION_MODEL, vision=True),
         }
 
         with _lock:
@@ -206,10 +267,14 @@ def _fetch_pools() -> dict:
 
     except Exception as exc:
         print(f"[ROUTER] Fetch failed: {exc}")
-        fallback_entry = {"id": DEFAULT_MODEL, "score": 50, "vision": False}
+        fallback_text   = {"id": DEFAULT_MODEL,        "score": 999, "vision": False}
+        fallback_vision = {"id": DEFAULT_VISION_MODEL, "score": 999, "vision": True}
         return _cache or {
-            k: [fallback_entry]
-            for k in ("reasoning", "science", "general", "casual", "vision")
+            "reasoning": [fallback_text],
+            "science":   [fallback_text],
+            "general":   [fallback_text],
+            "casual":    [fallback_text],
+            "vision":    [fallback_vision],
         }
 
 
@@ -307,6 +372,12 @@ def chat_node(state: ChatState, config: RunnableConfig):
     override  = cfg.get("model", "")
     search_enabled = cfg.get("search_enabled", False)
     has_image = cfg.get("has_image", False)
+    doc_bytes = cfg.get("doc_bytes", "")
+    doc_name  = cfg.get("doc_name", "")
+
+    # Surface the raw uploaded document in the LangSmith trace (not just its text).
+    if doc_bytes:
+        _attach_document(doc_name, doc_bytes)
 
     user_text = _extract_text(state["messages"])
     category  = _classify(user_text)

requirements.txt

@@ -11,9 +11,7 @@ resend
 torch --index-url https://download.pytorch.org/whl/cpu
 google-auth
 langsmith
-langchain-community
-duckduckgo-search
-ddgs
+tavily-python
 youtube-transcript-api
 pdfplumber
 python-docx

static/app.js

@@ -18,6 +18,7 @@ let isHeroMode = true;
 
 let isWebSearchEnabled = false;
 let isYtSearchEnabled = false;
+let hasTavilyKey = false;
 let pendingDocText = '';
 let pendingDocName = '';
 let pendingDocBytes = '';
@@ -78,6 +79,9 @@ const profileInput = document.getElementById('profileInput');
 const saveProfileBtn = document.getElementById('saveProfileBtn');
 const settingsApiKeyInput = document.getElementById('settingsApiKeyInput');
 const saveApiKeyBtn = document.getElementById('saveApiKeyBtn');
+const settingsTavilyKeyInput = document.getElementById('settingsTavilyKeyInput');
+const saveTavilyKeyBtn = document.getElementById('saveTavilyKeyBtn');
+const byokTavilyInput = document.getElementById('byokTavilyInput');
 
 const attachPlusBtn = document.getElementById('attachPlusBtn');
 const attachMenu = document.getElementById('attachMenu');
@@ -444,6 +448,7 @@ function handleGoogleCredential(response) {
             localStorage.setItem('stemcopilot_user', JSON.stringify(currentUser));
             currentUsername = currentUser.name;
             localStorage.setItem('stemcopilot_username', currentUsername);
+            hasTavilyKey = !!data.has_tavily_key;
             if (!data.has_api_key) showByok(); else showApp();
         }).catch(() => showToast('Login failed. Check your connection.', 'error'));
 }
@@ -458,6 +463,7 @@ function checkExistingSession() {
             .then(data => {
                 if (data.error) { localStorage.removeItem('stemcopilot_user'); currentUser = null; initGoogleAuth(); return; }
                 currentUser = data.user;
+                hasTavilyKey = !!data.has_tavily_key;
                 if (!data.has_api_key) showByok(); else showApp();
             }).catch(() => initGoogleAuth());
     } else initGoogleAuth();
@@ -475,8 +481,16 @@ function showByok() {
 if (byokSubmitBtn) byokSubmitBtn.addEventListener('click', () => {
     const key = byokInput.value.trim();
     if (!key) { byokInput.focus(); return; }
+    const tavilyKey = byokTavilyInput ? byokTavilyInput.value.trim() : '';
     fetch('/user/apikey', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ user_id: currentUser.google_id, key: key }) })
         .then(r => { if (!r.ok) throw new Error(); return r.json(); })
+        .then(() => {
+            // Optionally save the Tavily key, then enter the app regardless.
+            if (tavilyKey) {
+                return fetch('/user/tavilykey', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ user_id: currentUser.google_id, key: tavilyKey }) })
+                    .then(() => { hasTavilyKey = true; });
+            }
+        })
         .then(() => showApp())
         .catch(() => showToast('Failed to save key.', 'error'));
 });
@@ -507,7 +521,10 @@ function showApp() {
                 if (data.user) {
                     if (data.user.student_profile && profileInput) profileInput.value = data.user.student_profile;
                     if (data.user.openrouter_key && settingsApiKeyInput) settingsApiKeyInput.value = '••••••••••••';
+                    if (data.user.tavily_key && settingsTavilyKeyInput) settingsTavilyKeyInput.value = '••••••••••••';
                 }
+                hasTavilyKey = !!data.has_tavily_key;
+                _applyWebSearchAvailability();
             }).catch(() => { });
     }
 
@@ -1063,6 +1080,24 @@ if (saveApiKeyBtn) saveApiKeyBtn.addEventListener('click', () => {
         .finally(() => { saveApiKeyBtn.disabled = false; saveApiKeyBtn.textContent = 'Save Key'; });
 });
 
+if (saveTavilyKeyBtn) saveTavilyKeyBtn.addEventListener('click', () => {
+    const key = settingsTavilyKeyInput.value.trim();
+    // Allow saving an empty value to clear/disable web search; ignore the masked placeholder.
+    if (key.startsWith('••')) return;
+    if (!currentUser) return;
+    saveTavilyKeyBtn.disabled = true; saveTavilyKeyBtn.textContent = 'Saving...';
+    fetch('/user/tavilykey', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ user_id: currentUser.google_id, key: key }) })
+        .then(r => { if (!r.ok) throw new Error(); return r.json(); })
+        .then((data) => {
+            hasTavilyKey = !!data.has_tavily_key;
+            _applyWebSearchAvailability();
+            if (settingsTavilyKeyInput) settingsTavilyKeyInput.value = hasTavilyKey ? '••••••••••••' : '';
+            showToast(hasTavilyKey ? 'Tavily key saved! Web search enabled.' : 'Tavily key cleared. Web search disabled.', 'success');
+        })
+        .catch(() => showToast('Failed to save Tavily key.', 'error'))
+        .finally(() => { saveTavilyKeyBtn.disabled = false; saveTavilyKeyBtn.textContent = 'Save Key'; });
+});
+
 if (saveProfileBtn) saveProfileBtn.addEventListener('click', () => {
     if (!currentUser) return;
     fetch('/user/profile', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ user_id: currentUser.google_id, profile: profileInput.value }) })
@@ -1411,6 +1446,27 @@ function _syncToggles() {
     });
 }
 
+function _applyWebSearchAvailability() {
+    // Web search requires a Tavily API key. Without one, grey out the toggles.
+    const webToggles = [
+        webSearchToggle,
+        document.getElementById('heroWebSearchToggle'),
+        document.getElementById('heroWebSearchToggleDynamic')
+    ].filter(Boolean);
+
+    webToggles.forEach(el => {
+        el.classList.toggle('web-search-disabled', !hasTavilyKey);
+        el.title = hasTavilyKey ? '' : 'Add a Tavily API key in Settings to enable web search';
+    });
+
+    // If the key was removed while web search was on, turn it off.
+    if (!hasTavilyKey && isWebSearchEnabled) {
+        isWebSearchEnabled = false;
+        _syncToggles();
+        _updateInputPlaceholder();
+    }
+}
+
 function _updateInputPlaceholder() {
     let placeholder = 'Ask STEM Copilot...';
     if (isWebSearchEnabled) {
@@ -1446,6 +1502,12 @@ function setupAttachMenu(plusBtn, menuEl, webSearchToggleEl, ytSearchToggleEl, a
     if (webSearchToggleEl) {
         webSearchToggleEl.addEventListener('click', (e) => {
             e.stopPropagation();
+            if (!hasTavilyKey) {
+                showToast('Add a Tavily API key in Settings to enable web search.', 'info');
+                menuEl.classList.remove('show');
+                plusBtn.classList.remove('open');
+                return;
+            }
             isWebSearchEnabled = !isWebSearchEnabled;
             if (isWebSearchEnabled) isYtSearchEnabled = false;
             _syncToggles();

static/index.html

@@ -15,7 +15,7 @@
     <meta name="theme-color" content="#0a0a0a">
     <link rel="icon" type="image/png" href="/assets/bot.png">
     <link rel="manifest" href="/manifest.json">
-    <link rel="apple-touch-icon" href="/assets/stem_transparent.png">
+    <link rel="apple-touch-icon" href="/assets/stem_black.png">
     <!-- Preconnect for faster font/CDN loading -->
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
@@ -89,8 +89,17 @@
             </ol>
             <input type="text" id="byokInput" class="settings-input" placeholder="Paste your OpenRouter API key here"
                 autocomplete="off" spellcheck="false">
+            <div class="byok-optional">
+                <p class="byok-optional-label">Tavily API key <span class="byok-optional-badge">Optional</span></p>
+                <p class="byok-optional-desc">Add it to unlock live web search. Skip it and web search stays disabled.</p>
+                <input type="text" id="byokTavilyInput" class="settings-input" placeholder="Paste your Tavily API key (optional)"
+                    autocomplete="off" spellcheck="false">
+                <p class="byok-optional-hint">Get a free Tavily key at
+                    <a href="https://app.tavily.com/home" target="_blank" rel="noopener">app.tavily.com</a>
+                </p>
+            </div>
             <button class="byok-submit-btn" id="byokSubmitBtn">Start Learning</button>
-            <p class="byok-note">Your key is stored securely and never shared.</p>
+            <p class="byok-note">Your keys are stored securely and never shared.</p>
         </div>
     </div>
 
@@ -564,6 +573,15 @@
                             Get your free key at <a href="https://openrouter.ai/workspaces/default/keys" target="_blank"
                                 rel="noopener">openrouter.ai/keys</a>
                         </p>
+
+                        <h3 class="settings-section-title">Tavily API Key <span class="settings-optional-badge">Optional</span></h3>
+                        <input type="password" class="settings-input" id="settingsTavilyKeyInput" placeholder="tvly-..."
+                            autocomplete="off" spellcheck="false">
+                        <button class="settings-save-btn" id="saveTavilyKeyBtn">Save Key</button>
+                        <p class="settings-hint">
+                            Enables live web search. Get a free key at
+                            <a href="https://app.tavily.com/home" target="_blank" rel="noopener">app.tavily.com</a>
+                        </p>
                     </div>
 
                     <!-- Profile Tab -->

static/manifest.json

@@ -11,13 +11,13 @@
   "prefer_related_applications": false,
   "icons": [
     {
-      "src": "/assets/stem_transparent.png",
+      "src": "/assets/stem_black.png",
       "sizes": "512x512",
       "type": "image/png",
       "purpose": "any"
     },
     {
-      "src": "/assets/stem_transparent.png",
+      "src": "/assets/stem_black.png",
       "sizes": "512x512",
       "type": "image/png",
       "purpose": "maskable"

static/style.css

@@ -297,6 +297,51 @@ textarea, input, select {
     margin-top: 12px;
 }
 
+/* Optional Tavily key block on the BYOK screen */
+.byok-optional {
+    margin-top: 18px;
+    padding-top: 16px;
+    border-top: 1px solid var(--border);
+    text-align: left;
+}
+.byok-optional-label {
+    font-size: 13px;
+    font-weight: 600;
+    margin: 0 0 4px;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+.byok-optional-badge,
+.settings-optional-badge {
+    font-size: 10px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--brand);
+    background: color-mix(in srgb, var(--brand) 14%, transparent);
+    padding: 2px 7px;
+    border-radius: 999px;
+}
+.byok-optional-desc {
+    font-size: 12px;
+    color: var(--text-muted);
+    margin: 0 0 10px;
+}
+.byok-optional-hint {
+    font-size: 11px;
+    color: var(--text-muted);
+    margin-top: 8px;
+}
+.byok-optional-hint a { color: var(--brand); text-decoration: none; }
+.byok-optional-hint a:hover { text-decoration: underline; }
+
+/* Disabled web-search toggle (no Tavily key) */
+.web-search-disabled {
+    opacity: 0.45;
+    cursor: not-allowed;
+}
+
 
 /* ============================================================
    PWA INSTALL BANNER

sw.js

@@ -1,11 +1,11 @@
 // STEM Copilot — Service Worker (PWA installability + basic cache)
-const CACHE_NAME = 'stemcopilot-v1';
+const CACHE_NAME = 'stemcopilot-v2';
 const SHELL_URLS = [
   '/',
   '/static/style.css',
   '/static/app.js',
   '/assets/bot.png',
-  '/assets/stem_transparent.png',
+  '/assets/stem_black.png',
   '/assets/stembotix.png',
 ];
 

tools.py

@@ -1,46 +1,81 @@
 from __future__ import annotations
 import re
-from langchain_community.tools import DuckDuckGoSearchResults
 from langchain_core.tools import tool
-from duckduckgo_search import DDGS #type:ignore
+from tavily import TavilyClient  # type:ignore
 from youtube_transcript_api import YouTubeTranscriptApi #type:ignore
+from config import TAVILY_API_KEY
 
-# ── Web Search ────────────────────────────────────────────────
-web_search = DuckDuckGoSearchResults(
-    name="web_search",
-    num_results=4,
-    description=(
-        "Search the internet for current information. "
-        "Use when the student asks about recent events, specific facts, "
-        "or anything not covered by the NCERT curriculum context. "
-        "Input: a concise search query string."
-    ),
-)
 
-
-def run_web_search(query: str) -> str:
+# ── Web Search (Tavily) ───────────────────────────────────────
+def run_web_search(
+    query: str,
+    api_key: str = "",
+    *,
+    search_depth: str = "advanced",
+    topic: str = "general",
+    max_results: int = 5,
+    include_answer: bool = True,
+) -> str:
     """
-    Run web search programmatically using DDGS.
+    Run a web search using the Tavily API.
+
+    `api_key` is the user's own Tavily key (BYOK). Falls back to the shared
+    server key if the user didn't provide one. If no key is available at all,
+    web search is treated as disabled.
+
+    Returns a formatted block: an optional LLM-ready answer followed by
+    result cards (title, URL, relevance score, content snippet).
     """
+    key = api_key or TAVILY_API_KEY
+    if not key:
+        return (
+            "Web search is unavailable: no Tavily API key configured. "
+            "Add a Tavily API key in Settings to enable web search."
+        )
+
     try:
-        with DDGS(timeout=10) as ddgs:
-            results = list(ddgs.text(query, max_results=4))
-            if not results:
-                return "No search results found."
-            
-            formatted = []
-            for r in results:
-                title = r.get("title", "No Title")
-                href = r.get("href", "")
-                body = r.get("body", "")
-                formatted.append(f"Title: {title}\nURL: {href}\nSnippet: {body}\n")
-            return "\n".join(formatted)
+        client = TavilyClient(api_key=key)
+        resp = client.search(
+            query,
+            search_depth=search_depth,
+            topic=topic,
+            max_results=max_results,
+            include_answer=include_answer,
+            include_raw_content=False,
+            chunks_per_source=3,
+        )
     except Exception as e:
-        print(f"[SEARCH DDGS ERROR] {e}. Trying LangChain fallback...", flush=True)
-        try:
-            return web_search.invoke(query)
-        except Exception as fallback_err:
-            return f"Web search is temporarily unavailable. (Error: {fallback_err})"
+        print(f"[TAVILY SEARCH ERROR] {e}", flush=True)
+        return f"Web search is temporarily unavailable. (Error: {e})"
+
+    results = resp.get("results", []) if isinstance(resp, dict) else []
+    if not results and not (isinstance(resp, dict) and resp.get("answer")):
+        return "No search results found."
+
+    blocks = []
+    answer = resp.get("answer") if isinstance(resp, dict) else None
+    if answer:
+        blocks.append(f"Answer: {answer}\n")
+
+    for r in results:
+        title = r.get("title", "No Title")
+        url = r.get("url", "")
+        score = r.get("score", "")
+        content = r.get("content", "")
+        score_str = f" (relevance: {score:.2f})" if isinstance(score, (int, float)) else ""
+        blocks.append(f"Title: {title}{score_str}\nURL: {url}\nSnippet: {content}\n")
+
+    return "\n".join(blocks)
+
+
+@tool
+def web_search(query: str) -> str:
+    """
+    Search the internet for current information. Use when the student asks
+    about recent events, specific facts, or anything not covered by the NCERT
+    curriculum context. Input: a concise search query string.
+    """
+    return run_web_search(query)
 
 
 # ── YouTube Transcript ────────────────────────────────────────