Day 3 / 30 — HireFlow AI

Autonomous Resume Evaluator & Interview Automation Agent

🚀 Overview

HireFlow AI is an intelligent HR automation agent that streamlines the hiring workflow — from bulk resume uploads to personalized interview scheduling and email communication. It uses AI + LLM-based scoring to evaluate candidates on technical, ATS, and reasoning metrics, giving HR a single dashboard for decisions.

🧩 Features

Bulk Resume Uploads
- Drag-and-drop multiple resumes (PDF, DOCX, TXT — big files welcome).
AI Job Understanding
- Paste the Job Description (JD). The agent extracts key skills & responsibilities automatically.
ATS Score Calculation
- Weighted keyword map like { "python": 3, "pytorch": 2 } → normalized to 0–100.
LLM Analysis & Score
- Interprets resume quality, relevance, clarity → “LLM Score (0–100)”.
GitHub / Portfolio Evaluation
- Optionally fetches live repo stars/forks. Scores projects (0–100).
Smart Reasoning Engine
- Explains selection or rejection, e.g., “Strong ML match and project relevance”.
Overall Scoring & Cutoff
- Combines ATS + LLM + Project → Overall.
- You set a cutoff → auto-split Selected vs Deselected.
Automated Interview Email System (Brevo)
- Fill Company, Role, Date, Time, Round, Mode, Location/Link.
- Generates warm emails for selected and polite notes for others.
- Sends via Brevo and shows a delivery log.
CSV Download & Record Keeping
- Export the entire evaluation summary to CSV.

🖥️ UI Glimpse

Dark, modern Streamlit interface
Overall Candidates → Selection split → Email previews as beautiful cards
Success toasts + send log after mailing

Tip: Replace docs/screenshot.png with your own to show off!

🧒 Setup (Super Easy)

Think of this like building blocks. Follow the pictures and you’re done! 🤗

Install Python (if you don’t have it)
- Windows/Mac: get it from https://www.python.org/downloads/
- When installing on Windows, tick “Add Python to PATH”.
Get the code
- Click the green Code button (or download ZIP) and open the folder in your computer.
Open a terminal in this folder
- Windows: open PowerShell → Right click the folder → “Open in Terminal”.

Create a virtual environment (optional but nice)

bashpython -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # macOS/Linux

Install requirements

bashpip install -r requirements.txt

Add your keys (safe place)

Create file .streamlit/secrets.toml and put:

tomlOPENAI_API_KEY = "sk-..."
BREVO_API_KEY = "xkeysib-..."
SENDER_NAME = "Your Name"
SENDER_EMAIL = "you@example.com"

You can also fill these in the app sidebar.

Run the app

bashstreamlit run app.py

Use it!
- Paste the JD
- Upload resumes
- Set company, role, interview details in sidebar
- Click Process → Generate Emails → Send

🎉 You did it!

▶️ One-Click Run

bashstreamlit run app.py

Works on Windows, macOS, and Linux.

✨ Usage

Paste Job Description (JD) in the big text box.
Optionally set ATS weight map (e.g., { "python": 3, "pytorch": 2 }).
Toggle OpenAI scoring for ATS/Project.
Upload multiple resumes (PDF/DOCX/TXT).
Click Process — you’ll get:
- ATS Score
- LLM Score
- Project Score
- Overall Score
- Why selected or not
Enter a cutoff and see Selected vs Deselected.
Fill Company, Role, Date, Time, Round, Mode, Link.
Generate beautiful email cards → Send via Brevo.
Download CSV of all results.

⚙️ Tech Stack

Category	Tools / APIs
Frontend	Streamlit (Dark UI)
AI/LLM	OpenAI GPT-4o / GPT-4o-mini
ATS Parsing	Regex + tokenization + custom weights
Automation	Python + Brevo API
Integrations	GitHub API (optional)
Storage	CSV export
Deploy	Streamlit Cloud / Render / Docker

🧠 Why HireFlow AI Stands Out

Autonomous end-to-end flow (resume → interview mail)
Transparent reasoning (see why someone was selected)
Validates skills via project evidence, not only resume text
Integrated communication via Brevo
Plug-and-play: export, reuse, extend

Taglines:

“HireFlow AI — Where Hiring Meets Automation.”

