Polish: concept top-2 calibration, cross-cutting tag, uncertainty flag, overall depth bar

frontend/index.html

@@ -35,7 +35,7 @@
   }
   .mono { font-family: 'IBM Plex Mono', monospace; }
 
-  /* ---- header ---- */
+  /* Header */
   header {
     display: flex; align-items: baseline; justify-content: space-between;
     padding: 22px 32px 18px; color: var(--paper);
@@ -58,7 +58,7 @@
   }
   .reset:hover { color: var(--paper); border-color: rgba(237,234,226,.5); }
 
-  /* provider toggle */
+  /* Provider toggle */
   .provider-pick {
     display: flex; align-items: center; gap: 8px;
   }
@@ -75,7 +75,7 @@
   .seg-toggle button.active { background: var(--crit); color: #fff; }
   .seg-toggle button:not(.active):hover { color: var(--paper); }
 
-  /* ---- workspace ---- */
+  /* Workspace */
   .workspace {
     display: grid; grid-template-columns: minmax(300px, 38%) 1fr;
     gap: 22px; padding: 22px 32px 32px; height: calc(100vh - 73px);
@@ -99,7 +99,7 @@
   .panel-meta { font-family:'IBM Plex Mono',monospace; font-size: 11px; color: var(--ink-soft); }
   .panel-body { flex: 1; overflow-y: auto; padding: 20px; }
 
-  /* ---- left: setup ---- */
+  /* Left: setup */
   .dropzone {
     border: 1.5px dashed var(--rule-strong); border-radius: 3px;
     padding: 28px 18px; text-align: center; cursor: pointer; transition: .15s;
@@ -132,7 +132,19 @@
   .btn-block { width: 100%; margin-top: 14px; }
   .filename { font-size: 13px; color: var(--crit-ink); margin-top: 10px; font-weight: 500; }
 
-  /* ---- left: coverage map (signature) ---- */
+  /* Left: coverage map */
+  .overall { margin-bottom: 18px; }
+  .overall-head { display: flex; align-items: baseline; justify-content: space-between; margin-bottom: 7px; }
+  .overall-label { font-family:'IBM Plex Mono',monospace; font-size: 11px; text-transform: uppercase;
+    letter-spacing: .16em; color: var(--ink); }
+  .overall-count { font-family:'IBM Plex Mono',monospace; font-size: 11px; color: var(--ink-soft); }
+  .overall-track { height: 8px; background: var(--paper-inset); border: 1px solid var(--rule-strong);
+    border-radius: 3px; overflow: hidden; }
+  .overall-fill { height: 100%; width: 0%;
+    background: linear-gradient(90deg, var(--surface), var(--mech) 55%, var(--crit));
+    transition: width .5s ease; }
+  .overall-sub { font-size: 11px; color: var(--ink-soft); margin-top: 5px; }
+
   .legend { display: flex; gap: 14px; margin-bottom: 18px; }
   .legend span { display: flex; align-items: center; gap: 6px; font-size: 11px; color: var(--ink-soft);
     font-family:'IBM Plex Mono',monospace; letter-spacing: .04em; }
@@ -155,7 +167,7 @@
   .seg.pulse { animation: pulse .6s ease; }
   @keyframes pulse { 0%{transform:scaleY(1)} 40%{transform:scaleY(2.1)} 100%{transform:scaleY(1)} }
 
-  /* ---- right: dialogue ---- */
+  /* Right: dialogue */
   .dialogue { display: flex; flex-direction: column; height: 100%; min-height: 0; overflow: hidden; }
   .transcript { flex: 1; min-height: 0; overflow-y: auto; padding: 22px 22px 8px; }
   .empty {
@@ -203,7 +215,9 @@
   .badge.Surface { background: var(--surface); color: #1f3a47; }
   .badge.Mechanistic { background: var(--mech); }
   .badge.Critical { background: var(--crit); }
+  .badge.uncertain { background: var(--ink-soft); color: var(--paper); opacity: .8; }
   .concept-tag { color: var(--ink-soft); font-style: normal; }
+  .concept-tag.cross { font-style: italic; opacity: .85; }
 
   .thinking { font-style: italic; color: var(--ink-soft); font-size: 14px; }
   .dot-flash::after { content: "…"; animation: dots 1.2s steps(4,end) infinite; }
@@ -251,14 +265,14 @@
   </header>
 
   <div class="workspace">
-    <!-- LEFT -->
+    <!-- Left -->
     <section class="panel left">
       <div class="panel-head">
         <span class="panel-label" id="leftLabel">Material</span>
         <span class="panel-meta" id="leftMeta"></span>
       </div>
       <div class="panel-body" id="leftBody">
-        <!-- setup state -->
+        <!-- Setup state -->
         <div id="setup">
           <div class="dropzone" id="dropzone">
             <div class="big">Drop your lecture material</div>
@@ -272,8 +286,16 @@
           <div class="errline hidden" id="setupErr"></div>
         </div>
 
-        <!-- coverage state -->
+        <!-- Coverage state -->
         <div id="coverage" class="hidden">
+          <div class="overall">
+            <div class="overall-head">
+              <span class="overall-label">Overall depth</span>
+              <span class="overall-count" id="overallCount">0 / 0 depth points</span>
+            </div>
+            <div class="overall-track"><div class="overall-fill" id="overallFill"></div></div>
+            <div class="overall-sub">depth reached across all concepts and levels</div>
+          </div>
           <div class="legend">
             <span><i class="chip s"></i>Surface</span>
             <span><i class="chip m"></i>Mechanistic</span>
@@ -284,7 +306,7 @@
       </div>
     </section>
 
-    <!-- RIGHT -->
+    <!-- Right -->
     <section class="panel right">
       <div class="panel-head">
         <span class="panel-label">The interrogation</span>
@@ -314,7 +336,7 @@ let provider = "deepseek";
 
 const $ = (id) => document.getElementById(id);
 
-// ---- provider toggle ----
+// Provider toggle
 document.querySelectorAll("#providerToggle button").forEach((btn) => {
   btn.addEventListener("click", () => {
     document.querySelectorAll("#providerToggle button").forEach((b) =>
@@ -324,7 +346,7 @@ document.querySelectorAll("#providerToggle button").forEach((btn) => {
   });
 });
 
-// ---- material loading ----
+// Material loading
 $("dropzone").addEventListener("click", () => $("fileInput").click());
 $("fileInput").addEventListener("change", (e) => {
   selectedFile = e.target.files[0] || null;
@@ -379,7 +401,7 @@ function showSetupErr(msg) {
   $("setupErr").classList.remove("hidden");
 }
 
-// ---- enter interrogation ----
+// Enter interrogation
 function enterInterrogation(data) {
   setLoading(false);
   $("setup").classList.add("hidden");
@@ -408,6 +430,20 @@ function renderConcepts(concepts, coverage) {
     row.innerHTML = `<div class="concept-name">${c}</div><div class="depth">${segs}</div>`;
     list.appendChild(row);
   });
+  updateOverall(concepts, coverage);
+}
+
+// Overall depth = lit / total segments.
+function updateOverall(concepts, coverage) {
+  const total = concepts.length * LEVELS.length;
+  let lit = 0;
+  concepts.forEach((c) => {
+    const cov = coverage[c] || {};
+    LEVELS.forEach((lv) => { if (cov[lv] > 0) lit += 1; });
+  });
+  const pct = total > 0 ? Math.round((lit / total) * 100) : 0;
+  $("overallFill").style.width = pct + "%";
+  $("overallCount").textContent = `${lit} / ${total} depth points`;
 }
 
 function updateCoverage(coverage) {
@@ -420,9 +456,13 @@ function updateCoverage(coverage) {
       setTimeout(() => seg.classList.remove("pulse"), 600);
     }
   });
+  // Refresh overall depth.
+  const concepts = Array.from(document.querySelectorAll(".concept-name"))
+    .map((el) => el.textContent);
+  updateOverall(concepts, coverage);
 }
 
-// ---- asking ----
+// Asking
 $("askBtn").addEventListener("click", ask);
 $("qInput").addEventListener("keydown", (e) => {
   if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); ask(); }
@@ -471,15 +511,29 @@ function addStudentTurn(text) {
   lastStudentEl = el;
   scrollDown();
 }
+const UNCERTAIN_THRESHOLD = 0.55;
+
 function tagLastStudent(level, conf, concepts) {
   if (!lastStudentEl) return;
   const pct = Math.round(conf * 100);
-  let conceptBit = "";
+
+  // Show concepts or mark as cross-cutting.
+  let conceptBit;
   if (concepts && concepts.length > 0) {
     conceptBit = ` · <span class="concept-tag">${concepts.join(" + ")}</span>`;
+  } else {
+    conceptBit = ` · <span class="concept-tag cross">cross-cutting</span>`;
   }
-  lastStudentEl.querySelector(".who").innerHTML =
-    `<span class="badge ${level}">${level.toUpperCase()} ${pct}%</span>${conceptBit} You`;
+
+  // Mark low-confidence questions.
+  let badge;
+  if (conf < UNCERTAIN_THRESHOLD) {
+    badge = `<span class="badge uncertain">${level.toUpperCase()}? · uncertain</span>`;
+  } else {
+    badge = `<span class="badge ${level}">${level.toUpperCase()} ${pct}%</span>`;
+  }
+
+  lastStudentEl.querySelector(".who").innerHTML = `${badge}${conceptBit} You`;
 }
 function addThinking() {
   const el = document.createElement("div");
@@ -504,10 +558,10 @@ function addExpertTurn(text) {
   scrollDown();
 }
 
-// ---- reset ----
+// Reset
 $("resetBtn").addEventListener("click", () => location.reload());
 
-// auto-grow question box
+// Auto-grow question box
 $("qInput").addEventListener("input", function () {
   this.style.height = "44px";
   this.style.height = Math.min(this.scrollHeight, 120) + "px";

main.py

@@ -1,10 +1,4 @@
-"""FastAPI backend for Dialectica.
-
-Handles material upload, expert Q&A, question classification, and coverage map.
-
-Run locally:
-        PYTORCH_ENABLE_MPS_FALLBACK=1 uvicorn main:app
-"""
+"""FastAPI backend for Dialectica."""
 
 import os
 import time
@@ -26,13 +20,13 @@ app = FastAPI(title="Dialectica")
 
 VALID_PROVIDERS = ("deepseek", "gemini")
 
-# Abuse protection settings.
-DAILY_CALL_CAP = 200          # global expert-call cap per day
+# Basic limits.
+DAILY_CALL_CAP = 200          # expert-call cap per day
 PER_IP_PER_MINUTE = 6         # max requests per IP per minute
-MAX_QUESTION_CHARS = 2000     # limit very long questions
+MAX_QUESTION_CHARS = 2000     # max question length
 
 # In-memory rate-limit state.
-_ip_hits = defaultdict(deque)   # ip -> recent request timestamps
+_ip_hits = defaultdict(deque)   # ip -> recent timestamps
 _daily = {"day": None, "count": 0}
 
 SESSION = {
@@ -46,7 +40,7 @@ COMPONENTS = {"classifier": None, "matcher": None, "experts": {}}
 
 
 def get_classifier_and_matcher():
-    """Initialize classifier and matcher on first use."""
+    """Get classifier and matcher (lazy init)."""
     product_config = config.ProductConfig()
     if COMPONENTS["classifier"] is None:
         COMPONENTS["classifier"] = CognitiveClassifier(product_config)
@@ -56,7 +50,7 @@ def get_classifier_and_matcher():
 
 
 def get_expert(provider):
-    """Return cached expert for provider, creating it if needed."""
+    """Get cached expert for provider."""
     if provider not in VALID_PROVIDERS:
         provider = "deepseek"
     if provider not in COMPONENTS["experts"]:
@@ -72,12 +66,12 @@ def get_expert(provider):
 
 
 def _blank_coverage(concepts):
-    """Create empty coverage counts for each concept."""
+    """Make empty coverage map."""
     return {c: {level: 0 for level in ORDERED_LABELS} for c in concepts}
 
 
 def _check_rate_limit(request):
-    """Check per-IP per-minute limit."""
+    """Check per-IP rate limit."""
     client_ip = request.client.host if request.client else "unknown"
     now = time.time()
     hits = _ip_hits[client_ip]
@@ -90,7 +84,7 @@ def _check_rate_limit(request):
 
 
 def _check_daily_cap():
-    """Check global daily call cap."""
+    """Check daily usage cap."""
     today = time.strftime("%Y-%m-%d", time.gmtime())
     if _daily["day"] != today:
         _daily["day"] = today
@@ -102,7 +96,7 @@ def _check_daily_cap():
 
 
 class AskRequest(BaseModel):
-    """Body for the /api/ask endpoint."""
+    """Request body for /api/ask."""
 
     question: str
     provider: str = "deepseek"
@@ -110,7 +104,7 @@ class AskRequest(BaseModel):
 
 @app.get("/")
 def index():
-    """Serve the single-page frontend."""
+    """Serve frontend page."""
     return FileResponse(os.path.join("frontend", "index.html"))
 
 
@@ -121,7 +115,7 @@ async def upload(
     text: str = Form(None),
     provider: str = Form("deepseek"),
 ):
-    """Parse uploaded material or pasted text and extract concepts."""
+    """Load material and extract concepts."""
     rate_error = _check_rate_limit(request)
     if rate_error:
         return JSONResponse(status_code=429, content={"error": rate_error})
@@ -157,7 +151,7 @@ async def upload(
 
     concepts = expert.extract_concepts(material)
     matcher.set_concepts(concepts)
-    _daily["count"] += 1  # concept extraction uses one expert call
+    _daily["count"] += 1  # concept extraction counts as one call
 
     SESSION["material"] = material
     SESSION["concepts"] = concepts
@@ -170,7 +164,7 @@ async def upload(
 
 @app.post("/api/ask")
 def ask(request: Request, body: AskRequest):
-    """Classify the question, answer as the expert, and update coverage."""
+    """Answer one question and update coverage."""
     rate_error = _check_rate_limit(request)
     if rate_error:
         return JSONResponse(status_code=429, content={"error": rate_error})
@@ -201,7 +195,7 @@ def ask(request: Request, body: AskRequest):
 
     classification = classifier.classify(question)
     level = classification["level"]
-    concepts = matcher.match(question)  # list (can be empty)
+    concepts = matcher.match(question)  # may be empty
 
     answer_text = expert.answer(question, SESSION["material"], SESSION["history"])
     _daily["count"] += 1
@@ -225,5 +219,5 @@ def ask(request: Request, body: AskRequest):
 
 @app.get("/api/coverage")
 def coverage():
-    """Return the current coverage map and concept list."""
+    """Return current coverage state."""
     return {"concepts": SESSION["concepts"], "coverage": SESSION["coverage"]}

scripts/inference.py

@@ -1,16 +1,13 @@
-"""Inference utilities for Dialectica.
-
-Includes question-level classification and concept matching.
-"""
+"""Inference helpers for Dialectica."""
 
 ORDERED_LABELS = ["Surface", "Mechanistic", "Critical"]
 
 
 class CognitiveClassifier:
-    """Use DistilBERT to classify question cognitive level."""
+    """DistilBERT question classifier."""
 
     def __init__(self, product_config):
-        """Load classifier and tokenizer."""
+        """Load model and tokenizer."""
         import torch
         from transformers import (
             AutoModelForSequenceClassification,
@@ -24,13 +21,12 @@ class CognitiveClassifier:
             self.cfg.classifier_dir
         )
         self.model.eval()
-        # Use model labels if available; otherwise use default order.
         self.id2label = self.model.config.id2label or {
             i: label for i, label in enumerate(ORDERED_LABELS)
         }
 
     def classify(self, question):
-        """Return the predicted level and a confidence score for one question."""
+        """Predict level and confidence."""
         inputs = self.tokenizer(
             question,
             truncation=True,
@@ -48,10 +44,10 @@ class CognitiveClassifier:
 
 
 class ConceptMatcher:
-    """Match a question to nearest concepts by embedding similarity."""
+    """Embedding-based concept matcher."""
 
     def __init__(self, product_config):
-        """Load sentence embedding model."""
+        """Load embedding model."""
         from sentence_transformers import SentenceTransformer
 
         self.cfg = product_config
@@ -60,7 +56,7 @@ class ConceptMatcher:
         self.concept_embeddings = None
 
     def set_concepts(self, concepts):
-        """Store concepts and precompute embeddings."""
+        """Cache concept embeddings."""
         self.concepts = concepts
         if concepts:
             self.concept_embeddings = self.model.encode(
@@ -70,7 +66,7 @@ class ConceptMatcher:
             self.concept_embeddings = None
 
     def match(self, question):
-        """Return up to two matched concepts, or an empty list."""
+        """Return up to two matching concepts."""
         from sentence_transformers import util
 
         if not self.concepts or self.concept_embeddings is None:
@@ -84,7 +80,9 @@ class ConceptMatcher:
             reverse=True,
         )
         threshold = self.cfg.concept_match_threshold
-        runner_up_margin = 0.07  # allow a close second concept
+        # Keep a second concept if it's close to top or strong enough.
+        runner_up_margin = 0.05
+        runner_up_absolute = 0.45
 
         top_index = ranked[0]
         top_score = float(scores[top_index])
@@ -95,7 +93,8 @@ class ConceptMatcher:
         if len(ranked) > 1:
             second_index = ranked[1]
             second_score = float(scores[second_index])
-            if (second_score >= threshold
-                    and top_score - second_score <= runner_up_margin):
+            close_to_top = top_score - second_score <= runner_up_margin
+            strong_alone = second_score >= runner_up_absolute
+            if second_score >= threshold and (close_to_top or strong_alone):
                 matched.append(self.concepts[second_index])
         return matched