AGENTS.md

# 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`
---