Add semantic routing and retrieval to cut per-request token cost

.github/workflows/tests.yml

@@ -0,0 +1,27 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt -r requirements-dev.txt
+
+      # No secrets and no data/ directory: tests/conftest.py pins the
+      # environment so the suite runs without credentials.
+      - name: Run tests
+        run: python -m pytest tests/ -q

README.md

@@ -8,10 +8,27 @@ grounded only in your own career documents.
 
 **1. Create the environment**
 
+Python 3.13 is what CI runs on; 3.11+ works.
+
 ```bash
 python -m venv .venv
-.venv\Scripts\activate          # Windows
-source .venv/bin/activate       # macOS / Linux
+```
+
+Activate it — Windows:
+
+```powershell
+.venv\Scripts\activate
+```
+
+macOS / Linux:
+
+```bash
+source .venv/bin/activate
+```
+
+Then:
+
+```bash
 pip install -r requirements.txt
 ```
 
@@ -24,7 +41,7 @@ CANDIDATE_NAME=Your Name        # used in the system prompt
 # Optional — Langfuse tracing. Tracing turns on only when both keys are present.
 LANGFUSE_PUBLIC_KEY=pk-lf-...
 LANGFUSE_SECRET_KEY=sk-lf-...
-LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
+LANGFUSE_HOST=https://us.cloud.langfuse.com
 ```
 
 | Variable | Default | Purpose |
@@ -35,10 +52,13 @@ LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
 | `GROQ_MODEL` | `openai/gpt-oss-120b` | Model id. |
 | `LLM_TEMPERATURE` | `0.0` | Sampling temperature. |
 | `LLM_MAX_TOKENS` | `3000` | Response cap. See the token budget note below. |
+| `LLM_DRAFTING_TEMPERATURE` | `0.4` | Temperature for cover-letter drafting only. |
 | `MAX_HISTORY_TURNS` | `10` | Turns replayed to the model per request. |
+| `EMBEDDING_MODEL` | `sentence-transformers/all-MiniLM-L6-v2` | Routing and retrieval embeddings, run through fastembed (ONNX, no torch). Downloaded on first run. |
+| `RETRIEVAL_TOP_K` | `5` | Excerpts retrieved for a narrow question. |
 | `CHECKPOINT_DB` | `checkpoints.sqlite` | Where conversation threads persist. |
 | `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` | — | Enable tracing when both are set. |
-| `LANGFUSE_HOST` or `LANGFUSE_BASE_URL` | `https://cloud.langfuse.com` | Langfuse region. Use the US host if your keys are US. |
+| `LANGFUSE_HOST` (alias: `LANGFUSE_BASE_URL`) | `https://cloud.langfuse.com` | Langfuse region. Use `https://us.cloud.langfuse.com` if your keys are US. |
 
 **3. Add your documents.** Put your resume, project write-ups, and any other career documents
 in `data/`. PDFs must be converted to Markdown first — the app reads only `.md`:
@@ -48,6 +68,11 @@ pip install -r requirements-ingest.txt   # docling, heavy; needed only for this
 python pdf_2_markdown_converter.py
 ```
 
+The converter reads and writes `data/` directly; it does not honour `DATA_DIR`. If you point
+`DATA_DIR` elsewhere, convert in `data/` first and move the `.md` files across.
+
+Startup fails if the directory is missing or holds no `.md` file, so do this before step 4.
+
 **4. Run**
 
 ```bash
@@ -62,7 +87,10 @@ Paste a job description into the left panel, then chat or use the preset buttons
 job-chat/
 ├── app.py                       # Gradio UI and event wiring — the entry point
 ├── graph.py                     # LangGraph state graph, routing, LLM construction
-├── prompts.py                   # System prompt and the three preset action instructions
+├── prompts.py                   # System prompts and the three preset action instructions
+├── router.py                    # Semantic router: trivial / specific / full
+├── retrieval.py                 # Chunking and similarity search over the profile
+├── embeddings.py                # fastembed wrapper
 ├── ats.py                       # ATS schema and score calculation
 ├── dataloader.py                # Loads and concatenates the Markdown profile documents
 ├── config.py                    # Environment settings with validation
@@ -70,22 +98,30 @@ job-chat/
 ├── pdf_2_markdown_converter.py  # One-off: PDF -> Markdown
 ├── data/                        # Your documents (gitignored)
 ├── tests/                       # Unit tests; no API calls
+├── .github/workflows/tests.yml  # CI: runs the suite on push and pull request
 ├── requirements.txt             # Runtime
 ├── requirements-ingest.txt      # PDF conversion only
-└── requirements-dev.txt         # Tests
+└── requirements-dev.txt         # Tests (install on top of requirements.txt)
 ```
 
 ## Graph structure
 
-One state graph with two nodes. Routing depends on `action` in the state: the ATS button needs
-structured output, everything else streams as chat.
+A preset button routes on its `action`. Free-form chat is classified by a semantic router, which
+decides how much of your profile the question actually needs.
 
 ```mermaid
-flowchart LR
-    START([START]) -->|action == "ats"| ATS["ats_analysis<br/>structured output"]
-    START -->|otherwise| ANSWER["answer<br/>streaming chat"]
+flowchart TD
+    START([START]) --> DECIDE{action set?}
+    DECIDE -->|ats| ATS["ats_analysis<br/>full profile, structured output"]
+    DECIDE -->|review, cover_letter| ANSWER["answer<br/>full profile + job description"]
+    DECIDE -->|no action| ROUTER{{semantic router}}
+    ROUTER -->|trivial| TRIVIAL["trivial_answer<br/>no profile"]
+    ROUTER -->|specific| RAG["rag_answer<br/>retrieved excerpts"]
+    ROUTER -->|full / uncertain| ANSWER
     ATS --> FINISH([END])
     ANSWER --> FINISH
