Spaces:
Sleeping
Sleeping
| # JD2GH - Mini ATS (Applicant Tracking System) | |
| An AI-powered mini ATS that finds GitHub developers matching your job descriptions and manages the entire candidate lifecycle from discovery to assessment. | |
| ## Features | |
| ### 🎯 Complete ATS Workflow | |
| 1. **Dashboard** - Overview metrics and job listings | |
| 2. **Job Postings** - Create and manage job postings with AI-powered JD analysis | |
| 3. **Candidates** - Discover GitHub developers, score them, and invite top candidates | |
| 4. **Tests (HR)** - View assessment results and anti-cheat metrics | |
| 5. **Candidate Portal** - Token-based candidate application portal with assessments | |
| ### 🤖 AI-Powered Features | |
| - **Gemini AI** extracts structured requirements from job descriptions | |
| - Automatically identifies programming languages, frameworks, and skills | |
| - Generates must-have and nice-to-have requirements | |
| ### 🔍 GitHub Discovery | |
| - Searches GitHub users by location and programming languages | |
| - Analyzes repositories, topics, contributions, and activity | |
| - Intelligent scoring algorithm (skills 60%, activity 25%, quality 10%, completeness 5%) | |
| ### 📊 Candidate Management | |
| - Automated candidate discovery and scoring | |
| - Customizable filters (must-haves, activity recency) | |
| - Top-N candidate selection | |
| - Invitation system with tokenized links | |
| ### �� Assessment System | |
| - **Soft Skills Test** (7 minutes, 5 questions) | |
| - **Technical Test** (20 minutes, 8 questions) | |
| - Anti-cheat features: | |
| - Tab switch detection | |
| - Copy/paste prevention | |
| - Automatic scoring penalties | |
| - Timer with auto-submit | |
| ### 💾 Data Persistence | |
| - SQLite database with SQLModel ORM | |
| - Job postings, candidates, matches, invitations, assessments | |
| - Automatic job statistics tracking | |
| ### 📥 Export Options | |
| - CSV and JSON export per job | |
| - Full candidate dataset with scores and evidence | |
| ## Installation | |
| 1. Clone the repository: | |
| ```bash | |
| cd /path/to/your/workspace | |
| ``` | |
| 2. Create and activate virtual environment: | |
| ```bash | |
| python -m venv venv | |
| source venv/bin/activate # On Windows: venv\Scripts\activate | |
| ``` | |
| 3. Install dependencies: | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| 4. Set up environment variables: | |
| ```bash | |
| cp .env.example .env | |
| # Edit .env and add your API keys: | |
| # - GEMINI_API_KEY (from Google AI Studio) | |
| # - GITHUB_TOKEN (Personal Access Token from GitHub) | |
| ``` | |
| ## Usage | |
| ### Start the Application | |
| ```bash | |
| ./run_streamlit.sh | |
| # Or manually: | |
| source venv/bin/activate && streamlit run streamlit_app.py | |
| ``` | |
| The app will open in your browser at `http://localhost:8501` | |
| ### Complete Workflow | |
| #### 1. Create a Job Posting | |
| - Go to **Job Postings** → **New Job** | |
| - Enter job title, city, and minimum repositories | |
| - Paste job description or upload a file (.pdf, .docx, .md, .txt) | |
| - Click "Extract & Preview" | |
| - Edit extracted languages, topics, and requirements using multiselect chips | |
| - Adjust scoring weights (Skills, Activity, Quality, Completeness) | |
| - Click "Save Job Posting" | |
| #### 2. Discover Candidates | |
| - Go to **Candidates** | |
| - Select your job from the dropdown | |
| - Click "Run / Refresh Discovery Now" | |
| - Wait for GitHub search and scoring to complete | |
| - Apply filters: | |
| - "Has all must-haves" - Only show candidates matching all required skills | |
| - "Active in last 90 days" - Only show recently active developers | |
| #### 3. Invite Top Candidates | |
| - Use the "Top N" slider to select your preferred number | |
| - Review candidate profiles, scores, and evidence | |
| - Click "Invite" button for selected candidates | |
| - Copy the generated invitation link | |
| - Send the link to candidates (via email, LinkedIn, etc.) | |
| #### 4. Candidate Applies | |
| - Candidate clicks the invitation link | |
| - Fills out profile (name, email, LinkedIn, years of experience) | |
| - Takes Soft Skills assessment (7 minutes) | |
| - Takes Technical assessment (20 minutes) | |
| - System tracks anti-cheat metrics (tab switches, copy/paste attempts) | |
| #### 5. Review Results | |
| - Go to **Tests (HR)** | |
| - Select the job | |
| - View all assessment attempts with: | |
| - Scores (Soft and Tech) | |
| - Duration | |
| - Anti-cheat flags | |
| - Completion status | |
| #### 6. Track Progress | |
| - **Dashboard** shows real-time metrics: | |
| - Total job posts | |
| - Candidates discovered | |
| - Applications received | |
| - Tests completed | |
| ### Advanced Features | |
| #### Custom Scoring Weights | |
| When creating a job, adjust the weight sliders: | |
| - **Skills** (default 60%): Match on languages and topics | |
| - **Activity** (default 25%): Contributions and recency | |
| - **Quality** (default 10%): Stars and followers | |
| - **Completeness** (default 5%): Profile completeness | |
| #### File Upload Support | |
| Upload job descriptions in multiple formats: | |
| - PDF (`.pdf`) | |
| - Word (`.docx`) | |
| - Markdown (`.md`) | |
| - Plain text (`.txt`) | |
| #### Export Data | |
| From the Candidates page: | |
| - **CSV Export**: Spreadsheet-compatible format | |
| - **JSON Export**: Structured data for integrations | |
| ## Architecture | |
| ### Single-File Design | |
| The entire application is contained in `streamlit_app.py` (~1800 lines): | |
| - Database models (SQLModel) | |
| - Utility functions | |
| - Gemini AI integration | |
| - GitHub GraphQL queries | |
| - Scoring algorithm | |
| - All 5 pages | |
| - Assessment system | |
| ### Database Schema | |
| - **JobPosting**: Job details, parsed requirements, weights | |
| - **Candidate**: GitHub user profile, portfolio | |
| - **JobCandidateMatch**: Per-job scoring and evidence | |
| - **Invitation**: Tokenized invite links | |
| - **AssessmentTemplate**: Test questions (Soft/Tech) | |
| - **AssessmentAttempt**: Test results and anti-cheat data | |
| ### Technology Stack | |
| - **Streamlit**: Web framework | |
| - **SQLModel**: Database ORM | |
| - **Google Gemini**: AI text extraction | |
| - **GitHub GraphQL API**: Developer search | |
| - **pypdf**: PDF parsing | |
| - **python-docx**: DOCX parsing | |
| ## API Keys | |
| ### Google Gemini API | |
| 1. Go to [Google AI Studio](https://makersuite.google.com/app/apikey) | |
| 2. Create an API key | |
| 3. Add to `.env` as `GEMINI_API_KEY` | |
| ### GitHub Personal Access Token | |
| 1. Go to [GitHub Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens) | |
| 2. Generate new token (classic) | |
| 3. Select scopes: `read:user`, `user:email`, `read:org` | |
| 4. Add to `.env` as `GITHUB_TOKEN` | |
| ## Limitations | |
| - GitHub rate limits: ~10-30 candidates per discovery run | |
| - No email sending (invitations are copyable links) | |
| - Lightweight anti-cheat (not enterprise-grade proctoring) | |
| - Local SQLite database (single user) | |
| ## Troubleshooting | |
| ### GitHub Rate Limits | |
| If you see "RESOURCE_LIMITS_EXCEEDED": | |
| - The app already uses minimal queries (10 users/page, 3 pages max) | |
| - Wait a few minutes and try again | |
| - Consider using a GitHub personal access token with higher limits | |
| ### File Upload Errors | |
| If PDF or DOCX uploads fail: | |
| ```bash | |
| pip install pypdf python-docx | |
| ``` | |
| ### Database Issues | |
| To reset the database: | |
| ```bash | |
| rm ats.db | |
| # Restart the app - database will be recreated | |
| ``` | |
| ## License | |
| MIT | |
| ## Contributing | |
| This is a minimal ATS demo. For production use, consider: | |
| - PostgreSQL instead of SQLite | |
| - Email integration (SendGrid, AWS SES) | |
| - Enterprise proctoring (e.g., Proctorio API) | |
| - Multi-tenancy support | |
| - Advanced analytics dashboard | |