🧭 Job-Pilot

Your personal, AI-powered job hunter & application co-pilot.

Search remote jobs across multiple boards, get instant AI salary & company intel, and auto-draft a tailored email, cover letter, and CV-tailoring prompt — from one clean dashboard.

---

👀 Preview

📸 Drop your own screenshots into docs/ (see docs/README.md). Until then, the layout mock and diagrams below render instantly on GitHub.

┌──────────────────────────────── 🧭 Job-Pilot ─────────────────────────────────┐
│  [ python developer …………… ]   ( Remote | Any )   [ location ]     🔍 Search    │
├───────────────────────────────┬───────────────────────────────────────────────┤
│  40 jobs · sorted by match     │  Go Software Engineer                          │
│ ┌───────────────────────────┐ │  🏢 Canonical · Remote                         │
│ │ Go Software Engineer      │ │  [ 📄 Overview ][ 🏢 Company & Salary ][ ✉️ Apply ]│
│ │ 🏢 Canonical              │ │                                                │
│ │ Jobicy  💰 $120k  ★ 82%   │ │   Fit score  ██████████░░  82%                 │
│ │        [  ✓ Selected  ]   │ │   💰 Recommended salary   $110k–$140k          │
│ ├───────────────────────────┤ │   🏢 Company brief …                           │
│ │ Software Engineer –Python │ │   ⭐ Reputation …                              │
│ │ 🏢 Canonical              │ │   🚀 Best way to apply …                        │
│ │ Jobicy   ★ 74%            │ │   ── Apply ──────────────────────────────────  │
│ │        [   Select →   ]   │ │   ( Email · Cover Letter · CV Prompt )         │
│ ├───────────────────────────┤ │   ✨ Generate Email  →  editable draft + copy   │
│ │ Embedded Linux Consultant │ │   📧 Open in mail client                        │
│ └───────────────────────────┘ │                                                │
└───────────────────────────────┴───────────────────────────────────────────────┘

---

✨ Features

• 🔎 Multi-board search — pulls from 5 free job APIs at once, remote-first with a Remote | Any toggle.
• ⭐ Instant match score — every card shows how well it fits your skills (keyword overlap, zero AI cost).
• 🧠 AI company & salary intel — one click gives you a company brief, reputation summary, fit score, recommended salary (real or AI-estimated), and the best way to apply.
• 🔗 Deep research links — jump straight to the company's Glassdoor, Levels.fyi, Blind, and LinkedIn pages.
• ✉️ One-click application kit — tailored outreach email, cover letter, and a CV-tailoring prompt, each editable with copy + mailto:.
• 🔌 Provider-agnostic AI — works with any OpenAI-compatible endpoint: OmniRoute, Groq, OpenRouter, OpenAI, or local Ollama. Built-in model picker + connection tester.
• 🎛️ Clean master-detail UI — scrollable job list on the left, live detail panel on the right. No database, no build step.

---

🛠 How it works

flowchart LR
    U([You]) -->|title · skills · Remote/Any| S[Search form]
    S --> J["jobs.search_jobs()"]
    J --> R[Remotive]
    J --> RO[RemoteOK]
    J --> AB[Arbeitnow]
    J --> JC[Jobicy]
    J --> TM[The Muse]
    J -. optional key .-> AD[Adzuna]
    J -. optional key .-> JS[JSearch]
    R & RO & AB & JC & TM --> N[Normalize · de-dupe · match score]
    N --> C[[Job cards]]
    C -->|Select| D[Detail panel]
    D -->|Analyze| E["ai.enrich()"]
    D -->|Generate| G["ai.generate()"]
    E & G --> AI{{Any OpenAI-compatible endpoint}}
    AI --> OMNI[OmniRoute / Groq / OpenAI / Ollama]

Loading

The job boards find the jobs; the AI enriches them (salary, company, fit, drafts). The LLM never scrapes — it only reasons over what the APIs return.

Tech stack: Python · Streamlit · requests · openai SDK · python-dotenv. No database — results live in session state, your profile saves to a local profile.json.

---

🚀 Quick start

# 1. Clone
git clone https://github.com/hassanannajjar/Job-Pilot.git
cd Job-Pilot

# 2. Create a virtual env + install
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 3. (Optional) configure AI + keys
cp .env.example .env               # edit AI_BASE_URL / AI_API_KEY / AI_MODEL

# 4. Run
streamlit run app.py

