ocr, email writing, rag

.gitignore

@@ -8,3 +8,5 @@ __pycache__/
 # LangGraph checkpoints
 checkpoints.sqlite
 checkpoints.sqlite-*
+
+experiment.ipynb

Dockerfile

@@ -1,16 +0,0 @@
-FROM python:3.13
-WORKDIR /
-
-# Install the application dependencies
-COPY requirements.txt ./
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Copy in the source code
-COPY src ./src
-EXPOSE 8080
-
-# Setup an app user so the container doesn't run as the root user
-RUN useradd app
-USER app
-
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

README.md

@@ -46,7 +46,7 @@ pip install -r requirements.txt
 **2. Configure `.env`** in the project root (optional if you will paste your key into the UI):
 
 ```ini
-OPENROUTER_API_KEY=...            # optional; can also be entered in the UI
+OPENROUTER_API_KEY=...            # required to use the model; can also be entered in the UI
 CANDIDATE_NAME=Your Name        # used in the system prompt
 
 # Optional — Langfuse tracing. Tracing turns on only when both keys are present.
@@ -57,16 +57,17 @@ LANGFUSE_HOST=https://us.cloud.langfuse.com
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `OPENROUTER_API_KEY` | — | Optional. If omitted, paste a key into the app's OpenRouter API key panel. |
+| `OPENROUTER_API_KEY` | — | Required to use the model. Set it here or paste a key into the always-visible UI field. |
 | `CANDIDATE_NAME` | `the candidate` | Your name, used in the system prompt. |
 | `OPENROUTER_MODEL` | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free` | OpenRouter model id. |
 | `LLM_TEMPERATURE` | `0.0` | Sampling temperature. |
