🔍 SnapplAI — AI-Powered LinkedIn Job Alerts

Stop refreshing LinkedIn. This pipeline scrapes new job listings based on your settings, uses AI agents to summarize each one and score it against your CV, then delivers only the best matches straight to your inbox 📬 — so you're always first to apply 🚀

📑 Table of Contents

• The Problem
• How It Works
• Tech Stack
• Pipeline Architecture
• AI Output Fields
• Setup
• Project Structure
• Roadmap v2
• Contributing
• License

🎯 The Problem

Job hunting on LinkedIn is a full-time job in itself. New listings appear daily, most are irrelevant, and by the time you spot a good one, 200 people have already applied.

SnapplAI flips the game: it runs on a schedule, scrapes fresh listings, lets AI read and score every single one against your CV, and emails you only the top matches — before the crowd even sees them.

⚙️ How It Works

The pipeline runs in 4 sequential steps, fully automated:

1. Scrape → job_scraper() pulls fresh listings from LinkedIn based on your search settings (role, location, filters) using python-jobspy.

2. Summarize → agentic_summarize() sends each job description to Gemini, which extracts structured fields (title, seniority, skills, salary, etc.) as clean JSON.

3. Analyze → agentic_analyze() reads your CV and scores each listing on how well it matches your profile. Chain-of-thought enforced: the model writes analysis before score in the JSON schema, so reasoning comes before judgment.

4. Deliver → send_email() builds an email with the top-scored jobs and sends it to your inbox via SMTP.

Key principle: AI reads and evaluates. Python orchestrates and delivers. No frameworks, no agents-calling-agents — just a clean data pipeline with LLM calls where they matter.

🔧 Tech Stack

🏗️ Pipeline Architecture

The entire pipeline operates on a single pandas DataFrame that gets enriched at each step. No intermediate files, no database — everything flows through memory.

📊 AI Output Fields

Each job in the email is ranked by match score and includes company, role, work mode, a one-line AI summary explaining why it matched (or didn't), and a direct apply link to the LinkedIn listing.

🚀 Setup

1. Get a free API key from Google AI Studio
2. Generate a Gmail App Password
3. Place your CV (PDF) in your_cv_config/
4. Configure search settings: use file_config.txt to create your file_config.env (filter docs)
5. Create your .env from the template: cp example_env.txt .env

Deploy

Local

git clone https://github.com/TDK-99/SnapplAI.git && cd SnapplAI
pip install -r requirements.txt
# complete setup steps above
python main.py

Docker

git clone https://github.com/TDK-99/SnapplAI.git && cd SnapplAI
# complete setup steps above
docker build -t snapplai .
docker run --env-file .env snapplai

GitHub Actions

1. Fork this repo (or create a private copy)
2. Complete setup steps 1-4 above in your fork
3. Edit your settings in .github/workflows/snapplai.yml under the env: block
4. Add credentials as repository secrets (Settings → Secrets → Actions): GOOGLE_API_KEY, GMAIL_USER, GMAIL_APP_PASSWORD
5. Actions tab → enable workflows → Run workflow

📁 Project Structure

SnapplAI/
├── main.py                 # Entry point — runs the 4-step pipeline
├── src/
│   ├── daily_scraper.py    # LinkedIn scraping with python-jobspy
│   ├── ai_agents.py        # Gemini calls: summarize + analyze
│   └── smtp.py             # Email builder and SMTP sender
├── your_cv_config/
│   ├── .gitkeep            # Keeps folder tracked in git
│   ├── file_config.env     # Your settings (role, location, filters)
│   ├── file_config.txt     # Additional config parameters
│   └── Your_CV.pdf         # Your CV goes here (PDF)
├── .github/
│   └── workflows/
│       └── snapplai.yml    # GitHub Actions workflow (scheduled + manual)
├── Dockerfile              # Run anywhere with Docker
├── .env                    # API keys and SMTP credentials (git-ignored)
├── example_env.txt         # Template for .env variables
├── requirements.txt        # Dependencies
├── LICENSE                 # MIT
└── README.md

🛣️ Roadmap v2

• Multi-country scraping — search across 2+ countries in a single run (custom feature, not supported by python-jobspy out of the box)
• Excel/DB deduplication — persistent storage to compare runs and filter out already-seen listings, so you never score the same job twice
• Scoring calibration — benchmark AI scores against known good/bad matches to improve match quality
• Output redesign — better visual formatting for the email report (job cards, readability, direct links)

🤝 Contributing

Contributions are welcome — bug fixes, new features, or docs improvements.

• Issues — Report bugs or suggest features
• Pull Requests — Fork, build, submit

📄 License

MIT — see LICENSE