Jobs_v3: AI-Powered Job Application Tailoring & LaTeX Management System

Welcome to Jobs_v3 (also known as MicroscopeMaestro / Job Tailor App). This repository is an end-to-end, high-efficiency local web application designed to tailor professional Resumes, Motivation Letters (Cover Letters), and Research Statements to specific job postings using fine-tuned AI prompts, verified candidate profile ground truths, RAG (Retrieval-Augmented Generation), and real-time LaTeX compilation.

---

Quick Navigation

• Where Everything Is Located (Code & Manuals)
• System Architecture
• Prerequisites
• Installation Guide
• Configuration & API Keys
• How to Run the Application
• How the AI Tailoring & Anti-Hallucination Pipeline Works
• Testing & Quality Verification
• Troubleshooting & FAQs

---

Where Everything Is Located

Documentation & Manuals

Document	File Path	Purpose
Master Manual	README.md	Complete system manual, codebase tour, operational guide.
Developer Guide	EXTENDING_GUIDE.md	Instructions for manually adding tools, endpoints, and UI features.
System Architecture	ARCHITECTURE.md	Detailed map of the modular frontend, backend, and core engine.
Installation Guide	INSTALL.md	Step-by-step setup on clean machines (macOS, Linux, Windows).
Project Architecture	PROJECT.md	System internals, refactoring milestones, database design.
AI Audit & Verification	ai_integration_audit.md	Detailed verification of AI client integration and contracts.
Testing Infrastructure	TEST_READY.md	Test harness setup and test tier execution instructions.

Code Structure Tour

Jobs_v3/
├── backend/                        # FastAPI Backend & Persistence
│   ├── api.py                      # REST endpoints for UI, compilation, tailoring & autosave
│   ├── database.py                 # SQLite database layer (applications, snapshots, settings)
│   ├── latex_html_converter.py     # Bi-directional LaTeX <-> HTML converter for rich-text editor
│   ├── app.db                      # Local SQLite application database
│   └── models.py                   # Pydantic schemas for API requests & responses
│
├── frontend/                       # Web UI (Single-Page Application)
│   ├── index.html                  # Minimalist 2-zone interface (Editor + Live PDF Preview)
│   ├── app.js                      # UI logic, debounced autosave, rephrase tooltips, PDF.js render
│   ├── style.css                   # Modern clean styling, responsive drawer, tags styling
│   └── lib/                        # Vendor libraries (Quill WYSIWYG, PDF.js viewer)
│
├── job_tailor_app/                 # Core AI Tailoring & Prompt Pipeline
│   ├── prompts.py                  # Master Candidate Profile, strict anti-hallucination rules, DIN 5008 rules
│   ├── rag.py                      # SQLite FTS5 & Dense Vector retrieval engine for past CVs & PDFs
│   ├── tailor.py                   # 2-stage tailoring orchestration (Nemotron drafter + Gemini reasoning)
│   ├── latex.py                    # Formats JSON into LaTeX sections (experience, competencies, summary)
│   ├── ai_client.py                # Multi-provider client wrapper (Gemini, NVIDIA NIM, OpenAI)
│   └── rephrase.py                 # Contextual rephrasing engine (friendly, personal, technical, concise)
│
├── templates/                      # LaTeX Source Templates (Industrial Track)
│   ├── resume.tex                  # Master 2-column/1-column modular CV template
│   ├── motivation_letter.tex       # Master Cover Letter template (DIN 5008 compliant)
│   └── sections/                   # Modular .tex sections (experience, competencies, summary, etc.)
│
├── templates_academic/             # LaTeX Source Templates (Academic / Research Track)
│   ├── resume.tex                  # Academic CV template
│   ├── motivation_letter.tex       # Academic Cover Letter template
│   ├── research_statement.tex      # Academic Research Statement template
│   └── sections/                   # Academic modular .tex files (publications, visits, awards, etc.)
│
├── data/                           # User Data & Application Workspaces
│   ├── active_applications/        # Isolated workspaces for each job application generated
│   ├── candidate_rag_cache.json    # Cached RAG database of past documents and real experiences
│   └── user_settings.db            # Persistent user settings (API keys, selected models, preferences)
│
├── server.py                       # Main application launcher (starts FastAPI and opens browser)
├── main.py                         # Standalone compilation CLI engine with SHA-256 caching
└── requirements.txt                # Full Python dependencies list

---

System Architecture

