---

📖 Overview

Job Hunter Agent is an autonomous, multi-portal AI job search agent. It sweeps Google Jobs, LinkedIn, Indeed, Naukri, and executive portals worldwide, enforces your chosen posting window (24h → 30d), extracts the full job description, calculates an ATS match score (0–100), optionally aligns your CV, and hands you a 1-click Direct Apply link — with instant Telegram alerts for the best matches.

💡 Zero setup required. The agent runs out of the box with its built-in heuristic scoring engine. Add API keys only if you want AI deep-scoring and mobile alerts.

---

🌟 Key Capabilities

---

🏗️ Architecture

flowchart TD
    A["🌐 Global Job Sources<br/>Google Jobs • LinkedIn • Indeed • Naukri • iimjobs<br/><i>scraped concurrently</i>"]
    B["⏱️ Posting Age Verification<br/>1–6h • 6–12h • 12–24h • 2d • 7d • 15d"]
    C["🗄️ Deduplication & Persistence<br/>SQLite / Temp — across portals & previous runs"]
    D["🧠 Hybrid Profile & CV Match Engine (0–100)<br/>Gemini 2.5 Flash + Deterministic Keyword Heuristics"]
    E["🖥️ Streamlit Web UI<br/>Live search & filters"]
    F["📱 Automated Notifications<br/>Telegram alerts + Cron"]

    A --> B --> C --> D
    D --> E
    D --> F

    style A fill:#1e293b,stroke:#38bdf8,color:#fff
    style B fill:#1e293b,stroke:#a78bfa,color:#fff
    style C fill:#1e293b,stroke:#fbbf24,color:#fff
    style D fill:#1e293b,stroke:#34d399,color:#fff
    style E fill:#1e293b,stroke:#f87171,color:#fff
    style F fill:#1e293b,stroke:#26A5E4,color:#fff

---

📂 Repository Structure

job-hunter-agent/
├── .github/
│   └── workflows/
│       └── daily_job_hunter.yml   # Twice-daily automated GitHub Actions sweep
├── .gitignore                     # Protects API keys, database, and local cache
├── job_hunter_agent.py            # Main app (Streamlit UI + CLI scraper)
├── requirements.txt               # Lightweight Python dependencies
├── LICENSE                        # MIT Open Source License
└── README.md                      # You are here 👋

---

🚀 Quick Start

1️⃣ Clone the repository

git clone https://github.com/your-username/job-hunter-agent.git
cd job-hunter-agent

2️⃣ Create a virtual environment & install dependencies

python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

3️⃣ Launch the interactive dashboard

streamlit run job_hunter_agent.py

Open http://localhost:8501, pick your region or career domain, and click ▶️ Run Agent!

4️⃣ Or run headless via CLI (cron mode)

python job_hunter_agent.py --cli --hours 24 --country "India"

This generates:

---

☁️ Free Cloud Deployment

Option A — Streamlit Community Cloud (free interactive web app)

1. Fork or push this repository to your GitHub account.
2. Sign in to Streamlit Community Cloud.
3. Click Create app → select your repository → set Main file path to job_hunter_agent.py.
4. Under Advanced settings, optionally paste your secrets (GEMINI_API_KEY, TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID).
5. Click Deploy! — your dashboard is live with a public URL. 🎉

Option B — GitHub Actions (twice-daily automated sweeps)

This repo ships with a scheduled workflow at .github/workflows/daily_job_hunter.yml that:

• ⏰ Runs automatically every day at 9:00 AM IST and 6:00 PM IST
• 🌐 Sweeps all platforms and generates fresh CSV / Markdown reports
• 💾 Commits the reports back to the repository
• 📱 Dispatches top matches to Telegram (if bot secrets are configured)

Manual trigger: open your repo on GitHub → Actions → Daily Autonomous Job Hunter Sweep → Run workflow.

---

⚙️ Configuration & Secrets

The agent works with zero configuration. To unlock AI deep-scoring and instant mobile alerts, set these environment variables — or add them to GitHub Secrets (Settings → Secrets and variables → Actions).

🔒 Never commit your keys. The included .gitignore already protects API keys, the local database, and cache files.

---

💼 Pre-Tuned Industry Presets

---

👤 Author

Rinku Lodhi · @Insideofcub

Built and maintained by Rinku Lodhi. Feedback, ideas, and collaborations are always welcome!

---

🤝 Contributing

Contributions, bug reports, and ideas are always welcome!

1. 🍴 Fork the project
2. 🌿 Create your feature branch — git checkout -b feature/AmazingFeature
3. 💾 Commit your changes — git commit -m 'Add AmazingFeature'
4. 📤 Push to the branch — git push origin feature/AmazingFeature
5. 🔃 Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---