Update api/server.py

api/server.py

@@ -1,6 +1,7 @@
 # api/server.py
 import os
 import time
+import threading
 from typing import Dict, List, Optional, Any, Tuple
 
 from fastapi import FastAPI, UploadFile, File, Form, Request
@@ -22,7 +23,7 @@ from api.clare_core import (
     summarize_conversation,
 )
 
-# ✅ LangSmith
+# ✅ LangSmith (optional)
 try:
     from langsmith import Client
 except Exception:
@@ -45,6 +46,24 @@ LS_PROJECT = os.getenv("LANGSMITH_PROJECT", os.getenv("LANGCHAIN_PROJECT", "")).
 
 EXPERIMENT_ID = os.getenv("CLARE_EXPERIMENT_ID", "RESP_AI_W10").strip()
 
+# ----------------------------
+# Health / Warmup (cold start mitigation)
+# ----------------------------
+APP_START_TS = time.time()
+
+WARMUP_DONE = False
+WARMUP_ERROR: Optional[str] = None
+WARMUP_STARTED = False
+
+# warmup knobs
+CLARE_ENABLE_WARMUP = os.getenv("CLARE_ENABLE_WARMUP", "1").strip() == "1"
+CLARE_WARMUP_BLOCK_READY = os.getenv("CLARE_WARMUP_BLOCK_READY", "0").strip() == "1"
+
+# langsmith knobs (important for latency)
+CLARE_ENABLE_LANGSMITH_LOG = os.getenv("CLARE_ENABLE_LANGSMITH_LOG", "0").strip() == "1"
+# If true, logging is done in background thread to avoid blocking /api/chat
+CLARE_LANGSMITH_ASYNC = os.getenv("CLARE_LANGSMITH_ASYNC", "1").strip() == "1"
+
 # ----------------------------
 # App
 # ----------------------------
@@ -94,6 +113,7 @@ def _preload_module10_chunks() -> List[Dict[str, Any]]:
     return []
 
 
+# Preload at import time (fast path for requests)
 MODULE10_CHUNKS_CACHE = _preload_module10_chunks()
 
 
@@ -113,10 +133,51 @@ def _get_session(user_id: str) -> Dict[str, Any]:
 
 
 # ----------------------------
-# LangSmith helpers
+# Warmup (runs once, background)
+# ----------------------------
+def _do_warmup_once():
+    """
+    Warm OpenAI connection + touch module10 chunks cache.
+    Best-effort; should never crash the app.
+    """
+    global WARMUP_DONE, WARMUP_ERROR, WARMUP_STARTED
+    if WARMUP_STARTED:
+        return
+    WARMUP_STARTED = True
+
+    try:
+        # Warm OpenAI network / TLS / keep-alive
+        from api.config import client
+
+        # cheapest call: models.list() (no token usage)
+        client.models.list()
+
+        # Touch module10 cache (already loaded at import; this is just a safety)
+        _ = MODULE10_CHUNKS_CACHE
+
+        WARMUP_DONE = True
+        WARMUP_ERROR = None
+    except Exception as e:
+        WARMUP_DONE = False
+        WARMUP_ERROR = repr(e)
+
+
+def _start_warmup_background():
+    if not CLARE_ENABLE_WARMUP:
+        return
+    threading.Thread(target=_do_warmup_once, daemon=True).start()
+
+
+@app.on_event("startup")
+def _on_startup():
+    _start_warmup_background()
+
+
+# ----------------------------
+# LangSmith helpers (optional; default OFF)
 # ----------------------------
 _ls_client = None
-if Client is not None:
+if (Client is not None) and CLARE_ENABLE_LANGSMITH_LOG:
     try:
         _ls_client = Client()
     except Exception as e:
@@ -127,29 +188,69 @@ if Client is not None:
 def _log_event_to_langsmith(data: Dict[str, Any]):
     """
     Create an Example in LangSmith Dataset.
+    Best-effort and non-blocking by default (async thread).
     """
     if _ls_client is None:
         return
-    try:
-        inputs = {
-            "question": data.get("question", ""),
-            "student_id": data.get("student_id", ""),
-            "student_name": data.get("student_name", ""),
-        }
-        outputs = {"answer": data.get("answer", "")}
-        metadata = {k: v for k, v in data.items() if k not in ("question", "answer")}
 
