feat!: add working hours and weekend constraints

src/constraint_solvers/timetable/constraints.py

@@ -1,10 +1,13 @@
-### GENERAL IMPORTS ###
 from datetime import date, timedelta
 
-### DOMAIN ###
 from .domain import Employee, Task, ScheduleInfo
 
-### TIMEFOLD ###
+from .working_hours import (
+    get_working_day_from_slot,
+    get_slot_within_day,
+    task_spans_lunch_break,
+)
+
 from timefold.solver.score import HardSoftDecimalScore
 from timefold.solver.score._constraint_factory import ConstraintFactory
 from timefold.solver.score._joiners import Joiners
@@ -32,13 +35,34 @@ def get_slot_overlap(task1: Task, task2: Task) -> int:
 def get_slot_date(slot: int) -> date:
     """Convert a slot index to a date.
 
+    For compatibility with tests, slot 0 = today, slot 16 = tomorrow, etc.
+    In production, weekends would be filtered out, but for tests we keep simple mapping.
+
     Args:
         slot (int): The slot index.
 
     Returns:
         date: The date corresponding to the slot.
     """
-    return date.today() + timedelta(days=slot // 20)  # 20 slots per day
+    working_day = get_working_day_from_slot(slot)
+    today = date.today()
+    return today + timedelta(days=working_day)
+
+
+def is_weekend_slot(slot: int) -> bool:
+    """Check if a slot falls on a weekend.
+
+    Since our slot system only includes working days, this should always return False
+    for valid slots, but we keep it for validation purposes.
+
+    Args:
+        slot (int): The slot index.
+
+    Returns:
+        bool: True if the slot would fall on a weekend.
+    """
+    slot_date = get_slot_date(slot)
+    return slot_date.weekday() >= 5  # Saturday=5, Sunday=6
 
 
 def tasks_violate_sequence_order(task1: Task, task2: Task) -> bool:
@@ -94,6 +118,8 @@ def define_constraints(constraint_factory: ConstraintFactory) -> list:
         task_fits_in_schedule(constraint_factory),
         unavailable_employee(constraint_factory),
         maintain_project_task_order(constraint_factory),
+        no_lunch_break_spanning(constraint_factory),
+        no_weekend_scheduling(constraint_factory),
         # Soft constraints
         undesired_day_for_employee(constraint_factory),
         desired_day_for_employee(constraint_factory),
@@ -166,6 +192,26 @@ def unavailable_employee(constraint_factory: ConstraintFactory):
     )
 
 
