Inspiration
Pay inequity rarely shows up as one dramatic mistake. It hides in hundreds of small gaps: a loyal engineer who never got a market correction, a new hire brought in above people with years more tenure, a promotion that came with a title but no raise. HR teams know these problems exist but usually find them only during an annual comp review, by hand, in spreadsheets. We wanted a tool that surfaces them in seconds and lets you ask follow-up questions in plain English.
What it does
PayGuard AI is a compensation audit agent. You load an employee dataset and it immediately:
- Builds peer cohorts from job role and job level, then computes each cohort's median and interquartile range.
- Runs four detectors: underpayment, overpayment, salary compression (a new hire out-earning a tenured peer), and promotion/raise mismatch (promoted recently but given a sub-par raise).
- Shows a dashboard with total dollar exposure, flag counts by severity, and an evidence panel per flagged employee with a cohort box plot and histogram.
- Lets you look up any employee by name, ID, role, or department and see their full profile, career timeline, flags, and where they sit against their cohort.
- Answers questions through an "Ask PayGuard" chat. With an OpenAI key it's a tool-using GPT-4o-mini agent that can fetch employees, list flags, pull cohort stats, and compare two people. Without a key it falls back to a local rule-based responder on the same data, so the demo always works.
On the bundled IBM HR Analytics dataset of 1,470 employees, it finds roughly $4.1M in compensation exposure.
How we built it
- Python with Streamlit for the UI, organized into four tabs.
- pandas and NumPy for the detectors. Every rule is a pure dataframe operation, so the audit of 1,470 employees runs in well under a second.
- Plotly for the cohort visualizations.
- The OpenAI Python SDK for the chat agent, using function calling with four tools that query the already-computed dataframes rather than letting the model do math on its own.
- A shared schema module that maps dataset columns to named constants and holds every threshold, so tuning a rule is a one-line change.
- pytest smoke tests for each detector.
- Built largely with Claude Code in the terminal, which wrote and iterated on the detectors, the agent tool schemas, and the lookup tab.
Challenges we ran into
- Deployment. We first pushed to Vercel, which only runs serverless Python functions. Streamlit needs a persistent WebSocket server, so the build failed with an error about a missing top-level app object. We moved to Streamlit Community Cloud.
- Python version drift. Streamlit Cloud defaulted to Python 3.14, and our pinned packages had no prebuilt wheels for it. Pillow tried to compile from source and failed on missing zlib headers. Fixing it meant selecting Python 3.12 at deploy time, which can't be changed afterward without deleting and redeploying.
- The dataset has no names. IBM's HR dataset is anonymized, so we synthesize deterministic names from employee numbers to make the demo feel real while keeping the underlying data untouched.
- Making chat trustworthy. Early versions let the model reason about salaries from raw rows and it would occasionally invent numbers. We moved all computation into tools and made the model only narrate results.
- Demo without a key. We didn't want judges to hit a wall if the API key was missing, so we built a keyword-routed local responder that mirrors the agent's interface.
Accomplishments that we're proud of
- Four detectors that produce explainable, evidence-backed flags, each with a severity and a human-readable reason.
- A chat agent that stays grounded because it can only answer through tools that read the audited data.
- A full employee lookup view with a reconstructed career timeline from tenure, years in role, and years since promotion.
- An end-to-end demo that runs with zero configuration and zero API cost.
What we learned
- Cohort-relative statistics beat global thresholds. A salary that looks fine company-wide can be a clear outlier within its role and level.
- Tool-using agents are far more reliable when the tools own the math and the model owns the explanation.
- Streamlit is wonderful for fast iteration but has real constraints on where it can be hosted. Pick the host before you pick the framework.
- Pin your Python version as deliberately as you pin your packages.
What's next for PayGuard AI
- Upload your own CSV with a column-mapping step, instead of the bundled dataset only.
- Add demographic pay-gap analysis across gender and age within cohorts, with the appropriate statistical guardrails.
- Let the agent draft adjustment recommendations and export a review packet for each flagged employee.
- Historical snapshots so you can watch exposure trend down over time as fixes land.
- Role-based access and an audit log so it's safe to use on real payroll data.
Log in or sign up for Devpost to join the conversation.