feat!: add constraint analyzer service and refactor all systems

src/app.py

@@ -13,7 +13,7 @@ if not os.getenv("NEBIUS_API_KEY") or not os.getenv("NEBIUS_MODEL"):
     load_secrets("tests/secrets/creds.py")
 
 
-from handlers import (
+from handlers.web_backend import (
     load_data,
     show_solved,
     start_timer,
@@ -21,7 +21,7 @@ from handlers import (
     show_mock_project_content,
 )
 
-from mcp_handlers import process_message_and_attached_file
+from handlers.mcp_backend import process_message_and_attached_file
 
 from services import MockProjectService
 

src/constraint_solvers/timetable/__init__.py

@@ -0,0 +1,52 @@
+"""
+Timetable constraint solver module.
+
+This module contains the domain models, constraints, and solver logic
+for employee scheduling optimization.
+"""
+
+try:
+    from .domain import (
+        Employee,
+        Task,
+        EmployeeSchedule,
+        ScheduleInfo,
+    )
+    from .solver import solver_manager, solution_manager
+    from .constraints import (
+        get_slot_overlap,
+        get_slot_date,
+        tasks_violate_sequence_order,
+        define_constraints,
+    )
+
+    _TIMEFOLD_AVAILABLE = True
+except ImportError as e:
+    # Handle missing timefold dependency gracefully
+    _TIMEFOLD_AVAILABLE = False
+    Employee = None
+    Task = None
+    EmployeeSchedule = None
+    ScheduleInfo = None
+    solver_manager = None
+    solution_manager = None
+    get_slot_overlap = None
+    get_slot_date = None
+    tasks_violate_sequence_order = None
+    define_constraints = None
+
+__all__ = [
+    # Domain models
+    "Employee",
+    "Task",
+    "EmployeeSchedule",
+    "ScheduleInfo",
+    # Solver managers
+    "solver_manager",
+    "solution_manager",
+    # Constraint functions
+    "get_slot_overlap",
+    "get_slot_date",
+    "tasks_violate_sequence_order",
+    "define_constraints",
+]

src/constraint_solvers/timetable/analysis/__init__.py

@@ -1,9 +0,0 @@
-"""
-Constraint violation analysis module.
-
-This module provides tools for analyzing constraint violations in Timefold solver results.
-"""
-
-from .violation_analyzer import ConstraintViolationAnalyzer
-
-__all__ = ["ConstraintViolationAnalyzer"]

src/constraint_solvers/timetable/analysis/violation_analyzer.py

@@ -1,185 +0,0 @@
-from typing import Dict, List, Set
-from ..domain import EmployeeSchedule, Task, Employee
-
-
-class ConstraintViolationAnalyzer:
-    """
-    Service for analyzing constraint violations in scheduling solutions.
-
-    This service implements automatic detection of infeasible scheduling problems.
-    When the Timefold solver cannot satisfy all hard constraints, it returns a
-    solution with a negative hard score. This service analyzes such solutions to
-    provide users with specific, actionable feedback about why their scheduling
-    problem cannot be solved.
-    """
-
-    @staticmethod
-    def analyze_constraint_violations(schedule: EmployeeSchedule) -> str:
-        """
-        Analyze constraint violations in a schedule and provide detailed feedback.
-
-        Args:
-            schedule: The schedule to analyze
-
-        Returns:
-            Detailed string describing constraint violations and suggestions
-        """
-        if not schedule.score or schedule.score.hard_score >= 0:
-            return "No constraint violations detected."
-
-        violations = []
-
-        # Check for missing skills
-        skill_violations = ConstraintViolationAnalyzer._check_skill_violations(schedule)
-        if skill_violations:
-            violations.extend(skill_violations)
-
-        # Check for insufficient time
-        time_violations = ConstraintViolationAnalyzer._check_time_violations(schedule)
-        if time_violations:
-            violations.extend(time_violations)
-
-        # Check for availability conflicts
-        availability_violations = (
-            ConstraintViolationAnalyzer._check_availability_violations(schedule)
-        )
-        if availability_violations:
-            violations.extend(availability_violations)
-
-        # Check for sequencing issues
-        sequence_violations = ConstraintViolationAnalyzer._check_sequence_violations(
-            schedule
-        )
-        if sequence_violations:
-            violations.extend(sequence_violations)
-
-        if not violations:
-            violations.append("Unknown constraint violations detected.")
-
-        return "\n".join(violations)
-
-    @staticmethod
-    def _check_skill_violations(schedule: EmployeeSchedule) -> List[str]:
-        """Check for tasks that require skills not available in the employee pool"""
-        violations = []
-
-        # Get all available skills
-        available_skills: Set[str] = set()
-        for employee in schedule.employees:
-            available_skills.update(employee.skills)
-
-        # Check for tasks requiring unavailable skills
-        unassigned_tasks = [task for task in schedule.tasks if not task.employee]
-        missing_skills: Set[str] = set()
-
-        for task in unassigned_tasks:
-            if task.required_skill not in available_skills:
-                missing_skills.add(task.required_skill)
-
-        if missing_skills:
-            violations.append(
-                f"• Missing Skills: No employees have these required skills: {', '.join(sorted(missing_skills))}"
-            )
-
-        return violations
-
-    @staticmethod
-    def _check_time_violations(schedule: EmployeeSchedule) -> List[str]:
-        """Check for insufficient time to complete all tasks"""
-        violations = []
-
-        total_task_slots = sum(task.duration_slots for task in schedule.tasks)
-        total_available_slots = (
-            len(schedule.employees) * schedule.schedule_info.total_slots
-        )
-
-        if total_task_slots > total_available_slots:
-            total_task_hours = total_task_slots / 2  # Convert slots to hours
-            total_available_hours = total_available_slots / 2
-            violations.append(
-                f"• Insufficient Time: Tasks require {total_task_hours:.1f} hours total, "
-                f"but only {total_available_hours:.1f} hours available across all employees"
-            )
-
-        return violations
-
-    @staticmethod
-    def _check_availability_violations(schedule: EmployeeSchedule) -> List[str]:
-        """Check for tasks scheduled during employee unavailable periods"""
-        violations = []
-
-        for task in schedule.tasks:
-            if task.employee and hasattr(task.employee, "unavailable_dates"):
-                # This would need actual date calculation based on start_slot
-                # For now, we'll just note if there are unassigned tasks with availability constraints
-                pass
-
-        unassigned_count = len([task for task in schedule.tasks if not task.employee])
-        if unassigned_count > 0:
-            violations.append(
-                f"• Unassigned Tasks: {unassigned_count} task(s) could not be assigned to any employee"
-            )
-
-        return violations
-
-    @staticmethod
-    def _check_sequence_violations(schedule: EmployeeSchedule) -> List[str]:
-        """Check for project sequencing constraint violations"""
-        violations = []
-
-        # Group tasks by project
-        project_tasks: Dict[str, List[Task]] = {}
-        for task in schedule.tasks:
-            project_id = getattr(task, "project_id", "")
-            if project_id:
-                if project_id not in project_tasks:
-                    project_tasks[project_id] = []
-                project_tasks[project_id].append(task)
-
-        # Check sequencing within each project
-        for project_id, tasks in project_tasks.items():
-            if len(tasks) > 1:
-                # Sort by sequence number
-                sorted_tasks = sorted(
-                    tasks, key=lambda t: getattr(t, "sequence_number", 0)
-                )
-
-                # Check if tasks are assigned and properly sequenced
-                for i in range(len(sorted_tasks) - 1):
-                    current_task = sorted_tasks[i]
-                    next_task = sorted_tasks[i + 1]
-
-                    if not current_task.employee or not next_task.employee:
-                        continue  # Skip unassigned tasks
-
-                    # Check if next task starts after current task ends
-                    if next_task.start_slot < (
-                        current_task.start_slot + current_task.duration_slots
-                    ):
-                        violations.append(
-                            f"• Sequence Violation: In project '{project_id}', task sequence is violated"
-                        )
-                        break
-
-        return violations
-
-    @staticmethod
-    def generate_suggestions(schedule: EmployeeSchedule) -> List[str]:
-        """Generate actionable suggestions for fixing constraint violations"""
-        suggestions = []
-
-        if not schedule.score or schedule.score.hard_score >= 0:
-            return suggestions
-
-        # Basic suggestions based on common issues
-        suggestions.extend(
-            [
-                "Add more employees with required skills",
-                "Increase the scheduling time window (more days)",
-                "Reduce task requirements or durations",
-                "Check employee availability constraints",
-                "Review project sequencing requirements",
-            ]
-        )
-
-        return suggestions

src/constraint_solvers/timetable/domain.py

@@ -1,7 +1,8 @@
 from timefold.solver import SolverStatus
 from timefold.solver.domain import *
 from timefold.solver.score import HardSoftDecimalScore
-from datetime import datetime, date
+
+from datetime import date
 from typing import Annotated
 from dataclasses import dataclass, field
 

src/constraint_solvers/timetable/solver.py

@@ -2,8 +2,8 @@ from timefold.solver import SolverManager, SolverFactory, SolutionManager
 from timefold.solver.config import (
     SolverConfig,
     ScoreDirectorFactoryConfig,
-    TerminationConfig,
-    Duration,
+    # TerminationConfig,
+    # Duration,
 )
 
 from .domain import *

src/factory/__init__.py

@@ -0,0 +1,35 @@
+"""
+Factory module for data creation - both algorithmic and AI-powered.
+
+This module contains all data creation, generation, and formatting logic
+for the Yuga Planner scheduling system, organized into:
+- data: Algorithmic data generation and formatting
+- agents: AI-powered task composition
+"""
+
+# Import from data submodule
+from .data.formatters import schedule_to_dataframe, employees_to_dataframe
+from .data.generators import (
+    generate_employees,
+    generate_employee_availability,
+    earliest_monday_on_or_after,
+)
+from .data.provider import generate_agent_data, generate_mcp_data
+
+# Import from agents submodule
+from .agents.task_composer_agent import TaskComposerAgent
+
+__all__ = [
+    # Data formatters - convert domain objects to DataFrames
+    "schedule_to_dataframe",
+    "employees_to_dataframe",
+    # Data generators - create domain objects
+    "generate_employees",
+    "generate_employee_availability",
+    "earliest_monday_on_or_after",
+    # Data providers - orchestrate data creation
+    "generate_agent_data",
+    "generate_mcp_data",
+    # AI agents - intelligent task composition
+    "TaskComposerAgent",
+]

src/factory/agents/__init__.py

@@ -0,0 +1,26 @@
+"""
+Agents module for AI-powered data creation.
+
+This module contains all AI-based task composition and data generation logic
+for the Yuga Planner scheduling system.
+"""
+
+from .task_composer_agent import TaskComposerAgent
+from .task_processing import (
+    remove_markdown_code_blocks,
+    remove_markdown_list_elements,
+    unwrap_tasks_from_generated,
+    log_task_duration_breakdown,
+    log_total_time,
+)
+
+__all__ = [
+    # Main agent class
+    "TaskComposerAgent",
+    # Task processing utilities
+    "remove_markdown_code_blocks",
+    "remove_markdown_list_elements",
+    "unwrap_tasks_from_generated",
+    "log_task_duration_breakdown",
+    "log_total_time",
+]

src/{agents → factory/agents}/task_composer_agent.py

@@ -1,4 +1,4 @@
-import os, asyncio
+import asyncio
 from typing import Optional, List
 
 from llama_index.llms.nebius import NebiusLLM
@@ -12,7 +12,7 @@ from llama_index.core.workflow import (
 )
 
 from utils.markdown_analyzer import MarkdownAnalyzer
-from agents.task_processing import (
+from factory.agents.task_processing import (
     remove_markdown_code_blocks,
     remove_markdown_list_elements,
     unwrap_tasks_from_generated,
@@ -89,6 +89,34 @@ class TaskComposerAgent:
             input=query, skills=skills or [], context=context
         )
 
+    async def compose_tasks(self, input_text: str, parameters) -> List:
+        """
+        Compose tasks from input text using the task composer workflow.
+
+        Args:
+            input_text: The input text to compose tasks from
+            parameters: TimeTableDataParameters containing skill information
+
+        Returns:
+            List of task tuples (description, duration, skill)
+        """
+        try:
+            # Extract skills from parameters
+            skills = list(parameters.skill_set.required_skills) + list(
+                parameters.skill_set.optional_skills
+            )
+
+            # Run the workflow
+            result = await self.run_workflow(input_text, skills=skills, context="")
+
+            # The workflow returns a list of tuples (description, duration, skill)
+            logger.debug(f"Task composer workflow result: {result}")
+            return result
+
+        except Exception as e:
+            logger.error(f"Error in compose_tasks: {e}")
+            return []
+
 
 class TaskSplitter(Event):
     task_splitter_output: str
@@ -200,34 +228,14 @@ class TaskComposerWorkflow(Workflow):
     async def evaluate_tasks_dependencies(
         self, event: TaskEvaluator
     ) -> TaskDependencyMatcher:
-        logger.info("=== Step 3: Task Dependencies ===")
-        logger.info("Matching tasks with available skills")
-
-        # Get skills and context from the event
-        skills = event.skills
-        context = event.context
-
-        if not skills:
-            logger.warning("No skills provided, skipping dependency matching")
-            # Convert to dependency format with empty skill
-            task_dependencies = [
-                (task, duration, "") for task, duration in event.task_evaluator_output
-            ]
-            return TaskDependencyMatcher(task_dependency_output=task_dependencies)
-
-        skills_str = "\n".join([f"- {skill}" for skill in skills])
-        logger.info(f"Available skills: {skills}")
-        logger.info(f"Context: {context}")
-
-        task_dependencies: list[tuple[str, str, str]] = []
-        logger.info(
-            f"Processing {len(event.task_evaluator_output)} tasks for skill matching..."
-        )
+        logger.info("=== Step 3: Skill Matching ===")
+        logger.info("Matching tasks with skills...")
 
+        final_tasks: list[tuple[str, str, str]] = []
         for i, (task, duration) in enumerate(event.task_evaluator_output, 1):
             try:
                 formatted_prompt: str = self._task_deps_matcher_template.format(
-                    task=task, skills=skills_str, context=context
+                    task=task, skills=", ".join(event.skills), context=event.context
                 )
 
                 response = await asyncio.wait_for(
@@ -236,36 +244,35 @@ class TaskComposerWorkflow(Workflow):
                 )
 
                 matched_skill = response.text.strip()
-                task_dependencies.append((task, duration, matched_skill))
+                final_tasks.append((task, duration, matched_skill))
                 logger.info(
-                    f"Completed skill matching {i}/{len(event.task_evaluator_output)}: {task[:50]}... -> {matched_skill}"
+                    f"Completed skill matching {i}/{len(event.task_evaluator_output)}"
                 )
 
             except asyncio.TimeoutError:
                 logger.warning(f"Skill matching timeout for task {i}: {task[:50]}...")
 
-                # Use first available skill as fallback
-                fallback_skill = skills[0] if skills else ""
-                task_dependencies.append((task, duration, fallback_skill))
+                # Use a default skill
+                default_skill = event.skills[0] if event.skills else "General"
+                final_tasks.append((task, duration, default_skill))
 
             except Exception as e:
                 logger.error(f"Error matching skill for task {i}: {e}")
 
-                # Use first available skill as fallback
-                fallback_skill = skills[0] if skills else ""
-                task_dependencies.append((task, duration, fallback_skill))
+                # Use a default skill
+                default_skill = event.skills[0] if event.skills else "General"
+                final_tasks.append((task, duration, default_skill))
+
+        logger.info(f"Skill matching completed for {len(final_tasks)} tasks")
 
-        return TaskDependencyMatcher(task_dependency_output=task_dependencies)
+        return TaskDependencyMatcher(task_dependency_output=final_tasks)
 
     @step
     async def result_output(self, event: TaskDependencyMatcher) -> StopEvent:
-        logger.info("=== Step 4: Final Result ===")
+        logger.info("=== Final Result ===")
+        logger.info(f"Generated {len(event.task_dependency_output)} tasks with skills")
 
-        # Log the final breakdown with dependencies
         for task, duration, skill in event.task_dependency_output:
-            logger.info(f"Task: {task}")
-            logger.info(f"  Duration: {duration} units")
-            logger.info(f"  Matched Skill: {skill}")
-            logger.info("-" * 50)
+            logger.info(f"- {task[:50]}... | Duration: {duration} | Skill: {skill}")
 
         return StopEvent(result=event.task_dependency_output)

src/{agents → factory/agents}/task_processing.py

@@ -1,5 +1,3 @@
-import re
-
 from utils.markdown_analyzer import MarkdownAnalyzer
 from utils.logging_config import setup_logging, get_logger
 

src/factory/data/__init__.py

@@ -0,0 +1,27 @@
+"""
+Data module for data generation, transformation, and formatting.
+
+This module contains all algorithmic data creation, generation, and formatting logic
+for the Yuga Planner scheduling system.
+"""
+
+from .formatters import schedule_to_dataframe, employees_to_dataframe
+from .generators import (
+    generate_employees,
+    generate_employee_availability,
+    earliest_monday_on_or_after,
+)
+from .provider import generate_agent_data, generate_mcp_data
+
+__all__ = [
+    # Data formatters - convert domain objects to DataFrames
+    "schedule_to_dataframe",
+    "employees_to_dataframe",
+    # Data generators - create domain objects
+    "generate_employees",
+    "generate_employee_availability",
+    "earliest_monday_on_or_after",
+    # Data providers - orchestrate data creation
+    "generate_agent_data",
+    "generate_mcp_data",
+]

src/{helpers.py → factory/data/formatters.py}

@@ -1,6 +1,8 @@
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, date
 import pandas as pd
 
+from factory.data.generators import earliest_monday_on_or_after
+
 
 def schedule_to_dataframe(schedule) -> pd.DataFrame:
     """
@@ -21,9 +23,6 @@ def schedule_to_dataframe(schedule) -> pd.DataFrame:
 
         # Calculate start and end times based on 30-minute slots
         # Schedule starts from next Monday at 8 AM
-        from datetime import date
-        from factory.data_generators import earliest_monday_on_or_after
-
         base_date = earliest_monday_on_or_after(date.today())
         base_datetime = datetime.combine(
             base_date, datetime.min.time().replace(hour=8)

src/factory/{data_generators.py → data/generators.py}

@@ -1,8 +1,9 @@
 from datetime import date, timedelta
+import random
 from random import Random
 from itertools import product
 
-from factory.data_models import *
+from factory.data.models import *
 from constraint_solvers.timetable.domain import *
 
 
@@ -200,6 +201,7 @@ def generate_tasks(
                 required_skill=required_skill,
             )
         )
+
     return tasks
 
 
@@ -209,51 +211,35 @@ def generate_tasks_from_calendar(
     calendar_entries: list[dict],
 ) -> list[Task]:
     """
-    Given a list of calendar entry dicts, generate Task objects with randomized required_skill.
-    Output format matches generate_tasks.
+    Generate Task objects from calendar entries with Skills.
     """
-    from datetime import datetime
-
     tasks: list[Task] = []
     ids = generate_task_ids()
 
     for entry in calendar_entries:
-        try:
-            summary = entry.get("summary", "Event")
-            dtstart = entry.get("dtstart", "").replace("Z", "+00:00")
-            dtend = entry.get("dtend", "").replace("Z", "+00:00")
-            start_dt = datetime.fromisoformat(dtstart) if dtstart else None
-            end_dt = datetime.fromisoformat(dtend) if dtend else None
-            if start_dt and end_dt:
-                duration_minutes = int((end_dt - start_dt).total_seconds() // 60)
-                duration_slots = max(1, duration_minutes // 30)
-            else:
-                duration_slots = 2  # Default 1 hour
-
-            # Randomize required_skill as in generate_tasks
+        # Get skill from entry or randomly assign
+        required_skill = entry.get("skill")
+        if not required_skill:
             if random.random() >= 0.5:
                 required_skill = random.choice(parameters.skill_set.required_skills)
-
             else:
                 required_skill = random.choice(parameters.skill_set.optional_skills)
 
-            tasks.append(
-                Task(
-                    id=next(ids),
-                    description=summary,
-                    duration_slots=duration_slots,
-                    start_slot=0,  # This will be assigned by the solver
-                    required_skill=required_skill,
-                )
+        tasks.append(
+            Task(
+                id=next(ids),
+                description=entry["summary"],
+                duration_slots=entry.get("duration_slots", 2),  # Default 1 hour
+                start_slot=entry.get("start_slot", 0),
+                required_skill=required_skill,
             )
-
-        except Exception:
-            continue
+        )
 
     return tasks
 
 
 def generate_task_ids():
+    """Generate sequential task IDs starting from 0."""
     current_id = 0
     while True:
         yield str(current_id)
@@ -279,18 +265,16 @@ def weights(distributions: tuple[CountDistribution, ...]) -> tuple[float, ...]:
 
 def earliest_monday_on_or_after(target_date: date) -> date:
     """
-    Returns the date of the next Monday on or after the given date.
-    If the date is already Monday, returns the same date.
+    Returns the earliest Monday on or after the given date.
     """
-    days = (7 - target_date.weekday()) % 7
-    return target_date + timedelta(days=days)
+    days_until_monday = (7 - target_date.weekday()) % 7
+    return target_date + timedelta(days=days_until_monday)
 
 
 def tasks_from_agent_output(agent_output, parameters, project_id: str = ""):
     """
     Convert task_composer_agent output (list of (description, duration, skill)) to Task objects.
     """
-    from constraint_solvers.timetable.domain import Task
 
     ids = generate_task_ids()
     tasks = []
@@ -302,12 +286,13 @@ def tasks_from_agent_output(agent_output, parameters, project_id: str = ""):
         elif len(task_data) == 2:
             description, duration = task_data
             # Fallback to random assignment if no skill provided
-            import random
+            # Use a new Random instance for compatibility
+            rng = random.Random()
 
-            if random.random() >= 0.5:
-                required_skill = random.choice(parameters.skill_set.required_skills)
+            if rng.random() >= 0.5:
+                required_skill = rng.choice(parameters.skill_set.required_skills)
             else:
-                required_skill = random.choice(parameters.skill_set.optional_skills)
+                required_skill = rng.choice(parameters.skill_set.optional_skills)
         else:
             continue  # skip invalid task data
 
@@ -325,19 +310,20 @@ def tasks_from_agent_output(agent_output, parameters, project_id: str = ""):
             )
             if required_skill not in all_skills:
                 # If skill doesn't match exactly, try to find closest match or fallback to random
-                import random
+                rng = random.Random()
 
-                required_skill = random.choice(parameters.skill_set.required_skills)
+                required_skill = rng.choice(parameters.skill_set.required_skills)
 
         tasks.append(
             Task(
                 id=next(ids),
                 description=description,
                 duration_slots=duration_int,
-                start_slot=0,
+                start_slot=0,  # Will be assigned by solver
                 required_skill=required_skill,
                 project_id=project_id,
                 sequence_number=sequence_num,
             )
         )
+
     return tasks

src/factory/{data_provider.py → data/provider.py}

@@ -1,18 +1,16 @@
 import os
 import pandas as pd
 
-pd.set_option("display.max_columns", None)
-from helpers import schedule_to_dataframe
-
 from datetime import date
 from random import Random
 
-from domain import AGENTS_CONFIG
+pd.set_option("display.max_columns", None)
+from factory.data.formatters import schedule_to_dataframe
 
-from factory.data_generators import *
-from factory.data_models import *
+from factory.data.generators import *
+from factory.data.models import *
 
-from agents.task_composer_agent import TaskComposerAgent
+from factory.agents.task_composer_agent import TaskComposerAgent
 
 from constraint_solvers.timetable.domain import *
 
@@ -173,8 +171,6 @@ async def generate_mcp_data(
     # --- LLM TASKS ---
     llm_tasks = []
     if user_message:
-        from factory.data_provider import run_task_composer_agent
-
         agent_output = await run_task_composer_agent(user_message, parameters)
         llm_tasks = tasks_from_agent_output(agent_output, parameters, "PROJECT")
         for t in llm_tasks:
@@ -274,32 +270,18 @@ async def generate_mcp_data(
 async def run_task_composer_agent(
     input_str: str, parameters: TimeTableDataParameters
 ) -> list:
-    agent = TaskComposerAgent(AGENTS_CONFIG)
-    available_skills = list(parameters.skill_set.required_skills) + list(
-        parameters.skill_set.optional_skills
-    )
-    context = f"Project scheduling for {parameters.employee_count} employees over {parameters.days_in_schedule} days"
-
-    logger.info(
-        "Starting task composer workflow - timeout: %ds, input length: %d chars",
-        AGENTS_CONFIG.workflow_timeout,
-        len(input_str),
-    )
-
-    logger.debug("Available skills: %s", available_skills)
-
+    """Runs the task composition agent with the given input and parameters."""
     try:
-        agent_output = await agent.run_workflow(
-            query=input_str, skills=available_skills, context=context
-        )
+        # Initialize the agent
+        agent = TaskComposerAgent()
 
-        logger.info(
-            "Task composer workflow completed successfully - generated %d tasks",
-            len(agent_output),
-        )
+        # Run the agent with the input
+        output = await agent.compose_tasks(input_str, parameters)
 
-        return agent_output
+        logger.debug("Agent output: %s", output)
+        return output
 
     except Exception as e:
-        logger.error("Task composer workflow failed: %s", e)
-        raise
+        logger.error("Error running task composer agent: %s", e)
+        # Return empty list on error
+        return []

src/handlers/__init__.py

@@ -0,0 +1,26 @@
+"""
+Handlers module for Yuga Planner.
+
+This module contains handlers for web UI interactions and MCP API endpoints.
+"""
+
+from .web_backend import (
+    load_data,
+    show_solved,
+    start_timer,
+    auto_poll,
+    show_mock_project_content,
+)
+
+from .mcp_backend import (
+    process_message_and_attached_file,
+)
+
+__all__ = [
+    "load_data",
+    "show_solved",
+    "start_timer",
+    "auto_poll",
+    "show_mock_project_content",
+    "process_message_and_attached_file",
+]

src/{mcp_handlers.py → handlers/mcp_backend.py}

@@ -32,9 +32,9 @@ import time
 
 from utils.extract_calendar import extract_ical_entries
 
-from factory.data_provider import generate_mcp_data
+from factory.data.provider import generate_mcp_data
 from services import ScheduleService, StateService
-from helpers import schedule_to_dataframe
+from factory.data.formatters import schedule_to_dataframe
 
 from utils.logging_config import setup_logging, get_logger, is_debug_enabled
 
@@ -143,7 +143,7 @@ async def process_message_and_attached_file(file_path: str, message_body: str) -
                 solved_schedule = StateService.get_solved_schedule(job_id)
 
                 # Check if we have a valid solution
-                if solved_schedule and solved_schedule.score is not None:
+                if solved_schedule is not None:
                     processing_time = time.time() - start_time
                     logger.info(
                         "Schedule solved after %d polls! (Total time: %.2fs)",
@@ -151,35 +151,58 @@ async def process_message_and_attached_file(file_path: str, message_body: str) -
                         processing_time,
                     )
 
-                    # Convert to final dataframe
-                    final_df = schedule_to_dataframe(solved_schedule)
-
-                    # Generate status message
-                    status_message = ScheduleService.generate_status_message(
-                        solved_schedule
-                    )
-
-                    logger.info("Final Status: %s", status_message)
-
-                    # Return comprehensive JSON response
-                    return {
-                        "status": "success",
-                        "message": "Schedule solved successfully",
-                        "file_info": {
-                            "path": file_path,
-                            "calendar_entries_count": len(calendar_entries),
-                        },
-                        "calendar_entries": calendar_entries,
-                        "solution_status": status_message,
-                        "schedule": final_df.to_dict(
-                            orient="records"
-                        ),  # Convert to list of dicts for JSON
-                        "job_id": job_id,
-                        "polls_required": poll_count + 1,
-                        "processing_time_seconds": processing_time,
-                        "timestamp": time.time(),
-                        "debug_mode": debug_mode,
-                    }
+                    try:
+                        # Convert to final dataframe
+                        final_df = schedule_to_dataframe(solved_schedule)
+
+                        # Generate status message
+                        status_message = ScheduleService.generate_status_message(
+                            solved_schedule
+                        )
+
+                        logger.info("Final Status: %s", status_message)
+
+                        # Return comprehensive JSON response
+                        response_data = {
+                            "status": "success",
+                            "message": "Schedule solved successfully",
+                            "file_info": {
+                                "path": file_path,
+                                "calendar_entries_count": len(calendar_entries),
+                            },
+                            "calendar_entries": calendar_entries,
+                            "solution_status": status_message,
+                            "schedule": final_df.to_dict(
+                                orient="records"
+                            ),  # Convert to list of dicts for JSON
+                            "job_id": job_id,
+                            "polls_required": poll_count + 1,
+                            "processing_time_seconds": processing_time,
+                            "timestamp": time.time(),
+                            "debug_mode": debug_mode,
+                        }
+
+                        logger.debug(
+                            "Returning JSON response with %d schedule entries",
+                            len(response_data["schedule"]),
+                        )
+                        return response_data
+
+                    except Exception as e:
+                        logger.error(
+                            "Error converting schedule to JSON: %s",
+                            e,
+                            exc_info=debug_mode,
+                        )
+                        # Return error response instead of raising
+                        return {
+                            "error": f"Error converting schedule to JSON: {str(e)}",
+                            "status": "conversion_failed",
+                            "job_id": job_id,
+                            "processing_time_seconds": processing_time,
+                            "timestamp": time.time(),
+                            "debug_mode": debug_mode,
+                        }
 
             if debug_mode:
                 logger.debug("Poll %d/%d: Still solving...", poll_count + 1, max_polls)

src/{handlers.py → handlers/web_backend.py}

@@ -1,9 +1,10 @@
 from typing import Tuple
+import os
 
 import pandas as pd
 import gradio as gr
 
-from utils.logging_config import setup_logging, get_logger, is_debug_enabled
+from utils.logging_config import setup_logging, get_logger
 
 # Initialize logging
 setup_logging()
@@ -247,8 +248,6 @@ def _ensure_log_streaming_setup(debug: bool = False) -> None:
     """
     if debug:
         # Force debug mode setup if explicitly requested
-        import os
-
         os.environ["YUGA_DEBUG"] = "true"
         setup_logging("DEBUG")
 

src/services/__init__.py

@@ -4,11 +4,11 @@ Services module for Yuga Planner business logic.
 This module contains all the business logic separated from the UI handlers.
 """
 
-from .logging_service import LoggingService
-from .schedule_service import ScheduleService
-from .data_service import DataService
-from .mock_projects_service import MockProjectService
-from .state_service import StateService
+from .logging import LoggingService
+from .schedule import ScheduleService
+from .data import DataService
+from .mock_projects import MockProjectService
+from .state import StateService
 
 __all__ = [
     "LoggingService",

src/services/constraint_analyzer.py

@@ -0,0 +1,278 @@
+from typing import Dict, List, Any
+from constraint_solvers.timetable.domain import EmployeeSchedule
+from constraint_solvers.timetable.solver import solution_manager
+
+
+class ConstraintAnalyzerService:
+    """
+    Service for analyzing scheduling solutions using Timefold's native constraint analysis.
+
+    This service provides methods to analyze constraint violations, generate suggestions,
+    and understand solution quality using Timefold's built-in ScoreAnalysis and SolutionManager APIs.
+    """
+
+    @staticmethod
+    def analyze_constraint_violations(schedule: EmployeeSchedule) -> str:
+        """
+        Analyze constraint violations in a schedule using Timefold's native score analysis.
+
+        Args:
+            schedule: The schedule to analyze
+
+        Returns:
+            Detailed string describing constraint violations and their breakdown
+        """
+        if not schedule.score or schedule.score.hard_score >= 0:
+            return "No constraint violations detected."
+
+        # Get Timefold's solution manager and analyze the schedule
+        score_analysis = solution_manager.analyze(schedule)
+
+        # Return the built-in summary
+        return score_analysis.summary
+
+    @staticmethod
+    def get_detailed_analysis(schedule: EmployeeSchedule) -> Dict[str, Any]:
+        """
+        Get detailed constraint analysis as a structured dictionary.
+
+        Args:
+            schedule: The schedule to analyze
+
+        Returns:
+            Dictionary containing detailed constraint analysis information
+        """
+        score_analysis = solution_manager.analyze(schedule)
+
+        analysis_result = {
+            "total_score": str(score_analysis.score),
+            "hard_score": score_analysis.score.hard_score,
+            "soft_score": score_analysis.score.soft_score,
+            "constraints": {},
+        }
+
+        # Analyze each constraint
+        for (
+            constraint_ref,
+            constraint_analysis,
+        ) in score_analysis.constraint_map.items():
+            constraint_id = constraint_ref.constraint_id
+            constraint_info = {
+                "score": str(constraint_analysis.score),
+                "match_count": constraint_analysis.match_count,
+                "matches": [],
+            }
+
+            # Get details for each constraint match
+            for match_analysis in constraint_analysis.matches:
+                match_info = {
+                    "score": str(match_analysis.score),
+                    "justification": str(match_analysis.justification)
+                    if match_analysis.justification
+                    else None,
+                }
+                constraint_info["matches"].append(match_info)
+
+            analysis_result["constraints"][constraint_id] = constraint_info
+
+        return analysis_result
+
+    @staticmethod
+    def get_broken_constraints(schedule: EmployeeSchedule) -> List[Dict[str, Any]]:
+        """
+        Get a list of broken constraints with their details.
+
+        Args:
+            schedule: The schedule to analyze
+
+        Returns:
+            List of dictionaries, each containing information about a broken constraint
+        """
+        score_analysis = solution_manager.analyze(schedule)
+        broken_constraints = []
+
+        for (
+            constraint_ref,
+            constraint_analysis,
+        ) in score_analysis.constraint_map.items():
+            # Only include constraints that have a negative impact on the score
+            if (
+                constraint_analysis.score.hard_score < 0
+                or constraint_analysis.score.soft_score < 0
+            ):
+
+                broken_constraints.append(
+                    {
+                        "constraint_id": constraint_ref.constraint_id,
+                        "score": str(constraint_analysis.score),
+                        "hard_score": constraint_analysis.score.hard_score,
+                        "soft_score": constraint_analysis.score.soft_score,
+                        "match_count": constraint_analysis.match_count,
+                        "constraint_name": constraint_ref.constraint_name,
+                    }
+                )
+
+        return broken_constraints
+
+    @staticmethod
+    def compare_solutions(
+        old_schedule: EmployeeSchedule, new_schedule: EmployeeSchedule
+    ) -> Dict[str, Any]:
+        """
+        Compare two solutions and identify what changed between them.
+
+        Args:
+            old_schedule: The previous schedule solution
+            new_schedule: The new schedule solution
+
+        Returns:
+            Dictionary containing the differences between the two solutions
+        """
+        old_analysis = solution_manager.analyze(old_schedule)
+        new_analysis = solution_manager.analyze(new_schedule)
+
+        # Calculate the difference
+        diff = old_analysis - new_analysis
+
+        comparison_result = {
+            "old_score": str(old_analysis.score),
+            "new_score": str(new_analysis.score),
+            "score_difference": str(diff.score),
+            "improved": (
+                new_analysis.score.hard_score > old_analysis.score.hard_score
+                or (
+                    new_analysis.score.hard_score == old_analysis.score.hard_score
+                    and new_analysis.score.soft_score > old_analysis.score.soft_score
+                )
+            ),
+            "changed_constraints": {},
+        }
+
+        # Analyze changes in constraints
+        for constraint_ref, constraint_analysis in diff.constraint_map.items():
+            comparison_result["changed_constraints"][constraint_ref.constraint_id] = {
+                "score_difference": str(constraint_analysis.score),
+                "match_count": constraint_analysis.match_count,
+                "changes": [
+                    str(match.justification)
+                    for match in constraint_analysis.matches
+                    if match.justification
+                ],
+            }
+
+        return comparison_result
+
+    @staticmethod
+    def get_heat_map_data(schedule: EmployeeSchedule) -> Dict[Any, Dict[str, Any]]:
+        """
+        Get heat map data showing which planning entities have the most constraint violations.
+
+        Args:
+            schedule: The schedule to analyze
+
+        Returns:
+            Dictionary mapping planning entities to their constraint impact
+        """
+        score_explanation = solution_manager.explain(schedule)
+        indictment_map = score_explanation.indictment_map
+
+        heat_map_data = {}
+
+        # Process indictments for tasks
+        for task in schedule.tasks:
+            indictment = indictment_map.get(task)
+
+            if indictment is not None:
+                heat_map_data[task] = {
+                    "total_score": str(indictment.score),
+                    "hard_score": indictment.score.hard_score,
+                    "soft_score": indictment.score.soft_score,
+                    "constraint_matches": [
+                        {
+                            "constraint_name": match.constraint_name,
+                            "score": str(match.score),
+                        }
+                        for match in indictment.constraint_match_set
+                    ],
+                }
+
+        # Process indictments for employees
+        for employee in schedule.employees:
+            indictment = indictment_map.get(employee)
+
+            if indictment is not None:
+                heat_map_data[employee] = {
+                    "total_score": str(indictment.score),
+                    "hard_score": indictment.score.hard_score,
+                    "soft_score": indictment.score.soft_score,
+                    "constraint_matches": [
+                        {
+                            "constraint_name": match.constraint_name,
+                            "score": str(match.score),
+                        }
+                        for match in indictment.constraint_match_set
+                    ],
+                }
+
+        return heat_map_data
+
+    @staticmethod
+    def generate_improvement_suggestions(schedule: EmployeeSchedule) -> List[str]:
+        """
+        Generate improvement suggestions based on constraint analysis.
+
+        Args:
+            schedule: The schedule to analyze
+
+        Returns:
+            List of actionable suggestions for improving the schedule
+        """
+        if not schedule.score or schedule.score.hard_score >= 0:
+            return [
+                "Schedule is feasible. Consider optimizing soft constraints for better quality."
+            ]
+
+        broken_constraints = ConstraintAnalyzerService.get_broken_constraints(schedule)
+        suggestions = []
+
+        # Generate suggestions based on broken constraint types
+        for constraint in broken_constraints:
+            constraint_id = constraint["constraint_id"].lower()
+
+            match constraint_id:
+                case constraint_id if "skill" in constraint_id:
+                    suggestions.append(
+                        f"Skill constraint violation: Consider adding employees with required skills "
+                        f"or reassigning tasks ({constraint['match_count']} violations)"
+                    )
+
+                case constraint_id if "availability" in constraint_id or "time" in constraint_id:
+                    suggestions.append(
+                        f"Time/Availability constraint violation: Check employee schedules and "
+                        f"task timing ({constraint['match_count']} violations)"
+                    )
+
+                case constraint_id if "sequence" in constraint_id or "order" in constraint_id:
+                    suggestions.append(
+                        f"Sequencing constraint violation: Review task dependencies and ordering "
+                        f"({constraint['match_count']} violations)"
+                    )
+
+                case constraint_id if "capacity" in constraint_id or "workload" in constraint_id:
+                    suggestions.append(
+                        f"Capacity constraint violation: Distribute workload more evenly or "
+                        f"add more resources ({constraint['match_count']} violations)"
+                    )
+
+                case _:
+                    suggestions.append(
+                        f"Constraint '{constraint['constraint_id']}' violated "
+                        f"({constraint['match_count']} times) - review constraint definition"
+                    )
+
+        if not suggestions:
+            suggestions.append(
+                "Hard constraints violated. Review constraint definitions and problem data."
+            )
+
+        return suggestions

src/services/{data_service.py → data.py}

@@ -5,7 +5,7 @@ from typing import Dict, List, Tuple, Union, Optional, Any
 
 import pandas as pd
 
-from factory.data_provider import (
+from factory.data.provider import (
     generate_agent_data,
     DATA_PARAMS,
     TimeTableDataParameters,
@@ -19,8 +19,8 @@ from constraint_solvers.timetable.domain import (
     Employee,
 )
 
-from helpers import schedule_to_dataframe, employees_to_dataframe
-from .mock_projects_service import MockProjectService
+from factory.data.formatters import schedule_to_dataframe, employees_to_dataframe
+from .mock_projects import MockProjectService
 from utils.logging_config import setup_logging, get_logger
 
 # Initialize logging

src/services/{logging_service.py → logging.py}

@@ -1,8 +1,8 @@
-import logging
-import threading
 from datetime import datetime
 from typing import List
 
+import logging, threading
+
 from utils.logging_config import setup_logging, get_logger, is_debug_enabled
 
 # Initialize logging

src/services/{schedule_service.py → schedule.py}

@@ -5,21 +5,27 @@ from typing import Tuple, Dict, Any, Optional
 import pandas as pd
 import gradio as gr
 
-from .state_service import StateService
+from .state import StateService
 from constraint_solvers.timetable.solver import solver_manager
-from factory.data_provider import (
-    generate_employees,
-    generate_employee_availability,
+
+from factory.data.provider import (
     DATA_PARAMS,
     TimeTableDataParameters,
     SLOTS_PER_DAY,
 )
 
+from factory.data.generators import (
+    generate_employees,
+    generate_employee_availability,
+)
+
+from factory.data.formatters import schedule_to_dataframe, employees_to_dataframe
+
 from constraint_solvers.timetable.domain import EmployeeSchedule, ScheduleInfo
 
-from helpers import schedule_to_dataframe, employees_to_dataframe
-from .data_service import DataService
-from constraint_solvers.timetable.analysis import ConstraintViolationAnalyzer
+from .data import DataService
+from .constraint_analyzer import ConstraintAnalyzerService
+
 from utils.logging_config import setup_logging, get_logger
 
 # Initialize logging
@@ -333,16 +339,22 @@ class ScheduleService:
             if hard_score < 0:
                 # Hard constraints are violated - the problem is infeasible
                 violation_count = abs(int(hard_score))
+
                 violation_details = (
-                    ConstraintViolationAnalyzer.analyze_constraint_violations(schedule)
+                    ConstraintAnalyzerService.analyze_constraint_violations(schedule)
                 )
-                suggestions = ConstraintViolationAnalyzer.generate_suggestions(schedule)
+
+                suggestions = (
+                    ConstraintAnalyzerService.generate_improvement_suggestions(schedule)
+                )
+
                 suggestion_text = "\n".join(f"• {s}" for s in suggestions)
 
                 status_message = (
                     f"⚠️ CONSTRAINTS VIOLATED: {violation_count} hard constraint(s) could not be satisfied. "
                     f"The schedule is not feasible.\n\n{violation_details}\n\nSuggestions:\n{suggestion_text}"
                 )
+
                 logger.warning(
                     f"Infeasible solution detected. Hard score: {hard_score}"
                 )

src/services/{state_service.py → state.py}

@@ -1,6 +1,9 @@
 from typing import Optional
+
 from state import app_state
+
 from constraint_solvers.timetable.domain import EmployeeSchedule
+
 from utils.logging_config import setup_logging, get_logger
 
 # Initialize logging

src/utils/__init__.py

@@ -1,3 +1,24 @@
 """
-Utils package initialization.
+Utils package for common utilities and helper functions.
+
+This module contains logging configuration, secret loading, calendar extraction,
+and markdown analysis utilities.
 """
+
+from .logging_config import setup_logging, get_logger, is_debug_enabled
+from .load_secrets import load_secrets
+from .extract_calendar import extract_ical_entries
+from .markdown_analyzer import MarkdownAnalyzer
+
+__all__ = [
+    # Logging utilities
+    "setup_logging",
+    "get_logger",
+    "is_debug_enabled",
+    # Configuration utilities
+    "load_secrets",
+    # Calendar utilities
+    "extract_ical_entries",
+    # Markdown utilities
+    "MarkdownAnalyzer",
+]

src/utils/load_secrets.py

@@ -1,4 +1,5 @@
 import os
+import importlib.util
 
 from utils.logging_config import setup_logging, get_logger
 
@@ -19,8 +20,6 @@ def load_secrets(secrets_file: str):
     """
     try:
         # Import secrets from the specified file
-        import importlib.util
-
         spec = importlib.util.spec_from_file_location("secrets", secrets_file)
         secrets = importlib.util.module_from_spec(spec)
         spec.loader.exec_module(secrets)

tests/test_factory.py

@@ -7,7 +7,7 @@ from icalendar import Calendar, vDDDTypes
 # Load environment variables for agent (if needed)
 load_secrets("tests/secrets/creds.py")
 
-import factory.data_provider as data_provider
+import factory.data.provider as data_provider
 from src.utils.extract_calendar import extract_ical_entries