modular-noc-scheduling 1.0.7

Shift Scheduling Algorithm using OR-Tools with Modular Constraints

Modular NOC Scheduling System

High‑performance, constraint‑based shift scheduling for 24/7 NOC / SOC teams. Built on Google OR-Tools CP-SAT. Supports expert/beginner supervision, holidays, weekends, Ramadan adjustments, fairness and workload balancing, off‑day allocation, and extensible modular constraints.

What's New in v1.0.7 (New Release)

• Reorganized developer-centric documentation (architecture, data model, extension patterns)
• Clear separation between core API and optional UI layer (Streamlit sample now considered a reference sandbox only)
• Detailed guide for: microservice integration (FastAPI), custom UI frameworks, exporting & parsing schedule data
• Shift name mapping + parsing helpers + CSV export examples
• Clarified constraint semantics & extension workflow

---

Contents

1. Overview
2. Core Concepts & Data Model
3. Installation & Quick Start
4. Troubleshooting
5. Technical Information
6. API Reference
7. License
8. Support
9. Version History

---

1. Overview

The package exposes a single high-level function that turns (year, month, employees, optional holidays, constraint toggles) into an optimized monthly assignment matrix. It can be:

• Called directly in Python scripts or notebooks
• Wrapped in a REST / gRPC microservice
• Driven via CLI for ad-hoc generation
• Connected to any UI (React, Vue, Django, Flask, FastAPI, Streamlit, etc.)

The repository formerly included a Streamlit prototype UI. Treat that file strictly as a developer sandbox example—NOT a required dependency. You can substitute any web layer; the API surface you need is the returned schedule_data structure and auxiliary output files.

---

2. Core Concepts & Data Model

Employees

Each employee is defined minimally as:

{"type": "EXPERT" | "BEGINNER", "vacation_days": int}

Fairness and supervision logic relies on a valid expert/beginner ratio (at least one expert when beginners exist).

Shifts (Technical Codes)

Regular: M (Morning), E (Evening), N (Night) Ramadan: MR, E1R, E2R, NR Holiday regular: HM, HE, HN Holiday Ramadan: HMR, HE1R, HE2R, HNR Non-working states: OFF (Annual Leave), No Shift Assigned (Weekend / free), No Shift Assigned - Rest (Mandatory rest)

Returned Schedule Structure

schedule_data = {
  "Employee 1": {"Day 1": "M", "Day 2": "N", ...},
  "Employee 2": {"Day 1": "No Shift Assigned", ...},
  # ... one dict per employee
}

All days are labeled Day 1 .. Day N (N = days in month). Values are technical shift codes above.

Output Files (Optional Artifacts)

• solution_YYYY_MM_timestamp_sol1.txt – human-readable schedule
• input_summary_YYYY_MM_timestamp.txt – configuration + constraint flags
• off_days_distribution_...txt – off-day fairness calculation
• month_calendar_info_...txt – calendar metadata (weekends, holidays, Ramadan)

---

3. Installation & Quick Start

Install from PyPI

pip install modular-noc-scheduling

Only PyPI installation is supported. Source / editable installs are not part of the standard distribution for this release.

Common Scenarios and Solutions

Scenario 1: "The Algorithm Says No Solution Found"

What this means: Your requirements cannot be met with the current team size or constraints.

Solutions:

• Add more team members
• Reduce minimum shift requirements
• Check if vacation day allocations are realistic

Scenario 2: "Someone Has Too Many Shifts"

What this means: The workload distribution isn't perfectly even.

Solutions:

• Enable the "Fair Distribution" constraints
• Increase the solution search time
• Consider if the person has fewer vacation days (affecting their off-day allocation)

Scenario 3: "Weekend Coverage Looks Uneven"

What this means: Some people work more weekends than others.

Solutions:

• Ensure "Fair Weekend Distribution" is enabled
• Check that you have enough team members for weekend coverage
• Consider the impact of vacation day differences

Scenario 4: "Holiday Coverage Is Missing"

What this means: Some holidays don't have proper shift coverage.

Solutions:

• Upload a complete holiday calendar file
• Enable holiday shift constraints
• Ensure minimum holiday staffing requirements are met

---

4. Troubleshooting

When to Contact Support

Contact us if:

• The algorithm doesn't load or crashes
• You get error messages you don't understand
• The schedule results seem completely wrong
• You need to modify algorithm rules or constraints

---

5. Technical Information