+    TRIVIAL --> FINISH
+    RAG --> FINISH
 ```
 
 **State**
@@ -96,13 +132,37 @@ flowchart LR
 | `job_description` | The pasted target role. |
 | `action` | `ats`, `review`, `cover_letter`, or empty for free chat. |
 
-**`answer`** renders the system prompt with your documents and the job description, replays the
-last `MAX_HISTORY_TURNS` turns, and streams the reply. Older turns stay in the checkpoint but are
-not resent, so cost per turn stays flat however long the conversation runs.
+**Nodes**
+
+| Node | Context sent | Used for |
+|---|---|---|
+| `answer` | Full profile + job description | Preset review and cover letter, and any broad question |
+| `rag_answer` | Top `RETRIEVAL_TOP_K` excerpts | Narrow factual questions |
+| `trivial_answer` | None | Greetings and pleasantries |
+| `ats_analysis` | Full profile + job description | ATS button only |
+
+All three chat nodes replay only the last `MAX_HISTORY_TURNS` turns. Older turns stay in the
+checkpoint but are not resent, so cost per turn stays flat however long the conversation runs.
+
+`ats_analysis` asks the model only to classify each job-description keyword as matched or missing.
+The percentage is computed in Python from the list lengths, so the score cannot contradict the
+lists it is derived from.
+
+**Routing rules.** Every preset action bypasses the router and receives the full profile: a
+retrieval miss inside an ATS score or a fit review would silently drop real evidence. For free
+chat, the router compares the question against the centroid of reference examples per route
+(`router.py`) and falls back to the full profile whenever the best match is weak or close to the
+runner-up. The asymmetry is deliberate — routing a greeting to the full profile only wastes
+tokens, while routing a real question away from it produces a confident answer with no evidence
+behind it.
 
-**`ats_analysis`** asks the model only to classify each job-description keyword as matched or
-missing. The percentage is computed in Python from the list lengths, so the score cannot
-contradict the lists it is derived from.
+**Measured cost per request** (this profile, one narrow question):
+
+| Route | Approximate prompt tokens | Saving |
+|---|---|---|
+| `answer` | 4,110 | — |
+| `rag_answer` | 1,028 | 75% |
+| `trivial_answer` | 195 | 95% |
 
 **Persistence.** A SQLite checkpointer keeps each thread on disk, so conversations survive a
 restart. "Reset conversation" starts a new thread; the previous one is retained.
@@ -110,16 +170,22 @@ restart. "Reset conversation" starts a new thread; the previous one is retained.
 ## Tests
 
 ```bash
