Predictive HR Scanner

Design fiction — A satirical tool that simulates automated social media screening for job applicants, exposing the absurdity and bias of algorithmic hiring systems.

What it does

Paste a social media post and run it through a two-stage screening pipeline:

1. ML Scanner — A pre-trained TF-IDF + Logistic Regression model scores the post 0–1 and classifies it as LOW / MEDIUM / HIGH risk, then issues an AUTO-PASS, AUTO-FLAG, or REQUIRES MANUAL REVIEW decision.
2. AI Committee — For MEDIUM-risk posts, a LangGraph multi-agent system convenes three "reviewers" that deliberate and issue a final hiring verdict.

The committee agents are intentionally over-the-top to illustrate how automated review systems amplify bias:

Agent	Model	Role
COMPLIANCE MONITOR	Cohere command-r7b-12-2024	Paranoid corporate compliance officer
BRAND PROTECTION DIRECTOR	OpenRouter (auto-routed)	Anxious PR executive catastrophising media risk
JUDGE_ALGO_3	OpenRouter (auto-routed)	Cold algorithmic arbitrator issuing unappealable verdicts

Tech Stack

Layer	Technology
Backend	FastAPI + Jinja2
Frontend	Windows 11-style desktop UI, Tailwind CSS (CDN), Spline 3D background
ML Model	scikit-learn (TF-IDF + Logistic Regression, loaded from .pkl)
Agent Orchestration	LangGraph
LLM APIs	Cohere API, OpenRouter (OpenAI-compatible SDK)

Quick Start

1. Install dependencies

pip install -r requirements.txt

2. Set up API keys

Create a .env file in the project root:

COHERE_API_KEY=your_cohere_key_here
OPENROUTER_API_KEY=your_openrouter_key_here

3. Run the app

uvicorn app.main:app

Open http://127.0.0.1:8000 in your browser.

Features

Tab	Description
Scanner	Paste social media text → risk score + policy decision + optional AI committee deliberation
What-if Lab	Compare original vs. edited post side-by-side to see how wording shifts the score
Audit Log	Browse all past scans in the current session with expandable post text

Project Structure

HR/
├── app/
│   ├── __init__.py
│   ├── main.py                  # FastAPI app & API endpoints
│   ├── committee/
│   │   ├── agents.py            # LLM call wrappers (Cohere + OpenRouter)
│   │   ├── config.py            # API key loader (.env)
│   │   ├── graph.py             # LangGraph state graph
│   │   ├── models.py            # Pydantic request models
│   │   └── __init__.py
│   ├── static/
│   │   └── custom.css           # Animations & progress bar styles
│   └── templates/
│       └── index.html           # Jinja2 template — Windows 11-style desktop UI
├── hr_scanner_model.pkl         # Trained model 
├── .env                         # API keys (not committed)
├── requirements.txt
└── README.md

API Endpoints

Method	Path	Description
GET	/	Serve the frontend
POST	/api/scan	Run ML scan on a post
POST	/api/whatif	Compare two posts side-by-side
GET	/api/history	Retrieve session scan history
DELETE	/api/history	Clear session scan history
POST	/api/committee	Convene AI committee (MEDIUM risk scores only)