🚨 RECHTLICHER HINWEIS — Dieses Tool interagiert automatisiert mit Webseiten Dritter, was gegen deren AGB oder geltende Datenschutzgesetze (u.a. DSGVO, TTDSG) verstoßen kann. Die Nutzung erfolgt ausschließlich zu Test- und Lernzwecken. Nicht für reale Bewerbungen verwenden. Geplant sind eine Umstellung auf offizielle APIs sowie die Nutzung lokaler LLMs, um Rechtskonformität zu gewährleisten.

⚠️ BETA — This project is in early beta. Features, configuration, and data formats may change without notice. Use at your own risk.

Automated job application agent for the German-speaking job market. Currently supports Indeed and LinkedIn — evaluates vacancies through LLM scoring, generates personalised cover letters as PDF, and submits applications via direct email or web form autofill with Playwright. Support for StepStone, Monster, Xing, Glassdoor and other platforms is planned for future releases.

DE: Gemini ist der primäre KI-Dienst für Bewertung, Anschreiben und CV-Parsing.
OpenRouter dient als kostenloses Fallback, wenn alle Gemini-Keys erschöpft sind.
Beide sind in src/config/config.yaml konfigurierbar.

This project lives from the community!
Whether you are an experienced Python developer, an AI enthusiast, or just someone who wants to automate the job application process — you are warmly invited to fork this repository, improve it, or extend it.

My roadmap includes:

• ➕ New job platforms — StepStone, Xing, Monster, Glassdoor
• ➕ New LLM providers — Claude, local models via Ollama
• ➕ Headless CI/CD integration — fully automated pipeline
• ➕ Docker containerization — one-command setup
• ➕ Web UI / Dashboard — track applications visually

→ Fork the repository, create a Pull Request, or open an Issue.
→ Every contribution counts — be it a new module, a bug fix, or better documentation.

_{Companion extension — analyse job listings directly in your browser}

• How It Works
• Pipeline Diagram
• Requirements
• Installation
• Configuration
• CLI Arguments
• Architecture

The agent processes job vacancies one by one through a deterministic pipeline. Each vacancy goes through the following stages:

1. Job URL acquisition — URLs come from either an Indeed/StepStone keyword search (--search-jobs) or a direct URL (--url). Indeed search pages are parsed for individual job links; each link is visited separately.

2. Duplicate check — Every URL is checked against the SQLite database (output/applications.db, table applied_jobs). If the URL already exists (regardless of status), the vacancy is skipped immediately. This guarantees idempotency across multiple runs.

3. Playwright page load — The job page is opened in a Chrome browser controlled by Playwright. The agent waits for domcontentloaded + 2 seconds, then extracts the page title and full body text. Dead links are detected early (404 pages, expired Indeed job search pages) to avoid wasting LLM quota.

4. Rule-based extraction — Company name and job title are extracted from the page title using URL-specific heuristics (LinkedIn: title | Company | LinkedIn; Indeed: title - company - Indeed; StepStone: title - Company). If rules fail, Gemini extracts the data.

5. KO filter check — The job text is checked against hard filters from job_criteria.yaml:

• Forbidden titles: Senior, Middle, Consultant, Helpdesk, Full Stack — blocked immediately.
• Company blacklist: Specific companies (e.g. Zukunftsmotor) are blocked.
• Language requirements: German below B1 or English below A2 triggers a KO.
• Education: Roles requiring a specific degree without IT relevance are blocked; block_degree_only_roles and require_it_degree_strictly flags control strictness.
• Certifications: If RHCSA/RHCE/CCNA are listed as mandatory and missing in the profile, KO.
• Security clearances: U.S. citizenship, Secret/Top Secret clearance keywords → KO.
• Spam providers: GFN, WBS, DAA, IU keywords → KO (internships still allowed via allow_internship).
• Salary: min_annual_eur threshold checked against any salary mentioned.
• Datacenter/physical work: If the role requires on-site datacenter work and it is forbidden → KO.
• User rejection reasons: Past user rejections (saved in user_rejections table) are merged into the KO list and passed to the scoring prompt, which gives 0/10 if the reason matches.

