JobScout-lite

Open your device, and your agent silently starts working in the background to find jobs where you are the best fit, auto-drafting a personalized cover letter/application pitch for each matched role. JobScout-Lite is a fully autonomous, GPU-accelerated AI recruiting agent that works for you. It scrapes major job portals, filters matches against your profile, scores compatibility using locally-run LLMs via Ollama, and delivers structured, prioritized reports straight to your Telegram. 100% Private. 100% Free. 100% Local.

---

In a crowded job market, finding the right role shouldn't mean spending hours manually parsing listing boards or sending your personal resume to third-party scrapers.

[!NOTE] Key Value Propositions:

• Zero API Cost: Powered entirely by state-of-the-art local SLMs/LLMs (like Qwen2.5 / Qwen3 / Llama3). No OpenAI API tokens or subscriptions required.
• Ultimate Privacy: Your resume, skills, target compensation, and locations never leave your machine.
• Smart Filtering: The two-stage pre-filtering engine ensures you don't waste precious GPU cycles or time scanning irrelevant matches.
• Double-Agent Utility: Includes both an automated Pipeline Orchestrator (to run on system boot) and an interactive Conversational Chatbot (with custom personality via SOUL.md).

---

Engine / Component	Capability	Tech Under the Hood
Aggregator Scraper	Parallel scraping across LinkedIn, Indeed, Glassdoor, Naukri, Internshala, Wellfound, and Foundit.	python-jobspy + BeautifulSoup + asyncio
Stage-1 Pre-Filter	Filters out obvious mismatch roles instantly based on profile keywords before invoking LLM logic.	Python RegEx (Instant, 0 GPU cost)
Stage-2 LLM Classifier	Classifies compatibility into STRONG_MATCH, GOOD_MATCH, or NO_MATCH with structured JSON reasons.	Ollama + SLM (qwen3:4b / llama3)
Telegram Delivery	Instantly dispatches ranked job detail cards, direct apply links, and AI matching explanations.	python-telegram-bot + Markdown formatting
Interactive Chatbot	A conversational companion bot with conversation memory and custom personality injection (SOUL.md).	python-telegram-bot + httpx stream
Smart Cache	Hash-based deduplication ensuring you never see the same job post twice across separate runs.	JSON local database store
Wake & Sleep Scheduler	Runs silently in the background on startup, processes new postings, and automatically unloads models.	Windows Task Scheduler / Startup batch scripts

---

          ┌─────────────────────────────┐
          │   OS Task Scheduler / Boot  │
          └─────────────┬───────────────┘
                        ▼
          ┌─────────────────────────────┐
          │   1. SCRAPE JOB PORTALS     │
          │   LinkedIn • Indeed • Naukri │
          │   Glassdoor • Internshala   │
          │   Wellfound • Foundit       │
          └─────────────┬───────────────┘
                        ▼
          ┌─────────────────────────────┐
          │   2. DEDUPLICATE            │
          │   Filter against local cache│
          └─────────────┬───────────────┘
                        ▼
          ┌─────────────────────────────┐
          │   3. KEYWORD PRE-FILTER     │
          │   Filters out non-matching  │
          │   roles without GPU cost    │
          └─────────────┬───────────────┘
                        ▼
          ┌─────────────────────────────┐
          │   4. AI MATCH CLASSIFIER    │
          │   Ollama classifies matches │
          │   as Strong, Good, or None  │
          └─────────────┬───────────────┘
                        ▼
          ┌─────────────────────────────┐
          │   5. TELEGRAM PUSH          │
          │   🟢 Strong Match           │
          │   🟡 Good Match             │
          └─────────────────────────────┘

---

Prerequisites

• Python 3.10+
• Ollama — Install Ollama (or run via Docker)
• Telegram Account — Create a bot via @BotFather and get your Chat ID from @userinfobot
• NVIDIA GPU (recommended, not required) — 6GB+ VRAM for fast inference. CPU-only mode also works.

Step 1: Clone & Install

git clone https://github.com/ArPaN-DS/JobScout-lite.git
cd JobScout-lite

# Create virtual environment
python -m venv assist_enve

# Activate (Windows)
.\assist_enve\Scripts\activate

# Activate (Linux/macOS)
# source assist_enve/bin/activate

# Install dependencies
pip install -r requirements.txt

Step 2: Configure Your Settings

# Copy all example templates
cp .env.example .env
cp profiles/my_profile.example.md profiles/my_profile.md
cp resumes/master_resume.example.md resumes/master_resume.md
cp SOUL.example.md SOUL.md

Windows users: Use copy instead of cp.

Now edit each file:

