How adityajaiswal440/india-runs-hackathon works
1. What this repository is
- This is a batch candidate-ranking pipeline, not a long-running service.
- It takes candidate profile data plus a job-description target, computes offline features, ranks candidates deterministically, and writes a submission file (era.csv).
2. Core architectural boundary: precompute vs. rank
- The repo is split into two phases:
- Precomputation: stream and normalize raw candidate data, extract features, build embeddings, and persist artifacts.
- Online ranking: load those artifacts, combine scores, apply penalties/multipliers, and emit final ranked output.
- This separation is central to the architecture because it keeps runtime memory and latency low.
3. Data ingress and storage
- Raw inputs live under data/raw/, with intermediate workspace under data/interim/.
- Precomputed outputs are stored in artifacts/, including candidate IDs, dense embeddings, and feature matrices.
- The code expects offline local files only; there is no external network dependency in the ranking flow.
4. Ingestion and normalization layer
- src/data/loader.py and the helpers in src/utils/text_cleaner.py and src/challenge/text_match.py handle JSONL loading, tokenization, and text normalization.
- This layer is responsible for turning noisy profile text into stable, reusable inputs for scoring.
5. Feature extraction subsystem
- src/features/embedder.py and src/features/heuristic_extractor.py build the candidate feature set.
- Feature extraction produces both:
- semantic features from embeddings and text similarity, and
- structural/heuristic features from resume content, experience patterns, and metadata.
- src/challenge/features.py wraps these into a candidate index used by later scoring stages.
6. Domain-scoring rules live in src/challenge/
- This package contains the job-description schema, scoring heuristics, availability logic, company-year checks, and assessment handling.
- Key modules include:
- jd_config.py for skill/title taxonomies and thresholds,
- availability.py for recency and engagement logic,
- assessment.py for verified-skill weighting,
- company_matrix.py and career_blurb.py for consistency checks and duplicate/template detection.
- This is the main “business logic” boundary of the system.
7. Semantic retrieval path
- src/challenge/embeddings.py, semantic.py, and text_match.py implement the semantic side of matching.
- The repository uses offline embedding-based similarity plus lexical/phrase matching to capture both broad fit and exact term overlap.
- src/challenge/rerank.py is an optional reranking hook, while redrob_ranker.py is the primary orchestrator.
8. Anti-gaming / fraud detection boundary
- src/challenge/honeypot.py is a dedicated fraud/quality filter.
- It checks for structural anomalies such as impossible dates, unrealistic tenure, template-like resumes, and other “honeypot” conditions.
- This subsystem acts as a gate before candidates can rise into the top ranks.
9. Ranking assembly
- src/challenge/redrob_ranker.py combines the component scores into the final ranking signal.
- src/ranking/heuristic_scorer.py performs the heuristic weighting/fusion, and src/challenge/rerank.py can optionally add a second semantic pass.
- The ranking order is deterministic, with explicit tie-breaking by candidate ID.
10. Reasoning and output generation
- src/ranking/reasoning_gen.py produces grounded explanations for ranked candidates.
- src/pipeline.py is the top-level CLI entrypoint that runs the whole flow and writes the submission output.
- run_pipeline.py is the root wrapper used for invoking the pipeline from the repository root.
11. Operational tooling and verification
- scripts/precompute.py prepares offline artifacts; the audit/sensitivity scripts in scripts/ check submission quality and robustness.
- src/validate_submission.py and the tests/ suite enforce correctness, determinism, and output-shape expectations.
- The tests cover data loading, embedding extraction, heuristic extraction, precompute behavior, and ranking logic.
12. Configuration and runtime controls
- src/config/defaults.py and src/utils/config.py centralize runtime settings and fixed reference values.
- src/utils/logger.py supports consistent pipeline logging.
- The repo is designed around CPU-only execution, offline operation, and reproducible scoring.
13. How to draw the architecture
- A clear diagram would show:
- Raw data inputs → load/clean → feature extraction → artifact storage
- then artifacts → ranking/orchestration → fraud filtering + scoring fusion → reasoning generation → era.csv output
- Surrounding that path are the config layer, audit/validation tools, and test suite, which enforce determinism and guardrails.
Main entry points: redrob_ranker.py Redrob ranker · loader.py Loader · pipeline.py Pipeline · features.py Feature index
Components 23
Precompute phase
Offline ingestion, normalization, feature extraction, and artifact writing.
- Raw data · Candidate JSONL and job-description inputs stored locally under data/raw/.
data/raw/sample_candidates.jsonl - Loader · Reads JSONL inputs and prepares records for downstream processing.
src/data/loader.py - Text clean · Tokenization and text normalization for noisy resume and JD content.
src/utils/text_cleaner.py - Text match · Phrase and lexical matching used during normalization and feature creation.
src/challenge/text_match.py - Embedder · Builds dense semantic representations for candidates and job text.
src/features/embedder.py - Heuristic feats · Extracts resume structure, experience patterns, and metadata-based features.
src/features/heuristic_extractor.py - Feature index · Wraps extracted features into the candidate-facing feature index used by ranking.
src/challenge/features.py - Artifacts · Persisted embeddings, feature matrices, and candidate IDs used by the ranking phase.
artifacts/features.npy
Ranking phase
Artifact-driven candidate scoring, fraud filtering, reranking, and output generation.
- Pipeline · Top-level entrypoint that runs the end-to-end flow and writes submission output.
src/pipeline.py - Runner · Root-level wrapper for invoking the pipeline from the repository root.
run_pipeline.py - Redrob ranker · Combines semantic, heuristic, and gating signals into the final rank order.
src/challenge/redrob_ranker.py - Honeypot · Rejects structural anomalies, impossible dates, template resumes, and other quality issues.
src/challenge/honeypot.py - Domain rules · Job-description schema, availability logic, assessment weighting, and consistency checks.
src/challenge/jd_config.py - Semantic match · Embedding-based and lexical semantic matching for candidate-job fit.
src/challenge/semantic.py - Rerank · Optional second-pass reranking hook for semantic refinement.
src/challenge/rerank.py - Heuristic score · Weights and fuses rule-based signals into the final candidate score.
src/ranking/heuristic_scorer.py - Reasoning · Generates grounded candidate explanations for the final submission.
src/ranking/reasoning_gen.py
Ops and guardrails
Configuration, validation, scripts, and tests that keep the pipeline deterministic.
- Data paths · Centralized repository-local path resolution for raw, interim, and artifact files.
src/challenge/data_paths.py - Defaults · Central runtime settings and fixed reference values.
src/config/defaults.py - Config utils · Loads and manages pipeline configuration values.
src/utils/config.py - Validate · Enforces output shape, determinism, and submission correctness.
src/validate_submission.py - Scripts · Offline precompute and audit/sensitivity utilities for submission quality.
scripts/precompute.py - Tests · Coverage for loading, embeddings, feature extraction, precompute, and ranking.
tests/test_ranker.py
Connections 27
- Raw data → Loader: load · Raw candidate data is ingested from local files.
- Loader → Text clean: normalize · Loaded records are cleaned and tokenized.
- Text clean → Text match: lexical prep · Normalized text is prepared for phrase and term matching.
- Text clean → Embedder: semantic prep · Clean text feeds embedding generation.
- Loader → Heuristic feats: structure prep · Record structure and metadata feed heuristic extraction.
- Text match → Feature index: signals · Lexical matching contributes to the candidate feature index.
- Embedder → Feature index: embeddings · Dense semantic vectors become part of the feature index.
- Heuristic feats → Feature index: heuristics · Structural features are folded into the candidate index.
- Feature index → Artifacts: persist · Precomputed features and IDs are written to offline artifacts.
- Data paths → Loader: resolve · Repository-local paths are used for data ingress.
- Data paths → Artifacts: locate · Artifact directories and files are resolved centrally.
- Defaults → Config utils: base settings · Defaults provide the baseline runtime configuration.
- Config utils → Pipeline: runtime config · Pipeline execution uses configured runtime values.
- Scripts → Artifacts: precompute · Scripts populate offline artifacts before ranking.
- Artifacts → Redrob ranker: load · Ranking consumes the precomputed artifacts.
- Redrob ranker → Honeypot: gate · Quality and fraud checks filter candidates before ranking.
- Redrob ranker → Domain rules: apply · Domain-specific rules shape the scoring logic.
- Redrob ranker → Semantic match: score · Semantic similarity contributes to candidate ranking.
- Redrob ranker → Heuristic score: fuse · Heuristic scoring fuses multiple signal families.
- Semantic match → Rerank: refine · Optional reranking adds a second semantic pass.
- Rerank → Redrob ranker: feedback · Rerank can feed refined ordering back into the orchestrator.
- Honeypot → Reasoning: filter context · Filtered candidates move into explanation generation.
- Heuristic score → Reasoning: ranked signal · Final scores inform candidate reasoning output.
- Reasoning → Pipeline: emit · Reasoned ranking output is assembled for submission.
- Pipeline → Runner: invoke · Root wrapper launches the top-level pipeline.
- Pipeline → Validate: check · Submission output is validated before completion.
- Validate → Tests: verify · Validation logic is reinforced by the test suite.