How to make a call schedule with AI that doesn’t hallucinate.

The v1 rule set

What the sample solver actually does.

I kept this intentionally small. It is not a production anesthesia scheduler. The point is to prove the workflow runs end-to-end before adding real-world complexity.

1. Cover every required shift in coverage.csv.
2. Respect shift eligibility in clinicians.csv.
3. Block hard vacation and no-call requests in requests.csv.
4. Assign each clinician to at most one shift per day.
5. Enforce a minimum rest gap between assignments.
6. Prefer fair total assignment counts.
7. Prefer fair weekend assignment counts.
8. Use prior history.csv assignments as part of the fairness picture.
9. Prefer more rest spacing when the hard rules leave room.

First run

Run the dummy data before touching your own data.

Do not debug Python, CSV formatting, and your real scheduling rules at the same time. Run the sample exactly as-is first, see the schedule come out, then adapt.

First, clone the repo:

git clone https://github.com/rumblelab/ai-call-scheduler.git
cd ai-call-scheduler

python3 -m venv .venv

.venv/bin/python -m pip install -r requirements.txt

.venv/bin/python solver.py

Status: OPTIMAL
Wrote 28 assignments to output/sample_schedule.csv

Demand generation

coverage.csv is the file you actually have to fill out.

Of the four CSVs, this is the demand side. If a row exists, the solver tries to staff it. If a row is missing, the solver does not know that shift exists. So this is the file you have to think about carefully.

That said: don’t type it by hand. If your coverage pattern is regular, have your agent write a small script that generates it.

Create a Python script that writes coverage.csv for June 2026.
Rules:
- Every Saturday and Sunday needs one NORTH call and one SOUTH call.
- Weekdays do not need call coverage in this example.
- Output columns: date, shift_type, required_count.
- Dates in ISO format (YYYY-MM-DD).

date,shift_type,required_count
2026-06-06,NORTH,1
2026-06-06,SOUTH,1
2026-06-07,NORTH,1
2026-06-07,SOUTH,1

The same pattern handles:

• one OB call every day
• two OR calls on weekdays, one OR call on weekends
• different sites: NORTH, SOUTH, OB
• holiday-specific call requirements
• higher required counts on known heavy days

Customization

Once the sample works, change one thing at a time.

Copy the sample data into your own folder:

cp -R data/sample data/my_data

Copy the sample config:

cp config/sample_rules.json config/my_rules.json

In config/my_rules.json, point at your data:

{
  "input_dir": "data/my_data",
  "output_csv": "output/my_schedule.csv"
}

Run it:

.venv/bin/python solver.py --config config/my_rules.json

Change one file at a time. First clinicians. Then coverage. Then requests. Then history. If the model becomes infeasible, the newest change is usually where the conflict lives — remove that rule first and inspect what changed.

For worked examples of common adaptations — adding a third shift type, locked assignments, weekend-pairing rules — see docs/adaptation-cookbook.md.

Agent handoff

If you have Claude Code or Codex, just paste this.

This whole tutorial is designed so a coding agent can drive it. Claude Code, Codex, Cursor, ChatGPT — any of them can clone the repo, read the docs, run the dummy solve, and then help you adapt one rule at a time.

I’d strongly recommend Claude Code or Codex over a chat-only assistant for this. Local-folder agents can inspect files, run the solver, and see the actual output. Chat-only assistants can only guess at what your CSVs look like.

I want to use the free NiceSchedule call schedule solver tutorial.

Public walkthrough:
https://niceschedule.com/how-to-make-a-schedule-with-ai/

GitHub repo:
https://github.com/rumblelab/ai-call-scheduler

My goal, in three phases:

PHASE 1 — Prove it works.
Clone the repo and run the dummy solve exactly as-is. Then explain
to me in plain English what the solver did and what the output means.

PHASE 2 — Set it up for my practice.
Once the dummy works, follow docs/new-practice-setup.md to walk me
through configuring my own schedule, step by step:
  - my clinician roster
  - my coverage pattern (use scripts/generate_coverage.py with my
    description, don't make me hand-type the file)
  - my hard vs soft rules (post-call rest, partner allocation,
    weekend pairing, etc.)
  - my vacation and time-off requests (I'll paste whatever format
    I have — emails, a list, a spreadsheet)
  - my first real solve, and a triage of the output before we change
    anything

PHASE 3 — Iterate.
Add one rule at a time. After each change, re-run and tell me what
shifted in the output. If the solver becomes infeasible, walk back
to the most recent change and use docs/troubleshooting.md to diagnose.

Before changing anything, please read these files in order:
- README.md
- docs/scheduler-agent-skill.md
- docs/new-practice-setup.md
- docs/csv-schema.md
- docs/adaptation-cookbook.md
- docs/troubleshooting.md
- docs/agent-privacy.md
- config/sample_rules.json
- data/sample/clinicians.csv
- data/sample/coverage.csv
- data/sample/requests.csv
- data/sample/history.csv
- scripts/generate_coverage.py
- solver.py

Safety rules:
- Don't ask me for real names or schedules until the dummy solve works.
- If you need example data at any point, invent fake data.
- Add one rule at a time and tell me how to test it.
- Per docs/agent-privacy.md, keep this data local. Don't paste real
  schedules into public tools.

Start by running the dummy solve and showing me the output.

Good first asks for your agent

• "Generate a new coverage.csv for a different month."
• "Add a third shift type (NIGHT) and the matching eligibility column."
• "Add a locked_assignments.csv file so I can pin specific people to specific shifts."
• "Add a rule that nobody works both Saturday and Sunday of the same weekend."
• "Add a soft preference for spreading holidays fairly."

Where it breaks

This gets hard when the rules become real.

The basic pattern is not magic. The hard part is making it work for a real group: cleaning requests, importing historical fairness, modeling local exceptions, fixing infeasible months, post-call recovery, locked assignments, holiday rotation, secure access, readable schedule views, distribution, and month-over-month maintenance.

That is roughly the moment a DIY script stops being enough. A real schedule needs a place where requests live, where history is tracked across months, where people can be added or removed without breaking previous solves, and where the schedule can be safely shared with the group after it’s reviewed.

If that’s the wall you’ve hit, see how NiceSchedule handles it for real groups — or jump to the cards below.