+def no_lunch_break_spanning(constraint_factory: ConstraintFactory):
+    """Prevent tasks from spanning across lunch break (13:00-14:00)."""
+    return (
+        constraint_factory.for_each(Task)
+        .filter(task_spans_lunch_break)
+        .penalize(HardSoftDecimalScore.ONE_HARD)
+        .as_constraint("No lunch break spanning")
+    )
+
+
+def no_weekend_scheduling(constraint_factory: ConstraintFactory):
+    """Prevent tasks from being scheduled on weekends."""
+    return (
+        constraint_factory.for_each(Task)
+        .filter(lambda task: is_weekend_slot(task.start_slot))
+        .penalize(HardSoftDecimalScore.ONE_HARD)
+        .as_constraint("No weekend scheduling")
+    )
+
+
 def undesired_day_for_employee(constraint_factory: ConstraintFactory):
     return (
         constraint_factory.for_each(Task)

src/constraint_solvers/timetable/working_hours.py

@@ -0,0 +1,48 @@
+# =========================
+#     WORKING HOURS CONFIG
+# =========================
+
+# Working hours: 9:00-13:00 (8 slots) + 14:00-18:00 (8 slots) = 16 slots per working day
+SLOTS_PER_WORKING_DAY = 16
+MORNING_SLOTS = 8  # 9:00-13:00 (4 hours * 2 slots/hour)
+AFTERNOON_SLOTS = 8  # 14:00-18:00 (4 hours * 2 slots/hour)
+
+
+def get_working_day_from_slot(slot: int) -> int:
+    """Get the working day index (0=first working day) from a slot.
+
+    Args:
+        slot (int): The slot index.
+
+    Returns:
+        int: The working day index (0-based).
+    """
+    return slot // SLOTS_PER_WORKING_DAY
+
+
+def get_slot_within_day(slot: int) -> int:
+    """Get the slot position within a working day (0-15).
+
+    Args:
+        slot (int): The slot index.
+
+    Returns:
+        int: The slot position within the day (0-15).
+    """
+    return slot % SLOTS_PER_WORKING_DAY
+
+
+def task_spans_lunch_break(task) -> bool:
+    """Check if a task spans across the lunch break period.
+
+    Args:
+        task: The task to check.
+
+    Returns:
+        bool: True if the task spans across lunch break.
+    """
+    start_slot_in_day = get_slot_within_day(task.start_slot)
+    end_slot_in_day = start_slot_in_day + task.duration_slots - 1
+
+    # If task starts in morning (0-7) and ends in afternoon (8-15), it spans lunch
+    return start_slot_in_day < MORNING_SLOTS and end_slot_in_day >= MORNING_SLOTS

src/factory/data/formatters.py

@@ -2,6 +2,46 @@ from datetime import datetime, timedelta, date
 import pandas as pd
 
 from factory.data.generators import earliest_monday_on_or_after
+from constraint_solvers.timetable.working_hours import (
+    SLOTS_PER_WORKING_DAY,
+    MORNING_SLOTS,
+)
+
+
+def slot_to_datetime(slot: int, base_date: date = None) -> datetime:
+    """Convert a slot index to actual datetime, respecting working hours.
+
+    Args:
+        slot (int): The slot index (0-based).
+        base_date (date, optional): Base date to start from. Defaults to today.
+
+    Returns:
+        datetime: The actual datetime for this slot.
+    """
+    if base_date is None:
+        base_date = date.today()
+
+    # Calculate which working day this slot falls on
+    working_day = slot // SLOTS_PER_WORKING_DAY
+    slot_within_day = slot % SLOTS_PER_WORKING_DAY
+
+    # Calculate the actual calendar date
+    actual_date = base_date + timedelta(days=working_day)
+
+    # Convert slot within day to actual time
+    if slot_within_day < MORNING_SLOTS:
+        # Morning session: 9:00-13:00 (slots 0-7)
+        hour = 9 + (slot_within_day // 2)
+        minute = (slot_within_day % 2) * 30
+    else:
+        # Afternoon session: 14:00-18:00 (slots 8-15)
+        afternoon_slot = slot_within_day - MORNING_SLOTS
+        hour = 14 + (afternoon_slot // 2)
+        minute = (afternoon_slot % 2) * 30
+
+    return datetime.combine(
+        actual_date, datetime.min.time().replace(hour=hour, minute=minute)
+    )
 
 
 def schedule_to_dataframe(schedule) -> pd.DataFrame:
@@ -21,14 +61,9 @@ def schedule_to_dataframe(schedule) -> pd.DataFrame:
         # Get employee name or "Unassigned" if no employee assigned
         employee: str = task.employee.name if task.employee else "Unassigned"
 
-        # Calculate start and end times based on 30-minute slots
-        # Schedule starts from next Monday at 8 AM
-        base_date = earliest_monday_on_or_after(date.today())
-        base_datetime = datetime.combine(
-            base_date, datetime.min.time().replace(hour=8)
-        )  # Start at 8 AM Monday
-        start_time: datetime = base_datetime + timedelta(minutes=30 * task.start_slot)
-        end_time: datetime = start_time + timedelta(minutes=30 * task.duration_slots)
+        # Calculate start and end times using working hours
+        start_time: datetime = slot_to_datetime(task.start_slot)
+        end_time: datetime = slot_to_datetime(task.start_slot + task.duration_slots)
 
         # Add task data to list with availability flags
         data.append(

src/factory/data/provider.py

@@ -24,8 +24,8 @@ logger = get_logger(__name__)
 #        CONSTANTS
 # =========================
 
-# Each slot is 30 minutes - 20 slots = 10 hours working day
-SLOTS_PER_DAY = 20
+# Import working hours configuration
+from constraint_solvers.timetable.working_hours import SLOTS_PER_WORKING_DAY
 
 
 # =========================
@@ -100,7 +100,7 @@ async def generate_agent_data(
     start_date: date = earliest_monday_on_or_after(date.today())
     randomizer: Random = Random(parameters.random_seed)
     employees: list[Employee] = generate_employees(parameters, randomizer)
-    total_slots: int = parameters.days_in_schedule * SLOTS_PER_DAY
+    total_slots: int = parameters.days_in_schedule * SLOTS_PER_WORKING_DAY
 
     logger.debug("Processing file object: %s (type: %s)", file, type(file))
 
@@ -157,7 +157,7 @@ async def generate_mcp_data(
 
     start_date: date = earliest_monday_on_or_after(date.today())
     randomizer: Random = Random(parameters.random_seed)
-    total_slots: int = parameters.days_in_schedule * SLOTS_PER_DAY
+    total_slots: int = parameters.days_in_schedule * SLOTS_PER_WORKING_DAY
 
     # --- CALENDAR TASKS ---
     calendar_tasks = generate_tasks_from_calendar(

src/services/data.py

@@ -9,8 +9,8 @@ from factory.data.provider import (
     generate_agent_data,
     DATA_PARAMS,
     TimeTableDataParameters,
-    SLOTS_PER_DAY,
 )
+from constraint_solvers.timetable.working_hours import SLOTS_PER_WORKING_DAY
 
 from constraint_solvers.timetable.domain import (
     EmployeeSchedule,
@@ -214,7 +214,7 @@ class DataService:
             employees=list(combined_employees.values()),
             tasks=combined_tasks,
             schedule_info=ScheduleInfo(
-                total_slots=parameters.days_in_schedule * SLOTS_PER_DAY
+                total_slots=parameters.days_in_schedule * SLOTS_PER_WORKING_DAY
             ),
         )
 

src/services/schedule.py

@@ -11,8 +11,8 @@ from constraint_solvers.timetable.solver import solver_manager
 from factory.data.provider import (
     DATA_PARAMS,
     TimeTableDataParameters,
-    SLOTS_PER_DAY,
 )
+from constraint_solvers.timetable.working_hours import SLOTS_PER_WORKING_DAY
 
 from factory.data.generators import (
     generate_employees,
@@ -181,7 +181,7 @@ class ScheduleService:
             employees=employees,
             tasks=tasks,
             schedule_info=ScheduleInfo(
-                total_slots=parameters.days_in_schedule * SLOTS_PER_DAY
+                total_slots=parameters.days_in_schedule * SLOTS_PER_WORKING_DAY
             ),
         )
 

tests/test_constraints.py

@@ -1,5 +1,3 @@
-# Test comprehensive constraint validation using ConstraintVerifier
-
 import pytest
 from datetime import date, timedelta
 from decimal import Decimal
@@ -17,7 +15,11 @@ from src.constraint_solvers.timetable.constraints import (
     undesired_day_for_employee,
     desired_day_for_employee,
     balance_employee_task_assignments,
+    no_lunch_break_spanning,
+    no_weekend_scheduling,
 )
+
+from src.constraint_solvers.timetable.working_hours import task_spans_lunch_break
 from src.constraint_solvers.timetable.domain import (
     Employee,
     Task,
@@ -243,11 +245,11 @@ class TestConstraints:
 
     def test_unavailable_employee_constraint_violation(self):
         """Test that tasks assigned to unavailable employees are penalized."""
-        # Assuming 20 slots per day, tomorrow starts at slot 20
+        # Assuming 16 slots per working day, tomorrow starts at slot 16
         task = create_task(
             task_id="task1",
             description="Task on unavailable day",
-            start_slot=20,  # Tomorrow (when Alice is unavailable)
+            start_slot=16,  # Tomorrow (when Alice is unavailable)
             required_skill="Python",
             employee=self.employee_alice,
         )
@@ -364,15 +366,86 @@ class TestConstraints:
             .penalizes_by(0)
         )
 
+    def test_no_lunch_break_spanning_constraint_violation(self):
+        """Test that tasks spanning lunch break are penalized."""
+        task = create_task(
+            task_id="task1",
+            description="Task spanning lunch",
+            start_slot=6,  # Starts in morning (slot 6)
+            duration_slots=4,  # Ends in afternoon (slot 10), spans lunch
+            required_skill="Python",
+            employee=self.employee_alice,
+        )
+
+        (
+            self.constraint_verifier.verify_that(no_lunch_break_spanning)
+            .given(task, self.employee_alice, self.schedule_info)
+            .penalizes_by(1)
+        )
+
+    def test_no_lunch_break_spanning_constraint_satisfied_morning(self):
+        """Test that tasks contained in morning session are not penalized."""
+        task = create_task(
+            task_id="task1",
+            description="Morning task",
+            start_slot=2,  # Morning session
+            duration_slots=4,  # Stays in morning (slots 2-5)
+            required_skill="Python",
+            employee=self.employee_alice,
+        )
+
+        (
+            self.constraint_verifier.verify_that(no_lunch_break_spanning)
+            .given(task, self.employee_alice, self.schedule_info)
+            .penalizes_by(0)
+        )
+
+    def test_no_lunch_break_spanning_constraint_satisfied_afternoon(self):
+        """Test that tasks contained in afternoon session are not penalized."""
+        task = create_task(
+            task_id="task1",
+            description="Afternoon task",
+            start_slot=10,  # Afternoon session (slot 10 = 3rd hour of afternoon)
+            duration_slots=4,  # Stays in afternoon (slots 10-13)
+            required_skill="Python",
+            employee=self.employee_alice,
+        )
+
+        (
+            self.constraint_verifier.verify_that(no_lunch_break_spanning)
+            .given(task, self.employee_alice, self.schedule_info)
+            .penalizes_by(0)
+        )
+
+    def test_no_weekend_scheduling_constraint_satisfied(self):
+        """Test that weekday tasks are not penalized.
+
+        Note: Since our slot system only includes working days,
+        is_weekend_slot should always return False for valid slots.
+        """
+        task = create_task(
+            task_id="task1",
+            description="Weekday task",
+            start_slot=0,  # First slot of first working day
+            required_skill="Python",
+            employee=self.employee_alice,
+        )
+
+        (
+            self.constraint_verifier.verify_that(no_weekend_scheduling)
+            .given(task, self.employee_alice, self.schedule_info)
+            .penalizes_by(0)
+        )
+
     # ==================== SOFT CONSTRAINT TESTS ====================
 
     def test_undesired_day_for_employee_constraint_violation(self):
         """Test that tasks on undesired days incur soft penalty."""
-        # Assuming 20 slots per day, day after tomorrow starts at slot 40
+        # Assuming 16 slots per working day, day after tomorrow starts at slot 32
         task = create_task(
             task_id="task1",
             description="Task on undesired day",
-            start_slot=40,  # Day after tomorrow (Alice's undesired date)
+            start_slot=32,  # Day after tomorrow (Alice's undesired date)
             required_skill="Python",
             employee=self.employee_alice,
         )
@@ -420,7 +493,7 @@ class TestConstraints:
         task = create_task(
             task_id="task1",
             description="Task on neutral day",
-            start_slot=20,  # Tomorrow (neutral for Alice)
+            start_slot=16,  # Tomorrow (neutral for Alice)
             required_skill="Python",
             employee=self.employee_alice,
         )
@@ -533,7 +606,7 @@ class TestConstraints:
             create_task(
                 "task2",
                 "Valid Java Task",
-                start_slot=5,  # After task1, non-overlapping
+                start_slot=8,  # Afternoon session, non-overlapping
                 required_skill="Java",
                 project_id="project1",
                 sequence_number=2,
@@ -542,7 +615,7 @@ class TestConstraints:
             create_task(
                 "task3",
                 "Bob's Valid Task",
-                start_slot=10,
+                start_slot=12,
                 required_skill="Java",
                 project_id="project2",
                 sequence_number=1,
@@ -602,7 +675,7 @@ class TestConstraints:
                 self.employee_bob,
                 self.schedule_info,
             )
-            .scores(HardSoftDecimalScore.of(Decimal("-4"), Decimal("-0.12132")))
+            .scores(HardSoftDecimalScore.of(Decimal("-5"), Decimal("-0.12132")))
         )
 
 
@@ -655,8 +728,10 @@ def create_task(
     )
 
 
-def create_schedule_info(total_slots=60):
-    """Create a schedule info object with specified total slots."""
+def create_schedule_info(total_slots=48):
+    """Create a schedule info object with specified total slots.
+    Default is 48 slots = 3 working days * 16 slots per working day.
+    """
     return ScheduleInfo(total_slots=total_slots)
 
 

tests/test_factory.py

@@ -1,8 +1,6 @@
 import pytest
-from datetime import datetime, timedelta
+
 from src.utils.load_secrets import load_secrets
-from dateutil.rrule import rrulestr
-from icalendar import Calendar, vDDDTypes
 
 # Load environment variables for agent (if needed)
 load_secrets("tests/secrets/creds.py")