The ultimate open-source AI agent for job hunters—find, score, tailor, and track your next career move.
| Feature | How It Works | Tech Metric |
|---|---|---|
| QualityCritic Self-Correction | Multi-agent auditing loop between TailoringExpert and QualityCritic to prevent resume hallucinations. |
 |
| Local-First Privacy | Symmetric Fernet encryption for API keys and database records stored entirely at rest on your disk. |  |
| Recruiter Q&A Memory | Searches past recruiter answers using Jaccard word similarity to auto-draft custom portal answers. |  |
| Resilience & Failovers | 10+ provider chain supporting auto-cooldowns (1hr rate-limit blocks) and fallback routes. |  |
| Visual Career Funnel | Track conversion from initial discovery to match score, kit preparation, and interviews. |  |
| Dynamic Customizer | Personalize document margins, typography themes, and line heights directly from the web panel. |  |
JobScout-AI uses a decoupled, local-first engine. The flowchart below maps the entire ingestion, scoring, and multi-agent tailoring pipeline:
graph TD
A[Job Boards / Pasted URLs] -->|Ingestion| B[JobSourceRun Ingestor]
B -->|Deduplication| C[Job Fingerprint Check]
C -->|New Leads| D[JobLead Queue]
D -->|Match Request| E[Resilient LLM Router]
E -->|Scoring Engine| F[MatchResult Scorer]
F -->|High Match| G[Auto-Queue Dashboard]
H[Candidate Resume/DOCX] -->|Parser| I[MasterProfile Parser]
I -->|Store| J[Local SQLite Database]
G -->|Generation Trigger| K[TailoringExpert Agent]
J -->|Skills Grounding| K
K -->|Draft Materials| L[QualityCritic Agent]
L -->|Audit & Verify| M{Approved?}
M -->|No: Re-tailor| K
M -->|Yes: Save| N[ApplicationKit Saved]
N -->|User Dashboard| O[Review, Edit & Export]
style A fill:#ffe8cc,stroke:#ff922b,stroke-width:2px,color:#000
style B fill:#ffe8cc,stroke:#ff922b,stroke-width:2px,color:#000
style C fill:#ffe8cc,stroke:#ff922b,stroke-width:2px,color:#000
style D fill:#ffe8cc,stroke:#ff922b,stroke-width:2px,color:#000
style E fill:#f3d9fa,stroke:#cc5de8,stroke-width:2px,color:#000
style F fill:#f3d9fa,stroke:#cc5de8,stroke-width:2px,color:#000
style G fill:#f3d9fa,stroke:#cc5de8,stroke-width:2px,color:#000
style H fill:#e7f5ff,stroke:#228be6,stroke-width:2px,color:#000
style I fill:#e7f5ff,stroke:#228be6,stroke-width:2px,color:#000
style J fill:#e7f5ff,stroke:#228be6,stroke-width:2px,color:#000
style K fill:#e6fcf5,stroke:#20c997,stroke-width:2px,color:#000
style L fill:#e6fcf5,stroke:#20c997,stroke-width:2px,color:#000
style M fill:#e6fcf5,stroke:#20c997,stroke-width:2px,color:#000
style N fill:#e6fcf5,stroke:#20c997,stroke-width:2px,color:#000
style O fill:#fff0f6,stroke:#f783ac,stroke-width:2px,color:#000
To guarantee that AI-tailored resumes and cover letters match your actual skills (and don't invent false credentials), JobScout-AI runs a strict, multi-agent self-correction cycle.
Here is the exact runtime architecture mapping this verification process:
sequenceDiagram
autonumber
actor User
participant App as Django View
participant Agent as CareerAgentAI
participant Tailor as TailoringExpert (LLM)
participant Critic as QualityCritic (LLM)
User->>App: Request Application Kit Generation
App->>Agent: Instantiate generate_application_kit()
Agent->>Agent: Load Candidate Master Profile
Note over Agent, Tailor: Turn 1: Initial Generation
Agent->>Tailor: Request Tailored Resume & Cover Letter
Tailor-->>Agent: Return Initial Application Kit JSON
Note over Agent, Critic: Turn 1 Audit & Verification
Agent->>Agent: Run Deterministic Grounding Checks
Agent->>Critic: Audit Materials (Profile vs. Job Description vs. Kit)
rect rgb(240, 200, 200)
Note over Critic: CRITIC DETECTS HALLUCINATION<br/>"Candidate has no AWS cloud experience in profile!"
Critic-->>Agent: Approved: False (Inject fix instructions)
Agent->>Agent: Log Warning to AgentRunLog Dashboard
end
Note over Agent, Tailor: Turn 2: Self-Correction Loop
Agent->>Tailor: Request Revision + Critic Rejection Instructions
Tailor-->>Agent: Return Corrected Application Kit JSON
Note over Agent, Critic: Turn 2 Audit & Verification
Agent->>Critic: Audit Materials (Profile vs. Job Description vs. Updated Kit)
rect rgb(200, 240, 200)
Note over Critic: CRITIC APPROVES MATERIAL<br/>"All claims grounded in candidate profile."
Critic-->>Agent: Approved: True (No issues)
Agent->>Agent: Log Success to AgentRunLog Dashboard
end
Agent->>App: Return Fully Grounded ApplicationKit
App->>User: Render Verified Kit (Resume, Cover Letter, Outreach)
JobScout-AI uses a custom fallback chain with automated rate-limit detection and cool-downs to prevent execution blocks:
graph LR
A[Generate Request] --> B[LLM Router]
B -->|Check Active| C{Gemini Active?}
C -->|Yes| D[Call Gemini API]
C -->|No: On Cooldown| E{Groq/OpenAI Active?}
D -->|Success| F[Return JSON]
D -->|Quota/Rate Limit Error| G[Trigger Circuit Breaker]
G -->|Put on Cooldown 1 Hr| H[Gemini Suspended]
H -->|Failover Route| E
E -->|Yes| I[Call Fallback Provider]
E -->|No| J[Local Ollama Offline Mode]
I -->|Success| F
J -->|Success| F
style A fill:#f1f3f5,stroke:#868e96,stroke-width:2px,color:#000
style B fill:#f1f3f5,stroke:#868e96,stroke-width:2px,color:#000
style C fill:#e7f5ff,stroke:#228be6,stroke-width:2px,color:#000
style D fill:#e7f5ff,stroke:#228be6,stroke-width:2px,color:#000
style E fill:#e7f5ff,stroke:#228be6,stroke-width:2px,color:#000
style F fill:#ebfbee,stroke:#40c057,stroke-width:2px,color:#000
style G fill:#fff5f5,stroke:#fa5252,stroke-width:2px,color:#000
style H fill:#fff5f5,stroke:#fa5252,stroke-width:2px,color:#000
style I fill:#ebfbee,stroke:#40c057,stroke-width:2px,color:#000
style J fill:#ebfbee,stroke:#40c057,stroke-width:2px,color:#000
Placeholders for application interfaces:
▪ Dashboard Overview: Track your application pipeline and active search runs.
▪ Agent Logs Panel: Real-time visibility into the thought process of TailoringExpert and QualityCritic.
▪ Browser Session Console: Watch the Playwright automated agent handle forms in real-time.
JobScout-AI is designed to run locally on your machine. We provide one-command onboarding scripts to automate the setup.
Click here to expand Step-by-Step Local Setup Instructions
- Python 3.11 or newer installed.
- Git configured.
git clone https://github.com/ArPaN-DS/JobScout-AI.git
cd JobScout-AIOur setup scripts automatically build the virtual environment, install dependencies, generate secure encryption keys, run migrations, and bootstrap a default admin superuser.
- On Windows (PowerShell / CMD):
.\setup.bat - On macOS / Linux:
chmod +x setup.sh ./setup.sh
Because JobScout-AI processes matches and background tasks asynchronously, run two terminal windows side-by-side:
- Terminal 1: Web Interface Server
# Windows: .\job_finder_env\Scripts\activate python manage.py runserver # macOS/Linux: source job_finder_env/bin/activate python manage.py runserver
- Terminal 2: Background Task Worker
# Windows: .\job_finder_env\Scripts\activate python manage.py qcluster # macOS/Linux: source job_finder_env/bin/activate python manage.py qcluster
Open your browser and navigate to http://127.0.0.1:8000/.
Log in using the default developer credentials:
- Username:
admin - Password:
admin123
[!WARNING] Please update your password in the Django Admin panel under
/adminif hosting on a local network.
Click here to expand Repository File Map
career_agent/: Django project settings, deployment rules, and root URL routing.core/: Main career engine application directory.core/models.py: Defines schemas (Job leads, Candidates, LLM audits).core/llm.py: Resilient LLM router with fallbacks and cooldown trackers.core/ai_service.py: Orchestrates the multi-agentQualityCriticcorrection loop.core/sources/: Extensible scraping adapters (LinkedIn, Indeed, etc.).
templates/: Responsive HTML5 dashboard templates.static/: Client-side styles, charts, and interactive scripts.
We welcome open-source contributions! Here is our current roadmap. Feel free to pick up any issues marked as [Help Wanted] or [Good First Issue]:
- Fernet Secret Encryption: Encrypt API keys and credentials at rest in SQLite.
- One-Click Setup: Automate virtual environments, key creation, and migrations.
- Chrome Extension Integration [Help Wanted]: A simple extension to clip job descriptions directly from your browser to your local queue.
- Vision-based LLM Form Filler [Good First Issue]: Feed screenshot captures of complex recruiter questions to the LLM to draft answers.
- Unified Multi-Profile [Help Wanted]: Track job applications for multiple candidate profiles (e.g., Data Scientist vs. Backend Engineer) under the same dashboard.
- Latency & Cost Profiler: Beautiful charts showing which LLM models are costing you the most and causing bottlenecks.
- ATS Gap Matcher: Highlight missing keywords between your resume and a job description before tailoring.
Ready to contribute? Please review our Contributing Guide for branch formatting, testing thresholds, and styling rules.
For details on private vulnerability reporting, please see SECURITY.md.
JobScout-AI is completely local. Your SQLite database and uploaded resume files are stored on your local drive and are excluded from git index via .gitignore. The system only makes requests to LLM APIs that you configure, sending only the prompt context required.
Yes! JobScout-AI supports Ollama. Set OLLAMA_ENABLED=true in your .env and specify a local model like llama3.1 or mistral to run matches and tailoring without internet access.
MIT License. Copyright (c) 2026 Arpan.