-        if LS_PROJECT:
-            metadata.setdefault("langsmith_project", LS_PROJECT)
+    def _do():
+        try:
+            inputs = {
+                "question": data.get("question", ""),
+                "student_id": data.get("student_id", ""),
+                "student_name": data.get("student_name", ""),
+            }
+            outputs = {"answer": data.get("answer", "")}
+            metadata = {k: v for k, v in data.items() if k not in ("question", "answer")}
+
+            if LS_PROJECT:
+                metadata.setdefault("langsmith_project", LS_PROJECT)
+
+            _ls_client.create_example(
+                inputs=inputs,
+                outputs=outputs,
+                metadata=metadata,
+                dataset_name=LS_DATASET_NAME,
+            )
+        except Exception as e:
+            print("[langsmith] log failed:", repr(e))
 
-        _ls_client.create_example(
-            inputs=inputs,
-            outputs=outputs,
-            metadata=metadata,
-            dataset_name=LS_DATASET_NAME,
-        )
-    except Exception as e:
-        print("[langsmith] log failed:", repr(e))
+    if CLARE_LANGSMITH_ASYNC:
+        threading.Thread(target=_do, daemon=True).start()
+    else:
+        _do()
+
+
+# ----------------------------
+# Health endpoints (pure lightweight)
+# ----------------------------
+@app.get("/health")
+def health():
+    # do not touch LLM/RAG/disk heavy work here
+    return {
+        "ok": True,
+        "uptime_s": round(time.time() - APP_START_TS, 3),
+        "warmup_enabled": CLARE_ENABLE_WARMUP,
+        "warmup_started": bool(WARMUP_STARTED),
+        "warmup_done": bool(WARMUP_DONE),
+        "warmup_error": WARMUP_ERROR,
+        "ready": bool(WARMUP_DONE) if CLARE_WARMUP_BLOCK_READY else True,
+        "langsmith_enabled": bool(CLARE_ENABLE_LANGSMITH_LOG),
+        "langsmith_async": bool(CLARE_LANGSMITH_ASYNC),
+        "ts": int(time.time()),
+    }
+
+
+@app.get("/ready")
+def ready():
+    # readiness probe: optionally block until warmup completes
+    if not CLARE_ENABLE_WARMUP or not CLARE_WARMUP_BLOCK_READY:
+        return {"ready": True}
+
+    if WARMUP_DONE:
+        return {"ready": True}
+
+    return JSONResponse({"ready": False, "error": WARMUP_ERROR}, status_code=503)
 
 
 # ----------------------------
@@ -247,8 +348,12 @@ def chat(req: ChatReq):
     sess["cognitive_state"] = update_cognitive_state_from_message(msg, sess["cognitive_state"])
     marks_ms["cognitive_update_done"] = (time.time() - t0) * 1000.0
 
-    # rag retrieve
-    rag_context_text, rag_used_chunks = retrieve_relevant_chunks(msg, sess["rag_chunks"])
+    # rag retrieve (optional micro-gate for very short messages)
+    if len(msg) < 20 and ("?" not in msg):
+        rag_context_text, rag_used_chunks = "", []
+    else:
+        rag_context_text, rag_used_chunks = retrieve_relevant_chunks(msg, sess["rag_chunks"])
+
     marks_ms["rag_retrieve_done"] = (time.time() - t0) * 1000.0
 
     # llm
@@ -273,7 +378,14 @@ def chat(req: ChatReq):
     total_ms = marks_ms["llm_done"]
 
     # segments (delta)
-    ordered = ["start", "language_detect_done", "weakness_update_done", "cognitive_update_done", "rag_retrieve_done", "llm_done"]
+    ordered = [
+        "start",
+        "language_detect_done",
+        "weakness_update_done",
+        "cognitive_update_done",
+        "rag_retrieve_done",
+        "llm_done",
+    ]
     segments_ms: Dict[str, float] = {}
     for i in range(1, len(ordered)):
         a = ordered[i - 1]
@@ -294,7 +406,7 @@ def chat(req: ChatReq):
     rag_used_chunks_count = len(rag_used_chunks or [])
     history_len = len(sess["history"])
 
-    # ✅ log chat_turn to LangSmith
+    # ✅ log chat_turn to LangSmith (optional; async by default)
     _log_event_to_langsmith(
         {
             "experiment_id": EXPERIMENT_ID,