Files · Automated Resume Scoring Agent for Boutique Recruiters

# Automated Resume Scoring Agent for Boutique Recruiters
 
> Score 200 resumes per role in seconds with a consistent rubric, no spreadsheets.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
The Automated Resume Scoring Agent ingests resumes via a web API, parses them (PDF/DOCX), scores each candidate against a recruiter-defined rubric using an LLM, caches results for repeat runs, evaluates score quality with an independent judge model, and persists candidate records for historical review. Built for boutique recruiting firms that need consistent, fast, and auditable resume screening.
 
## Getting Started
 
```bash
pnpm install
```
 
Copy `.env.example` to `.env` and configure the required environment variables:
 
| Variable | Description | Default |
|----------|-------------|---------|
| `OPENAI_API_KEY` | API key for OpenAI embeddings and scoring | — |
| `OPENAI_BASE_URL` | Base URL for OpenAI-compatible API | `https://api.openai.com/v1` |
| `SCORING_MODEL` | Model used for resume scoring | `gpt-4o` |
| `EMBEDDING_MODEL` | Model used for embedding generation | `text-embedding-3-small` |
| `JUDGE_MODEL` | Model used for score evaluation | `claude-sonnet-4-20250514` |
| `JUDGE_PROVIDER` | Provider for the judge model | `claude` |
 
Run the development server:
 
```bash
pnpm dev             # next dev
pnpm test            # vitest run with coverage
```
 
## Architecture
 
```
Upload → Parse → Score → Cache → Evaluate → Persist
```
 
1. **Upload** — Resume files (PDF/DOCX) are submitted via `POST /api/score` as multipart FormData along with a JSON rubric.
2. **Parse** — The resume-parser extracts raw text from the uploaded file.
3. **Score** — The scorer sends parsed text + rubric to an LLM and returns structured criterion scores and an overall score.
4. **Cache** — Results are cached (semantic/exact-match) so identical or similar resumes return instantly on re-score.
5. **Evaluate** — An independent judge model evaluates the quality of the score output (faithfulness, relevance, etc.).
6. **Persist** — Candidate scores are stored in memory for retrieval via the candidates API and optionally synced to long-term memory via `@reaatech/agent-memory`.
 
## API
 
| Method | Route | Purpose |
|--------|-------|---------|
| `POST` | `/api/score` | Upload a resume + rubric and get a scored evaluation |
| `POST` | `/api/jobs` | Create a job posting with rubric criteria |
| `GET` | `/api/jobs` | List all job postings |
| `DELETE` | `/api/jobs` | Delete a job posting by id |
| `POST` | `/api/candidates` | Store a scored candidate result |
| `GET` | `/api/candidates` | List candidates (filter by `?jobId=`) |
| `GET` | `/api/candidates/[id]` | Get a candidate with scoring history |
| `GET` | `/api/health` | Health check endpoint |
 
## REAA Packages
 
| Package | Role |
|---------|------|
| `@reaatech/llm-cache` | Semantic and exact-match caching of resume scores to avoid redundant LLM calls |
| `@reaatech/agent-budget-spend-tracker` | Tracks per-scope LLM spend for cost visibility and budget enforcement |
| `@reaatech/agent-eval-harness-judge` | LLM-as-judge engine that evaluates scoring quality (faithfulness, relevance, overall quality) |
| `@reaatech/agent-eval-harness-golden` | Golden trajectory dataset for evaluating scoring performance against known-good examples |
| `@reaatech/agent-memory` | Long-term memory layer for persisting candidate results and retrieving historical scoring data |
| `@reaatech/llm-cost-telemetry` | Cost telemetry and observability for LLM calls across the scoring pipeline |
 
## Running locally
 
```bash
pnpm install
pnpm test            # vitest run with coverage
pnpm dev             # next dev
```
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
src/                  services, lib, adapters
tests/                vitest suite (mirrors src/)
packages/             API references for every dependency (read these first)
DEV_PLAN.md           build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).