API Reference

Auto-generated reference for the shiftcraft_core package. All public symbols are documented here from their source docstrings.

Entry point

Main entry point: solve the scheduling problem.

Parameters:

Name	Type	Description	Default
`payload`	`dict[str, Any]`	Raw JSON dict containing period, team, coverage, and holidays.	required

Returns:

Type	Description
`dict[str, Any]`	Dictionary with solution status, schedule, summary, and penalty (or conflicts).

Model building

Build the complete CP-SAT model with variables, constraints, and objective.

Parameters:

Name	Type	Description	Default
`inp`	`ScheduleInput`	The parsed schedule input.	required

Returns:

Type	Description
`CpModel`	Tuple of (model, vars_dict) where vars_dict contains all decision variables
`dict[str, Any]`	and metadata needed for solution formatting.

Input parsing

Parse and validate input JSON payload.

Parameters:

Name	Type	Description	Default
`payload`	`dict[str, Any]`	Raw JSON dict containing period, team, coverage, and holidays.	required

Returns:

Type	Description
`ScheduleInput`	Validated ScheduleInput with all dates expanded and structures parsed.

Data types

Complete input specification for schedule generation.

`get_coverage(d)`

Return effective coverage for a date.

Applies date-range overrides first, falls back to day-of-week defaults.

`is_holiday_for(d, city)`

Check if a date is a holiday for a specific city.

Team member with leave history and preferences.

A leave request for a specific date with optional type.

Record of a compensatory off earned and optionally redeemed.

Historical shift counts from the previous month.

Coverage requirements for all shifts on a given day.

Coverage requirements for a single shift slot.

Override default coverage for a specific date range.

`covers(d)`

Check if this override applies to the given date.

`get_slot(shift)`

Get the coverage slot for a specific shift.

Holiday definition with optional location restrictions.

Variables

Create all decision variables for the scheduling problem.

Parameters:

Name	Type	Description	Default
`model`	`CpModel`	The CP-SAT model to add variables to.	required
`inp`	`ScheduleInput`	The parsed schedule input.	required

Returns:

Type	Description
`dict[str, Any]`	Dictionary containing:
`dict[str, Any]`	shift_vars: {(emp_id, date_iso, shift): BoolVar} — 1 if assigned
`dict[str, Any]`	off_vars: {(emp_id, date_iso): BoolVar} — 1 if off (week_off or leave)
`dict[str, Any]`	leave_vars: {(emp_id, date_iso, leave_type): BoolVar} — 1 if specific leave type
`dict[str, Any]`	emp_ids: list of employee IDs
`dict[str, Any]`	emp_by_id: dict mapping employee ID to Employee object
`dict[str, Any]`	date_isos: list of date ISO strings
`dict[str, Any]`	date_by_iso: dict mapping date ISO string to date object

Constraints

Add all hard constraints to the CP-SAT model.

Parameters:

Name	Type	Description	Default
`model`	`CpModel`	The CP-SAT model to add constraints to.	required
`inp`	`ScheduleInput`	The parsed schedule input.	required
`vars_dict`	`dict[str, Any]`	Dictionary containing decision variables and metadata.	required

Objective

Attach a minimise-penalty objective to model.

Formatter

Build the output dict from solver results.

Parameters:

Name	Type	Description	Default
`status`	`CpSolverStatus`	CP-SAT solver status code.	required
`solver`	`CpSolver`	The CP-SAT solver instance.	required
`inp`	`ScheduleInput`	The parsed schedule input.	required
`vars_dict`	`dict[str, Any]`	Dictionary containing decision variables and metadata.	required
`conflict_reasons`	`list[str] \| None`	Optional list of conflict explanations for infeasible solutions.	`None`

Returns:

Type	Description
`dict[str, Any]`	On failure: {"status": "infeasible", "conflicts": [...]}
`dict[str, Any]`	On success: { "status": "ok" \| "feasible", "schedule": [{"date": ..., "": ""}, ...], "summary": {"": {"morning": n, "afternoon": n, ...}, ...}, "penalty": }

Diagnostics

Analyze input to identify potential causes of infeasibility.

Parameters:

Name	Type	Description	Default
`inp`	`ScheduleInput`	The parsed schedule input.	required

Returns:

Type	Description
`list[str]`	List of human-readable conflict explanations.