Any KO causes score = 0 and the vacancy is logged as skipped.

6. LLM scoring — The job text and candidate profile are sent to Gemini (or OpenRouter fallback) with a scoring prompt. The LLM returns a score from 0.0 to 10.0, the reasoning text, and a match assessment.

If score < min_score_to_apply (default 5.0), the vacancy is logged as Skipped (Low Score) and skipped.

7. Cover letter generation — For vacancies scoring >= threshold, Gemini generates a personalised Anschreiben. The letter is rendered to a PDF file via ReportLab and saved to output/Anschreiben_{CompanyName}.pdf.

8. Direct email — The job description is scanned for a contact email (regex) and optionally a recruiter name (regex + Gemini extract_recruiter_prompt). If found:

• The Anschreiben is personalised with the recruiter's name.
• Relevant attachments are collected: the newest Lebenslauf (from candidate_files table), the generated Anschreiben PDF, and any Zertifikat/Diplom whose content keyword-overlaps with the job description.
• A single SMTP session is opened: the primary email is sent to the recruiter, then a CC copy ([KOPIE] prefix) is sent to the candidate in the same connection.
• On SMTPServerDisconnected, the agent reconnects and retries up to 3 times.
• On success → Applied (Direct Email), email_sent = 1.
• On failure → Applied (Direct Email Failed).

9. Form filler — If no contact email is found, Playwright attempts to fill the job application web form:

• Fields are matched by name/label/placeholder keywords (name, vorname, nachname, email, telefon, strasse, plz, stadt, linkedin, github, gehaltsvorstellung, verfügbarkeit, kündigungsfrist, arbeitserlaubnis, nachricht, anschreiben, lebenslauf, upload, file, bewerbung).
• File uploads are handled via set_input_files.
• Text inputs use fill() and select_option() for dropdowns.
• If the page is LinkedIn and the form filler produced 0 actions, try_linkedin_easy_apply() is triggered (clicks the "Easy Apply" button and steps through modal dialogs).

10. Fallback email — If the form filler produced 0 actions AND no recruiter email was found, the agent sends the generated Anschreiben + attachments to the candidate's own email address (from candidate_profile.json) as a fallback. This ensures the candidate never loses an application even when automation fails.

• Success → Applied (Email), email_sent = 1.
• Failure → Applied (Email Failed) (retried later by --send-email).

11. Human-in-the-loop (or auto-approve) — For form-filled applications, the agent prints the score + reasoning and waits for user input unless --auto-approve is active:

• enter → application is logged as Applied.
• cancel → user is prompted for a reason, which is saved to user_rejections table AND appended to ko_filters.user_rejected_reasons in job_criteria.yaml. This creates a feedback loop — future runs will pass this reason to the scoring prompt, causing matching vacancies to score 0/10.
• s → skip to next vacancy.

12. Batch email sending — At the end of the run (or via --send-email standalone), send_pending_emails() queries the database for all records with email_sent = 0. For each:

• A ZIP archive is built containing job_info.txt (company, title, URL, date, score), terminal_output.txt (cleaned log), and the Anschreiben PDF.
• A single SMTP session connects and sends all pending ZIP packages to the candidate's email.
• On SMTPServerDisconnected, the remaining packages are skipped (logged, to be retried next run).
• email_sent = 1 is set on success.

The diagram below shows the current architecture for job portals LinkedIn and Indeed. As the project evolves and new platforms (StepStone, Xing, Monster, Glassdoor) are added, this pipeline may change or be extended.

