initial commit - InterviewCopilotLocal

.gitignore

@@ -0,0 +1,77 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Local environment and secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+
+# App runtime data
+.runtime/
+interviews.db
+*.db
+*.sqlite
+*.sqlite3
+live_audi_transcript.md
+*.csv
+
+# Model and training artifacts
+models/
+checkpoints/
+outputs/
+runs/
+wandb/
+mlruns/
+*.safetensors
+*.bin
+*.pt
+*.pth
+*.ckpt
+*.gguf
+
+# Hugging Face / ML caches
+.cache/
+huggingface/
+hf_cache/
+
+# Gradio
+flagged/
+.gradio/
+
+# Logs
+*.log
+logs/
+
+# OS and editor files
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Test and coverage artifacts
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

AGENTS.md

@@ -0,0 +1,112 @@
+# InterviewCoach — Project Brief
+> Silent real-time coaching during interviews. Runs 100% local on your Mac.
+
+---
+
+## What It Does
+
+When user is in an interview, the app listens to the interviewer's question via mic → transcribes it → classifies the question type → displays a compact coaching card with the framework to follow. You glance at it, then answer. No cloud. No latency. No trace.
+
+APp will add if the question is asked by interviewer or candidate and also tags if answer is answered by the candidate or interviewer. If there is a low cofidence, flags for user updates later.
+
+As a second part, there is another agent who goes through the transcripts and rates the interview by adding critical feedbacks highlighting areas for improvements.
+
+---
+## Architecture
+LangGraph agentic pipeline. Each node is a discrete async function. State flows through the graph.
+ 
+```
+AudioNode → TranscriptNode → ClassifierAgent → FrameworkNode → UINode
+                                                      ↓
+                                              EvaluationAgent (post-session)
+```
+ 
+---
+ 
+## Stack
+- **Framework**: LangGraph + LangChain
+- **LLM**: Qwen2.5 7B Instruct via Ollama (Part 1) / fine-tuned Qwen2.5 3B via llama.cpp (Part 2)
+- **STT**: mlx-whisper (whisper-small-mlx)
+- **UI**: Gradio with custom dark-mode CSS
+- **Database**: SQLite (via `aiosqlite` for async)
+- **Runtime**: Python 3.11+, Apple Silicon M1 Pro
+---
+ 
+## Coding Rules
+- All nodes and DB calls must be `async`/`await` — no blocking I/O on the main thread
+- Use `aiosqlite` for all database operations
+- Use `asyncio.Queue` for audio chunk passing between nodes
+- LangGraph state must be a typed `TypedDict`
+- Each agent/node lives in its own file under `agents/`
+---
+ 
+## Agents
+ 
+### ClassifierAgent
+- Input: transcribed question string
+- Output: `{type: str, steps: list[str]}`
+- Uses Qwen2.5 7B Instruct with structured output prompt
+- Must return valid framework type — fallback to "General" if uncertain
+### EvaluationAgent
+- Input: `{question: str, answer: str, framework: str, steps: list[str]}`
+- Output: `{steps_covered: list[bool], score: int, feedback: str}`
+- Runs post-session, not real-time
+- One evaluation card per Q&A exchange
+---
+ 
+## Database (SQLite)
+File: `interviews.db`
+ 
+```sql
+sessions    (id, date, company, role, duration)
+exchanges   (id, session_id, question, answer, framework_used, timestamp)
+evaluations (id, exchange_id, steps_covered_json, score, feedback)
+transcripts (id, session_id, raw_text, labelled_json)
+patterns    (framework, times_shown, avg_score, most_missed_step)
+```
+ 
+- All DB access via `aiosqlite`
+- Init schema on app startup if tables don't exist
+- Never block the event loop with synchronous sqlite3 calls
+---
+ 
+## Gradio UI
+- Dark mode custom CSS — no default Gradio theme
+- Three tabs: **Live** (coaching cards) · **Session Log** (transcript) · **Evaluate** (post-interview report)
+- Coaching cards: colour-coded by framework type, step-by-step list
+- Use `gr.Blocks` not `gr.Interface`
+- UI updates via async generator / `queue=True`
+---
+ 
+## File Structure
+```
+interview-coach/
+├── AGENTS.md
+├── app.py                  # Gradio entry point
+├── graph.py                # LangGraph pipeline definition
+├── state.py                # TypedDict state schema
+├── agents/
+│   ├── classifier.py       # ClassifierAgent
+│   └── evaluator.py        # EvaluationAgent
+├── nodes/
+│   ├── audio.py            # Whisper capture node
+│   ├── transcript.py       # Speaker labelling node
+│   └── framework.py        # Framework lookup node
+├── db/
+│   ├── schema.py           # Table definitions + init
+│   └── queries.py          # Async CRUD functions
+├── frameworks.yaml          # Question types + steps
+├── prompts.py              # All LLM prompt templates
+├── data/
+│   └── train.jsonl         # Fine-tuning dataset
+└── requirements.txt
+```
+ 
+---
+ 
+## Models
+- Part 1: `ollama pull qwen2.5:7b`
+- Part 2: fine-tuned Qwen2.5 3B via `mlx-lm` LoRA, exported to GGUF for llama.cpp
+- Swap model in one place only: `config.py` → `MODEL_PATH`
+---
+

README.md

@@ -0,0 +1,57 @@
+---
+title: InterviewCoach
+colorFrom: teal
+colorTo: slate
+sdk: gradio
+sdk_version: 6.16.0
+app_file: app.py
+pinned: false
+---
+
+# Interview Coach
+
+Interview Coach is a local-first assistant for live technical interviews. It listens to noisy interview audio, extracts the actual Data Science, ML, AI, or System Design question, and shows a compact coaching card with important pointers while the candidate is answering.
+
+## Why It Matters
+
+The goal is not to handhold the candidate through the interview or generate a scripted answer. The goal is to give timely, high-signal reminders so the candidate can cover the important parts of their own answer naturally.
+
+Interview conversations are messy: greetings, interviewer transitions, repeated words, partial transcription, candidate clarifications, and answer fragments often appear in the same transcript. Interview Coach helps by:
+
+- Capturing the core technical question from noisy live conversation.
+- Showing concise pointers that help the candidate cover the expected areas.
+- Separating interviewer questions from candidate answers after the session.
+- Evaluating saved Q&A exchanges with critical feedback and improvement areas.
+
+## Multi-Model Approach
+
+The app uses different local models for different jobs instead of asking one model to do everything:
+
+- Speech-to-text: Whisper via `mlx-whisper` for local audio transcription.
+- Topic and pattern detection: fine-tuned `vadirajkrishna/interview-coach-3b` to identify the interview question type and coarse pattern.
+- Coaching hints: `Qwen/Qwen2.5-3B-Instruct` generates short, question-specific pointers for the live coaching card.
+- Transcript cleanup and Q&A extraction: the general LLM extracts structured questions and candidate answers from noisy transcripts.
+- Evaluation: the evaluator uses the saved candidate answer, not the coaching hints, to provide a benchmark answer, hiring band, strengths, weaknesses, and critical gaps.
+
+This keeps the live coaching path fast while allowing more careful reasoning for post-session extraction and evaluation.
+
+## Agentic Architecture
+
+The app follows a LangGraph-style pipeline where each step has a focused responsibility:
+
+```text
+Audio Capture -> Transcription -> Question Extraction -> Topic/Pattern Agent
+              -> Coaching Card UI
+
+Saved Transcript -> Q&A Extraction -> SQLite Persistence -> Evaluation Agent
+```
+
+At runtime, the live path prioritizes speed: it listens to system audio, updates the transcript, extracts the latest likely technical question, classifies the question type, and renders a coaching card. After the session, the slower processing path extracts all Q&A exchanges from the full transcript and stores them in SQLite for evaluation and CSV export.
+
+## Running Locally
+
+Local-first interview coaching app with a Hugging Face Space demo mode.
+
+On Hugging Face Spaces, the app uses browser microphone recording and a
+Linux-compatible Transformers Whisper backend. Local-only system audio capture
+via BlackHole and Ollama-based LLM calls are not available in Space mode.

agents/__init__.py

@@ -0,0 +1 @@
+

agents/evaluator.py

