From c2b17fc5f7d00d57a8e53150f49322922983546f Mon Sep 17 00:00:00 2001 From: VisheshRampersad Date: Sat, 22 Nov 2025 04:00:49 +0000 Subject: [PATCH 1/3] Added the strategy pattern for the autoscheduling, it includes the init file, schedule class, the three scheduling methods. --- App/strategies/__init__.py | 6 ++ App/strategies/balancedaynight.py | 42 +++++++++++ App/strategies/evendistribution.py | 28 ++++++++ App/strategies/minimizedays.py | 50 +++++++++++++ App/strategies/strategy.py | 110 +++++++++++++++++++++++++++++ 5 files changed, 236 insertions(+) create mode 100644 App/strategies/__init__.py create mode 100644 App/strategies/balancedaynight.py create mode 100644 App/strategies/evendistribution.py create mode 100644 App/strategies/minimizedays.py create mode 100644 App/strategies/strategy.py diff --git a/App/strategies/__init__.py b/App/strategies/__init__.py new file mode 100644 index 0000000..1dbf826 --- /dev/null +++ b/App/strategies/__init__.py @@ -0,0 +1,6 @@ +from .strategy import Schedule, ScheduleStrategy, get_staff_id, get_shift_id, get_shift_day, get_shift_type +from .evendistribution import EvenDistribution +from .balancedaynight import BalanceDayNight +from .minimizedays import MinimizeDays + +__all__ = ["Schedule", "ScheduleStrategy", "get_staff_id", "get_shift_id", "get_shift_day", "get_shift_type", "EvenDistribution", "BalanceDayNight", "MinimizeDays"] \ No newline at end of file diff --git a/App/strategies/balancedaynight.py b/App/strategies/balancedaynight.py new file mode 100644 index 0000000..9e1ac1b --- /dev/null +++ b/App/strategies/balancedaynight.py @@ -0,0 +1,42 @@ +from .strategy import * + + + +class BalanceDayNight(ScheduleStrategy): + + + def distribute_shifts(self, staff, shifts, week_start=None): + assignments = {} + + if not staff: + return Schedule(assignments) + + staff_ids = [get_staff_id(member) for member in staff] + for staff_id in staff_ids: + assignments[staff_id] = [] + + counts = {staff_id: {'day': 0, 'night': 0} for staff_id in staff_ids} + + for shift in shifts: + shift_type = get_shift_type(shift) + + def score(staff_id): + return (counts[staff_id].get(shift_type, 0), len(assignments[staff_id])) + + chosen_staff = min(staff_ids, key=score) + assignments[chosen_staff].append(shift) + counts[chosen_staff][shift_type] = counts[chosen_staff].get(shift_type, 0) + 1 + + + return Schedule(assignments) + +""" +This strategy uses a greedy algorithm to balance the number of day and night shifts assigned to each staff member. +It first determins whether the shift is a day or night shift using the get_shift_type function. +It calculates a score for each staff member based on how many shifts of that type they already have assigned, as well as their total number of assigned shifts. +The staff member with the lowest score is chosen to receive the shift, helping to ensure an even distribution of day and night shifts among all staff members. + +e.g if s1 has 2 day shifts and s2 has 1, the next day shift will go to s2 to balance it out. + +- VR. +""" \ No newline at end of file diff --git a/App/strategies/evendistribution.py b/App/strategies/evendistribution.py new file mode 100644 index 0000000..276f430 --- /dev/null +++ b/App/strategies/evendistribution.py @@ -0,0 +1,28 @@ +from .strategy import * + + + +class EvenDistribution(ScheduleStrategy): + + def distribute_shifts(self, staff, shifts, week_start=None): + assignments = {} + + if not staff: + return Schedule(assignments) + + + staff_ids = [get_staff_id(member) for member in staff] + for staff_id in staff_ids: + assignments[staff_id] = [] + + i = 0 + num_staff = len(staff_ids) + + for shift in shifts: + staff_id = staff_ids[i % num_staff] + assignments[staff_id].append(shift) + i += 1 + + return Schedule(assignments) + +# This use an even distribution, a round robin approach, to assign shifts to staff members in order. - VR \ No newline at end of file diff --git a/App/strategies/minimizedays.py b/App/strategies/minimizedays.py new file mode 100644 index 0000000..5092df2 --- /dev/null +++ b/App/strategies/minimizedays.py @@ -0,0 +1,50 @@ +from .strategy import * + +class MinimizeDays(ScheduleStrategy): + + + def distribute_shifts(self, staff, shifts, week_start=None): + assignments = {} + + if not staff: + return Schedule(assignments) + + staff_ids = [get_staff_id(member) for member in staff] + + for staff_id in staff_ids: + assignments[staff_id] = [] + + days = {staff_id: set() for staff_id in staff_ids} + + for shift in shifts: + shift_day = get_shift_day(shift) + + chosen = None + + for staff_id in staff_ids: + if shift_day in days[staff_id]: + chosen = staff_id + break + + if chosen is None: + chosen = min(staff_ids, key = lambda x: (len(days[x]), len(assignments[x]))) + + assignments[chosen].append(shift) + if shift_day is not None: + days[chosen].add(shift_day) + + + return Schedule(assignments) + + +""" +This strategy as the name suggests aims to reduce the number of distinct days that each staff members comes in to work. +When a new shift is to be assigned, it first checks if there is any staff member who is already scheduled to work on that day. +If such a staff member is found, the shift is assigned to them, so that they can work multiple shifts on the same day and thus minimize the total number of days they need to come in. +If no staff member is already scheduled for that day, the strategy selects the staff member who currently has the fewest distinct working days. +If there is a tie, it further breaks the tie by choosing the staff member with the fewest total assigned shifts. +This gives the staff more complete days off by goruping all their shifts into fewer days instead of spreading them out. +- VR. + + +""" diff --git a/App/strategies/strategy.py b/App/strategies/strategy.py new file mode 100644 index 0000000..c166531 --- /dev/null +++ b/App/strategies/strategy.py @@ -0,0 +1,110 @@ +from abc import ABC, abstractmethod + +class Schedule: + def __init__(self, assignments): + if assignments is not None: + self.assignments = assignments + else: + self.assignments = {} + + def to_dict(self): + out = {} + for shiftID, shifts in self.assignments.items(): + out[shiftID] = [] + for item in shifts: + if isinstance(item, dict): + out[shiftID].append(item) + elif hasattr(item, "get_json"): + out[shiftID].append(item.get_json()) + else: + out[shiftID].append(str(item)) + return out + +class ScheduleStrategy(ABC): + @abstractmethod + def distribute_shifts(self, staff, shifts, week_start=None): + raise NotImplementedError("distribute_shifts must be implemented by subclasses") + + +def get_staff_id(staff_member): + if staff_member is None: + raise ValueError("Staff member cannot be None") + + if isinstance(staff_member, dict): + if "id" in staff_member and staff_member["id"] is not None: + return str(staff_member["id"]) + else: + val = getattr(staff_member, "id", None) + if val is not None: + return str(val) + + raise ValueError("Unable to determine staff member ID") + + +def get_shift_day(shift): + if shift is None: + return None + + if isinstance(shift, dict): + st = shift.get("start_time") + else: + st = getattr(shift, "start_time", None) + + if st is not None: + if hasattr(st, "date"): + return st.date() + if hasattr(st, "strftime"): + return st.strftime("%Y-%m-%d") + if isinstance(st, str): + return st.split("T")[0] + + return None + + +def get_shift_type(shift): + if shift is None: + return "day" + + if isinstance(shift, dict): + startTime = shift.get("start_time") + else: + startTime = getattr(shift, "start_time", None) + + if startTime is not None: + if hasattr(startTime, "hour"): + hour = startTime.hour + if (hour >= 18 or hour < 6): + return "night" + else: + return "day" + + if isinstance(startTime, str): + try: + if "T" in startTime: + timePart = startTime.split("T")[1] + hour = int(timePart.split(":")[0]) + else: + hour = int(startTime.split(":")[0]) + if (hour >= 18 or hour < 6): + return "night" + else: + return "day" + + except Exception: + return "day" + + return "day" + + +def get_shift_id(shift): + if shift is None: + return None + + if isinstance(shift, dict): + if "id" in shift and shift["id"] is not None: + return shift["id"] + else: + val = getattr(shift, "id", None) + if val is not None: + return val + return None \ No newline at end of file From 4a9075db7c52b58f6deafe9d56a9e7b576a948c8 Mon Sep 17 00:00:00 2001 From: VisheshRampersad Date: Sat, 22 Nov 2025 23:20:40 +0000 Subject: [PATCH 2/3] auto scheduler controller --- App/controllers/scheduler.py | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 App/controllers/scheduler.py diff --git a/App/controllers/scheduler.py b/App/controllers/scheduler.py new file mode 100644 index 0000000..2552f66 --- /dev/null +++ b/App/controllers/scheduler.py @@ -0,0 +1,22 @@ +from App.models import Staff, Shift +from App.controllers.user import get_user +from App.strategies.evendistribution import EvenDistribution +from App.strategies.balancedaynight import BalanceDayNight +from App.strategies.minimizedays import MinimizeDays + +STRATEGIES = { "even": EvenDistribution, "balance_day_night": BalanceDayNight, "minimize_days": MinimizeDays } + +def auto_generate_schedule(admin_id, strategy_name="even"): + admin = get_user(admin_id) + if admin.role != "admin": + raise PermissionError("Only admins can generate schedules") + + strategy_class = STRATEGIES.get(strategy_name) + if not strategy_class: + raise ValueError(f"Invalid strategy '{strategy_name}'. Valid strategies are: {list(STRATEGIES.keys())}") + + strategy = strategy_class() + staff_list = Staff.query.all() + shifts = Shift.query.all() + + return strategy.distribute_shifts(staff_list, shifts) From 8d9ace9656de8fcee945c5de0f989fe2666eff3a Mon Sep 17 00:00:00 2001 From: VisheshRampersad Date: Sun, 23 Nov 2025 04:16:56 +0000 Subject: [PATCH 3/3] Fixed strategy pattern to reflect UML diagram --- App/controllers/scheduler.py | 41 ++++++---- App/models/schedule.py | 33 +++++--- App/strategies/__init__.py | 11 +-- App/strategies/balancedaynight.py | 34 ++++++-- App/strategies/evendistribution.py | 15 ++-- App/strategies/minimizedays.py | 29 +++++-- App/strategies/schedule_generator.py | 44 +++++++++++ App/strategies/scheduling_strategy.py | 6 ++ App/strategies/strategy.py | 110 -------------------------- 9 files changed, 161 insertions(+), 162 deletions(-) create mode 100644 App/strategies/schedule_generator.py create mode 100644 App/strategies/scheduling_strategy.py delete mode 100644 App/strategies/strategy.py diff --git a/App/controllers/scheduler.py b/App/controllers/scheduler.py index 2552f66..ed32507 100644 --- a/App/controllers/scheduler.py +++ b/App/controllers/scheduler.py @@ -1,22 +1,29 @@ from App.models import Staff, Shift -from App.controllers.user import get_user -from App.strategies.evendistribution import EvenDistribution -from App.strategies.balancedaynight import BalanceDayNight -from App.strategies.minimizedays import MinimizeDays -STRATEGIES = { "even": EvenDistribution, "balance_day_night": BalanceDayNight, "minimize_days": MinimizeDays } +from App.strategies.schedule_generator import ScheduleGenerator +from App.strategies.evendistribution import EvenDistributionStrategy +from App.strategies.balancedaynight import BalanceDayNightStrategy +from App.strategies.minimizedays import MinimizeDaysStrategy -def auto_generate_schedule(admin_id, strategy_name="even"): - admin = get_user(admin_id) - if admin.role != "admin": - raise PermissionError("Only admins can generate schedules") - - strategy_class = STRATEGIES.get(strategy_name) - if not strategy_class: - raise ValueError(f"Invalid strategy '{strategy_name}'. Valid strategies are: {list(STRATEGIES.keys())}") - - strategy = strategy_class() + + + +def auto_generate_schedule(strategy_name="even", week_start=None): staff_list = Staff.query.all() - shifts = Shift.query.all() - return strategy.distribute_shifts(staff_list, shifts) + if not staff_list: + raise ValueError("No staff members available for scheduling") + + generator = ScheduleGenerator() + generator.setStaffList(staff_list) + + if strategy_name == "even": + generator.setStrategy(EvenDistributionStrategy()) + elif strategy_name == "balance_day_night": + generator.setStrategy(BalanceDayNightStrategy()) + elif strategy_name == "minimize_days": + generator.setStrategy(MinimizeDaysStrategy()) + else: + raise ValueError(f"Unknown strategy name: {strategy_name}") + + return generator.generateSchedule(week_start) diff --git a/App/models/schedule.py b/App/models/schedule.py index 64c0e24..4721595 100644 --- a/App/models/schedule.py +++ b/App/models/schedule.py @@ -1,23 +1,38 @@ from datetime import datetime from App.database import db +#updated to match UML class diagram + class Schedule(db.Model): id = db.Column(db.Integer, primary_key=True) - name = db.Column(db.String(50), nullable=False) - created_at = db.Column(db.DateTime, default=datetime.utcnow) - created_by = db.Column(db.Integer, db.ForeignKey("user.id"), nullable=False) + weekStart = db.Column(db.Date, nullable=True) shifts = db.relationship("Shift", backref="schedule", lazy=True) - def shift_count(self): - return len(self.shifts) + def get_all_shifts(self): + return self.shifts + + def get_shifts_by_staff(self, staff): + return [shift for shift in self.shifts if shift.staff_id == staff.id] + + + def add_shift(self, shift): + shift.schedule_id = self.id + self.shifts.append(shift) + + def validate_schedule(self): + if not self.shifts: + return False + for shift in self.shifts: + if shift.staff_id is None: + return False + return True + def get_json(self): + return { "id": self.id, - "name": self.name, - "created_at": self.created_at.isoformat(), - "created_by": self.created_by, - "shift_count": self.shift_count(), + "weekStart": self.weekStart.strftime("%Y-%m-%d") if self.weekStart else None, "shifts": [shift.get_json() for shift in self.shifts] } diff --git a/App/strategies/__init__.py b/App/strategies/__init__.py index 1dbf826..0bcf862 100644 --- a/App/strategies/__init__.py +++ b/App/strategies/__init__.py @@ -1,6 +1,7 @@ -from .strategy import Schedule, ScheduleStrategy, get_staff_id, get_shift_id, get_shift_day, get_shift_type -from .evendistribution import EvenDistribution -from .balancedaynight import BalanceDayNight -from .minimizedays import MinimizeDays +from .scheduling_strategy import SchedulingStrategy +from .schedule_generator import ScheduleGenerator +from .evendistribution import EvenDistributionStrategy +from .balancedaynight import BalanceDayNightStrategy +from .minimizedays import MinimizeDaysStrategy -__all__ = ["Schedule", "ScheduleStrategy", "get_staff_id", "get_shift_id", "get_shift_day", "get_shift_type", "EvenDistribution", "BalanceDayNight", "MinimizeDays"] \ No newline at end of file +__all__ = ["SchedulingStrategy", "ScheduleGenerator","EvenDistributionStrategy", "MinimizeDaysStrategy", "BalanceDayNightStrategy"] \ No newline at end of file diff --git a/App/strategies/balancedaynight.py b/App/strategies/balancedaynight.py index 9e1ac1b..b854e35 100644 --- a/App/strategies/balancedaynight.py +++ b/App/strategies/balancedaynight.py @@ -1,17 +1,37 @@ -from .strategy import * +from .scheduling_strategy import SchedulingStrategy -class BalanceDayNight(ScheduleStrategy): +# again this function was moved to here as it is the only strategy that uses it. +def get_shift_type(shift): + if shift is None: + return "day" + + startTime = getattr(shift, "start_time", None) + + if startTime is not None: + if hasattr(startTime, "hour"): + hour = startTime.hour + if hour >= 18 or hour < 6: + return "night" + else: + return "day" + + return "day" - def distribute_shifts(self, staff, shifts, week_start=None): + +class BalanceDayNightStrategy(SchedulingStrategy): + + + def distribute(self, staff_list, shifts, week_start=None): assignments = {} - if not staff: - return Schedule(assignments) + if not staff_list: + return assignments - staff_ids = [get_staff_id(member) for member in staff] + staff_ids = [str(staffMember.id) for staffMember in staff_list] + for staff_id in staff_ids: assignments[staff_id] = [] @@ -28,7 +48,7 @@ def score(staff_id): counts[chosen_staff][shift_type] = counts[chosen_staff].get(shift_type, 0) + 1 - return Schedule(assignments) + return assignments """ This strategy uses a greedy algorithm to balance the number of day and night shifts assigned to each staff member. diff --git a/App/strategies/evendistribution.py b/App/strategies/evendistribution.py index 276f430..7fefc7e 100644 --- a/App/strategies/evendistribution.py +++ b/App/strategies/evendistribution.py @@ -1,17 +1,18 @@ -from .strategy import * +from .scheduling_strategy import SchedulingStrategy -class EvenDistribution(ScheduleStrategy): +class EvenDistributionStrategy(SchedulingStrategy): - def distribute_shifts(self, staff, shifts, week_start=None): + def distribute(self, staff_list, shifts, week_start=None): assignments = {} - if not staff: - return Schedule(assignments) + if not staff_list: + return assignments - staff_ids = [get_staff_id(member) for member in staff] + staff_ids = [str(staffMember.id) for staffMember in staff_list] + for staff_id in staff_ids: assignments[staff_id] = [] @@ -23,6 +24,6 @@ def distribute_shifts(self, staff, shifts, week_start=None): assignments[staff_id].append(shift) i += 1 - return Schedule(assignments) + return assignments # This use an even distribution, a round robin approach, to assign shifts to staff members in order. - VR \ No newline at end of file diff --git a/App/strategies/minimizedays.py b/App/strategies/minimizedays.py index 5092df2..485728f 100644 --- a/App/strategies/minimizedays.py +++ b/App/strategies/minimizedays.py @@ -1,15 +1,30 @@ -from .strategy import * +from .scheduling_strategy import SchedulingStrategy -class MinimizeDays(ScheduleStrategy): +#this method was relocated here as it is only used by this strategy - def distribute_shifts(self, staff, shifts, week_start=None): +def get_shift_day(shift): + if shift is None: + return None + + startTime = getattr(shift, "start_time", None) + + if startTime is not None: + if hasattr(startTime, "date"): + return startTime.date() + return None + + +class MinimizeDaysStrategy(SchedulingStrategy): + + + def distribute(self, staff_list, shifts, week_start=None): assignments = {} - if not staff: - return Schedule(assignments) + if not staff_list: + return assignments - staff_ids = [get_staff_id(member) for member in staff] + staff_ids = [str(staffMember.id) for staffMember in staff_list] for staff_id in staff_ids: assignments[staff_id] = [] @@ -34,7 +49,7 @@ def distribute_shifts(self, staff, shifts, week_start=None): days[chosen].add(shift_day) - return Schedule(assignments) + return assignments """ diff --git a/App/strategies/schedule_generator.py b/App/strategies/schedule_generator.py new file mode 100644 index 0000000..bd6311c --- /dev/null +++ b/App/strategies/schedule_generator.py @@ -0,0 +1,44 @@ +from App.models import Schedule, Staff, Shift +from App.database import db + + + +class ScheduleGenerator: + def __init__(self): + self.strategy = None + self.staffList = [] + + def setStrategy(self, strategy): + self.strategy = strategy + + def setStaffList(self, staffList): + self.staffList = staffList + + def generateSchedule(self, week_start=None): + if self.strategy is None: + raise ValueError("No scheduling strategy set") + + if not self.staffList: + raise ValueError("Staff list is empty") + + unassigned_shifts = Shift.query.filter_by(staff_id = None).all() + + if not unassigned_shifts: + raise ValueError("No unassigned shifts available for scheduling") + + assignments = self.strategy.distribute(self.staffList, unassigned_shifts, week_start) + + new_schedule = Schedule(weekStart=week_start) + + db.session.add(new_schedule) + db.session.flush() + + for staff_id, shifts in assignments.items(): + for shift in shifts: + shift.staff_id = int(staff_id) + shift.schedule_id = new_schedule.id + + db.session.commit() + + return new_schedule + diff --git a/App/strategies/scheduling_strategy.py b/App/strategies/scheduling_strategy.py new file mode 100644 index 0000000..4b78615 --- /dev/null +++ b/App/strategies/scheduling_strategy.py @@ -0,0 +1,6 @@ +from abc import ABC, abstractmethod + +class SchedulingStrategy(ABC): + @abstractmethod + def distribute(self, staff, shifts, week_start=None): + raise NotImplementedError("distribute must be implemented by subclasses") \ No newline at end of file diff --git a/App/strategies/strategy.py b/App/strategies/strategy.py deleted file mode 100644 index c166531..0000000 --- a/App/strategies/strategy.py +++ /dev/null @@ -1,110 +0,0 @@ -from abc import ABC, abstractmethod - -class Schedule: - def __init__(self, assignments): - if assignments is not None: - self.assignments = assignments - else: - self.assignments = {} - - def to_dict(self): - out = {} - for shiftID, shifts in self.assignments.items(): - out[shiftID] = [] - for item in shifts: - if isinstance(item, dict): - out[shiftID].append(item) - elif hasattr(item, "get_json"): - out[shiftID].append(item.get_json()) - else: - out[shiftID].append(str(item)) - return out - -class ScheduleStrategy(ABC): - @abstractmethod - def distribute_shifts(self, staff, shifts, week_start=None): - raise NotImplementedError("distribute_shifts must be implemented by subclasses") - - -def get_staff_id(staff_member): - if staff_member is None: - raise ValueError("Staff member cannot be None") - - if isinstance(staff_member, dict): - if "id" in staff_member and staff_member["id"] is not None: - return str(staff_member["id"]) - else: - val = getattr(staff_member, "id", None) - if val is not None: - return str(val) - - raise ValueError("Unable to determine staff member ID") - - -def get_shift_day(shift): - if shift is None: - return None - - if isinstance(shift, dict): - st = shift.get("start_time") - else: - st = getattr(shift, "start_time", None) - - if st is not None: - if hasattr(st, "date"): - return st.date() - if hasattr(st, "strftime"): - return st.strftime("%Y-%m-%d") - if isinstance(st, str): - return st.split("T")[0] - - return None - - -def get_shift_type(shift): - if shift is None: - return "day" - - if isinstance(shift, dict): - startTime = shift.get("start_time") - else: - startTime = getattr(shift, "start_time", None) - - if startTime is not None: - if hasattr(startTime, "hour"): - hour = startTime.hour - if (hour >= 18 or hour < 6): - return "night" - else: - return "day" - - if isinstance(startTime, str): - try: - if "T" in startTime: - timePart = startTime.split("T")[1] - hour = int(timePart.split(":")[0]) - else: - hour = int(startTime.split(":")[0]) - if (hour >= 18 or hour < 6): - return "night" - else: - return "day" - - except Exception: - return "day" - - return "day" - - -def get_shift_id(shift): - if shift is None: - return None - - if isinstance(shift, dict): - if "id" in shift and shift["id"] is not None: - return shift["id"] - else: - val = getattr(shift, "id", None) - if val is not None: - return val - return None \ No newline at end of file