Upload 105 files

Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpango-1.0-0 \
+    libharfbuzz0b \
+    libpangoft2-1.0-0 \
+    libglib2.0-0 \
+    libgdk-pixbuf-2.0-0 \
+    libffi-dev \
+    shared-mime-info \
+    fonts-dejavu-core \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --upgrade pip && pip install -r requirements.txt
+
+COPY . .
+
+RUN mkdir -p output
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,14 +1,68 @@
 ---
-title: Draftme
-emoji: 💻
-colorFrom: indigo
-colorTo: blue
-sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
-app_file: app.py
+title: DraftMe
+sdk: docker
+app_port: 7860
 pinned: false
-short_description: Upload CV and get job-optimized resume under 1 minute
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# DraftMe
+
+DraftMe is an AI resume tailoring tool. Upload a PDF resume, paste a job description, choose a model, and generate a targeted one-page resume PDF.
+
+The app extracts structured information from the resume, parses the job posting, optimizes the resume against the role, validates the result, and renders the final HTML to PDF.
+
+## What It Does
+
+- Extracts resume content from uploaded PDFs with PyMuPDF
+- Parses job postings into title, company, requirements, keywords, and summary
+- Uses Modal-hosted vLLM endpoints for LLM inference
+- Lets users choose between Qwen and NVIDIA Nemotron backends
+- Runs validation filters for structure, length, hallucination risk, and keyword coverage
+- Shows live workflow telemetry while the resume is being generated
+- Renders the optimized resume to PDF with WeasyPrint
+
+## Models
+
+DraftMe currently supports:
+
+- Qwen 3.5 27B FP8
+- NVIDIA Nemotron 3 Nano 30B BF16
+
+Both models are served through OpenAI-compatible Modal endpoints.
+
+## Stack
+
+- Python 3.11
+- Gradio Server with custom HTML, CSS, and JavaScript UI
+- FastAPI / ASGI
+- Pydantic and Pydantic AI
+- OpenAI SDK for Modal vLLM calls
+- PyMuPDF for PDF text extraction
+- WeasyPrint for PDF rendering
+- Jinja2 resume templates
+
+## Local Run
+
+```bash
+uv run --with-requirements requirements.txt uvicorn app:app --host 127.0.0.1 --port 8801
+```
+
+Then open:
+
+```text
+http://127.0.0.1:8801
+```
+
+## Hugging Face Spaces
+
+This project is configured as a Docker Space because it serves a custom ASGI app instead of a standard Gradio Blocks interface.
+
+The container starts with:
+
+```bash
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+## Notes
+
+Generated PDFs are written to the local `output/` directory and are ignored during Space uploads.

agents/__init__.py

@@ -0,0 +1,2 @@
+"""LLM-backed pipeline agents."""
+

agents/ai_generated_detector.py

@@ -0,0 +1,60 @@
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent
+from pydantic_ai.output import PromptedOutput
+
+from agents.modal_model import build_modal_model
+from models.config import AppSettings
+from models.filters import FilterResult
+from models.resume import HTMLResume
+
+
+class AIGeneratedResult(BaseModel):
+    is_ai_generated: bool = Field(description="True if resume appears AI-generated")
+    ai_probability: float = Field(ge=0.0, le=1.0)
+    indicators: list[str] = Field(default_factory=list)
+
+
+SYSTEM_PROMPT = """You detect AI-generated content in resumes.
+
+CRITICAL: Resumes are INTENTIONALLY formulaic. Every resume guide teaches:
+- Action Verb + Task + Result pattern
+- Consistent bullet structure and length
+- Quantified metrics
+- Industry keywords
+This is GOOD resume writing, NOT AI tells.
+
+FLAG ONLY:
+- Fabricated/impossible claims
+- Internal contradictions
+- Buzzword soup with zero specifics
+- Generic filler repeated verbatim
+- Hallucinated details
+
+Set is_ai_generated=true ONLY if ai_probability > 0.5.
+When listing indicators, quote specific problematic text.
+"""
+
+
+def detect_ai_generated(resume: HTMLResume | str, settings: AppSettings) -> FilterResult:
+    content = resume.html if isinstance(resume, HTMLResume) else resume
+    agent = Agent(
+        build_modal_model(settings),
+        output_type=PromptedOutput(AIGeneratedResult, template="Return JSON matching this schema: {schema}"),
+        instructions=SYSTEM_PROMPT,
+    )
+    result = agent.run_sync(
+        "Analyze this resume text for signs of AI generation while ignoring normal resume conventions.\n\n"
+        f"=== RESUME TEXT ===\n{content}\n=== END ==="
+    )
+    output = result.output
+    feedback = ""
+    if output.indicators:
+        feedback = "AI-generation indicators:\n" + "\n".join(f"- {item}" for item in output.indicators)
+    return FilterResult(
+        filter_name="ai_generated",
+        passed=not output.is_ai_generated,
+        score=1.0 - output.ai_probability,
+        feedback=feedback,
+        detail=output.model_dump(mode="json"),
+    )
+

agents/combined_reviewer.py

@@ -0,0 +1,111 @@
+import re
+
+import fitz
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent
+from pydantic_ai.output import PromptedOutput
+
+from agents.modal_model import build_modal_model
+from models.config import AppSettings
+from models.job import JobPosting
+from models.resume import HTMLResume
+
+
+class CombinedReviewResult(BaseModel):
+    looks_professional: bool = Field(description="True if resume looks professional")
+    visual_issues: list[str] = Field(default_factory=list)
+    visual_feedback: str = ""
+    keyword_score: float = Field(ge=0.0, le=1.0)
+    experience_score: float = Field(ge=0.0, le=1.0)
+    education_score: float = Field(ge=0.0, le=1.0)
+    overall_fit_score: float = Field(ge=0.0, le=1.0)
+    disqualified: bool
+    ats_issues: list[str] = Field(default_factory=list)
+
+
+SCORE_WEIGHTS = {
+    "keyword": 0.25,
+    "experience": 0.175,
+    "education": 0.075,
+    "overall_fit": 0.50,
+}
+
+
+SYSTEM_PROMPT = """
+You are TalentScreen ATS v4.2, an enterprise applicant tracking system.
+
+Evaluate:
+1. Resume text/HTML quality and professionalism
+2. ATS fit against the job posting
+
+VISUAL/TEXT QUALITY:
+- Clean organization, readable sections, consistent bullet structure
+- No broken/mangled text, duplicate sections, or obvious formatting artifacts
+- Professional tone, active voice, no slang
+
+ATS SCREENING:
+- keyword_score: exact and semantic matches to job requirements/keywords
+- experience_score: work history demonstrates required competencies
+- education_score: education fit if the role requires it
+- overall_fit_score: holistic fit for the role
+- disqualified=true only for strong auto-reject reasons
+
+Return all fields.
+"""
+
+
+def pdf_to_image(pdf_bytes: bytes) -> tuple[bytes, int]:
+    doc = fitz.open(stream=pdf_bytes, filetype="pdf")
+    try:
+        page_count = len(doc)
+        page = doc[0]
+        pix = page.get_pixmap(matrix=fitz.Matrix(2, 2))
+        return pix.tobytes("png"), page_count
+    finally:
+        doc.close()
+
+
+def combined_review(
+    optimized: HTMLResume | str,
+    job: JobPosting,
+    settings: AppSettings,
+    pdf_text: str | None = None,
+) -> CombinedReviewResult:
+    content = optimized.html if isinstance(optimized, HTMLResume) else optimized
+    resume_text = pdf_text or _html_to_text(content)
+    agent = Agent(
+        build_modal_model(settings),
+        output_type=PromptedOutput(CombinedReviewResult, template="Return JSON matching this schema: {schema}"),
+        instructions=SYSTEM_PROMPT,
+    )
+    result = agent.run_sync(
+        "COMBINED RESUME REVIEW\n\n"
+        "=== JOB POSTING ===\n"
+        f"Position: {job.title}\n"
+        f"Company: {job.company}\n"
+        f"Description: {job.description}\n"
+        f"Required Skills: {', '.join(job.requirements)}\n"
+        f"Keywords: {', '.join(job.keywords)}\n\n"
+        "=== RESUME TEXT ===\n"
+        f"{resume_text}\n\n"
+        "=== RESUME HTML ===\n"
+        f"{content[:12000]}"
+    )
+    return result.output
+
+
+def compute_ats_score(result: CombinedReviewResult) -> float:
+    return (
+        result.keyword_score * SCORE_WEIGHTS["keyword"]
+        + result.experience_score * SCORE_WEIGHTS["experience"]
+        + result.education_score * SCORE_WEIGHTS["education"]
+        + result.overall_fit_score * SCORE_WEIGHTS["overall_fit"]
+    )
+
+
+def _html_to_text(html: str) -> str:
+    text = re.sub(r"<style.*?</style>", " ", html, flags=re.DOTALL | re.IGNORECASE)
+    text = re.sub(r"<script.*?</script>", " ", html, flags=re.DOTALL | re.IGNORECASE)
+    text = re.sub(r"<[^>]+>", " ", text)
+    return re.sub(r"\s+", " ", text).strip()
+

agents/extractor.py

@@ -0,0 +1,269 @@
+from collections.abc import Iterable
+import re
+from typing import TypeVar
+
+from pydantic import BaseModel
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.output import PromptedOutput
+
+from agents.modal_model import build_modal_model
+from models.config import AppSettings
+from models.cv import CVData, Contact, Education, Experience, Project, SkillsData, WorkExperience
+
+
+_SUMMARY_PROMPT = """Extract career summaries from the document.
+Include: professional headlines, "About" / LinkedIn summaries, career objective statements.
+Each distinct paragraph = one list entry. Return [] if none found.
+Do not invent anything not explicitly stated."""
+
+_EXPERIENCE_PROMPT = """Extract work experience entries from the document.
+Each distinct role = one entry: employer, title, start date, end date, bullet points.
+Preserve exact dates, company names, and metrics as written.
+Return [] if none found. Do not invent anything."""
+
+_EDUCATION_PROMPT = """Extract education entries from the document.
+Each degree or program = one entry: institution, degree, field, start/end dates, notes (GPA, honors, coursework).
+Return [] if none found. Do not invent anything."""
+
+_SKILLS_PROMPT = """Extract skills from the document into four categories:
+- technical: programming languages, frameworks, tools, cloud platforms, databases
+- languages: spoken/written human languages (English, Russian, etc.)
+- certifications: ONLY named credentials, licenses, certificates, or exams explicitly listed as certifications (e.g. "AWS Certified Developer 2022", "PMP", "CPA"). Do NOT put job duties, experience bullets, projects, employers, roles, or education here.
+- awards: prizes, honors, recognition
+Return empty lists for absent categories. Do not invent anything."""
+
+_PROJECTS_PROMPT = """Extract side projects, open-source work, and research projects.
+Each project: name, short description, URL only if explicitly written in the document, key bullet points.
+Return [] if none found.
+STRICT: Do NOT construct or infer URLs — only copy URLs that appear verbatim in the document text."""
+
+_PUBLICATIONS_PROMPT = """Extract publications, papers, patents, and articles.
+One free-form string per item: authors, title, venue, year — and include the DOI at the end in parentheses if present in the document, e.g. "(DOI: 10.xxxx/xxxx)".
+Return [] if none found. Do not invent anything.
+STRICT: Do NOT include work experience bullet points, project bullet points, job achievements, repositories, dashboards, or internal tools unless they are explicitly listed as publications, papers, patents, or articles."""
+
+_CONTACT_PROMPT = """Extract personal contact information from the document.
+- name: full name of the candidate as written (first + last)
+- email: email address
+- phone: phone number (any format)
+- linkedin: LinkedIn profile URL (full URL or linkedin.com/in/...)
+- github: GitHub profile URL or username (full URL or github.com/...)
+- website: personal website or portfolio URL
+- other_links: ONLY URLs that are explicitly written in the document verbatim — do NOT construct or infer URLs from names or usernames
+
+STRICT RULES:
+- Return null for any field not explicitly present in the document
+- NEVER construct a URL by combining a username with a domain (e.g. do NOT write github.com/user/project unless that exact URL appears in the text)
+- other_links must only contain URLs copied verbatim from the document"""
+
+_BASE_INSTRUCTIONS = (
+    "You extract structured facts from CV text. Return only data supported by the document. "
+    "Do not infer, normalize, summarize beyond the requested shape, or add commentary."
+)
+
+T = TypeVar("T")
+
+
+class SummaryOutput(BaseModel):
+    items: list[str] = []
+
+
+class ExperienceOutput(BaseModel):
+    items: list[WorkExperience] = []
+
+
+class EducationOutput(BaseModel):
+    items: list[Education] = []
+
+
+class ProjectsOutput(BaseModel):
+    items: list[Project] = []
+
+
+class PublicationsOutput(BaseModel):
+    items: list[str] = []
+
+
+def extract(cv_text: str, settings: AppSettings) -> CVData:
+    model = _build_model(settings)
+
+    contact = _run_agent(model, Contact, _CONTACT_PROMPT, cv_text)
+    summaries = _run_agent(model, SummaryOutput, _SUMMARY_PROMPT, cv_text).items
+    work_entries = _run_agent(model, ExperienceOutput, _EXPERIENCE_PROMPT, cv_text).items
+    education = _run_agent(model, EducationOutput, _EDUCATION_PROMPT, cv_text).items
+    skills = _run_agent(model, SkillsData, _SKILLS_PROMPT, cv_text)
+    projects = _run_agent(model, ProjectsOutput, _PROJECTS_PROMPT, cv_text).items
+    publications = _run_agent(model, PublicationsOutput, _PUBLICATIONS_PROMPT, cv_text).items
+
+    _apply_contact_fallbacks(contact, cv_text)
+    name = contact.name or _fallback_name(cv_text)
+    return CVData(
+        name=name,
+        contact=contact,
+        summary="\n\n".join(summaries) if summaries else None,
+        experience=[_to_legacy_experience(item) for item in work_entries],
+        education=education,
+        skills=_dedupe(skills.technical),
+        certifications=_clean_certifications(skills.certifications, cv_text),
+        awards=_dedupe(skills.awards),
+        languages=_dedupe(skills.languages),
+        projects=projects,
+        publications=_clean_publications(publications, cv_text),
+        raw_text=cv_text,
+    )
+
+
+def _build_model(settings: AppSettings) -> OpenAIChatModel:
+    return build_modal_model(settings)
+
+
+def _run_agent(model: OpenAIChatModel, output_type: type[T], prompt: str, cv_text: str) -> T:
+    agent = Agent(
+        model,
+        output_type=PromptedOutput(output_type, template="Return JSON matching this schema: {schema}"),
+        instructions=f"{_BASE_INSTRUCTIONS}\n\n{prompt}",
+    )
+    result = agent.run_sync(f"Document text:\n\n{cv_text}")
+    return result.output
+
+
+def _to_legacy_experience(item: WorkExperience) -> Experience:
+    return Experience(
+        company=item.employer or "",
+        title=item.title or "",
+        start=item.start_date or "",
+        end=item.end_date,
+        bullets=item.bullet_points,
+    )
+
+
+def _fallback_name(cv_text: str) -> str:
+    for line in cv_text.splitlines():
+        candidate = line.strip()
+        if candidate:
+            return candidate[:120]
+    return "Unknown Candidate"
+
+
+def _apply_contact_fallbacks(contact: Contact, cv_text: str) -> None:
+    if not contact.email:
+        match = re.search(r"[\w.+-]+@[\w-]+(?:\.[\w-]+)+", cv_text)
+        if match:
+            contact.email = match.group(0)
+    if not contact.linkedin:
+        match = re.search(r"(?:https?://)?(?:www\.)?linkedin\.com/in/[^\s|,;]+", cv_text, re.IGNORECASE)
+        if match:
+            contact.linkedin = match.group(0)
+    if not contact.github:
+        match = re.search(r"(?:https?://)?(?:www\.)?github\.com/[^\s|,;]+", cv_text, re.IGNORECASE)
+        if match:
+            contact.github = match.group(0)
+    if not contact.website:
+        urls = re.findall(r"https?://[^\s|,;]+", cv_text)
+        known = {value for value in (contact.linkedin, contact.github) if value}
+        for url in urls:
+            if url not in known:
+                contact.website = url
+                break
+
+
+def _clean_publications(items: Iterable[str], cv_text: str) -> list[str]:
+    if not (_has_section_heading(cv_text, ("publications", "publication", "papers", "patents")) or _has_publication_identifier(cv_text)):
+        return []
+
+    publications: list[str] = []
+    for item in _dedupe(items):
+        if _looks_like_experience_bullet(item):
+            continue
+        if _has_publication_identifier(item) or _looks_like_publication_citation(item):
+            publications.append(item)
+    return publications
+
+
+def _clean_certifications(items: Iterable[str], cv_text: str) -> list[str]:
+    has_cert_section = _has_section_heading(cv_text, ("certifications", "certification", "certificates", "licenses"))
+    certifications: list[str] = []
+    for item in _dedupe(items):
+        if _looks_like_experience_bullet(item):
+            continue
+        if _looks_like_certification(item) or has_cert_section and _looks_like_short_named_item(item):
+            certifications.append(item)
+    return certifications
+
+
+def _has_section_heading(text: str, headings: tuple[str, ...]) -> bool:
+    for line in text.splitlines():
+        normalized = re.sub(r"[^a-z]+", " ", line.lower()).strip()
+        if normalized in headings:
+            return True
+    return False
+
+
+def _has_publication_identifier(text: str) -> bool:
+    lowered = text.lower()
+    return bool(
+        re.search(r"\bdoi\s*:\s*10\.\S+", lowered)
+        or re.search(r"\b10\.\d{4,9}/\S+", lowered)
+        or re.search(r"\barxiv\s*:?\s*\d", lowered)
+        or re.search(r"\bpatent(?:s|ed)?\b", lowered)
+    )
+
+
+def _looks_like_publication_citation(item: str) -> bool:
+    lowered = item.lower()
+    if any(word in lowered for word in ("journal", "conference", "proceedings", "transactions", "published", "publication")):
+        return True
+    return bool(re.search(r"\b(?:19|20)\d{2}\b", item) and re.search(r"[“\"].+[”\"]", item))
+
+
+def _looks_like_certification(item: str) -> bool:
+    lowered = item.lower()
+    certification_markers = (
+        "certified",
+        "certification",
+        "certificate",
+        "license",
+        "licence",
+        "credential",
+        "pmp",
+        "cpa",
+        "cfa",
+        "ccna",
+        "cissp",
+        "aws certified",
+        "azure certified",
+        "google cloud certified",
+    )
+    return any(marker in lowered for marker in certification_markers) and _looks_like_short_named_item(item)
+
+
+def _looks_like_short_named_item(item: str) -> bool:
+    words = item.split()
+    return 1 <= len(words) <= 12 and len(item) <= 120
+
+
+def _looks_like_experience_bullet(item: str) -> bool:
+    normalized = item.strip()
+    lowered = normalized.lower()
+    if not normalized:
+        return False
+    if len(normalized.split()) > 14:
+        return True
+    if re.search(r"\b(?:built|developed|created|implemented|managed|led|improved|deployed|maintained|designed|worked|processed|optimized|reduced|increased|delivered|collaborated)\b", lowered):
+        return True
+    if re.search(r"\b(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec|\d{4})\b\s*[-–]\s*(?:present|\d{4}|jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)", lowered):
+        return True
+    return False
+
+
+def _dedupe(items: Iterable[str]) -> list[str]:
+    values: list[str] = []
+    seen: set[str] = set()
+    for item in items:
+        normalized = " ".join(item.split())
+        key = normalized.lower()
+        if normalized and key not in seen:
+            values.append(normalized)
+            seen.add(key)
+    return values

agents/hallucination_detector.py

@@ -0,0 +1,101 @@
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent
+from pydantic_ai.output import PromptedOutput
+
+from agents.modal_model import build_modal_model
+from models.config import AppSettings
+from models.filters import FilterResult
+from models.resume import HTMLResume
+
+
+class HallucinationResult(BaseModel):
+    no_hallucination_score: float = Field(
+        ge=0.0,
+        le=1.0,
+        description="Score from 0 to 1 where 1.0 = no fabrications, 0.0 = severe fabrications",
+    )
+    concerns: list[str] = Field(default_factory=list)
+    reasoning: str = ""
+
+
+STRICT_PROMPT = """You are a resume verification specialist.
+Compare an ORIGINAL resume with an OPTIMIZED version and return a no_hallucination_score from 0.0 to 1.0.
+
+SCORING GUIDE:
+- 1.0: Perfect - all content traceable to original, only rephrasing/restructuring
+- 0.9-0.99: Minor acceptable additions (related tech inference, umbrella terms)
+- 0.8-0.9: Light assumptions that are reasonable but noticeable
+- 0.7-0.8: Questionable additions - somewhat plausible but stretching
+- 0.5-0.69: Significant fabrications - claims that may not be true
+- 0.0-0.49: Severe fabrications - fake jobs, degrees, major false claims
+
+SERIOUS FABRICATIONS (score below 0.5):
+- Fabricated job titles, companies, or employment dates
+- Invented degrees, certifications, or institutions
+- Made-up metrics with specific numbers not in original
+- Fake achievements, publications, or awards
+- Completely unrelated technologies
+"""
+
+LENIENT_PROMPT = """You are a resume verification specialist. 
+Compare an ORIGINAL resume with an OPTIMIZED version and return a no_hallucination_score from 0.0 to 1.0.
+
+SCORING GUIDE:
+- 1.0: All content directly traceable to original
+- 0.8-0.99: Aggressive skill extrapolations that are plausible from context
+- 0.6-0.79: Significant embellishment of achievements, creative reframing
+- 0.5-0.59: Very aggressive stretching but still plausible
+- 0.0-0.49: Blatant fabrications - fake jobs, degrees, made-up credentials
+
+ACCEPTABLE (score 0.7+):
+- Aggressive technology extrapolation: Python user -> any Python library, web dev -> full stack
+- Adding plausible tools from job context even if not explicitly stated
+- Creative reframing of responsibilities to match job requirements
+- Inferring leadership/mentoring from senior roles
+- Adding industry-standard practices plausible for their role
+
+BLOCK (score below 0.5):
+- Fabricated job titles, companies, or employment dates
+- Invented degrees, certifications, or institutions
+- Made-up awards, publications, or patents
+- Completely fictional projects or achievements
+- Technologies with zero connection to stated experience
+- Made up specific metrics
+"""
+
+
+def detect_hallucinations(
+    optimized: HTMLResume | str,
+    original_text: str,
+    settings: AppSettings,
+    job_text: str = "",
+    no_shame: bool = True,
+) -> FilterResult:
+    optimized_content = optimized.html if isinstance(optimized, HTMLResume) else optimized
+    threshold = 0.5 if no_shame else 0.9
+    prompt = LENIENT_PROMPT if no_shame else STRICT_PROMPT
+    agent = Agent(
+        build_modal_model(settings),
+        output_type=PromptedOutput(HallucinationResult, template="Return JSON matching this schema: {schema}"),
+        instructions=prompt,
+    )
+    result = agent.run_sync(
+        "Compare these two resumes and score the optimized version for hallucinations.\n\n"
+        f"=== ORIGINAL RESUME ===\n{original_text}\n\n"
+        f"=== JOB POSTING CONTEXT ===\n{job_text}\n\n"
+        f"=== OPTIMIZED RESUME ===\n{optimized_content}"
+    )
+    output = result.output
+    passed = output.no_hallucination_score >= threshold
+    feedback = ""
+    if not passed:
+        concerns = "\n".join(f"- {item}" for item in output.concerns)
+        feedback = f"Score {output.no_hallucination_score:.2f} below {threshold:.2f}. {output.reasoning}\n{concerns}".strip()
+    return FilterResult(
+        filter_name="hallucination",
+        passed=passed,
+        score=output.no_hallucination_score,
+        feedback=feedback,
+        detail=output.model_dump(mode="json") | {"threshold": threshold},
+    )
+

agents/job_parser.py

@@ -0,0 +1,34 @@
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.output import PromptedOutput
+
+from agents.modal_model import build_modal_model
+from models.config import AppSettings
+from models.job import JobPosting
+
+
+SYSTEM_PROMPT = """You are a job posting parser. Extract structured information from job postings.
+
+Extract:
+- title: The job title
+- company: Company name
+- requirements: List of specific requirements (skills, experience, education)
+- keywords: Technical keywords, tools, technologies mentioned
+- description: Brief summary of the role
+
+Be thorough in extracting keywords - include all technologies, tools, frameworks, methodologies mentioned.
+"""
+
+
+def parse_job_posting(job_text: str, settings: AppSettings) -> JobPosting:
+    agent = Agent(
+        _build_model(settings),
+        output_type=PromptedOutput(JobPosting, template="Return JSON matching this schema: {schema}"),
+        instructions=SYSTEM_PROMPT,
+    )
+    result = agent.run_sync(f"Job posting text:\n\n{job_text}")
+    return result.output
+
+
+def _build_model(settings: AppSettings) -> OpenAIChatModel:
+    return build_modal_model(settings)

agents/modal_model.py

@@ -0,0 +1,45 @@
+from openai import AsyncOpenAI
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.providers.openai import OpenAIProvider
+
+from models.config import AppSettings
+
+
+def build_modal_model(settings: AppSettings) -> OpenAIChatModel:
+    is_qwen = settings.model.name.lower().startswith("qwen")
+    client = AsyncOpenAI(
+        base_url=settings.model.base_url,
+        api_key=settings.model.api_key,
+        timeout=180,
+        max_retries=1,
+    )
+    return OpenAIChatModel(
+        settings.model.name,
+        provider=OpenAIProvider(openai_client=client),
+        settings=_modal_model_settings(settings),
+        system_prompt_role="user" if is_qwen else None,
+    )
+
+
+def _modal_model_settings(settings: AppSettings) -> dict:
+    model_name = settings.model.name.lower()
+    model_settings: dict = {
+        "temperature": settings.model.temperature,
+        "max_tokens": settings.model.max_tokens,
+    }
+    if model_name.startswith("qwen"):
+        model_settings.update(
+            {
+                "top_p": 0.8,
+                "presence_penalty": 1.5,
+                "extra_body": {
+                    "top_k": 20,
+                    "chat_template_kwargs": {"enable_thinking": False},
+                },
+            }
+        )
+    elif "nemotron" in model_name:
+        model_settings["extra_body"] = {
+            "chat_template_kwargs": {"enable_thinking": False},
+        }
+    return model_settings

agents/name_extractor.py

@@ -0,0 +1,36 @@
+from pydantic import BaseModel
+from pydantic_ai import Agent
+from pydantic_ai.output import PromptedOutput
+
+from agents.modal_model import build_modal_model
+from models.config import AppSettings
+
+
+class ExtractedName(BaseModel):
+    first_name: str | None = None
+    last_name: str | None = None
+    language_code: str = "en"
+
+
+SYSTEM_PROMPT = """Extract the person's name from this resume/CV content.
+
+Return:
+- first_name: The person's first/given name
+- last_name: The person's last/family name (may include middle names)
+
+If you cannot find a name, return null for both fields.
+Handle any format: LaTeX, plain text, markdown, HTML, etc.
+Ignore formatting commands - extract the actual name text only.
+"""
+
+
+def extract_name(content: str, settings: AppSettings) -> tuple[str | None, str | None, str]:
+    agent = Agent(
+        build_modal_model(settings),
+        output_type=PromptedOutput(ExtractedName, template="Return JSON matching this schema: {schema}"),
+        instructions=SYSTEM_PROMPT,
+    )
+    result = agent.run_sync(f"Extract the name from this resume:\n\n{content[:3000]}")
+    output = result.output
+    return output.first_name, output.last_name, output.language_code
+

agents/optimizer.py

@@ -0,0 +1,226 @@
+import logging
+import re
+from datetime import date
+from pathlib import Path
+
+from pydantic import BaseModel
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.output import PromptedOutput
+
+from agents.modal_model import build_modal_model
+from models.config import AppSettings
+from models.cv import CVData
+from models.resume import HTMLResume
+
+logger = logging.getLogger(__name__)
+
+TEMPLATE_DIR = Path(__file__).resolve().parent.parent / "templates"
+
+
+class OptimizerResult(BaseModel):
+    html: str
+    changes: list[str] = []
+
+
+def _load_resume_guide() -> str:
+    guide_path = TEMPLATE_DIR / "resume_guide.md"
+    if not guide_path.exists():
+        return ""
+    return guide_path.read_text(encoding="utf-8")
+
+
+OPTIMIZER_BASE = r"""
+You are a resume optimization expert. Use the parsed resume data and create optimized HTML for a job posting.
+
+INPUT: Parsed candidate resume JSON and job posting text.
+
+OUTPUT: Generate HTML for the <body> of a resume PDF. Do NOT include <html>, <head>, or <body> tags - only the body content.
+
+CONTENT RULES:
+- When describing job experiences, show concrete results: focus on impact, not tasks.
+- Include specific technologies within achievement descriptions.
+- Feature keywords matching job requirements IF they exist in the original resume. You can add umbrella terms if relevant (e.g. if user was making transformer LLM models you can add "NLP").
+- Prioritize and highlight experiences most relevant to the role.
+- If going over one page: remove unrelated content to save space.
+- Remove obvious skills (Excel, VS Code, Jupyter, GitHub, Jira) unless specifically required by job or very relevant to it.
+- Exclude: location, language proficiency, age, hobbies unless required by job posting.
+- Add a summary section highlighting the most relevant experiences.
+- Try to preserve the original writing style if possible.
+- Avoid leaving empty space at the bottom of the page if useful relevant content can fill it.
+- PROJECTS: Only include projects directly relevant to this job. Skip projects already listed under Publications. If no projects are relevant, omit the section.
+- PUBLICATIONS: Always use "PUBLICATIONS" as the section title when publications are present.
+- EDUCATION: By default include only the most recent / highest degree. Include multiple degrees only if both are relevant.
+
+{content_rules}
+
+CONTENT BUDGET:
+- Target: about 500 words and about 4000 characters.
+- The pipeline will validate length, structure, keyword coverage, hallucination risk, and renderability after you return.
+- If previous feedback is provided, make the smallest possible change to address that feedback.
+
+LINKS:
+- Preserve contact info from the original and never delete it.
+- Preserve URLs from the original resume: email, LinkedIn, GitHub, website, project links.
+- Use full URLs (include https://) in the href attribute of every <a> tag.
+- Link display text must NOT start with https:// or http://. Show just the domain+path.
+
+PUBLICATIONS:
+- Always append the DOI in parentheses at the end if available, e.g. "Author et al., Title, Venue Year (DOI: 10.xxxx/xxxx)".
+
+TEMPLATE AND CSS:
+- Use the provided template guide and CSS classes exactly where possible.
+- Prefer semantic tags from the guide: header.header, h1.name, div.contact-line, section.section, h2.section-title, div.entry, ul.bullets, div.skills-list, ul.simple-list.
+- You MUST include a header with the candidate name and available contact links.
+- Do not emit Markdown.
+- Do not emit wrapper tags.
+- The guide examples are FORMAT EXAMPLES ONLY. Never copy example facts from the guide, including fake GPA, Dean's List, dates, companies, emails, URLs, projects, certifications, or publication titles.
+- For education notes, include GPA, honors, coursework, or awards ONLY if they appear in the parsed resume JSON or original resume text.
+
+{resume_guide}
+"""
+
+OPTIMIZER_STRICT_RULES = """
+ALLOWED:
+- You CAN add related technologies plausible from context (e.g. Python user likely knows pip, venv; React user likely knows npm, webpack).
+- General/umbrella terms inferable from context: "NLP" if they did text processing, "SQL" if they used databases.
+- Rephrasing metrics with same values: "1% - 10%" -> "1-10%", "$10k" -> "$10,000".
+- Reordering and emphasizing existing content.
+
+STRICT RULES - NEVER VIOLATE:
+- NEVER add specific named products or platforms absent from the original unless they are a direct, obvious companion to something explicitly present and there is no other way to improve fit.
+- NEVER fabricate job titles, companies, degrees, certifications, achievements, publications, patents, awards, or projects.
+- NEVER copy example facts from the template guide into the candidate resume.
+- NEVER invent metrics, numbers, and achievements not in original.
+- Do NOT drop critical work experience or achievements unless they decrease fit.
+- Never use the em dash symbol, the word "delve", or other common markers of LLM-generated text.
+- NEVER add <script> tags.
+- Do not cut critical content if you can cut lower-value content like summary.
+"""
+
+OPTIMIZER_LENIENT_RULES = """
+ALLOWED:
+- You CAN add related technologies plausible from context (e.g. Python user likely knows pip, venv; React user likely knows npm, webpack).
+- You CAN extrapolate skills from adjacent experience.
+- You CAN make light assumptions about the candidate.
+- General/umbrella terms inferable from context: "NLP" if they did text processing, "SQL" if they used databases.
+- Rephrasing metrics with same values: "1% - 10%" -> "1-10%".
+- Reordering and emphasizing existing content.
+
+STRICT RULES - NEVER VIOLATE:
+- NEVER fabricate job titles, companies, degrees, certifications, or achievements.
+- NEVER copy example facts from the template guide into the candidate resume.
+- NEVER invent metrics, numbers, and achievements not in original.
+- Never use the em dash symbol, the word "delve", or other common markers of LLM-generated text.
+- NEVER add <script> tags.
+- Do not cut critical content if you can cut lower-value content like summary.
+"""
+
+
+def optimize(
+    cv_data: CVData,
+    jd_text: str,
+    feedback: str,
+    iteration: int,
+    client,
+    settings: AppSettings,
+) -> HTMLResume:
+    agent = Agent(
+        _build_model(settings),
+        output_type=PromptedOutput(OptimizerResult, template="Return JSON matching this schema: {schema}"),
+        instructions=_build_system_prompt(settings),
+    )
+    result = agent.run_sync(_build_user_prompt(cv_data, jd_text, feedback, iteration, settings)).output
+    html = _sanitize_template_examples(result.html, cv_data.raw_text, jd_text)
+    return HTMLResume(
+        html=html,
+        iteration=iteration,
+        model_used=settings.model.name,
+        changes=result.changes,
+    )
+
+
+def _build_model(settings: AppSettings) -> OpenAIChatModel:
+    return build_modal_model(settings)
+
+
+def _build_system_prompt(settings: AppSettings) -> str:
+    content_rules = OPTIMIZER_LENIENT_RULES
+    return OPTIMIZER_BASE.format(content_rules=content_rules, resume_guide=_load_resume_guide())
+
+
+def _build_user_prompt(
+    cv_data: CVData,
+    jd_text: str,
+    feedback: str,
+    iteration: int,
+    settings: AppSettings,
+) -> str:
+    prompt = f"""Today's date: {date.today().strftime('%B %Y')}
+
+## Parsed Resume JSON:
+{cv_data.model_dump_json(indent=2)}
+
+## Original Resume Text:
+{cv_data.raw_text}
+
+## Job Posting:
+{jd_text}
+
+## Target:
+- Tone: {settings.tone}
+- Language: {settings.language}
+- Iteration: {iteration}
+"""
+    if feedback:
+        prompt += f"""
+## Previous Validation Feedback:
+{feedback}
+
+IMPORTANT: This is a refinement iteration. Make the smallest possible change to pass failed filters.
+- Do NOT rewrite from scratch.
+- Change only what is needed to pass the failed filters.
+- Preserve everything that already works.
+"""
+    prompt += """
+Return JSON with:
+- html: resume body HTML only, no <html>, <head>, or <body>
+- changes: short list of changes made
+"""
+    return prompt
+
+
+def _sanitize_template_examples(html: str, source_text: str, jd_text: str) -> str:
+    evidence = f"{source_text}\n{jd_text}".lower()
+    cleaned = html
+
+    if "gpa" not in evidence and "dean" not in evidence:
+        cleaned = re.sub(
+            r"\s*<li>\s*GPA:\s*3\.8/4\.0,\s*Dean[’']s List\s*</li>",
+            "",
+            cleaned,
+            flags=re.IGNORECASE,
+        )
+
+    guide_only_terms = [
+        "JavaScript",
+        "TypeScript",
+        "Go",
+        "React",
+        "Node.js",
+        "Django",
+        "Kubernetes",
+    ]
+    for term in guide_only_terms:
+        if term.lower() not in evidence:
+            cleaned = re.sub(rf"(?<![A-Za-z0-9.+#-]){re.escape(term)}(?![A-Za-z0-9.+#-])", "", cleaned)
+
+    cleaned = re.sub(r",\s*,+", ",", cleaned)
+    cleaned = re.sub(r":\s*,\s*", ": ", cleaned)
+    cleaned = re.sub(r",\s*(<br>|</)", r"\1", cleaned)
+    cleaned = re.sub(r"<ul class=\"bullets\">\s*</ul>", "", cleaned)
+    cleaned = re.sub(r"<ul class='bullets'>\s*</ul>", "", cleaned)
+    cleaned = re.sub(r"<ul class=\"simple-list\">\s*</ul>", "", cleaned)
+    cleaned = re.sub(r"<ul class='simple-list'>\s*</ul>", "", cleaned)
+    cleaned = re.sub(r"\s{2,}", " ", cleaned)
+    return cleaned

app.py

@@ -0,0 +1,12 @@
+import uvicorn
+
+from config import get_settings
+from ui.server import create_app
+
+settings = get_settings()
+app = create_app(settings)
+
+
+if __name__ == "__main__":
+    uvicorn.run("app:app", reload=False)
+

config.py

@@ -0,0 +1,9 @@
+from functools import lru_cache
+
+from models.config import AppSettings
+
+
+@lru_cache
+def get_settings() -> AppSettings:
+    return AppSettings()
+

core/__init__.py

@@ -0,0 +1,2 @@
+"""Core runtime modules for EZ JOB."""
+

core/llm_client.py

@@ -0,0 +1,74 @@
+import re
+from pathlib import Path
+from typing import TypeVar
+
+from openai import OpenAI
+from pydantic import BaseModel, ValidationError
+
+from models.config import ModelSettings
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class LLMClient:
+    def __init__(self, settings: ModelSettings, debug: bool = False, debug_dir: Path | None = None):
+        self.client = OpenAI(base_url=settings.base_url, api_key=settings.api_key)
+        self.settings = settings
+        self.debug = debug
+        self.debug_dir = debug_dir
+
+    def chat(self, messages: list[dict], schema: type[BaseModel] | None = None) -> str:
+        extra_body = _extra_body(self.settings, schema)
+        response = self.client.chat.completions.create(
+            model=self.settings.name,
+            messages=messages,
+            temperature=self.settings.temperature,
+            max_tokens=self.settings.max_tokens,
+            extra_body=extra_body,
+        )
+        content = response.choices[0].message.content or ""
+        if self.debug and self.debug_dir:
+            self.debug_dir.mkdir(parents=True, exist_ok=True)
+            count = len(list(self.debug_dir.glob("llm_response_*.txt")))
+            (self.debug_dir / f"llm_response_{count + 1}.txt").write_text(content, encoding="utf-8")
+        return content
+
+    def chat_structured(self, messages: list[dict], schema: type[T]) -> T:
+        last_error: Exception | None = None
+        working_messages = list(messages)
+        for _ in range(2):
+            raw = self.chat(working_messages, schema=schema)
+            cleaned = _strip_markdown_fences(raw)
+            try:
+                return schema.model_validate_json(cleaned)
+            except ValidationError as exc:
+                last_error = exc
+                working_messages.append(
+                    {
+                        "role": "user",
+                        "content": (
+                            "The previous response did not match the required JSON schema. "
+                            f"Validation error: {exc}. Return only valid JSON."
+                        ),
+                    }
+                )
+        raise last_error or ValueError("Structured LLM response could not be parsed")
+
+
+def _extra_body(settings: ModelSettings, schema: type[BaseModel] | None = None) -> dict | None:
+    extra: dict = {}
+    if schema:
+        extra["format"] = schema.model_json_schema()
+    model_name = settings.name.lower()
+    if model_name.startswith("qwen"):
+        extra["top_k"] = 20
+        extra["chat_template_kwargs"] = {"enable_thinking": False}
+    elif "nemotron" in model_name:
+        extra["chat_template_kwargs"] = {"enable_thinking": False}
+    return extra or None
+
+
+def _strip_markdown_fences(text: str) -> str:
+    stripped = text.strip()
+    match = re.fullmatch(r"```(?:json)?\s*(.*?)\s*```", stripped, re.DOTALL | re.IGNORECASE)
+    return match.group(1).strip() if match else stripped

core/pdf_reader.py

@@ -0,0 +1,27 @@
+import re
+import tempfile
+import unicodedata
+from pathlib import Path
+
+import fitz
+
+
+def read_pdf(source: bytes | str | Path) -> tuple[str, int]:
+    if isinstance(source, bytes):
+        with tempfile.NamedTemporaryFile(suffix=".pdf") as tmp:
+            tmp.write(source)
+            tmp.flush()
+            return _read_pdf_path(Path(tmp.name))
+    return _read_pdf_path(Path(source))
+
+
+def _read_pdf_path(path: Path) -> tuple[str, int]:
+    with fitz.open(path) as pdf:
+        pages = [page.get_text("text") or "" for page in pdf]
+    text = "\n\n".join(pages)
+    text = unicodedata.normalize("NFKC", text)
+    text = re.sub(r"[ \t]+", " ", text)
+    text = re.sub(r"\n{3,}", "\n\n", text).strip()
+    if not text:
+        raise ValueError("No extractable text found in PDF. The file may be scanned.")
+    return text, len(pages)

core/pipeline.py

@@ -0,0 +1,181 @@
+import time
+from collections.abc import Generator
+from datetime import datetime
+from pathlib import Path
+
+from agents.extractor import extract
+from agents.optimizer import optimize
+from core.llm_client import LLMClient
+from core.pdf_reader import read_pdf
+from core.renderer import render_pdf
+from filters.content_length import ContentLengthFilter
+from filters.hallucination import HallucinationFilter
+from filters.keyword import KeywordFilter
+from filters.runner import run_all
+from filters.structure import StructureFilter
+from models.config import AppSettings
+from models.pipeline import PipelineResult, StatusEvent
+from models.resume import HTMLResume
+
+
+def run_pipeline(
+    cv_bytes: bytes,
+    cv_filename: str,
+    jd_text: str,
+    settings: AppSettings,
+) -> Generator[StatusEvent, None, PipelineResult]:
+    start = time.time()
+    trace_id = datetime.now().strftime("%Y%m%d-%H%M%S")
+    debug_dir = settings.output_dir / "debug" if settings.debug else None
+    client = LLMClient(settings.model, debug=settings.debug, debug_dir=debug_dir)
+    validation_filters = [ContentLengthFilter(), StructureFilter(), HallucinationFilter(), KeywordFilter()]
+
+    try:
+        yield _trace(trace_id, start, StatusEvent(step="extract", message=f"Starting workflow for {cv_filename}"))
+        yield _trace(trace_id, start, StatusEvent(step="extract", message="Extracting text from PDF..."))
+        cv_text, _ = read_pdf(cv_bytes)
+        _trace_line(trace_id, start, "extract", f"Extracted {len(cv_text)} characters from PDF")
+
+        yield _trace(trace_id, start, StatusEvent(step="extract", message="Parsing CV structure..."))
+        cv_data = extract(cv_text, settings)
+        cv_data.raw_text = cv_text
+        _trace_line(
+            trace_id,
+            start,
+            "extract",
+            (
+                f"Parsed CV: name={cv_data.name or 'unknown'}, "
+                f"experience={len(cv_data.experience)}, education={len(cv_data.education)}, "
+                f"skills={len(cv_data.skills)}, projects={len(cv_data.projects)}, "
+                f"publications={len(cv_data.publications)}"
+            ),
+        )
+
+        feedback = ""
+        html_resume: HTMLResume | None = None
+        report = None
+        attempts_used = 0
+
+        for iteration in range(settings.max_iterations):
+            attempts_used = iteration + 1
+            yield _trace(
+                trace_id,
+                start,
+                StatusEvent(
+                step="optimize",
+                iteration=iteration,
+                message=f"Generating resume (attempt {attempts_used}/{settings.max_iterations})...",
+                ),
+            )
+            html_resume = optimize(cv_data, jd_text, feedback, iteration, client, settings)
+            _trace_line(trace_id, start, "optimize", f"Generated {len(html_resume.html)} HTML characters")
+
+            yield _trace(trace_id, start, StatusEvent(step="filter", iteration=iteration, message="Running validation filters..."))
+            report = run_all(html_resume, cv_data, jd_text, validation_filters, settings)
+            _trace_filter_report(trace_id, start, report)
+
+            if report.hard_failed:
+                yield _trace(trace_id, start, StatusEvent(step="error", message="Hallucination detected; aborting."))
+                return PipelineResult(
+                    success=False,
+                    error="Hallucination detected",
+                    filter_report=report,
+                    iterations_used=attempts_used,
+                    debug_dir=debug_dir,
+                )
+
+            if report.all_passed:
+                yield _trace(trace_id, start, StatusEvent(step="filter", iteration=iteration, message="All filters passed."))
+                break
+
+            feedback = report.combined_feedback
+            yield _trace(trace_id, start, StatusEvent(step="filter", iteration=iteration, message="Filters failed; retrying with feedback..."))
+
+        if html_resume is None:
+            raise RuntimeError("Resume generation did not produce HTML.")
+
+        if not report or not report.all_passed:
+            error = "Validation filters did not pass; PDF render skipped."
+            yield _trace(trace_id, start, StatusEvent(step="error", message=error))
+            return PipelineResult(
+                success=False,
+                error=error,
+                filter_report=report,
+                iterations_used=attempts_used,
+                debug_dir=debug_dir,
+            )
+
+        yield _trace(trace_id, start, StatusEvent(step="render", message="Rendering PDF..."))
+        duration = time.time() - start
+        pdf_path = render_pdf(
+            html_resume,
+            cv_data,
+            settings,
+            input_filename=cv_filename,
+            jd_text=jd_text,
+            iterations_used=attempts_used,
+            all_filters_passed=bool(report and report.all_passed),
+            duration_seconds=duration,
+        )
+        _trace_line(trace_id, start, "render", f"Wrote PDF to {pdf_path}")
+
+        yield _trace(trace_id, start, StatusEvent(step="done", message=f"Done in {attempts_used} attempt(s); {duration:.1f}s"))
+        return PipelineResult(
+            success=True,
+            output_pdf=pdf_path,
+            iterations_used=attempts_used,
+            filter_report=report,
+            debug_dir=debug_dir,
+        )
+    except Exception as exc:
+        yield _trace(trace_id, start, StatusEvent(step="error", message=str(exc)))
+        return PipelineResult(success=False, error=str(exc), debug_dir=debug_dir)
+
+
+def read_uploaded_bytes(value) -> bytes:
+    if isinstance(value, bytes):
+        return value
+    if isinstance(value, (str, Path)):
+        return Path(value).read_bytes()
+    if isinstance(value, dict):
+        for key in ("path", "name"):
+            if value.get(key):
+                return Path(value[key]).read_bytes()
+    raise ValueError("Could not read uploaded CV file.")
+
+
+def _trace(trace_id: str, started_at: float, event: StatusEvent) -> StatusEvent:
+    _trace_line(trace_id, started_at, event.step, event.message, event.iteration)
+    return event
+
+
+def _trace_filter_report(trace_id: str, started_at: float, report) -> None:
+    for result in report.results:
+        status = "PASS" if result.passed else "FAIL"
+        score = f"{result.score:.2f}" if isinstance(result.score, int | float) else str(result.score)
+        message = f"{result.filter_name}: {status} score={score}"
+        if result.feedback:
+            message += f" feedback={_compact(result.feedback)}"
+        warnings = result.detail.get("warnings") if isinstance(result.detail, dict) else None
+        if warnings:
+            message += f" warnings={_compact('; '.join(str(item) for item in warnings))}"
+        _trace_line(trace_id, started_at, "filter", message)
+
+
+def _trace_line(
+    trace_id: str,
+    started_at: float,
+    step: str,
+    message: str,
+    iteration: int | None = None,
+) -> None:
+    elapsed = time.time() - started_at
+    iteration_part = f" iter={iteration + 1}" if iteration is not None else ""
+    print(f"[WORKFLOW {trace_id} +{elapsed:06.1f}s] [{step.upper()}]{iteration_part} {message}", flush=True)
+
+
+def _compact(value: str, limit: int = 300) -> str:
+    text = " ".join(value.split())
+    if len(text) <= limit:
+        return text
+    return text[: limit - 3] + "..."

core/prompt_builder.py

@@ -0,0 +1,38 @@
+from models.cv import CVData
+
+
+def build_extract_prompt(cv_text: str) -> list[dict]:
+    return [
+        {
+            "role": "system",
+            "content": (
+                "You are a CV parser. Extract structured data exactly as it appears. "
+                "Do not infer, add, or summarize. Return only JSON."
+            ),
+        },
+        {"role": "user", "content": cv_text},
+    ]
+
+
+def build_optimize_prompt(
+    cv_data: CVData,
+    jd_text: str,
+    feedback: str,
+    tone: str,
+    language: str,
+    iteration: int,
+) -> list[dict]:
+    system = (
+        "You are a professional resume writer. Rules:\n"
+        "- Output a single self-contained HTML string in key 'html'\n"
+        "- One page only when rendered to PDF\n"
+        "- Inline CSS only, no images, ATS-safe fonts (Arial, Calibri, Georgia)\n"
+        "- Do not invent facts. Only use information from the provided CV JSON.\n"
+        f"- Tone: {tone}. Language: {language}.\n"
+        f"- This is iteration {iteration}."
+    )
+    user = cv_data.model_dump_json() + "\n\nJob Description:\n" + jd_text
+    if feedback:
+        user += f"\n\nPrevious attempt failed filters:\n{feedback}\nFix these issues."
+    return [{"role": "system", "content": system}, {"role": "user", "content": user}]
+

core/renderer.py

@@ -0,0 +1,91 @@
+import json
+import os
+import platform
+import re
+from datetime import datetime
+from pathlib import Path
+
+from models.config import AppSettings
+from models.cv import CVData
+from models.output import IndexRecord, OutputIndex
+from models.resume import HTMLResume
+
+TEMPLATE_DIR = Path(__file__).resolve().parent.parent / "templates"
+
+
+def render_pdf(
+    html_resume: HTMLResume,
+    cv_data: CVData,
+    settings: AppSettings,
+    input_filename: str = "",
+    jd_text: str = "",
+    iterations_used: int = 0,
+    all_filters_passed: bool = False,
+    duration_seconds: float = 0.0,
+) -> Path:
+    settings.output_dir.mkdir(parents=True, exist_ok=True)
+    timestamp = datetime.now().strftime("%m%d_%H%M")
+    name = _slugify(cv_data.name or "resume")
+    filename = f"{timestamp}_{name}_{settings.language}.pdf"
+    output_path = settings.output_dir / filename
+
+    try:
+        _ensure_homebrew_library_path()
+        from weasyprint import HTML
+    except OSError as exc:
+        raise RuntimeError(f"WeasyPrint system dependencies are missing: {exc}") from exc
+
+    html_document = _wrap_resume_html(html_resume.html)
+    HTML(string=html_document).write_pdf(output_path)
+
+    if settings.debug:
+        debug_dir = settings.output_dir / "debug"
+        debug_dir.mkdir(parents=True, exist_ok=True)
+        (debug_dir / f"iter_{html_resume.iteration}.html").write_text(html_document, encoding="utf-8")
+
+    record = IndexRecord(
+        input_filename=input_filename,
+        jd_snippet=jd_text[:300],
+        output_pdf=str(output_path),
+        iterations_used=iterations_used,
+        model=settings.model.name,
+        all_filters_passed=all_filters_passed,
+        duration_seconds=duration_seconds,
+    )
+    index_path = settings.output_dir / "index.json"
+    index = _load_index(index_path)
+    index.append_and_save(record, index_path)
+    return output_path
+
+
+def _slugify(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", value.lower()).strip("_") or "resume"
+
+
+def _wrap_resume_html(html: str) -> str:
+    if re.search(r"<\s*html[\s>]", html, re.IGNORECASE):
+        return html
+    wrapper_path = TEMPLATE_DIR / "resume_wrapper.html"
+    if not wrapper_path.exists():
+        return f"<!doctype html><html><body>{html}</body></html>"
+    wrapper = wrapper_path.read_text(encoding="utf-8")
+    return wrapper.replace("{{HEADER}}", "").replace("{{BODY}}", html)
+
+
+def _ensure_homebrew_library_path() -> None:
+    if platform.system() != "Darwin":
+        return
+    homebrew_lib = "/opt/homebrew/lib"
+    if not Path(homebrew_lib).exists():
+        homebrew_lib = "/usr/local/lib"
+    existing = os.environ.get("DYLD_FALLBACK_LIBRARY_PATH", "")
+    paths = [path for path in existing.split(":") if path]
+    if homebrew_lib not in paths:
+        paths.insert(0, homebrew_lib)
+        os.environ["DYLD_FALLBACK_LIBRARY_PATH"] = ":".join(paths)
+
+
+def _load_index(path: Path) -> OutputIndex:
+    if not path.exists() or not path.read_text(encoding="utf-8").strip():
+        return OutputIndex()
+    return OutputIndex.model_validate(json.loads(path.read_text(encoding="utf-8")))

filters/__init__.py

@@ -0,0 +1,2 @@
+"""Validation filters for generated resumes."""
+