@@ -0,0 +1,451 @@
+import json
+import re
+from typing import Any
+
+from config import EVALUATION_MODEL_PATH
+from agents.hf_chat import HuggingFaceChatModel
+from prompts import EVALUATOR_SYSTEM_PROMPT, EVALUATOR_USER_PROMPT
+
+
+class EvaluationAgent:
+    def __init__(self, model: str = EVALUATION_MODEL_PATH):
+        self.model = model
+        self.llm = HuggingFaceChatModel(model)
+
+    async def evaluate(
+        self,
+        question: str,
+        answer: str,
+        framework: str,
+        steps: list[str],
+    ) -> dict[str, Any]:
+        result = await self._try_model(question, answer, framework, steps)
+        if not result or self._model_result_looks_invalid(result, answer):
+            result = self._heuristic(question, answer, framework, steps)
+
+        steps_covered = result.get("steps_covered", [False] * len(steps))
+        band = self._normalize_band(result.get("band"))
+        score = self._band_to_score(band)
+        result["band"] = band
+        feedback = self._format_feedback(result)
+        return {
+            "steps_covered": [bool(item) for item in steps_covered[: len(steps)]],
+            "score": score,
+            "feedback": feedback,
+        }
+
+    async def _try_model(
+        self,
+        question: str,
+        answer: str,
+        framework: str,
+        steps: list[str],
+    ) -> dict[str, Any] | None:
+        prompt = EVALUATOR_USER_PROMPT.format(
+            question=question,
+            answer=answer,
+            framework=framework,
+            steps="\n".join(f"- {step}" for step in steps),
+        )
+        response = await self.llm.generate(
+            EVALUATOR_SYSTEM_PROMPT,
+            prompt,
+            max_new_tokens=768,
+        )
+        if not response:
+            return None
+        try:
+            return json.loads(self._extract_json(response))
+        except Exception:
+            return None
+
+    def _model_result_looks_invalid(self, result: dict[str, Any], answer: str) -> bool:
+        answer = answer.strip()
+        if not answer:
+            return self._normalize_band(result.get("band")) != "No hire"
+
+        feedback_text = " ".join(
+            str(result.get(key, ""))
+            for key in ("strong_points", "weak_points", "critical_gaps")
+        ).lower()
+        benchmark = str(result.get("benchmark_answer", "")).lower()
+
+        generic_phrases = (
+            "should clarify",
+            "should include",
+            "should explain",
+            "strong answer should",
+            "benchmark answer",
+            "perfect answer",
+        )
+        if any(phrase in feedback_text for phrase in generic_phrases):
+            return True
+
+        if benchmark and feedback_text and self._text_similarity(feedback_text, benchmark) > 0.55:
+            return True
+
+        strong_points = result.get("strong_points", [])
+        if isinstance(strong_points, list) and strong_points and answer:
+            answer_words = {
+                word
+                for word in re.findall(r"[a-zA-Z]+", answer.lower())
+                if len(word) > 3
+            }
+            strong_words = {
+                word
+                for item in strong_points
+                for word in re.findall(r"[a-zA-Z]+", str(item).lower())
+                if len(word) > 3
+            }
+            if strong_words and len(answer_words.intersection(strong_words)) == 0:
+                return True
+
+        return False
+
+    def _text_similarity(self, left: str, right: str) -> float:
+        left_words = {
+            word
+            for word in re.findall(r"[a-zA-Z]+", left.lower())
+            if len(word) > 3
+        }
+        right_words = {
+            word
+            for word in re.findall(r"[a-zA-Z]+", right.lower())
+            if len(word) > 3
+        }
+        if not left_words or not right_words:
+            return 0.0
+        return len(left_words.intersection(right_words)) / len(left_words.union(right_words))
+
+    def _heuristic(self, question: str, answer: str, framework: str, steps: list[str]) -> dict[str, Any]:
+        benchmark = self._benchmark_answer(question, framework)
+        if not answer.strip():
+            return {
+                "benchmark_answer": benchmark,
+                "steps_covered": [False] * len(steps),
+                "band": "No hire",
+                "strong_points": ["Nil"],
+                "weak_points": ["Candidate did not give any answer."],
+                "critical_gaps": ["No candidate answer was captured, so structured thinking could not be assessed."],
+            }
+
+        answer_words = set(re.findall(r"[a-zA-Z]+", answer.lower()))
+        covered = []
+        for step in steps:
+            step_words = set(re.findall(r"[a-zA-Z]+", step.lower()))
+            covered.append(bool(answer_words.intersection(step_words)))
+
+        assessment = self._assess_structured_thinking(answer, covered, framework)
+
+        return {
+            "benchmark_answer": benchmark,
+            "steps_covered": covered,
+            "band": assessment["band"],
+            "strong_points": assessment["strong_points"],
+            "weak_points": assessment["weak_points"],
+            "critical_gaps": assessment["critical_gaps"],
+        }
+
+    def _assess_structured_thinking(
+        self,
+        answer: str,
+        covered: list[bool],
+        framework: str,
+    ) -> dict[str, Any]:
+        text = answer.lower()
+        structure_signals = [
+            bool(re.search(r"\b(first|second|third|next|then|finally|step|approach)\b", text)),
+            bool(re.search(r"\b(assume|requirement|constraint|clarify)\b", text)),
+            bool(re.search(r"\b(tradeoff|however|but|risk|limitation)\b", text)),
+            bool(re.search(r"\b(metric|evaluate|validate|test|monitor)\b", text)),
+            bool(re.search(r"\b(example|for instance|such as)\b", text)),
+        ]
+        covered_count = sum(covered)
+        structure_count = sum(structure_signals)
+        word_count = len(answer.split())
+
+        if covered_count >= 4 and structure_count >= 3 and word_count >= 80:
+            band = "Strong hire"
+        elif covered_count >= 3 or (structure_count >= 3 and word_count >= 60):
+            band = "Hire"
+        elif covered_count >= 1 or structure_count >= 1 or word_count >= 25:
+            band = "Borderline"
+        else:
+            band = "No hire"
+
+        strong_points = []
+        if covered_count >= 3:
+            strong_points.append("Covered most of the expected framework areas.")
+        elif covered_count > 0:
+            strong_points.append("Covered at least part of the expected framework.")
+        if structure_count >= 2:
+            strong_points.append("Showed some structured thinking instead of only giving isolated facts.")
+        if word_count >= 60:
+            strong_points.append("Provided enough detail to understand the direction of the answer.")
+
+        weak_points = []
+        if covered_count < 3:
+            weak_points.append("Did not clearly cover enough key areas for a confident pass.")
+        if structure_count < 2:
+            weak_points.append("The reasoning process was not explicit enough.")
+        if word_count < 40:
+            weak_points.append("The answer was brief, so the interviewer has limited evidence of depth.")
+
+        critical_gaps = []
+        if framework == "System Design" and not re.search(r"\b(requirement|constraint|scale|latency|tradeoff|failure)\b", text):
+            critical_gaps.append("For system design, the answer needs clearer requirements, constraints, scale, and tradeoff reasoning.")
+        if framework == "Technical" and not re.search(r"\b(example|metric|evaluate|tradeoff|assumption|why)\b", text):
+            critical_gaps.append("For a technical answer, the candidate should explain why the concept works and give an example or validation angle.")
+        if not critical_gaps:
+            critical_gaps.append("Nil")
+
+        return {
+            "band": band,
+            "strong_points": strong_points or ["Nil"],
+            "weak_points": weak_points or ["Nil"],
+            "critical_gaps": critical_gaps,
+        }
+
+    def _compare_to_benchmark(self, answer: str, benchmark: str) -> dict[str, Any]:
+        concepts = self._benchmark_concepts(benchmark)
+        answer_text = answer.lower()
+        matched = [concept for concept in concepts if self._concept_is_covered(concept, answer_text)]
+        missed = [concept for concept in concepts if concept not in matched]
+
+        coverage = len(matched) / max(1, len(concepts))
+        score = max(1, min(5, round(coverage * 5)))
+        if len(answer.split()) < 30 and score > 2:
+            score = 2
+
+        strong_points = [f"Covered {concept}." for concept in matched[:4]] or ["Nil"]
+        weak_points = [f"Did not clearly explain {concept}." for concept in missed[:4]] or ["Nil"]
+        critical_gaps = [f"Missing benchmark concept: {concept}." for concept in missed[:5]] or ["Nil"]
+
+        if len(answer.split()) < 30:
+            weak_points.append("The answer is too brief to demonstrate the reasoning expected by the benchmark.")
+        return {
+            "score": score,
+            "strong_points": strong_points,
+            "weak_points": weak_points,
+            "critical_gaps": critical_gaps,
+        }
+
+    def _benchmark_concepts(self, benchmark: str) -> list[str]:
+        sentences = re.split(r"(?<=[.!?])\s+", benchmark)
+        concepts = []
+        for sentence in sentences:
+            clean = sentence.strip()
+            if not clean:
+                continue
+            if ":" in clean and len(clean.split(":")[0].split()) <= 5:
+                label, detail = clean.split(":", 1)
+                clean = f"{label.strip()} ({detail.strip()})"
+            concepts.append(clean.rstrip("."))
+        return concepts[:10]
+
+    def _concept_is_covered(self, concept: str, answer_text: str) -> bool:
+        concept_words = {
+            word
+            for word in re.findall(r"[a-zA-Z]+", concept.lower())
+            if len(word) > 3 and word not in self._stopwords()
+        }
+        if not concept_words:
+            return False
+        answer_words = set(re.findall(r"[a-zA-Z]+", answer_text))
+        overlap = concept_words.intersection(answer_words)
+        required = 1 if len(concept_words) <= 3 else max(2, min(4, len(concept_words) // 3))
+        return len(overlap) >= required
+
+    def _stopwords(self) -> set[str]:
+        return {
+            "correct",
+            "answer",
+            "should",
+            "include",
+            "explain",
+            "mention",
+            "strong",
+            "typical",
+            "common",
+            "uses",
+            "such",
+            "that",
+            "with",
+            "from",
+            "into",
+            "where",
+            "when",
+            "while",
+            "also",
+            "mainly",
+            "useful",
+        }
+
+    def _benchmark_answer(self, question: str, framework: str) -> str:
+        text = question.lower()
+        if "supervised" in text and "unsupervised" in text:
+            return (
+                "A correct answer should explain that supervised learning uses labeled training data, where each example has input features "
+                "and a known target label or value. The model learns a mapping from inputs to outputs and is evaluated against ground truth. "
+                "Typical supervised tasks include classification, such as spam detection or churn prediction, and regression, such as predicting "
+                "house prices. Common algorithms include linear regression, logistic regression, decision trees, random forests, gradient boosting, "
+                "support vector machines, and neural networks. Unsupervised learning uses unlabeled data and tries to discover structure, patterns, "
+                "or representations without a target label. Typical tasks include clustering, dimensionality reduction, anomaly detection, and "
+                "association discovery. Common algorithms include k-means, hierarchical clustering, DBSCAN, PCA, t-SNE or UMAP for visualization, "
+                "autoencoders, and Gaussian mixture models. A strong answer should also mention evaluation differences: supervised models can use "
+                "metrics like accuracy, precision, recall, F1, RMSE, or MAE, while unsupervised models are harder to evaluate and may use silhouette "
+                "score, reconstruction error, downstream task performance, or human/business validation."
+            )
+
+        if "linear regression" in text and "assumption" in text:
+            return (
+                "A correct answer should state the main assumptions of linear regression: "
+                "1. Linearity: the expected target is a linear combination of the predictors. "
+                "2. Independence: observations and residual errors are independent, with no autocorrelation. "
+                "3. Homoscedasticity: residuals have constant variance across predicted values. "
+                "4. No perfect multicollinearity: predictors are not exact linear combinations of each other. "
+                "5. Exogeneity: errors have mean zero and are not correlated with the predictors. "
+                "6. Normality of residuals is mainly needed for small-sample hypothesis tests and confidence intervals, "
+                "not for unbiased coefficient estimates. A strong answer should also mention checking residual plots, "
+                "variance inflation factor for multicollinearity, and transformations or robust standard errors when assumptions fail."
+            )
+
+        if "logistic regression" in text and "assumption" in text:
+            return (
+                "A correct answer should explain that logistic regression assumes independent observations, "
+                "a linear relationship between predictors and the log-odds of the target, no severe multicollinearity, "
+                "adequate sample size, correctly specified features and interactions, and limited influence from extreme outliers. "
+                "It should also mention that the target is binary or modeled as binomial, and that calibration, ROC-AUC, precision, recall, "
+                "and confusion-matrix tradeoffs are useful evaluation checks."
+            )
+
+        if "recommendation" in text or "recommender" in text:
+            return (
+                "A strong benchmark answer should clarify users, items, goals, constraints, and success metrics such as CTR, conversion, "
+                "retention, NDCG, recall@K, and diversity. It should propose candidate generation using collaborative filtering, "
+                "content-based retrieval, or embeddings; ranking using a learned model with user, item, and context features; "
+                "and feedback loops from clicks, ratings, purchases, skips, and dwell time. It should cover cold start, popularity bias, "
+                "exploration versus exploitation, freshness, latency, offline and online evaluation, A/B testing, monitoring drift, "
+                "and abuse or privacy concerns."
+            )
+
+        if "overfitting" in text or "underfitting" in text:
+            return (
+                "A correct answer should define overfitting as low training error but poor generalization, and underfitting as poor performance "
+                "on both train and validation data. It should mention causes such as excessive model complexity, noisy features, data leakage, "
+                "or insufficient regularization for overfitting, and overly simple models or insufficient features for underfitting. "
+                "It should include fixes such as cross-validation, regularization, more data, feature selection, early stopping, pruning, "
+                "simpler or richer models as appropriate, and monitoring train-validation learning curves."
+            )
+
+        if "bias" in text and "variance" in text:
+            return (
+                "A correct answer should explain bias as error from overly restrictive assumptions and variance as sensitivity to training data. "
+                "High bias causes underfitting; high variance causes overfitting. The answer should discuss the tradeoff, how model complexity "
+                "affects each side, and practical diagnosis using train and validation errors. It should mention remedies such as adding features "
+                "or model capacity for high bias, and regularization, more data, ensembling, or simpler models for high variance."
+            )
+
+        if ("rate limit" in text or "rate limiting" in text) and (
+            "token" in text or "consumption" in text or "aggregate" in text or "aggregates" in text
+        ):
+            return (
+                "A strong benchmark answer should design a low-latency token usage metering and rate-limiting service. "
+                "First clarify requirements: limit by user, API key, organization, model, endpoint, or time window; support per-minute, "
+                "daily, and monthly quotas; handle burst limits; provide accurate enough enforcement with very low request-path latency; "
+                "and expose usage dashboards and audit logs. The request path should call a Rate Limit service before or during inference. "
+                "That service should use Redis or another fast distributed counter store for hot-window counters, commonly with token bucket, "
+                "leaky bucket, or sliding-window counters keyed by tenant and model. Estimated input tokens can be checked before admission, "
+                "then final actual input plus output tokens should be committed after completion. For streaming responses, token usage can be "
+                "reserved up front, incrementally updated, or reconciled at stream end. The system should write durable usage events to Kafka, "
+                "Kinesis, or a log table, then aggregate asynchronously into OLAP/storage such as ClickHouse, BigQuery, or partitioned Postgres "
+                "tables for reporting. The design should cover idempotency with request IDs, atomic counter updates, TTLs for window counters, "
+                "clock/window boundary handling, refunds for failed requests, backpressure behavior, multi-region consistency tradeoffs, "
+                "eventual reconciliation between Redis and durable aggregates, and observability metrics such as allowed/blocked requests, "
+                "counter latency, aggregation lag, dropped events, and quota accuracy."
+            )
+
+        if framework == "System Design":
+            return (
+                "A strong answer should clarify functional and non-functional requirements, define APIs and data entities, propose a high-level "
+                "architecture, explain storage and serving choices, discuss scaling, caching, reliability, observability, latency, throughput, "
+                "and failure modes, then close with tradeoffs and validation metrics."
+            )
+
+        if framework == "Technical":
+            return (
+                "A strong technical answer should define the concept accurately, state assumptions, explain the mechanism or formula where relevant, "
+                "give practical examples, discuss edge cases and tradeoffs, and mention how to validate the approach in production or experiments."
+            )
+
+        return (
+            "A strong answer should directly answer the question, define key terms, provide a structured explanation, include concrete examples, "
+            "discuss tradeoffs or limitations, and close with how the answer would be validated or applied in practice."
+        )
+
+    def _normalize_score(self, value: Any) -> int:
+        try:
+            score = int(float(value))
+        except (TypeError, ValueError):
+            score = 3
+        return max(0, min(5, score))
+
+    def _normalize_band(self, value: Any) -> str:
+        text = str(value or "").strip().lower()
+        labels = {
+            "strong hire": "Strong hire",
+            "hire": "Hire",
+            "borderline": "Borderline",
+            "no hire": "No hire",
+        }
+        if text in labels:
+            return labels[text]
+
+        score = self._normalize_score(value)
+        if score >= 5:
+            return "Strong hire"
+        if score >= 4:
+            return "Hire"
+        if score >= 2:
+            return "Borderline"
+        return "No hire"
+
+    def _band_to_score(self, band: str) -> int:
+        return {
+            "Strong hire": 5,
+            "Hire": 4,
+            "Borderline": 2,
+            "No hire": 0,
+        }.get(band, 2)
+
+    def _format_feedback(self, result: dict[str, Any]) -> str:
+        benchmark = str(
+            result.get("benchmark_answer")
+            or result.get("baseline_answer")
+            or "No benchmark answer was generated."
+        ).strip()
+        band = self._normalize_band(result.get("band") or result.get("score", 2))
+        strong_points = self._format_list(result.get("strong_points") or result.get("strengths") or ["Nil"])
+        weak_points = self._format_list(result.get("weak_points") or ["Nil"])
+        critical_gaps = self._format_list(
+            result.get("critical_gaps")
+            or result.get("gaps")
+            or result.get("improvements")
+            or ["Nil"]
+        )
+        return (
+            f"Agent benchmark answer:\n{benchmark}\n\n"
+            f"Evaluation band: {band}\n\n"
+            f"Strong points:\n{strong_points}\n\n"
+            f"Weak points:\n{weak_points}\n\n"
+            f"Critical gaps:\n{critical_gaps}"
+        )
+
+    def _format_list(self, value: Any) -> str:
+        if not isinstance(value, list):
+            return str(value).strip()
+        return "\n".join(f"- {item}" for item in value if str(item).strip())
+
+    def _extract_json(self, text: str) -> str:
+        match = re.search(r"\{.*\}", text, flags=re.DOTALL)
+        return match.group(0) if match else text

agents/hf_chat.py

@@ -0,0 +1,114 @@
+import asyncio
+import threading
+import traceback
+from typing import Any
+
+from config import GENERAL_LLM_MODEL
+
+
+class HuggingFaceChatModel:
+    """Lazy local Hugging Face chat model for non-topic reasoning tasks."""
+
+    def __init__(self, model_name: str = GENERAL_LLM_MODEL):
+        self.model_name = model_name
+        self._model: Any | None = None
+        self._tokenizer: Any | None = None
+        self._load_lock = threading.Lock()
+        self.last_error = ""
+
+    async def generate(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        max_new_tokens: int = 512,
+    ) -> str:
+        try:
+            return await asyncio.to_thread(
+                self._generate_sync,
+                system_prompt,
+                user_prompt,
+                max_new_tokens,
+            )
+        except Exception as exc:
+            self.last_error = str(exc)
+            return ""
+
+    def _generate_sync(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        max_new_tokens: int,
+    ) -> str:
+        self.last_error = ""
+        self._ensure_model_loaded_sync()
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+        try:
+            encoded = self._tokenizer.apply_chat_template(
+                messages,
+                add_generation_prompt=True,
+                return_tensors="pt",
+                return_dict=True,
+            )
+            encoded = {key: value.to(self._model.device) for key, value in encoded.items()}
+        except Exception as exc:
+            raise RuntimeError(f"chat template failed for {self.model_name}: {exc}") from exc
+
+        import torch
+
+        try:
+            with torch.no_grad():
+                outputs = self._model.generate(
+                    **encoded,
+                    max_new_tokens=max_new_tokens,
+                    do_sample=False,
+                    pad_token_id=self._tokenizer.eos_token_id,
+                )
+        except Exception as exc:
+            detail = "".join(traceback.format_exception_only(type(exc), exc)).strip()
+            raise RuntimeError(
+                f"generation failed for {self.model_name}: {detail}. "
+                "This can happen if the model exceeds available memory or the Transformers input format changed."
+            ) from exc
+
+        input_length = encoded["input_ids"].shape[-1]
+        generated = outputs[0][input_length:]
+        return self._tokenizer.decode(generated, skip_special_tokens=True).strip()
+
+    def _ensure_model_loaded_sync(self) -> None:
+        if self._model is not None and self._tokenizer is not None:
+            return
+
+        with self._load_lock:
+            if self._model is not None and self._tokenizer is not None:
+                return
+
+            import torch
+            from transformers import AutoModelForCausalLM, AutoTokenizer
+
+            try:
+                tokenizer = AutoTokenizer.from_pretrained(self.model_name, trust_remote_code=False)
+            except Exception as exc:
+                detail = "".join(traceback.format_exception_only(type(exc), exc)).strip()
+                raise RuntimeError(f"tokenizer load failed for {self.model_name}: {detail}") from exc
+            if tokenizer.pad_token_id is None:
+                tokenizer.pad_token = tokenizer.eos_token
+
+            model_kwargs = {"trust_remote_code": False, "low_cpu_mem_usage": True}
+            if torch.backends.mps.is_available():
+                model_kwargs["torch_dtype"] = torch.float16
+
+            try:
+                model = AutoModelForCausalLM.from_pretrained(self.model_name, **model_kwargs)
+            except Exception as exc:
+                detail = "".join(traceback.format_exception_only(type(exc), exc)).strip()
+                raise RuntimeError(f"model load failed for {self.model_name}: {detail}") from exc
+            if torch.backends.mps.is_available():
+                model = model.to("mps")
+            model.eval()
+
+            self._tokenizer = tokenizer
+            self._model = model

agents/topic_pattern.py

@@ -0,0 +1,155 @@
+import asyncio
+import re
+import threading
+from typing import Any
+
+import yaml
+
+from config import TOPIC_PATTERN_BASE_MODEL, TOPIC_PATTERN_MODEL, USE_TOPIC_PATTERN_MODEL
+
+
+class TopicPatternAgent:
+    """Fine-tuned topic/pattern + coaching-step classifier."""
+
+    def __init__(
+        self,
+        frameworks_path: str = "frameworks.yaml",
+        model_name: str = TOPIC_PATTERN_MODEL,
+        base_model_name: str = TOPIC_PATTERN_BASE_MODEL,
+    ):
+        self.model_name = model_name
+        self.base_model_name = base_model_name
+        self.enabled = USE_TOPIC_PATTERN_MODEL
+        self._model: Any | None = None
+        self._tokenizer: Any | None = None
+        self._device: str = "cpu"
+        self._load_error: str = ""
+        self.last_error = ""
+        self._load_lock = threading.Lock()
+        with open(frameworks_path, "r", encoding="utf-8") as file:
+            self.frameworks: dict[str, dict[str, Any]] = yaml.safe_load(file)
+
+    async def analyze(self, question: str) -> dict[str, Any]:
+        if not self.enabled or not question.strip():
+            self.last_error = "Topic/pattern model is disabled or question is empty."
+            return {}
+
+        try:
+            output = await asyncio.to_thread(self._generate, question.strip())
+        except Exception as exc:
+            self._load_error = str(exc)
+            self.last_error = str(exc)
+            return {}
+
+        parsed = self.parse_output(output)
+        framework = self._valid_framework(parsed.get("type", ""))
+        steps = parsed.get("steps") or []
+        if not framework or not steps:
+            self.last_error = f"Could not parse topic model output: {output[:300]}"
+            return {}
+
+        self.last_error = ""
+        return {
+            "type": framework,
+            "pattern": parsed.get("type", ""),
+            "steps": steps,
+            "confidence": 0.85,
+            "model": self.model_name,
+        }
+
+    def parse_output(self, text: str) -> dict[str, Any]:
+        clean = self._extract_assistant_text(text)
+        type_match = re.search(r"Type\s*:\s*(.+?)(?:\n|$)", clean, flags=re.IGNORECASE)
+        steps_match = re.search(r"Steps\s*:\s*(.+)", clean, flags=re.IGNORECASE | re.DOTALL)
+
+        raw_type = type_match.group(1).strip() if type_match else ""
+        raw_steps = steps_match.group(1).strip() if steps_match else ""
+        steps = self._split_steps(raw_steps)
+
+        return {"type": raw_type, "steps": steps}
+
+    def _generate(self, question: str) -> str:
+        self._ensure_model_loaded_sync()
+        prompt = f"<|im_start|>user\n{question}<|im_end|>\n<|im_start|>assistant\n"
+        inputs = self._tokenizer(prompt, return_tensors="pt")
+        inputs = {key: value.to(self._model.device) for key, value in inputs.items()}
+
+        import torch
+
+        with torch.no_grad():
+            outputs = self._model.generate(
+                **inputs,
+                max_new_tokens=80,
+                temperature=0.1,
+                do_sample=False,
+                pad_token_id=self._tokenizer.eos_token_id,
+            )
+
+        return self._tokenizer.decode(outputs[0], skip_special_tokens=False)
+
+    def _ensure_model_loaded_sync(self) -> None:
+        if self._model is not None and self._tokenizer is not None:
+            return
+
+        with self._load_lock:
+            if self._model is not None and self._tokenizer is not None:
+                return
+
+            import torch
+            from huggingface_hub import snapshot_download
+            from transformers import AutoModelForCausalLM, AutoTokenizer
+
+            adapter_path = snapshot_download(self.model_name, local_files_only=True)
+            tokenizer = AutoTokenizer.from_pretrained(self.base_model_name, trust_remote_code=False)
+            if tokenizer.pad_token_id is None:
+                tokenizer.pad_token = tokenizer.eos_token
+
+            model_kwargs = {"trust_remote_code": False, "low_cpu_mem_usage": True}
+            if torch.backends.mps.is_available():
+                model_kwargs["torch_dtype"] = torch.float16
+
+            try:
+                from peft import PeftModel
+
+                base_model = AutoModelForCausalLM.from_pretrained(self.base_model_name, **model_kwargs)
+                model = PeftModel.from_pretrained(base_model, adapter_path)
+            except Exception as exc:
+                self.last_error = f"PEFT load failed: {exc}"
+                raise
+
+            if torch.backends.mps.is_available():
+                model = model.to("mps")
+            model.eval()
+
+            self._tokenizer = tokenizer
+            self._model = model
+
+    def _extract_assistant_text(self, text: str) -> str:
+        if "<|im_start|>assistant" in text:
+            text = text.split("<|im_start|>assistant", 1)[-1]
+        if "<|im_end|>" in text:
+            text = text.split("<|im_end|>", 1)[0]
+        return text.strip()
+
+    def _split_steps(self, text: str) -> list[str]:
+        if not text:
+            return []
+
+        parts = re.split(r"\s*(?:→|->|,|\n|;)\s*", text)
+        steps = []
+        for part in parts:
+            clean = re.sub(r"^\s*(?:[-*]|\d+[.)])\s*", "", part).strip()
+            if clean:
+                steps.append(clean)
+        return steps[:6]
+
+    def _valid_framework(self, value: str) -> str:
+        aliases = {
+            "Behavioural": "Behavioral",
+            "Product Design": "Product Sense",
+            "Data Science": "Technical",
+            "AI Engineering": "Technical",
+            "Estimation": "Case",
+        }
+        normalized = aliases.get(value.strip(), value.strip())
+        return normalized if normalized in self.frameworks else ""

app.py

@@ -0,0 +1,1721 @@
+import asyncio
+import csv
+import html
+import json
+import os
+import re
+from typing import Any
+
+import gradio as gr
+import numpy as np
+
+from agents.evaluator import EvaluationAgent
+from agents.hf_chat import HuggingFaceChatModel
+from agents.topic_pattern import TopicPatternAgent
+from config import APP_HOST, APP_PORT, BASE_DIR, GENERAL_LLM_MODEL, HF_SPACE_MODE, STREAMING_WHISPER_MODEL
+from db.queries import (
+    add_evaluation,
+    append_exchange_answer,
+    clear_all_tables,
+    create_session,
+    list_all_evaluations,
+    list_evaluations,
+    list_exchanges,
+)
+from db.schema import init_db
+from graph import coach_graph
+from nodes.audio import LiveAudioTranscriber, transcribe_audio_array, transcribe_audio_file
+from prompts import (
+    CLARIFICATION_CHECK_SYSTEM_PROMPT,
+    CLARIFICATION_CHECK_USER_PROMPT,
+    COACHING_GUIDANCE_SYSTEM_PROMPT,
+    COACHING_GUIDANCE_USER_PROMPT,
+    MULTI_EXCHANGE_EXTRACTOR_SYSTEM_PROMPT,
+    MULTI_EXCHANGE_EXTRACTOR_USER_PROMPT,
+    TRANSCRIPT_NORMALIZER_REPAIR_SYSTEM_PROMPT,
+    TRANSCRIPT_NORMALIZER_REPAIR_USER_PROMPT,
+    TRANSCRIPT_NORMALIZER_SYSTEM_PROMPT,
+    TRANSCRIPT_NORMALIZER_USER_PROMPT,
+)
+
+
+CSS = """
+:root {
+    --bg: #0b0f14;
+    --panel: #111827;
+    --panel-soft: #151c28;
+    --panel-muted: #0f1622;
+    --border: #263241;
+    --border-strong: #344154;
+    --text: #e7ebf0;
+    --muted: #9aa5b1;
+    --accent: #14b8a6;
+    --accent-strong: #2dd4bf;
+    --danger: #ef4444;
+}
+body,
+.gradio-container {
+    background: var(--bg) !important;
+    color: var(--text) !important;
+}
+.gradio-container {
+    max-width: 1280px !important;
+    margin: 0 auto !important;
+    padding: 12px 18px !important;
+    font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+#app-shell {
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+}
+#app-header {
+    padding: 0;
+}
+#app-header h1 {
+    margin: 0;
+    font-size: 22px;
+    line-height: 1.15;
+    font-weight: 700;
+}
+#app-header p {
+    margin: 3px 0 0;
+    color: var(--muted);
+    font-size: 12px;
+}
+.form {
+    border: 1px solid var(--border) !important;
+    border-radius: 8px !important;
+    background: var(--panel-muted) !important;
+    padding: 8px 10px !important;
+}
+.action-row {
+    align-items: end;
+}
+.action-row button,
+button {
+    border-radius: 6px !important;
+    font-weight: 650 !important;
+    min-height: 34px !important;
+}
+button.primary {
+    background: var(--accent) !important;
+    border-color: var(--accent) !important;
+    color: #041412 !important;
+}
+button.secondary {
+    background: #1f2937 !important;
+    border-color: var(--border-strong) !important;
+    color: var(--text) !important;
+}
+button.stop {
+    background: #3b1417 !important;
+    border-color: #7f1d1d !important;
+    color: #fecaca !important;
+}
+.tabs {
+    border-radius: 8px !important;
+}
+.tab-nav {
+    border-bottom: 1px solid var(--border) !important;
+}
+.tab-nav button {
+    border-radius: 6px 6px 0 0 !important;
+    color: var(--muted) !important;
+    font-weight: 650 !important;
+}
+.tab-nav button.selected {
+    color: var(--text) !important;
+    border-color: var(--accent) !important;
+}
+.block,
+.panel,
+.form,
+textarea,
+input {
+    border-color: var(--border) !important;
+}
+textarea,
+input {
+    background: #0d131d !important;
+    color: var(--text) !important;
+    border-radius: 6px !important;
+}
+label,
+.label-wrap span {
+    color: var(--muted) !important;
+    font-weight: 650 !important;
+}
+#status_box textarea,
+#stream_status_box textarea {
+    color: var(--accent-strong) !important;
+    font-size: 13px !important;
+}
+.section-title {
+    margin: 0 0 6px;
+    color: var(--muted);
+    font-size: 11px;
+    font-weight: 750;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+}
+.compact-panel {
+    border: 1px solid var(--border) !important;
+    border-radius: 8px !important;
+    background: var(--panel-muted) !important;
+    padding: 10px !important;
+    min-width: 0 !important;
+}
+#live_grid {
+    flex-wrap: nowrap !important;
+    gap: 10px !important;
+}
+#live_grid > div {
+    min-width: 0 !important;
+}
+#live_transcript_box textarea {
+    min-height: 330px !important;
+}
+#log_box textarea,
+#report_box textarea {
+    min-height: 500px !important;
+}
+#status_box textarea {
+    min-height: 34px !important;
+}
+#stream_status_box textarea {
+    min-height: 72px !important;
+    font-size: 12px !important;
+}
+.coach-card {
+    border: 1px solid var(--border);
+    border-left: 5px solid var(--framework-color);
+    border-radius: 8px;
+    background: var(--panel);
+    padding: 14px;
+    min-height: 425px;
+    max-height: 425px;
+    overflow: auto;
+}
+.floating-card {
+    resize: both;
+    min-width: 220px;
+    min-height: 145px;
+    max-width: 100%;
+}
+.coach-card summary {
+    cursor: pointer;
+    list-style: none;
+}
+.coach-card summary::-webkit-details-marker {
+    display: none;
+}
+.card-question {
+    margin: 0 0 8px;
+    color: var(--text);
+    font-size: 14px;
+    line-height: 1.45;
+    font-weight: 650;
+}
+.card-type {
+    display: inline-block;
+    margin: 4px 0 8px;
+    color: var(--accent-strong);
+    font-size: 13px;
+    font-weight: 700;
+}
+.coach-card h3 {
+    margin: 0 0 6px;
+    font-size: 17px;
+    line-height: 1.25;
+}
+.coach-card p {
+    margin: 10px 0;
+    color: var(--text);
+    line-height: 1.5;
+}
+.coach-card ol {
+    margin: 10px 0 0 22px;
+    padding: 0;
+    color: #d5dbe3;
+}
+.coach-card li {
+    margin-bottom: 6px;
+}
+.coach-card-stack {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(230px, 1fr));
+    gap: 10px;
+    max-height: 425px;
+    overflow: auto;
+    padding-right: 4px;
+}
+.coach-card-stack .coach-card {
+    min-height: 0;
+    max-height: none;
+    box-shadow: 0 14px 32px rgba(0, 0, 0, 0.24);
+}
+.meta {
+    color: var(--muted);
+    font-size: 13px;
+}
+.review {
+    color: #fbbf24;
+}
+@keyframes card-pulse {
+    0% { box-shadow: 0 0 0 0 rgba(20, 184, 166, 0.35); }
+    55% { box-shadow: 0 0 0 10px rgba(20, 184, 166, 0); }
+    100% { box-shadow: 0 0 0 0 rgba(20, 184, 166, 0); }
+}
+.flash-card {
+    animation: card-pulse 1.1s ease-out infinite;
+}
+"""
+
+FRAMEWORK_COLORS = {
+    "General": "#64748b",
+    "Behavioral": "#0ea5e9",
+    "Behavioural": "#0ea5e9",
+    "Technical": "#22c55e",
+    "Data Science": "#22c55e",
+    "AI Engineering": "#14b8a6",
+    "System Design": "#f59e0b",
+    "Product Sense": "#ec4899",
+    "Product Design": "#ec4899",
+    "Case": "#a855f7",
+    "Estimation": "#a855f7",
+}
+
+GENERIC_EXTRACTION_MAX_WINDOW_CHARS = 1800
+GENERIC_EXTRACTION_MIN_LLM_DELTA_CHARS = 80
+LIVE_CARD_ANALYSIS_MIN_DELTA_CHARS = 30
+LIVE_FAST_QUESTION_WINDOW_CHARS = 420
+LIVE_FAST_MIN_DELTA_CHARS = 90
+LIVE_FAST_DUPLICATE_SIMILARITY = 0.78
+LIVE_TARGET_FRAMEWORKS = {"Technical", "System Design"}
+LIVE_QUESTION_MARKERS = (
+    "first,",
+    "first.",
+    "first ",
+    "first question",
+    "first one",
+    "second,",
+    "second.",
+    "second ",
+    "second question",
+    "third,",
+    "third.",
+    "third ",
+    "third question",
+    "next question",
+    "another question",
+    "you have",
+    "let me ask",
+    "can you",
+    "could you",
+    "tell me",
+    "explain",
+    "how would",
+    "what would",
+)
+LIVE_ANSWER_STARTS = (
+    " i would ",
+    " i will ",
+    " i can ",
+    " i think ",
+    " i would first ",
+    " first i ",
+    " my approach ",
+    " so i ",
+    " sure ",
+    " yeah ",
+    " yes ",
+)
+
+evaluator = EvaluationAgent()
+general_llm = HuggingFaceChatModel(GENERAL_LLM_MODEL)
+topic_pattern_agent = TopicPatternAgent()
+live_audio = LiveAudioTranscriber()
+topic_model_warmup_task: asyncio.Task | None = None
+
+
+def ensure_topic_model_warmup() -> None:
+    global topic_model_warmup_task
+    if topic_model_warmup_task and not topic_model_warmup_task.done():
+        return
+    topic_model_warmup_task = asyncio.create_task(
+        topic_pattern_agent.analyze("How would you handle class imbalance in a fraud detection model?")
+    )
+
+
+async def start_session(company: str, role: str) -> tuple[int, str]:
+    ensure_topic_model_warmup()
+    await init_db()
+    session_id = await create_session(company=company, role=role)
+    return session_id, f"Session {session_id} started"
+
+
+async def coach_question(session_id: int | None, question: str, answer: str) -> tuple[str, str, dict[str, Any]]:
+    if not session_id:
+        await init_db()
+        session_id = await create_session()
+
+    classification = await classify_topic_and_steps(question)
+    if classification.get("model_unavailable"):
+        state = {
+            "session_id": session_id,
+            "question": question,
+            "answer": answer,
+            "message": classification["message"],
+        }
+        return render_answer_card(state), classification["message"], state
+
+    clarification_state = await handle_clarification_if_needed(session_id, question, answer)
+    if clarification_state:
+        return render_card(clarification_state), await render_log(session_id), clarification_state
+
+    state = await coach_graph.ainvoke(
+        {
+            "session_id": session_id,
+            "raw_text": question,
+            "question": question,
+            "answer": answer.strip(),
+            "framework": classification["type"],
+            "pattern": classification.get("pattern", classification["type"]),
+            "steps": classification["steps"],
+            "confidence": classification["confidence"],
+            "topic_model_used": classification.get("topic_model_used", ""),
+        }
+    )
+    framework_steps = state.get("steps", [])
+    state["steps"] = await generate_coaching_cues(
+        question,
+        classification["type"],
+        classification.get("pattern", classification["type"]),
+        framework_steps,
+    )
+    state["framework_steps"] = framework_steps
+    return render_card(state), await render_log(session_id), state
+
+
+async def classify_topic_and_steps(question: str) -> dict[str, Any]:
+    topic_result = await topic_pattern_agent.analyze(question)
+    if not topic_result:
+        details = topic_pattern_agent.last_error
+        suffix = f" Details: {details}" if details else ""
+        return {
+            "type": "General",
+            "steps": [],
+            "confidence": 0.0,
+            "model_unavailable": True,
+            "message": (
+                "Topic/steps model unavailable. Expected Hugging Face model "
+                f"vadirajkrishna/interview-coach-3b.{suffix}"
+            ),
+        }
+
+    return {
+        "type": topic_result["type"],
+        "steps": topic_result["steps"],
+        "confidence": topic_result.get("confidence", 0.0),
+        "pattern": topic_result.get("pattern", topic_result["type"]),
+        "topic_model_used": topic_result.get("model", ""),
+    }
+
+
+async def normalize_interview_exchange_with_llm(
+    transcript: str,
+    question: str = "",
+    answer: str = "",
+    prefer_latest: bool = False,
+) -> dict[str, Any] | None:
+    mode_instruction = (
+        "Extract the latest complete target interviewer question in the transcript window. "
+        "Ignore earlier target questions that already have candidate answers. "
+        "If the transcript says 'second question', 'next question', or similar, prefer the target question after that marker. "
+        "In a technical/ML interview, production checks, data drift, monitoring, and training-serving data issues are target ML/MLOps questions. "
+        "If first-person answer text follows the latest question, such as 'I will...' or 'I would...', keep that text in answer, not question."
+        if prefer_latest
+        else "Extract the clearest complete target interviewer question and its candidate answer, if present."
+    )
+    prompt = TRANSCRIPT_NORMALIZER_USER_PROMPT.format(
+        transcript=transcript,
+        mode_instruction=mode_instruction,
+        question=question,
+        answer=answer,
+    )
+    response = await general_llm.generate(
+        TRANSCRIPT_NORMALIZER_SYSTEM_PROMPT,
+        prompt,
+        max_new_tokens=512,
+    )
+    if not response:
+        if not general_llm.last_error:
+            general_llm.last_error = "Model returned an empty response."
+        return None
+    try:
+        payload = json.loads(extract_json_object(response))
+    except Exception as exc:
+        preview = response.replace("\n", " ")[:300]
+        general_llm.last_error = f"Model returned non-JSON output: {exc}. Output preview: {preview}"
+        return None
+
+    normalized = normalize_normalizer_payload(payload)
+    if normalized["is_target"] and normalized["complete"] and not normalized["question"]:
+        repaired = await repair_normalizer_payload_with_llm(transcript, payload)
+        if repaired:
+            normalized = normalize_normalizer_payload(repaired)
+    if (
+        normalized["question"]
+        and normalized["answer"]
+        and normalized["answer"].lower() in normalized["question"].lower()
+    ):
+        repaired = await repair_normalizer_payload_with_llm(transcript, normalized)
+        if repaired:
+            repaired_normalized = normalize_normalizer_payload(repaired)
+            if repaired_normalized["is_target"] and repaired_normalized["complete"]:
+                normalized = repaired_normalized
+    if normalized["is_target"] and normalized["complete"] and not normalized["question"]:
+        general_llm.last_error = "Normalizer marked target complete but returned an empty question."
+        normalized["is_target"] = False
+        normalized["complete"] = False
+        normalized["reason"] = "Target question was empty."
+    return normalized
+
+
+def normalize_normalizer_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    clean_question = normalize_llm_text(str(payload.get("question", "")))
+    clean_answer = normalize_llm_text(str(payload.get("answer", "")))
+    if clean_question and not clean_question.endswith("?"):
+        clean_question = f"{clean_question.rstrip('.')}?"
+    return {
+        "question": clean_question,
+        "answer": clean_answer,
+        "is_target": bool(payload.get("is_target", False)),
+        "complete": bool(payload.get("complete", False)),
+        "reason": str(payload.get("reason", "")).strip(),
+    }
+
+
+async def repair_normalizer_payload_with_llm(transcript: str, payload: dict[str, Any]) -> dict[str, Any] | None:
+    prompt = TRANSCRIPT_NORMALIZER_REPAIR_USER_PROMPT.format(
+        transcript=transcript,
+        payload=json.dumps(payload),
+    )
+    response = await general_llm.generate(
+        TRANSCRIPT_NORMALIZER_REPAIR_SYSTEM_PROMPT,
+        prompt,
+        max_new_tokens=384,
+    )
+    if not response:
+        return None
+    try:
+        return json.loads(extract_json_object(response))
+    except Exception as exc:
+        preview = response.replace("\n", " ")[:300]
+        general_llm.last_error = f"Normalizer repair returned non-JSON output: {exc}. Output preview: {preview}"
+        return None
+
+
+async def extract_all_interview_exchanges_with_llm(transcript: str) -> list[dict[str, Any]]:
+    prompt = MULTI_EXCHANGE_EXTRACTOR_USER_PROMPT.format(transcript=transcript)
+    response = await general_llm.generate(
+        MULTI_EXCHANGE_EXTRACTOR_SYSTEM_PROMPT,
+        prompt,
+        max_new_tokens=1400,
+    )
+    if not response:
+        return []
+    try:
+        payload = json.loads(extract_json_object(response))
+    except Exception as exc:
+        preview = response.replace("\n", " ")[:300]
+        general_llm.last_error = f"Multi-exchange extractor returned non-JSON output: {exc}. Output preview: {preview}"
+        return []
+
+    exchanges = payload.get("exchanges", [])
+    if not isinstance(exchanges, list):
+        return []
+
+    cleaned = []
+    for item in exchanges:
+        if not isinstance(item, dict):
+            continue
+        normalized = normalize_normalizer_payload(item)
+        if not normalized["is_target"] or not normalized["complete"] or not normalized["question"]:
+            continue
+        cleaned.append(normalized)
+    return cleaned
+
+
+def normalize_llm_text(text: str) -> str:
+    return re.sub(r"\s+", " ", text).strip(" -:")
+
+
+def general_llm_unavailable_message() -> str:
+    details = f" Details: {general_llm.last_error}" if general_llm.last_error else ""
+    return f"General LLM unavailable. Expected Hugging Face model {GENERAL_LLM_MODEL}.{details}"
+
+
+async def handle_clarification_if_needed(
+    session_id: int,
+    question: str,
+    answer: str,
+) -> dict[str, Any] | None:
+    exchanges = await list_exchanges(session_id)
+    if not exchanges:
+        return None
+
+    previous = exchanges[-1]
+    if not await is_clarification_question(previous["question"], question, answer):
+        return None
+
+    addition = f"Clarification: {question}"
+    if answer.strip():
+        addition = f"{addition}\nCandidate follow-up: {answer.strip()}"
+    await append_exchange_answer(previous["id"], addition)
+
+    result = await classify_topic_and_steps(previous["question"])
+    cues = await generate_coaching_cues(
+        previous["question"],
+        previous["framework_used"],
+        result.get("pattern", previous["framework_used"]),
+        result["steps"],
+    )
+    return {
+        "session_id": session_id,
+        "exchange_id": previous["id"],
+        "question": previous["question"],
+        "answer": addition,
+        "framework": previous["framework_used"],
+        "pattern": result.get("pattern", previous["framework_used"]),
+        "steps": cues,
+        "framework_steps": result["steps"],
+        "confidence": result["confidence"],
+        "needs_review": False,
+    }
+
+
+async def is_clarification_question(previous_question: str, new_question: str, answer: str) -> bool:
+    heuristic = is_clarification_question_heuristic(previous_question, new_question)
+    llm_result = await is_clarification_question_with_llm(previous_question, new_question, answer)
+    return llm_result if llm_result is not None else heuristic
+
+
+async def is_clarification_question_with_llm(
+    previous_question: str,
+    new_question: str,
+    answer: str,
+) -> bool | None:
+    prompt = CLARIFICATION_CHECK_USER_PROMPT.format(
+        previous_question=previous_question,
+        new_question=new_question,
+        answer=answer,
+    )
+    response = await general_llm.generate(
+        CLARIFICATION_CHECK_SYSTEM_PROMPT,
+        prompt,
+        max_new_tokens=256,
+    )
+    if not response:
+        return None
+    try:
+        payload = json.loads(extract_json_object(response))
+        return bool(payload.get("is_clarification", False))
+    except Exception:
+        return None
+
+
+def is_clarification_question_heuristic(previous_question: str, new_question: str) -> bool:
+    previous = previous_question.lower()
+    current = new_question.lower().strip()
+    if len(current.split()) < 3:
+        return False
+
+    clarification_starts = (
+        "do you mean",
+        "did you mean",
+        "when you say",
+        "should i assume",
+        "can i assume",
+        "are we assuming",
+        "are we considering",
+        "should we consider",
+        "is it okay if",
+        "can i clarify",
+        "could you clarify",
+        "what do you mean by",
+        "for this question",
+        "in this case",
+    )
+    if current.startswith(clarification_starts):
+        return True
+
+    clarification_terms = (
+        "assume",
+        "clarify",
+        "constraint",
+        "scope",
+        "mean by",
+        "considering",
+        "requirement",
+        "latency",
+        "scale",
+        "users",
+        "time window",
+    )
+    overlap = set(re.findall(r"[a-zA-Z]+", previous)).intersection(
+        set(re.findall(r"[a-zA-Z]+", current))
+    )
+    return any(term in current for term in clarification_terms) and bool(overlap)
+
+
+async def transcribe_and_coach(
+    session_id: int | None,
+    audio_input: Any,
+    typed_transcript: str,
+) -> tuple[str, str, str, dict[str, Any]]:
+    if audio_input is None:
+        return "Record audio first, then press Transcribe & Coach.", render_answer_card(), "", {}
+
+    transcript = await transcribe_audio_input(audio_input)
+    if transcript.startswith("[transcription unavailable:"):
+        return transcript, render_answer_card(), "", {}
+
+    normalized = await normalize_interview_exchange_with_llm(transcript)
+    if (
+        normalized
+        and normalized.get("is_target")
+        and normalized.get("complete")
+        and normalized.get("question", "").strip()
+    ):
+        card, log, state = await coach_question(
+            session_id,
+            normalized.get("question", ""),
+            normalized.get("answer", ""),
+        )
+        return transcript, card, log, state
+
+    state = {
+        "message": (
+            "General LLM could not extract a complete DS/ML/AI/System Design question."
+            if normalized
+            else general_llm_unavailable_message()
+        )
+    }
+    return transcript, render_answer_card(state), state["message"], state
+
+
+async def stream_live_transcript(
+    audio_input: Any,
+    current_transcript: str,
+    stream_state: dict[str, Any] | None,
+) -> tuple[str, str, str, dict[str, Any], dict[str, Any]]:
+    if audio_input is None:
+        state = stream_state or fresh_stream_state()
+        return (
+            current_transcript or "",
+            state.get("card_html") or render_answer_card(),
+            format_stream_status(state, "waiting for microphone"),
+            state,
+            state.get("card_state") or {},
+        )
+
+    state = update_stream_state(audio_input, stream_state)
+    audio_buffer = state.get("audio_buffer")
+    sample_rate = int(state.get("sample_rate") or 16000)
+    processed_until = int(state.get("processed_until") or 0)
+    available = 0 if audio_buffer is None else len(audio_buffer) - processed_until
+    if available < sample_rate * 3:
+        return (
+            current_transcript or "",
+            state.get("card_html") or render_answer_card(),
+            format_stream_status(state, "buffering audio"),
+            state,
+            state.get("card_state") or {},
+        )
+
+    overlap = int(sample_rate * 0.5)
+    start = max(0, processed_until - overlap)
+    end = len(audio_buffer)
+    audio_window = audio_buffer[start:end].copy()
+    state["processed_until"] = end
+    rms = audio_rms(audio_window)
+    state["last_rms"] = rms
+    if rms < 0.003:
+        return (
+            current_transcript or "",
+            state.get("card_html") or render_answer_card(),
+            format_stream_status(state, "quiet audio skipped"),
+            state,
+            state.get("card_state") or {},
+        )
+
+    chunk_text = await transcribe_audio_array(
+        sample_rate,
+        audio_window,
+        model=STREAMING_WHISPER_MODEL,
+        temperature=0.0,
+        condition_on_previous_text=False,
+        compression_ratio_threshold=1.8,
+        logprob_threshold=-0.6,
+        no_speech_threshold=0.35,
+    )
+    if not chunk_text or chunk_text.startswith("[transcription unavailable:"):
+        return (
+            current_transcript or "",
+            state.get("card_html") or render_answer_card(),
+            format_stream_status(state, chunk_text or "no speech detected yet"),
+            state,
+            state.get("card_state") or {},
+        )
+    if is_repetitive_hallucination(chunk_text):
+        state["rejected"] = int(state.get("rejected") or 0) + 1
+        state["last_text"] = f"rejected: {chunk_text[:60]}"
+        return (
+            current_transcript or "",
+            state.get("card_html") or render_answer_card(),
+            format_stream_status(state, "repeated-word output skipped"),
+            state,
+            state.get("card_state") or {},
+        )
+
+    state["transcriptions"] = int(state.get("transcriptions") or 0) + 1
+    state["last_text"] = chunk_text
+    updated_transcript = merge_transcript_text(current_transcript or "", chunk_text)
+    card_html, card_state = await monitor_answer_card(updated_transcript, state, force=True)
+    state["card_html"] = card_html
+    state["card_state"] = card_state
+    return (
+        updated_transcript,
+        card_html,
+        format_stream_status(state, "transcribing"),
+        state,
+        card_state,
+    )
+
+
+async def start_backend_live_transcript():
+    ensure_topic_model_warmup()
+    await live_audio.start()
+    monitor_state = fresh_card_monitor_state()
+    async for transcript in live_audio.transcript_stream():
+        card_html, card_state = await monitor_answer_card(
+            transcript,
+            monitor_state,
+            force=False,
+            fast=True,
+        )
+        yield (
+            transcript,
+            card_html,
+            "Capturing system audio via BlackHole/default input",
+            card_state,
+            monitor_state,
+        )
+
+
+async def stop_backend_live_transcript() -> str:
+    await live_audio.stop()
+    return "Stopped live audio capture"
+
+
+async def transcribe_audio_input(audio_input: Any) -> str:
+    if isinstance(audio_input, str):
+        return await transcribe_audio_file(audio_input)
+    if isinstance(audio_input, tuple) and len(audio_input) == 2:
+        sample_rate, audio = audio_input
+        return await transcribe_audio_array(int(sample_rate), np.asarray(audio))
+    return "[transcription unavailable: unsupported audio input]"
+
+
+async def process_typed_transcript(
+    session_id: int | None,
+    transcript: str,
+) -> tuple[str, str, str, dict[str, Any]]:
+    exchanges = await extract_all_interview_exchanges_with_llm(transcript)
+    if exchanges:
+        cards = []
+        last_state: dict[str, Any] = {}
+        log = ""
+        for exchange in exchanges:
+            card, log, last_state = await coach_question(
+                session_id,
+                exchange["question"],
+                exchange.get("answer", ""),
+            )
+            cards.append(card)
+            session_id = last_state.get("session_id", session_id)
+        last_state["processed_exchanges"] = exchanges
+        return transcript, render_cards(cards), log, last_state
+
+    normalized = await normalize_interview_exchange_with_llm(transcript)
+    if (
+        normalized
+        and normalized.get("is_target")
+        and normalized.get("complete")
+        and normalized.get("question", "").strip()
+    ):
+        card, log, state = await coach_question(
+            session_id,
+            normalized.get("question", ""),
+            normalized.get("answer", ""),
+        )
+        return transcript, card, log, state
+
+    state = {
+        "message": (
+            "General LLM could not extract a complete DS/ML/AI/System Design question."
+            if normalized
+            else general_llm_unavailable_message()
+        )
+    }
+    return transcript, render_answer_card(state), state["message"], state
+
+
+def clear_live_state() -> tuple[str, str, dict[str, Any], str, dict[str, Any]]:
+    state = fresh_stream_state()
+    return "", render_answer_card(), state, format_stream_status(state, "cleared"), fresh_card_monitor_state()
+
+
+async def clear_database() -> tuple[None, dict[str, Any], dict[str, Any], str, str, str, str, str, dict[str, Any]]:
+    await init_db()
+    await clear_all_tables()
+    return (
+        None,
+        {},
+        fresh_stream_state(),
+        "All SQLite tables cleared. Start a new session to continue.",
+        "",
+        render_answer_card(),
+        "",
+        "",
+        fresh_card_monitor_state(),
+    )
+
+
+async def monitor_answer_card(
+    transcript: str,
+    monitor_state: dict[str, Any] | None,
+    force: bool = False,
+    fast: bool = True,
+) -> tuple[str, dict[str, Any]]:
+    monitor_state = monitor_state or fresh_card_monitor_state()
+    if fast:
+        question = extract_fast_live_question_candidate(transcript, monitor_state, force=force)
+    else:
+        question = await extract_target_question_from_transcript(transcript, monitor_state, force=force)
+    if not question:
+        message = monitor_state.get("last_extraction_message", "")
+        card_html = monitor_state.get("card_html") or render_answer_card({"message": message})
+        return card_html, monitor_state.get("card_state") or {}
+
+    question_key = question_dedupe_key(question)
+    if is_duplicate_live_question(question_key, monitor_state):
+        return monitor_state.get("card_html") or render_answer_card(), monitor_state.get("card_state") or {}
+    if question_key == monitor_state.get("last_non_target_question_key"):
+        return monitor_state.get("card_html") or render_answer_card(), monitor_state.get("card_state") or {}
+
+    result = await classify_topic_and_steps(question)
+    if result.get("model_unavailable"):
+        monitor_state["last_extraction_message"] = result["message"]
+        return monitor_state.get("card_html") or render_answer_card({"message": result["message"]}), {}
+    if fast and result.get("type") not in LIVE_TARGET_FRAMEWORKS:
+        monitor_state["last_non_target_question"] = question
+        monitor_state["last_non_target_question_key"] = question_key
+        monitor_state["last_extraction_message"] = "Listening for a DS/ML/AI/System Design question."
+        return monitor_state.get("card_html") or render_answer_card({"message": monitor_state["last_extraction_message"]}), {}
+
+    cues = await generate_coaching_cues(
+        question,
+        result["type"],
+        result.get("pattern", result["type"]),
+        result["steps"],
+    )
+    card_state = {
+        "question": question,
+        "question_key": question_key,
+        "framework": result["type"],
+        "pattern": result.get("pattern", result["type"]),
+        "steps": cues,
+        "framework_steps": result["steps"],
+        "confidence": result["confidence"],
+        "needs_review": result["confidence"] < 0.6,
+    }
+    cards = monitor_state.setdefault("cards", [])
+    if not any(questions_are_similar(question_key, str(card.get("question_key", ""))) for card in cards):
+        cards.append(card_state)
+    card_html = render_cards([render_card(card, flash=card.get("question") == question) for card in cards])
+    monitor_state["last_question"] = question
+    monitor_state["last_question_key"] = question_key
+    monitor_state["card_html"] = card_html
+    monitor_state["card_state"] = card_state
+    return card_html, card_state
+
+
+async def update_live_card_from_transcript(
+    transcript: str,
+    monitor_state: dict[str, Any] | None,
+) -> tuple[str, dict[str, Any], dict[str, Any]]:
+    return await refresh_live_card_from_transcript(transcript, monitor_state, force=False)
+
+
+async def call_coaching_from_transcript(
+    transcript: str,
+    monitor_state: dict[str, Any] | None,
+) -> tuple[str, dict[str, Any], dict[str, Any]]:
+    ensure_topic_model_warmup()
+    return await refresh_live_card_from_transcript(transcript, monitor_state, force=True)
+
+
+async def refresh_live_card_from_transcript(
+    transcript: str,
+    monitor_state: dict[str, Any] | None,
+    force: bool,
+) -> tuple[str, dict[str, Any], dict[str, Any]]:
+    monitor_state = monitor_state or fresh_card_monitor_state()
+    if not transcript.strip():
+        monitor_state = fresh_card_monitor_state()
+        return render_answer_card(), {}, monitor_state
+
+    card_html, card_state = await monitor_answer_card(
+        transcript,
+        monitor_state,
+        force=force,
+        fast=True,
+    )
+    return card_html, card_state, monitor_state
+
+
+async def generate_coaching_cues(
+    question: str,
+    framework: str,
+    pattern: str,
+    fallback_steps: list[str],
+) -> list[str]:
+    cues = await generate_coaching_cues_with_llm(question, framework, pattern, fallback_steps)
+    if cues:
+        return cues
+    return fallback_steps
+
+
+async def generate_coaching_cues_with_llm(
+    question: str,
+    framework: str,
+    pattern: str,
+    fallback_steps: list[str],
+) -> list[str]:
+    prompt = COACHING_GUIDANCE_USER_PROMPT.format(
+        question=question,
+        framework=framework,
+        pattern=pattern,
+        steps="\n".join(f"- {step}" for step in fallback_steps),
+    )
+    response = await general_llm.generate(
+        COACHING_GUIDANCE_SYSTEM_PROMPT,
+        prompt,
+        max_new_tokens=384,
+    )
+    if not response:
+        return []
+    try:
+        payload = json.loads(extract_json_object(response))
+        cues = payload.get("cues", [])
+        if isinstance(cues, list):
+            return [str(cue).strip() for cue in cues if str(cue).strip()][:6]
+    except Exception:
+        return []
+    return []
+
+
+def fresh_card_monitor_state() -> dict[str, Any]:
+    return {
+        "last_question": "",
+        "last_question_key": "",
+        "card_html": render_answer_card(),
+        "card_state": {},
+        "cards": [],
+        "last_non_target_question": "",
+        "last_non_target_question_key": "",
+        "generic_last_llm_until": 0,
+        "generic_last_extracted_question": "",
+        "fast_last_checked_until": 0,
+    }
+
+
+def extract_fast_live_question_candidate(
+    transcript: str,
+    state: dict[str, Any],
+    force: bool = False,
+) -> str | None:
+    clean = normalize_llm_text(transcript)
+    if len(clean.split()) < 5:
+        state["last_extraction_message"] = "Listening for a complete DS/ML/AI/System Design question."
+        return None
+
+    last_checked_until = int(state.get("fast_last_checked_until") or 0)
+    if not force and len(clean) - last_checked_until < LIVE_FAST_MIN_DELTA_CHARS:
+        return None
+
+    state["fast_last_checked_until"] = len(clean)
+    candidate = clean_fast_live_question(clean[-LIVE_FAST_QUESTION_WINDOW_CHARS:])
+    if len(candidate.split()) < 5:
+        state["last_extraction_message"] = "Listening for a complete DS/ML/AI/System Design question."
+        return None
+
+    state["last_extraction_message"] = ""
+    return candidate
+
+
+def clean_fast_live_question(window: str) -> str:
+    candidate = f" {normalize_llm_text(window)} "
+    lowered = candidate.lower()
+
+    marker_positions = [lowered.rfind(marker) for marker in LIVE_QUESTION_MARKERS]
+    marker_positions = [position for position in marker_positions if position >= 0]
+    if marker_positions:
+        candidate = candidate[max(marker_positions) :].strip()
+
+    lowered = f" {candidate.lower()} "
+    answer_positions = [lowered.find(marker) for marker in LIVE_ANSWER_STARTS]
+    answer_positions = [position for position in answer_positions if position > 6]
+    if answer_positions:
+        candidate = candidate[: min(answer_positions)].strip()
+
+    candidate = re.sub(
+        r"^(?:first|second|third|next|another)(?:\s+(?:question|one))?\s*[:,.-]?\s*",
+        "",
+        candidate,
+        flags=re.IGNORECASE,
+    )
+    candidate = re.sub(r"^(you have)\.\s+\1\b", r"\1", candidate, flags=re.IGNORECASE)
+
+    question_mark = candidate.rfind("?")
+    if question_mark >= 0:
+        candidate = candidate[: question_mark + 1]
+
+    candidate = remove_fast_transcript_repeats(candidate)
+    candidate = candidate.strip(" .,-:")
+    if candidate and not candidate.endswith("?"):
+        candidate = f"{candidate}?"
+    return candidate
+
+
+def remove_fast_transcript_repeats(text: str) -> str:
+    words = text.split()
+    cleaned: list[str] = []
+    for word in words:
+        normalized = word.lower().strip(".,?!:;")
+        if cleaned and normalized == cleaned[-1].lower().strip(".,?!:;"):
+            continue
+        cleaned.append(word)
+    return " ".join(cleaned)
+
+
+def question_dedupe_key(question: str) -> str:
+    words = re.findall(r"[a-z0-9]+", question.lower())
+    stop_words = {
+        "a",
+        "an",
+        "and",
+        "are",
+        "as",
+        "be",
+        "briefly",
+        "can",
+        "could",
+        "do",
+        "does",
+        "explain",
+        "for",
+        "how",
+        "i",
+        "in",
+        "is",
+        "it",
+        "me",
+        "of",
+        "please",
+        "question",
+        "tell",
+        "the",
+        "to",
+        "we",
+        "what",
+        "would",
+        "you",
+        "your",
+    }
+    useful = [word for word in words if word not in stop_words and len(word) > 1]
+    return " ".join(useful[:40])
+
+
+def is_duplicate_live_question(question_key: str, state: dict[str, Any]) -> bool:
+    if not question_key:
+        return False
+    if questions_are_similar(question_key, str(state.get("last_question_key", ""))):
+        return True
+    return any(
+        questions_are_similar(question_key, str(card.get("question_key", "")))
+        for card in state.get("cards", [])
+        if isinstance(card, dict)
+    )
+
+
+def questions_are_similar(left_key: str, right_key: str) -> bool:
+    left = set(left_key.split())
+    right = set(right_key.split())
+    if not left or not right:
+        return False
+    overlap = len(left & right)
+    containment = overlap / min(len(left), len(right))
+    union = len(left | right)
+    jaccard = overlap / union if union else 0.0
+    return containment >= LIVE_FAST_DUPLICATE_SIMILARITY or jaccard >= LIVE_FAST_DUPLICATE_SIMILARITY
+
+
+async def extract_target_question_from_transcript(
+    transcript: str,
+    state: dict[str, Any],
+    force: bool = False,
+) -> str | None:
+    clean = re.sub(r"\s+", " ", transcript).strip()
+    if len(clean.split()) < 4:
+        return None
+
+    last_llm_until = int(state.get("generic_last_llm_until") or 0)
+    if (
+        not force
+        and len(clean) - last_llm_until < GENERIC_EXTRACTION_MIN_LLM_DELTA_CHARS
+        and "?" not in clean[last_llm_until:]
+    ):
+        return None
+
+    window = clean[-GENERIC_EXTRACTION_MAX_WINDOW_CHARS:]
+    state["generic_last_llm_until"] = len(clean)
+    result = await normalize_interview_exchange_with_llm(window, prefer_latest=True)
+    if not result:
+        details = f" Details: {general_llm.last_error}" if general_llm.last_error else ""
+        state["last_extraction_message"] = (
+            f"General LLM unavailable. Expected Hugging Face model {GENERAL_LLM_MODEL}.{details}"
+        )
+        return None
+    if not result.get("is_target") or not result.get("complete"):
+        state["last_extraction_message"] = "Listening for a complete DS/ML/AI/System Design question."
+        return None
+
+    question = str(result.get("question", "")).strip()
+    if not question or question == state.get("generic_last_extracted_question"):
+        return None
+
+    state["generic_last_extracted_question"] = question
+    state["last_extraction_message"] = ""
+    return question
+
+
+def extract_json_object(text: str) -> str:
+    match = re.search(r"\{.*\}", text, flags=re.DOTALL)
+    return match.group(0) if match else text
+
+
+def merge_transcript_text(existing: str, incoming: str) -> str:
+    existing = re.sub(r"\s+", " ", existing).strip()
+    incoming = re.sub(r"\s+", " ", incoming).strip()
+    if not existing:
+        return incoming
+    if not incoming:
+        return existing
+    if incoming.lower().startswith(existing.lower()):
+        return incoming
+    if existing.lower().endswith(incoming.lower()):
+        return existing
+    overlap = find_text_overlap(existing, incoming)
+    if overlap:
+        return f"{existing}{incoming[overlap:]}".strip()
+    return f"{existing} {incoming}".strip()
+
+
+def find_text_overlap(existing: str, incoming: str) -> int:
+    existing_lower = existing.lower()
+    incoming_lower = incoming.lower()
+    max_overlap = min(len(existing), len(incoming), 120)
+    for size in range(max_overlap, 4, -1):
+        if existing_lower.endswith(incoming_lower[:size]):
+            return size
+    return 0
+
+
+def fresh_stream_state() -> dict[str, Any]:
+    return {
+        "sample_rate": None,
+        "audio_buffer": np.array([], dtype=np.float32),
+        "last_seen_samples": 0,
+        "processed_until": 0,
+        "chunks": 0,
+        "transcriptions": 0,
+        "rejected": 0,
+        "last_rms": 0.0,
+        "last_text": "",
+    }
+
+
+def update_stream_state(audio_input: Any, stream_state: dict[str, Any] | None) -> dict[str, Any]:
+    state = stream_state or fresh_stream_state()
+    if not isinstance(audio_input, tuple) or len(audio_input) != 2:
+        return state
+
+    sample_rate, audio = audio_input
+    audio = np.asarray(audio)
+    if audio.ndim > 1:
+        audio = audio.mean(axis=1)
+    if np.issubdtype(audio.dtype, np.integer):
+        audio = audio.astype(np.float32) / np.iinfo(audio.dtype).max
+    else:
+        audio = audio.astype(np.float32, copy=False)
+
+    last_seen = int(state.get("last_seen_samples") or 0)
+    if len(audio) > last_seen:
+        new_audio = audio[last_seen:]
+        state["last_seen_samples"] = len(audio)
+    else:
+        new_audio = audio
+        state["last_seen_samples"] = len(audio)
+
+    audio_buffer = state.get("audio_buffer")
+    if audio_buffer is None:
+        audio_buffer = np.array([], dtype=np.float32)
+
+    state["sample_rate"] = int(sample_rate)
+    state["chunks"] = int(state.get("chunks") or 0) + 1
+    combined = np.concatenate([audio_buffer, new_audio])
+    max_samples = int(sample_rate) * 45
+    dropped = max(0, len(combined) - max_samples)
+    state["audio_buffer"] = combined[-max_samples:]
+    state["processed_until"] = max(0, int(state.get("processed_until") or 0) - dropped)
+    return state
+
+
+def format_stream_status(state: dict[str, Any], message: str) -> str:
+    sample_rate = int(state.get("sample_rate") or 16000)
+    audio_buffer = state.get("audio_buffer")
+    buffered_seconds = 0.0
+    if audio_buffer is not None:
+        buffered_seconds = len(audio_buffer) / sample_rate
+    processed_seconds = int(state.get("processed_until") or 0) / sample_rate
+
+    chunks = int(state.get("chunks") or 0)
+    transcriptions = int(state.get("transcriptions") or 0)
+    rejected = int(state.get("rejected") or 0)
+    rms = float(state.get("last_rms") or 0.0)
+    last_text = str(state.get("last_text") or "").strip()
+    if last_text:
+        last_text = f" | last: {last_text[:80]}"
+    return (
+        f"{message} | chunks: {chunks} | buffered: {buffered_seconds:.1f}s "
+        f"| processed: {processed_seconds:.1f}s | runs: {transcriptions} "
+        f"| rejected: {rejected} | rms: {rms:.4f}{last_text}"
+    )
+
+
+def audio_rms(audio: np.ndarray) -> float:
+    if audio.size == 0:
+        return 0.0
+    return float(np.sqrt(np.mean(np.square(audio.astype(np.float32)))))
+
+
+def is_repetitive_hallucination(text: str) -> bool:
+    words = re.findall(r"[a-zA-Z']+", text.lower())
+    if len(words) < 8:
+        return False
+
+    unique_words = set(words)
+    if len(unique_words) <= 2:
+        return True
+
+    most_common = max(words.count(word) for word in unique_words)
+    if most_common / len(words) >= 0.65:
+        return True
+
+    repeated_run = 1
+    for previous, current in zip(words, words[1:]):
+        repeated_run = repeated_run + 1 if previous == current else 1
+        if repeated_run >= 5:
+            return True
+    return False
+
+
+async def evaluate_session(session_id: int | None, last_state: dict[str, Any] | None) -> str:
+    if not session_id:
+        return "Start a session first."
+
+    exchanges = await list_exchanges(session_id)
+    if not exchanges:
+        return "No exchanges to evaluate yet."
+
+    existing_evaluations = await list_evaluations(session_id)
+    evaluated_exchange_ids = {item["exchange_id"] for item in existing_evaluations}
+    pending_exchanges = [exchange for exchange in exchanges if exchange["id"] not in evaluated_exchange_ids]
+    if not pending_exchanges:
+        return await render_evaluations(session_id)
+
+    latest_state_exchange_id = (last_state or {}).get("exchange_id")
+    for exchange in pending_exchanges:
+        if exchange["id"] == latest_state_exchange_id:
+            steps = (last_state or {}).get("framework_steps") or (last_state or {}).get("steps") or []
+        else:
+            classification = await classify_topic_and_steps(exchange["question"])
+            steps = classification.get("steps", [])
+        if not steps:
+            steps = ["Clarify", "Answer", "Example", "Impact"]
+
+        result = await evaluator.evaluate(
+            question=exchange["question"],
+            answer=exchange["answer"],
+            framework=exchange["framework_used"],
+            steps=steps,
+        )
+        await add_evaluation(
+            exchange_id=exchange["id"],
+            steps_covered=result["steps_covered"],
+            score=result["score"],
+            feedback=result["feedback"],
+        )
+    return await render_evaluations(session_id)
+
+
+async def render_log(session_id: int) -> str:
+    exchanges = await list_exchanges(session_id)
+    if not exchanges:
+        return "No exchanges yet."
+    lines = []
+    for item in exchanges:
+        lines.append(
+            f"Q{item['id']} [{item['framework_used']}]: {item['question']}\n"
+            f"A: {item['answer'] or '(not captured yet)'}"
+        )
+    return "\n\n".join(lines)
+
+
+async def render_evaluations(session_id: int) -> str:
+    evaluations = await list_evaluations(session_id)
+    if not evaluations:
+        return "No evaluations yet."
+    blocks = []
+    for item in evaluations:
+        blocks.append(
+            f"Exchange {item['exchange_id']}\n"
+            f"Framework: {item['framework_used']}\n"
+            f"{item['feedback']}"
+        )
+    return "\n\n".join(blocks)
+
+
+async def render_sqlite_evaluation_summary(session_id: int | None) -> tuple[str, list[list[str]]]:
+    evaluations = await list_evaluations(session_id) if session_id else await list_all_evaluations()
+    if not evaluations:
+        return "No evaluated exchanges found in SQLite. Run Evaluate Session first.", []
+
+    blocks = []
+    rows = []
+    for item in evaluations:
+        feedback_parts = split_evaluation_feedback(item["feedback"])
+        session_name = format_session_name(item)
+        session_date = format_session_date(item.get("date", ""))
+        session_label = ""
+        if item.get("session_id"):
+            session_label = f"{session_name} - {session_date}\n"
+        blocks.append(
+            f"{session_label}"
+            f"Exchange {item['exchange_id']} [{item['framework_used']}]\n\n"
+            f"Question:\n{item['question']}\n\n"
+            f"My answer:\n{item['answer'] or '(not captured yet)'}\n\n"
+            f"Benchmark answer:\n{feedback_parts['benchmark']}\n\n"
+            f"Evaluation band:\n{feedback_parts['band']}\n\n"
+            f"Feedback:\n{feedback_parts['feedback']}"
+        )
+        rows.append(
+            [
+                session_name,
+                session_date,
+                item["question"],
+                item["answer"] or "(not captured yet)",
+                feedback_parts["benchmark"],
+                feedback_parts["band"],
+                feedback_parts["feedback"],
+            ]
+        )
+    return "\n\n---\n\n".join(blocks), rows
+
+
+async def export_sqlite_evaluation_summary_csv(session_id: int | None) -> str | None:
+    _, rows = await render_sqlite_evaluation_summary(session_id)
+    if not rows:
+        return None
+
+    export_dir = BASE_DIR / ".runtime" / "exports"
+    export_dir.mkdir(parents=True, exist_ok=True)
+    export_path = export_dir / "evaluation_summary.csv"
+    with export_path.open("w", newline="", encoding="utf-8") as file:
+        writer = csv.writer(file)
+        writer.writerow(EVALUATION_TABLE_HEADERS)
+        writer.writerows(rows)
+    return str(export_path)
+
+
+EVALUATION_TABLE_HEADERS = [
+    "Session",
+    "Date",
+    "Question",
+    "Candidate Answer",
+    "Model Benchmark Answer",
+    "Evaluation Band",
+    "Feedback",
+]
+
+
+def format_session_name(item: dict[str, Any]) -> str:
+    session_id = item.get("session_id", "")
+    company = item.get("company") or "Unknown company"
+    role = item.get("role") or "Unknown role"
+    return f"Session {session_id} - {company} / {role}"
+
+
+def format_session_date(value: str) -> str:
+    if not value:
+        return ""
+    return value.replace("T", " ").split(".")[0]
+
+
+def split_evaluation_feedback(feedback: str) -> dict[str, str]:
+    benchmark = extract_feedback_section(feedback, "Agent benchmark answer:", "Evaluation band:")
+    if not benchmark:
+        benchmark = extract_feedback_section(feedback, "Agent benchmark answer:", "Score:")
+
+    band = extract_feedback_section(feedback, "Evaluation band:", "Strong points:")
+    score_and_feedback = extract_feedback_section(feedback, "Evaluation band:", "")
+    if band:
+        score_and_feedback = extract_feedback_section(feedback, "Strong points:", "")
+        score_and_feedback = f"Strong points:\n{score_and_feedback}".strip()
+    else:
+        score_and_feedback = extract_feedback_section(feedback, "Score:", "")
+        if score_and_feedback:
+            score_text = re.match(r"^\s*(\d+\s*/\s*5)", score_and_feedback)
+            band = score_text.group(1) if score_text else "Unknown"
+            score_and_feedback = re.sub(r"^\s*\d+\s*/\s*5\s*", "", score_and_feedback).strip()
+    return {
+        "benchmark": benchmark or "(benchmark not available)",
+        "band": band or "Unknown",
+        "feedback": score_and_feedback or feedback.strip() or "(feedback not available)",
+    }
+
+
+def extract_feedback_section(text: str, start_label: str, end_label: str) -> str:
+    start = text.find(start_label)
+    if start == -1:
+        return ""
+    start += len(start_label)
+    end = text.find(end_label, start) if end_label else -1
+    if end == -1:
+        return text[start:].strip()
+    return text[start:end].strip()
+
+
+def render_card(state: dict[str, Any], flash: bool = False) -> str:
+    framework = html.escape(state.get("framework", "General"))
+    pattern = html.escape(state.get("pattern", ""))
+    display_type = pattern or framework
+    question = html.escape(state.get("question", "Question unavailable"))
+    color = FRAMEWORK_COLORS.get(display_type, FRAMEWORK_COLORS.get(framework, FRAMEWORK_COLORS["General"]))
+    steps = "".join(f"<li>{html.escape(step)}</li>" for step in state.get("steps", []))
+    flash_class = " flash-card" if flash else ""
+    return f"""
+    <details class="coach-card floating-card{flash_class}" style="--framework-color: {color}" open>
+        <summary>
+            <div class="card-question">{question}</div>
+            <span class="card-type">Type: {display_type}</span>
+        </summary>
+        <div class="meta">Steps</div>
+        <ol>{steps}</ol>
+    </details>
+    """
+
+
+def render_cards(cards: list[str]) -> str:
+    if not cards:
+        return render_answer_card()
+    return "<div class='coach-card-stack'>" + "\n".join(cards) + "</div>"
+
+
+def render_answer_card(state: dict[str, Any] | None = None) -> str:
+    state = state or {}
+    status = state.get("message") or "Waiting for answer card content."
+    if state.get("answer"):
+        status = "Answer captured. Card content to be defined."
+    return f"""
+    <div class="coach-card" style="--framework-color: #22c55e">
+        <h3>Answer Card</h3>
+        <div class="meta">{html.escape(status)}</div>
+    </div>
+    """
+
+
+with gr.Blocks(elem_id="app-shell") as demo:
+    session_id = gr.State(None)
+    last_state = gr.State({})
+    stream_state = gr.State(fresh_stream_state())
+    card_monitor_state = gr.State(fresh_card_monitor_state())
+
+    runtime_label = "Hugging Face Space browser-mic demo" if HF_SPACE_MODE else "Local real-time system-audio coaching"
+    gr.Markdown(
+        f"# InterviewCoach\n{runtime_label} with live transcript, framework cards, and post-session evaluation.",
+        elem_id="app-header",
+    )
+    with gr.Row(elem_classes=["form", "action-row"]):
+        company = gr.Textbox(label="Company", placeholder="Anthropic", scale=2)
+        role = gr.Textbox(label="Role", placeholder="ML Engineer", scale=2)
+        start = gr.Button("Create Session", variant="primary", scale=1)
+    status = gr.Textbox(label="Session Status", interactive=False, elem_id="status_box")
+
+    with gr.Tabs():
+        with gr.Tab("Live"):
+            with gr.Row(equal_height=True, elem_id="live_grid"):
+                with gr.Column(scale=2, min_width=180, elem_classes=["compact-panel"]):
+                    if HF_SPACE_MODE:
+                        gr.Markdown("Browser microphone", elem_classes=["section-title"])
+                        mic = gr.Audio(
+                            sources=["microphone"],
+                            type="numpy",
+                            label="Record from browser",
+                            elem_id="mic_box",
+                        )
+                        with gr.Row(elem_classes=["action-row"]):
+                            transcribe_coach = gr.Button("Transcribe & Process", variant="primary")
+                    else:
+                        gr.Markdown("System audio", elem_classes=["section-title"])
+                        with gr.Row(elem_classes=["action-row"]):
+                            start_live = gr.Button("Start System Audio", variant="secondary")
+                            stop_live = gr.Button("Stop System Audio", variant="stop")
+                    with gr.Row(elem_classes=["action-row"]):
+                        clear = gr.Button("Clear Screen", variant="secondary")
+                    stream_status = gr.Textbox(
+                        label="Audio Status",
+                        interactive=False,
+                        lines=2,
+                        elem_id="stream_status_box",
+                    )
+
+                with gr.Column(scale=3, min_width=280, elem_classes=["compact-panel"]):
+                    gr.Markdown("Transcript workspace", elem_classes=["section-title"])
+                    live_transcript = gr.Textbox(
+                        label="Live Transcript",
+                        lines=11,
+                        placeholder="Recorded or typed transcript appears here.",
+                        elem_id="live_transcript_box",
+                    )
+                    with gr.Row(elem_classes=["action-row"]):
+                        call_coaching = gr.Button("Call Coaching", variant="primary")
+                        coach = gr.Button("Process Text", variant="secondary")
+
+                with gr.Column(scale=2, min_width=220, elem_classes=["compact-panel"]):
+                    gr.Markdown("Coaching card", elem_classes=["section-title"])
+                    answer_card = gr.HTML(render_answer_card())
+
+        with gr.Tab("Session Log"):
+            log = gr.Textbox(label="Saved Exchanges", lines=16, interactive=False, elem_id="log_box")
+            clear_db = gr.Button("Clear SQLite Tables", variant="stop")
+
+        with gr.Tab("Evaluate"):
+            with gr.Row(elem_classes=["action-row"]):
+                evaluate = gr.Button("Evaluate Session", variant="primary")
+                load_eval_summary = gr.Button("Load SQLite Summary", variant="secondary")
+                export_eval_csv = gr.Button("Export CSV", variant="secondary")
+            evaluation_table = gr.Dataframe(
+                headers=EVALUATION_TABLE_HEADERS,
+                datatype=["str", "str", "str", "str", "str", "str", "str"],
+                label="SQLite Evaluation History",
+                interactive=False,
+                wrap=True,
+            )
+            export_file = gr.File(label="CSV Download", interactive=False)
+            report = gr.Textbox(label="Evaluation Report", lines=16, interactive=False, elem_id="report_box")
+
+    start.click(start_session, inputs=[company, role], outputs=[session_id, status])
+    if HF_SPACE_MODE:
+        transcribe_coach.click(
+            transcribe_and_coach,
+            inputs=[session_id, mic, live_transcript],
+            outputs=[live_transcript, answer_card, log, last_state],
+            queue=True,
+        )
+    else:
+        start_live.click(
+            start_backend_live_transcript,
+            outputs=[live_transcript, answer_card, stream_status, last_state, card_monitor_state],
+            queue=True,
+        )
+        stop_live.click(
+            stop_backend_live_transcript,
+            outputs=[stream_status],
+            queue=False,
+        )
+    coach.click(
+        process_typed_transcript,
+        inputs=[session_id, live_transcript],
+        outputs=[live_transcript, answer_card, log, last_state],
+        queue=True,
+    )
+    call_coaching.click(
+        call_coaching_from_transcript,
+        inputs=[live_transcript, card_monitor_state],
+        outputs=[answer_card, last_state, card_monitor_state],
+        queue=True,
+    )
+    live_transcript.change(
+        update_live_card_from_transcript,
+        inputs=[live_transcript, card_monitor_state],
+        outputs=[answer_card, last_state, card_monitor_state],
+        queue=True,
+    )
+    clear.click(
+        clear_live_state,
+        outputs=[live_transcript, answer_card, stream_state, stream_status, card_monitor_state],
+        queue=False,
+    )
+    clear_db.click(
+        clear_database,
+        outputs=[
+            session_id,
+            last_state,
+            stream_state,
+            status,
+            live_transcript,
+            answer_card,
+            log,
+            report,
+            card_monitor_state,
+        ],
+        queue=True,
+    )
+    evaluate.click(evaluate_session, inputs=[session_id, last_state], outputs=[report], queue=True)
+    load_eval_summary.click(
+        render_sqlite_evaluation_summary,
+        inputs=[session_id],
+        outputs=[report, evaluation_table],
+        queue=True,
+    )
+    export_eval_csv.click(
+        export_sqlite_evaluation_summary_csv,
+        inputs=[session_id],
+        outputs=[export_file],
+        queue=True,
+    )
+
+
+if __name__ == "__main__":
+    port = int(os.environ.get("INTERVIEW_COACH_PORT", APP_PORT))
+    demo.queue().launch(
+        css=CSS,
+        theme=gr.themes.Base(),
+        server_name=APP_HOST,
+        server_port=port,
+    )

article.md

@@ -0,0 +1,170 @@
+# Interview Coach: Real-Time, Local Interview Assistance Without Taking Over the Answer
+
+## Introduction
+
+Technical interviews are noisy, fast, and cognitively expensive. A candidate has to listen carefully, identify the actual question, choose the right structure, remember the important concepts, and answer naturally, all in a few seconds.
+
+Interview Coach is built for that exact moment. It listens to the interview audio, extracts the interviewer’s Data Science, Machine Learning, AI, or System Design question, and shows a compact coaching card with important pointers. The goal is not to generate an answer for the candidate or handhold them through the interview. The goal is to provide timely reminders so the candidate can cover the important parts of their own answer.
+
+The app also helps after the interview. It extracts question-answer pairs from noisy transcripts, stores them in SQLite, and evaluates the candidate’s answers with structured feedback. That makes it useful both as a live coaching tool and as a practice-review system.
+
+The full setup is designed to run locally on a Mac. This keeps latency low, avoids sending interview audio to a cloud service, and makes the experience feel private and responsive.
+
+## Architecture
+
+At a high level, Interview Coach has two paths: a fast live coaching path and a slower post-session evaluation path.
+
+```text
+Live audio
+  -> Speech-to-text
+  -> Fast question boundary detection
+  -> Fine-tuned topic/pattern classifier
+  -> Coaching hint generator
+  -> Floating coaching cards
+
+Full transcript
+  -> Q&A extraction
+  -> SQLite persistence
+  -> Evaluation agent
+  -> Feedback table / CSV export
+```
+
+The live path is optimized for speed. It tries to show the coaching card immediately after the interviewer asks the question, before the candidate has already started answering. The post-session path is optimized for accuracy and reflection, so it can spend more time cleaning up the transcript and evaluating the answer.
+
+## Models Used
+
+The project uses a multi-model approach. Instead of forcing one model to handle every task, each model has a focused responsibility.
+
+| Model | Approx Size | Purpose |
+| --- | ---: | --- |
+| `mlx-community/whisper-tiny` | ~39M parameters | Fast streaming transcription for live audio |
+| `mlx-community/whisper-small-mlx` | ~244M parameters | Higher-quality local transcription when needed |
+| `vadirajkrishna/interview-coach-3b` | 3B base model plus LoRA adapter | Fine-tuned topic and pattern detection |
+| `Qwen/Qwen2.5-3B-Instruct` | ~3B parameters | General reasoning, coaching hint generation, transcript cleanup, and evaluation |
+| SQLite | Local database | Session, exchange, and evaluation storage |
+
+This split is important. The fine-tuned model is used for what it is good at: quickly identifying the type and pattern of the question. The general instruction model is used when more flexible reasoning is needed, such as generating hints or extracting structured Q&A from a noisy transcript.
+
+## Fine-Tuning Approach
+
+The fine-tuned model was trained to map interview questions to a type and a set of coarse answering steps. For example:
+
+```json
+{
+  "prompt": "How would you handle class imbalance in a fraud detection model?",
+  "completion": "Type: Data Science\nSteps: Check base rate -> Choose right metric -> Handle imbalance -> Tune threshold -> Evaluate"
+}
+```
+
+This helped in two ways.
+
+First, the coaching system became more reliable at deciding whether a transcript segment was relevant. Greetings, logistics, and generic discussion should not trigger a coaching card. The fine-tuned model helps classify only meaningful DS, ML, AI, or System Design questions.
+
+Second, it gave the live system a fast topic/pattern signal. The app does not need to ask a larger model to deeply reason about the question before showing anything. It can quickly classify the question and then use that classification as context for generating better hints.
+
+The final design uses the fine-tuned 3B model for type and pattern detection, not for the final coaching bullets. The displayed hints are generated separately so they can be more specific and useful.
+
+## Challenge 1: Making the Coaching Card Appear Fast Enough
+
+The most critical product challenge was timing.
+
+If the coaching card appears after the candidate has already started answering, it is too late. The card has to appear right after the interviewer asks the question and before the candidate has committed to an answer structure.
+
+The first version used a general LLM to extract the clean question before showing the card. That was accurate, but too slow. The fix was to split the live path from the post-processing path.
+
+For the live path, the app now uses:
+
+- A recent transcript window instead of the full transcript.
+- Fast question boundary cleanup.
+- A warm-loaded fine-tuned topic/pattern model.
+- A separate coaching-hints prompt only after the question is detected.
+- Persistent floating cards so earlier coaching cards do not disappear.
+
+The live extractor intentionally does not try to produce a perfect transcript. It aims to identify the current question quickly enough to help the candidate. Accuracy cleanup happens later in `Process Text`.
+
+This tradeoff made the coaching card feel much faster and more useful during an actual interview.
+
+## Challenge 2: Extracting Questions and Answers From Noisy Conversations
+
+Live transcripts are messy. A single transcript may contain:
+
+- Interviewer greetings.
+- Candidate acknowledgements.
+- Repeated STT fragments.
+- Half-finished questions.
+- Candidate answers starting before punctuation is clear.
+- Transitions like “Good, next question”.
+- Multiple questions and answers in one block.
+
+One recurring issue was that the candidate’s answer was being included inside the question. Another issue was that the extracted answer was sometimes shortened too aggressively.
+
+The solution was to separate extraction responsibilities:
+
+- The live coaching path extracts a fast question candidate only for the card.
+- The post-session path uses a structured LLM prompt to extract all Q&A exchanges chronologically.
+- The extraction prompt explicitly says to preserve the candidate’s full answer, including definitions, reasoning, examples, caveats, and explanatory setup.
+- The answer ends only when the next interviewer question or transition begins.
+
+This makes the session log more useful. It does not just store the shortest direct answer; it stores what the candidate actually said, lightly cleaned for transcription noise.
+
+## Challenge 3: Avoiding Duplicate or Noisy Coaching Cards
+
+Another challenge was duplicate cards. Live transcription can produce slightly different versions of the same question:
+
+```text
+How does linear regression work?
+Can you briefly explain how linear regression works?
+Can you explain how linear regression works?
+```
+
+Exact string matching was not enough. The app now creates a dedupe key from the important words in the question and compares similarity between cards. That prevents repeated STT variants from creating multiple coaching cards for the same question.
+
+The app also filters out non-target topics. If the detected type is too generic or not relevant to DS, ML, AI, or System Design, the live card keeps listening instead of showing noise.
+
+## Challenge 4: Making the Evaluation Fair
+
+Evaluation had a subtle failure mode. The evaluator generated a benchmark answer so the candidate could learn, but the feedback sometimes looked like it was evaluating the benchmark rather than the candidate’s actual answer.
+
+The fix was to make the evaluator contract explicit:
+
+- The benchmark answer is only for learning.
+- The hiring band and feedback must be based only on the candidate answer.
+- Empty candidate answers should not receive credit.
+- Generic benchmark-style feedback is rejected and falls back to a local candidate-answer heuristic.
+
+This made the evaluation more faithful to what the candidate actually said.
+
+## Local-First Runtime
+
+The entire system can run locally on a Mac. That is a major part of the design.
+
+Local execution gives three practical benefits:
+
+- Privacy: interview audio and transcripts do not need to leave the machine.
+- Latency: the coaching card can appear quickly enough to be useful.
+- Control: models, prompts, and fine-tuned adapters can be swapped without changing the whole app.
+
+The local setup uses Python, Gradio, SQLite, Hugging Face Transformers, PEFT, and MLX Whisper. For system audio capture on macOS, the app can use a local audio routing setup such as BlackHole.
+
+## What Makes the Design Agentic
+
+The app is agentic because it is not a single prompt wrapped in a UI. It is a pipeline of specialized steps, each with a clear role and state handoff.
+
+The main agents and nodes are:
+
+- Audio/transcription node: converts live audio into text.
+- Question extraction logic: identifies the likely interviewer question boundary.
+- Topic/pattern agent: classifies the question using the fine-tuned model.
+- Coaching hint generator: creates short, useful pointers for the candidate.
+- Persistence layer: stores sessions, exchanges, and evaluations in SQLite.
+- Evaluation agent: reviews saved Q&A exchanges and produces structured feedback.
+
+This modular design made it easier to improve one part without breaking the rest. For example, the live coaching path could be optimized for speed while the post-session extractor stayed more careful and LLM-driven.
+
+## Conclusion
+
+Interview Coach is designed around a simple idea: candidates do not need a model to answer for them, but they can benefit from timely reminders that help them structure their own thinking.
+
+The project combines local speech-to-text, a fine-tuned 3B model, a general instruction model, SQLite persistence, and a Gradio interface into a practical interview practice system. The hardest part was not simply building a chatbot. It was making the coaching card appear at the right moment, extracting useful Q&A from noisy speech, and evaluating the candidate���s actual answer fairly.
+
+The result is a local-first tool that helps during the interview and becomes a feedback system after the interview.

config.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+import os
+
+
+BASE_DIR = Path(__file__).resolve().parent
+DB_PATH = BASE_DIR / "interviews.db"
+GENERAL_LLM_MODEL = os.environ.get("INTERVIEW_COACH_GENERAL_LLM_MODEL", "Qwen/Qwen2.5-3B-Instruct")
+MODEL_PATH = GENERAL_LLM_MODEL
+EVALUATION_MODEL_PATH = GENERAL_LLM_MODEL
+WHISPER_MODEL = "mlx-community/whisper-small-mlx"
+STREAMING_WHISPER_MODEL = "mlx-community/whisper-tiny"
+HF_SPACE_MODE = bool(os.environ.get("SPACE_ID")) or os.environ.get("INTERVIEW_COACH_RUNTIME") == "space"
+STT_BACKEND = os.environ.get("INTERVIEW_COACH_STT_BACKEND", "transformers" if HF_SPACE_MODE else "mlx")
+HF_WHISPER_MODEL = os.environ.get("INTERVIEW_COACH_HF_WHISPER_MODEL", "openai/whisper-tiny")
+APP_HOST = os.environ.get("INTERVIEW_COACH_HOST", "0.0.0.0" if HF_SPACE_MODE else "127.0.0.1")
+APP_PORT = 7860
+TOPIC_PATTERN_MODEL = os.environ.get("INTERVIEW_COACH_TOPIC_PATTERN_MODEL", "vadirajkrishna/interview-coach-3b")
+TOPIC_PATTERN_BASE_MODEL = os.environ.get("INTERVIEW_COACH_TOPIC_PATTERN_BASE_MODEL", GENERAL_LLM_MODEL)
+USE_TOPIC_PATTERN_MODEL = os.environ.get("INTERVIEW_COACH_USE_TOPIC_PATTERN_MODEL", "1").strip().lower() not in {
+    "0",
+    "false",
+    "no",
+}

data/train.jsonl

@@ -0,0 +1 @@
+

db/__init__.py

@@ -0,0 +1 @@
+

db/queries.py

@@ -0,0 +1,212 @@
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+import aiosqlite
+
+from config import DB_PATH
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+async def create_session(
+    company: str = "",
+    role: str = "",
+    duration: int = 0,
+    db_path=DB_PATH,
+) -> int:
+    async with aiosqlite.connect(db_path) as db:
+        cursor = await db.execute(
+            "INSERT INTO sessions (date, company, role, duration) VALUES (?, ?, ?, ?)",
+            (utc_now(), company, role, duration),
+        )
+        await db.commit()
+        return int(cursor.lastrowid)
+
+
+async def add_exchange(
+    session_id: int,
+    question: str,
+    answer: str,
+    framework_used: str,
+    db_path=DB_PATH,
+) -> int:
+    async with aiosqlite.connect(db_path) as db:
+        cursor = await db.execute(
+            """
+            INSERT INTO exchanges (session_id, question, answer, framework_used, timestamp)
+            VALUES (?, ?, ?, ?, ?)
+            """,
+            (session_id, question, answer, framework_used, utc_now()),
+        )
+        await db.execute(
+            """
+            INSERT INTO patterns (framework, times_shown)
+            VALUES (?, 1)
+            ON CONFLICT(framework) DO UPDATE SET times_shown = times_shown + 1
+            """,
+            (framework_used,),
+        )
+        await db.commit()
+        return int(cursor.lastrowid)
+
+
+async def add_transcript(
+    session_id: int,
+    raw_text: str,
+    labelled: dict[str, Any],
+    db_path=DB_PATH,
+) -> int:
+    async with aiosqlite.connect(db_path) as db:
+        cursor = await db.execute(
+            "INSERT INTO transcripts (session_id, raw_text, labelled_json) VALUES (?, ?, ?)",
+            (session_id, raw_text, json.dumps(labelled)),
+        )
+        await db.commit()
+        return int(cursor.lastrowid)
+
+
+async def add_evaluation(
+    exchange_id: int,
+    steps_covered: list[bool],
+    score: int,
+    feedback: str,
+    db_path=DB_PATH,
+) -> int:
+    async with aiosqlite.connect(db_path) as db:
+        cursor = await db.execute(
+            """
+            INSERT INTO evaluations (exchange_id, steps_covered_json, score, feedback)
+            VALUES (?, ?, ?, ?)
+            """,
+            (exchange_id, json.dumps(steps_covered), score, feedback),
+        )
+        await db.commit()
+        return int(cursor.lastrowid)
+
+
+async def update_exchange_answer(exchange_id: int, answer: str, db_path=DB_PATH) -> None:
+    async with aiosqlite.connect(db_path) as db:
+        await db.execute(
+            "UPDATE exchanges SET answer = ? WHERE id = ?",
+            (answer, exchange_id),
+        )
+        await db.commit()
+
+
+async def append_exchange_answer(exchange_id: int, addition: str, db_path=DB_PATH) -> None:
+    async with aiosqlite.connect(db_path) as db:
+        cursor = await db.execute(
+            "SELECT answer FROM exchanges WHERE id = ?",
+            (exchange_id,),
+        )
+        row = await cursor.fetchone()
+        existing = row[0] if row else ""
+        updated = f"{existing.strip()}\n{addition.strip()}".strip()
+        await db.execute(
+            "UPDATE exchanges SET answer = ? WHERE id = ?",
+            (updated, exchange_id),
+        )
+        await db.commit()
+
+
+async def clear_all_tables(db_path=DB_PATH) -> None:
+    async with aiosqlite.connect(db_path) as db:
+        await db.executescript(
+            """
+            DELETE FROM evaluations;
+            DELETE FROM exchanges;
+            DELETE FROM transcripts;
+            DELETE FROM patterns;
+            DELETE FROM sessions;
+            DELETE FROM sqlite_sequence
+            WHERE name IN ('evaluations', 'exchanges', 'transcripts', 'sessions');
+            """
+        )
+        await db.commit()
+
+
+async def list_exchanges(session_id: int, db_path=DB_PATH) -> list[dict[str, Any]]:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cursor = await db.execute(
+            """
+            SELECT id, session_id, question, answer, framework_used, timestamp
+            FROM exchanges
+            WHERE session_id = ?
+            ORDER BY id
+            """,
+            (session_id,),
+        )
+        rows = await cursor.fetchall()
+        return [dict(row) for row in rows]
+
+
+async def list_evaluations(session_id: int, db_path=DB_PATH) -> list[dict[str, Any]]:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cursor = await db.execute(
+            """
+            SELECT
+                evaluations.id,
+                evaluations.exchange_id,
+                exchanges.session_id,
+                sessions.date,
+                sessions.company,
+                sessions.role,
+                exchanges.question,
+                exchanges.answer,
+                exchanges.framework_used,
+                evaluations.steps_covered_json,
+                evaluations.score,
+                evaluations.feedback
+            FROM evaluations
+            JOIN exchanges ON evaluations.exchange_id = exchanges.id
+            JOIN sessions ON exchanges.session_id = sessions.id
+            WHERE exchanges.session_id = ?
+            ORDER BY evaluations.id
+            """,
+            (session_id,),
+        )
+        rows = await cursor.fetchall()
+        results = []
+        for row in rows:
+            item = dict(row)
+            item["steps_covered"] = json.loads(item.pop("steps_covered_json"))
+            results.append(item)
+        return results
+
+
+async def list_all_evaluations(db_path=DB_PATH) -> list[dict[str, Any]]:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cursor = await db.execute(
+            """
+            SELECT
+                evaluations.id,
+                evaluations.exchange_id,
+                exchanges.session_id,
+                sessions.date,
+                sessions.company,
+                sessions.role,
+                exchanges.question,
+                exchanges.answer,
+                exchanges.framework_used,
+                evaluations.steps_covered_json,
+                evaluations.score,
+                evaluations.feedback
+            FROM evaluations
+            JOIN exchanges ON evaluations.exchange_id = exchanges.id
+            JOIN sessions ON exchanges.session_id = sessions.id
+            ORDER BY sessions.id DESC, evaluations.id DESC
+            """
+        )
+        rows = await cursor.fetchall()
+        results = []
+        for row in rows:
+            item = dict(row)
+            item["steps_covered"] = json.loads(item.pop("steps_covered_json"))
+            results.append(item)
+        return results

db/schema.py

@@ -0,0 +1,55 @@
+import aiosqlite
+
+from config import DB_PATH
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS sessions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    date TEXT NOT NULL,
+    company TEXT,
+    role TEXT,
+    duration INTEGER DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS exchanges (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id INTEGER NOT NULL,
+    question TEXT NOT NULL,
+    answer TEXT DEFAULT '',
+    framework_used TEXT NOT NULL,
+    timestamp TEXT NOT NULL,
+    FOREIGN KEY (session_id) REFERENCES sessions(id)
+);
+
+CREATE TABLE IF NOT EXISTS evaluations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    exchange_id INTEGER NOT NULL,
+    steps_covered_json TEXT NOT NULL,
+    score INTEGER NOT NULL,
+    feedback TEXT NOT NULL,
+    FOREIGN KEY (exchange_id) REFERENCES exchanges(id)
+);
+
+CREATE TABLE IF NOT EXISTS transcripts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id INTEGER NOT NULL,
+    raw_text TEXT NOT NULL,
+    labelled_json TEXT NOT NULL,
+    FOREIGN KEY (session_id) REFERENCES sessions(id)
+);
+
+CREATE TABLE IF NOT EXISTS patterns (
+    framework TEXT PRIMARY KEY,
+    times_shown INTEGER NOT NULL DEFAULT 0,
+    avg_score REAL NOT NULL DEFAULT 0,
+    most_missed_step TEXT DEFAULT ''
+);
+"""
+
+
+async def init_db(db_path=DB_PATH) -> None:
+    async with aiosqlite.connect(db_path) as db:
+        await db.executescript(SCHEMA)
+        await db.commit()
+

fine-tune/data/train.json

@@ -0,0 +1,170 @@
+[
+    {
+        "prompt": "How would you design a URL shortener like bit.ly?",
+        "completion": "Type: System Design\nSteps: Clarify scale → High-level components → Deep dive → Bottlenecks → Tradeoffs"
+    },
+    {
+        "prompt": "Design a rate limiter for a public API.",
+        "completion": "Type: System Design\nSteps: Clarify scale → High-level components → Deep dive → Bottlenecks → Tradeoffs"
+    },
+    {
+        "prompt": "How would you architect a notification system for a banking app?",
+        "completion": "Type: System Design\nSteps: Clarify scale → High-level components → Deep dive → Bottlenecks → Tradeoffs"
+    },
+    {
+        "prompt": "Design a distributed cache like Redis.",
+        "completion": "Type: System Design\nSteps: Clarify scale → High-level components → Deep dive → Bottlenecks → Tradeoffs"
+    },
+    {
+        "prompt": "How would you build a real-time leaderboard for a gaming platform?",
+        "completion": "Type: System Design\nSteps: Clarify scale → High-level components → Deep dive → Bottlenecks → Tradeoffs"
+    },
+    {
+        "prompt": "Design a search autocomplete system.",
+        "completion": "Type: System Design\nSteps: Clarify scale → High-level components → Deep dive → Bottlenecks → Tradeoffs"
+    },
+    {
+        "prompt": "How would you design a ride-sharing service like Uber?",
+        "completion": "Type: System Design\nSteps: Clarify scale → High-level components → Deep dive → Bottlenecks → Tradeoffs"
+    },
+    {
+        "prompt": "How would you design Spotify for rural areas with poor connectivity?",
+        "completion": "Type: Product Design\nSteps: Clarify scope → Identify users → Map pain points → Propose solution → Define metrics"
+    },
+    {
+        "prompt": "How would you improve the onboarding experience for a fintech app?",
+        "completion": "Type: Product Design\nSteps: Clarify scope → Identify users → Map pain points → Propose solution → Define metrics"
+    },
+    {
+        "prompt": "Design a feature to help elderly users navigate a mobile banking app.",
+        "completion": "Type: Product Design\nSteps: Clarify scope → Identify users → Map pain points → Propose solution → Define metrics"
+    },
+    {
+        "prompt": "How would you design YouTube for blind users?",
+        "completion": "Type: Product Design\nSteps: Clarify scope → Identify users → Map pain points → Propose solution → Define metrics"
+    },
+    {
+        "prompt": "How would you redesign the checkout flow for an e-commerce app?",
+        "completion": "Type: Product Design\nSteps: Clarify scope → Identify users → Map pain points → Propose solution → Define metrics"
+    },
+    {
+        "prompt": "Design a feature to reduce churn in a subscription app.",
+        "completion": "Type: Product Design\nSteps: Clarify scope → Identify users → Map pain points → Propose solution → Define metrics"
+    },
+    {
+        "prompt": "How would you design Airbnb for pets?",
+        "completion": "Type: Product Design\nSteps: Clarify scope → Identify users → Map pain points → Propose solution → Define metrics"
+    },
+    {
+        "prompt": "How would you handle class imbalance in a fraud detection model?",
+        "completion": "Type: Data Science\nSteps: Check base rate → Choose right metric → Handle imbalance → Tune threshold → Evaluate"
+    },
+    {
+        "prompt": "How would you detect anomalies in a time series dataset?",
+        "completion": "Type: Data Science\nSteps: Define anomaly → Explore data → Choose method → Evaluate → Production concerns"
+    },
+    {
+        "prompt": "Walk me through building a churn prediction model.",
+        "completion": "Type: Data Science\nSteps: Define churn → Feature engineering → Baseline model → Iterate → Deploy"
+    },
+    {
+        "prompt": "How would you evaluate a recommender system?",
+        "completion": "Type: Data Science\nSteps: Define metric → Offline eval → A/B test → Business impact → Monitor"
+    },
+    {
+        "prompt": "How would you approach a dataset with 40% missing values?",
+        "completion": "Type: Data Science\nSteps: Understand missingness → Explore patterns → Imputation strategy → Validate → Document"
+    },
+    {
+        "prompt": "How would you build a model to predict customer lifetime value?",
+        "completion": "Type: Data Science\nSteps: Define CLV → Feature engineering → Baseline model → Iterate → Deploy"
+    },
+    {
+        "prompt": "How would you select features for a high-dimensional dataset?",
+        "completion": "Type: Data Science\nSteps: Understand data → Correlation analysis → Feature importance → Dimensionality reduction → Validate"
+    },
+    {
+        "prompt": "How would you build a RAG pipeline for a customer support chatbot?",
+        "completion": "Type: AI Engineering\nSteps: Define retrieval scope → Chunking strategy → Embedding model → Retrieval + rerank → Evaluate"
+    },
+    {
+        "prompt": "How would you reduce hallucinations in an LLM-based application?",
+        "completion": "Type: AI Engineering\nSteps: Identify sources → Grounding strategy → Prompt engineering → Evaluation → Monitoring"
+    },
+    {
+        "prompt": "How would you fine-tune an LLM for a specific domain?",
+        "completion": "Type: AI Engineering\nSteps: Define task → Curate data → Choose method → Train → Evaluate → Deploy"
+    },
+    {
+        "prompt": "How would you evaluate the quality of a RAG system?",
+        "completion": "Type: AI Engineering\nSteps: Define metrics → Retrieval eval → Generation eval → End-to-end eval → Monitor drift"
+    },
+    {
+        "prompt": "How would you deploy an LLM with sub-100ms latency requirements?",
+        "completion": "Type: AI Engineering\nSteps: Clarify latency budget → Quantisation → Runtime choice → Caching → Load test"
+    },
+    {
+        "prompt": "How would you implement guardrails for an LLM in production?",
+        "completion": "Type: AI Engineering\nSteps: Define risks → Input filtering → Output validation → Monitoring → Escalation"
+    },
+    {
+        "prompt": "How would you handle prompt injection attacks in an LLM app?",
+        "completion": "Type: AI Engineering\nSteps: Define threat model → Input sanitisation → Prompt hardening → Detection → Response"
+    },
+    {
+        "prompt": "Tell me about a time you disagreed with your manager.",
+        "completion": "Type: Behavioural\nSteps: Situation → Task → Action → Result → Reflection"
+    },
+    {
+        "prompt": "Give me an example of when you had to deliver under a tight deadline.",
+        "completion": "Type: Behavioural\nSteps: Situation → Task → Action → Result → Reflection"
+    },
+    {
+        "prompt": "Describe a time you failed and what you learned from it.",
+        "completion": "Type: Behavioural\nSteps: Situation → Task → Action → Result → Reflection"
+    },
+    {
+        "prompt": "Tell me about a time you had to influence without authority.",
+        "completion": "Type: Behavioural\nSteps: Situation → Task → Action → Result → Reflection"
+    },
+    {
+        "prompt": "Give an example of a time you handled ambiguity well.",
+        "completion": "Type: Behavioural\nSteps: Situation → Task → Action → Result → Reflection"
+    },
+    {
+        "prompt": "Tell me about a time you took ownership of a failing project.",
+        "completion": "Type: Behavioural\nSteps: Situation → Task → Action → Result → Reflection"
+    },
+    {
+        "prompt": "Describe a situation where you had to learn something quickly.",
+        "completion": "Type: Behavioural\nSteps: Situation → Task → Action → Result → Reflection"
+    },
+    {
+        "prompt": "How many piano tuners are there in London?",
+        "completion": "Type: Estimation\nSteps: Clarify → Decompose → Anchor number → Calculate → Sanity check"
+    },
+    {
+        "prompt": "How many WhatsApp messages are sent per day globally?",
+        "completion": "Type: Estimation\nSteps: Clarify → Decompose → Anchor number → Calculate → Sanity check"
+    },
+    {
+        "prompt": "Estimate the storage required for all photos on Instagram.",
+        "completion": "Type: Estimation\nSteps: Clarify → Decompose → Anchor number → Calculate → Sanity check"
+    },
+    {
+        "prompt": "How many Ubers are active in London at 9am on a Monday?",
+        "completion": "Type: Estimation\nSteps: Clarify → Decompose → Anchor number → Calculate → Sanity check"
+    },
+    {
+        "prompt": "How much revenue does a McDonald's in central London make per year?",
+        "completion": "Type: Estimation\nSteps: Clarify → Decompose → Anchor number → Calculate → Sanity check"
+    },
+    {
+        "prompt": "How many golf balls fit in a Boeing 747?",
+        "completion": "Type: Estimation\nSteps: Clarify → Decompose → Anchor number → Calculate → Sanity check"
+    },
+    {
+        "prompt": "Estimate the number of software developers in the world.",
+        "completion": "Type: Estimation\nSteps: Clarify → Decompose → Anchor number → Calculate → Sanity check"
+    }
+]

fine-tune/data/valid.json

@@ -0,0 +1,26 @@
+[
+    {
+        "prompt": "Design a Twitter trending topics feature.",
+        "completion": "Type: System Design\nSteps: Clarify scale → High-level components → Deep dive → Bottlenecks → Tradeoffs"
+    },
+    {
+        "prompt": "How would you design a food delivery app for hospitals?",
+        "completion": "Type: Product Design\nSteps: Clarify scope → Identify users → Map pain points → Propose solution → Define metrics"
+    },
+    {
+        "prompt": "How would you build a model to detect fake reviews?",
+        "completion": "Type: Data Science\nSteps: Check base rate → Choose right metric → Handle imbalance → Tune threshold → Evaluate"
+    },
+    {
+        "prompt": "How would you version and monitor ML models in production?",
+        "completion": "Type: AI Engineering\nSteps: Define metrics → Retrieval eval → Generation eval → End-to-end eval → Monitor drift"
+    },
+    {
+        "prompt": "Tell me about a time you had to change your approach mid-project.",
+        "completion": "Type: Behavioural\nSteps: Situation → Task → Action → Result → Reflection"
+    },
+    {
+        "prompt": "How many coffee cups are sold in London every day?",
+        "completion": "Type: Estimation\nSteps: Clarify → Decompose → Anchor number → Calculate → Sanity check"
+    }
+]

fine-tune/lora-finetune.py

@@ -0,0 +1,353 @@
+"""
+InterviewCoach — Fine-tuning with Unsloth on Modal
+Trains Qwen2.5-3B-Instruct for interview question classification using LoRA.
+
+## Objective
+The base Qwen2.5-3B model is capable but general-purpose. This fine-tune
+teaches it one narrow task: given a raw interview question, output the correct
+framework type and ordered coaching steps — nothing else.
+
+Without fine-tuning, a 3B model needs a long system prompt with many few-shot
+examples to produce consistent output, and still occasionally adds waffle or
+gets the format wrong. After fine-tuning on ~80 domain-specific examples, the
+model learns to:
+  1. Classify questions reliably into 6 types (System Design, Product Design,
+     Data Science, AI Engineering, Behavioural, Estimation)
+  2. Return a clean, consistently formatted coaching card every time
+  3. Do this faster and with less memory than the 7B model it replaces
+
+The result is a lightweight 3B model that matches 7B quality on this specific
+task — suitable for real-time inference on a local Mac during a live interview.
+
+## Usage
+    modal run finetune_unsloth_modal.py
+
+## Optional CLI flags
+    modal run finetune_unsloth_modal.py --max-steps 300
+    modal run finetune_unsloth_modal.py --lora-r 16
+"""
+
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import modal
+
+# ===========================================================================
+# Configurations
+# ===========================================================================
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+
+# Your Hugging Face username (https://huggingface.co/settings/profile)
+HF_USERNAME = "vadirajkrishna"
+
+# Name for the fine-tuned model repo on Hugging Face
+HF_MODEL_NAME = "interview-coach-3b"
+
+# Base model to fine-tune (from Unsloth's HF collection)
+BASE_MODEL = "unsloth/Qwen2.5-3B-Instruct"
+
+# Path to training data files (relative to this script)
+TRAIN_DATA_FILE = "data/train.json"
+VALID_DATA_FILE = "data/valid.json"
+
+# Modal secret name containing HF_TOKEN
+# Create at: https://modal.com/secrets  key=HF_TOKEN
+MODAL_HF_SECRET = "huggingface-secret"
+
+# Modal GPU — A10G is cost-effective for 3B models (~$1.10/hr, job ~10 min)
+# Options: "A10G", "A100", "L40S"
+MODAL_GPU = "A10G"
+
+# ===========================================================================
+# LoRA hyperparameters — safe defaults for a small classification dataset
+# ===========================================================================
+
+LORA_R              = 8       # LoRA rank — increase to 16 for harder tasks
+LORA_ALPHA          = 16      # scaling factor, usually 2x rank
+LORA_DROPOUT        = 0.05
+MAX_SEQ_LENGTH      = 256     # interview questions are short
+MAX_STEPS           = 200     # small dataset — 200 is enough, increase if loss plateaus
+BATCH_SIZE          = 4
+GRAD_ACCUM_STEPS    = 2
+LEARNING_RATE       = 2e-4
+WARMUP_RATIO        = 0.1
+SEED                = 42
+
+# LoRA target modules — all projection layers in Qwen2.5
+LORA_TARGET_MODULES = [
+    "q_proj", "k_proj", "v_proj", "o_proj",
+    "gate_proj", "up_proj", "down_proj",
+]
+
+# ===========================================================================
+# Validation — fail loudly before Modal even starts
+# ===========================================================================
+
+def _validate_config():
+    errors = []
+    if not HF_USERNAME:
+        errors.append("  • HF_USERNAME is empty — set your Hugging Face username")
+    if not HF_MODEL_NAME:
+        errors.append("  • HF_MODEL_NAME is empty — set a repo name")
+    if not (SCRIPT_DIR / TRAIN_DATA_FILE).exists():
+        errors.append(f"  • TRAIN_DATA_FILE not found: {TRAIN_DATA_FILE}")
+    if not (SCRIPT_DIR / VALID_DATA_FILE).exists():
+        errors.append(f"  • VALID_DATA_FILE not found: {VALID_DATA_FILE}")
+    if errors:
+        print("\n❌  Config errors — fix before running:\n")
+        for e in errors:
+            print(e)
+        sys.exit(1)
+
+# ===========================================================================
+# Modal infrastructure
+# ===========================================================================
+
+app = modal.App("interview-coach-finetune")
+
+image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .uv_pip_install(
+        "accelerate==1.9.0",
+        "datasets==3.6.0",
+        "hf-transfer==0.1.9",
+        "huggingface_hub==0.34.2",
+        "peft==0.16.0",
+        "transformers==4.54.0",
+        "trl==0.19.1",
+        "unsloth[cu128-torch270]==2025.7.8",
+        "unsloth_zoo==2025.7.10",
+    )
+    .env({"HF_HOME": "/model_cache"})
+)
+
+with image.imports():
+    import unsloth  # noqa: F401 — must be first
+    import torch
+    from datasets import Dataset
+    from transformers import TrainingArguments
+    from trl import SFTTrainer
+    from unsloth import FastLanguageModel
+
+model_cache_vol = modal.Volume.from_name("ic-model-cache", create_if_missing=True)
+checkpoint_vol  = modal.Volume.from_name("ic-checkpoints", create_if_missing=True)
+
+# ===========================================================================
+# Training config dataclass — populated from constants above
+# ===========================================================================
+
+@dataclass
+class TrainingConfig:
+    hf_repo:                  str
+    model_name:               str
+    max_seq_length:           int
+    lora_r:                   int
+    lora_alpha:               int
+    lora_dropout:             float
+    learning_rate:            float
+    batch_size:               int
+    gradient_accumulation_steps: int
+    max_steps:                int
+    warmup_ratio:             float
+    seed:                     int
+    train_data:               list
+    valid_data:               list
+
+
+def _build_config(
+    max_steps: int = MAX_STEPS,
+    lora_r: int    = LORA_R,
+) -> TrainingConfig:
+    """Load data files and assemble config. Call only after _validate_config()."""
+    train_data = json.loads((SCRIPT_DIR / TRAIN_DATA_FILE).read_text())
+    valid_data = json.loads((SCRIPT_DIR / VALID_DATA_FILE).read_text())
+    return TrainingConfig(
+        hf_repo                    = f"{HF_USERNAME}/{HF_MODEL_NAME}",
+        model_name                 = BASE_MODEL,
+        max_seq_length             = MAX_SEQ_LENGTH,
+        lora_r                     = lora_r,
+        lora_alpha                 = LORA_ALPHA,
+        lora_dropout               = LORA_DROPOUT,
+        learning_rate              = LEARNING_RATE,
+        batch_size                 = BATCH_SIZE,
+        gradient_accumulation_steps= GRAD_ACCUM_STEPS,
+        max_steps                  = max_steps,
+        warmup_ratio               = WARMUP_RATIO,
+        seed                       = SEED,
+        train_data                 = train_data,
+        valid_data                 = valid_data,
+    )
+
+# ===========================================================================
+# Fine-tuning function — runs on Modal GPU
+# ===========================================================================
+
+@app.function(
+    image=image,
+    gpu=MODAL_GPU,
+    volumes={
+        "/model_cache": model_cache_vol,
+        "/checkpoints": checkpoint_vol,
+    },
+    secrets=[modal.Secret.from_name(MODAL_HF_SECRET)],
+    timeout=3600,
+)
+def finetune(config: TrainingConfig):
+    import os
+    from huggingface_hub import login
+
+    login(token=os.environ["HF_TOKEN"])
+
+    print(f"Model:     {config.model_name}")
+    print(f"HF repo:   {config.hf_repo}")
+    print(f"Steps:     {config.max_steps}")
+    print(f"LoRA rank: {config.lora_r}")
+    print(f"Train:     {len(config.train_data)} examples")
+    print(f"Valid:     {len(config.valid_data)} examples")
+
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name     = config.model_name,
+        max_seq_length = config.max_seq_length,
+        dtype          = None,
+        load_in_4bit   = True,
+    )
+
+    model = FastLanguageModel.get_peft_model(
+        model,
+        r                        = config.lora_r,
+        target_modules           = LORA_TARGET_MODULES,
+        lora_alpha               = config.lora_alpha,
+        lora_dropout             = config.lora_dropout,
+        bias                     = "none",
+        use_gradient_checkpointing = "unsloth",
+        random_state             = config.seed,
+        use_rslora               = False,
+    )
+    model.print_trainable_parameters()
+
+    def format_example(example):
+        return {
+            "text": (
+                f"<|im_start|>user\n{example['prompt']}<|im_end|>\n"
+                f"<|im_start|>assistant\n{example['completion']}<|im_end|>"
+            )
+        }
+
+    train_dataset = Dataset.from_list(config.train_data).map(format_example)
+    valid_dataset = Dataset.from_list(config.valid_data).map(format_example)
+
+    training_args = TrainingArguments(
+        output_dir                  = "/checkpoints/interview-coach",
+        per_device_train_batch_size = config.batch_size,
+        gradient_accumulation_steps = config.gradient_accumulation_steps,
+        learning_rate               = config.learning_rate,
+        max_steps                   = config.max_steps,
+        warmup_ratio                = config.warmup_ratio,
+        fp16                        = not torch.cuda.is_bf16_supported(),
+        bf16                        = torch.cuda.is_bf16_supported(),
+        optim                       = "adamw_8bit",
+        lr_scheduler_type           = "cosine",
+        weight_decay                = 0.01,
+        logging_steps               = 10,
+        eval_strategy               = "steps",
+        eval_steps                  = 50,
+        save_strategy               = "steps",
+        save_steps                  = 100,
+        load_best_model_at_end      = True,
+        report_to                   = "none",
+        seed                        = config.seed,
+    )
+
+    trainer = SFTTrainer(
+        model              = model,
+        tokenizer          = tokenizer,
+        train_dataset      = train_dataset,
+        eval_dataset       = valid_dataset,
+        dataset_text_field = "text",
+        max_seq_length     = config.max_seq_length,
+        args               = training_args,
+    )
+
+    print("Training...")
+    trainer.train()
+    print("Training complete.")
+
+    print(f"Pushing to {config.hf_repo}...")
+    model.push_to_hub(config.hf_repo)
+    tokenizer.push_to_hub(config.hf_repo)
+    print(f"Done → https://huggingface.co/{config.hf_repo}")
+
+    return config.hf_repo
+
+
+# ===========================================================================
+# Test function — run after training to verify model output
+# ===========================================================================
+
+@app.function(
+    image=image,
+    gpu=MODAL_GPU,
+    volumes={"/model_cache": model_cache_vol},
+    secrets=[modal.Secret.from_name(MODAL_HF_SECRET)],
+    timeout=600,
+)
+def test(
+    question: str = "How would you design a payment system for a marketplace?",
+):
+    import os
+    from huggingface_hub import login
+
+    login(token=os.environ["HF_TOKEN"])
+
+    hf_repo = f"{HF_USERNAME}/{HF_MODEL_NAME}"
+    print(f"Loading {hf_repo}...")
+
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name     = hf_repo,
+        max_seq_length = MAX_SEQ_LENGTH,
+        dtype          = None,
+        load_in_4bit   = True,
+    )
+    FastLanguageModel.for_inference(model)
+
+    prompt  = f"<|im_start|>user\n{question}<|im_end|>\n<|im_start|>assistant\n"
+    inputs  = tokenizer(prompt, return_tensors="pt").to(model.device)
+
+    with torch.no_grad():
+        outputs = model.generate(
+            **inputs,
+            max_new_tokens = 80,
+            temperature    = 0.1,
+            do_sample      = False,
+        )
+
+    full  = tokenizer.decode(outputs[0], skip_special_tokens=True)
+    reply = full.split("<|im_start|>assistant\n")[-1].strip()
+    print(f"\nQ: {question}\n\n{reply}")
+
+
+# ===========================================================================
+# Entry point
+# ===========================================================================
+
+@app.local_entrypoint()
+def main(
+    max_steps: int = MAX_STEPS,
+    lora_r:    int = LORA_R,
+):
+    _validate_config()
+    config = _build_config(max_steps=max_steps, lora_r=lora_r)
+
+    print("\n🚀  InterviewCoach fine-tuning")
+    print(f"   Model:     {config.model_name}")
+    print(f"   HF repo:   {config.hf_repo}")
+    print(f"   Steps:     {config.max_steps}")
+    print(f"   LoRA rank: {config.lora_r}")
+    print(f"   Train:     {len(config.train_data)} examples")
+    print(f"   Valid:     {len(config.valid_data)} examples\n")
+
+    repo = finetune.remote(config)
+    print(f"\n✅  Done → https://huggingface.co/{repo}")

frameworks.yaml

@@ -0,0 +1,43 @@
+General:
+  color: "#64748b"
+  steps:
+    - Clarify the question if needed
+    - State a concise answer
+    - Add one concrete example
+    - Close with impact or tradeoff
+Behavioral:
+  color: "#0ea5e9"
+  steps:
+    - Situation
+    - Task
+    - Action
+    - Result
+Technical:
+  color: "#22c55e"
+  steps:
+    - Restate constraints
+    - Outline the approach
+    - Discuss complexity or tradeoffs
+    - Validate with edge cases
+System Design:
+  color: "#f59e0b"
+  steps:
+    - Requirements
+    - APIs and data model
+    - Architecture
+    - Bottlenecks and tradeoffs
+Product Sense:
+  color: "#ec4899"
+  steps:
+    - User and goal
+    - Pain points
+    - Prioritized solution
+    - Success metrics
+Case:
+  color: "#a855f7"
+  steps:
+    - Clarify objective
+    - Structure the problem
+    - Estimate or analyze
+    - Recommend next step
+

graph.py

@@ -0,0 +1,78 @@
+from langgraph.graph import END, StateGraph
+
+from agents.topic_pattern import TopicPatternAgent
+from db.queries import add_exchange, add_transcript
+from nodes.audio import audio_node
+from nodes.framework import framework_node
+from nodes.transcript import transcript_node
+from state import CoachState
+
+
+topic_pattern_agent = TopicPatternAgent()
+
+
+async def topic_pattern_node(state: CoachState) -> CoachState:
+    if state.get("framework") and state.get("steps"):
+        return state
+
+    question = state.get("question", "")
+    result = await topic_pattern_agent.analyze(question)
+    if not result:
+        return state
+
+    state["framework"] = result["type"]
+    state["pattern"] = result.get("pattern", result["type"])
+    state["steps"] = result["steps"]
+    state["confidence"] = max(float(state.get("confidence", 0.0)), float(result["confidence"]))
+    state["topic_model_used"] = result.get("model", "")
+    state["needs_review"] = state.get("needs_review", False) and result["confidence"] < 0.6
+    return state
+
+
+async def persistence_node(state: CoachState) -> CoachState:
+    session_id = state.get("session_id")
+    if not session_id:
+        return state
+
+    await add_transcript(
+        session_id=session_id,
+        raw_text=state.get("raw_text", ""),
+        labelled=state.get("labelled_json", {}),
+    )
+    if state.get("question"):
+        exchange_id = await add_exchange(
+            session_id=session_id,
+            question=state["question"],
+            answer=state.get("answer", ""),
+            framework_used=state.get("framework", "General"),
+        )
+        state["exchange_id"] = exchange_id
+    return state
+
+
+def should_classify(state: CoachState) -> str:
+    return "topic_pattern" if state.get("question") else "persist"
+
+
+def build_graph():
+    builder = StateGraph(CoachState)
+    builder.add_node("audio", audio_node)
+    builder.add_node("transcript", transcript_node)
+    builder.add_node("topic_pattern", topic_pattern_node)
+    builder.add_node("framework", framework_node)
+    builder.add_node("persist", persistence_node)
+
+    builder.set_entry_point("audio")
+    builder.add_edge("audio", "transcript")
+    builder.add_conditional_edges(
+        "transcript",
+        should_classify,
+        {"topic_pattern": "topic_pattern", "persist": "persist"},
+    )
+    builder.add_edge("topic_pattern", "framework")
+    builder.add_edge("framework", "persist")
+    builder.add_edge("persist", END)
+    return builder.compile()
+
+
+coach_graph = build_graph()

nodes/__init__.py

@@ -0,0 +1 @@
+

nodes/audio.py

@@ -0,0 +1,329 @@
+import asyncio
+import os
+import shutil
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+import numpy as np
+
+from config import BASE_DIR, HF_WHISPER_MODEL, STT_BACKEND, WHISPER_MODEL
+from state import CoachState
+
+SAMPLE_RATE = 16000
+CHUNK_SECONDS = 3
+OVERLAP_SECONDS = 0.5
+CHUNK_SAMPLES = int(CHUNK_SECONDS * SAMPLE_RATE)
+OVERLAP_SAMPLES = int(OVERLAP_SECONDS * SAMPLE_RATE)
+QUEUE_MAX_SIZE = 10
+SILENCE_RMS_THRESHOLD = 0.003
+
+executor = ThreadPoolExecutor(max_workers=2)
+_asr_pipeline = None
+
+
+async def audio_node(state: CoachState) -> CoachState:
+    if "audio_queue" not in state:
+        state["audio_queue"] = asyncio.Queue(maxsize=QUEUE_MAX_SIZE)
+    return state
+
+
+async def enqueue_audio(audio_queue: asyncio.Queue, chunk: Any) -> None:
+    await audio_queue.put(chunk)
+
+
+def get_input_device() -> int | None:
+    try:
+        import sounddevice as sd
+
+        devices = sd.query_devices()
+    except Exception:
+        return None
+
+    for index, device in enumerate(devices):
+        name = str(device.get("name", ""))
+        max_inputs = int(device.get("max_input_channels", 0))
+        if "BlackHole" in name and max_inputs > 0:
+            return index
+    return None
+
+
+class LiveAudioTranscriber:
+    def __init__(self, model: str = WHISPER_MODEL):
+        self.model = model
+        self.audio_queue: asyncio.Queue[np.ndarray] = asyncio.Queue(maxsize=QUEUE_MAX_SIZE)
+        self.stop_event = asyncio.Event()
+        self.capture_task: asyncio.Task | None = None
+
+    async def start(self) -> None:
+        if self.capture_task and not self.capture_task.done():
+            await self.stop()
+        self.stop_event = asyncio.Event()
+        self.audio_queue = asyncio.Queue(maxsize=QUEUE_MAX_SIZE)
+        device_index = get_input_device()
+        self.capture_task = asyncio.create_task(
+            capture_audio(
+                audio_queue=self.audio_queue,
+                stop_event=self.stop_event,
+                device_index=device_index,
+            )
+        )
+
+    async def stop(self) -> None:
+        self.stop_event.set()
+        if self.capture_task:
+            await self.capture_task
+            self.capture_task = None
+
+    async def transcript_stream(self):
+        transcript = ""
+        while not self.stop_event.is_set():
+            try:
+                chunk = await asyncio.wait_for(self.audio_queue.get(), timeout=1.0)
+            except asyncio.TimeoutError:
+                continue
+
+            try:
+                text = await transcribe_chunk(chunk, model=self.model)
+            except Exception as exc:
+                text = f"[live transcription error: {exc}]"
+            if text:
+                transcript = merge_chunk_text(transcript, text)
+                yield transcript
+
+
+async def capture_audio(
+    audio_queue: asyncio.Queue[np.ndarray],
+    stop_event: asyncio.Event,
+    device_index: int | None = None,
+) -> None:
+    try:
+        import sounddevice as sd
+    except Exception as exc:
+        raise RuntimeError(
+            "sounddevice is required for live audio capture. Install dependencies with "
+            "`python3 -m pip install -r requirements.txt`."
+        ) from exc
+
+    loop = asyncio.get_running_loop()
+    buffer: list[float] = []
+
+    def callback(indata, frames, time, status):
+        if status:
+            return
+
+        buffer.extend(indata[:, 0].tolist())
+        while len(buffer) >= CHUNK_SAMPLES:
+            chunk = np.array(buffer[:CHUNK_SAMPLES], dtype=np.float32)
+            buffer[:] = buffer[CHUNK_SAMPLES - OVERLAP_SAMPLES :]
+            if is_silent(chunk):
+                continue
+            loop.call_soon_threadsafe(enqueue_chunk_nowait, audio_queue, chunk)
+
+    with sd.InputStream(
+        samplerate=SAMPLE_RATE,
+        channels=1,
+        dtype="float32",
+        device=device_index,
+        callback=callback,
+        blocksize=1024,
+    ):
+        while not stop_event.is_set():
+            await asyncio.sleep(0.1)
+
+
+def enqueue_chunk_nowait(audio_queue: asyncio.Queue[np.ndarray], chunk: np.ndarray) -> None:
+    if audio_queue.full():
+        try:
+            audio_queue.get_nowait()
+        except asyncio.QueueEmpty:
+            pass
+    audio_queue.put_nowait(chunk)
+
+
+async def transcribe_chunk(audio: np.ndarray, model: str = WHISPER_MODEL) -> str:
+    if audio.size == 0 or is_silent(audio):
+        return ""
+
+    loop = asyncio.get_running_loop()
+    result = await loop.run_in_executor(
+        executor,
+        lambda: _transcribe_audio_array_sync(
+            audio,
+            model,
+            {
+                "language": "en",
+                "temperature": 0.0,
+                "condition_on_previous_text": False,
+                "compression_ratio_threshold": 1.8,
+                "logprob_threshold": -0.6,
+                "no_speech_threshold": 0.35,
+            },
+        ),
+    )
+    return "" if is_repetitive_hallucination(result) else result
+
+
+def is_silent(audio: np.ndarray, threshold: float = SILENCE_RMS_THRESHOLD) -> bool:
+    if audio.size == 0:
+        return True
+    rms = float(np.sqrt(np.mean(np.square(audio.astype(np.float32)))))
+    return rms < threshold
+
+
+def merge_chunk_text(existing: str, incoming: str) -> str:
+    existing = " ".join(existing.split()).strip()
+    incoming = " ".join(incoming.split()).strip()
+    if not existing:
+        return incoming
+    if not incoming:
+        return existing
+    if incoming.lower().startswith(existing.lower()):
+        return incoming
+    if existing.lower().endswith(incoming.lower()):
+        return existing
+
+    existing_lower = existing.lower()
+    incoming_lower = incoming.lower()
+    max_overlap = min(len(existing), len(incoming), 120)
+    for size in range(max_overlap, 4, -1):
+        if existing_lower.endswith(incoming_lower[:size]):
+            return f"{existing}{incoming[size:]}".strip()
+    return f"{existing} {incoming}".strip()
+
+
+def is_repetitive_hallucination(text: str) -> bool:
+    import re
+
+    words = re.findall(r"[a-zA-Z']+", text.lower())
+    if len(words) < 8:
+        return False
+    unique_words = set(words)
+    if len(unique_words) <= 2:
+        return True
+    most_common = max(words.count(word) for word in unique_words)
+    return most_common / len(words) >= 0.65
+
+
+async def transcribe_audio_file(audio_path: str, model: str = WHISPER_MODEL) -> str:
+    if not audio_path:
+        return ""
+
+    return await asyncio.to_thread(_transcribe_audio_file_sync, audio_path, model)
+
+
+async def transcribe_audio_array(
+    sample_rate: int,
+    audio: np.ndarray,
+    model: str = WHISPER_MODEL,
+    **decode_options: Any,
+) -> str:
+    if audio.size == 0:
+        return ""
+
+    waveform = prepare_audio_array(sample_rate, audio)
+    return await asyncio.to_thread(_transcribe_audio_array_sync, waveform, model, decode_options)
+
+
+def _transcribe_audio_file_sync(audio_path: str, model: str) -> str:
+    if STT_BACKEND == "transformers":
+        return _transcribe_with_transformers(audio_path, HF_WHISPER_MODEL)
+
+    try:
+        ensure_ffmpeg_on_path()
+        import mlx_whisper
+
+        result = mlx_whisper.transcribe(audio_path, path_or_hf_repo=model)
+        if isinstance(result, dict):
+            return str(result.get("text", "")).strip()
+        return str(result).strip()
+    except Exception as exc:
+        return f"[transcription unavailable: {exc}]"
+
+
+def _transcribe_audio_array_sync(
+    waveform: np.ndarray,
+    model: str,
+    decode_options: dict[str, Any] | None = None,
+) -> str:
+    if STT_BACKEND == "transformers":
+        return _transcribe_with_transformers(
+            {"array": waveform.astype(np.float32), "sampling_rate": 16000},
+            HF_WHISPER_MODEL,
+        )
+
+    try:
+        import mlx_whisper
+
+        result = mlx_whisper.transcribe(
+            waveform,
+            path_or_hf_repo=model,
+            verbose=False,
+            **(decode_options or {}),
+        )
+        if isinstance(result, dict):
+            return str(result.get("text", "")).strip()
+        return str(result).strip()
+    except Exception as exc:
+        return f"[transcription unavailable: {exc}]"
+
+
+def _transcribe_with_transformers(audio_input: Any, model: str) -> str:
+    try:
+        pipeline = get_asr_pipeline(model)
+        result = pipeline(audio_input, generate_kwargs={"language": "english", "task": "transcribe"})
+        if isinstance(result, dict):
+            return str(result.get("text", "")).strip()
+        return str(result).strip()
+    except Exception as exc:
+        return f"[transcription unavailable: {exc}]"
+
+
+def get_asr_pipeline(model: str):
+    global _asr_pipeline
+    if _asr_pipeline is None:
+        from transformers import pipeline
+
+        _asr_pipeline = pipeline(
+            "automatic-speech-recognition",
+            model=model,
+        )
+    return _asr_pipeline
+
+
+def prepare_audio_array(sample_rate: int, audio: np.ndarray) -> np.ndarray:
+    if audio.ndim > 1:
+        audio = audio.mean(axis=1)
+
+    if np.issubdtype(audio.dtype, np.integer):
+        audio = audio.astype(np.float32) / np.iinfo(audio.dtype).max
+    else:
+        audio = audio.astype(np.float32)
+
+    if sample_rate != 16000:
+        from scipy.signal import resample_poly
+
+        gcd = np.gcd(sample_rate, 16000)
+        audio = resample_poly(audio, 16000 // gcd, sample_rate // gcd).astype(np.float32)
+
+    return audio
+
+
+def ensure_ffmpeg_on_path() -> None:
+    if shutil.which("ffmpeg"):
+        return
+
+    try:
+        import imageio_ffmpeg
+
+        ffmpeg = imageio_ffmpeg.get_ffmpeg_exe()
+        bin_dir = BASE_DIR / ".runtime" / "bin"
+        bin_dir.mkdir(parents=True, exist_ok=True)
+        shim = bin_dir / "ffmpeg"
+        if not shim.exists():
+            shim.symlink_to(ffmpeg)
+        os.environ["PATH"] = f"{bin_dir}{os.pathsep}{os.environ.get('PATH', '')}"
+    except Exception as exc:
+        raise RuntimeError(
+            "ffmpeg is required for audio decoding. Install it with `brew install ffmpeg` "
+            "or `python3 -m pip install imageio-ffmpeg`."
+        ) from exc

nodes/framework.py

@@ -0,0 +1,17 @@
+import yaml
+
+from state import CoachState
+
+
+async def framework_node(state: CoachState) -> CoachState:
+    framework = state.get("framework", "General")
+    with open("frameworks.yaml", "r", encoding="utf-8") as file:
+        frameworks = yaml.safe_load(file)
+
+    if framework not in frameworks:
+        framework = "General"
+
+    state["framework"] = framework
+    if not state.get("steps"):
+        state["steps"] = frameworks[framework]["steps"]
+    return state

nodes/transcript.py

@@ -0,0 +1,35 @@
+from state import CoachState
+
+
+QUESTION_HINTS = ("?", "tell me", "how would", "can you", "describe", "design")
+
+
+async def transcript_node(state: CoachState) -> CoachState:
+    raw_text = state.get("raw_text", "").strip()
+    if state.get("question"):
+        speaker = "interviewer"
+    elif state.get("answer"):
+        speaker = "candidate"
+    else:
+        speaker = infer_speaker(raw_text)
+    labelled = {
+        "speaker": speaker,
+        "text": raw_text,
+        "confidence": 0.65 if raw_text else 0.0,
+    }
+
+    state["speaker"] = speaker
+    state["labelled_json"] = labelled
+    if speaker == "interviewer" and not state.get("question"):
+        state["question"] = raw_text
+    elif speaker == "candidate" and not state.get("answer"):
+        state["answer"] = raw_text
+    state["needs_review"] = labelled["confidence"] < 0.6
+    return state
+
+
+def infer_speaker(text: str) -> str:
+    lowered = text.lower()
+    if text.endswith("?") or any(hint in lowered for hint in QUESTION_HINTS):
+        return "interviewer"
+    return "candidate"

prompts.py

@@ -0,0 +1,229 @@
+CLASSIFIER_SYSTEM_PROMPT = """You classify interview questions into one coaching framework.
+Return only valid JSON with keys "type" and "confidence".
+Use "General" when uncertain."""
+
+CLASSIFIER_USER_PROMPT = """Question:
+{question}
+
+Valid frameworks:
+{frameworks}"""
+
+COACHING_GUIDANCE_SYSTEM_PROMPT = """You generate silent interview coaching cues.
+The candidate will glance at these while answering, so keep them short, natural, and specific to the question.
+Do not give a full scripted answer. Do not answer for the candidate. Do not sound robotic.
+Return only valid JSON with key "cues", a list of 4 to 6 concise strings.
+Each cue should be a hint that helps the candidate cover important aspects naturally: definition, structure, mechanism, metrics, tradeoffs, examples, risks, or closing checks.
+Make cues specific to the question, not generic framework labels."""
+
+COACHING_GUIDANCE_USER_PROMPT = """Interview question:
+{question}
+
+Detected framework:
+{framework}
+
+Fine-tuned topic/pattern:
+{pattern}
+
+Fine-tuned coarse steps, for context only:
+{steps}
+
+Generate question-specific coaching hints the candidate can glance at while answering."""
+
+EVALUATOR_SYSTEM_PROMPT = """You are a senior ML interview evaluator.
+You are NOT generating a perfect answer.
+You are assessing whether the candidate demonstrated structured thinking.
+A real interviewer would pass a candidate who covered 3 of 5 areas clearly and thought out loud well, even if they missed some detail.
+Be encouraging about what was done well before noting gaps.
+Never give "No hire" unless the candidate showed no structure at all or gave no answer.
+Generate a benchmark answer only so the candidate can learn and improve. Do not grade by comparing the candidate against a perfect benchmark answer.
+
+Critical evaluation rules:
+- First generate "benchmark_answer" as a learning reference only.
+- Then ignore the benchmark when assigning the band and feedback.
+- The band, steps_covered, strong_points, weak_points, and critical_gaps must be based only on the text under "Candidate answer".
+- Never evaluate your own benchmark_answer.
+- Never say the answer covered an item unless that idea appears in the candidate answer.
+- If the candidate answer is empty, say the candidate did not give an answer.
+- Strong/weak points must cite what the candidate did or did not say, not what a model answer should say.
+
+Use these evaluation bands:
+Strong hire = Covered all key areas, showed depth
+Hire = Covered most areas, good structure
+Borderline = Some structure, missed important areas
+No hire = Jumped to solution, no process, or no answer
+
+Return only valid JSON with these keys:
+"benchmark_answer": string,
+"steps_covered": list of booleans,
+"band": one of ["Strong hire", "Hire", "Borderline", "No hire"],
+"strong_points": list of strings,
+"weak_points": list of strings,
+"critical_gaps": list of strings.
+Use ["Nil"] for any list that has no relevant items.
+Do not include generic encouragement or extra prose outside the JSON."""
+
+EVALUATOR_USER_PROMPT = """Interview question:
+{question}
+
+Candidate answer to evaluate. Use only this text for score and feedback:
+{answer}
+
+Framework: {framework}
+Framework steps:
+{steps}"""
+
+CLARIFICATION_CHECK_SYSTEM_PROMPT = """You decide whether a newly extracted question is actually a candidate clarification about the previous interview question.
+Return only valid JSON with keys "is_clarification" and "reason".
+A clarification asks about constraints, assumptions, scope, definitions, examples, or what the interviewer means.
+Do not mark it as clarification if it is a new interview question from the interviewer."""
+
+CLARIFICATION_CHECK_USER_PROMPT = """Previous interview question:
+{previous_question}
+
+New extracted question:
+{new_question}
+
+Candidate answer captured with new question:
+{answer}
+
+Is the new extracted question a candidate clarification of the previous interview question?"""
+
+TRANSCRIPT_NORMALIZER_SYSTEM_PROMPT = """You clean noisy live interview transcripts for InterviewCoach.
+Return only valid JSON with keys:
+"question": string,
+"answer": string,
+"is_target": boolean,
+"complete": boolean,
+"reason": string.
+
+Target questions are only Data Science, Machine Learning, AI Engineering, or System Design interview questions.
+Reject greetings, logistics, small talk, background discussion, interviewer transitions, and generic interview setup.
+
+Rules:
+- Extract the interviewer's actual target question, not a candidate clarification.
+- Put only the candidate's response in "answer".
+- Preserve the candidate's full response in "answer" until the next interviewer question or transition.
+- Do not compress the answer to only the most direct sentence. Keep supporting explanation, examples, caveats, and reasoning.
+- If there is no candidate response yet, "answer" must be "".
+- A candidate answer is not required for "complete": a complete interviewer question with no answer should still return "is_target": true and "complete": true.
+- Never put interviewer question text in "answer".
+- Never create a question by summarizing or rephrasing the candidate's answer.
+- The question must come from interviewer wording before the candidate starts answering.
+- Candidate answer cues include "not necessarily", "I would", "I will", "I think", "accuracy is misleading", "look at", "since", and first-person explanation.
+- If the answer begins with the question, move that text into "question" and remove it from "answer".
+- Fix obvious transcription artifacts generically: repeated words, broken phrases, missing punctuation, and minor speech-to-text errors.
+- Do not hard-code domain-specific rewrites. Preserve the interviewer intent.
+- Live STT can be very noisy. If the transcript contains a clearly inferable ML/AI/System Design question, reconstruct the intended grammatical question instead of rejecting it.
+- Treat phrases like "supervised machines", "machine learning on..." or broken algorithm/model wording as noisy ML interview speech when the intent is clear.
+- Join fragmented interviewer question pieces when STT inserts punctuation too early. For example, "Can you briefly explain? how does linear regression work?" is one complete question: "Can you briefly explain how linear regression works?"
+- If the interviewer question is corrupted but the intent is inferable, extract the shortest faithful question. Do not add details that appear only in the candidate answer.
+- If there are multiple questions, follow the extraction mode in the user prompt.
+- A noisy but answerable reconstructed question is complete.
+- If "is_target" is true and "complete" is true, "question" must be non-empty.
+- Interview prompts phrased as imperatives are questions. "Tell me...", "Explain...", "Describe...", and "Walk me through..." are complete questions when they target ML/AI/System Design.
+- Interview prompts phrased as knowledge checks are questions. "Do you know anything about...", "Are you familiar with...", and "Can you explain..." are complete questions when they target ML/AI/System Design.
+- Ignore setup questions such as "Can I ask one question?" when a real target question follows.
+- If no complete target question is present, return {"question": "", "answer": "", "is_target": false, "complete": false, "reason": "..."}.
+- If a target question is present but no candidate answer is present, return the question and an empty answer.
+- Keep "reason" under 20 words.
+- Examples below are illustrative only. Never copy an example question unless the same question appears in the transcript.
+
+Examples:
+Noisy transcript: "hello let me start asking questions can you tell me how many supervised machines otherwise machine learning algorithms you have worked with"
+JSON: {"question": "Can you tell me which supervised machine learning algorithms you have worked with?", "answer": "", "is_target": true, "complete": true, "reason": "Noisy ML question reconstructed."}
+
+Noisy transcript: "Tell me the difference between supervised and unsupervised. and unsupervised machine learning models."
+JSON: {"question": "Tell me the difference between supervised and unsupervised machine learning models.", "answer": "", "is_target": true, "complete": true, "reason": "Extracted ML comparison prompt."}
+
+Noisy transcript: "Hope you are good. Can I ask one question? Do you know anything about supervised? supervised machine learning algorithms."
+JSON: {"question": "Do you know anything about supervised machine learning algorithms?", "answer": "", "is_target": true, "complete": true, "reason": "Extracted ML knowledge question."}
+
+Noisy transcript: "Okay that's also good. Can you briefly explain? how does linear regression work? linear regression we have set up of predictors and then there is a target."
+JSON: {"question": "Can you briefly explain how linear regression works?", "answer": "Linear regression uses predictors to estimate a target.", "is_target": true, "complete": true, "reason": "Joined fragmented ML question."}
+
+Noisy transcript: "First one. You have a data set where 95% and only 5% fraud. a model and get 95% accuracy. Please try good model. not necessarily a model that predicts every transaction as legitimate. So accuracy is misleading here."
+JSON: {"question": "You have a dataset with 95% legitimate transactions and 5% fraud, and a model gets 95% accuracy. Is it a good model?", "answer": "Not necessarily. A model that predicts every transaction as legitimate would get 95% accuracy, so accuracy is misleading here.", "is_target": true, "complete": true, "reason": "Separated question from answer."}
+
+Noisy transcript: "Good. Second question. in production, what is the first thing we check? I will check for data."
+JSON: {"question": "In production, what is the first thing we check?", "answer": "I will check for data.", "is_target": true, "complete": true, "reason": "Extracted latest production question."}
+
+Noisy transcript: "What is and what is x and y variables. Yes. So the linear regression is F form of machine learning algorithm predict an output based on certain features given input into the model. The x variables are called the predictors and the y variable is the target variable. For example, if I want to predict on the number of years experience that's a classic linear regression."
+JSON: {"question": "What are x and y variables in linear regression?", "answer": "Linear regression is a form of machine learning algorithm that predicts an output based on certain features given as input into the model. The x variables are called the predictors and the y variable is the target variable. For example, if I want to predict based on the number of years of experience, that's a classic linear regression example.", "is_target": true, "complete": true, "reason": "Preserved full candidate answer."}
+
+"""
+
+TRANSCRIPT_NORMALIZER_USER_PROMPT = """Raw transcript or transcript window:
+{transcript}
+
+Extraction mode:
+{mode_instruction}
+
+Current extracted question, if any:
+{question}
+
+Current extracted answer, if any:
+{answer}
+
+Normalize this into one clean target interview Q&A boundary."""
+
+TRANSCRIPT_NORMALIZER_REPAIR_SYSTEM_PROMPT = """You repair invalid JSON produced by an interview transcript normalizer.
+Return only valid JSON with keys "question", "answer", "is_target", "complete", and "reason".
+The "question" field must contain the interviewer's DS/ML/AI/System Design question.
+The "answer" field must contain only the candidate response.
+If the previous output put interviewer question text in "answer", move it to "question" and set "answer" to "" unless a real candidate answer exists.
+If the previous output put candidate answer text inside "question", remove it from "question" and keep it only in "answer".
+After repairing fields, re-evaluate "is_target" and "complete" from the repaired question.
+If the repaired question is about supervised learning, machine learning algorithms, AI, data science, or system design, set "is_target": true.
+If the repaired question can be answered as a standalone interview question, set "complete": true.
+A noisy but answerable ML question is complete after repair.
+
+Example invalid JSON:
+{"question": "In production, what is the first thing we check? I will check for data.", "answer": "I will check for data.", "is_target": true, "complete": true, "reason": "duplicate answer"}
+Repaired JSON:
+{"question": "In production, what is the first thing we check?", "answer": "I will check for data.", "is_target": true, "complete": true, "reason": "Removed answer from question."}"""
+
+TRANSCRIPT_NORMALIZER_REPAIR_USER_PROMPT = """Raw transcript:
+{transcript}
+
+Previous invalid JSON:
+{payload}
+
+Repair the JSON."""
+
+MULTI_EXCHANGE_EXTRACTOR_SYSTEM_PROMPT = """You extract all target interview Q&A exchanges from a noisy transcript.
+Return only valid JSON with key "exchanges", a list of objects with keys:
+"question": string,
+"answer": string,
+"is_target": boolean,
+"complete": boolean,
+"reason": string.
+
+Target questions are only Data Science, Machine Learning, AI Engineering, MLOps, or System Design interview questions.
+
+Rules:
+- Extract every target interviewer question in chronological order.
+- Do not only extract the latest question.
+- Each candidate answer belongs to the target question immediately before it.
+- Preserve candidate answers fully. Do not summarize, rewrite conceptually, improve, or add missing ideas.
+- Do not shorten the candidate answer to only the final/direct sentence. Keep definitions, reasoning, examples, caveats, and explanatory setup.
+- The answer ends only when the next interviewer question, interviewer transition, or transcript end begins.
+- Only clean obvious STT noise: repeated words, broken punctuation, filler fragments, and spelling/word recognition mistakes when meaning is clear.
+- Correct obvious ML/STT word errors when context is clear, such as "Frot" -> "fraud" and "data trips/drips" -> "data drift".
+- Never use candidate answer content to invent or expand the interviewer question.
+- If the interviewer question is noisy but inferable, reconstruct the shortest faithful question.
+- If a target question has no answer, return an empty string for "answer".
+- Exclude greetings, logistics, transitions, interviewer praise, and non-target small talk.
+- Keep "reason" under 20 words.
+
+Example:
+Transcript: "First one you have a data set where 95% are legitimate and 5% fraud. You train a model and get 95% accuracy. Is this a good model? not necessarily a model that predicts every transaction as legitimate. accuracy is misleading. Good. Second question your model performs well in testing poorly in production. What's the first thing you would do? I would check for data drift."
+JSON: {"exchanges":[{"question":"You have a dataset where 95% of transactions are legitimate and 5% are fraud. You train a model and get 95% accuracy. Is this a good model?","answer":"Not necessarily. A model that predicts every transaction as legitimate would get 95% accuracy. Accuracy is misleading.","is_target":true,"complete":true,"reason":"Extracted fraud metric question."},{"question":"Your model performs well in testing but poorly in production. What is the first thing you would do?","answer":"I would check for data drift.","is_target":true,"complete":true,"reason":"Extracted production performance question."}]}
+
+Example:
+Transcript: "What is and what is x and y variables. Yes. So the linear regression is F form of machine learning algorithm predict an output based on certain features given input into the model. The x variables are called the predictors and the y variable is the target variable. For example, if I want to predict on the number of years experience that's a classic linear regression."
+JSON: {"exchanges":[{"question":"What are x and y variables in linear regression?","answer":"Linear regression is a form of machine learning algorithm that predicts an output based on certain features given as input into the model. The x variables are called the predictors and the y variable is the target variable. For example, if I want to predict based on the number of years of experience, that's a classic linear regression example.","is_target":true,"complete":true,"reason":"Preserved full candidate answer."}]}"""
+
+MULTI_EXCHANGE_EXTRACTOR_USER_PROMPT = """Transcript:
+{transcript}
+
+Extract all target Q&A exchanges."""

requirements.txt

@@ -0,0 +1,13 @@
+aiosqlite>=0.20.0
+accelerate>=1.9.0
+gradio>=4.44.0
+imageio-ffmpeg>=0.5.1
+langgraph>=0.2.0
+mlx-whisper>=0.4.0; platform_system == "Darwin"
+modal>=1.1.0
+peft>=0.16.0
+pyyaml>=6.0.2
+scipy>=1.11.0
+sounddevice>=0.5.1; platform_system == "Darwin"
+torch>=2.3.0
+transformers>=4.54.0

state.py

@@ -0,0 +1,19 @@
+from typing import Any, TypedDict
+
+
+class CoachState(TypedDict, total=False):
+    session_id: int
+    audio_queue: Any
+    raw_text: str
+    labelled_json: dict[str, Any]
+    speaker: str
+    question: str
+    answer: str
+    framework: str
+    pattern: str
+    steps: list[str]
+    confidence: float
+    needs_review: bool
+    topic_model_used: str
+    exchange_id: int
+    evaluation: dict[str, Any]