Installation

PhdScout runs locally with Python 3.10+ or on HuggingFace Spaces.

Clone & install

git clone https://github.com/Hipsterfil998/PhDScout.git
cd PhDScout
pip install -r requirements.txt

Get a Groq API key

Configure

Create a .env file in the project root:

# Required
LLM_BACKEND=groq
GROQ_API_KEY=gsk_your_key_here

# Optional overrides (see Configuration section)
OUTPUT_DIR=./output

Run

python app.py

Open http://localhost:7860 in your browser.

Dependencies

Quickstart

From zero to your first scored job list in under 5 minutes.

Web Interface

The Gradio UI is organised into three tabs.

Tab 1 — Setup & Search

Tab 2 — Results

Displays a scored table with columns: #, Score, Title, Institution, Type, Freshness, Rec., Why good fit.

Freshness labels

Tab 3 — Review & Edit

Select a position from the dropdown, click Load Position, then:

• Read the Position Details and match analysis
• Follow the CV Tailoring Hints panel
• Edit the Cover Letter draft freely
• Click Regenerate for a different version
• Download the letter as a .txt file
• Click Approve & Save to add it to the export queue

Command-Line Interface

For batch use or scripting, PhdScout exposes a CLI via main.py.

Basic usage

python main.py \
  --cv path/to/cv.pdf \
  --field "machine learning" \
  --location "Germany" \
  --type phd

Options

Python API

from agent import JobAgent

agent = JobAgent(
    model="llama-3.1-8b-instant",
    backend="groq",
    api_key="gsk_...",
)

profile, profile_text = agent.parse_cv("cv.pdf")
jobs = agent.search_jobs(field="NLP", location="Europe", position_type="phd")
scored = agent.score_jobs(jobs, profile_text)

for job in scored[:5]:
    m = job["match"]
    print(m["match_score"], job["title"], job.get("freshness"))

Job Sources

Freshness filtering

After scraping, PhdScout automatically removes:

• Postings with a posting date in a previous year
• Postings with a deadline already passed
• Jobs with no date info are kept (benefit of the doubt)

PhD eligibility gate

Before scoring, PhdScout checks whether the candidate holds or is pursuing a PhD and enforces two caps on postdoc and fellowship positions:

Adding a source

Create a new file in agent/search/scrapers/ that subclasses BaseScraper:

from agent.search.scrapers.base import BaseScraper

class MyScraper(BaseScraper):
    name = "mysource"

    def scrape(self, field, location, position_type):
        soup = self._fetch(f"https://example.com/jobs?q={field}")
        if soup is None: return []
        results = []
        for card in soup.select(".job-card"):
            results.append({
                "title": card.select_one("h2").text,
                "url": card.select_one("a")["href"],
                "posted": card.select_one(".date").text,
                "source": self.name,
                "type": self._detect_type(card.text, ""),
            })
        return results

Then register it in agent/search/searcher.py → _build_scrapers().

Configuration

All settings live in config.py. Edit the file directly — no restart needed if using the CLI, restart the Gradio app after changes.

LLM settings

Scraper settings

Freshness thresholds

UI defaults

Environment variables

Prompts

All LLM prompts live in agent/prompts/. Each service has its own file — edit the relevant file to tune that part of the agent's behaviour.

Available prompts

Example: changing the letter length

In agent/prompts/cover_letter.py, find COVER_LETTER_SYSTEM and change:

# Before
The letter should be 400-600 words (3-4 paragraphs).

# After
The letter should be 250-350 words (2-3 paragraphs).

Example: stricter scoring

In JOB_MATCHER_PROMPT, raise the thresholds in the scoring guide:

Scoring guide:
  85-100: Excellent — perfect research keyword overlap, recent publications
  70-84:  Good — strong overlap on primary research area
  50-69:  Partial — some overlap, transferable skills
  0-49:   Skip — different area or missing key requirements

Architecture

Project structure

Pipeline flow

LLM backends

Deployment

HuggingFace Spaces (recommended)

GitHub Pages (this documentation)

To enable GitHub Pages:

1. Go to your GitHub repo → Settings → Pages
2. Source: Deploy from a branch
3. Branch: main / folder: /docs
4. Click Save

The docs will be live at https://<username>.github.io/PhDScout.

Editing the docs

To modify this documentation directly on GitHub:

1. Go to your repo on GitHub
2. Navigate to docs/index.html
3. Click the pencil icon (Edit this file)
4. Edit the HTML — each section is a <section class="section" id="..."> block
5. Commit directly to main — GitHub Pages rebuilds automatically