README.md

---
title: Redrob Candidate Ranker
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.0.0
app_file: app.py
python_version: "3.10"
pinned: false
---

# Redrob Candidate Ranker

Offline candidate discovery and ranking system for the India Runs Data and AI Challenge.

The app uses:

- FAISS vector search over a local 384-dim hashing index
- BM25 keyword retrieval
- Reciprocal Rank Fusion
- structured skill, experience, title, behavioral, career, and proficiency scoring
- honeypot penalties for inconsistent candidate profiles
- a Gradio UI for searching and re-ranking candidates

## Run Locally

Install dependencies:

```bash
pip install -r requirements.txt
```

Run the Gradio app:

```bash
python app.py
```

Generate the submission CSV:

```bash
python rank.py --batch --out submission.csv
```

## Required Data Files

The app expects these files:

```text
data/candidates.jsonl
data/indexes/faiss_index.bin
data/indexes/faiss_id_map.json
data/indexes/offset_index.json
data/indexes/index_meta.json
```

`data/indexes/bm25_index.pkl` is optional for the Hugging Face deployment because
the free Space storage limit is 1 GB. When it is absent, the app still runs with
FAISS retrieval and skips the BM25 side of hybrid search.

If indexes need to be rebuilt:

```bash
python scripts/build_fast_indexes.py --profiles data/candidates.jsonl
```

## Hugging Face Spaces Deploy

Create a new Space with SDK `Gradio`, then push this repository.

Because `.gitignore` excludes large data/index files, add them explicitly:

```bash
git add app.py requirements.txt README.md
git add src configs scripts rank.py submission.csv submission_metadata.yaml
git add -f data/candidates.jsonl data/indexes/faiss_index.bin data/indexes/faiss_id_map.json data/indexes/offset_index.json data/indexes/index_meta.json
git commit -m "Deploy candidate ranker to Hugging Face Spaces"
git push space main
```

Use Turbo Mode in the UI for deployment unless LLM provider secrets are configured in the Space settings.