How soumadipta-konar/fitrank-ai works
1. Overall shape
- FitRank AI is an offline candidate-ranking pipeline for a hiring challenge, not an interactive app.
- The architecture is centered on taking a job description plus candidate data and producing a ranked top-100 shortlist.
2. Orchestration layer
- rank.py appears to be the main entry point that ties the system together.
- It likely coordinates loading data, building features, running the ranking stages, and producing the final output.
3. Data ingestion boundary
- src/data_loader.py is the input boundary for the system.
- This module likely normalizes raw challenge data into internal structures for jobs, candidates, skills, career history, and any recruiter-behavior signals.
4. Candidate reduction / prefiltering
- src/prefilter.py is a first-pass narrowing stage.
- Its role is probably to eliminate obviously irrelevant candidates before heavier semantic or scoring logic runs, which matters for performance and shortlist quality.
5. Feature engineering layer
- src/features.py is the main signal-construction module.
- Based on the README, this is where candidate/job attributes are turned into features such as skills overlap, experience alignment, career history patterns, and risk indicators.
6. Semantic matching subsystem
- src/semantic_ranker.py handles the “meaning-based” match between job description and candidate profile.
- This is the part of the system that goes beyond keyword overlap and supports the repo’s stated goal of semantic job-candidate matching.
7. Lexical matching subsystem
- src/lexical_ranker.py likely provides a more direct text/surface-form ranking signal.
- In the overall architecture, it complements semantic matching by capturing exact or near-exact keyword and phrase matches.
8. Scoring and fusion
- src/scoring.py appears to combine multiple signals into a final ranking score.
- The README suggests this fused score includes skill and experience matching, recruiter-behavior signals, and penalties for risk/honeypot cases.
9. Final output generation
- src/submission.py is the output boundary.
- It likely formats the ranked candidate list into the challenge-required submission structure, enforcing the top-100 shortlist requirement.
10. Experimentation and analysis
- notebooks/fitrank_ai.ipynb is the exploratory workspace.
- It likely contains model experimentation, feature validation, ranking analysis, and tuning that informed the production pipeline in src/.
11. Key architectural boundary
- The important design boundary is between candidate retrieval/filtering and multi-signal ranking.
- The system first reduces the search space, then applies lexical, semantic, and heuristic scoring to produce a trustworthy shortlist.
12. What to show in an architecture diagram
- A good diagram should show: raw challenge data → data loading → prefiltering → feature extraction → lexical/semantic rankers → scoring/fusion → submission output.
- The diagram should also show the notebook as a sidecar for offline experimentation, not part of the core runtime path.
Main entry points: rank.py rank.py · features.py Features · scoring.py Scoring · data_loader.py Data loader
Components 11
Core pipeline
Offline candidate-ranking runtime from input loading to submission output.
- rank.py · Main entry point that coordinates the ranking pipeline.
rank.py - Data loader · Loads and normalizes challenge job and candidate data.
src/data_loader.py - Prefilter · First-pass narrowing stage that removes obviously weak candidates.
src/prefilter.py - Features · Builds structured signals from job and candidate attributes.
src/features.py - Lexical ranker · Scores direct keyword and phrase overlap between job and candidate text.
src/lexical_ranker.py - Semantic ranker · Computes deeper semantic similarity between job requirements and candidate profiles.
src/semantic_ranker.py - Scoring · Combines ranking signals and penalties into the final score.
src/scoring.py - Submission · Formats the ranked shortlist into the required challenge submission.
src/submission.py
Offline analysis
Notebook used for experimentation and tuning outside the main runtime path.
- Notebook · Offline experimentation and analysis workspace.
notebooks/fitrank_ai.ipynb
Other components
- Challenge data · Raw hiring-challenge job and candidate data consumed by the pipeline.
- Top-100 shortlist · Final ranked candidate list produced by the system.
Connections 20
- Challenge data → Data loader: load · Raw input is ingested and normalized.
- Data loader → Prefilter: candidates · Loaded records feed the narrowing stage.
- Data loader → Features: job/candidate data · Normalized entities are converted into features.
- Prefilter → Features: filtered set · Reduced candidate pool proceeds to feature construction.
- Features → Lexical ranker: text signals · Feature layer supplies surface-form matching inputs.
- Features → Semantic ranker: profile signals · Feature layer supplies semantic matching inputs.
- Lexical ranker → Scoring: lexical score · Surface-form match contributes to the fused score.
- Semantic ranker → Scoring: semantic score · Meaning-based match contributes to the fused score.
- Prefilter → Scoring: candidate gate · Prefiltering constrains the pool scored downstream.
- Scoring → Submission: ranked list · Final scores are converted into the required output format.
- Submission → Top-100 shortlist: emit · Top-100 shortlist is produced for delivery.
- rank.py → Data loader: orchestrate · Main script coordinates loading.
- rank.py → Prefilter: orchestrate · Main script coordinates candidate reduction.
- rank.py → Features: orchestrate · Main script coordinates feature construction.
- rank.py → Lexical ranker: orchestrate · Main script coordinates lexical scoring.
- rank.py → Semantic ranker: orchestrate · Main script coordinates semantic scoring.
- rank.py → Scoring: orchestrate · Main script coordinates score fusion.
- rank.py → Submission: orchestrate · Main script coordinates final output generation.
- Notebook → Features: explore · Notebook informs feature design and tuning.
- Notebook → Scoring: analyze · Notebook supports experimentation with weighting and ranking behavior.