# Stage 4 — Assessment Agent (code)

After a candidate passes the phone screen, this agent runs the assessment step end to end:
sends it, chases the deadline, and routes the results to the recruiter. It handles communication
and routing **only** — it never scores or decides pass/fail. That judgment stays with the recruiter.

## Files
- `stage4_assessment_agent.py` — the agent.
- `stage4_candidates_sample.csv` — candidates at the assessment stage (your ATS exports this).
- `stage4_assessments_sample.json` — per-role assessment config (name, link, deadline, required or not).
- `stage4_assessment_README.md` — this file.

## What it does, by candidate state
- **Not sent yet** → sends the assessment with instructions and a deadline.
- **Sent, deadline near** → sends a nudge.
- **Sent, overdue** → final note to the candidate, then escalates to the recruiter. **Never auto-rejects.**
- **Completed** → routes the result to the recruiter so a human decides the next step.
- **Role needs no assessment** → advances without one.

## Safety rails (built in)
- **Dry-run by default** — prints what it would do, sends nothing.
- **Texts need consent** — SMS only when `consent_to_contact = TRUE`.
- **No judgments** — the agent never scores or decides; results and overdue cases go to a human.
- **Audit log** of every send, nudge, route, and escalation.

## Run it
1. Python 3 in this folder.
2. `python stage4_assessment_agent.py`
3. Watch all five paths play out — nothing is actually sent.

## Use your own data
- Replace the candidates CSV with your real assessment-stage list (same columns).
- Edit `stage4_assessments_sample.json`: set each role's assessment name, link, and deadline,
  or `assessment_required: false` for roles with no test.

## Going live
1. Set company name, sender, and nudge window in CONFIG; edit the message templates.
2. Wire your services into the PROVIDER HOOKS:
   - `get_assessment_status()` → your assessment platform (status + score)
   - `send_email()` / `send_sms()` → email & text providers
   - `notify_recruiter()` → email or Slack to the recruiter
3. Set `DRY_RUN = False` and test on your own addresses first.

## Note on timing
The `days_since_sent` column simulates time so you can see nudge/overdue behavior in one run.
In production you drop that column — the agent reads the real sent-date and completion status from
your assessment platform, and you run it on a schedule (e.g., daily) so nudges fire when due.
Track which candidates were already nudged to avoid repeat reminders.