Algorithm Architecture

Core Components

• Scheduler Engine: Uses Google OR-Tools constraint programming
• Constraint Algorithm: Modular rules that can be enabled/disabled
• Calendar Integration: Supports both Gregorian and Hijri calendars

How It Works

1. Input Processing: Algorithm converts your requirements into mathematical constraints
2. Optimization: Advanced algorithms find the best schedule that satisfies all rules
3. Solution Generation: Multiple valid schedules may be found
4. Output Formatting: Results are presented in user-friendly formats

Constraint Categories

Coverage Constraints

• Ensure all shifts have adequate staffing
• Guarantee weekend and holiday coverage
• Maintain 24/7 operations continuity

Fairness Constraints

• Equal distribution of workload
• Balanced weekend/holiday assignments
• Fair vacation day consideration

Safety Constraints

• Expert supervision for beginners
• Mandatory rest after certain shift sequences
• Limits on consecutive working days

Cultural Constraints

• Special Ramadan shift patterns
• Regional holiday observances
• Cultural work week conventions

File Formats

Employee Data Input Employee information is entered through the web interface with the following parameters:

• Employee Type: EXPERT or BEGINNER
• Vacation Days: Integer value (0-21 for experts, 0-14 for beginners)

No separate employee data file is required - all input is handled through the interactive web interface.

Holiday File Format Upload a text file (.txt) with holidays using this exact format:

day; month; description
1; 1; New Year's Day
15; 8; Independence Day
25; 12; Christmas Day

Format requirements:

• Each line contains: day; month; description
• Semicolon (;) separated values
• Day and month as integers (e.g., 1-31 for day, 1-12 for month)
• Description is optional but recommended for clarity
• Lines starting with "day" are treated as headers and ignored
• Empty lines are ignored
• File encoding: UTF-8

Generated Output Files The algorithm automatically creates several output files with structured formats:

1. Input Summary (input_summary_YYYY_MM_timestamp.txt)

   • Contains all input parameters and constraint settings
   • Employee details and configuration used

2. Month Calendar Info (month_calendar_info_{YYYY_MM}_{YYYYMMDD_HHMMSS}.txt)

   • Title + month
   • Counts: Number of employees, solution limit, maximum shifts per employee
   • Employee Details: List of all employees with type and vacation days
   • Active Constraints: List of enabled constraint flags
   • Solver Results: Status, number of solutions found, success indicator

3. Off Days Distribution (off_days_distribution_{YYYY_MM}_{YYYYMMDD_HHMMSS}.txt)

   • Title + month
   • Repeated per-employee block: name/role, remaining vacation days, remaining months, min/max off days this month

4. Solution File (solution_YYYY_MM_timestamp_sol1.txt)

   • Complete day-by-day schedule assignments
   • Employee-day-shift mappings in readable format

---

6. API Reference

Main Function

run_modular_scheduling_algorithm()

The primary function for generating NOC schedules.

Function Signature:

from modular_scheduling.modular_scheduler import run_modular_scheduling_algorithm

success, output_files, solver_status, error_msg, schedule_data, max_shifts_per_employee = run_modular_scheduling_algorithm(
    year,                    # int: Gregorian year (e.g., 2025)
    month,                   # int: Month (1-12)
    employees_data,          # list: Employee information
    holidays_file_path=None, # str or None: Path to holidays file
    solution_limit=1,        # int: Maximum solutions to generate
    constraints=None         # dict or None: Constraint configuration
)

Parameters:

• year (int): The Gregorian year for scheduling
• month (int): Month (1-12) for scheduling
• employees_data (list): List of employee dictionaries with format:

  [
      {'type': 'EXPERT', 'vacation_days': 10},
      {'type': 'BEGINNER', 'vacation_days': 5} ## vacation_days: remaining vation days for the employee until the end of this year
  ]
  

• holidays_file_path (str, optional): Path to holidays file in specified format
• solution_limit (int): Maximum number of solutions to generate (default: 1)
• constraints (dict): Constraint configuration dictionary

Returns:

• success (bool): True if scheduling succeeded, False otherwise
• output_files (list): List of generated output file paths
• solver_status (str): OR-Tools solver status ("OPTIMAL", "FEASIBLE", "INFEASIBLE", etc.)
• error_msg (str): Error message if failed, empty string if successful
• schedule_data (dict): Complete schedule in format: {employee_name: {day_name: shift_assignment}}
• max_shifts_per_employee (int): Maximum number of shifts assigned to any employee