File	What to configure
.env	Your Telegram bot token, chat ID, Ollama URL, model names, your name
profiles/my_profile.md	Your target roles, skills, location preferences, things to avoid
resumes/master_resume.md	Your full resume/CV in markdown format
SOUL.md	(Optional) Customize the chatbot's personality and tone

Step 3: Setup Ollama

# Pull the models (choose based on your VRAM)
ollama pull qwen3:4b        # Recommended for job scoring (~3.5GB VRAM)
ollama pull qwen3:1.7b      # Recommended for fast chat (~2.4GB VRAM)

# (Optional) Create optimized chat model with reduced context
ollama create qwen3:fast -f - <<EOF
FROM qwen3:1.7b
PARAMETER num_ctx 8192
EOF

Step 4: Run

# Run the job scanner (scrapes → scores → sends to Telegram)
python job_finder.py

# OR run the conversational Telegram bot
python bot.py

# OR use the batch scripts (Windows)
# Double-click START_AI.bat to launch everything
# Double-click STOP_AI.bat to free GPU/RAM

Step 5: Agent Memory & Feedback Commands

JobScout-Lite features a persistent feedback memory database and job state CRM. Every matched job card is delivered with a unique 6-character short identifier (e.g. ID: abcd12). You can send the following commands to the Telegram bot to manage your pipeline:

• /yes <job_id> — Register positive feedback. Future LLM classification runs dynamically load these as positive few-shot exemplars, self-correcting and prioritizing similar roles.
• /no <job_id> — Register negative feedback. Future LLM classification runs dynamically load these to avoid showing similar irrelevant roles.
• /apply <job_id> — Log that you have applied to this job. This moves the job state in the persistent cache to applied.
• /status — View your current agent status, active model configurations, total cache size, feedback counts, and a summary of your applied job pipeline.

Additionally, conversation histories are persistently saved to jobs_cache/chat_history.json, preserving chatbot memory across system restarts.

Step 6: Running Tests

To run the unit and integration tests and verify that the system is fully functional:

# Activate virtual environment if not already active
# Windows:
.\assist_enve\Scripts\activate
# Linux/macOS:
# source assist_enve/bin/activate

# Run test suite
python -m pytest tests/ -v --tb=short

---

JobScout-Lite/
├── bot.py                           # Conversational Telegram bot (with memory/auth)
├── job_finder.py                    # Autonomous pipeline orchestrator wrapper
├── core/                            # Core functionality package
│   ├── __init__.py                  # Package initialization
│   ├── cache.py                     # Persistent deduplication cache
│   ├── config.py                    # Centralized settings & path configuration
│   ├── notifier.py                  # Telegram message formatting & delivery
│   ├── scrapers.py                  # Portal search scrapers (LinkedIn, Naukri, etc.)
│   └── scorer.py                    # Two-stage job match scoring pipeline
├── tests/                           # Pytest unit & integration test suite
│   ├── __init__.py                  # Test suite setup
│   ├── test_cache.py                # Cache deduplication tests
│   ├── test_config.py               # Config loading tests
│   ├── test_notifier.py             # Telegram notifier & auth tests
│   ├── test_scorer.py               # Matching classification & parsing tests
│   └── fixtures/                    # Mock responses and data fixtures
├── jobs_cache/                      # Persistent cache directory (gitignored)
├── logs/                            # Local application log files (gitignored)
├── requirements.txt                 # Python dependencies
├── .env.example                     # Environment settings template
├── .gitignore                       # Protects credentials & cache files
├── START_AI.bat                     # Runs job finder on startup (Windows)
├── STOP_AI.bat                      # Stops background AI services (Windows)
├── SOUL.example.md                  # Template for bot personality
├── profiles/
│   └── my_profile.example.md        # Template for your profile configuration
├── resumes/
│   └── master_resume.example.md     # Template for master resume
├── ARCHITECTURE.md                  # Technical architecture deep-dive
├── DATA_FLOW.md                     # Data flow diagrams
├── CONTRIBUTING.md                  # Contribution guidelines
└── LICENSE                          # MIT License

Note: Files marked with templates (.example) should be copied to their real names (without .example), which are gitignored to prevent pushing sensitive data.

---

Environment Variables (.env)

Variable	Required	Description
USER_NAME	Yes	Your name (used in bot system prompt)
TELEGRAM_BOT_TOKEN	Yes	Bot token from @BotFather
TELEGRAM_CHAT_ID	Yes	Your personal chat ID from @userinfobot
OLLAMA_URL	No	Ollama API endpoint (default: http://localhost:11434/api/chat)
OLLAMA_MODEL	No	Model for job classification (default: qwen3:4b)
OLLAMA_BOT_MODEL	No	Model for chatbot (default: qwen3:fast)
LOG_LEVEL	No	Logging level: DEBUG, INFO, WARNIN