-| `LLM_MAX_TOKENS` | `3000` | Response cap for ordinary chat. See the token budget note below. |
-| `SKILL_MAX_TOKENS` | `6500` | Response cap for the four skills (review, ATS, cover letter, email). |
+| `LLM_MAX_TOKENS` | `20000` | Response cap for ordinary chat. See the token budget note below. |
+| `SKILL_MAX_TOKENS` | `6500` | Response cap for prose skills (review, cover letter, email). |
+| `ATS_MAX_TOKENS` | `12000` | Response cap for ATS structured output. Increase only if the selected model supports it. |
 | `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. |
+| `RETRIEVAL_TOP_K` | `10` | 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` (alias: `LANGFUSE_BASE_URL`) | `https://cloud.langfuse.com` | Langfuse region. Use `https://us.cloud.langfuse.com` if your keys are US. |
@@ -77,9 +78,9 @@ LANGFUSE_HOST=https://us.cloud.langfuse.com
 python app.py                   # http://localhost:7860
 ```
 
-If you did not set `OPENROUTER_API_KEY` in `.env`, paste it into the **OpenRouter API key** panel and select **Connect key**. The key stays in server memory for that browser session and is not written to disk. Only enter a key when you trust the server running this app.
+If you did not set `OPENROUTER_API_KEY` in `.env`, paste it into the **OpenRouter API key** field and select **Connect key**. An API key is required to use the model. A key entered in the UI stays in server memory for that browser session and is not written to disk. Only enter a key when you trust the server running this app.
 
-Upload one or more PDF, DOCX, Markdown, or text files in **Your profile**. The app converts them to Markdown in memory and loads them into the profile pipeline; a later upload replaces the current profile. Uploads are not written to the project `data/` directory. Add a job description in **Target role** before chatting or using a skill button; requests without one do not call the model.
+Upload one or more PDF, DOCX, Markdown, or text files in **Your profile**. The app converts them to Markdown in memory and loads them into the profile pipeline; a later upload replaces the current profile. For PDFs, RapidOCR with ONNX Runtime is used as a fallback if MarkItDown fails or extracts no text, including for scanned/image-only pages. Uploads are not written to the project `data/` directory. Add a job description in **Target role** before chatting or using a skill button; requests without one do not call the model.
 
 Select
 **Stop** beside the message box to cancel a response that's being generated; any text already
@@ -159,6 +160,11 @@ checkpoint but are not resent, so cost per turn stays flat however long the conv
 The percentage is computed in Python from the list lengths, so the score cannot contradict the
 lists it is derived from.
 
+**Retrieval.** Uploaded profile documents are split into 100-word windows with 15 words of
+overlap, keeping adjacent context available to narrow searches. The `rag_answer` index combines
+BM25 keyword rankings with FAISS cosine-similarity rankings over FastEmbed vectors, then merges
+the results with reciprocal-rank fusion. This hybrid index is rebuilt for each uploaded profile.
+
 **Routing rules.** Every skill button bypasses the router and receives the full profile: a
 retrieval miss inside an ATS score or a resume review would silently drop real evidence. For free
 chat, the router compares the question against the centroid of reference examples per route
@@ -193,7 +199,7 @@ every push to `main` and every pull request.
 
 ## Token budget
 
-`LLM_MAX_TOKENS` defaults to 3,000 to cap the response size. A full-profile request also sends
-your profile (~3,900 tokens), the job description, and recent conversation history. OpenRouter
-model context windows and account limits vary, so shorten the job description or lower
-`LLM_MAX_TOKENS` if a request exceeds the model's limits.
+`LLM_MAX_TOKENS` defaults to 20,000 to cap ordinary chat responses. ATS uses its own
+12,000-token cap because it returns a structured classification of every job-description
+keyword. OpenRouter model output limits vary; if ATS reports a truncated response, choose a
+model with a larger output limit or lower `ATS_MAX_TOKENS` to fit the selected model.

app.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 import gradio as gr
 from langchain_core.messages import AIMessage, HumanMessage
+from openai import LengthFinishReasonError
 
 from config import ConfigError, get_settings
 from dataloader import convert_uploaded_documents
@@ -37,6 +38,28 @@ def graph_for_session(session_id):
     return session.get("graph") if session else None
 
 
+def request_error_detail(exc):
+    if isinstance(exc, LengthFinishReasonError):
+        return (
+            "The ATS report exceeded the model's response-token limit and was incomplete. "
+            "Retry with a shorter job description, choose a model with a larger output "
+            "limit, or raise ATS_MAX_TOKENS if the model supports it."
+        )
+
+    detail = str(exc)
+    if "rate_limit" in detail or "429" in detail:
+        return (
+            "OpenRouter rate limit reached. Check your account's limits or wait "
+            "before retrying."
+        )
+    if "413" in detail:
+        return (
+            "The request is too large for the OpenRouter model. Shorten the job "
+            "description or lower LLM_MAX_TOKENS, then retry."
+        )
+    return detail
+
+
 def connect_api_key(api_key, session_id):
     api_key = (api_key or "").strip()
     if not api_key:
@@ -190,17 +213,7 @@ def stream_response(
                     yield chat_history
     except Exception as exc:
         logger.exception("Request failed")
-        detail = str(exc)
-        if "rate_limit" in detail or "429" in detail:
-            detail = (
-                "OpenRouter rate limit reached. Check your account's limits or wait "
-                "before retrying."
-            )
-        elif "413" in detail:
-            detail = (
-                "The request is too large for the OpenRouter model. Shorten the job "
-                "description or lower LLM_MAX_TOKENS, then retry."
-            )
+        detail = request_error_detail(exc)
         chat_history[-1]["content"] = f"**Request failed.** {detail}"
         yield chat_history
 
@@ -211,21 +224,19 @@ with gr.Blocks(title="job-chat", fill_height=True, analytics_enabled=False) as d
 
     gr.Markdown("## Job chat")
     gr.Markdown("Ask about your background, draft interview answers, or test your fit against a role.")
-    with gr.Accordion(
-        "OpenRouter API key", open=not bool(SETTINGS.openrouter_api_key)
-    ):
-        api_key_box = gr.Textbox(
-            label="Paste your OpenRouter API key",
-            placeholder="sk-or-v1-…",
-            type="password",
-            show_label=True,
-        )
-        connect_key_btn = gr.Button("Connect key")
-        key_status = gr.Markdown(
-            "Using the server-configured key."
-            if SETTINGS.openrouter_api_key
-            else "Your key is kept in server memory for this browser session and is not written to disk."
-        )
+    gr.Markdown("### OpenRouter API key")
+    api_key_box = gr.Textbox(
+        label="Paste your OpenRouter API key",
+        placeholder="sk-or-v1-…",
+        type="password",
+        show_label=True,
+    )
+    connect_key_btn = gr.Button("Connect key")
+    key_status = gr.Markdown(
+        "Using the server-configured key."
+        if SETTINGS.openrouter_api_key
+        else "An API key is required to use the model. Your key is kept in server memory for this browser session and is not written to disk."
+    )
 
     with gr.Row(equal_height=False):
         with gr.Column(scale=1):

config.py

@@ -21,8 +21,11 @@ DEFAULT_DRAFTING_TEMPERATURE = 0.4
 # truncated them mid-answer. This leaves room for the profile, job description,
 # and conversation history while avoiding an unnecessarily large response cap.
 DEFAULT_MAX_TOKENS = 20000
-# Skill output (cover letters, reviews, ATS reports) gets its own response cap.
+# Prose skill output gets its own response cap.
 DEFAULT_SKILL_MAX_TOKENS = 6500
+# ATS returns a structured classification for every keyword, so it needs more
+# output room than the prose skills.
+DEFAULT_ATS_MAX_TOKENS = 12000
 DEFAULT_LANGFUSE_HOST = "https://cloud.langfuse.com"
 DEFAULT_CHECKPOINT_DB = "checkpoints.sqlite"
 # Turns of conversation replayed to the model. Older turns stay in the
@@ -30,7 +33,7 @@ DEFAULT_CHECKPOINT_DB = "checkpoints.sqlite"
 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
+DEFAULT_RETRIEVAL_TOP_K = 10
 
 
 class ConfigError(RuntimeError):
@@ -46,6 +49,7 @@ class Settings:
     drafting_temperature: float
     max_tokens: int
     skill_max_tokens: int
+    ats_max_tokens: int
     max_history_turns: int
     embedding_model: str
     retrieval_top_k: int
@@ -94,6 +98,7 @@ def get_settings(require_api_key=True) -> Settings:
         drafting_temperature=_get_float("LLM_DRAFTING_TEMPERATURE", DEFAULT_DRAFTING_TEMPERATURE),
         max_tokens=_get_int("LLM_MAX_TOKENS", DEFAULT_MAX_TOKENS),
         skill_max_tokens=_get_int("SKILL_MAX_TOKENS", DEFAULT_SKILL_MAX_TOKENS),
+        ats_max_tokens=_get_int("ATS_MAX_TOKENS", DEFAULT_ATS_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),

dataloader.py

@@ -1,8 +1,74 @@
+import logging
+from functools import lru_cache
 from pathlib import Path
 
 SEPARATOR = "\n\n" + "-" * 60 + "\n\n"
 SUPPORTED_UPLOAD_EXTENSIONS = {".pdf", ".docx", ".md", ".txt"}
 
+logger = logging.getLogger(__name__)
+
+
+@lru_cache(maxsize=1)
+def _get_ocr_engine():
+    from rapidocr import RapidOCR
+
+    return RapidOCR()
+
+
+def _convert_pdf_with_ocr(path):
+    """Render a PDF page-by-page and extract text with RapidOCR."""
+    import pypdfium2
+
+    ocr = _get_ocr_engine()
+    pdf = pypdfium2.PdfDocument(str(path))
+    pages = []
+    try:
+        for page_number in range(len(pdf)):
+            page = pdf[page_number]
+            try:
+                image = page.render(scale=2).to_numpy()
+                result = ocr(image)
+                if result is not None and result.txts:
+                    pages.append("\n".join(text for text in result.txts if text.strip()))
+            finally:
+                page.close()
+    finally:
+        pdf.close()
+    return "\n\n".join(pages)
+
+
+def _convert_pdf(path):
+    """Prefer MarkItDown and use OCR when extraction fails or returns no text."""
+    try:
+        from markitdown import MarkItDown
+
+        content = MarkItDown().convert(str(path)).markdown
+    except Exception as exc:
+        markitdown_error = exc
+        logger.warning(
+            "MarkItDown failed for PDF %s; trying RapidOCR: %s",
+            path.name,
+            exc,
+        )
+    else:
+        if content and content.strip():
+            return content
+        logger.info("MarkItDown returned no text for PDF %s; trying RapidOCR.", path.name)
+        markitdown_error = None
+
+    try:
+        return _convert_pdf_with_ocr(path)
+    except Exception as ocr_exc:
+        markitdown_detail = (
+            f"MarkItDown failed: {markitdown_error}"
+            if markitdown_error
+            else "MarkItDown returned no readable text"
+        )
+        raise RuntimeError(
+            f"{markitdown_detail}; RapidOCR could not read PDF "
+            f"'{path.name}': {ocr_exc}"
+        ) from ocr_exc
+
 
 def format_documents(documents):
     """Combine named Markdown strings into the profile context."""
@@ -33,6 +99,8 @@ def convert_uploaded_documents(files):
 
         if extension in {".md", ".txt"}:
             content = path.read_text(encoding="utf-8-sig")
+        elif extension == ".pdf":
+            content = _convert_pdf(path)
         else:
             if converter is None:
                 from markitdown import MarkItDown

graph.py

@@ -132,10 +132,11 @@ def build_graph(api_key=None, profile_data=None):
     rag_chain = build_rag_prompt() | llm
     trivial_chain = build_trivial_prompt() | llm
     structured_llm = build_llm(
-        max_tokens=settings.skill_max_tokens, api_key=api_key
+        max_tokens=settings.ats_max_tokens, api_key=api_key
     ).with_structured_output(ATSAnalysis)
 
-    index = ProfileIndex(chunk_documents(profile_data), embed)
+    chunks = chunk_documents(profile_data)
+    index = ProfileIndex(chunks, embed)
     semantic_router = SemanticRouter(embed)
     logger.info("Indexed %d profile chunks for retrieval.", len(index.chunks))
 

requirements.txt

@@ -1,4 +1,7 @@
 fastembed==0.8.0
+bm25s==0.3.15
+faiss-cpu==1.15.1
+PyStemmer==3.1.0
 langchain==1.3.14
 langchain-core==1.5.1
 langchain-openai==1.1.3
@@ -7,6 +10,9 @@ langgraph-checkpoint-sqlite==3.1.1
 langfuse==4.14.3
 python-dotenv==1.2.2
 markitdown[docx,pdf]==0.1.9
+rapidocr==3.10.0
+onnxruntime==1.31.1
+pypdfium2==5.14.0
 
 # Makes Python trust the OS certificate store. Required on networks that do
 # TLS inspection (corporate proxy / antivirus); harmless elsewhere.

retrieval.py

@@ -1,24 +1,28 @@
-"""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.
-"""
+"""Hybrid BM25 and FAISS retrieval over the uploaded profile."""
 
+import bm25s
+import faiss
 import numpy as np
+import Stemmer
 
 from dataloader import SEPARATOR
 
-TARGET_CHUNK_CHARS = 600
+WORDS_PER_CHUNK = 100
+CHUNK_OVERLAP_WORDS = 15
+RRF_K = 60
+
 
+def chunk_documents(
+    profile_text,
+    words_per_chunk=WORDS_PER_CHUNK,
+    overlap=CHUNK_OVERLAP_WORDS,
+):
+    """Split each source document into word windows with exact overlap."""
+    if words_per_chunk <= 0 or overlap < 0 or overlap >= words_per_chunk:
+        raise ValueError("Require words_per_chunk > overlap >= 0")
 
-def chunk_documents(profile_text, target_chars=TARGET_CHUNK_CHARS):
-    """Split the profile into retrievable chunks, each labelled with its source."""
     chunks = []
+    step = words_per_chunk - overlap
 
     for document in profile_text.split(SEPARATOR):
         document = document.strip()
@@ -26,55 +30,81 @@ def chunk_documents(profile_text, target_chars=TARGET_CHUNK_CHARS):
             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))
+        has_source = lines[0].startswith("# Source:")
+        source = lines[0].removeprefix("# Source:").strip() if has_source else ""
+        body = "\n".join(lines[1:]).strip() if has_source else document
+        words = body.split()
+
+        for start in range(0, len(words), step):
+            chunk = " ".join(words[start : start + words_per_chunk])
+            if chunk:
+                chunks.append(_label(source, chunk))
+            if start + words_per_chunk >= len(words):
+                break
 
     return chunks
 
 
-def _label(source, paragraphs):
-    body = "\n\n".join(paragraphs)
-    return f"[{source}]\n{body}" if source else body
+def _label(source, text):
+    return f"[{source}]\n{text}" if source else text
+
+
+def _reciprocal_rank_fusion(*rankings, k=RRF_K):
+    scores = {}
+    for ranking in rankings:
+        for rank, chunk_id in enumerate(ranking, start=1):
+            if chunk_id >= 0:
+                scores[chunk_id] = scores.get(chunk_id, 0.0) + 1.0 / (k + rank)
+    return sorted(scores, key=scores.get, reverse=True)
 
 
 class ProfileIndex:
     def __init__(self, chunks, embed_fn):
         self.chunks = list(chunks)
+        self.embed_fn = embed_fn
+        self.stemmer = Stemmer.Stemmer("english")
+
         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)
+            tokens = bm25s.tokenize(
+                self.chunks,
+                stopwords="en",
+                stemmer=self.stemmer,
+                show_progress=False,
+            )
+            self.bm25 = bm25s.BM25()
+            self.bm25.index(tokens, show_progress=False)
+
+            vectors = np.ascontiguousarray(embed_fn(self.chunks), dtype=np.float32)
+            faiss.normalize_L2(vectors)
+            self.faiss_index = faiss.IndexFlatIP(vectors.shape[1])
+            self.faiss_index.add(vectors)
         else:
-            self.vectors = np.zeros((0, 0), dtype=np.float32)
-        self.embed_fn = embed_fn
+            self.bm25 = None
+            self.faiss_index = None
 
     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 chunks ranked by reciprocal-rank fusion of BM25 and cosine."""
+        if not self.chunks or not query.strip() or k <= 0:
             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]
+        candidate_count = min(k, len(self.chunks))
+        query_tokens = bm25s.tokenize(
+            [query],
+            stopwords="en",
+            stemmer=self.stemmer,
+            show_progress=False,
+        )
+        bm25_ids, _ = self.bm25.retrieve(
+            query_tokens,
+            k=candidate_count,
+            show_progress=False,
+        )
+        dense_query = np.ascontiguousarray(self.embed_fn([query]), dtype=np.float32)
+        faiss.normalize_L2(dense_query)
+        _, faiss_ids = self.faiss_index.search(dense_query, candidate_count)
+
+        fused_ids = _reciprocal_rank_fusion(bm25_ids[0], faiss_ids[0])
+        return [self.chunks[i] for i in fused_ids[:candidate_count]]
 
     def search_text(self, query, k=5):
         found = self.search(query, k)

skills/email-writing.md

@@ -29,7 +29,6 @@ Construct the email body using this exact 3-part sequence:
 - **Do Not Highlight Gaps:** If the user's data does not perfectly match every requirement of the job description, focus entirely on the overlapping strengths. Do not apologize for or acknowledge missing skills.
 
 ## Execution Steps
-1. **Analyze:** Ingest all provided background material. Silently discard anything irrelevant to the target job.
-2. **Draft Subject Lines:** Generate 3 highly optimized, scannable subject line options (e.g., "[Role] Application - [Name] - [Top Credential]").
-3. **Draft the Email:** Write the email strictly following the structure and tone rules above. Target length: ~100 words.
-4. **Format Output:** Present the subject lines, the email draft, and a brief 1-bullet explanation of why those specific bullets were chosen.
+1. **Think privately:** Compare the job description with the provided background, select only relevant and supported evidence, and plan a concise email. Do not reveal analysis or reasoning.
+2. **Draft the email:** Follow the structure and tone rules above. Use one subject line, not options. Do not invent facts or metrics, and do not include bracketed placeholders; omit unsupported details instead.
+3. **Return only the finished email:** Include a single `Subject:` line, greeting, email body, and sign-off. Do not add a heading, introduction, alternatives, explanation, rationale, suggestions, or any other text outside the email.

tests/test_app.py

@@ -18,6 +18,18 @@ def test_chat_without_job_description_does_not_access_the_graph(monkeypatch):
     assert "Paste a job description" in result[0][-1]["content"]
 
 
+def test_length_limit_error_explains_how_to_retry():
+    from types import SimpleNamespace
+
+    from openai import LengthFinishReasonError
+
+    completion = SimpleNamespace(usage=None)
+    detail = app.request_error_detail(LengthFinishReasonError(completion=completion))
+
+    assert "ATS report exceeded" in detail
+    assert "ATS_MAX_TOKENS" in detail
+
+
 def test_upload_builds_a_per_session_graph(monkeypatch, tmp_path):
     markdown_file = tmp_path / "resume.md"
     markdown_file.write_text("# Resume", encoding="utf-8")

tests/test_config.py

@@ -14,7 +14,7 @@ def clear_settings_cache():
 @pytest.fixture
 def base_env(monkeypatch):
     monkeypatch.setenv("OPENROUTER_API_KEY", "test-key")
-    for name in ("OPENROUTER_MODEL", "LLM_TEMPERATURE", "LLM_MAX_TOKENS", "SKILL_MAX_TOKENS", "MAX_HISTORY_TURNS",
+    for name in ("OPENROUTER_MODEL", "LLM_TEMPERATURE", "LLM_MAX_TOKENS", "SKILL_MAX_TOKENS", "ATS_MAX_TOKENS", "MAX_HISTORY_TURNS",
                  "CANDIDATE_NAME", "DATA_DIR", "LANGFUSE_HOST", "LANGFUSE_BASE_URL",
                  "LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY"):
         monkeypatch.delenv(name, raising=False)
@@ -34,7 +34,7 @@ def test_api_key_can_be_supplied_later_by_the_ui(base_env, monkeypatch):
     assert settings.openrouter_api_key == ""
 
 
-@pytest.mark.parametrize("var", ["LLM_TEMPERATURE", "LLM_MAX_TOKENS", "SKILL_MAX_TOKENS", "MAX_HISTORY_TURNS"])
+@pytest.mark.parametrize("var", ["LLM_TEMPERATURE", "LLM_MAX_TOKENS", "SKILL_MAX_TOKENS", "ATS_MAX_TOKENS", "MAX_HISTORY_TURNS"])
 def test_non_numeric_values_are_rejected(base_env, monkeypatch, var):
     monkeypatch.setenv(var, "hot")
     with pytest.raises(ConfigError, match=var):
@@ -49,19 +49,30 @@ def test_defaults_apply_when_optional_vars_are_unset(base_env):
     assert settings.max_tokens == config.DEFAULT_MAX_TOKENS
     assert settings.max_history_turns == config.DEFAULT_MAX_HISTORY_TURNS
     assert settings.skill_max_tokens == config.DEFAULT_SKILL_MAX_TOKENS == 6500
+    assert settings.ats_max_tokens == config.DEFAULT_ATS_MAX_TOKENS == 12000
     assert settings.candidate_name == "the candidate"
 
 
 def test_overrides_are_read_from_the_environment(base_env, monkeypatch):
     monkeypatch.setenv("OPENROUTER_MODEL", "some/other-model")
     monkeypatch.setenv("LLM_TEMPERATURE", "0.7")
+    monkeypatch.setenv("ATS_MAX_TOKENS", "9000")
     monkeypatch.setenv("MAX_HISTORY_TURNS", "3")
     settings = get_settings()
     assert settings.model == "some/other-model"
     assert settings.temperature == 0.7
+    assert settings.ats_max_tokens == 9000
     assert settings.max_history_turns == 3
 
 
+def test_ats_llm_uses_its_separate_response_cap(base_env):
+    from graph import build_llm
+
+    settings = get_settings()
+
+    assert build_llm(max_tokens=settings.ats_max_tokens).max_tokens == 12000
+
+
 def test_settings_do_not_require_a_data_directory(base_env, monkeypatch, tmp_path):
     monkeypatch.setenv("DATA_DIR", str(tmp_path / "missing"))
 

tests/test_dataloader.py

@@ -36,6 +36,66 @@ def test_uploaded_pdf_is_converted_to_markdown(tmp_path, monkeypatch):
     assert "# Converted resume" in convert_uploaded_documents([str(pdf)])
 
 
+@pytest.mark.parametrize("markitdown_result", ["", "raise"])
+def test_uploaded_pdf_falls_back_to_rapidocr(tmp_path, monkeypatch, markitdown_result):
+    import sys
+    from types import SimpleNamespace
+    import dataloader
+
+    pdf = tmp_path / "scanned.pdf"
+    pdf.write_bytes(b"fake pdf")
+
+    class FakeConverter:
+        def convert(self, _path):
+            if markitdown_result == "raise":
+                raise ValueError("No text layer")
+            return SimpleNamespace(markdown="  ")
+
+    class FakeBitmap:
+        def to_numpy(self):
+            return object()
+
+    class FakePage:
+        def render(self, scale):
+            assert scale == 2
+            return FakeBitmap()
+
+        def close(self):
+            pass
+
+    class FakePdfDocument:
+        def __init__(self, path):
+            assert path == str(pdf)
+
+        def __len__(self):
+            return 2
+
+        def __getitem__(self, _index):
+            return FakePage()
+
+        def close(self):
+            pass
+
+    class FakeOCR:
+        def __call__(self, _image):
+            return SimpleNamespace(txts=("recognized text",))
+
+    monkeypatch.setitem(
+        sys.modules, "markitdown", SimpleNamespace(MarkItDown=FakeConverter)
+    )
+    monkeypatch.setitem(
+        sys.modules,
+        "pypdfium2",
+        SimpleNamespace(PdfDocument=FakePdfDocument),
+    )
+    dataloader._get_ocr_engine.cache_clear()
+    monkeypatch.setattr(dataloader, "_get_ocr_engine", FakeOCR)
+
+    profile = convert_uploaded_documents([str(pdf)])
+
+    assert profile.count("recognized text") == 2
+
+
 def test_uploaded_unsupported_file_type_is_rejected(tmp_path):
     unsupported = tmp_path / "profile.exe"
     unsupported.write_text("not a document", encoding="utf-8")

tests/test_retrieval.py

@@ -34,11 +34,59 @@ def test_content_survives_chunking():
 
 
 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)
+    body = " ".join(f"word{i}" for i in range(40))
+    chunks = chunk_documents(
+        profile(f"# Source: resume\n\n{body}"),
+        words_per_chunk=10,
+        overlap=3,
+    )
     assert len(chunks) > 1
 
 
+def test_adjacent_chunks_overlap_by_the_requested_words():
+    body = " ".join(f"word{i}" for i in range(23))
+    chunks = chunk_documents(
+        profile(f"# Source: resume\n\n{body}"),
+        words_per_chunk=10,
+        overlap=3,
+    )
+    chunk_words = [chunk.split("]\n", 1)[1].split() for chunk in chunks]
+
+    assert all(
+        previous[-3:] == current[:3]
+        for previous, current in zip(chunk_words, chunk_words[1:])
+    )
+
+
+def test_chunks_do_not_cross_source_document_boundaries():
+    chunks = chunk_documents(
+        profile(
+            "# Source: resume\n\n" + " ".join(f"resume{i}" for i in range(12)),
+            "# Source: projects\n\n" + " ".join(f"project{i}" for i in range(12)),
+        ),
+        words_per_chunk=8,
+        overlap=2,
+    )
+
+    assert all(
+        ("resume" in chunk) != ("project" in chunk)
+        for chunk in chunks
+    )
+
+
+@pytest.mark.parametrize(
+    "words_per_chunk,overlap",
+    [(0, 0), (10, -1), (10, 10), (10, 11)],
+)
+def test_invalid_word_chunk_settings_are_rejected(words_per_chunk, overlap):
+    with pytest.raises(ValueError, match="words_per_chunk > overlap"):
+        chunk_documents(
+            "text",
+            words_per_chunk=words_per_chunk,
+            overlap=overlap,
+        )
+
+
 def test_short_documents_stay_whole():
     assert len(chunk_documents(profile("# Source: resume\n\nShort."))) == 1
 
@@ -68,12 +116,19 @@ class TestSearch:
     def test_search_respects_k(self, index):
         assert len(index.search("python", k=2)) == 2
 
+    def test_hybrid_search_returns_bm25_and_dense_matches(self, index):
+        results = index.search("volunteer", k=3)
+        assert "Volunteer" in results[0]
+
     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_non_positive_k_returns_nothing(self, index):
+        assert index.search("python", k=0) == []
+
     def test_search_text_joins_results(self, index):
         assert "---" in index.search_text("python", k=2)
 

tests/test_skills.py

@@ -1,4 +1,4 @@
-"""Skill files, registry, and the 6500-token cap."""
+"""Skill files, registry, and skill-specific response caps."""
 
 import pytest
 
@@ -47,7 +47,16 @@ def test_cover_letter_skill_requires_a_conventional_letter_only():
     assert "bullet points" in text
 
 
-def test_skill_responses_are_capped_at_6500_tokens():
+def test_email_skill_returns_only_one_final_email_without_explanation():
+    text = load_skill("email")
+    assert "one subject line, not options" in text
+    assert "Do not reveal analysis or reasoning" in text
+    assert "Return only the finished email" in text
+    assert "Do not add a heading, introduction, alternatives, explanation, rationale, suggestions" in text
+    assert "3 highly optimized" not in text
+
+
+def test_prose_skill_responses_are_capped_at_6500_tokens():
     assert get_settings().skill_max_tokens == 6500 == config.DEFAULT_SKILL_MAX_TOKENS