flowchart TD
    START["🎯 JOB URL / SEARCH"] --> CHECK{is_already_applied?<br/>SQLite lookup}
    CHECK -- "YES<br/>(duplicate)" --> SKIP1["⏭️ SKIP"]
    CHECK -- "NO" --> LOAD["🌐 Playwright load<br/>+ dead-link detection"]
    LOAD --> KO{KO filter check<br/>10 filter types}
    KO -- "KO hit" --> SKIP2["⏭️ SKIP"]
    KO -- "OK" --> LLM["🤖 LLM scoring<br/>0–10"]
    LLM --> SCORE{Score ≥ 5.0?}
    SCORE -- "No<br/>&lt; 5.0" --> SKIP3["⏭️ SKIP"]
    SCORE -- "Yes<br/>≥ 5.0" --> ANSCHREIBEN["📄 Anschreiben PDF<br/>Gemini + PDF"]
    ANSCHREIBEN --> EMAIL{Email found?}
    EMAIL -- "Yes" --> DIRECT["📧 send_direct_email()<br/>1 session: recruiter + CC"]
    DIRECT --> DIR_OK["✅ Applied<br/>(Direct Email)"]
    DIRECT --> DIR_FAIL["❌ Applied<br/>(Direct Email Failed)"]
    EMAIL -- "No" --> FILLER["📝 Form filler<br/>(Playwright)"]
    FILLER --> FILLED{Form filled?}
    FILLED -- "Yes" --> APP["✅ APPLIED"]
    FILLED -- "No (0 actions)" --> FALLBACK["📧 Fallback email<br/>to candidate"]
    FALLBACK --> FB_OK["✅ Applied<br/>(Email)"]
    FALLBACK --> FB_FAIL["❌ Applied<br/>(Email Failed)"]

• Version: 3.10 or higher (tested with 3.11, 3.12).
• Architecture: x64 recommended. ARM (Windows ARM) may have Playwright compatibility issues.

• Bundled with Python: No separate installation needed. SQLite is part of the Python standard library (sqlite3 module).
• Database file: Created automatically at output/applications.db on first run.
• Schema: Two tables — applied_jobs (application history) and user_rejections (user-cancelled applications with reasons). Schema is auto-created by init_db().

• Cross-platform: Runs on Windows, Linux, and macOS. Set chrome_data_dir in config.yaml to match your OS (see sample file for examples).
• Windows: Tested on Windows 11. Use .\check_types.ps1 for type checking.
• Linux: Tested on Gentoo Linux. Use bash check_types.sh for type checking.
• PowerShell: Used for coloured terminal output on Windows. On Linux/macOS, ANSI escape codes work natively.

• Required for: Playwright web scraping and form filling.
• Installation options:
  1. Existing Chrome installation (point config.yaml → user_profile.chrome_data_dir to your profile).
  2. Playwright's bundled Chromium (auto-downloaded by playwright install chromium).

• Minimum: ~500 MB for Playwright Chromium browser.
• Runtime: ~50 MB for generated PDFs, ZIP archives, and the SQLite database.

python -m pip install google-genai playwright pyyaml pymupdf reportlab

Note: reportlab is required for PDF generation. pymupdf (fitz) is used for PDF text extraction during document indexing. If pip install is blocked by Windows Defender, use python -m pip install instead of bare pip.

python -m playwright install chromium

This downloads ~300 MB of browser binaries to %USERPROFILE%\AppData\Local\ms-playwright.

python -c "import sqlite3; print('SQLite', sqlite3.sqlite_version); from google import genai; print('Gemini SDK OK'); import playwright; print('Playwright OK')"

After extracting the archive, your project should look like this:

AI-JobFinder/
├── README.md
├── .gitignore
├── requirements.txt
├── src/
│   ├── agent.py
│   ├── config/
│   │   ├── config.yaml.sample       ← rename to config.yaml
│   │   ├── job_criteria.yaml.sample
│   │   └── candidate_profile.json.sample
│   └── ...
└── documents/                       ← place your PDF files here
    └── .gitkeep

Steps:

1. Create the documents/ folder (if not already present) — it is a sibling of src/.
2. Copy your CV into documents/ — e.g. documents/Lebenslauf_YourName.pdf.
3. Add certificates, diplomas, recommendation letters — all PDFs in documents/ will be automatically indexed by the agent (classified by filename and content).
4. Rename the config files — copy src/config/config.yaml.sample → src/config/config.yaml, and optionally customise job_criteria.yaml.sample and candidate_profile.json.sample.
5. Edit config.yaml — set cv_path and documents_dir to match your folder structure:

user_profile:
  cv_path: "../documents/Lebenslauf_YourName.pdf"   # relative to src/
  documents_dir: "../documents"                      # relative to src/

The paths are relative to the src/ directory because agent.py runs from there. Absolute paths also work.

