SignalHire
Technical Documentation

Version 1.0 · June 2026 · AI-Powered Candidate Ranking for the Redrob AI Challenge

Overview

SignalHire is an AI-powered candidate ranking system that processes 100,000 candidate profiles and surfaces the top 100 best matches for a Senior AI Engineer role. Built for the Redrob AI Challenge at the India Runs Hackathon.

The Problem

Given a 487 MB JSONL file containing 100K candidate profiles — including keyword stuffers, ~80 honeypot/adversarial profiles, behavioral twins, and strong engineers who describe themselves in plain language — identify and rank the top 100 candidates for a Senior AI Engineer position.

The Solution

A two-phase offline hybrid scoring pipeline:

• Phase A (Precompute) — Embedding generation + multi-signal sub-score computation (GPU optional via EMBEDDING_DEVICE=cuda)
• Phase B (Ranking) — CPU-only composite scoring via vectorized matrix operations, evidence-based reasoning, and validated CSV output

Quick Start

# Clone and setup
git clone https://github.com/DevanshSrajput/SignalHire.git
cd SignalHire
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Step 1: Precompute (CPU default; GPU ~10× faster)
python precompute.py
# or:
EMBEDDING_DEVICE=cuda python precompute.py

# Step 2: Rank → output/submission.csv
python rank.py

# Step 3: Dashboard
streamlit run app.py  # http://localhost:8501

Prerequisites

Docker

Artifacts are baked into the image — only candidates.jsonl needs to be mounted at runtime.

# Build (bakes precomputed artifacts, pre-downloads embedding model)
docker build -t signalhire .

# Rank (mount candidates.jsonl in, get submission.csv out)
docker run --rm \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/output:/app/output \
  signalhire

# Dashboard
docker run --rm -p 8501:8501 \
  -v $(pwd)/data:/app/data \
  signalhire streamlit run app.py --server.port=8501 --server.address=0.0.0.0

Two-Phase Pipeline

                    candidates.jsonl (100K, 487 MB)
                            │
                            ▼
          ┌──────────────────────────────────────┐
          │  PHASE A: Precompute (GPU, ~4 min)   │
          │                                      │
          │  Stream JSONL ─► Disqualify fakes    │
          │         └──► Embed (MiniLM, 384-dim) │
          │         └──► Compute 4 sub-scores    │
          │         └──► Serialize artifacts     │
          └──────────────┬───────────────────────┘
                         │  embeddings.npy + subscores.pkl (~155 MB)
                         ▼
          ┌──────────────────────────────────────┐
          │  PHASE B: Ranking (CPU, <10 s)       │
          │                                      │
          │  Load artifacts ─► Cosine similarity │
          │         └──► Weighted composite      │
          │         └──► argsort → top 100       │
          │         └──► Evidence-based reasoning│
          │         └──► Validate & write CSV    │
          └──────────────┬───────────────────────┘
                         │
                         ▼
          ┌──────────────────────────────────────┐
          │  DASHBOARD (CPU, ~50 ms re-rank)     │
          │  Weight UI → Live matrix re-score    │
          │  6 interactive tabs                  │
          └──────────────────────────────────────┘

Dependency Graph

Layer 0 — leaf modules (no project imports):
    textmatch.py ─── re, functools
    config.py    ─── os, re, pathlib

Layer 1:
    disqualify.py ──► config, textmatch

Layer 2:
    signals.py   ──► config, disqualify, textmatch

Layer 3:
    evidence.py  ──► config, signals, textmatch
    engine.py    ──► config

Layer 4:
    precompute.py ──► config, disqualify, signals + sentence_transformers

Layer 5:
    rank.py      ──► config, engine, evidence

Layer 6:
    app.py       ──► config, engine, evidence, rank + streamlit, plotly

Data Flow