Open the URL Streamlit prints (default http://localhost:8501). Search works with zero config — you only need an AI provider for the intel & drafting features (set it live in the sidebar).

Sanity check the job parsers offline anytime:

python jobs.py     # → "jobs.py self-check OK"

---

🔗 Connect an AI provider

Pick a preset in the sidebar, paste a key, and go. Any OpenAI-compatible endpoint works.

Preset	Base URL	Example model	Key needed?
OmniRoute	http://localhost:20128/v1	auto/best-free	Local key (see below)
Groq (free)	https://api.groq.com/openai/v1	llama-3.3-70b-versatile	Free — console.groq.com
OpenRouter	https://openrouter.ai/api/v1	openai/gpt-4o-mini	openrouter.ai/keys
OpenAI	https://api.openai.com/v1	gpt-4o-mini	Paid — platform.openai.com
Ollama (local)	http://localhost:11434/v1	llama3.1	None (runs on your machine)

💡 New to this? Groq is the fastest free path (sign up, paste key, done). Ollama runs fully offline.

---

🔌 Using OmniRoute

OmniRoute is a local, open-source AI gateway — one OpenAI-compatible endpoint (http://localhost:20128/v1) that routes across 290+ providers with free-tier fallback. Job-Pilot connects to it like any other provider.

Setup:

1. Install & run OmniRoute — its dashboard opens at http://localhost:20128.
2. Providers → connect at least one (e.g. Kimi, DeepSeek, Gemini). The Provider Topology must show ≥ 1 active — a router with 0 active providers can't answer.
3. API Keys → Create a key.
4. In Job-Pilot's sidebar: choose the OmniRoute (local) preset → paste your key → click 🔄 Load models → pick a model → click 🧪 Test connection (should show ✅ + the model name).

sequenceDiagram
    participant JP as Job-Pilot
    participant OR as OmniRoute (:20128)
    participant P as Provider (DeepSeek / Kimi / …)
    JP->>OR: POST /v1/chat/completions (model = auto/best-free)
    OR->>P: routes to a healthy provider
    P-->>OR: completion
    OR-->>JP: OpenAI-shaped response

Loading

⚠️ Pick the right model (important!)

OmniRoute exposes namespaced model routes — there is no bare auto. Sending auto (or auto/best-chat) can fall through to a weak provider (e.g. felo-chat) that returns garbage like .com.

Use these ✅	Avoid these ❌
auto/best-free, auto/smart (route to DeepSeek)	bare auto, auto/best-chat (→ felo-chat junk)

Use 🔄 Load models to see everything your OmniRoute exposes, and 🧪 Test connection to confirm a model actually replies before you rely on it. If output ever comes back as a fragment, Job-Pilot detects it and tells you to switch models. Note: some providers may return errors independent of Job-Pilot (e.g. Kimi 402 if its quota/billing is unset, occasional 502s) — just pick another working route.

---

💼 Job sources

Source	Coverage	Salary data	Key required
Remotive	Remote (tech + non-tech)	sometimes	❌ none
RemoteOK	Remote (tech)	sometimes	❌ none
Arbeitnow	EU + remote	rarely	❌ none
Jobicy	Remote	often	❌ none
The Muse	Global (many on-site)	rarely	❌ none
Adzuna	Broad incl. non-remote	✅ real	ADZUNA_APP_ID + ADZUNA_APP_KEY
JSearch	Aggregates LinkedIn/Indeed/Glassdoor/ZipRecruiter	✅ real	RAPIDAPI_KEY

The five no-key sources are always on. Adzuna and JSearch activate automatically only when their keys are present in .env.

---

⚙️ Configuration (.env)

Variable	Purpose	Default
AI_BASE_URL	AI endpoint	http://localhost:20128/v1
AI_API_KEY	Key for the endpoint	—
AI_MODEL	Model id	auto (override to a valid one, e.g. auto/best-free)
ADZUNA_APP_ID / ADZUNA_APP_KEY	Enable Adzuna	—
ADZUNA_COUNTRY	Adzuna country code	us
RAPIDAPI_KEY	Enable JSearch	—

All AI settings are also editable live in the sidebar — .env just sets the defaults.

---

🧭 Usage walkthrough

1. Sidebar → My profile — add your name, email, target role, key skills, and a short résumé summary. (Skills power the match score & AI drafts.) Hit 💾 Save profile.
2. Search — type a title, choose Remote or Any, hit 🔍 Search.
3. Scan — cards are sorted by ★ match %; salary/source/remote chips at a glance.
4. Select a job → the right panel fills in.
5. 🏢 Company & Salary → 🔎 Analyze — get the AI brief, fit score, recommended salary, apply strategy, and research deep-links.
6. ✉️ Apply — pick Email / Cover Letter / CV Prompt → ✨ Generate → edit → copy or open in your mail client.

---

📁 Project structure

Job-Pilot/
├── app.py               # Streamlit dashboard — sidebar, search, master-detail UI
├── jobs.py              # Fetch + normalize + rank listings (5 free + 2 optional APIs)
├── ai.py                # OpenAI-compatible client: generate(), enrich(), list_models(), test_connection()
├── requirements.txt     # streamlit · requests · openai · python-dotenv
├── .env.example         # AI + optional job-source keys
├── .streamlit/config.toml  # dark violet theme
└── docs/                # put your screenshots here

---

🗺 Roadmap

• Saved-applications tracker (applications.json + a "Saved" tab)
• More keyed boards (USAJobs, etc.)
• Optional one-click send via Gmail SMTP (currently draft + mailto:)

---

🤔 Honest limitations

• No live Glassdoor ratings — Glassdoor has no free/legal API, so reputation is an AI summary + deep links, not scraped scores. Salary is real when a board provides it, otherwise a clearly-labeled AI estimate.
• Output quality tracks the model you route to — a weak/free model gives weaker text. Use the model picker + connection tester to land on a good one.
• Not a scraper — it uses official/public job APIs; it does not bypass any site's login or anti-bot.

---

🤝 Contributing

Issues and PRs welcome. It's a small, single-purpose codebase — keep changes lean and focused.

📄 License

MIT © 2026 Hassan Al-Najjar

⚠️ Disclaimer

A personal productivity tool. Respect each job board's Terms of Service and rate limits, and review every AI-generated draft before sending it.