Fair Call Agent

Faircall Agent Framework

Fair Call Agent is an agentic constraint reasoning layer built on top of Fair Call Pro. I originally created this production shift scheduling app for healthcare shift distribution, and it is now industry agnostic, serving clinics, security firms, call centers, and more.

The Origin Story

I built the first version of Fair Call Pro link as a practical tool during my medical laboratory science internship to solve the real problem of distributing shifts and calls fairly across a team . It worked well but was completely deterministic, meaning everyone was treated as interchangeable. The moment someone requested time off or refused weekend work, the system failed to adapt. Since this problem exists in every industry that schedules people, I took my original application further and built an agentic layer. This upgrade uses an LLM to understand natural language constraints, reason about them, and produce schedules that are both fair and practical.

The Problem

The deterministic Least Recently Used scheduler in my original Fair Call Pro distributes shifts evenly across staff. It works perfectly when everyone is interchangeable and has no personal constraints. However, real managers need to handle specific requests like Ada needing time off for her wedding, Chidi avoiding weekends, and Kemi only working mornings. The baseline scheduler ignores all of these nuances. It produces mathematically fair schedules that are practically unusable in the real world.

The Agent Solution

I built a three-agent system that sits on top of the base scheduler.

Constraint Parser: Converts natural language instructions into 14 types of structured constraints. It handles time off, availability, and workload limits using a Groq LLM for semantic understanding alongside a regex fallback.

Constraint Aware Scheduler: Wraps the core algorithm with hard constraint filtering and soft constraint scoring. It pre-pins specific shifts, filters ineligible staff, scores soft preferences, and gracefully degrades when the team is understaffed.

Schedule Explainer: Analyzes the output for fairness, constraint compliance, and anomalies. It also generates actionable insights from the failure analysis.

Measured Improvement

Across 12 realistic evaluation cases, the system demonstrated significant gains. Constraint satisfaction improved from 55 percent to 100 percent (a 45 point increase) while maintaining 100 percent coverage and keeping the fairness score nearly identical (95.6 vs 95.8).

Hot Take

Back-to-back violations increase slightly when honoring time off constraints in understaffed teams because removing one person forces others to work consecutive days. Constraint satisfaction and individual workload smoothness are sometimes at odds. The agent's job is not to eliminate all violations but to make transparent, principled trade offs that the baseline cannot consider.

Tech Stack

TypeScript, Groq SDK, NetMind (GLM-5.3-Flash), OpenAI SDK, Strands Agents SDK, Custom constraint parser + enhanced schedule (https://github.com/Danielbuildsorigin/fair-call-pro), date-fns , Zod