Example:

employees_data = [
    {'type': 'EXPERT', 'vacation_days': 12},
    {'type': 'EXPERT', 'vacation_days': 8},
    {'type': 'BEGINNER', 'vacation_days': 6} ## Vacation days are the remaining vacation days for this employee
]
## Configure constraints
constraints = {
    'constraint_weekday_shifts': True,
    'constraint_expert_supervision': True,
    'constraint_e_n_rest': True,
    'constraint_holiday_shifts': True,
    'constraint_weekend_shifts': True,
    'constraint_one_shift_per_person_per_day': True,
    'constraint_fair_weekend_distribution': True,
    'constraint_fair_holiday_distribution': True,
    'constraint_min_normal_evening_shifts': True,
    'constraint_min_abnormal_evening_shifts': True,
    'constraint_evenly_distribute_max_shifts': True,
    'constraint_off_days_based_on_vacation_balance': True,
    'constraint_limit_contiguous_shifts': True
}

success, output_files, solver_status, error_msg, schedule_data, max_shifts_per_employee = run_modular_scheduling_algorithm(
year=2025, month=9, employees_data=employees_data, holidays_file_path="holidays.txt", solution_limit=1, constraints=constraints
)

if success:
    print(f"Success! Status: {status}")
    print(f"Generated files: {files}")
    print(f"Max shifts per employee: {max_shifts}")
else:
    print(f"Failed: {error}")

Available Constraints

All constraints are modular and can be enabled/disabled through the constraints parameter:

constraints = {
    'constraint_weekday_shifts': True,                    # Ensure proper weekday shift coverage
    'constraint_expert_supervision': True,               # Require expert supervision for beginners
    'constraint_one_shift_per_person_per_day': True,     # One shift per employee per day
    'constraint_e_n_rest': True,                         # Rest after evening and night shifts
    'constraint_holiday_shifts': True,                   # Special holiday shift coverage
    'constraint_weekend_shifts': True,                   # Weekend shift coverage
    'constraint_fair_weekend_distribution': True,        # Fair weekend shift distribution
    'constraint_fair_holiday_distribution': True,        # Fair holiday shift distribution
    'constraint_min_normal_evening_shifts': True,        # Minimum evening shifts on normal days
    'constraint_min_abnormal_evening_shifts': True,      # Minimum evening shifts on Ramadan days
    'constraint_evenly_distribute_max_shifts': True,     # Equal maximum shifts for all employees
    'constraint_off_days_based_on_vacation_balance': True, # Off-days based on vacation balance
    'constraint_limit_contiguous_shifts': True           # Limit consecutive working days
}

Constraint Descriptions:

• constraint_weekday_shifts: Ensures adequate coverage during weekdays
• constraint_expert_supervision: Beginners must work with at least one expert
• constraint_one_shift_per_person_per_day: Prevents double-booking employees
• constraint_e_n_rest: Mandatory rest after evening/night shift sequences
• constraint_holiday_shifts: Special requirements for holiday coverage
• constraint_weekend_shifts: Ensures weekend shift coverage
• constraint_fair_weekend_distribution: Balances weekend work among employees
• constraint_fair_holiday_distribution: Balances holiday work among employees
• constraint_min_normal_evening_shifts: Minimum evening shifts for each employee
• constraint_min_abnormal_evening_shifts: Minimum evening shifts during Ramadan
• constraint_evenly_distribute_max_shifts: Forces equal workload distribution
• constraint_off_days_based_on_vacation_balance: Allocates off-days based on vacation entitlement
• constraint_limit_contiguous_shifts: Prevents excessive consecutive working days

---

7. License

This project is licensed under the MIT License - see the LICENSE file for details.

---

8. Support

• Documentation: GitHub Repository
• Issues: Report bugs or request features
• PyPI Package: modular-noc-scheduling

---

9. Version History

• v1.0.7 - New release: improved README with developer and IT guidance, notes and examples
• v1.0.6 - Version update for latest release
• v1.0.5 - Updated documentation
• v1.0.4 - Updated documentation with package-focused installation and improved usage examples
• v1.0.3 - Enhanced documentation and installation instructions
• v1.0.2 - Enhanced documentation and installation instructions
• v1.0.1 - Enhanced documentation and installation instructions
• v1.0.0 - Initial release with core scheduling functionality

---

Developed by the Innovation Team - Digital Transformation Directorate