┌────────────────────────────────────────────────────────────────────────┐
│                        FRONTEND (Single-Page App)                      │
│  - 50/50 Split View: Quill Rich-Text / Raw LaTeX Editor & PDF Preview │
│  - Multi-variant Rephrasing Tooltip (Friendly, Technical, Personal)    │
│  - Live Status Indicator & In-flight Request Cancellation             │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ HTTP REST APIs
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        BACKEND (FastAPI: server.py)                    │
│  - Applications CRUD & Snapshot History (/api/applications/*)          │
│  - Bi-directional LaTeX <-> HTML Conversion (/api/file)                │
│  - In-Process Scoped LaTeX Compilation Engine (/api/compile)           │
│  - Multi-provider AI Tailoring & Rephrase Pipeline                     │
└───────────────────┬─────────────────────────────────┬──────────────────┘
                    │                                 │
                    ▼                                 ▼
┌──────────────────────────────────────┐ ┌───────────────────────────────┐
│   DATABASE LAYER (backend/database.py│ │   AI TAILORING ENGINE         │
│ - SQLite WAL Mode & Connection Pool  │ │ - Master Profile Ground Truth │
│ - Application versions & snapshots   │ │ - Anti-Hallucination Pipeline │
│ - Token-guarded atomic persistence   │ │ - SQLite FTS5 + Vector RAG    │
└──────────────────────────────────────┘ └───────────────────────────────┘

---

Prerequisites

1. Python 3.9+: Ensure Python is installed on your machine.
2. TeX Live or MacTeX: Required by pdflatex to compile .tex files into .pdf.
   • macOS: brew install --cask mactex-no-gui (or basictex)
   • Linux (Debian/Ubuntu): sudo apt-get install texlive-latex-base texlive-latex-extra texlive-fonts-recommended
   • Windows: Install MiKTeX or TeX Live

---

Installation Guide

For complete, platform-specific setup details, see INSTALL.md. Here is the quick setup:

# 1. Clone repository
git clone https://github.com/juanmunoz/Jobs_private.git
cd Jobs_private

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate    # On Windows: .venv\Scripts�ctivate

# 3. Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

---

Configuration & API Keys

Create a .env file in the root directory to provide API keys for the tailoring models:

# Google Gemini API Key (Recommended for high-reasoning tailoring)
GEMINI_API_KEY=your_gemini_key_here

# NVIDIA NIM API Key (For fast extraction & Nemotron drafting)
NVIDIA_API_KEY=your_nvidia_key_here

# OpenAI API Key (Optional fallback)
OPENAI_API_KEY=your_openai_key_here

(You can also configure API keys directly inside the application UI via the Settings drawer.)

---

How to Run the Application

Option 1: Standard Web Server (Recommended)

Run the launcher:

python server.py

• The backend starts at http://127.0.0.1:8001.
• It will automatically launch your default browser and open the UI.

Option 2: Standalone LaTeX Compilation CLI

If you want to compile an application workspace from the command line:

python main.py --app-id <application_id> --target resume

---

How the AI Tailoring & Anti-Hallucination Pipeline Works

The application avoids generic AI hallucinations through a strict 3-tier architecture:

1. Master Candidate Profile (job_tailor_app/prompts.py):
   • Contains real, verified engineering achievements for John Doe across specific modules (EX-1 to EX-10).
   • Explicitly records verified machine vision & optics tools: MVTec HALCON, OpenCV (C++), Basler cameras, Cognex VisionPro, SICK optical sensors, RGB dome illumination, inclined flash, SVMs, DNNs, ZEMAX.
2. Strict Anti-Hallucination Policy:
   • The AI system prompt strictly forbids inventing degrees, companies, credentials, or tools not present in the master profile.
   • When a job requires a skill, the AI maps candidate experiences to real lab stories rather than generating boilerplate text.
3. Retrieval-Augmented Generation (RAG) (job_tailor_app/rag.py):
   • Uses SQLite FTS5 (full-text search) and cosine-similarity vector embeddings to pull relevant historical PDF/application chunks and provide them as context.
4. German DIN 5008 Compliance:
   • German cover letters automatically conform to standard business formatting (lowercase first word after salutation, bold subject without "Betreff:", closing without a comma).
5. Unified Tag System (\cvtag):
   • Competencies are output as clean, unified pill-tags (\cvtag{Skill}) without divisive "expertise" vs. "knowledge" labels.

---

Testing & Quality Verification

Run the test suite using pytest:

# Run all core tests
pytest tests/ -v

# Run LaTeX compilation tests specifically
pytest tests/test_latex.py -v

# Run AI tailor & prompt tests
pytest tests/test_tailor.py -v

---

Troubleshooting & FAQs

• Where is my tailored PDF saved? Each application has its own isolated directory in data/active_applications/app_<timestamp>_<id>/templates/resume.pdf (and motivation_letter.pdf).
• LaTeX compilation fails with Command not found: pdflatex: Make sure your LaTeX installation is on your PATH. On macOS, add /Library/TeX/texbin to your PATH in ~/.zshrc.
• Changes made in the UI aren't saving: The UI uses debounced autosave. Check the top right status indicator; it should show Saved ✓. You can also hit Cmd+S / Ctrl+S to save immediately.
• Git Synchronization: Active development runs in Jobs_v3/. All changes can be synced to GitHub via rsync into the Jobs_private repository.