“From Resume to Interview in One Flow.”

“Upload. Analyze. Shortlist. Notify.”

📦 Project Structure

.
├─ app.py                          # Entry point (streamlit run app.py)
├─ hireflow/                       # Core package — explain this in interviews
│  ├─ config.py                    # API keys & OpenAI client
│  ├─ models.py                    # ScoreBreakdown, ProcessingOptions dataclasses
│  ├─ resume_parser.py             # PDF / DOCX / TXT ingestion
│  ├─ email_extractor.py           # Regex email recovery from PDF artifacts
│  ├─ pipeline.py                  # Orchestrates the full scoring flow
│  ├─ scoring/
│  │  ├─ ats.py                    # Rule-based ATS (keyword + bigram overlap)
│  │  └─ project.py                # Portfolio scoring (GitHub, frameworks, demos)
│  ├─ llm/
│  │  ├─ prompts.py                # All LLM prompts in one place
│  │  └─ client.py                 # OpenAI calls (score + email generation)
│  ├─ integrations/
│  │  ├─ github.py                 # Live repo stars/forks
│  │  └─ brevo.py                  # Transactional email API
│  └─ ui/
│     ├─ app.py                    # Streamlit layout
│     ├─ sidebar.py                # Settings & HR forms
│     └─ results.py                # Results table, cutoff, email send
├─ requirements.txt
├─ .env.example
└─ README.md

Architecture (for interviews)

Upload → resume_parser → pipeline
                              ├─ email_extractor (deterministic contact info)
                              ├─ scoring/ats (fast, explainable)
                              ├─ scoring/project (evidence-based)
                              ├─ llm/client (semantic fit + optional LLM scores)
                              └─ ScoreBreakdown → UI → Brevo emails

Hybrid scoring rationale: rule-based ATS is fast and auditable; LLM adds semantic understanding; project score validates claims with GitHub/demo evidence. Final score = average of all three.

🔒 Environment & Keys

OPENAI_API_KEY — for LLM scoring and email drafting
BREVO_API_KEY, SENDER_NAME, SENDER_EMAIL — for sending emails
Optional: GITHUB_TOKEN — for live repo stats

Never commit real secrets to Git!

🛠️ Troubleshooting

“No module named …” → run pip install -r requirements.txt again
Emails not sending → check Brevo key + sender email validity
Low scores → adjust ATS weight JSON and/or enable LLM scoring
UI re-runs after clicks → that’s Streamlit; state is preserved

🤝 Contribute

Pull requests welcome! Ideas:

Add Google Meet/Zoom automatic link generation
Add LinkedIn profile parsing
Add company logo branding to email cards

💙 Open Source

This is Day 3 of the “30 Days, 30 Agents” journey. Star the repo ⭐ and share ideas!

                ┌─────────────────────────────────────────┐
                │              ui/app.py                   │
                │  Inputs: JD, files, checkboxes, weights  │
                └──────────────────┬──────────────────────┘
                                   │
                     ProcessingOptions + UploadedFile
                                   │
                                   ▼
                ┌─────────────────────────────────────────┐
                │           resume_parser.py               │
                │  UploadedFile → str (resume_text)        │
                └──────────────────┬──────────────────────┘
                                   │ resume_text: str
                                   ▼
                ┌─────────────────────────────────────────┐
                │              pipeline.py                 │
                │                                          │
                │  resume_text ──→ email_extractor.py      │
                │              ──→ llm/client.py           │
                │              ──→ scoring/ats.py          │
                │              ──→ scoring/project.py      │
                │              ──→ integrations/github.py  │
                │                                          │
                │  Output: ScoreBreakdown                  │
                └──────────────────┬──────────────────────┘
                                   │
                     .to_display_row() → dict
                                   │
                                   ▼
                ┌─────────────────────────────────────────┐
                │         pandas DataFrame                 │
                │  st.session_state["results_df"]          │
                └──────────────────┬──────────────────────┘
                                   │
                                   ▼
                ┌─────────────────────────────────────────┐
                │            ui/results.py                 │
                │  Table → Cutoff → Emails → Brevo send   │
                └─────────────────────────────────────────┘

HireFlow AI Pipeline — AI Agent for automated candidate screening