How salary_lookup.py Benchmarks Compensation During Job Evaluation

salary_lookup.py benchmarks compensation by comparing company-specific salary indices against a configurable baseline index, calculating percentage differences across categories like base salary and bonuses to reveal how a prospective employer pays relative to industry standards.

The salary_lookup.py script in the MadsLorentzen/ai-job-search repository is a command-line utility designed to help job seekers benchmark compensation quickly. It ingests structured salary data from a JSON file and performs fuzzy matching against company names to retrieve relevant pay statistics. By comparing these figures against a baseline index, the tool provides instant context on whether an offer sits above or below market standards.

The Three-Step Benchmarking Pipeline

Load and Validate Salary Data

The process begins in salary_lookup.py with the load_data() function, which reads the user-provided salary_data.json file. Immediately after loading, validate_data() (lines 86‑101) enforces schema compliance, ensuring the JSON contains the required metadata object (including the index_baseline value) and a companies array where each entry provides salary categories with count and index values.

Fuzzy Match the Target Company

To locate the correct employer, search_company() (lines 103‑129) normalizes the user’s query string and optionally filters by city. The function leverages match_score_optimized() (lines 30‑90) to score every company record against the query, retaining only entries with a match score of 30 or higher. This threshold ensures the tool returns a tight roster of the most probable matches without noise.

Calculate Percentage Differences Against Baseline

For each matching company, format_entry() (lines 132‑192) extracts the categories dictionary and computes the benchmark comparison. The script retrieves the global baseline value from the file’s metadata (defaulting to 100) and applies the formula:

diff_pct = ((index - baseline) / baseline) * 100  # Lines 66-70

This calculation yields the percentage difference displayed in the "vs Baseline" column, instantly communicating whether the company’s compensation index sits above or below the reference standard.

Running Salary Lookup from the Command Line

Execute the utility from the repository root to query specific employers:

# Basic lookup showing top matching companies

python salary_lookup.py "Novo Nordisk"

# Filter results to a specific location

python salary_lookup.py "Novo Nordisk" --city "Aarhus"

# Output raw JSON for integration with other tools

python salary_lookup.py "Novo Nordisk" --json

Interpreting the Benchmark Output

The console displays a formatted table for each matched company:

============================================================
  Novo Nordisk
  Location: København
============================================================

  Category               Count   Index      vs Baseline
  --------------------------------------------------
  Base Salary            120   108.5        +8.5%
  Bonus                  115    95.0       -5.0%
  Stock Options           80    12.0       -88.0%

The Index represents the company’s compensation level for that category, while vs Baseline shows the calculated variance from the baseline of 100. Positive values indicate above-market pay, and negative values signal below-market rates. The Count column displays the sample size (e.g., number of surveyed employees) used to derive that index.

Summary

• salary_lookup.py ingests salary_data.json and validates it against a strict schema before processing.
• The search_company() function uses fuzzy matching with a threshold of ≥30 to identify relevant employers.
• Compensation benchmarks are calculated using ((index - baseline) / baseline) * 100, comparing category indices against the metadata baseline.
• The CLI supports city filtering and JSON output modes for flexible integration into job evaluation workflows.

Frequently Asked Questions

What data format does salary_lookup.py require?

The utility expects a JSON file named salary_data.json containing a metadata object with an index_baseline field and a companies array. Each company entry must include name, location, and a categories dictionary with numeric count and index values.

How does the fuzzy matching algorithm work?

The match_score_optimized() function normalizes both the query and company names, then calculates a similarity score. Only companies scoring 30 or higher proceed to the final output, ensuring high-confidence matches even with slight spelling variations.

Can I customize the baseline index?

Yes. The baseline defaults to 100 but is configurable via the index_baseline field in your salary_data.json metadata section. This allows you to adjust the reference point to reflect specific industry standards or geographic adjustments.

Where can I find instructions for preparing the salary data?

Documentation for structuring your JSON or Excel source data is available in tools/README_SALARY_TOOL.md within the repository. This file explains how to format categories and indices for optimal compatibility with the benchmarking tool.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}