All configuration files are in config/. Sample files (with .sample extension) serve as templates. On first run, if an active config file is missing, the agent automatically copies the .sample file and prints a warning.

gemini:
  model: gemini-2.5-flash
  api_keys:
    - "YOUR_API_KEY_1"
    - "YOUR_API_KEY_2"

user_profile:
  chrome_data_dir: "C:\\Users\\YourName\\AppData\\Local\\Google\\Chrome\\User Data"
  chrome_profile: Default
  cv_path: "Lebenslauf_YourName.pdf"
  documents_dir: "documents"

smtp:
  host: smtp.gmail.com
  port: 587
  username: "your.email@gmail.com"
  password: "xxxx xxxx xxxx xxxx"   # Google App Password

defaults:
  availability: "zwei Monate nach Zusage"
  notice_period: "3 Monate zum Quartalsende"
  salary_expectation: "36.000 €"
  work_permit: Germany

criteria:
  excluded_companies: ["CompanyToSkip"]
  german_level: B2
  min_salary_eur: 36000
  min_score: 8.0
  remote_allowed: true

llm:
  priority: gemini   # "gemini" or "openrouter" — which LLM to try first

Security: This file contains API keys and SMTP password. It is listed in .gitignore and must NEVER be committed.

{
  "personal_info": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "email": "max.mustermann@gmail.com",
    "phone": "+49 176 12345678",
    "address": "Musterstr. 1, 12345 Berlin",
    "linkedin": "https://linkedin.com/in/maxmustermann",
    "github": "https://github.com/maxmustermann",
    "birth_date": "1990-01-01",
    "nationality": "Deutsch"
  },
  "education": [...],
  "experience": [...],
  "skills": ["Linux", "Python", "Java"],
  "certifications": [...],
  "languages": {"Deutsch": "C2", "Englisch": "B2", "Russisch": "Muttersprache"},
  "salary_expectation": "36.000 €",
  "availability": "zwei Monate nach Zusage",
  "notice_period": "3 Monate zum Quartalsende",
  "work_permit": "Germany",
  "career_start_year": 2010
}

Defines ko_filters (blocking criteria), scoring (minimum score), and cover_letter (mandatory skills to mention). See the sample file for the full schema.

Customise prompts for:

• scoring_prompt — how the LLM evaluates job fit
• cover_letter_prompt — how the Anschreiben is written
• form_filler_prompt — how Playwright fills web form fields
• classification_prompt — how documents are classified
• extract_recruiter_prompt — how recruiter names are extracted from job text

Important: The form_filler_prompt must return a JSON array of {action, selector_type, selector_value, value}. This format is critical for Playwright to parse and execute form actions.

python agent.py [--search-jobs QUERY] [--location CITY] [--radius KM]
                [--url URL] [--interactive] [--headless] [--auto-approve]
                [--send-email] [--parse-cv] [--test-score FILE]
                [--test-anschreiben COMPANY FILE] [--generate-dummy-cv]
                [--reset-candidate]

Searches Indeed for job vacancies matching the keyword, scrapes all result pages, and processes each link through the full pipeline.

City or region to search in. Used together with --search-jobs.

Search radius around the location.

Process a single job vacancy by URL.

Prompts the user to paste a URL interactively.

Runs Chrome in headless mode (no visible browser window). Automatically enables --auto-approve.

Automatically logs all applications without waiting for user confirmation.

Sends all pending application emails to the candidate.

Parses and indexes the candidate's CV PDF without running the job pipeline.

Tests the scoring prompt on a job description text file.

Tests the cover letter generation for a given company and job description.

Generates a dummy CV PDF for testing purposes.

Destructive reset of all candidate data.

• ✅ = compatible
• ❌ = mutually exclusive (passing both causes the last one to win or raises an error)
• ✅* = automatically enabled by the other flag
• —** = --send-email standalone (no URL/search) skips Playwright entirely

The CLI arguments naturally group into three mutually exclusive families:

Within the job acquisition family, you can add:

• --headless (invisible browser)
• --auto-approve (skip human review)
• --send-email (send pending emails after processing)

