# Stage 3 — Phone Screen Scheduler Agent (code)

A human approved the candidate in Stage 2. This agent books the phone screen — finding a time
that works for **both** the candidate and every interviewer, across time zones, then sending the
booking link and reminders. It does logistics only; it never screens or decides.

## Files
- `stage3_phone_screen_scheduler.py` — the agent.
- `stage3_candidates_sample.csv` — candidates advanced to the phone screen (your ATS exports this).
- `stage3_interviewers_sample.json` — interviewer roster + working hours + which interviewers each req needs.
- `stage3_scheduler_README.md` — this file.

## The clever part
The agent computes **mutual open slots** — times inside every interviewer's working hours, clear of
their busy calendars (plus buffers), at least 24h out — and shows them to the candidate **in the
candidate's own time zone**. If no time works for everyone, it escalates to the recruiter instead
of forcing a bad slot.

## Safety rails (built in)
- **Dry-run by default** — prints what it would do, books/sends nothing.
- **Texts need consent** — SMS only when `consent_to_contact = TRUE`.
- **Never** offers a slot outside working hours or over a busy block; **never** double-books.
- **Escalates** to the recruiter when there's no shared availability.
- **Audit log** of every invite, booking, and escalation.

## Run it (no setup needed)
1. Python 3.9+ in this folder.
2. `python stage3_phone_screen_scheduler.py`
3. You'll see the mutual slots, a simulated booking, calendar holds, and the reminder schedule —
   all printed, nothing sent.

## Use your own data
- Replace the candidates CSV with your recruiter-approved phone-screen list (same columns).
- Edit `stage3_interviewers_sample.json` with real people, time zones, and working hours, and map
  each `req` to its interviewer(s). Add 1, 2, or more interviewers per req — the agent intersects
  all their calendars.

## Going live
1. In the CONFIG block: set company name, booking-page URL, duration, window, and buffers.
2. Wire your real services into the four PROVIDER HOOKS:
   - `get_busy()` → calendar free/busy (Google / Outlook)
   - `create_calendar_event()` → calendar write
   - `send_email()` / `send_sms()` → your email & text providers
   - `generate_video_link()` → Zoom / Meet / Teams
3. Set `SIMULATE_BOOKING = False` (real candidates book from the link themselves).
4. Set `DRY_RUN = False`. Test on a couple of your own calendars first.

## Note on reminders
Reminders are time-based, so in production you run this agent on a schedule (e.g., every 15 min via
a cron job or your orchestration tool). Each run sends whatever reminders are now due. The demo
prints the full reminder plan so you can see the cadence.
