A newer version of the Gradio SDK is available: 6.15.1
title: PhDScout
emoji: 🎓
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.23.3
app_file: app.py
pinned: false
license: mit
short_description: AI-powered search agent for PhD and academic positions
PhdScout 🎓
AI-powered search agent for PhD positions, postdocs, research fellowships, and academic staff roles.
🆓 100% free — no subscriptions, no API costs, no sign-up required.
Live demo on HuggingFace Spaces: HipFil98/PhDScout
📖 Full documentation
What it does
Upload your CV, set a research field and country, and PhdScout will:
- Search multiple academic job boards for open positions
- Score each position against your profile (0–100 match score)
- Rank all results and highlight the best fits
- Generate a personalized cover letter draft for every position
- Export all approved applications as a ZIP (cover letters + position details)
How to use
- Upload your CV (PDF, DOCX, or TXT)
- Enter your research field (e.g.
machine learning,computational biology) - Select a country or region from the dropdown (40+ options, or type a custom value)
- Choose the position type (
PhD,postdoc,fellowship,predoctoral,research staff) - Set a minimum match score (used as a recommendation threshold — all positions are reviewable)
- Click Parse CV & Search Positions and wait (~2–3 minutes)
- In the Results tab, browse all scored positions
- In the Review & Edit tab, load any position, read CV tailoring hints, and edit the cover letter
- Click Approve & Save for positions you want to apply to
- In the Export tab, download all approved applications as a ZIP
Running locally
git clone https://github.com/Hipsterfil998/PhDScout.git
cd PhDScout
pip install -r requirements.txt
Create a .env file:
LLM_BACKEND=groq
GROQ_API_KEY=your_groq_api_key
Get a free Groq API key at console.groq.com/keys.
Then run:
python app.py
The app will be available at http://localhost:7860.
Project structure
PhDScout/
├── app.py # Gradio web interface
├── config.py # Runtime settings (model, thresholds, delays)
├── requirements.txt
└── agent/
├── __init__.py # Public API: JobAgent, LLMQuotaError
├── pipeline.py # JobAgent orchestrator
├── base_service.py # BaseLLMService base class
├── llm_client.py # Groq / HuggingFace / Ollama client
├── utils.py # Shared utilities
├── prompts/ # LLM prompts — one file per service
│ ├── cv_parser.py
│ ├── job_matcher.py
│ ├── cv_tailor.py
│ └── cover_letter.py
├── cv/ # CV-related services
│ ├── parser.py # CV extraction + LLM parsing
│ ├── tailor.py # Tailoring hints generator
│ └── cover_letter.py # Cover letter writer
├── matching/
│ └── matcher.py # LLM-based scoring + PhD eligibility cap
└── search/
├── searcher.py # JobSearcher (orchestrates scrapers)
└── scrapers/
├── base.py # BaseScraper ABC + shared helpers
├── euraxess.py # EU/worldwide research portal
├── mlscientist.py # ML & AI academic positions
├── jobs_ac_uk.py # UK academic jobs (UK/worldwide only)
├── scholarshipdb.py # Worldwide aggregator (28k+ positions)
└── nature_careers.py # Nature.com/careers — multidisciplinary
Model
Powered by Groq free API — fast inference, no subscription required.
Uses llama-3.1-8b-instant by default. To change the model, edit default_model in config.py.
For local use, the app also supports Ollama — set LLM_BACKEND=ollama in .env.
Credits
Job data sourced from:
- Euraxess — European Commission portal for research careers
- mlscientist.com — ML & AI academic job board
- jobs.ac.uk — UK academic jobs portal
- scholarshipdb.net — Worldwide academic jobs and scholarships aggregator
- nature.com/careers — Multidisciplinary global research job board
LLM inference powered by Groq free API.
Cite this work
If you use PhdScout in your research or project, please cite it as:
@software{pellegrino2026phdscout,
author = {Pellegrino, Filippo},
title = {{PhdScout}: an AI-powered search agent for academic positions},
year = {2026},
url = {https://github.com/Hipsterfil998/PhDScout},
license = {MIT}
}
License
MIT