https://github.com/shuddha2021/stellar-candidate-selector
A sophisticated candidate selection algorithm leveraging multi-criteria analysis and machine learning to identify top software engineering candidates. This tool features flexible filtering, score adjustment, and detailed visualizations to streamline the recruitment process.
https://github.com/shuddha2021/stellar-candidate-selector
candidate-selection data-analysis data-visualization machine-learning pandas plotting-in-python python python-data-analysis recruitment scikit-learn
Last synced: 2 months ago
JSON representation
A sophisticated candidate selection algorithm leveraging multi-criteria analysis and machine learning to identify top software engineering candidates. This tool features flexible filtering, score adjustment, and detailed visualizations to streamline the recruitment process.
- Host: GitHub
- URL: https://github.com/shuddha2021/stellar-candidate-selector
- Owner: shuddha2021
- Created: 2024-06-03T20:21:49.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-03T20:30:23.000Z (about 2 years ago)
- Last Synced: 2025-09-07T14:45:38.861Z (10 months ago)
- Topics: candidate-selection, data-analysis, data-visualization, machine-learning, pandas, plotting-in-python, python, python-data-analysis, recruitment, scikit-learn
- Language: Python
- Homepage:
- Size: 4.88 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Stellar Candidate Selector
A **production-grade candidate ranking engine** that combines multi-criteria analysis, ML-powered score adjustment, and rich visualizations to identify top software engineering candidates.
---
## Features
| Feature | Description |
|---------|-------------|
| **Pydantic v2 Models** | Type-safe `Candidate`, `Skill`, `Criteria` with validation, proficiency levels |
| **Skill Proficiency** | Three-tier system (Expert / Proficient / Familiar) with weighted scoring |
| **Adaptive ML Model** | Ridge regression for small sets, Gradient Boosting for larger pools |
| **Multi-Stage Pipeline** | Filter → Skill Score → ML Adjust → Weighted Rank |
| **Config-Driven** | External `criteria.json` — adjust weights, thresholds, skills without code changes |
| **4-Panel Dashboard** | Horizontal bar, grouped breakdown, experience scatter, top-candidate profile |
| **CLI Interface** | `argparse`-based with `--criteria`, `--save-chart`, `--no-chart`, `--verbose` |
| **Certification Bonus** | Candidates with certifications earn a capped bonus in skill scoring |
| **Comprehensive Tests** | 25+ pytest tests covering models, engine, config, edge cases |
| **Clean Architecture** | Modular `src/` layout — models, engine, config, visualize, sample data |
---
## Architecture
```
stellar-candidate-selector/
├── criteria.json # Selection criteria config
├── pyproject.toml # Build config, deps, scripts
├── src/stellar_selector/
│ ├── __init__.py # Public API exports
│ ├── __main__.py # CLI entry point
│ ├── models.py # Pydantic models: Candidate, Skill, Criteria
│ ├── engine.py # ScoringEngine: filter → score → ML → rank
│ ├── config.py # Load criteria from JSON/dict/file
│ ├── visualize.py # Console report + Matplotlib dashboard
│ └── sample_data.py # 8 diverse demo candidates
└── tests/
├── test_models.py # Model validation & property tests
├── test_engine.py # Pipeline, filtering, scoring, edge cases
└── test_config.py # Config loading from file/string/dict
```
### Scoring Pipeline
```
Candidates → Filter (experience, skills, score) → Skill Match Score
→ ML Adjustment (Ridge / GradientBoosting) → Weighted Final Score → Rank
```
**Weights** (configurable in `criteria.json`):
- `experience_weight` (0.3) — normalised years of experience
- `skills_weight` (0.4) — required + preferred skill match with proficiency
- `score_weight` (0.3) — ML-adjusted assessment score
---
## Prerequisites
- **Python** 3.12+
- **pip** 23+
## Getting Started
```bash
# Clone
git clone https://github.com/shuddha2021/stellar-candidate-selector.git
cd stellar-candidate-selector
# Install (editable mode with dev deps)
pip install -e ".[dev]"
# Run
python -m stellar_selector
# Or use the installed script
stellar-selector
```
## Usage
```bash
# Default run with criteria.json
python -m stellar_selector
# Custom criteria file
python -m stellar_selector --criteria my_criteria.json
# Save chart to file
python -m stellar_selector --save-chart results.png
# Skip chart, just print table
python -m stellar_selector --no-chart
# Verbose debug logging
python -m stellar_selector -v
```
### Sample Output
```
================================================================================
STELLAR CANDIDATE SELECTOR — Ranking Report
================================================================================
Candidates evaluated : 8
Passed filtering : 4
Rejected : 4
ML model R² : 0.9987
Rank Name Exp Skills ML Adj Final
──────────────────────────────────────────────────────────────
1 Senior Dev 7 2.35 94.00 33.59
2 Lisa Park 4 2.08 91.00 31.08
3 Mid Dev 4 1.70 85.00 28.92
4 Tom Brown 6 1.78 87.00 29.46
★ Top Candidate: Senior Dev — Final Score 33.59
================================================================================
```
## Running Tests
```bash
pytest
# With coverage
pytest --cov=stellar_selector --cov-report=term-missing
```
Tests cover:
- **Models** — Skill equality/hashing, candidate validation, proficiency lookup, criteria defaults
- **Engine** — Experience filtering, skill filtering, score filtering, ranking order, ranks assignment, skill proficiency weighting, ML R² reporting
- **Config** — Loading from dict, JSON string, file, invalid JSON handling
- **Edge cases** — Empty candidates, single candidate, no required/preferred skills, all filtered out
---
## Configuration
Edit `criteria.json` to tune the selection:
```json
{
"min_experience": 3,
"required_skills": ["Python", "Java"],
"preferred_skills": ["AWS", "React", "Kubernetes"],
"experience_weight": 0.3,
"skills_weight": 0.4,
"score_weight": 0.3,
"min_base_score": 0,
"top_n": 5
}
```
| Field | Type | Description |
|-------|------|-------------|
| `min_experience` | int | Minimum years to pass filter |
| `required_skills` | list | Must-have skills (all required) |
| `preferred_skills` | list | Bonus skills (0.5× weight) |
| `experience_weight` | float | Weight for experience component (0–1) |
| `skills_weight` | float | Weight for skill match component (0–1) |
| `score_weight` | float | Weight for ML-adjusted score component (0–1) |
| `min_base_score` | float | Minimum assessment score to pass filter |
| `top_n` | int | Number of top candidates to highlight |
---
## Technologies
| Technology | Version | Purpose |
|------------|---------|---------|
| Python | 3.12+ | Language runtime — type hints, StrEnum, modern syntax |
| Pydantic | 2.10+ | Data validation, serialisation, model_copy |
| pandas | 2.2+ | Data manipulation (internal) |
| NumPy | 2.1+ | Numerical arrays for ML features |
| scikit-learn | 1.6+ | Ridge regression, Gradient Boosting, StandardScaler |
| Matplotlib | 3.10+ | 4-panel dashboard visualisation |
| pytest | 8.3+ | Test framework with fixtures & parametrisation |
---
## License
This project is licensed under the MIT License.