prospect-jobs 0.1.1

Autonomous AI job opportunity hunter for Twitter/X

Prospect

Prospect is an autonomous AI job opportunity hunter for Twitter/X. It searches for hiring tweets matching your target role and location, scores them against your profile using a local or cloud LLM, and surfaces the best leads in a review dashboard.

Works for any role, any location, any tech stack — all behaviour is driven by your config files.

Quick Start

1. Install

pip install "prospect-jobs[dashboard]"
playwright install chromium

Want to hack on the code instead? Clone the repo and run pip install -e ".[dashboard]".

2. Pick a working directory and scaffold it

Prospect stores its config, database, and session cookies in whatever directory you run it from (or whatever $PROSPECT_HOME points to). Pick one — anywhere is fine:

mkdir ~/job-hunt && cd ~/job-hunt

Then run init to scaffold the three config files you need:

# Basic scaffold — creates .env, config.yaml, profile.yaml from templates
prospect init

# Or: scaffold + auto-fill profile.yaml from your resume (requires Ollama or Anthropic API key)
prospect init --resume /path/to/your/resume.pdf

After this runs, ~/job-hunt/ contains:

• .env — Twitter credentials and API keys (fill in before running)
• config.yaml — search queries, LLM settings, filters
• profile.yaml — your target roles, skills, location

3. Fill in your credentials

Edit .env (in the directory you chose):

X_USERNAME=your_twitter_username
X_EMAIL=[e-mail]
X_PASSWORD=your_twitter_password
ANTHROPIC_API_KEY=sk-ant-...   # Optional — only if using Claude for scoring

Edit profile.yaml — confirm target roles, skills, and location (skip this if you used --resume).

Edit config.yaml — replace the example queries with ones relevant to your role:

search:
  queries:
    - "hiring ML engineer NYC"
    - "LLM engineer job remote"
    - "AI startup hiring [your city]"

4. Pull the LLM model (if using Ollama)

ollama pull llama3.1:8b

Or switch to Anthropic Claude in config.yaml (requires ANTHROPIC_API_KEY in .env).

5. Run

# Single search cycle (limit 2 queries for a smoke test first)
prospect search --limit 2

# Full search cycle
prospect search

# Search without LLM scoring (faster, no model needed)
prospect search --no-score

# Limit to first N queries (good for testing)
prospect search --limit 5

# Continuous daemon (searches every 30 min by default, fires immediately on start)
prospect daemon

# Launch Streamlit dashboard
prospect dashboard

# Wipe the database (asks for confirmation)
prospect clear-db

# Wipe without prompt (for scripts)
prospect clear-db --confirm

Customisation

Profile (profile.yaml)

All scoring is derived from your profile — no Python changes needed:

Field	Effect on scoring
target_roles	Roles closely matching score higher
skills	Tech stack alignment affects score
preferences.locations	Location match boosts score
seniority	junior / mid / senior / any
resume_summary	Embedded in every LLM scoring prompt

Search queries (config.yaml)

Queries run verbatim through the Twitter/X search bar. Short, conversational phrases work best — write them how a person would type them, not like a job board listing.

Useful angles to cover:

• "hiring ML engineer [city]" — geographic targeting
• "founding engineer AI remote" — startup-stage signals
• "we're looking for LLM engineer" — informal hiring language
• "[specific skill] engineer job" — stack-first signals

Switching LLM providers

Edit config.yaml:

# Local (free, runs on your machine)
scoring:
  provider: "ollama"
  model: "llama3.1:8b"

# Cloud (better quality, costs money)
scoring:
  provider: "anthropic"
  model: "claude-haiku-4-5-20251001"

Configuration Reference

config.yaml

Key	Default	Description
search.queries	[]	Seed search queries — replace with your own
search.interval_minutes	30	Daemon search interval
search.use_generated_queries	true	Expand seed queries via LLM (cached 24h)
filters.min_followers	200	Discard authors below this (reduces bots)
filters.exclude_keywords	list	Pre-LLM discard — saves API costs
scoring.provider	ollama	ollama or anthropic
scoring.model	llama3.1:8b	Model name
scoring.auto_irrelevant_threshold	3	Score below this → auto-marked irrelevant
scoring.hot_lead_threshold	7	Score above this → hot lead
scoring.hard_disqualifiers	list	Role types that always score low

profile.yaml

Field	Description
name	Your name (included in scoring context)
target_roles	List of job titles you're targeting
skills	Your technical skills
preferences.locations	Cities/regions/remote you're open to
preferences.remote_ok	true / false
seniority	junior / mid / senior / any
resume_summary	2-4 sentence background (verbatim in prompt)

Project Structure

src/prospect/
├── core/              # Search, parse, score logic
│   ├── searcher.py   # Twitter/X search via Playwright
│   ├── parser.py     # Extract job details from tweets
│   ├── scorer.py     # LLM-based relevance scoring
│   ├── llm.py        # Provider abstraction (Ollama / Anthropic)
│   └── query_generator.py  # LLM-generated query expansion (cached)
├── db/               # Database layer
│   ├── models.py     # SQLAlchemy ORM models
│   └── database.py   # Session management
├── cli/              # Command-line interface
│   └── commands.py   # Search, daemon, and clear-db logic
├── dashboard/        # Optional Streamlit UI
│   ├── app.py        # Home page with stats
│   └── pages/        # Feed, Contacts, Outreach pipeline, Settings
└── __main__.py       # CLI entry point

Dashboard

Launch with prospect dashboard, then open http://localhost:8501.

Page	Description
Home	Stats overview and score distribution
Feed	Review and action opportunities
Contacts	Manage contacts and outreach status
Outreach	Kanban pipeline (reviewed → contacted → applied)
Settings	Edit queries, run searches manually, manage database

Data & Security

• Credentials are stored only in .env (gitignored by default)
• profile.yaml and config.yaml are gitignored — create them from the .example files
• Twitter session cookies are stored in data/cookies.json with 600 permissions (owner-only)
• All data is stored locally in data/prospect.db (SQLite)
• The dashboard runs on localhost only — no external access
• Set PROSPECT_HOME=/path/to/dir to run the CLI from anywhere (data, config, and profile resolve relative to that path)

Troubleshooting

profile.yaml not found or config.yaml not found

• Copy the .example files: cp profile.yaml.example profile.yaml && cp config.yaml.example config.yaml
• Run prospect from the directory containing those files, or set PROSPECT_HOME

No tweets found

• Verify your search queries in config.yaml are relevant to your role/location
• Make sure Twitter cookies are valid (re-run triggers auto-login)

LLM scoring failing

• Make sure Ollama is running: ollama serve
• Confirm the model is pulled: ollama list
• If >50% of tweets fail scoring, a warning is printed with the likely cause

Daemon not running searches

• Check logs — after 3 consecutive failures the daemon pauses and prints a clear message

License

MIT