candidates.jsonl ──► precompute.py ──► artifacts/
                          │                 ├── embeddings.npy     (99965×384, float32)
                          │                 ├── candidate_ids.npy  (99965 strings)
                          │                 ├── jd_embedding.npy   (384, float32)
                          │                 ├── subscores.pkl      (99965 dicts)
                          │                 ├── disqualified.json  (~35 records)
                          │                 └── demographics.csv
                          │
                          └── rank.py ──► output/submission.csv
                              app.py  ──► Streamlit dashboard (http://localhost:8501)

Module Reference

config.py — Configuration Hub

Single source of truth for all paths, weights, keyword lists, penalties, and thresholds. Every other module imports from here — no magic numbers elsewhere.

Path Constants

Scoring Weights

WEIGHTS = {
    "technical_fit":       0.35,
    "career_quality":      0.25,
    "availability_signal": 0.20,
    "seniority_fit":       0.12,
    "semantic_similarity": 0.08,
}
# Sum is asserted to equal 1.0

Embedding Configuration

Penalty Constants

textmatch.py — Keyword Matching Engine

Word-boundary-aware keyword matching. Prevents false positives like "rag" matching inside "storage" or "map" inside "bitmap".

Design: Keywords ≥4 characters use stem matching (\b{kw}\w*), allowing "eval" → "evaluation". Keywords <4 characters require exact word match (\b{kw}\b).

disqualify.py — Adversarial Profile Detection

Identifies and removes adversarial profiles before scoring. Three hard-disqualify checks, plus soft penalties for borderline profiles.

signals.py — Sub-Score Computation

Computes the four primary sub-scores. Each returns a float in [0, 1].

evidence.py — Provenance & Reasoning

Traces every JD requirement match back to the specific skill or career sentence that triggered it. Generates honest, evidence-cited reasoning strings for the output CSV.

engine.py — Vectorized Ranking Engine

All ranking math as vectorized NumPy operations. Every operation works on precomputed matrices — no per-candidate loops.

precompute.py — Phase A Pipeline

The expensive one-time computation phase. Streams 487 MB JSONL, removes adversarial profiles, embeds all valid profiles with all-MiniLM-L6-v2, computes all sub-scores, serializes to disk.

rank.py — Phase B Pipeline

Loads precomputed artifacts, calculates composite scores, selects top 100, generates evidence-based reasoning, writes validated CSV.

app.py — Interactive Dashboard

Six-tab Streamlit workbench. All scoring is a single float32 matrix multiply over precomputed artifacts — ~50 ms for 100K candidates regardless of which tab or slider is active.

Scoring Methodology

Composite Formula

S = penalty_multiplier × (
    0.35 × technical_fit
  + 0.25 × career_quality
  + 0.20 × availability_signal
  + 0.12 × seniority_fit
  + 0.08 × semantic_similarity
)

All sub-scores ∈ [0, 1]
penalty_multiplier ∈ [0.12, 1.0]
Final score scaled to [0, 10] in output CSV

Technical Fit (0.35)

Proficiency weights: expert=1.0, advanced=0.75, intermediate=0.4, beginner=0.1. Platform assessment scores override self-reported proficiency.

Career Quality (0.25)

• Non-consulting role presence → +0.30
• ML/AI title at company with ≥50 employees → +0.15
• Median tenure ≥36 months → +0.25 · ≥24 months → +0.20 · ≥18 months → +0.05
• Upward title progression (last role seniority > first) → +0.20

Availability Signal (0.20)

• open_to_work_flag → +0.25
• Last active ≤30d → +0.20 · ≤90d → +0.12 · ≤180d → +0.06
• recruiter_response_rate → × 0.15
• interview_completion_rate → × 0.15
• Active applications (>0) → +0.05
• Notice period ≤30d → +0.05 · ≤60d → +0.035

Seniority Fit (0.12)

Education bonus: Tier-1 (IIT, IISc, NIT, BITS...) → +0.05. Tier-2 (DTU, VIT, SRM...) → +0.02.

Semantic Similarity (0.08)

Cosine similarity between the candidate's 384-dim all-MiniLM-L6-v2 embedding and the JD embedding. This is the "safety net" — catches strong engineers whose plain-language descriptions miss keyword checks.

Penalty Multipliers

Data Schemas

Input: candidates.jsonl

{
  "candidate_id": "CAND_0000001",
  "profile": {
    "name": "...",
    "headline": "Senior ML Engineer | NLP & Search",
    "years_of_experience": 7,
    "current_title": "Senior ML Engineer",
    "current_company": "Razorpay",
    "company_size": "1001-5000"
  },
  "career_history": [{
    "company": "Razorpay", "title": "Senior ML Engineer",
    "start_date": "2022-03", "end_date": "present",
    "is_current": true,
    "description": "Built embedding-based retrieval pipeline..."
  }],
  "skills": [{ "name": "Python", "proficiency": "expert" }],
  "redrob_signals": {
    "profile_completeness_score": 92,
    "open_to_work_flag": true,
    "recruiter_response_rate": 0.73,
    "notice_period_days": 30,
    "last_active_date": "2026-05-28",
    "verified_email": true
  }
}

Internal: Artifacts

Output: submission.csv

candidate_id,rank,score,reasoning
CAND_0081846,1,8.70,"6.7yr Lead AI Engineer at Razorpay; strong match on embeddings, vector search,
python, information retrieval; production evidence (serving, ndcg);
actively looking, 73% response rate, 30d notice."

Deployment

Local Development

EMBEDDING_DEVICE=cuda python precompute.py  # Phase A: ~4 min GPU
python rank.py                               # Phase B: ~3 s
streamlit run app.py                         # Dashboard: http://localhost:8501

HuggingFace Space

Live demo at huggingface.co/spaces/DevanshSrajput/SignalHire — Docker SDK with precomputed artifacts for the 50-candidate sample dataset. All dashboard tabs work identically to the full 100K version.

Sandbox Constraints

Performance Benchmarks

Measured on NVIDIA RTX 3050 (6 GB) + 12-core CPU

Initial Documentation Archive

The original planning documents that guided SignalHire's development are preserved in the Initial-Documentation/ directory. These were the blueprints — the code is the building.

PRD — Product Requirements

The RecruiterIQ PRD defines the core problem: rank 100K candidates for a Senior AI Engineer role, defeat adversarial profiles, and surface the top 100 with honest evidence-based reasoning. It established the five-signal scoring formula and the evaluation criteria (recall of known good candidates, 0 honeypots in top 100).

TRD — Technical Requirements

The TRD translates the PRD into hard constraints: CPU-only inference, 16 GB RAM limit, 5-minute wall-clock budget, no network access, deterministic reproducibility. It specified the offline precompute architecture as the solution to the GPU/CPU split.

App Flow

The APP_FLOW document traces every user interaction through the system: from JSONL load to artifact production (Phase A), from artifact load to CSV output (Phase B), and from sidebar control to live matrix multiply (Dashboard). It includes the state machine for the Streamlit session and error handling for missing artifacts.

Implementation Plan

A 9-phase build roadmap: (1) config skeleton → (2) keyword matching → (3) disqualification → (4) sub-scores → (5) evidence → (6) vectorized engine → (7) precompute → (8) rank → (9) dashboard. Each phase has acceptance criteria, code snippets, and a risk register entry.

UI/UX Design

The UIUX document specifies the exact layout of each Streamlit tab, the color palette (dark theme with indigo/violet/green/amber accents), component hierarchy (cards → badges → bars → chips), and the sidebar control order. The stability badge design and MMR slider range were specified here.

FAQ

Why two phases instead of one?

The sandbox is CPU-only with a 5-minute time limit. Precomputing embeddings (GPU) separately keeps Phase B well under the budget.

How does it handle keyword stuffers?

Multi-signal scoring. A candidate who stuffs "Python" 50 times gets high technical_fit but still needs career_quality, availability_signal, and seniority_fit. No single signal can game the composite score.

Why all-MiniLM-L6-v2 over larger models?

Best accuracy-to-speed tradeoff for 100K profiles. 384 dimensions, ~60 MB model, <200 ms per batch of 2048. Larger models would exceed the RAM/time budget.

Why is the consulting penalty so severe (×0.15)?

For this specific JD, all-consulting careers at service firms rarely involve the depth of AI/ML work required. In a production system, it would be a configurable threshold, not a constant.

How is the stability badge calculated?

200 Monte Carlo trials with ±20% random weight perturbation. Frequency in top-100: >95% → "stable", 70–95% → "moderate", <70% → "fragile".