# Standard workflow: search + GUI + human review
python agent.py --search-jobs "Junior Systemadministrator" --location "Frankfurt am Main" --radius 25

# Headless automation
python agent.py --search-jobs "Junior Linux" --location "Frankfurt" --radius 25 --headless

# Single manual URL with auto-approve
python agent.py --url "https://de.indeed.com/viewjob?jk=XXXXX" --auto-approve

# Interactive loop
python agent.py --interactive

# Just send pending emails (no scraping)
python agent.py --send-email

# Parse CV only
python agent.py --parse-cv

# Test scoring prompt
python agent.py --test-score job_test.txt

# Full reset
python agent.py --reset-candidate

agent.py                          # CLI entry point, argparse, Tkinter GUI, main pipeline loop
│
├── job_agent/config.py           # YAML/JSON config loaders, restore from .sample
├── job_agent/db.py               # SQLite init, queries, logging
├── job_agent/llm.py              # Gemini SDK, key rotation, model fallback, OpenRouter dispatch
├── job_agent/utils.py            # ANSI colours, JSON repair, ANSI escape removal, profile normalisation
├── job_agent/direct_email_applier.py  # SMTP email sending with reconnect, contact extraction
├── job_agent/email_sender.py     # Batch email sender (pending jobs → ZIP → SMTP)
├── job_agent/openrouter_llm.py   # OpenRouter API client (free LLM fallback)
├── job_agent/groq_llm.py         # Groq API client (region-blocked fallback)
├── job_agent/deepseek_llm.py     # DeepSeek API client (experimental)
└── job_agent/__init__.py         # Package marker

llm_request_with_fallback(prompt)
  │
  ├── priority == "openrouter" ? → call_openrouter() → success? → return
  │
  └── loop over models [gemini-2.5-flash, gemini-3.1-flash-lite, ...]
        │
        └── loop over API keys (up to 5)
              │
              ├── key exhausted (429) → mark exhausted → next key
              ├── all keys exhausted → next model
              └── all models exhausted → OpenRouter fallback
                    │
                    ├── OpenRouter success → return
                    └── OpenRouter fails → interactive user prompt:
                          [1] Enter new API key → retry
                          [2] Wait 1 hour → reset all keys → retry
                          [3] Exit

-- Main application log
applied_jobs (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    company_name    TEXT,
    job_title       TEXT,
    url             TEXT UNIQUE,
    score           REAL,
    applied_date    TEXT,
    status          TEXT,     -- 'Applied' | 'Self-rejection' | 'Skipped (Low Score)'
    email_sent      INTEGER DEFAULT 0,
    terminal_output TEXT,
    pdf_path        TEXT
)

-- User-initiated rejections (feedback loop)
user_rejections (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    company_name    TEXT,
    job_title       TEXT,
    url             TEXT UNIQUE,
    reason          TEXT,
    date            TEXT
)

-- Candidate document index
candidate_files (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    file_path       TEXT UNIQUE,
    file_size       INTEGER,
    mtime           REAL,
    classification  TEXT,     -- 'Lebenslauf' | 'Anschreiben' | 'Zertifikat' | 'Diplom' | 'Sonstiges'
    parsed_json     TEXT
)

1. Filename keywords (instant, free): lebenslauf/cv/curriculum → Lebenslauf, anschreiben/cover_letter → Anschreiben, zertifikat/certificate → Zertifikat, diplom/zeugnis/degree → Diplom.
2. Text keywords (instant, free via PyMuPDF): werdegang/berufserfahrung → Lebenslauf, sehr geehrte/bewerbung um → Anschreiben.
3. Gemini API (only if both above fail): Send first 1000 chars to the classification prompt.
4. Gemini CV parsing (only for Lebenslauf): Full document sent to Gemini acting as Senior HR specialist → returns structured JSON with seniority_level, hr_assessment, job_search_directions, target_vacancies.

Files that must NEVER be committed to git:

Pre-commit enforcement:

• check_secrets.py scans all staged files before every commit (run via pre-commit hook if configured).
• git add -A is prohibited — only specific files may be staged.
• Committable file types: *.py, *.yaml, *.yaml.sample, *.json.sample, *.md, *.txt, .gitignore, requirements.txt.