-pip install -r requirements-dev.txt
+pip install -r requirements-dev.txt      # on top of requirements.txt
 python -m pytest tests/ -q
 ```
 
 Unit tests only — no API calls, no keys needed. They cover the ATS score arithmetic, config
-validation, document loading, routing, history trimming, and prompt templating.
+validation, document loading, chunking and retrieval, semantic routing, node selection, history
+trimming, temperature selection, and prompt templating. `tests/test_isolation.py` asserts the
+suite never touches your real credentials or your `data/` documents. CI runs the same command on
+every push to `main` and every pull request.
 
 ## Token budget
 
-Groq's free tier allows 8,000 tokens per minute and 200,000 per day. Each request sends your full
-profile (~3,900 tokens) plus the job description plus the reserved response budget, so a single
-request costs roughly 7,000–8,000 tokens. That is about 25–40 requests per day. `LLM_MAX_TOKENS`
-is capped at 3,000 to keep requests under the per-minute ceiling; raising it triggers HTTP 413.
+Groq's free tier allows 8,000 tokens per minute and 200,000 per day for `openai/gpt-oss-120b`
+(check your own limits — they vary by model and account). A full-profile request sends your
+profile (~3,900 tokens) plus the job description plus the reserved response budget, so it costs
+roughly 7,000–8,000 tokens: about 25–28 such requests per day. Routed chat is much cheaper, so
+the real daily count is higher whenever questions take the `rag_answer` or `trivial_answer`
+route. `LLM_MAX_TOKENS` defaults to 3,000 to keep a full-profile request under the per-minute
+ceiling; raising it can push a request past the limit, which Groq rejects with HTTP 413.

app.py

@@ -78,7 +78,7 @@ def stream_response(chat_history, job_description, thread_id, model_query=None,
             chat_history[-1]["content"] = "_Extracting and scoring keywords…_"
             yield chat_history
             result = GRAPH.invoke(state, config)
-            chat_history[-1]["content"] = result["messages"][-1].content
+            chat_history[-1]["content"] = str(result["messages"][-1].text)
             yield chat_history
             return
 

config.py

@@ -13,6 +13,9 @@ PROJECT_ROOT = Path(__file__).parent
 
 DEFAULT_MODEL = "openai/gpt-oss-120b"
 DEFAULT_TEMPERATURE = 0.0
+# Drafting a cover letter is writing, not analysis: a little sampling gives
+# natural prose. Kept low so it does not start inventing detail.
+DEFAULT_DRAFTING_TEMPERATURE = 0.4
 # The preset actions (ATS keyword tables, detailed reviews) run long, so 2048
 # truncated them mid-answer. The ceiling is Groq's free-tier limit of 8000
 # tokens per minute, which counts input + max_tokens together: profile (~3.9k)
@@ -24,6 +27,9 @@ DEFAULT_CHECKPOINT_DB = "checkpoints.sqlite"
 # Turns of conversation replayed to the model. Older turns stay in the
 # checkpoint (nothing is deleted) but are not resent.
 DEFAULT_MAX_HISTORY_TURNS = 10
+# Routing and retrieval. ONNX runtime, so no torch dependency.
+DEFAULT_EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+DEFAULT_RETRIEVAL_TOP_K = 5
 
 
 class ConfigError(RuntimeError):
@@ -37,8 +43,11 @@ class Settings:
     data_dir: Path
     model: str
     temperature: float
+    drafting_temperature: float
     max_tokens: int
     max_history_turns: int
+    embedding_model: str
+    retrieval_top_k: int
     checkpoint_db: Path
     langfuse_public_key: str
     langfuse_secret_key: str
@@ -102,8 +111,11 @@ def get_settings() -> Settings:
         data_dir=_resolve_data_dir(),
         model=os.getenv("GROQ_MODEL", "").strip() or DEFAULT_MODEL,
         temperature=_get_float("LLM_TEMPERATURE", DEFAULT_TEMPERATURE),
+        drafting_temperature=_get_float("LLM_DRAFTING_TEMPERATURE", DEFAULT_DRAFTING_TEMPERATURE),
         max_tokens=_get_int("LLM_MAX_TOKENS", DEFAULT_MAX_TOKENS),
         max_history_turns=_get_int("MAX_HISTORY_TURNS", DEFAULT_MAX_HISTORY_TURNS),
+        embedding_model=os.getenv("EMBEDDING_MODEL", "").strip() or DEFAULT_EMBEDDING_MODEL,
+        retrieval_top_k=_get_int("RETRIEVAL_TOP_K", DEFAULT_RETRIEVAL_TOP_K),
         checkpoint_db=PROJECT_ROOT / (
             os.getenv("CHECKPOINT_DB", "").strip() or DEFAULT_CHECKPOINT_DB
         ),

embeddings.py

@@ -0,0 +1,25 @@
+"""Sentence embeddings via fastembed (ONNX runtime, no torch dependency).
+
+Vectors come back L2-normalised, so a dot product is cosine similarity.
+"""
+
+from functools import lru_cache
+
+import numpy as np
+
+from config import get_settings
+
+
+@lru_cache(maxsize=1)
+def _model():
+    from fastembed import TextEmbedding
+
+    return TextEmbedding(get_settings().embedding_model)
+
+
+def embed(texts) -> np.ndarray:
+    """Embed a sequence of strings into a (n, dim) float32 matrix."""
+    texts = list(texts)
+    if not texts:
+        return np.zeros((0, 0), dtype=np.float32)
+    return np.asarray(list(_model().embed(texts)), dtype=np.float32)

graph.py

@@ -1,12 +1,13 @@
 """LangGraph application graph.
 
-Today the graph is a single node, which is deliberate: it buys checkpointed
-conversation state (threads that survive a restart) and gives the planned
-cover-letter flow (draft -> critique -> revise) somewhere to live without a
-rewrite.
+Preset actions route by their action name and always receive the full profile.
+Free-form chat is classified by the semantic router, which decides whether the
+question needs no profile, retrieved excerpts, or all of it.
 """
 
+import logging
 import sqlite3
+from functools import partial
 from typing import Annotated, TypedDict
 
 from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, trim_messages
@@ -15,10 +16,22 @@ from langgraph.checkpoint.sqlite import SqliteSaver
 from langgraph.graph import START, StateGraph
 from langgraph.graph.message import add_messages
 
+import router as router_module
 from ats import ATSAnalysis, format_ats_report
 from config import get_settings
 from dataloader import ProfileLoader
-from prompts import NO_JD_PLACEHOLDER, build_qa_prompt, render_system_prompt
+from embeddings import embed
+from prompts import (
+    NO_JD_PLACEHOLDER,
+    build_qa_prompt,
+    build_rag_prompt,
+    build_trivial_prompt,
+    render_system_prompt,
+)
+from retrieval import ProfileIndex, chunk_documents
+from router import SemanticRouter
+
+logger = logging.getLogger(__name__)
 
 
 class ChatState(TypedDict):
@@ -29,17 +42,54 @@ class ChatState(TypedDict):
     action: str
 
 
-def route_action(state) -> str:
-    """Pick the node for this turn. Only 'ats' needs structured output."""
-    return "ats_analysis" if state.get("action") == "ats" else "answer"
+NODE_BY_ROUTE = {
+    router_module.TRIVIAL: "trivial_answer",
+    router_module.SPECIFIC: "rag_answer",
+    router_module.FULL: "answer",
+}
+
+
+def latest_text(messages) -> str:
+    """Text of the most recent message.
+
+    Message content survives a checkpoint round trip as a list of content
+    blocks rather than a plain string, so `.content` cannot be used directly.
+    `.text` returns a str for either shape.
+    """
+    if not messages:
+        return ""
+    return str(messages[-1].text)
+
+
+def route_action(state, semantic_router=None) -> str:
+    """Pick the node for this turn.
+
+    Preset actions always get the full profile: a retrieval miss would silently
+    corrupt an ATS score or a fit review. Only free-form chat is routed.
+    """
+    action = state.get("action")
+    if action == "ats":
+        return "ats_analysis"
+    if action:
+        return "answer"
+    if semantic_router is None:
+        return "answer"
+
+    messages = state.get("messages") or []
+    query = latest_text(messages)
+    return NODE_BY_ROUTE[semantic_router.route(query)]
+
+
+# Actions that write prose rather than analyse, and so use a higher temperature.
+DRAFTING_ACTIONS = {"cover_letter"}
 
 
-def build_llm():
+def build_llm(temperature=None):
     settings = get_settings()
     return ChatGroq(
         api_key=settings.groq_api_key,
         model=settings.model,
-        temperature=settings.temperature,
+        temperature=settings.temperature if temperature is None else temperature,
         max_tokens=settings.max_tokens,
     )
 
@@ -47,16 +97,25 @@ def build_llm():
 def build_graph():
     settings = get_settings()
     profile_data = ProfileLoader(settings.data_dir).load_and_format_markdown()
-    chain = build_qa_prompt() | build_llm()
-    structured_llm = build_llm().with_structured_output(ATSAnalysis)
+    prompt = build_qa_prompt()
+    llm = build_llm()
+    chain = prompt | llm
+    drafting_chain = prompt | build_llm(settings.drafting_temperature)
+    rag_chain = build_rag_prompt() | llm
+    trivial_chain = build_trivial_prompt() | llm
+    structured_llm = llm.with_structured_output(ATSAnalysis)
+
+    index = ProfileIndex(chunk_documents(profile_data), embed)
+    semantic_router = SemanticRouter(embed)
+    logger.info("Indexed %d profile chunks for retrieval.", len(index.chunks))
 
     # Two messages per turn (human + ai).
     max_history_messages = settings.max_history_turns * 2
 
-    def answer(state: ChatState):
+    def recent_history(state):
         # Older turns remain in the checkpoint; they are simply not resent,
         # which keeps per-turn cost flat instead of growing with the thread.
-        history = trim_messages(
+        return trim_messages(
             state["messages"][:-1],
             max_tokens=max_history_messages,
             token_counter=len,
@@ -64,12 +123,32 @@ def build_graph():
             start_on="human",
             include_system=False,
         )
-        user_query = state["messages"][-1].content
-        response = chain.invoke({
+
+    def answer(state: ChatState):
+        active = drafting_chain if state.get("action") in DRAFTING_ACTIONS else chain
+        response = active.invoke({
             "context_text": profile_data,
             "job_description": state.get("job_description") or NO_JD_PLACEHOLDER,
-            "user_query": user_query,
-            "history": history,
+            "user_query": latest_text(state["messages"]),
+            "history": recent_history(state),
+        })
+        return {"messages": [response]}
+
+    def rag_answer(state: ChatState):
+        """Narrow question: send only the excerpts that match it."""
+        query = latest_text(state["messages"])
+        response = rag_chain.invoke({
+            "context_text": index.search_text(query, k=settings.retrieval_top_k),
+            "user_query": query,
+            "history": recent_history(state),
+        })
+        return {"messages": [response]}
+
+    def trivial_answer(state: ChatState):
+        """Greeting or pleasantry: no profile at all."""
+        response = trivial_chain.invoke({
+            "user_query": latest_text(state["messages"]),
+            "history": recent_history(state),
         })
         return {"messages": [response]}
 
@@ -77,14 +156,20 @@ def build_graph():
         """Classify keywords with structured output, then score them in Python."""
         analysis = structured_llm.invoke([
             SystemMessage(content=render_system_prompt(profile_data, state.get("job_description"))),
-            HumanMessage(content=state["messages"][-1].content),
+            HumanMessage(content=latest_text(state["messages"])),
         ])
         return {"messages": [AIMessage(content=format_ats_report(analysis))]}
 
     builder = StateGraph(ChatState)
     builder.add_node("answer", answer)
+    builder.add_node("rag_answer", rag_answer)
+    builder.add_node("trivial_answer", trivial_answer)
     builder.add_node("ats_analysis", ats_analysis)
-    builder.add_conditional_edges(START, route_action, ["answer", "ats_analysis"])
+    builder.add_conditional_edges(
+        START,
+        partial(route_action, semantic_router=semantic_router),
+        ["answer", "rag_answer", "trivial_answer", "ats_analysis"],
+    )
 
     # check_same_thread=False: Gradio serves requests from a pool of threads.
     conn = sqlite3.connect(str(settings.checkpoint_db), check_same_thread=False)

prompts.py

@@ -61,6 +61,46 @@ If the documents genuinely do not cover something, say so directly and stop. "Th
 """
 
 
+TRIVIAL_SYSTEM_PROMPT = """You are the interview-preparation assistant for {candidate_name}. The user has sent a greeting, a pleasantry, or a question about what you do — nothing that requires their career documents, which is why you have not been given them.
+
+Reply in one or two short sentences. Be warm but brief, and do not pad.
+
+If the user asks what you can do, say that you can answer questions about their background, analyse how well they match a job description they paste in, draft interview answers, and write cover letters.
+
+You do not have their documents in front of you for this message, so make no claims about their experience, skills, or history. If the message turns out to need that detail, say you will need to look at their profile and invite them to ask directly."""
+
+
+RAG_SYSTEM_PROMPT = """You are the interview-preparation assistant for {candidate_name}, referred to below as "the candidate". The user asked a narrow question, so you have been given the excerpts from their career documents that best match it — not the complete profile.
+
+## What the excerpts are
+
+They are verbatim passages from the candidate's resume, project write-ups, and volunteer experience, each tagged with its source document. They are the only evidence you have.
+
+## Grounding rules
+
+- STATED: written in the excerpts. Assert it freely.
+- INFERRED: a reasonable read of what the excerpts say. Allowed, but mark it as inference.
+- UNSUPPORTED: anything else. Never assert it.
+
+## The distinction that matters here
+
+You are working from a subset of the candidate's documents, so absence from these excerpts is not proof of absence from their record. Never say a skill or experience does not exist. Say instead that it does not appear in the excerpts you were given, and suggest they ask again for a full review if they want certainty. Wrongly telling someone they lack experience they actually have is the worst outcome here.
+
+If the excerpts do not address the question at all, say so plainly and stop.
+
+## Style
+
+- Answer directly, in one short paragraph unless the question needs more.
+- Name the specific project, role, or skill you are drawing on.
+- No preamble, no praise, no restating the question.
+
+## Retrieved excerpts
+
+<excerpts>
+{context_text}
+</excerpts>"""
+
+
 def render_system_prompt(context_text, job_description) -> str:
     """The system prompt as plain text, for paths that bypass the chat template."""
     return QA_SYSTEM_PROMPT.format(
@@ -70,14 +110,29 @@ def render_system_prompt(context_text, job_description) -> str:
     )
 
 
-def build_qa_prompt() -> ChatPromptTemplate:
+def _chat_prompt(system_text) -> ChatPromptTemplate:
     return ChatPromptTemplate.from_messages([
-        ("system", QA_SYSTEM_PROMPT),
+        ("system", system_text),
         MessagesPlaceholder("history"),
         ("user", "{user_query}"),
     ]).partial(candidate_name=get_settings().candidate_name)
 
 
+def build_qa_prompt() -> ChatPromptTemplate:
+    """Full profile plus job description."""
+    return _chat_prompt(QA_SYSTEM_PROMPT)
+
+
+def build_rag_prompt() -> ChatPromptTemplate:
+    """Retrieved excerpts only, for narrowly scoped questions."""
+    return _chat_prompt(RAG_SYSTEM_PROMPT)
+
+
+def build_trivial_prompt() -> ChatPromptTemplate:
+    """No profile at all, for greetings and pleasantries."""
+    return _chat_prompt(TRIVIAL_SYSTEM_PROMPT)
+
+
 # ---------------------------------------------------------------------------
 # Preset actions.
 #

requirements.txt

@@ -1,3 +1,4 @@
+fastembed==0.8.0
 gradio==6.22.0
 langchain==1.3.14
 langchain-core==1.5.1

retrieval.py

@@ -0,0 +1,81 @@
+"""Retrieval over the profile documents.
+
+The corpus is three documents and a few dozen chunks, so similarity is computed
+directly against an in-memory matrix. A vector database would add a dependency
+and an external service without changing the result at this size.
+
+Retrieval is used only for narrowly scoped questions. The preset actions always
+receive the full profile, because a retrieval miss there would silently corrupt
+an ATS score or a fit review.
+"""
+
+import numpy as np
+
+from dataloader import SEPARATOR
+
+TARGET_CHUNK_CHARS = 600
+
+
+def chunk_documents(profile_text, target_chars=TARGET_CHUNK_CHARS):
+    """Split the profile into retrievable chunks, each labelled with its source."""
+    chunks = []
+
+    for document in profile_text.split(SEPARATOR):
+        document = document.strip()
+        if not document:
+            continue
+
+        lines = document.splitlines()
+        source = lines[0].removeprefix("# Source:").strip() if lines[0].startswith("# Source:") else ""
+        body = "\n".join(lines[1:]).strip() if source else document
+
+        current = []
+        length = 0
+        for paragraph in (p.strip() for p in body.split("\n\n")):
+            if not paragraph:
+                continue
+            if current and length + len(paragraph) > target_chars:
+                chunks.append(_label(source, current))
+                current, length = [], 0
+            current.append(paragraph)
+            length += len(paragraph)
+
+        if current:
+            chunks.append(_label(source, current))
+
+    return chunks
+
+
+def _label(source, paragraphs):
+    body = "\n\n".join(paragraphs)
+    return f"[{source}]\n{body}" if source else body
+
+
+class ProfileIndex:
+    def __init__(self, chunks, embed_fn):
+        self.chunks = list(chunks)
+        if self.chunks:
+            vectors = embed_fn(self.chunks)
+            norms = np.linalg.norm(vectors, axis=1, keepdims=True)
+            self.vectors = vectors / np.where(norms == 0, 1, norms)
+        else:
+            self.vectors = np.zeros((0, 0), dtype=np.float32)
+        self.embed_fn = embed_fn
+
+    def search(self, query, k=5):
+        """Return the k chunks most similar to the query, best first."""
+        if not self.chunks or not query.strip():
+            return []
+
+        vector = self.embed_fn([query])[0]
+        norm = np.linalg.norm(vector)
+        if norm:
+            vector = vector / norm
+
+        similarities = self.vectors @ vector
+        top = np.argsort(similarities)[::-1][:k]
+        return [self.chunks[i] for i in top]
+
+    def search_text(self, query, k=5):
+        found = self.search(query, k)
+        return "\n\n---\n\n".join(found) if found else "(No relevant excerpts found.)"

router.py

@@ -0,0 +1,94 @@
+"""Three-way semantic router.
+
+Queries are compared against the centroid of a few reference examples per
+route. Routing is deliberately asymmetric: sending a real question to a route
+without the profile produces a confident answer about the candidate with no
+evidence behind it, while sending a greeting to the full profile merely wastes
+tokens. So anything short of a clear, confident match falls back to FULL.
+"""
+
+import numpy as np
+
+TRIVIAL = "trivial"
+SPECIFIC = "specific"
+FULL = "full"
+
+REFERENCE_QUERIES = {
+    TRIVIAL: [
+        "hello",
+        "hi there",
+        "hey",
+        "how are you?",
+        "thanks!",
+        "thank you",
+        "good morning",
+        "good evening",
+        "who are you?",
+        "what can you do?",
+        "bye",
+    ],
+    SPECIFIC: [
+        "do I know Rust?",
+        "what is my Python experience?",
+        "have I used Kubernetes?",
+        "which projects used FAISS?",
+        "tell me about my volunteer work",
+        "what certifications do I have?",
+        "where did I use Docker?",
+        "what did I do at my last job?",
+        "which languages do I know?",
+    ],
+    FULL: [
+        "am I a fit for this role?",
+        "what are my weakest areas?",
+        "how should I position myself?",
+        "summarise my background",
+        "what should I emphasise in the interview?",
+        "what gaps do I have for this job?",
+        "what do I bring to the table?",
+        "write me a cover letter",
+        "how do I compare to this job description?",
+        "what will they push back on?",
+    ],
+}
+
+# Tuned against the reference set: correct routes score 0.38-0.60 with margins
+# above 0.25, so these thresholds reject genuinely ambiguous queries only.
+MIN_SCORE = 0.35
+MIN_MARGIN = 0.10
+
+
+class SemanticRouter:
+    def __init__(self, embed_fn, references=None, min_score=MIN_SCORE, min_margin=MIN_MARGIN):
+        self.min_score = min_score
+        self.min_margin = min_margin
+        references = references or REFERENCE_QUERIES
+
+        self.routes = list(references)
+        centroids = np.stack([embed_fn(references[route]).mean(axis=0) for route in self.routes])
+        norms = np.linalg.norm(centroids, axis=1, keepdims=True)
+        self.centroids = centroids / np.where(norms == 0, 1, norms)
+        self.embed_fn = embed_fn
+
+    def scores(self, query) -> dict:
+        vector = self.embed_fn([query])[0]
+        norm = np.linalg.norm(vector)
+        if norm:
+            vector = vector / norm
+        return dict(zip(self.routes, (self.centroids @ vector).tolist()))
+
+    def route(self, query) -> str:
+        # Defensive: an unroutable query must never crash the turn.
+        if not isinstance(query, str) or not query.strip():
+            return FULL
+
+        scores = self.scores(query)
+        ranked = sorted(scores.items(), key=lambda item: item[1], reverse=True)
+        (winner, top), (_, runner_up) = ranked[0], ranked[1]
+
+        if winner == FULL:
+            return FULL
+        # Leaving the profile behind requires confidence; FULL is the safe default.
+        if top < self.min_score or (top - runner_up) < self.min_margin:
+            return FULL
+        return winner

tests/conftest.py

@@ -1,5 +1,30 @@
+"""Test bootstrap.
+
+The environment is pinned here before any application module is imported, so
+the suite never reads the developer's real .env or personal documents and runs
+identically on a clean CI machine.
+"""
+
+import atexit
+import os
+import shutil
 import sys
+import tempfile
 from pathlib import Path
 
-# Tests import the application modules from the project root.
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+_FIXTURE_DIR = tempfile.mkdtemp(prefix="job-chat-tests-")
+(Path(_FIXTURE_DIR) / "fixture.md").write_text("# Fixture profile", encoding="utf-8")
+atexit.register(shutil.rmtree, _FIXTURE_DIR, True)
+
+# load_dotenv() does not override variables that are already set, so these win
+# over any real .env on a developer machine.
+os.environ["GROQ_API_KEY"] = "test-key-not-used"
+os.environ["DATA_DIR"] = _FIXTURE_DIR
+os.environ["CANDIDATE_NAME"] = "Test Candidate"
+# Set to empty rather than deleted: load_dotenv() skips keys already present, so
+# an empty value keeps real Langfuse credentials out and stops the suite emitting
+# traces to a live project.
+for _optional in ("LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY", "LANGFUSE_HOST", "LANGFUSE_BASE_URL"):
+    os.environ[_optional] = ""

tests/test_config.py

@@ -73,9 +73,16 @@ def test_overrides_are_read_from_the_environment(base_env, monkeypatch):
     assert settings.max_history_turns == 3
 
 
-def test_relative_data_dir_resolves_against_the_project_root(base_env, monkeypatch):
-    monkeypatch.setenv("DATA_DIR", "data")
-    assert get_settings().data_dir == config.PROJECT_ROOT / "data"
+def test_relative_data_dir_resolves_against_the_project_root(base_env, monkeypatch, tmp_path):
+    """A relative DATA_DIR must not depend on the process working directory."""
+    project_root = tmp_path / "project"
+    (project_root / "docs").mkdir(parents=True)
+    (project_root / "docs" / "resume.md").write_text("# Resume", encoding="utf-8")
+
+    monkeypatch.setattr(config, "PROJECT_ROOT", project_root)
+    monkeypatch.setenv("DATA_DIR", "docs")
+
+    assert get_settings().data_dir == project_root / "docs"
 
 
 class TestLangfuseHost:

tests/test_graph.py

@@ -3,7 +3,7 @@
 import pytest
 from langchain_core.messages import AIMessage, HumanMessage, trim_messages
 
-from graph import route_action
+from graph import latest_text, route_action
 
 
 @pytest.mark.parametrize(
@@ -14,7 +14,6 @@ from graph import route_action
         ("cover_letter", "answer"),
         ("", "answer"),
         (None, "answer"),
-        ("unknown", "answer"),
     ],
 )
 def test_only_ats_routes_to_structured_output(action, expected):
@@ -25,6 +24,87 @@ def test_missing_action_key_falls_back_to_chat():
     assert route_action({}) == "answer"
 
 
+class StubRouter:
+    def __init__(self, decision):
+        self.decision = decision
+        self.seen = []
+
+    def route(self, query):
+        self.seen.append(query)
+        return self.decision
+
+
+@pytest.mark.parametrize(
+    "decision,expected",
+    [("trivial", "trivial_answer"), ("specific", "rag_answer"), ("full", "answer")],
+)
+def test_free_chat_follows_the_semantic_router(decision, expected):
+    state = {"action": "", "messages": [HumanMessage(content="a question")]}
+    assert route_action(state, semantic_router=StubRouter(decision)) == expected
+
+
+@pytest.mark.parametrize("action", ["review", "cover_letter"])
+def test_preset_actions_bypass_the_router_and_keep_full_context(action):
+    """A retrieval miss inside a review or cover letter would drop real evidence."""
+    stub = StubRouter("trivial")
+    state = {"action": action, "messages": [HumanMessage(content="hello")]}
+    assert route_action(state, semantic_router=stub) == "answer"
+    assert stub.seen == []
+
+
+def test_the_ats_action_never_reaches_the_router():
+    """Retrieval could omit a skill and silently corrupt the score."""
+    stub = StubRouter("specific")
+    state = {"action": "ats", "messages": [HumanMessage(content="hi")]}
+    assert route_action(state, semantic_router=stub) == "ats_analysis"
+    assert stub.seen == []
+
+
+def test_the_router_sees_the_latest_message():
+    stub = StubRouter("full")
+    state = {"action": "", "messages": [HumanMessage(content="old"), HumanMessage(content="newest")]}
+    route_action(state, semantic_router=stub)
+    assert stub.seen == ["newest"]
+
+
+class TestContentBlocks:
+    """Checkpointed messages come back with list content, not a plain string.
+
+    Reading .content directly crashed the first real conversation with
+    'list object has no attribute strip'.
+    """
+
+    def test_latest_text_reads_plain_string_content(self):
+        assert latest_text([HumanMessage(content="hello")]) == "hello"
+
+    def test_latest_text_reads_block_content(self):
+        blocks = [HumanMessage(content=[{"type": "text", "text": "hi there"}])]
+        assert latest_text(blocks) == "hi there"
+
+    def test_latest_text_returns_a_real_string(self):
+        text = latest_text([HumanMessage(content=[{"type": "text", "text": "x"}])])
+        assert type(text) is str
+        assert text.strip() == "x"
+
+    def test_latest_text_handles_no_messages(self):
+        assert latest_text([]) == ""
+
+    def test_routing_survives_block_content(self):
+        stub = StubRouter("specific")
+        state = {"action": "", "messages": [HumanMessage(content=[{"type": "text", "text": "do I know Rust?"}])]}
+        assert route_action(state, semantic_router=stub) == "rag_answer"
+        assert stub.seen == ["do I know Rust?"]
+
+
+def test_router_rejects_non_string_queries_without_crashing():
+    from router import FULL, SemanticRouter
+    from tests.test_router import REFERENCES, fake_embed
+
+    router = SemanticRouter(fake_embed, references=REFERENCES)
+    for bad in ([{"type": "text", "text": "hi"}], None, 42):
+        assert router.route(bad) == FULL
+
+
 def conversation(turns):
     messages = []
     for i in range(turns):

tests/test_isolation.py

@@ -0,0 +1,27 @@
+"""The suite must not touch the developer's real credentials or documents.
+
+Without this, load_dotenv() silently pulls the real .env into every test run,
+which sent traces to the live Langfuse project.
+"""
+
+from config import get_settings
+
+
+def test_real_langfuse_credentials_are_not_loaded():
+    settings = get_settings()
+    assert settings.langfuse_public_key == ""
+    assert settings.langfuse_secret_key == ""
+
+
+def test_tracing_is_disabled_during_tests():
+    assert get_settings().tracing_enabled is False
+
+
+def test_the_real_groq_key_is_not_used():
+    assert get_settings().groq_api_key == "test-key-not-used"
+
+
+def test_personal_documents_are_not_read():
+    data_dir = get_settings().data_dir
+    assert data_dir.name != "data"
+    assert [p.name for p in data_dir.glob("*.md")] == ["fixture.md"]

tests/test_retrieval.py

@@ -0,0 +1,87 @@
+"""Chunking and retrieval, with a bag-of-words embedder so tests stay offline."""
+
+import numpy as np
+import pytest
+
+from dataloader import SEPARATOR
+from retrieval import ProfileIndex, chunk_documents
+
+VOCAB = ["faiss", "kubernetes", "volunteer", "python", "rust"]
+
+
+def fake_embed(texts):
+    vectors = []
+    for text in texts:
+        lowered = text.lower()
+        vectors.append([float(word in lowered) for word in VOCAB])
+    return np.array(vectors, dtype=np.float32)
+
+
+def profile(*documents):
+    return SEPARATOR.join(documents)
+
+
+def test_chunks_carry_their_source_label():
+    text = profile("# Source: resume\n\nWorked with FAISS.", "# Source: volunteer\n\nTaught Python.")
+    chunks = chunk_documents(text)
+    assert any(c.startswith("[resume]") for c in chunks)
+    assert any(c.startswith("[volunteer]") for c in chunks)
+
+
+def test_content_survives_chunking():
+    chunks = chunk_documents(profile("# Source: resume\n\nWorked with FAISS."))
+    assert "Worked with FAISS." in "\n".join(chunks)
+
+
+def test_long_documents_split_into_several_chunks():
+    body = "\n\n".join(f"Paragraph {i} " + "x" * 200 for i in range(10))
+    chunks = chunk_documents(profile(f"# Source: resume\n\n{body}"), target_chars=300)
+    assert len(chunks) > 1
+
+
+def test_short_documents_stay_whole():
+    assert len(chunk_documents(profile("# Source: resume\n\nShort."))) == 1
+
+
+def test_empty_input_yields_no_chunks():
+    assert chunk_documents("") == []
+
+
+def test_documents_without_a_source_header_still_chunk():
+    chunks = chunk_documents("Just a body with no header.")
+    assert len(chunks) == 1
+    assert "Just a body" in chunks[0]
+
+
+class TestSearch:
+    @pytest.fixture
+    def index(self):
+        return ProfileIndex(
+            ["[resume] Built a FAISS index", "[volunteer] Volunteer teaching", "[projects] Python tooling"],
+            fake_embed,
+        )
+
+    def test_search_ranks_the_matching_chunk_first(self, index):
+        assert "FAISS" in index.search("faiss", k=1)[0]
+        assert "Volunteer" in index.search("volunteer", k=1)[0]
+
+    def test_search_respects_k(self, index):
+        assert len(index.search("python", k=2)) == 2
+
+    def test_k_larger_than_the_corpus_is_safe(self, index):
+        assert len(index.search("python", k=99)) == 3
+
+    def test_empty_query_returns_nothing(self, index):
+        assert index.search("   ") == []
+
+    def test_search_text_joins_results(self, index):
+        assert "---" in index.search_text("python", k=2)
+
+    def test_search_text_reports_when_nothing_is_found(self, index):
+        assert "No relevant excerpts" in index.search_text("", k=3)
+
+
+def test_an_empty_index_does_not_crash():
+    empty = ProfileIndex([], fake_embed)
+    assert empty.search("anything") == []
+    assert "No relevant excerpts" in empty.search_text("anything")

tests/test_router.py

@@ -0,0 +1,97 @@
+"""Router logic, tested with a controlled embedder rather than the real model.
+
+Model quality is a separate concern; what matters here is that ambiguity falls
+back to the full profile instead of silently answering without evidence.
+"""
+
+import numpy as np
+import pytest
+
+from router import FULL, SPECIFIC, TRIVIAL, SemanticRouter
+
+REFERENCES = {TRIVIAL: ["GREET"], SPECIFIC: ["NARROW"], FULL: ["BROAD"]}
+AXIS = {"GREET": 0, "NARROW": 1, "BROAD": 2}
+
+
+def fake_embed(texts):
+    """One-hot per route keyword; anything else is equidistant from all three."""
+    vectors = []
+    for text in texts:
+        vector = np.zeros(3, dtype=np.float32)
+        for token, axis in AXIS.items():
+            if token in text:
+                vector[axis] = 1.0
+        if not vector.any():
+            vector[:] = 1 / np.sqrt(3)
+        vectors.append(vector)
+    return np.array(vectors, dtype=np.float32)
+
+
+@pytest.fixture
+def router():
+    return SemanticRouter(fake_embed, references=REFERENCES)
+
+
+@pytest.mark.parametrize(
+    "query,expected",
+    [("GREET", TRIVIAL), ("NARROW", SPECIFIC), ("BROAD", FULL)],
+)
+def test_confident_queries_reach_their_route(router, query, expected):
+    assert router.route(query) == expected
+
+
+def test_ambiguous_queries_fall_back_to_full(router):
+    """Equidistant from every route: answering without the profile is the costly error."""
+    assert router.route("nothing in particular") == FULL
+
+
+def test_a_tie_between_trivial_and_specific_falls_back_to_full(router):
+    assert router.route("GREET NARROW") == FULL
+
+
+@pytest.mark.parametrize("query", ["", "   ", None])
+def test_empty_queries_fall_back_to_full(router, query):
+    assert router.route(query) == FULL
+
+
+def test_a_high_threshold_forces_the_safe_route():
+    """An exact match scores 1.0 here, so the bar has to sit above it."""
+    strict = SemanticRouter(fake_embed, references=REFERENCES, min_score=1.1)
+    assert strict.route("GREET") == FULL
+
+
+def test_a_wide_margin_requirement_forces_the_safe_route():
+    strict = SemanticRouter(fake_embed, references=REFERENCES, min_margin=1.1)
+    assert strict.route("NARROW") == FULL
+
+
+def test_shipped_thresholds_leave_room_for_a_confident_match():
+    from router import MIN_MARGIN, MIN_SCORE
+
+    assert 0 < MIN_SCORE < 1
+    assert 0 < MIN_MARGIN < 1
+
+
+def test_scores_cover_every_route(router):
+    assert set(router.scores("GREET")) == {TRIVIAL, SPECIFIC, FULL}
+
+
+def test_centroids_are_normalised(router):
+    assert np.allclose(np.linalg.norm(router.centroids, axis=1), 1.0)
+
+
+class TestRealReferenceSet:
+    """The shipped reference queries must be well formed."""
+
+    def test_every_route_has_examples(self):
+        from router import REFERENCE_QUERIES
+
+        assert set(REFERENCE_QUERIES) == {TRIVIAL, SPECIFIC, FULL}
+        for examples in REFERENCE_QUERIES.values():
+            assert len(examples) >= 5
+
+    def test_examples_are_unique_across_routes(self):
+        from router import REFERENCE_QUERIES
+
+        seen = [q for examples in REFERENCE_QUERIES.values() for q in examples]
+        assert len(seen) == len(set(seen))

tests/test_temperature.py

@@ -0,0 +1,39 @@
+"""Drafting uses a higher temperature than analysis."""
+
+import pytest
+
+import config
+from config import get_settings
+from graph import DRAFTING_ACTIONS, build_llm
+
+
+def test_drafting_is_warmer_than_analysis():
+    settings = get_settings()
+    assert settings.drafting_temperature > settings.temperature
+
+
+def test_only_the_cover_letter_drafts():
+    assert DRAFTING_ACTIONS == {"cover_letter"}
+
+
+def test_default_temperatures():
+    assert config.DEFAULT_TEMPERATURE == 0.0
+    assert 0 < config.DEFAULT_DRAFTING_TEMPERATURE < 1
+
+
+def test_build_llm_defaults_to_the_analysis_temperature():
+    # ChatGroq clamps an exact 0.0 to 1e-08, since Groq rejects zero.
+    assert build_llm().temperature == pytest.approx(get_settings().temperature, abs=1e-6)
+
+
+def test_build_llm_accepts_an_override():
+    assert build_llm(0.4).temperature == 0.4
+
+
+def test_drafting_temperature_is_configurable(monkeypatch):
+    monkeypatch.setenv("LLM_DRAFTING_TEMPERATURE", "0.9")
+    get_settings.cache_clear()
+    try:
+        assert get_settings().drafting_temperature == 0.9
+    finally:
+        get_settings.cache_clear()