{"id":18537159,"url":"https://github.com/shuddha2021/stellar-candidate-selector","last_synced_at":"2026-05-05T08:32:00.215Z","repository":{"id":242589627,"uuid":"809979195","full_name":"shuddha2021/stellar-candidate-selector","owner":"shuddha2021","description":"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.","archived":false,"fork":false,"pushed_at":"2024-06-03T20:30:23.000Z","size":5,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-07T14:45:38.861Z","etag":null,"topics":["candidate-selection","data-analysis","data-visualization","machine-learning","pandas","plotting-in-python","python","python-data-analysis","recruitment","scikit-learn"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shuddha2021.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-03T20:21:49.000Z","updated_at":"2025-06-13T15:37:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"3af4b765-51fb-446e-b012-4cad41600947","html_url":"https://github.com/shuddha2021/stellar-candidate-selector","commit_stats":null,"previous_names":["shuddha2021/stellar-candidate-selector"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shuddha2021/stellar-candidate-selector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuddha2021%2Fstellar-candidate-selector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuddha2021%2Fstellar-candidate-selector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuddha2021%2Fstellar-candidate-selector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuddha2021%2Fstellar-candidate-selector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shuddha2021","download_url":"https://codeload.github.com/shuddha2021/stellar-candidate-selector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuddha2021%2Fstellar-candidate-selector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32642007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"online","status_checked_at":"2026-05-05T02:00:06.033Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["candidate-selection","data-analysis","data-visualization","machine-learning","pandas","plotting-in-python","python","python-data-analysis","recruitment","scikit-learn"],"created_at":"2024-11-06T19:37:16.317Z","updated_at":"2026-05-05T08:32:00.208Z","avatar_url":"https://github.com/shuddha2021.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stellar Candidate Selector\n\n![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white)\n![Pydantic](https://img.shields.io/badge/Pydantic-v2-E92063?style=flat-square)\n![scikit-learn](https://img.shields.io/badge/scikit--learn-1.6+-F7931E?style=flat-square\u0026logo=scikit-learn\u0026logoColor=white)\n![Pandas](https://img.shields.io/badge/Pandas-2.2+-150458?style=flat-square\u0026logo=pandas\u0026logoColor=white)\n![Tests](https://img.shields.io/badge/Tests-25%2B_pytest-4B8BBE?style=flat-square)\n![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)\n\nA **production-grade candidate ranking engine** that combines multi-criteria analysis, ML-powered score adjustment, and rich visualizations to identify top software engineering candidates.\n\n---\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Pydantic v2 Models** | Type-safe `Candidate`, `Skill`, `Criteria` with validation, proficiency levels |\n| **Skill Proficiency** | Three-tier system (Expert / Proficient / Familiar) with weighted scoring |\n| **Adaptive ML Model** | Ridge regression for small sets, Gradient Boosting for larger pools |\n| **Multi-Stage Pipeline** | Filter → Skill Score → ML Adjust → Weighted Rank |\n| **Config-Driven** | External `criteria.json` — adjust weights, thresholds, skills without code changes |\n| **4-Panel Dashboard** | Horizontal bar, grouped breakdown, experience scatter, top-candidate profile |\n| **CLI Interface** | `argparse`-based with `--criteria`, `--save-chart`, `--no-chart`, `--verbose` |\n| **Certification Bonus** | Candidates with certifications earn a capped bonus in skill scoring |\n| **Comprehensive Tests** | 25+ pytest tests covering models, engine, config, edge cases |\n| **Clean Architecture** | Modular `src/` layout — models, engine, config, visualize, sample data |\n\n---\n\n## Architecture\n\n```\nstellar-candidate-selector/\n├── criteria.json                  # Selection criteria config\n├── pyproject.toml                 # Build config, deps, scripts\n├── src/stellar_selector/\n│   ├── __init__.py                # Public API exports\n│   ├── __main__.py                # CLI entry point\n│   ├── models.py                  # Pydantic models: Candidate, Skill, Criteria\n│   ├── engine.py                  # ScoringEngine: filter → score → ML → rank\n│   ├── config.py                  # Load criteria from JSON/dict/file\n│   ├── visualize.py               # Console report + Matplotlib dashboard\n│   └── sample_data.py             # 8 diverse demo candidates\n└── tests/\n    ├── test_models.py             # Model validation \u0026 property tests\n    ├── test_engine.py             # Pipeline, filtering, scoring, edge cases\n    └── test_config.py             # Config loading from file/string/dict\n```\n\n### Scoring Pipeline\n\n```\nCandidates → Filter (experience, skills, score) → Skill Match Score\n    → ML Adjustment (Ridge / GradientBoosting) → Weighted Final Score → Rank\n```\n\n**Weights** (configurable in `criteria.json`):\n- `experience_weight` (0.3) — normalised years of experience\n- `skills_weight` (0.4) — required + preferred skill match with proficiency\n- `score_weight` (0.3) — ML-adjusted assessment score\n\n---\n\n## Prerequisites\n\n- **Python** 3.12+\n- **pip** 23+\n\n## Getting Started\n\n```bash\n# Clone\ngit clone https://github.com/shuddha2021/stellar-candidate-selector.git\ncd stellar-candidate-selector\n\n# Install (editable mode with dev deps)\npip install -e \".[dev]\"\n\n# Run\npython -m stellar_selector\n\n# Or use the installed script\nstellar-selector\n```\n\n## Usage\n\n```bash\n# Default run with criteria.json\npython -m stellar_selector\n\n# Custom criteria file\npython -m stellar_selector --criteria my_criteria.json\n\n# Save chart to file\npython -m stellar_selector --save-chart results.png\n\n# Skip chart, just print table\npython -m stellar_selector --no-chart\n\n# Verbose debug logging\npython -m stellar_selector -v\n```\n\n### Sample Output\n\n```\n================================================================================\n  STELLAR CANDIDATE SELECTOR — Ranking Report\n================================================================================\n\n  Candidates evaluated : 8\n  Passed filtering     : 4\n  Rejected             : 4\n  ML model R²          : 0.9987\n\n  Rank  Name                  Exp   Skills    ML Adj    Final\n  ──────────────────────────────────────────────────────────────\n  1     Senior Dev            7     2.35      94.00     33.59\n  2     Lisa Park             4     2.08      91.00     31.08\n  3     Mid Dev               4     1.70      85.00     28.92\n  4     Tom Brown             6     1.78      87.00     29.46\n\n  ★ Top Candidate: Senior Dev — Final Score 33.59\n================================================================================\n```\n\n## Running Tests\n\n```bash\npytest\n\n# With coverage\npytest --cov=stellar_selector --cov-report=term-missing\n```\n\nTests cover:\n- **Models** — Skill equality/hashing, candidate validation, proficiency lookup, criteria defaults\n- **Engine** — Experience filtering, skill filtering, score filtering, ranking order, ranks assignment, skill proficiency weighting, ML R² reporting\n- **Config** — Loading from dict, JSON string, file, invalid JSON handling\n- **Edge cases** — Empty candidates, single candidate, no required/preferred skills, all filtered out\n\n---\n\n## Configuration\n\nEdit `criteria.json` to tune the selection:\n\n```json\n{\n  \"min_experience\": 3,\n  \"required_skills\": [\"Python\", \"Java\"],\n  \"preferred_skills\": [\"AWS\", \"React\", \"Kubernetes\"],\n  \"experience_weight\": 0.3,\n  \"skills_weight\": 0.4,\n  \"score_weight\": 0.3,\n  \"min_base_score\": 0,\n  \"top_n\": 5\n}\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `min_experience` | int | Minimum years to pass filter |\n| `required_skills` | list | Must-have skills (all required) |\n| `preferred_skills` | list | Bonus skills (0.5× weight) |\n| `experience_weight` | float | Weight for experience component (0–1) |\n| `skills_weight` | float | Weight for skill match component (0–1) |\n| `score_weight` | float | Weight for ML-adjusted score component (0–1) |\n| `min_base_score` | float | Minimum assessment score to pass filter |\n| `top_n` | int | Number of top candidates to highlight |\n\n---\n\n## Technologies\n\n| Technology | Version | Purpose |\n|------------|---------|---------|\n| Python | 3.12+ | Language runtime — type hints, StrEnum, modern syntax |\n| Pydantic | 2.10+ | Data validation, serialisation, model_copy |\n| pandas | 2.2+ | Data manipulation (internal) |\n| NumPy | 2.1+ | Numerical arrays for ML features |\n| scikit-learn | 1.6+ | Ridge regression, Gradient Boosting, StandardScaler |\n| Matplotlib | 3.10+ | 4-panel dashboard visualisation |\n| pytest | 8.3+ | Test framework with fixtures \u0026 parametrisation |\n\n---\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuddha2021%2Fstellar-candidate-selector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshuddha2021%2Fstellar-candidate-selector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuddha2021%2Fstellar-candidate-selector/lists"}