Job Fit & Salary Estimator

Pipeline overview

The system is a pure-function pipeline with Pydantic-typed I/O at each step. Every step is auditable in isolation: same input → same output. The LLM is bounded to evidence extraction and soft subscores within strict JSON schemas; final score and salary math are deterministic.

All seven steps run in sequence. Five of them (extract, redact, score, salary, parts of recommend) contain no randomness — they're pure functions and produce identical output for identical input. The other two (parse, classify, soft-subscores via LLM) use Anthropic Claude with structured tool-use; their JSON output is validated against a Pydantic schema before downstream code sees it.

1Extract — text from PDF/DOCX

What it does: reads a binary file and returns plain text.

Logic

• .pdf → pypdf.PdfReader iterates pages, calls extract_text() on each, joins with newlines.
• .docx → python-docx reads paragraphs in document order.
• Anything else → ValueError("Unsupported file type").
• If a PDF page fails to extract, that page is skipped (text-only PDFs that contain images don't crash the pipeline; they just produce thin output, which downstream parse reports as low confidence).

Decision: why no OCR

OCR is out of scope for v1. Image-only PDFs result in low text length, which the parse step flags as "PDF extraction likely failed". The score's confidence label drops to low, and the salary range widens accordingly. Honest under-fitting is safer than fragile OCR.

2Redact — PII pre-pass

What it does: strips emails, phone numbers, URLs, birth dates, and Czech ID numbers from the text before any LLM call. Original file gets a SHA-256 hash for traceability.

Patterns (in order — order matters)

3Parse — text → CVJson

What it does: Claude reads the redacted text and emits a structured CVJson via tool-use. The schema enforces the shape; Pydantic validates the result.

Tool schema (abbreviated)

{
  "name": "parse_cv",
  "input_schema": {
    "type": "object",
    "required": ["roles", "skills", "education", "languages", "certifications",
                 "detected_language", "parse_confidence", "extraction_warnings"],
    "properties": {
      "roles": {"type": "array", "items": {Role schema with title, dates, description, is_current}},
      "skills": {"type": "array", "items": {"type": "string"}},
      "education": {"type": "array", "items": {Education schema}},
      "languages": [...],
      "certifications": [...],
      "detected_language": {"enum": ["cs", "en", "other"]},
      "parse_confidence": {"type": "number", "minimum": 0, "maximum": 1},
      "extraction_warnings": {"type": "array", "items": {"type": "string"}}
    }
  }
}

Decisions

• Self-reported confidence: the LLM reports parse_confidence ∈ [0,1]. Below 0.6 it contributes a reason to the final score's confidence label.
• Extraction warnings as tags: short strings like "no dates found", "low text length", "PDF extraction likely failed". These bubble up to the final ScoreCard's confidence_reasons.
• Prompt caching: the system block (instructions + extraction rules) is identical across CVs. Anthropic's prompt caching reads the cached block on subsequent calls, reducing input tokens by ~80% per CV after the first.
• No invented data: the system prompt explicitly forbids inventing roles, dates, or skills. Missing data → null + warning.

4Classify — CV → ISCO with confidence-gated rollup

What it does: picks the best ISCO-08 occupation code for the candidate's anchor role. The output drives salary lookup downstream.

Process

1. Pick anchor role (current role with longest duration; fallback to most recent role ≥ 12 months; fallback to most recent role).
2. Build a query string from anchor's title + description.
3. Query the local ESCO occupation index (28 hand-curated ISCO codes covering common occupations across all major groups) → top 8 candidates by Jaccard token overlap + substring bonus.
4. Pass the shortlist + CV skills + detected language to Claude. Claude picks ONE code, returns {isco_code, role_label, confidence, top1_margin, alternatives}.
5. Apply the confidence-gated rollup:

Edge case: high confidence + tiny margin

Confidence 0.85 with margin 0.05 means "I'm sure it's one of these two, I just don't know which." The gate returns level 3, not 4 — both candidates likely share a 3-digit prefix (e.g. 2511 Systems analyst and 2512 Software developer both roll up to 251).

5Score — five subscores blended

Five subscores, each 0–100, blended by fixed weights summing to 1.0:

The total is mapped to a band:

5a. relevant_experience (deterministic)

Two YoE measures, both with explicit handling of overlapping/parallel roles:

Total YoE — interval union

Sum the union of all dated role intervals. Parallel jobs don't double-count.

def total_yoe(roles):
    intervals = [(r.start_date, r.end_date or today) for r in roles if r.start_date]
    merged = merge_intervals(sorted(intervals))    # union: [(a, max(b, c)), ...]
    return sum(months_between(s, e) for s, e in merged) / 12.0

Relevant YoE — FTE-equivalent capped

For each calendar month a role was active, contribute isco_similarity × max(confidence, 0.5), capped at 1.0 per month so overlapping relevant roles can't sum to more than full-time. This is the correct way to handle freelance overlap.

def relevant_yoe(roles, anchor_isco):
    month_weights = {}
    for r in roles:
        weight = isco_similarity(r.isco_code, anchor_isco) * max(r.isco_confidence, 0.5)
        for ym in iter_months(r.start_date, r.end_date or today):
            month_weights[ym] = min(1.0, month_weights.get(ym, 0) + weight)
    return sum(month_weights.values()) / 12.0

ISCO similarity

YoE → 0–100 score (piecewise interpolation)

Five anchor points calibrate years of relevant experience to a subscore:

Linear interpolation between anchors. Concave (faster early gains, diminishing returns past 15y) — this matches market reality for IC roles.

Pipeline glue: ISCO propagation to roles

5b. skills_match (deterministic, two-tier)

Three signals combined to 0–100:

• Breadth (0–40): min(40, n × 6) where n is the count of distinct skills extracted.
• Depth (0–30): substring hits of senior markers ("architecture", "system design", "mentor", "distributed systems", ...) × 6, capped at 30.
• Match (0–30): overlap between extracted skills and the ISCO's expected keyword set, scaled.

Two-tier confidence

• Medium (default for v1 core): keyword-group fallback, ISCO-2-digit-keyed dictionary.
• High (stretch, not in v1): ESCO occupation→skill mapping (Jaccard against expected skill set).
• Low: when the ISCO has no keyword set in the dictionary (e.g. truck drivers — fallback to neutral score).

5c. impact_scope (LLM-bounded)

The LLM scores 0–100 against this rubric, returns 1–4 evidence quotes from the CV:

The schema enforces integer 0–100; Python clamps any out-of-range output as a safety net.

5d. leadership_ownership_growth (5 sub-dimensions × 0–20)

Originally called "personality" in the brief — renamed because CV text cannot defensibly infer personality. CV-observable signals are the honest proxy. Five dimensions, each scored 0/10/20 with evidence:

Sum of the five = 0–100. Each clamped before summing as a safety net.

5e. education (deterministic, role-sensitive)

Highest formal degree → base score, then adjustment for relevance to the anchor ISCO:

No institution-prestige scoring — deliberately excluded to avoid bias and the maintenance overhead of an "elite institution" allowlist. Reviewers see this in the README's "Limitations" section as a deliberate choice.

6Salary math — the load-bearing logic

Two-stage interpolation: score → percentile → salary. The percentile axis is "where in your ISCO group's salary distribution does this candidate fall." The salary axis is the actual CZK figure read from MPSV ISPV for that ISCO.

6a. Score → percentile (anchored interpolation)

Linear interpolation between anchors; clamped to P5–P95 at the edges (no extrapolation past observed deciles).

6b. Percentile → salary (linear through ISPV deciles)

MPSV ISPV publishes D1, Q1, median, Q3, D9 per CZ-ISCO occupation. Linear interpolation between observed deciles, clamped to [P10, P90] — never extrapolates past observed data:

def percentile_to_salary(p, *, d1, q1, median, q3, d9):
    p = max(10, min(90, p))                    # clamp to observed range
    points = [(10, d1), (25, q1), (50, median), (75, q3), (90, d9)]
    for (p0, v0), (p1, v1) in zip(points, points[1:]):
        if p0 <= p <= p1:
            t = (p - p0) / (p1 - p0)
            return v0 + t * (v1 - v0)

Why no extrapolation past D1/D9: ISPV doesn't publish percentiles below D1 or above D9. Any "P95 of nurses" or "P3 of CEOs" would be invented, which is exactly the kind of fake precision the methodology is meant to avoid.

6c. Confidence-driven salary range width

Confidence labels have a mathematical effect, not just a UI chip. Lower confidence widens the percentile band on each side of the point estimate before re-mapping to salary:

Confidence label is high only with zero confidence reasons; it drops to medium on one reason, low on two or more.

7+30% growth plan — three branches

Compute target_salary = current_salary × 1.30, find where it lands in the ISCO's salary distribution, and branch on that:

7a. role_family_change

Target salary exceeds the top decile of the candidate's current ISCO group. Even being P99 in this role won't get there. Recommendation is to change occupation (different ISCO, higher-paying industry) or change geography/comp model (foreign client, equity). Skill-up alone is mathematically impossible.

7b. stretch_within_role_or_market_change

Target sits in P85–P90. Mathematically reachable inside the current ISCO, but realistically requires a combination of demonstrated impact + a market move (changing companies, industries, or geographies). Skill-up alone usually isn't enough at this band.

7c. skill_up_within_role

Target lands inside P5–P85 of the current ISCO. Compute:

1. target_percentile from salary_to_percentile(target_salary, ...)
2. required_score = percentile_to_required_score(target_p) (inverse of the anchored interpolation)
3. score_delta = required_score − current_score
4. Allocate score_delta across subscores by weighted capacity (gap × weight), skipping relevant_experience — you can't fast-track years of experience.
5. Pass the deltas + redacted CV text to Claude → 3–5 concrete actions referencing CV evidence.

Subscore-delta allocation

def allocate_subscore_deltas(subscores, required_total_delta, weights, skip):
    gaps = {k: 100 - subscores[k] for k in subscores if k not in skip}
    weighted_capacity = {k: gaps[k] * weights[k] for k in gaps}
    total_capacity = sum(weighted_capacity.values()) or 1.0
    plan = {k: 0.0 for k in subscores}
    for k in gaps:
        share = required_total_delta * (weighted_capacity[k] / total_capacity)
        plan[k] = min(gaps[k], share / weights[k])      # convert total-points back to subscore-points
    return plan

Worked example: mid_dev_4y.docx

A 4-year-experienced software engineer in Czechia. The CV (paragraph form):

Jane Smith
Software Engineer

EXPERIENCE
Software Engineer — FinTech Plus, 05/2022 — present
- Owned the payment ingestion service handling 50k tx/day.
- Reduced p95 latency by 35% by introducing async Postgres pool.
- Mentored 1 intern.
Junior Developer — StartupX, 06/2020 — 04/2022
- Built REST APIs in Flask; helped migrate to FastAPI.
- Wrote integration tests; maintained CI pipeline.

SKILLS
Python, FastAPI, Flask, PostgreSQL, Redis, Docker, AWS, Kubernetes, Git, pytest, GitHub Actions

EDUCATION
Master's — Software Engineering, CTU Prague (2018–2020)

Step-by-step

Validation

No labelled ground-truth dataset exists for "correct" CV scores. Instead, the system is validated by rank-order assertions on a synthetic CV pack: hand-crafted CVs at known seniority bands run through the full pipeline (live LLM calls), and the relative ordering must be sensible.

Synthetic pack (5 CVs in v1 core)

Rank-order assertions (live E2E tests)

# tests/test_e2e_synthetic.py — gated on ANTHROPIC_API_KEY

assert score("junior_dev_1y") < score("mid_dev_4y") < score("senior_dev_8y")
assert score("buzzword_no_evidence") < score("mid_dev_4y")
assert relevant_yoe("nurse_to_dev_5y_2y") < total_yoe("nurse_to_dev_5y_2y")
assert classification("nurse_to_dev_5y_2y").isco_code.startswith("25")  # dev, not nurse
assert score("senior_dev_8y").band in ("Senior", "Lead/Principal")
for cv in all_cvs: assert len(growth_plan(cv).actions) >= 3

Assertions are intentionally loose (band ranges, not exact scores) — the goal is verifying the methodology rank-orders correctly, not that the LLM produces specific numbers.

Pure-function unit tests run without an API key

$ uv run pytest tests/ --ignore=tests/test_e2e_synthetic.py -q
71 passed, 1 skipped in 0.75s

$ uv run pytest tests/ --html=docs/reports/test-report.html \
    --cov=src/job_fit --cov-report=html:docs/reports/coverage --cov-report=term
TOTAL coverage: 86%

Data sources

What ISPV gives us

440 rows after fetch, period "rok 2025". Per CZ-ISCO occupation × wage/pay sphere (MZDOVA = private sector, PLATOVA = public sector), with fields: medianMzda, diferenciaceD1M, diferenciaceQ1M, diferenciaceQ3M, diferenciaceD9M, mzdaPrumer, pocetZamestnancuMzda, obdobi, czIsco.

Caveat: the public dataset is CZ-ISCO × sphere only — it is not a full region × education × age cube. Region/education/age salary adjustments are designed but not in v1. This is stated explicitly in the README's "Limitations" section.

What the local ESCO index gives us

A hand-curated CSV of 28 ISCO-08 occupation codes covering all major groups (managers, professionals, technicians, clerical, services, agricultural, trades, drivers). Each row has EN+CZ labels and bilingual keywords for keyword-overlap retrieval. The classify step uses this for top-k retrieval before passing to Claude. Stretch task 29 would extend this to the full ESCO occupation→skill mapping via the ESCO API.

Limitations & honest disclosures

• No full ISPV multidim cube — public dataset is CZ-ISCO × wage sphere only. Region/education/age adjustments are designed but not in v1.
• Eurostat SES is 2022 (quadrennial) — international anchors will lag.
• "Personality" renamed to leadership/ownership/growth signals — CV text cannot defensibly infer personality; CV-observable signals are the honest proxy.
• No labelled ground truth — validation is rank-order on a synthetic pack, not absolute correctness.
• Regex PII redaction — production would use NER (Named Entity Recognition); regex doesn't catch names or addresses.
• No institution-prestige scoring — deliberately excluded to avoid bias.
• OCR not implemented — image-only PDFs flow through as low parse confidence; the salary range widens accordingly.
• v1 ships CZ-only at runtime — EU/US/UK data layers are designed, not implemented.
• ISCO classification is hand-curated, not full ESCO — 28 occupations covering common roles; specialty roles fall back to keyword search and confidence-gated rollup.