Remote Job Agent

A FastAPI backend that collects remote job listings, pre-filters them against your profile, and scores promising matches with Claude (Anthropic).

Users register, define a career profile, and pull listings from multiple sources into the database. A keyword filter and LLM analysis then answer “how well does this fit you?” with a 1–10 score, reasoning, and pros/cons.

What it does

1. Job collection — Fetches remote jobs from RemoteOK and Remotive APIs, stores them in PostgreSQL (duplicates are skipped).
2. Profile — Skills, target roles, exclusions, minimum salary, location preferences, and more.
3. Pre-filter — Fast keyword-based screening before any LLM calls.
4. Matching — New jobs that pass the filter are analyzed with Claude; scores and explanations are saved to job_matches.

Tech stack

Layer	Tools
API	FastAPI, Uvicorn
Database	PostgreSQL, SQLAlchemy
Auth	JWT (python-jose), bcrypt
LLM	Anthropic API (claude-haiku-4-5)
Job sources	RemoteOK, Remotive

Project structure

okuma-asistani/
├── main.py                 # FastAPI application
├── app/
│   ├── routers/            # auth, profile, jobs, matches
│   ├── models.py           # User, UserProfile, JobPosting, JobMatch
│   ├── schemas.py          # Pydantic models
│   ├── auth.py             # JWT and password hashing
│   ├── database.py
│   └── services/
│       ├── job_collector.py
│       ├── keyword_filter.py
│       ├── matcher.py              # Claude scoring
│       ├── match_orchestrator.py
│       └── sources/                # remoteok, remotive
├── .env                    # Secrets (not committed to git)
└── .gitignore

Setup

Requirements

• Python 3.11+
• PostgreSQL
• Anthropic API key

1. Virtual environment and dependencies

python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install fastapi uvicorn sqlalchemy psycopg2-binary python-dotenv \
  anthropic bcrypt python-jose pydantic email-validator httpx

2. Environment variables

Create a .env file in the project root (it is listed in .gitignore):

DATABASE_URL=postgresql://user:password@localhost:5432/remote_job_agent
SECRET_KEY=a-long-random-production-secret
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60
ANTHROPIC_API_KEY=sk-ant-...

Security: Never commit ANTHROPIC_API_KEY or SECRET_KEY to the repository. Rotate keys if they were ever exposed.

3. Run the server

uvicorn main:app --reload

• API: http://127.0.0.1:8000
• Swagger docs: http://127.0.0.1:8000/docs

Typical workflow

flowchart LR
    A[Register / Login] --> B[Create profile]
    B --> C[POST /jobs/collect]
    C --> D[GET /jobs/candidates]
    D --> E[POST /matches/refresh]
    E --> F[GET /matches]

Loading

1. POST /auth/register — create an account
2. POST /auth/login — obtain access_token (use Authorization: Bearer <token> on later requests)
3. PUT /profile — skills, roles, exclusions, etc.
4. POST /jobs/collect — pull jobs from sources
5. GET /jobs/candidates — pre-filtered listings for your profile (no LLM)
6. POST /matches/refresh?max_jobs=30 — analyze selected jobs with Claude (uses API tokens)
7. GET /matches?min_score=7 — ranked matches by score

API overview

All protected endpoints require JWT (/auth/register and /auth/login are public).

Method	Path	Description
POST	/auth/register	Create user
POST	/auth/login	Get token (form: username=email, password)
GET/PUT/DELETE	/profile	Read / update / delete profile
POST	/jobs/collect	Collect jobs from all sources
GET	/jobs	List all jobs (paginated)
GET	/jobs/candidates	Jobs that pass the keyword filter
GET	/jobs/filter-stats	Filter statistics (debug)
GET	/jobs/{job_id}	Single job
POST	/matches/refresh	Run LLM analysis (limited by max_jobs)
GET	/matches	Scored matches with job details

Match scoring

For each job, Claude returns roughly:

• score — 1–10 (10 = strong apply recommendation)
• reasoning — short explanation
• pros / cons — highlights and caveats

POST /matches/refresh only processes jobs that have not been analyzed yet and pass the keyword filter; use max_jobs to control API cost.

License

Not specified yet.