| --- |
| 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 |
| --- |
| |
| <h1 align="center">PhdScout 🎓</h1> |
|
|
| <p align="center"> |
| <strong>AI-powered search agent for PhD positions, postdocs, research fellowships, and academic staff roles.</strong> |
| </p> |
|
|
| <p align="center"> |
| 🆓 <strong>100% free</strong> — no subscriptions, no API costs, no sign-up required.<br> |
| Live demo on HuggingFace Spaces: <a href="https://huggingface.co/spaces/HipFil98/PhDScout">HipFil98/PhDScout</a><br> |
| 📖 <a href="https://hipsterfil998.github.io/PhDScout">Full documentation</a> |
| </p> |
|
|
| --- |
|
|
| ## 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 |
|
|
| 1. Upload your CV (PDF, DOCX, or TXT) |
| 2. Enter your research field (e.g. `machine learning`, `computational biology`) |
| 3. Select a country or region from the dropdown (40+ options, or type a custom value) |
| 4. Choose the position type (`PhD`, `postdoc`, `fellowship`, `predoctoral`, `research staff`) |
| 5. Set a minimum match score (used as a recommendation threshold — all positions are reviewable) |
| 6. Click **Parse CV & Search Positions** and wait (~2–3 minutes) |
| 7. In the **Results** tab, browse all scored positions |
| 8. In the **Review & Edit** tab, load any position, read CV tailoring hints, and edit the cover letter |
| 9. Click **Approve & Save** for positions you want to apply to |
| 10. In the **Export** tab, download all approved applications as a ZIP |
|
|
| --- |
|
|
| ## Running locally |
|
|
| ```bash |
| git clone https://github.com/Hipsterfil998/PhDScout.git |
| cd PhDScout |
| pip install -r requirements.txt |
| ``` |
|
|
| Create a `.env` file: |
|
|
| ```env |
| LLM_BACKEND=groq |
| GROQ_API_KEY=your_groq_api_key |
| ``` |
|
|
| Get a free Groq API key at [console.groq.com/keys](https://console.groq.com/keys). |
|
|
| Then run: |
|
|
| ```bash |
| 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](https://groq.com) 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](https://euraxess.ec.europa.eu) — European Commission portal for research careers |
| - [mlscientist.com](https://mlscientist.com) — ML & AI academic job board |
| - [jobs.ac.uk](https://www.jobs.ac.uk) — UK academic jobs portal |
| - [scholarshipdb.net](https://scholarshipdb.net) — Worldwide academic jobs and scholarships aggregator |
| - [nature.com/careers](https://www.nature.com/naturecareers) — Multidisciplinary global research job board |
|
|
| LLM inference powered by [Groq](https://groq.com) free API. |
|
|
| --- |
|
|
| ## Cite this work |
|
|
| If you use PhdScout in your research or project, please cite it as: |
|
|
| ```bibtex |
| @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 |
|
|
