chore: reboot project versioning

refactor: add tabs to UI

Switched primary focus to MCP tool

.gitignore

@@ -0,0 +1,130 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+*.code-workspace
+
+tests/secrets/nebius_secrets.py
+
+tests/secrets/creds.py

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.3.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+
+-   repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.0
+    hooks:
+    -   id: gitleaks
+
+-   repo: https://github.com/psf/black
+    rev: 22.10.0
+    hooks:
+    -   id: black

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.10
+
+RUN apt-get update && \
+    apt-get install -y wget gnupg2 && \
+    wget -O- https://packages.adoptium.net/artifactory/api/gpg/key/public | gpg --dearmor > /usr/share/keyrings/adoptium-archive-keyring.gpg && \
+    echo "deb [signed-by=/usr/share/keyrings/adoptium-archive-keyring.gpg] https://packages.adoptium.net/artifactory/deb bookworm main" > /etc/apt/sources.list.d/adoptium.list && \
+    apt-get update && \
+    apt-get install -y temurin-21-jdk && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+ENV JAVA_HOME=/usr/lib/jvm/temurin-21-jdk-amd64
+ENV PATH="$JAVA_HOME/bin:$PATH"
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["python", "src/app.py"]

LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2025] [https://github.com/blackopsrepl]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

Makefile

@@ -0,0 +1,47 @@
+.PHONY: help venv install run test lint format clean setup-secrets
+
+PYTHON=python
+PIP=pip
+VENV=.venv
+ACTIVATE=. $(VENV)/bin/activate
+
+help:
+	@echo "Yuga Planner Makefile"
+	@echo "Available targets:"
+	@echo "  venv            Create a Python virtual environment"
+	@echo "  install         Install all Python dependencies"
+	@echo "  run             Run the Gradio app locally"
+	@echo "  test            Run all tests with pytest"
+	@echo "  lint            Run pre-commit hooks (includes black, yaml, gitleaks)"
+	@echo "  format          Format code with black"
+	@echo "  setup-secrets   Copy and edit secrets template for local dev"
+	@echo "  clean           Remove Python cache and virtual environment"
+
+venv:
+	$(PYTHON) -m venv $(VENV)
+
+install: venv
+	$(ACTIVATE); $(PIP) install --upgrade pip
+	$(ACTIVATE); $(PIP) install -r requirements.txt
+	$(ACTIVATE); $(PIP) install pre-commit black
+
+run:
+	$(ACTIVATE); $(PYTHON) src/app.py
+
+test:
+	$(ACTIVATE); pytest
+
+lint:
+	$(ACTIVATE); pre-commit run --all-files
+
+format:
+	$(ACTIVATE); black src tests
+
+setup-secrets:
+	cp -n tests/secrets/nebius_secrets.py.template tests/secrets/cred.py; \
+	echo "Edit tests/secrets/cred.py to add your own API credentials."
+
+clean:
+	rm -rf $(VENV) __pycache__ */__pycache__ .pytest_cache .mypy_cache .coverage .hypothesis
+	find . -type f -name '*.pyc' -delete
+	find . -type d -name '__pycache__' -exec rm -rf {} +

README.md

@@ -1,13 +1,168 @@
 ---
 title: Yuga Planner
-emoji: 🏃
-colorFrom: green
+emoji: 🐍
+colorFrom: purple
 colorTo: gray
-sdk: gradio
-sdk_version: 5.32.1
-app_file: app.py
-pinned: false
-license: gpl-3.0
+sdk: docker
+app_port: 7860
+license: apache-2.0
+tags: ["agent-demo-track"]
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Yuga Planner 🐍
+
+**This project was developed for the [Hugging Face Agents MCP Hackathon](https://huggingface.co/Agents-MCP-Hackathon)!**
+
+Yuga Planner is a neuro-symbolic system prototype: it provides an agent-powered team scheduling and task allocation platform built on [Gradio](https://gradio.app/).
+
+It takes a project description file such as a README.md file, breaks it down into actionable tasks through a [LLamaIndex](https://www.llamaindex.ai/) agent, then uses [Timefold](http://www.timefold.ai) to generate optimal employee schedules for complex projects.
+
+**Demo Video:** [pCloud]()
+
+## 🚀 Try It Now
+**Live Demo:**
+[https://huggingface.co/spaces/Agents-MCP-Hackathon/yuga-planner](https://huggingface.co/spaces/Agents-MCP-Hackathon/yuga-planner)
+
+**Source Code on GitHub:**
+[https://github.com/blackopsrepl/yuga-planner](https://github.com/blackopsrepl/yuga-planner)
+
+### Usage
+
+1. Go to [the live demo](https://huggingface.co/spaces/Agents-MCP-Hackathon/yuga-planner) or [http://localhost:7860](http://localhost:7860)
+
+2. Upload one or more Markdown project file(s), then click "Load Data"
+   - Each file will be taken as a separate project
+   - The app will parse, decompose, and estimate tasks
+   - Click "Solve" to generate an optimal schedule
+   - Task order is preserved withing each project
+
+3. When the data is loaded, click "Solve" and view results interactively
+
+## Architecture
+
+- **Gradio UI:** Main entry point for users
+- **task_composer_agent:** Uses LLMs to decompose and estimate tasks from Markdown
+- **Data Provider:** Generates synthetic employee data and availability preferences
+- **Constraint Solver:** Assigns tasks to employees, optimizing for skills, availability, and fairness
+- **Utils:** Markdown analysis, secret loading, and more
+
+---
+
+## 🌟 Key Features
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Markdown Project Parsing** | Automatic extraction of tasks from Markdown docs | ✅ |
+| **LLM-Powered Task Analysis** | [LLamaIndex](https://www.llamaindex.ai/) + [Nebius AI](https://nebius.ai/) for task decomposition & estimation | ✅ |
+| **Constraint-Based Scheduling** | [Timefold](http://www.timefold.ai) optimization engine for schedule assignments | ✅ |
+| **Skills Matching** | Detection of skills required for each task | ✅ |
+| **Task Dependencies** | Sequential workflow modeling | ✅ |
+| **Multiple Projects Support** | Load and schedule multiple projects simultaneously | ✅ |
+| **Live Log Streaming** | Real-time solver progress and status updates in UI | ✅ |
+| **Configurable Parameters** | Adjustable employee count and schedule duration | ✅ |
+| **Mock Project Loading** | Pre-configured sample projects for quick testing | ✅ |
+| **Calendar Parsing** | Extracts tasks from uploaded calendar files (.ics) | ✅ |
+| **MCP Endpoint** | API endpoint for MCP tool integration | ✅ |
+
+## 🧩 MCP Tool Integration
+
+Yuga Planner now includes an **MCP tool** endpoint, allowing integration with the Hugging Face MCP platform. The MCP tool can process uploaded calendar files (such as `.ics`) and user messages, extracting events and generating a corresponding task dataframe.
+
+> **Note:** The current MCP tool implementation returns the *unsolved* task dataframe (not a scheduled/solved output), as full schedule solving is not yet supported for MCP requests. This allows downstream tools or users to inspect and process the extracted tasks before scheduling is implemented.
+
+**Features:**
+- Accepts calendar files and user instructions
+- Parses events into actionable tasks
+- Returns a structured dataframe of tasks (unsolved)
+- Designed for easy integration with agent workflows
+
+See the [CHANGELOG.md](CHANGELOG.md) for details on recent MCP-related changes.
+
+### Work in Progress
+
+- **Gradio UI overhaul**
+- **General optimization of the workflow**
+
+### Future Work
+
+- **RAG:** validation of task decomposition and estimation against industry relevant literature
+- **More granular task dependency:** representation of tasks in a tree instead of a list to allow overlap within projects, where feasible/convenient
+- **Input from GitHub issues:** instead of processing markdown directly, it creates a list by parsing issue
+- **Chat interface:** detection of user intent, with on-the-fly CRUD operations on team, tasks and schedules
+- **Reinforcement learning:** training the agent to improve task decomposition and estimation from GitHub history (e.g. diffs in timestamps, issue comments etc.)
+
+## Prerequisites (Local/GitHub)
+
+- Python 3.10
+- Java 17+
+- Docker (optional, for containerized deployment)
+- Nebius API credentials (for LLM-powered features)
+
+### Installation
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/blackopsrepl/yuga-planner.git
+   cd yuga-planner
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   make install
+   ```
+
+3. **Set up environment variables / secrets:**
+   ```bash
+   make setup-secrets
+   # Then edit tests/secrets/cred.py to add your API credentials
+   ```
+
+4. **Run the app:**
+   ```bash
+   make run
+   ```
+
+#### Docker (Local/GitHub)
+
+1. **Build the image:**
+   ```bash
+   docker build -t yuga-planner .
+   ```
+
+2. **Run the container:**
+   ```bash
+   docker run -p 7860:786
+   ```
+
+---
+
+## Testing
+
+- **Run tests:**
+  ```bash
+  make test
+  ```
+
+- **Test files:**
+  Located in the `tests/` directory.
+
+---
+
+## Python Dependencies
+
+See `requirements.txt` for full list.
+
+---
+
+## License
+
+This project is licensed under the Apache 2.0 License. See [LICENSE.txt](LICENSE.txt) for details.
+
+---
+
+## Acknowledgements
+
+- [Hugging Face](https://huggingface.co/)
+- [Gradio](https://gradio.app/)
+- [Nebius LLM](https://nebius.ai/)
+- [llama-index](https://github.com/jerryjliu/llama_index)
+- [Timefold](https://timefold.ai/)

pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+pythonpath = src
+testpaths = tests
+python_files = test_*.py
+addopts = -s -v

requirements.txt

@@ -0,0 +1,14 @@
+# Base requirements
+pytest
+pytest-asyncio
+python-dotenv
+pathlib
+gradio
+gradio[mcp]
+llama-index-core
+llama-index-utils-workflow
+llama-index-llms-nebius
+pandas
+pydantic
+timefold == 1.22.1b0
+icalendar

src/agents/task_composer_agent.py

@@ -0,0 +1,269 @@
+import os, asyncio, logging
+from typing import Optional, List
+
+from llama_index.llms.nebius import NebiusLLM
+from llama_index.core.prompts import RichPromptTemplate
+from llama_index.core.workflow import (
+    StartEvent,
+    StopEvent,
+    Workflow,
+    step,
+    Event,
+)
+
+from utils.markdown_analyzer import MarkdownAnalyzer
+from agents.task_processing import (
+    remove_markdown_code_blocks,
+    remove_markdown_list_elements,
+    unwrap_tasks_from_generated,
+    log_task_duration_breakdown,
+    log_total_time,
+)
+
+logging.basicConfig(level=logging.INFO)
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+from domain import AgentsConfig, AGENTS_CONFIG
+
+
+class TaskComposerAgent:
+    def __init__(self, config: AgentsConfig = AGENTS_CONFIG):
+        self.config = config
+        self.llm: Optional[NebiusLLM] = None
+        self.task_splitter_template: Optional[RichPromptTemplate] = None
+        self.task_evaluator_template: Optional[RichPromptTemplate] = None
+        self.task_deps_matcher_template: Optional[RichPromptTemplate] = None
+        self.workflow: Optional[TaskComposerWorkflow] = None
+
+        self.set_llm()
+        self.set_prompt_templates()
+        self.set_workflow()
+
+    def set_llm(self) -> None:
+        self.llm = NebiusLLM(
+            model=self.config.nebius_model,
+            api_key=self.config.nebius_api_key,
+            timeout=self.config.timeout,
+            max_retries=self.config.max_retries,
+            verify_ssl=self.config.verify_ssl,
+            request_timeout=self.config.request_timeout,
+            max_tokens=self.config.max_tokens,
+            temperature=self.config.temperature,
+        )
+
+    def set_prompt_templates(self) -> None:
+        self.task_splitter_template = RichPromptTemplate(
+            self.config.task_splitter_prompt,
+            template_var_mappings={"query_str": "query"},
+        )
+        self.task_evaluator_template = RichPromptTemplate(
+            self.config.task_evaluator_prompt,
+            template_var_mappings={"query_str": "query"},
+        )
+        self.task_deps_matcher_template = RichPromptTemplate(
+            self.config.task_deps_matcher_prompt,
+            template_var_mappings={
+                "query_str": "task",
+                "skills_str": "skills",
+                "context_str": "context",
+            },
+        )
+
+    def set_workflow(self) -> None:
+        self.workflow = TaskComposerWorkflow(
+            llm=self.llm,
+            task_splitter_template=self.task_splitter_template,
+            task_evaluator_template=self.task_evaluator_template,
+            task_deps_matcher_template=self.task_deps_matcher_template,
+            timeout=self.config.workflow_timeout,
+            verbose=True,
+        )
+
+    async def run_workflow(
+        self, query: str, skills: Optional[List[str]] = None, context: str = ""
+    ) -> str:
+        return await self.workflow.run(
+            input=query, skills=skills or [], context=context
+        )
+
+
+class TaskSplitter(Event):
+    task_splitter_output: str
+    skills: List[str]
+    context: str
+
+
+class TaskEvaluator(Event):
+    task_evaluator_output: list[tuple[str, str]]
+    skills: List[str]
+    context: str
+
+
+class TaskDependencyMatcher(Event):
+    task_dependency_output: list[
+        tuple[str, str, str]
+    ]  # (task, duration, matched_skill)
+
+
+class TaskComposerWorkflow(Workflow):
+    def __init__(
+        self,
+        llm: NebiusLLM,
+        task_splitter_template: RichPromptTemplate,
+        task_evaluator_template: RichPromptTemplate,
+        task_deps_matcher_template: RichPromptTemplate,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self._llm = llm
+        self._task_splitter_template = task_splitter_template
+        self._task_evaluator_template = task_evaluator_template
+        self._task_deps_matcher_template = task_deps_matcher_template
+
+    @step
+    async def split_tasks(self, event: StartEvent) -> TaskSplitter:
+        logger.info("=== Step 1: Task Breakdown ===")
+        logger.info(f"Input task: {event.input}")
+
+        formatted_prompt: str = self._task_splitter_template.format(query=event.input)
+
+        response = await asyncio.wait_for(
+            asyncio.to_thread(self._llm.complete, formatted_prompt), timeout=30.0
+        )
+
+        logger.info("Task breakdown:")
+        logger.info(response.text)
+
+        # Get skills and context from the event, default to empty if not provided
+        skills = getattr(event, "skills", [])
+        context = getattr(event, "context", "")
+
+        logger.info(f"Received skills: {skills}")
+        logger.info(f"Received context: {context}")
+
+        return TaskSplitter(
+            task_splitter_output=response.text, skills=skills, context=context
+        )
+
+    @step
+    async def evaluate_tasks_duration(self, event: TaskSplitter) -> TaskEvaluator:
+        logger.info("=== Step 2: Time Estimation ===")
+        logger.info("Using task breakdown from Step 1:")
+        logger.info(event.task_splitter_output)
+
+        content: str = remove_markdown_code_blocks(event.task_splitter_output)
+        analyzer: MarkdownAnalyzer = MarkdownAnalyzer(content)
+        result: list = analyzer.identify_lists()["Unordered list"]
+        tasks: list[str] = unwrap_tasks_from_generated(result)
+
+        logger.info(f"Processing {len(tasks)} tasks for time estimation...")
+
+        merged_tasks: list[tuple[str, str]] = []
+        for i, task in enumerate(tasks, 1):
+            try:
+                formatted_prompt: str = self._task_evaluator_template.format(query=task)
+
+                response = await asyncio.wait_for(
+                    asyncio.to_thread(self._llm.complete, formatted_prompt),
+                    timeout=30.0,
+                )
+                merged_tasks.append((task, response.text))
+                logger.info(f"Completed time estimation {i}/{len(tasks)}")
+
+            except asyncio.TimeoutError:
+                logger.warning(f"Time estimation timeout for task {i}: {task[:50]}...")
+
+                # Use default duration of 2 units (1 hour)
+                merged_tasks.append((task, "2"))
+
+            except Exception as e:
+                logger.error(f"Error estimating time for task {i}: {e}")
+
+                # Use default duration of 2 units (1 hour)
+                merged_tasks.append((task, "2"))
+
+        # remove markdown list elements wrapped in **
+        merged_tasks = remove_markdown_list_elements(merged_tasks)
+        log_task_duration_breakdown(merged_tasks)
+        log_total_time(merged_tasks)
+
+        return TaskEvaluator(
+            task_evaluator_output=merged_tasks,
+            skills=event.skills,
+            context=event.context,
+        )
+
+    @step
+    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..."
+        )
+
+        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
+                )
+
+                response = await asyncio.wait_for(
+                    asyncio.to_thread(self._llm.complete, formatted_prompt),
+                    timeout=30.0,
+                )
+
+                matched_skill = response.text.strip()
+                task_dependencies.append((task, duration, matched_skill))
+                logger.info(
+                    f"Completed skill matching {i}/{len(event.task_evaluator_output)}: {task[:50]}... -> {matched_skill}"
+                )
+
+            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))
+
+            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))
+
+        return TaskDependencyMatcher(task_dependency_output=task_dependencies)
+
+    @step
+    async def result_output(self, event: TaskDependencyMatcher) -> StopEvent:
+        logger.info("=== Step 4: Final Result ===")
+
+        # 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)
+
+        return StopEvent(result=event.task_dependency_output)

src/agents/task_processing.py

@@ -0,0 +1,143 @@
+import re, logging
+
+from utils.markdown_analyzer import MarkdownAnalyzer
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+### MARKDOWN UTILS ###
+def remove_markdown_code_blocks(text: str) -> str:
+    """
+    Remove markdown code block syntax from text.
+
+    Args:
+        text (str): Text that may contain markdown code block syntax
+
+    Returns:
+        str: Text with markdown code block syntax removed
+    """
+    content = text
+
+    if content.startswith("```markdown"):
+        content = content[11:]  # Remove ```markdown
+
+    if content.endswith("```"):
+        content = content[:-3]  # Remove ```
+
+    return content.strip()
+
+
+def remove_markdown_list_headers(
+    merged_tasks: list[tuple[str, str]]
+) -> list[tuple[str, str]]:
+    """
+    Remove list headers (e.g. **element**) from task descriptions.
+
+    Args:
+        merged_tasks (list[tuple[str, str]]): List of (task, duration) tuples
+
+    Returns:
+        list[tuple[str, str]]: List of (task, duration) tuples with headers removed
+    """
+    cleaned_tasks: list[tuple[str, str]] = []
+
+    for task, duration in merged_tasks:
+        # Use MarkdownAnalyzer to parse and clean the task text
+        analyzer: MarkdownAnalyzer = MarkdownAnalyzer(task)
+
+        # Get the text content without any markdown formatting
+        cleaned_task: str = analyzer.text.strip()
+        cleaned_tasks.append((cleaned_task, duration))
+
+    return cleaned_tasks
+
+
+def remove_markdown_list_elements(
+    merged_tasks: list[tuple[str, str]]
+) -> list[tuple[str, str]]:
+    """
+    Remove markdown list elements that start and end with ** from task descriptions.
+    If a task is entirely wrapped in **, remove the entire task.
+
+    Args:
+        merged_tasks (list[tuple[str, str]]): List of (task, duration) tuples
+
+    Returns:
+        list[tuple[str, str]]: List of (task, duration) tuples with markdown list elements removed
+    """
+    cleaned_tasks = []
+    for task, duration in merged_tasks:
+        # Skip tasks that are wrapped in **
+        if task.strip().startswith("**") or task.strip().endswith("**"):
+            continue
+
+        cleaned_tasks.append((task, duration))
+
+    return cleaned_tasks
+
+
+def unwrap_tasks_from_generated(result: list) -> list:
+    """
+    Extract task text from the generated markdown list structure.
+
+    Args:
+        result (list): List containing markdown list structure
+
+    Returns:
+        list: List of task text strings
+    """
+    tasks = []
+
+    # Input validation: check if result is a list
+    if not isinstance(result, list):
+        logger.error("Error: 'Unordered list' is not a list!")
+        return tasks
+
+    # We expect result to be a list of lists, with only one entry
+    if not isinstance(result[0], list):
+        logger.error("Error: The first element of the result is not a list!")
+        return tasks
+
+    # Unwrap the inner list of dictionaries
+    for task in result[0]:
+        if isinstance(task, dict) and "text" in task:
+            tasks.append(task["text"])
+        else:
+            logger.warning(f"Unexpected task format: {task}")
+
+    return tasks
+
+
+### LOGGING ###
+def log_task_duration_breakdown(merged_tasks: list[tuple[str, str]]) -> None:
+    """
+    Log the duration breakdown for each task.
+
+    Args:
+        merged_tasks (list[tuple[str, str]]): List of (task, duration) tuples
+    """
+    logger.info("Task duration breakdown:")
+
+    for task, duration in merged_tasks:
+        logger.info(f"- {task}: {duration} units")
+
+
+def safe_int(val):
+    try:
+        return int(val)
+    except (ValueError, TypeError):
+        return 0
+
+
+def log_total_time(merged_tasks: list[tuple[str, str]]) -> None:
+    """
+    Log the total estimated time for all tasks.
+
+    Args:
+        merged_tasks (list[tuple[str, str]]): List of (task, duration) tuples
+    """
+    total_time = sum(safe_int(time) for _, time in merged_tasks)
+
+    logger.info("Estimated time:")
+    logger.info(f"{total_time} units (30 minutes each)")

src/app.py

@@ -0,0 +1,319 @@
+import os, argparse, logging
+import gradio as gr
+
+logging.basicConfig(level=logging.INFO)
+
+
+from utils.load_secrets import load_secrets
+
+if not os.getenv("NEBIUS_API_KEY") or not os.getenv("NEBIUS_MODEL"):
+    load_secrets("tests/secrets/creds.py")
+
+
+from handlers import (
+    load_data,
+    show_solved,
+    start_timer,
+    auto_poll,
+    show_mock_project_content,
+)
+
+from mcp_handlers import process_message_and_attached_file
+
+from services import MockProjectService
+
+# Store last chat message and file in global variables (for demo purposes)
+last_message_body = None
+last_attached_file = None
+
+
+# =========================
+#           APP
+# =========================
+
+
+def app(debug: bool = False):
+    with gr.Blocks() as demo:
+        gr.Markdown(
+            """
+            # Yuga Planner
+            Yuga Planner is a neuro-symbolic system prototype: it provides an agent-powered team scheduling and task allocation platform built on [Gradio](https://gradio.app/).
+            """
+        )
+
+        with gr.Tab("Information"):
+
+            def get_server_url():
+                try:
+                    return gr.get_state().server_url + "/gradio_api/mcp/sse"
+                except:
+                    return "http://localhost:7860/gradio_api/mcp/sse"
+
+            gr.Markdown(
+                f"""
+                This is a demo of the Yuga Planner system.
+
+                To use as an MCP server:
+                1. Register the MCP server with your client using the URL:
+                ```
+                {get_server_url()}
+                ```
+                2. Call the tool from your client. Example:
+                ```
+                use yuga planner tool @tests/data/calendar.ics
+                Task Description: Create a new AWS VPC
+                ```
+
+                """
+            )
+
+        with gr.Tab("Task Scheduling"):
+            gr.Markdown("### SWE Team Task Scheduling Demo")
+
+            gr.Markdown(
+                """
+                ## Instructions
+                1. Choose a project source - either upload your own project file(s) or select from our mock projects
+                2. Click 'Load Data' to parse, decompose, and estimate tasks
+                3. Click 'Solve' to generate an optimal schedule based on employee skills and availability
+                4. Review the results in the tables below
+                """
+            )
+
+            # Project source selector
+            project_source = gr.Radio(
+                choices=["Upload Project Files", "Use Mock Projects"],
+                value="Upload Project Files",
+                label="Project Source",
+            )
+
+            # Configuration parameters
+            with gr.Row():
+                employee_count = gr.Number(
+                    label="Number of Employees",
+                    value=12,
+                    minimum=1,
+                    maximum=100,
+                    step=1,
+                    precision=0,
+                )
+                days_in_schedule = gr.Number(
+                    label="Days in Schedule",
+                    value=365,
+                    minimum=1,
+                    maximum=365,
+                    step=1,
+                    precision=0,
+                )
+
+            # File upload component (initially visible)
+            with gr.Group(visible=True) as file_upload_group:
+                file_upload = gr.File(
+                    label="Upload Project Files (Markdown)",
+                    file_types=[".md"],
+                    file_count="multiple",
+                )
+
+            # Mock projects dropdown (initially hidden)
+            with gr.Group(visible=False) as mock_projects_group:
+                # Get mock project names from ProjectService
+                available_projects = MockProjectService.get_available_project_names()
+                mock_project_dropdown = gr.Dropdown(
+                    choices=available_projects,
+                    label="Select Mock Projects (multiple selection allowed)",
+                    value=[available_projects[0]] if available_projects else [],
+                    multiselect=True,
+                )
+
+                # Accordion for viewing mock project content
+                with gr.Accordion("📋 Project Content Preview", open=False):
+                    mock_project_content_accordion = gr.Textbox(
+                        label="Project Content",
+                        interactive=False,
+                        lines=15,
+                        max_lines=20,
+                        show_copy_button=True,
+                        placeholder="Select projects above and expand this section to view content...",
+                    )
+
+                # Auto-update content when projects change
+                mock_project_dropdown.change(
+                    show_mock_project_content,
+                    inputs=[mock_project_dropdown],
+                    outputs=[mock_project_content_accordion],
+                )
+
+            # Log Terminal - Always visible for streaming logs
+            gr.Markdown("## Live Log Terminal")
+            log_terminal = gr.Textbox(
+                label="Processing Logs",
+                interactive=False,
+                lines=8,
+                max_lines=15,
+                show_copy_button=True,
+                placeholder="Logs will appear here during data loading...",
+            )
+
+            # Toggle visibility based on project source selection
+            def toggle_visibility(choice):
+                if choice == "Upload Project Files":
+                    return gr.update(visible=True), gr.update(visible=False)
+                else:
+                    return gr.update(visible=False), gr.update(visible=True)
+
+            project_source.change(
+                toggle_visibility,
+                inputs=[project_source],
+                outputs=[file_upload_group, mock_projects_group],
+            )
+
+            # State for LLM output, persists per session
+            llm_output_state = gr.State(value=None)
+            job_id_state = gr.State(value=None)
+            status_text = gr.Textbox(
+                label="Solver Status",
+                interactive=False,
+                lines=8,
+                max_lines=20,
+                show_copy_button=True,
+            )
+
+            with gr.Row():
+                load_btn = gr.Button("Load Data")
+                solve_btn = gr.Button("Solve", interactive=False)  # Initially disabled
+
+            gr.Markdown("## Employees")
+            employees_table = gr.Dataframe(label="Employees", interactive=False)
+
+            gr.Markdown("## Tasks")
+            schedule_table = gr.Dataframe(label="Tasks Table", interactive=False)
+
+            # Outputs: always keep state as last output
+            outputs = [
+                employees_table,
+                schedule_table,
+                job_id_state,
+                status_text,
+                llm_output_state,
+                log_terminal,
+            ]
+
+            # Outputs for load_data that also enables solve button
+            load_outputs = outputs + [solve_btn]
+
+            # Create wrapper function to pass debug flag to auto_poll
+            async def auto_poll_with_debug(job_id, llm_output):
+                return await auto_poll(job_id, llm_output, debug=debug)
+
+            # Timer for polling (not related to state)
+            timer = gr.Timer(2, active=False)
+            timer.tick(
+                auto_poll_with_debug,
+                inputs=[job_id_state, llm_output_state],
+                outputs=outputs,
+            )
+
+            # Create wrapper function to pass debug flag to load_data
+            async def load_data_with_debug(
+                project_source,
+                file_obj,
+                mock_projects,
+                employee_count,
+                days_in_schedule,
+                llm_output,
+                progress=gr.Progress(),
+            ):
+                async for result in load_data(
+                    project_source,
+                    file_obj,
+                    mock_projects,
+                    employee_count,
+                    days_in_schedule,
+                    llm_output,
+                    debug=debug,
+                    progress=progress,
+                ):
+                    yield result
+
+            # Use state as both input and output
+            load_btn.click(
+                load_data_with_debug,
+                inputs=[
+                    project_source,
+                    file_upload,
+                    mock_project_dropdown,
+                    employee_count,
+                    days_in_schedule,
+                    llm_output_state,
+                ],
+                outputs=load_outputs,
+                api_name="load_data",
+            )
+
+            # Create wrapper function to pass debug flag to show_solved
+            async def show_solved_with_debug(state_data, job_id):
+                return await show_solved(state_data, job_id, debug=debug)
+
+            solve_btn.click(
+                show_solved_with_debug,
+                inputs=[llm_output_state, job_id_state],
+                outputs=outputs,
+            ).then(start_timer, inputs=[job_id_state, llm_output_state], outputs=timer)
+
+            if debug:
+
+                def debug_set_state(state):
+                    logging.info(f"DEBUG: Setting state to test_value")
+                    return "Debug: State set!", "test_value"
+
+                def debug_show_state(state):
+                    logging.info(f"DEBUG: Current state is {state}")
+                    return f"Debug: Current state: {state}", gr.update()
+
+                debug_out = gr.Textbox(label="Debug Output")
+                debug_set_btn = gr.Button("Debug Set State")
+                debug_show_btn = gr.Button("Debug Show State")
+
+                debug_set_btn.click(
+                    debug_set_state,
+                    inputs=[llm_output_state],
+                    outputs=[debug_out, llm_output_state],
+                )
+                debug_show_btn.click(
+                    debug_show_state,
+                    inputs=[llm_output_state],
+                    outputs=[debug_out, gr.State()],
+                )
+
+            # Register the MCP tool as an API endpoint
+            gr.api(process_message_and_attached_file)
+
+    return demo
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Yuga Planner - Team Scheduling Application"
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug mode with additional UI controls and logging",
+    )
+    parser.add_argument(
+        "--server-name",
+        default="0.0.0.0",
+        help="Server name/IP to bind to (default: 0.0.0.0)",
+    )
+    parser.add_argument(
+        "--server-port",
+        type=int,
+        default=7860,
+        help="Server port to bind to (default: 7860)",
+    )
+
+    args = parser.parse_args()
+
+    app(debug=args.debug).launch(
+        server_name=args.server_name, server_port=args.server_port, mcp_server=True
+    )

src/constraint_solvers/timetable/analysis/__init__.py

@@ -0,0 +1,9 @@
+"""
+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

@@ -0,0 +1,185 @@
+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/constraints.py

@@ -0,0 +1,223 @@
+### GENERAL IMPORTS ###
+from datetime import date, timedelta
+
+### DOMAIN ###
+from .domain import Employee, Task, ScheduleInfo
+
+### TIMEFOLD ###
+from timefold.solver.score import HardSoftDecimalScore
+from timefold.solver.score._constraint_factory import ConstraintFactory
+from timefold.solver.score._joiners import Joiners
+from timefold.solver.score._group_by import ConstraintCollectors
+from timefold.solver.score._annotations import constraint_provider
+
+
+def get_slot_overlap(task1: Task, task2: Task) -> int:
+    """Calculate the number of overlapping slots between two tasks.
+
+    Args:
+        task1 (Task): The first task.
+        task2 (Task): The second task.
+
+    Returns:
+        int: The number of overlapping slots.
+    """
+    task1_end: int = task1.start_slot + task1.duration_slots
+    task2_end: int = task2.start_slot + task2.duration_slots
+    overlap_start: int = max(task1.start_slot, task2.start_slot)
+    overlap_end: int = min(task1_end, task2_end)
+    return max(0, overlap_end - overlap_start)
+
+
+def get_slot_date(slot: int) -> date:
+    """Convert a slot index to a date.
+
+    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
+
+
+def tasks_violate_sequence_order(task1: Task, task2: Task) -> bool:
+    """Check if two tasks violate the project sequence order.
+
+    Args:
+        task1 (Task): The first task.
+        task2 (Task): The second task.
+
+    Returns:
+        bool: True if task1 should come before task2 but overlaps with it.
+    """
+    # Different tasks only
+    if task1.id == task2.id:
+        return False
+
+    # Both tasks must have project_id attribute
+    if not (hasattr(task1, "project_id") and hasattr(task2, "project_id")):
+        return False
+
+    # Task1 must belong to a project
+    if task1.project_id == "":
+        return False
+
+    # Tasks must be in the same project
+    if task1.project_id != task2.project_id:
+        return False
+
+    # Task1 must have lower sequence number (should come first)
+    if task1.sequence_number >= task2.sequence_number:
+        return False
+
+    # Task1 overlaps with task2 (task1 should finish before task2 starts)
+    return task1.start_slot + task1.duration_slots > task2.start_slot
+
+
+@constraint_provider
+def define_constraints(constraint_factory: ConstraintFactory) -> list:
+    """
+    Define the constraints for the timetable problem.
+
+    Args:
+        constraint_factory (ConstraintFactory): The constraint factory.
+
+    Returns:
+        list[Constraint]: The constraints.
+    """
+    return [
+        # Hard constraints
+        required_skill(constraint_factory),
+        no_overlapping_tasks(constraint_factory),
+        task_within_schedule(constraint_factory),
+        task_fits_in_schedule(constraint_factory),
+        unavailable_employee(constraint_factory),
+        maintain_project_task_order(constraint_factory),
+        # Soft constraints
+        undesired_day_for_employee(constraint_factory),
+        desired_day_for_employee(constraint_factory),
+        balance_employee_task_assignments(constraint_factory),
+    ]
+
+
+### CONSTRAINTS ###
+def required_skill(constraint_factory: ConstraintFactory):
+    return (
+        constraint_factory.for_each(Task)
+        .filter(
+            lambda task: task.employee is not None
+            and task.required_skill not in task.employee.skills
+        )
+        .penalize(HardSoftDecimalScore.ONE_HARD)
+        .as_constraint("Required skill")
+    )
+
+
+def no_overlapping_tasks(constraint_factory: ConstraintFactory):
+    return (
+        constraint_factory.for_each_unique_pair(
+            Task,
+            Joiners.equal(lambda task: task.employee.name),
+            Joiners.overlapping(
+                lambda task: task.start_slot,
+                lambda task: task.start_slot + task.duration_slots,
+            ),
+        )
+        .penalize(HardSoftDecimalScore.ONE_HARD, get_slot_overlap)
+        .as_constraint("No overlapping tasks")
+    )
+
+
+def task_within_schedule(constraint_factory: ConstraintFactory):
+    return (
+        constraint_factory.for_each(Task)
+        .filter(lambda task: task.start_slot < 0)
+        .penalize(HardSoftDecimalScore.ONE_HARD)
+        .as_constraint("Task within schedule")
+    )
+
+
+def task_fits_in_schedule(constraint_factory: ConstraintFactory):
+    return (
+        constraint_factory.for_each(Task)
+        .join(ScheduleInfo)
+        .filter(
+            lambda task, schedule_info: task.start_slot + task.duration_slots
+            > schedule_info.total_slots
+        )
+        .penalize(HardSoftDecimalScore.ONE_HARD)
+        .as_constraint("Task fits in schedule")
+    )
+
+
+def unavailable_employee(constraint_factory: ConstraintFactory):
+    return (
+        constraint_factory.for_each(Task)
+        .filter(
+            lambda task: task.employee is not None
+            and get_slot_date(task.start_slot) in task.employee.unavailable_dates
+        )
+        .penalize(HardSoftDecimalScore.ONE_HARD)
+        .as_constraint("Unavailable employee")
+    )
+
+
+def undesired_day_for_employee(constraint_factory: ConstraintFactory):
+    return (
+        constraint_factory.for_each(Task)
+        .filter(
+            lambda task: task.employee is not None
+            and get_slot_date(task.start_slot) in task.employee.undesired_dates
+        )
+        .penalize(HardSoftDecimalScore.ONE_SOFT)
+        .as_constraint("Undesired day for employee")
+    )
+
+
+def desired_day_for_employee(constraint_factory: ConstraintFactory):
+    return (
+        constraint_factory.for_each(Task)
+        .filter(
+            lambda task: task.employee is not None
+            and get_slot_date(task.start_slot) in task.employee.desired_dates
+        )
+        .reward(HardSoftDecimalScore.ONE_SOFT)
+        .as_constraint("Desired day for employee")
+    )
+
+
+def maintain_project_task_order(constraint_factory: ConstraintFactory):
+    """Ensure tasks within the same project maintain their original order."""
+    return (
+        constraint_factory.for_each(Task)
+        .join(Task)
+        .filter(tasks_violate_sequence_order)
+        .penalize(
+            HardSoftDecimalScore.ONE_SOFT,
+            lambda task1, task2: 100
+            * (task1.start_slot + task1.duration_slots - task2.start_slot),
+        )  # High penalty (100x) proportional to overlap to strongly encourage proper sequencing
+        .as_constraint("Project task sequence order")
+    )
+
+
+def balance_employee_task_assignments(constraint_factory: ConstraintFactory):
+    return (
+        constraint_factory.for_each(Task)
+        .group_by(lambda task: task.employee, ConstraintCollectors.count())
+        .complement(
+            Employee, lambda e: 0
+        )  # Include all employees which are not assigned to any task
+        .group_by(
+            ConstraintCollectors.load_balance(
+                lambda employee, task_count: employee,
+                lambda employee, task_count: task_count,
+            )
+        )
+        .penalize_decimal(
+            HardSoftDecimalScore.ONE_SOFT,
+            lambda load_balance: load_balance.unfairness(),
+        )
+        .as_constraint("Balance employee task assignments")
+    )

src/constraint_solvers/timetable/domain.py

@@ -0,0 +1,138 @@
+from timefold.solver import SolverStatus
+from timefold.solver.domain import *
+from timefold.solver.score import HardSoftDecimalScore
+from datetime import datetime, date
+from typing import Annotated
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Employee:
+    name: Annotated[str, PlanningId]
+    skills: Annotated[set[str], field(default_factory=set)]
+    unavailable_dates: Annotated[set[date], field(default_factory=set)] = field(
+        default_factory=set
+    )
+    undesired_dates: Annotated[set[date], field(default_factory=set)] = field(
+        default_factory=set
+    )
+    desired_dates: Annotated[set[date], field(default_factory=set)] = field(
+        default_factory=set
+    )
+
+    def to_dict(self):
+        return {
+            "name": self.name,
+            "skills": list(self.skills),
+            "unavailable_dates": [d.isoformat() for d in self.unavailable_dates],
+            "undesired_dates": [d.isoformat() for d in self.undesired_dates],
+            "desired_dates": [d.isoformat() for d in self.desired_dates],
+        }
+
+    @staticmethod
+    def from_dict(d):
+        return Employee(
+            name=d["name"],
+            skills=set(d["skills"]),
+            unavailable_dates=set(
+                date.fromisoformat(s) for s in d["unavailable_dates"]
+            ),
+            undesired_dates=set(date.fromisoformat(s) for s in d["undesired_dates"]),
+            desired_dates=set(date.fromisoformat(s) for s in d["desired_dates"]),
+        )
+
+
+@planning_entity
+@dataclass
+class Task:
+    id: Annotated[str, PlanningId]
+    description: str
+    duration_slots: int  # Number of 30-minute slots required
+    start_slot: Annotated[
+        int, PlanningVariable(value_range_provider_refs=["startSlotRange"])
+    ]  # Slot index when the task starts
+    required_skill: str
+    # Identifier for the project this task belongs to (set by the UI when loading multiple project files)
+    project_id: str = ""
+    # Sequence number within the project to maintain original task order
+    sequence_number: int = 0
+    employee: Annotated[
+        Employee | None, PlanningVariable(value_range_provider_refs=["employeeRange"])
+    ] = None
+
+    def to_dict(self):
+        return {
+            "id": self.id,
+            "description": self.description,
+            "duration_slots": self.duration_slots,
+            "start_slot": self.start_slot,
+            "required_skill": self.required_skill,
+            "project_id": self.project_id,
+            "sequence_number": self.sequence_number,
+            "employee": self.employee.to_dict() if self.employee else None,
+        }
+
+    @staticmethod
+    def from_dict(d):
+        return Task(
+            id=d["id"],
+            description=d["description"],
+            duration_slots=d["duration_slots"],
+            start_slot=d["start_slot"],
+            required_skill=d["required_skill"],
+            project_id=d.get("project_id", ""),
+            sequence_number=d.get("sequence_number", 0),
+            employee=Employee.from_dict(d["employee"]) if d["employee"] else None,
+        )
+
+
+@dataclass
+class ScheduleInfo:
+    total_slots: int  # Total number of 30-minute slots in the schedule
+
+    def to_dict(self):
+        return {"total_slots": self.total_slots}
+
+    @staticmethod
+    def from_dict(d):
+        return ScheduleInfo(total_slots=d["total_slots"])
+
+
+@planning_solution
+@dataclass
+class EmployeeSchedule:
+    employees: Annotated[
+        list[Employee],
+        ProblemFactCollectionProperty,
+        ValueRangeProvider(id="employeeRange"),
+    ]
+    tasks: Annotated[list[Task], PlanningEntityCollectionProperty]
+    schedule_info: Annotated[ScheduleInfo, ProblemFactProperty]
+    score: Annotated[HardSoftDecimalScore | None, PlanningScore] = None
+    solver_status: SolverStatus | None = None
+
+    def get_start_slot_range(
+        self,
+    ) -> Annotated[list[int], ValueRangeProvider(id="startSlotRange")]:
+        """Returns all possible start slots."""
+        return list(range(self.schedule_info.total_slots))
+
+    def to_dict(self):
+        return {
+            "employees": [e.to_dict() for e in self.employees],
+            "tasks": [t.to_dict() for t in self.tasks],
+            "schedule_info": self.schedule_info.to_dict(),
+            "score": str(self.score) if self.score is not None else None,
+            "solver_status": str(self.solver_status)
+            if self.solver_status is not None
+            else None,
+        }
+
+    @staticmethod
+    def from_dict(d):
+        return EmployeeSchedule(
+            employees=[Employee.from_dict(e) for e in d["employees"]],
+            tasks=[Task.from_dict(t) for t in d["tasks"]],
+            schedule_info=ScheduleInfo.from_dict(d["schedule_info"]),
+            # score and solver_status are not restored (not needed for state passing)
+        )

src/constraint_solvers/timetable/solver.py

@@ -0,0 +1,25 @@
+from timefold.solver import SolverManager, SolverFactory, SolutionManager
+from timefold.solver.config import (
+    SolverConfig,
+    ScoreDirectorFactoryConfig,
+    TerminationConfig,
+    Duration,
+)
+
+from .domain import *
+from .constraints import define_constraints
+
+
+solver_config: SolverConfig = SolverConfig(
+    solution_class=EmployeeSchedule,
+    entity_class_list=[Task],
+    score_director_factory_config=ScoreDirectorFactoryConfig(
+        constraint_provider_function=define_constraints
+    ),
+    termination_config=TerminationConfig(spent_limit=Duration(seconds=30)),
+)
+
+solver_manager: SolverManager = SolverManager.create(
+    SolverFactory.create(solver_config)
+)
+solution_manager: SolutionManager = SolutionManager.create(solver_manager)

src/domain.py

@@ -0,0 +1,115 @@
+import os
+from dataclasses import dataclass
+
+# =========================
+#        MOCK PROJECTS
+# =========================
+
+MOCK_PROJECTS: dict[str, str] = {
+    "go-rssagg": """# GO-RSSAGG
+
+## Project Description
+RSS aggregator backend written in Go. Features REST API and basic authentication.
+
+## Features
+- User authentication and account management
+- Fetch and parse RSS feeds
+- Store feed content in database
+- REST API to access feeds
+- Follow/unfollow feed functionality
+- Mark posts as read/unread
+
+## Tech Stack
+- Go for backend
+- PostgreSQL for database
+- RESTful API endpoints
+- JWT for authentication
+""",
+    "rust-chess-pipeline": """# RUST CHESS PIPELINE
+
+## Project Description
+Data Pipeline that extracts chess match metrics and match annotations from Excel files, using AWS Lambda and Step Functions written in Rust.
+
+## Features
+- Parse Excel files containing chess match data
+- Extract player statistics, game metadata, and move annotations
+- Calculate performance metrics and ELO adjustments
+- Store results in data warehouse
+- Generate analytical reports
+
+## Tech Stack
+- Rust for core processing logic
+- AWS Lambda for serverless compute
+- AWS Step Functions for orchestration
+- Amazon S3 for storage
+- AWS Glue for ETL processing
+""",
+    "python-ml-forecasting": """# PYTHON ML FORECASTING
+
+## Project Description
+Machine learning service for time-series forecasting of inventory demands, with API endpoints for integration with existing systems.
+
+## Features
+- Historical data ingestion and preprocessing
+- Feature engineering for time-series data
+- Multiple forecasting models (ARIMA, Prophet, LSTM)
+- Model selection and hyperparameter optimization
+- REST API for predictions and model management
+- Visualization of forecasts and confidence intervals
+
+## Tech Stack
+- Python for core functionality
+- FastAPI for REST endpoints
+- PyTorch and scikit-learn for ML models
+- PostgreSQL for metadata storage
+- Docker for containerization
+""",
+}
+
+# =========================
+#        AGENTS CONFIG
+# =========================
+@dataclass
+class AgentsConfig:
+    """Global configuration for all agents"""
+
+    # Model settings
+    nebius_api_key: str
+    nebius_model: str
+
+    # Prompt templates
+    task_splitter_prompt: str = "Split the following task into an accurate and concise tree of required subtasks:\n{{query}}\n\nYour output must be a markdown bullet list, with no additional comments.\n\n"
+    task_evaluator_prompt: str = "Evaluate the elapsed time, in 30 minute units, for a competent human to complete the following task:\n{{query}}\n\nYour output must be a one integer, with no additional comments.\n\n"
+    task_deps_matcher_prompt: str = "Given the following task:\n{{task}}\n\nAnd these available skills:\n{{skills}}\n\nIn this context:\n{{context}}\n\nSelect the most appropriate skill to complete this task. Return only the skill name as a string, with no additional comments or formatting.\n\n"
+
+    # LLM settings
+    timeout: int = 30
+    max_retries: int = 3
+    verify_ssl: bool = True
+    request_timeout: int = 30
+    max_tokens: int = 1024
+    temperature: float = 0.1
+    workflow_timeout: int = 300  # 5 minutes for workflow timeout
+
+    def __post_init__(self):
+        """Validate required configuration"""
+        if not self.nebius_model or not self.nebius_api_key:
+            if self.nebius_model == "dev-model" and self.nebius_api_key == "dev-key":
+                # Development mode - just warn
+                import warnings
+
+                warnings.warn(
+                    "Using development defaults for NEBIUS_MODEL and NEBIUS_API_KEY"
+                )
+            else:
+                raise ValueError(
+                    "NEBIUS_MODEL and NEBIUS_API_KEY environment variables must be set"
+                )
+
+
+# Global configuration instance
+# For development environments where env vars might not be set, use defaults
+AGENTS_CONFIG = AgentsConfig(
+    nebius_api_key=os.getenv("NEBIUS_API_KEY", "dev-key"),
+    nebius_model=os.getenv("NEBIUS_MODEL", "dev-model"),
+)

src/factory/data_generators.py

@@ -0,0 +1,300 @@
+from datetime import date, timedelta
+from random import Random
+from itertools import product
+
+from factory.data_models import *
+from constraint_solvers.timetable.domain import *
+
+
+### EMPLOYEES ###
+FIRST_NAMES = ("Amy", "Beth", "Carl", "Dan", "Elsa", "Flo", "Gus", "Hugo", "Ivy", "Jay")
+LAST_NAMES = (
+    "Cole",
+    "Fox",
+    "Green",
+    "Jones",
+    "King",
+    "Li",
+    "Poe",
+    "Rye",
+    "Smith",
+    "Watt",
+)
+
+
+def generate_employees(
+    parameters: TimeTableDataParameters, random: Random
+) -> list[Employee]:
+    """
+    Generates a list of Employee objects with random names and skills.
+    """
+    name_permutations = [
+        f"{first_name} {last_name}"
+        for first_name, last_name in product(FIRST_NAMES, LAST_NAMES)
+    ]
+
+    random.shuffle(name_permutations)
+
+    employees = []
+    for i in range(parameters.employee_count):
+        (count,) = random.choices(
+            population=counts(parameters.optional_skill_distribution),
+            weights=weights(parameters.optional_skill_distribution),
+        )
+
+        # Ensure we don't try to sample more skills than available
+        count = min(count, len(parameters.skill_set.optional_skills))
+
+        skills = []
+        skills += random.sample(parameters.skill_set.optional_skills, count)
+        skills += random.sample(parameters.skill_set.required_skills, 1)
+        employees.append(Employee(name=name_permutations[i], skills=set(skills)))
+
+    return employees
+
+
+def generate_employee_availability(
+    employees: list[Employee],
+    parameters: TimeTableDataParameters,
+    start_date: date,
+    random: Random,
+) -> None:
+    """
+    Sets up random availability preferences for employees proportional to schedule length.
+
+    For 365 days:
+    - Max 21 unavailable days per employee
+    - Max 0-12 undesired days per employee
+    - Desired dates remain flexible (0-12 days)
+
+    Scales proportionally for different schedule lengths.
+    """
+    days_in_schedule = parameters.days_in_schedule
+
+    # Calculate proportional limits based on 365-day baseline
+    max_unavailable_per_employee = round((21 / 365) * days_in_schedule)
+    max_undesired_per_employee = round((12 / 365) * days_in_schedule)
+    max_desired_per_employee = round((12 / 365) * days_in_schedule)
+
+    # Ensure minimum reasonable values
+    max_unavailable_per_employee = max(1, max_unavailable_per_employee)
+    max_undesired_per_employee = max(0, max_undesired_per_employee)
+    max_desired_per_employee = max(0, max_desired_per_employee)
+
+    # Generate all possible dates in the schedule
+    all_dates = [start_date + timedelta(days=i) for i in range(days_in_schedule)]
+
+    for employee in employees:
+        # Randomly assign unavailable dates (1 to max_unavailable_per_employee)
+        num_unavailable = random.randint(1, max_unavailable_per_employee)
+        unavailable_dates = random.sample(
+            all_dates, min(num_unavailable, len(all_dates))
+        )
+        employee.unavailable_dates.update(unavailable_dates)
+
+        # Remove unavailable dates from remaining pool for other preferences
+        remaining_dates = [d for d in all_dates if d not in employee.unavailable_dates]
+
+        # Randomly assign undesired dates (0 to max_undesired_per_employee)
+        if max_undesired_per_employee > 0 and remaining_dates:
+            num_undesired = random.randint(
+                0, min(max_undesired_per_employee, len(remaining_dates))
+            )
+            if num_undesired > 0:
+                undesired_dates = random.sample(remaining_dates, num_undesired)
+                employee.undesired_dates.update(undesired_dates)
+                remaining_dates = [
+                    d for d in remaining_dates if d not in employee.undesired_dates
+                ]
+
+        # Randomly assign desired dates (0 to max_desired_per_employee)
+        if max_desired_per_employee > 0 and remaining_dates:
+            num_desired = random.randint(
+                0, min(max_desired_per_employee, len(remaining_dates))
+            )
+            if num_desired > 0:
+                desired_dates = random.sample(remaining_dates, num_desired)
+                employee.desired_dates.update(desired_dates)
+
+
+def generate_employee_availability_mcp(
+    employees: list[Employee],
+) -> None:
+    """
+    For MCP data generator: does not set any unavailable, desired, or undesired days for employees.
+    All availability sets remain empty.
+    """
+    for employee in employees:
+        employee.unavailable_dates.clear()
+        employee.undesired_dates.clear()
+        employee.desired_dates.clear()
+
+
+def generate_tasks(
+    parameters: TimeTableDataParameters,
+    random: Random,
+    task_tuples: list[tuple[str, int]],
+) -> list[Task]:
+    """
+    Given a list of (description, duration) tuples, generate Task objects with randomized required_skill.
+    """
+    tasks: list[Task] = []
+
+    ids = generate_task_ids()
+
+    for description, duration in task_tuples:
+        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=description,
+                duration_slots=duration,
+                start_slot=0,  # This will be assigned by the solver
+                required_skill=required_skill,
+            )
+        )
+    return tasks
+
+
+def generate_tasks_from_calendar(
+    parameters: TimeTableDataParameters,
+    random: Random,
+    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.
+    """
+    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
+            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,
+                )
+            )
+        except Exception:
+            continue
+    return tasks
+
+
+def generate_task_ids():
+    current_id = 0
+    while True:
+        yield str(current_id)
+        current_id += 1
+
+
+# =========================
+#     UTILITY FUNCTIONS
+# =========================
+def counts(distributions: tuple[CountDistribution, ...]) -> tuple[int, ...]:
+    """
+    Extracts the count values from a tuple of CountDistribution objects.
+    """
+    return tuple(distribution.count for distribution in distributions)
+
+
+def weights(distributions: tuple[CountDistribution, ...]) -> tuple[float, ...]:
+    """
+    Extracts the weight values from a tuple of CountDistribution objects.
+    """
+    return tuple(distribution.weight for distribution in distributions)
+
+
+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.
+    """
+    days = (7 - target_date.weekday()) % 7
+    return target_date + timedelta(days=days)
+
+
+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 = []
+
+    for sequence_num, task_data in enumerate(agent_output):
+        # Handle both old format (description, duration) and new format (description, duration, skill)
+        if len(task_data) == 3:
+            description, duration, required_skill = task_data
+        elif len(task_data) == 2:
+            description, duration = task_data
+            # Fallback to random assignment if no skill provided
+            import random
+
+            if random.random() >= 0.5:
+                required_skill = random.choice(parameters.skill_set.required_skills)
+            else:
+                required_skill = random.choice(parameters.skill_set.optional_skills)
+        else:
+            continue  # skip invalid task data
+
+        try:
+            duration_int = int(duration)
+        except (ValueError, TypeError):
+            continue  # skip this task if duration is invalid
+
+        # Clean up skill name (remove any extra formatting)
+        if required_skill:
+            required_skill = required_skill.strip()
+            # Ensure the skill exists in our skill set
+            all_skills = list(parameters.skill_set.required_skills) + list(
+                parameters.skill_set.optional_skills
+            )
+            if required_skill not in all_skills:
+                # If skill doesn't match exactly, try to find closest match or fallback to random
+                import random
+
+                required_skill = random.choice(parameters.skill_set.required_skills)
+
+        tasks.append(
+            Task(
+                id=next(ids),
+                description=description,
+                duration_slots=duration_int,
+                start_slot=0,
+                required_skill=required_skill,
+                project_id=project_id,
+                sequence_number=sequence_num,
+            )
+        )
+    return tasks
+
+
+def skills_from_parameters(parameters: TimeTableDataParameters) -> list[str]:
+    return list(parameters.skill_set.required_skills) + list(
+        parameters.skill_set.optional_skills
+    )

src/factory/data_models.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass, field
+
+
+# =========================
+#        DATA MODELS
+# =========================
+@dataclass(frozen=True, kw_only=True)
+class CountDistribution:
+    count: int
+    weight: float
+
+
+@dataclass(frozen=True, kw_only=True)
+class SkillSet:
+    required_skills: tuple[str, ...]
+    optional_skills: tuple[str, ...]
+
+
+@dataclass(kw_only=True)
+class TimeTableDataParameters:
+    skill_set: SkillSet
+    days_in_schedule: int
+    employee_count: int
+    optional_skill_distribution: tuple[CountDistribution, ...]
+    availability_count_distribution: tuple[CountDistribution, ...]
+    random_seed: int = field(default=37)

src/factory/data_provider.py

@@ -0,0 +1,282 @@
+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
+
+from factory.data_generators import *
+from factory.data_models import *
+
+from agents.task_composer_agent import TaskComposerAgent
+
+from constraint_solvers.timetable.domain import *
+
+import logging
+
+logging.basicConfig(level=logging.INFO)
+
+# =========================
+#        CONSTANTS
+# =========================
+
+# Each slot is 30 minutes - 20 slots = 10 hours working day
+SLOTS_PER_DAY = 20
+
+
+# =========================
+#        DEMO PARAMS
+# =========================
+SKILL_SET = SkillSet(
+    required_skills=("Frontend Engineer", "Backend Engineer", "Cloud Engineer"),
+    optional_skills=(
+        "Security Expert",
+        "DevOps Engineer",
+        "Data Engineer",
+        "Network Engineer",
+        "AI Engineer",
+    ),
+)
+
+DATA_PARAMS = TimeTableDataParameters(
+    skill_set=SKILL_SET,
+    days_in_schedule=365,
+    employee_count=12,
+    optional_skill_distribution=(
+        CountDistribution(count=1, weight=3),
+        CountDistribution(count=2, weight=1),
+    ),
+    availability_count_distribution=(
+        CountDistribution(count=5, weight=4),
+        CountDistribution(count=10, weight=3),
+        CountDistribution(count=15, weight=2),
+        CountDistribution(count=20, weight=1),
+    ),
+    random_seed=37,
+)
+
+MCP_PARAMS = TimeTableDataParameters(
+    skill_set=SKILL_SET,
+    days_in_schedule=365,
+    # In this case, we only have one user
+    employee_count=1,
+    optional_skill_distribution=(
+        CountDistribution(count=len(SKILL_SET.optional_skills), weight=1),
+    ),
+    availability_count_distribution=(
+        # Full availability for one user
+        CountDistribution(count=20, weight=1),
+    ),
+    random_seed=37,
+)
+
+
+# =========================
+#        AGENT DATA
+# =========================
+async def generate_agent_data(
+    file, project_id: str = "", employee_count: int = None, days_in_schedule: int = None
+) -> EmployeeSchedule:
+    # Use DATA_PARAMS, but allow override
+    parameters = DATA_PARAMS
+    if employee_count is not None or days_in_schedule is not None:
+        parameters = TimeTableDataParameters(
+            skill_set=parameters.skill_set,
+            days_in_schedule=days_in_schedule
+            if days_in_schedule is not None
+            else parameters.days_in_schedule,
+            employee_count=employee_count
+            if employee_count is not None
+            else parameters.employee_count,
+            optional_skill_distribution=parameters.optional_skill_distribution,
+            availability_count_distribution=parameters.availability_count_distribution,
+            random_seed=parameters.random_seed,
+        )
+
+    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
+
+    if os.getenv("YUGA_DEBUG", "false").lower() == "true":
+        logging.info("FILE OBJECT: %s %s", file, type(file))
+
+    match file:
+        case file if hasattr(file, "read"):
+            input_str = file.read()
+
+        case bytes():
+            input_str = file.decode("utf-8")
+
+        case str() if os.path.exists(file):
+            with open(file, "r", encoding="utf-8") as f:
+                input_str = f.read()
+
+        case str():
+            input_str = file
+
+        case _:
+            raise ValueError(f"Unsupported file type: {type(file)}")
+
+    agent_output = await run_task_composer_agent(input_str, parameters)
+
+    tasks = tasks_from_agent_output(agent_output, parameters, project_id)
+    generate_employee_availability(employees, parameters, start_date, randomizer)
+
+    return EmployeeSchedule(
+        employees=employees,
+        tasks=tasks,
+        schedule_info=ScheduleInfo(total_slots=total_slots),
+    )
+
+
+async def generate_mcp_data(
+    calendar_entries,
+    user_message: str,
+    project_id: str = "PROJECT",
+    employee_count: int = None,
+    days_in_schedule: int = None,
+):
+    parameters = MCP_PARAMS
+    if employee_count is not None or days_in_schedule is not None:
+        parameters = TimeTableDataParameters(
+            skill_set=parameters.skill_set,
+            days_in_schedule=days_in_schedule
+            if days_in_schedule is not None
+            else parameters.days_in_schedule,
+            employee_count=employee_count
+            if employee_count is not None
+            else parameters.employee_count,
+            optional_skill_distribution=parameters.optional_skill_distribution,
+            availability_count_distribution=parameters.availability_count_distribution,
+            random_seed=parameters.random_seed,
+        )
+
+    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
+
+    # Set the single employee's name to 'Chatbot User'
+    if len(employees) == 1:
+        employees[0].name = "Chatbot User"
+    else:
+        raise ValueError("MCP data provider only supports one employee")
+
+    # Ensure all date sets are empty
+    for emp in employees:
+        emp.unavailable_dates.clear()
+        emp.undesired_dates.clear()
+        emp.desired_dates.clear()
+
+    # --- CALENDAR TASKS ---
+    calendar_tasks = generate_tasks_from_calendar(
+        parameters, randomizer, calendar_entries
+    )
+    # Assign project_id 'EXISTING' to all calendar tasks
+    for t in calendar_tasks:
+        t.sequence_number = 0  # will be overwritten later
+        t.employee = employees[0]
+        t.project_id = "EXISTING"
+    # Create DataFrame
+    calendar_df = pd.DataFrame(
+        [
+            {
+                "id": t.id,
+                "description": t.description,
+                "duration_slots": t.duration_slots,
+                "start_slot": t.start_slot,
+                "required_skill": t.required_skill,
+                "sequence_number": t.sequence_number,
+                "employee": t.employee.name if hasattr(t.employee, "name") else None,
+                "project_id": t.project_id,
+            }
+            for t in calendar_tasks
+        ]
+    )
+
+    print("\nCalendar DataFrame:")
+    print(calendar_df)
+
+    # --- 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:
+            t.sequence_number = 0  # will be overwritten later
+            t.employee = employees[0]
+            t.project_id = "PROJECT"
+    llm_df = pd.DataFrame(
+        [
+            {
+                "id": t.id,
+                "description": t.description,
+                "duration_slots": t.duration_slots,
+                "start_slot": t.start_slot,
+                "required_skill": t.required_skill,
+                "sequence_number": t.sequence_number,
+                "employee": t.employee.name if hasattr(t.employee, "name") else None,
+                "project_id": t.project_id,
+            }
+            for t in llm_tasks
+        ]
+    )
+
+    print("\nLLM DataFrame:")
+    print(llm_df)
+
+    # --- MERGE AND ASSIGN SEQUENCE ---
+    all_tasks = calendar_tasks + llm_tasks
+    # Assign sequence_number per project group
+    existing_seq = 0
+    project_seq = 0
+    for t in all_tasks:
+        if t.project_id == "EXISTING":
+            t.sequence_number = existing_seq
+            existing_seq += 1
+        elif t.project_id == "PROJECT":
+            t.sequence_number = project_seq
+            project_seq += 1
+
+    schedule = EmployeeSchedule(
+        employees=employees,
+        tasks=all_tasks,
+        schedule_info=ScheduleInfo(total_slots=total_slots),
+    )
+    final_df = schedule_to_dataframe(schedule)
+    print("\nFinal DataFrame (MCP-aligned):")
+    print(final_df)
+    return final_df
+
+
+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"
+
+    logging.info(f"Starting workflow with timeout: {AGENTS_CONFIG.workflow_timeout}s")
+    logging.info(f"Input length: {len(input_str)} characters")
+    logging.info(f"Available skills: {available_skills}")
+
+    try:
+        agent_output = await agent.run_workflow(
+            query=input_str, skills=available_skills, context=context
+        )
+        logging.info(
+            f"Workflow completed successfully. Generated {len(agent_output)} tasks."
+        )
+        return agent_output
+    except Exception as e:
+        logging.error(f"Workflow failed: {e}")
+        raise

src/handlers.py

@@ -0,0 +1,230 @@
+import logging
+from typing import Tuple, Dict, List, Optional
+
+import pandas as pd
+import gradio as gr
+
+from state import app_state
+
+from services import (
+    LoggingService,
+    ScheduleService,
+    DataService,
+    MockProjectService,
+)
+
+# Global logging service instance for UI streaming
+logging_service = LoggingService()
+
+
+async def show_solved(
+    state_data, job_id: str, debug: bool = False
+) -> Tuple[pd.DataFrame, pd.DataFrame, str, str, object, str]:
+    """Handler for solving a schedule from UI state data"""
+    # Set up log streaming for solving process
+    logging_service.setup_log_streaming()
+
+    logging.info(
+        f"🔧 show_solved called with state_data type: {type(state_data)}, job_id: {job_id}"
+    )
+
+    # Check if data has been loaded
+    if not state_data:
+        logging.warning("❌ No data loaded - cannot solve schedule")
+        return (
+            gr.update(),
+            gr.update(),
+            job_id,
+            "❌ No data loaded. Please click 'Load Data' first to load project data before solving.",
+            state_data,
+            logging_service.get_streaming_logs(),
+        )
+
+    logging.info(f"✅ State data found, proceeding with solve...")
+
+    try:
+        # Use the schedule service to solve the schedule
+        (
+            emp_df,
+            solved_task_df,
+            new_job_id,
+            status,
+            state_data,
+        ) = await ScheduleService.solve_schedule_from_state(
+            state_data, job_id, debug=debug
+        )
+
+        logging.info(f"✅ Solver completed successfully, returning results")
+
+        return (
+            emp_df,
+            solved_task_df,
+            new_job_id,
+            status,
+            state_data,
+            logging_service.get_streaming_logs(),
+        )
+    except Exception as e:
+        logging.error(f"Error in show_solved: {e}")
+        return (
+            gr.update(),
+            gr.update(),
+            job_id,
+            f"❌ Error solving schedule: {str(e)}",
+            state_data,
+            logging_service.get_streaming_logs(),
+        )
+
+
+def show_mock_project_content(project_names) -> str:
+    """Handler for displaying mock project content"""
+    return MockProjectService.show_mock_project_content(project_names)
+
+
+async def load_data(
+    project_source: str,
+    file_obj,
+    mock_projects,
+    employee_count: int,
+    days_in_schedule: int,
+    llm_output,
+    debug: bool = False,
+    progress=gr.Progress(),
+):
+    """
+    Handler for data loading from either file uploads or mock projects - streaming version
+    Yields intermediate updates for real-time progress
+    """
+    # Set up log streaming and clear previous logs
+    logging_service.setup_log_streaming()
+    logging_service.clear_streaming_logs()
+
+    # Initial log message
+    logging.info("🚀 Starting data loading process...")
+
+    # Yield initial state
+    yield (
+        gr.update(),  # employees_table
+        gr.update(),  # schedule_table
+        gr.update(),  # job_id_state
+        "Starting data loading...",  # status_text
+        gr.update(),  # llm_output_state
+        logging_service.get_streaming_logs(),  # log_terminal
+        gr.update(interactive=False),  # solve_btn - keep disabled during loading
+    )
+
+    try:
+        # Use the data service to load data from sources
+        (
+            emp_df,
+            task_df,
+            job_id,
+            status_message,
+            state_data,
+        ) = await DataService.load_data_from_sources(
+            project_source,
+            file_obj,
+            mock_projects,
+            employee_count,
+            days_in_schedule,
+            debug,
+        )
+
+        # Store schedule for later use
+        app_state.add_solved_schedule(job_id, None)  # Will be populated when solved
+
+        # Final yield with complete results
+        yield (
+            emp_df,  # employees_table
+            task_df,  # schedule_table
+            job_id,  # job_id_state
+            status_message,  # status_text
+            state_data,  # llm_output_state
+            logging_service.get_streaming_logs(),  # log_terminal with accumulated logs
+            gr.update(interactive=True),  # solve_btn - enable after successful loading
+        )
+
+    except Exception as e:
+        logging.error(f"Error loading data: {e}")
+        yield (
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            f"Error loading data: {str(e)}",
+            gr.update(),
+            logging_service.get_streaming_logs(),  # log_terminal
+            gr.update(interactive=False),  # solve_btn - keep disabled on error
+        )
+
+
+def start_timer(job_id, llm_output) -> gr.Timer:
+    """Handler for starting the polling timer"""
+    return ScheduleService.start_timer(job_id, llm_output)
+
+
+def poll_solution(
+    job_id: str, schedule, debug: bool = False
+) -> Tuple[pd.DataFrame, pd.DataFrame, str, str, object, str]:
+    """Handler for polling a solution for a given job_id"""
+    try:
+        (
+            emp_df,
+            task_df,
+            job_id,
+            status_message,
+            schedule,
+        ) = ScheduleService.poll_solution(job_id, schedule, debug)
+
+        return (
+            emp_df,
+            task_df,
+            job_id,
+            status_message,
+            schedule,
+            gr.update(),  # log_terminal
+        )
+
+    except Exception as e:
+        logging.error(f"Error in poll_solution: {e}")
+        return (
+            gr.update(),
+            gr.update(),
+            job_id,
+            f"Error polling solution: {str(e)}",
+            schedule,
+            gr.update(),  # log_terminal
+        )
+
+
+async def auto_poll(
+    job_id: str, llm_output: dict, debug: bool = False
+) -> Tuple[pd.DataFrame, pd.DataFrame, str, str, dict, str]:
+    """Handler for automatic polling of updates"""
+    try:
+        (
+            emp_df,
+            task_df,
+            job_id,
+            status_message,
+            llm_output,
+        ) = await ScheduleService.auto_poll(job_id, llm_output, debug)
+
+        return (
+            emp_df,  # employees_table
+            task_df,  # schedule_table
+            job_id,  # job_id_state
+            status_message,  # status_text
+            llm_output,  # llm_output_state
+            logging_service.get_streaming_logs(),  # log_terminal
+        )
+
+    except Exception as e:
+        logging.error(f"Error in auto_poll: {e}")
+        return (
+            gr.update(),
+            gr.update(),
+            job_id,
+            f"Error in auto polling: {str(e)}",
+            llm_output,
+            logging_service.get_streaming_logs(),  # log_terminal
+        )

src/helpers.py

@@ -0,0 +1,115 @@
+from datetime import datetime, timedelta
+import pandas as pd
+
+
+def schedule_to_dataframe(schedule) -> pd.DataFrame:
+    """
+    Convert an EmployeeSchedule to a pandas DataFrame.
+
+    Args:
+        schedule (EmployeeSchedule): The schedule to convert.
+
+    Returns:
+        pd.DataFrame: The converted DataFrame.
+    """
+    data: list[dict[str, str]] = []
+
+    # Process each task in the schedule
+    for task in schedule.tasks:
+        # 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
+        start_time: datetime = datetime.now() + timedelta(minutes=30 * task.start_slot)
+        end_time: datetime = start_time + timedelta(minutes=30 * task.duration_slots)
+
+        # Add task data to list with availability flags
+        data.append(
+            {
+                "Project": getattr(task, "project_id", ""),
+                "Sequence": getattr(task, "sequence_number", 0),
+                "Employee": employee,
+                "Task": task.description,
+                "Start": start_time,
+                "End": end_time,
+                "Duration (hours)": task.duration_slots / 2,  # Convert slots to hours
+                "Required Skill": task.required_skill,
+                # Check if task falls on employee's unavailable date
+                "Unavailable": employee != "Unassigned"
+                and hasattr(task.employee, "unavailable_dates")
+                and start_time.date() in task.employee.unavailable_dates,
+                # Check if task falls on employee's undesired date
+                "Undesired": employee != "Unassigned"
+                and hasattr(task.employee, "undesired_dates")
+                and start_time.date() in task.employee.undesired_dates,
+                # Check if task falls on employee's desired date
+                "Desired": employee != "Unassigned"
+                and hasattr(task.employee, "desired_dates")
+                and start_time.date() in task.employee.desired_dates,
+            }
+        )
+
+    return pd.DataFrame(data)
+
+
+def employees_to_dataframe(schedule) -> pd.DataFrame:
+    """
+    Convert an EmployeeSchedule to a pandas DataFrame.
+
+    Args:
+        schedule (EmployeeSchedule): The schedule to convert.
+    """
+
+    def format_dates(dates_list, max_display=3):
+        """Helper function to format dates for display"""
+        if not dates_list:
+            return "None"
+        try:
+            sorted_dates = sorted(dates_list)
+            if len(sorted_dates) <= max_display:
+                return ", ".join(d.strftime("%m/%d") for d in sorted_dates)
+            else:
+                displayed = ", ".join(
+                    d.strftime("%m/%d") for d in sorted_dates[:max_display]
+                )
+                return f"{displayed} (+{len(sorted_dates) - max_display} more)"
+        except Exception:
+            return f"{len(dates_list)} dates"
+
+    data: list[dict[str, str]] = []
+
+    for emp in schedule.employees:
+        try:
+            first, last = emp.name.split(" ", 1) if " " in emp.name else (emp.name, "")
+
+            # Safely get preference dates with fallback to empty sets
+            unavailable_dates = getattr(emp, "unavailable_dates", set())
+            undesired_dates = getattr(emp, "undesired_dates", set())
+            desired_dates = getattr(emp, "desired_dates", set())
+
+            data.append(
+                {
+                    "First Name": first,
+                    "Last Name": last,
+                    "Skills": ", ".join(sorted(emp.skills)),
+                    "Unavailable Dates": format_dates(unavailable_dates),
+                    "Undesired Dates": format_dates(undesired_dates),
+                    "Desired Dates": format_dates(desired_dates),
+                    "Total Preferences": f"{len(unavailable_dates)} unavailable, {len(undesired_dates)} undesired, {len(desired_dates)} desired",
+                }
+            )
+        except Exception as e:
+            # Fallback for any employee that causes issues
+            data.append(
+                {
+                    "First Name": str(emp.name),
+                    "Last Name": "",
+                    "Skills": ", ".join(sorted(getattr(emp, "skills", []))),
+                    "Unavailable Dates": "Error loading",
+                    "Undesired Dates": "Error loading",
+                    "Desired Dates": "Error loading",
+                    "Total Preferences": "Error loading preferences",
+                }
+            )
+
+    return pd.DataFrame(data)

src/mcp_handlers.py

@@ -0,0 +1,116 @@
+import os
+from dataclasses import dataclass
+import uuid
+import time
+import asyncio
+
+from utils.extract_calendar import extract_ical_entries
+from factory.data_provider import generate_mcp_data
+from services.schedule_service import ScheduleService
+
+
+@dataclass
+class MCPProcessingResult:
+    user_message: str
+    file: str
+    calendar_entries: list = None
+    error: str = None
+    solved_task_df: object = None
+    status: str = None
+    score: object = None
+
+
+async def process_message_and_attached_file(file_path: str, message_body: str) -> dict:
+    """
+    Store the last chat message and attached file, echo the message, extract calendar entries, generate tasks, solve, and poll for the solution.
+    Args:
+        file_path (str): Path to the attached file
+        message_body (str): The body of the last chat message, which contains the task description
+    Returns:
+        dict: Contains confirmation, file info, calendar entries, error, and solved schedule info
+    """
+    try:
+        with open(file_path, "rb") as f:
+            file_bytes = f.read()
+    except Exception as e:
+        result = MCPProcessingResult(
+            user_message="",
+            file="",
+            calendar_entries=[],
+            error=f"Failed to read file: {e}",
+        )
+        return result.__dict__
+
+    # Try to extract calendar entries
+    entries, error = extract_ical_entries(file_bytes)
+    if error:
+        result = MCPProcessingResult(
+            user_message=f"Received your message: {message_body}",
+            file=os.path.basename(file_path),
+            error=f"File is not a valid calendar file: {error}",
+        )
+        return result.__dict__
+
+    # Generate MCP DataFrame
+    df = await generate_mcp_data(entries, message_body)
+    if df is None or df.empty:
+        result = MCPProcessingResult(
+            user_message=f"Received your message: {message_body}",
+            file=os.path.basename(file_path),
+            calendar_entries=entries,
+            error="Failed to generate MCP data.",
+        )
+        return result.__dict__
+
+    # Build state_data for the solver
+    state_data = {
+        "task_df_json": df.to_json(orient="split"),
+        "employee_count": 1,
+        "days_in_schedule": 365,
+    }
+    job_id = str(uuid.uuid4())
+    (
+        emp_df,
+        solved_task_df,
+        new_job_id,
+        status,
+        state_data,
+    ) = await ScheduleService.solve_schedule_from_state(state_data, job_id, debug=True)
+
+    # Poll for the solution until the status string does not contain 'Solving'
+    max_wait = 30  # seconds
+    interval = 0.5
+    waited = 0
+    final_task_df = None
+    final_status = None
+    final_score = None
+    solved = False
+    while waited < max_wait:
+        (
+            _,
+            polled_task_df,
+            _,
+            polled_status,
+            solved_schedule,
+        ) = ScheduleService.poll_solution(new_job_id, None, debug=True)
+        if polled_status and "Solving" not in polled_status:
+            final_task_df = polled_task_df
+            final_status = polled_status
+            final_score = getattr(solved_schedule, "score", None)
+            solved = True
+            break
+        await asyncio.sleep(interval)
+        waited += interval
+
+    result = MCPProcessingResult(
+        user_message=f"Received your message: {message_body}",
+        file=os.path.basename(file_path),
+        calendar_entries=entries,
+        solved_task_df=final_task_df.to_dict(orient="records")
+        if final_task_df is not None
+        else None,
+        status=final_status,
+        score=final_score,
+        error=None if solved else "Solver did not finish within the timeout",
+    )
+    return result.__dict__

src/services/__init__.py

@@ -0,0 +1,17 @@
+"""
+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
+
+__all__ = [
+    "LoggingService",
+    "ScheduleService",
+    "DataService",
+    "MockProjectService",
+]

src/services/data_service.py

@@ -0,0 +1,309 @@
+import os
+import uuid
+import logging
+from datetime import datetime
+from io import StringIO
+from typing import Dict, List, Tuple, Union, Optional, Any
+
+import pandas as pd
+
+from factory.data_provider import (
+    generate_agent_data,
+    DATA_PARAMS,
+    TimeTableDataParameters,
+    SLOTS_PER_DAY,
+)
+
+from constraint_solvers.timetable.domain import (
+    EmployeeSchedule,
+    ScheduleInfo,
+    Task,
+    Employee,
+)
+
+from helpers import schedule_to_dataframe, employees_to_dataframe
+from .mock_projects_service import MockProjectService
+
+
+class DataService:
+    """Service for handling data loading and processing operations"""
+
+    @staticmethod
+    async def load_data_from_sources(
+        project_source: str,
+        file_obj: Any,
+        mock_projects: Union[str, List[str], None],
+        employee_count: int,
+        days_in_schedule: int,
+        debug: bool = False,
+    ) -> Tuple[pd.DataFrame, pd.DataFrame, str, str, Dict[str, Any]]:
+        """
+        Handle data loading from either file uploads or mock projects.
+
+        Args:
+            project_source: Source type ("Upload Project Files" or mock projects)
+            file_obj: Uploaded file object(s)
+            mock_projects: Selected mock project names
+            employee_count: Number of employees to generate
+            days_in_schedule: Number of days in the schedule
+            debug: Enable debug logging
+
+        Returns:
+            Tuple of (emp_df, task_df, job_id, status_message, state_data)
+        """
+        if project_source == "Upload Project Files":
+            files, project_source_info = DataService._process_uploaded_files(file_obj)
+        else:
+            files, project_source_info = DataService._process_mock_projects(
+                mock_projects
+            )
+
+        logging.info(f"🔄 Processing {len(files)} project(s)...")
+
+        combined_tasks: List[Task] = []
+        combined_employees: Dict[str, Employee] = {}
+
+        # Process each file/project
+        for idx, single_file in enumerate(files):
+            project_id = DataService._derive_project_id(
+                project_source, single_file, mock_projects, idx
+            )
+
+            logging.info(f"⚙️ Processing project {idx+1}/{len(files)}: '{project_id}'")
+
+            schedule_part: EmployeeSchedule = await generate_agent_data(
+                single_file,
+                project_id=project_id,
+                employee_count=employee_count,
+                days_in_schedule=days_in_schedule,
+            )
+            logging.info(f"✅ Completed processing project '{project_id}'")
+
+            # Merge employees (unique by name)
+            for emp in schedule_part.employees:
+                if emp.name not in combined_employees:
+                    combined_employees[emp.name] = emp
+
+            # Append tasks with project id already set
+            combined_tasks.extend(schedule_part.tasks)
+
+        logging.info(
+            f"👥 Merging data: {len(combined_employees)} unique employees, {len(combined_tasks)} total tasks"
+        )
+
+        # Build final schedule
+        final_schedule = DataService._build_final_schedule(
+            combined_employees, combined_tasks, employee_count, days_in_schedule
+        )
+
+        # Convert to DataFrames
+        emp_df, task_df = DataService._convert_to_dataframes(final_schedule, debug)
+
+        # Generate job ID and state data
+        job_id = str(uuid.uuid4())
+        state_data = {
+            "task_df_json": task_df.to_json(orient="split"),
+            "employee_count": employee_count,
+            "days_in_schedule": days_in_schedule,
+        }
+
+        status_message = f"Data loaded successfully from {project_source_info}"
+        logging.info("🎉 Data loading completed successfully!")
+
+        return emp_df, task_df, job_id, status_message, state_data
+
+    @staticmethod
+    def _process_uploaded_files(file_obj: Any) -> Tuple[List[Any], str]:
+        """Process uploaded files and return file list and description"""
+        if file_obj is None:
+            raise ValueError("No file uploaded. Please upload a file.")
+
+        # Support multiple files. Gradio returns a list when multiple files are selected.
+        files = file_obj if isinstance(file_obj, list) else [file_obj]
+        project_source_info = f"{len(files)} file(s)"
+        logging.info(f"📄 Found {len(files)} file(s) to process")
+
+        return files, project_source_info
+
+    @staticmethod
+    def _process_mock_projects(
+        mock_projects: Union[str, List[str], None]
+    ) -> Tuple[List[str], str]:
+        """Process mock projects and return file contents and description"""
+        if not mock_projects:
+            raise ValueError("Please select at least one mock project.")
+
+        # Ensure mock_projects is a list
+        if isinstance(mock_projects, str):
+            mock_projects = [mock_projects]
+
+        # Validate all selected mock projects
+        invalid_projects = MockProjectService.validate_mock_projects(mock_projects)
+        if invalid_projects:
+            raise ValueError(
+                f"Invalid mock projects selected: {', '.join(invalid_projects)}"
+            )
+
+        # Get file contents for mock projects
+        files = MockProjectService.get_mock_project_files(mock_projects)
+        project_source_info = (
+            f"{len(mock_projects)} mock project(s): {', '.join(mock_projects)}"
+        )
+        logging.info(f"📋 Selected mock projects: {', '.join(mock_projects)}")
+
+        return files, project_source_info
+
+    @staticmethod
+    def _derive_project_id(
+        project_source: str,
+        single_file: Any,
+        mock_projects: Union[str, List[str], None],
+        idx: int,
+    ) -> str:
+        """Derive project ID from file or mock project"""
+        if project_source == "Upload Project Files":
+            try:
+                return os.path.splitext(os.path.basename(single_file.name))[0]
+            except AttributeError:
+                return f"project_{idx+1}"
+        else:
+            # For mock projects, use the mock project name as the project ID
+            if isinstance(mock_projects, list):
+                return mock_projects[idx]
+            return mock_projects or f"project_{idx+1}"
+
+    @staticmethod
+    def _build_final_schedule(
+        combined_employees: Dict[str, Employee],
+        combined_tasks: List[Task],
+        employee_count: Optional[int],
+        days_in_schedule: Optional[int],
+    ) -> EmployeeSchedule:
+        """Build the final schedule with custom parameters if provided"""
+        parameters: TimeTableDataParameters = DATA_PARAMS
+
+        # Override with custom parameters if provided
+        if employee_count is not None or days_in_schedule is not None:
+            logging.info(
+                f"⚙️ Customizing parameters: {employee_count} employees, {days_in_schedule} days"
+            )
+            parameters = TimeTableDataParameters(
+                skill_set=parameters.skill_set,
+                days_in_schedule=days_in_schedule
+                if days_in_schedule is not None
+                else parameters.days_in_schedule,
+                employee_count=employee_count
+                if employee_count is not None
+                else parameters.employee_count,
+                optional_skill_distribution=parameters.optional_skill_distribution,
+                availability_count_distribution=parameters.availability_count_distribution,
+                random_seed=parameters.random_seed,
+            )
+
+        logging.info("🏗️ Building final schedule structure...")
+        return EmployeeSchedule(
+            employees=list(combined_employees.values()),
+            tasks=combined_tasks,
+            schedule_info=ScheduleInfo(
+                total_slots=parameters.days_in_schedule * SLOTS_PER_DAY
+            ),
+        )
+
+    @staticmethod
+    def _convert_to_dataframes(
+        schedule: EmployeeSchedule, debug: bool = False
+    ) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """Convert schedule to DataFrames for display"""
+        logging.info("📊 Converting to data tables...")
+        emp_df: pd.DataFrame = employees_to_dataframe(schedule)
+        task_df: pd.DataFrame = schedule_to_dataframe(schedule)
+
+        # Sort by project and sequence to maintain original order
+        task_df = task_df[
+            [
+                "Project",
+                "Sequence",
+                "Employee",
+                "Task",
+                "Start",
+                "End",
+                "Duration (hours)",
+                "Required Skill",
+            ]
+        ].sort_values(["Project", "Sequence"])
+
+        if debug:
+            # Log sequence numbers for debugging
+            logging.info("Task sequence numbers after load_data:")
+            for _, row in task_df.iterrows():
+                logging.info(
+                    f"Project: {row['Project']}, Sequence: {row['Sequence']}, Task: {row['Task']}"
+                )
+            logging.info("Task DataFrame being set in load_data: %s", task_df.head())
+
+        return emp_df, task_df
+
+    @staticmethod
+    def parse_task_data_from_json(
+        task_df_json: str, debug: bool = False
+    ) -> pd.DataFrame:
+        """
+        Parse task data from JSON string.
+
+        Args:
+            task_df_json: JSON string containing task data
+            debug: Enable debug logging
+
+        Returns:
+            DataFrame containing task data
+        """
+        if not task_df_json:
+            raise ValueError("No task_df_json provided")
+
+        try:
+            logging.info("📋 Parsing task data from JSON...")
+            task_df: pd.DataFrame = pd.read_json(StringIO(task_df_json), orient="split")
+            logging.info(f"📊 Found {len(task_df)} tasks to schedule")
+
+            if debug:
+                logging.info("Task sequence numbers from JSON:")
+                for _, row in task_df.iterrows():
+                    logging.info(
+                        f"Project: {row.get('Project', 'N/A')}, Sequence: {row.get('Sequence', 'N/A')}, Task: {row['Task']}"
+                    )
+
+            return task_df
+        except Exception as e:
+            logging.error(f"❌ Error parsing task_df_json: {e}")
+            raise ValueError(f"Error parsing task data: {str(e)}")
+
+    @staticmethod
+    def convert_dataframe_to_tasks(task_df: pd.DataFrame) -> List[Task]:
+        """
+        Convert a DataFrame to a list of Task objects.
+
+        Args:
+            task_df: DataFrame containing task data
+
+        Returns:
+            List of Task objects
+        """
+        logging.info("🆔 Generating task IDs and converting to solver format...")
+        ids = (str(i) for i in range(len(task_df)))
+
+        tasks = []
+        for _, row in task_df.iterrows():
+            tasks.append(
+                Task(
+                    id=next(ids),
+                    description=row["Task"],
+                    duration_slots=int(float(row["Duration (hours)"]) * 2),
+                    start_slot=0,
+                    required_skill=row["Required Skill"],
+                    project_id=row.get("Project", ""),
+                    sequence_number=int(row.get("Sequence", 0)),
+                )
+            )
+
+        logging.info(f"✅ Converted {len(tasks)} tasks for solver")
+        return tasks

src/services/logging_service.py

@@ -0,0 +1,80 @@
+import logging
+import threading
+from datetime import datetime
+from typing import List
+
+
+class LogCapture:
+    """Helper class to capture logs for streaming to UI"""
+
+    def __init__(self):
+        self.logs: List[str] = []
+        self.lock = threading.Lock()
+
+    def add_log(self, message: str) -> None:
+        """Add a log message with timestamp"""
+        with self.lock:
+            timestamp = datetime.now().strftime("%H:%M:%S")
+            self.logs.append(f"[{timestamp}] {message}")
+
+    def get_logs(self) -> str:
+        """Get all accumulated logs as a single string"""
+        with self.lock:
+            return "\n".join(self.logs)
+
+    def clear(self) -> None:
+        """Clear all accumulated logs"""
+        with self.lock:
+            self.logs.clear()
+
+
+class StreamingLogHandler(logging.Handler):
+    """Custom log handler that captures logs for UI streaming"""
+
+    def __init__(self, log_capture: LogCapture):
+        super().__init__()
+        self.log_capture = log_capture
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            msg = self.format(record)
+            self.log_capture.add_log(msg)
+        except Exception:
+            self.handleError(record)
+
+
+class LoggingService:
+    """Service for managing log streaming and capture for the UI"""
+
+    def __init__(self):
+        self.log_capture = LogCapture()
+        self._handler_added = False
+
+    def setup_log_streaming(self) -> None:
+        """Set up log streaming to capture logs for UI"""
+        logger = logging.getLogger()
+
+        # Remove existing handlers to avoid duplicate logs
+        for handler in logger.handlers[:]:
+            if isinstance(handler, StreamingLogHandler):
+                logger.removeHandler(handler)
+
+        # Add our streaming handler
+        stream_handler = StreamingLogHandler(self.log_capture)
+        stream_handler.setLevel(logging.INFO)
+        formatter = logging.Formatter("%(levelname)s - %(message)s")
+        stream_handler.setFormatter(formatter)
+        logger.addHandler(stream_handler)
+        self._handler_added = True
+
+    def get_streaming_logs(self) -> str:
+        """Get accumulated logs for streaming to UI"""
+        return self.log_capture.get_logs()
+
+    def clear_streaming_logs(self) -> None:
+        """Clear accumulated logs"""
+        self.log_capture.clear()
+
+    def is_setup(self) -> bool:
+        """Check if log streaming is set up"""
+        return self._handler_added

src/services/mock_projects_service.py

@@ -0,0 +1,90 @@
+from typing import List, Union
+from domain import MOCK_PROJECTS
+
+
+class MockProjectService:
+    """Service for handling project-related operations"""
+
+    @staticmethod
+    def show_mock_project_content(project_names: Union[str, List[str]]) -> str:
+        """
+        Display the content of selected mock projects.
+
+        Args:
+            project_names: Single project name or list of project names
+
+        Returns:
+            Formatted content of the selected projects
+        """
+        if not project_names:
+            return "No projects selected."
+
+        # Handle both single string and list of strings
+        if isinstance(project_names, str):
+            project_names = [project_names]
+
+        content_parts = []
+        for project_name in project_names:
+            if project_name in MOCK_PROJECTS:
+                content_parts.append(
+                    f"=== {project_name.upper()} ===\n\n{MOCK_PROJECTS[project_name]}"
+                )
+            else:
+                content_parts.append(
+                    f"=== {project_name.upper()} ===\n\nProject not found."
+                )
+
+        return (
+            "\n\n" + "=" * 50 + "\n\n".join(content_parts)
+            if content_parts
+            else "No valid projects selected."
+        )
+
+    @staticmethod
+    def validate_mock_projects(mock_projects: Union[str, List[str]]) -> List[str]:
+        """
+        Validate mock project selections and return list of invalid projects.
+
+        Args:
+            mock_projects: Single project name or list of project names
+
+        Returns:
+            List of invalid project names (empty if all valid)
+        """
+        if not mock_projects:
+            return []
+
+        if isinstance(mock_projects, str):
+            mock_projects = [mock_projects]
+
+        return [p for p in mock_projects if p not in MOCK_PROJECTS]
+
+    @staticmethod
+    def get_mock_project_files(mock_projects: Union[str, List[str]]) -> List[str]:
+        """
+        Get file contents for selected mock projects.
+
+        Args:
+            mock_projects: Single project name or list of project names
+
+        Returns:
+            List of project file contents
+        """
+        if isinstance(mock_projects, str):
+            mock_projects = [mock_projects]
+
+        return [
+            MOCK_PROJECTS[project]
+            for project in mock_projects
+            if project in MOCK_PROJECTS
+        ]
+
+    @staticmethod
+    def get_available_project_names() -> List[str]:
+        """
+        Get list of available mock project names.
+
+        Returns:
+            List of available project names
+        """
+        return list(MOCK_PROJECTS.keys())

src/services/schedule_service.py

@@ -0,0 +1,345 @@
+import uuid
+import logging
+import random
+from datetime import datetime
+from typing import Tuple, Dict, Any, Optional
+
+import pandas as pd
+import gradio as gr
+
+from state import app_state
+from constraint_solvers.timetable.solver import solver_manager
+from factory.data_provider import (
+    generate_employees,
+    generate_employee_availability,
+    DATA_PARAMS,
+    TimeTableDataParameters,
+    SLOTS_PER_DAY,
+)
+
+from constraint_solvers.timetable.domain import (
+    EmployeeSchedule,
+    ScheduleInfo,
+    Task,
+)
+
+from helpers import schedule_to_dataframe, employees_to_dataframe
+from .data_service import DataService
+from constraint_solvers.timetable.analysis import ConstraintViolationAnalyzer
+
+
+class ScheduleService:
+    """Service for handling schedule solving and management operations"""
+
+    @staticmethod
+    async def solve_schedule_from_state(
+        state_data: Dict[str, Any], job_id: str, debug: bool = False
+    ) -> Tuple[pd.DataFrame, pd.DataFrame, str, str, Dict[str, Any]]:
+        """
+        Solve a schedule from state data.
+
+        Args:
+            state_data: State data containing task information and parameters
+            job_id: Job identifier for tracking
+            debug: Enable debug logging
+
+        Returns:
+            Tuple of (emp_df, task_df, new_job_id, status_message, state_data)
+        """
+        logging.info(f"🔧 solve_schedule_from_state called with job_id: {job_id}")
+        logging.info("🚀 Starting solve process...")
+
+        # Set debug environment variable for constraint system
+        import os
+
+        if debug:
+            os.environ["YUGA_DEBUG"] = "true"
+        else:
+            os.environ["YUGA_DEBUG"] = "false"
+
+        # Handle both old format (string) and new format (dict) for backward compatibility
+        if isinstance(state_data, str):
+            task_df_json = state_data
+            employee_count = None
+            days_in_schedule = None
+        elif isinstance(state_data, dict):
+            task_df_json = state_data.get("task_df_json")
+            employee_count = state_data.get("employee_count")
+            days_in_schedule = state_data.get("days_in_schedule")
+        else:
+            task_df_json = None
+            employee_count = None
+            days_in_schedule = None
+
+        if not task_df_json:
+            logging.warning("❌ No task_df_json provided to solve_schedule_from_state")
+            return (
+                gr.update(),
+                gr.update(),
+                None,
+                "No schedule to solve. Please load data first using the 'Load Data' button.",
+                None,
+            )
+
+        try:
+            # Parse task data
+            task_df = DataService.parse_task_data_from_json(task_df_json, debug)
+
+            # Convert DataFrame to tasks
+            tasks = DataService.convert_dataframe_to_tasks(task_df)
+
+            # Debug: Log task information if debug is enabled
+            if debug:
+                logging.info("🔍 DEBUG: Task information for constraint checking:")
+                for task in tasks:
+                    logging.info(
+                        f"  Task ID: {task.id}, Project: '{task.project_id}', "
+                        f"Sequence: {task.sequence_number}, Description: '{task.description[:30]}...'"
+                    )
+
+            # Generate schedule
+            schedule = ScheduleService._generate_schedule_for_solving(
+                tasks, employee_count, days_in_schedule
+            )
+
+            # Start solving
+            (
+                emp_df,
+                solved_task_df,
+                new_job_id,
+                status,
+            ) = await ScheduleService._solve_schedule(schedule, debug)
+
+            logging.info("📈 Solver process initiated successfully")
+            return emp_df, solved_task_df, new_job_id, status, state_data
+
+        except Exception as e:
+            logging.error(f"Error in solve_schedule_from_state: {e}")
+            return (
+                gr.update(),
+                gr.update(),
+                None,
+                f"Error solving schedule: {str(e)}",
+                state_data,
+            )
+
+    @staticmethod
+    def _generate_schedule_for_solving(
+        tasks: list, employee_count: Optional[int], days_in_schedule: Optional[int]
+    ) -> EmployeeSchedule:
+        """Generate a complete schedule ready for solving"""
+        parameters: TimeTableDataParameters = DATA_PARAMS
+
+        # Override parameters if provided from UI
+        if employee_count is not None or days_in_schedule is not None:
+            parameters = TimeTableDataParameters(
+                skill_set=parameters.skill_set,
+                days_in_schedule=days_in_schedule
+                if days_in_schedule is not None
+                else parameters.days_in_schedule,
+                employee_count=employee_count
+                if employee_count is not None
+                else parameters.employee_count,
+                optional_skill_distribution=parameters.optional_skill_distribution,
+                availability_count_distribution=parameters.availability_count_distribution,
+                random_seed=parameters.random_seed,
+            )
+
+        logging.info("👥 Generating employees and availability...")
+        start_date = datetime.now().date()
+        randomizer = random.Random(parameters.random_seed)
+        employees = generate_employees(parameters, randomizer)
+        logging.info(f"✅ Generated {len(employees)} employees")
+
+        # Generate employee availability preferences
+        logging.info("📅 Generating employee availability preferences...")
+        generate_employee_availability(employees, parameters, start_date, randomizer)
+        logging.info("✅ Employee availability generated")
+
+        return EmployeeSchedule(
+            employees=employees,
+            tasks=tasks,
+            schedule_info=ScheduleInfo(
+                total_slots=parameters.days_in_schedule * SLOTS_PER_DAY
+            ),
+        )
+
+    @staticmethod
+    async def _solve_schedule(
+        schedule: EmployeeSchedule, debug: bool = False
+    ) -> Tuple[pd.DataFrame, pd.DataFrame, str, str]:
+        """
+        Solve the schedule and return the dataframes and job_id.
+
+        Args:
+            schedule: The schedule to solve
+            debug: Enable debug logging
+
+        Returns:
+            Tuple of (emp_df, task_df, job_id, status_message)
+        """
+        if schedule is None:
+            return None, None, None, "No schedule to solve. Please load data first."
+
+        job_id: str = str(uuid.uuid4())
+
+        # Start solving asynchronously
+        def listener(solution):
+            app_state.add_solved_schedule(job_id, solution)
+
+        solver_manager.solve_and_listen(job_id, schedule, listener)
+
+        emp_df = employees_to_dataframe(schedule)
+        task_df = schedule_to_dataframe(schedule)
+
+        task_df = task_df[
+            [
+                "Project",
+                "Sequence",
+                "Employee",
+                "Task",
+                "Start",
+                "End",
+                "Duration (hours)",
+                "Required Skill",
+            ]
+        ].sort_values(["Project", "Sequence"])
+
+        return emp_df, task_df, job_id, "Solving..."
+
+    @staticmethod
+    def poll_solution(
+        job_id: str, schedule: EmployeeSchedule, debug: bool = False
+    ) -> Tuple[pd.DataFrame, pd.DataFrame, str, str, object]:
+        """
+        Poll for a solution for a given job_id.
+
+        Args:
+            job_id: The job_id to poll for
+            schedule: The current schedule state
+            debug: Whether to enable debug logging
+
+        Returns:
+            Tuple of (emp_df, task_df, job_id, status_message, schedule)
+        """
+        if job_id and app_state.has_solved_schedule(job_id):
+            solved_schedule: EmployeeSchedule = app_state.get_solved_schedule(job_id)
+
+            emp_df: pd.DataFrame = employees_to_dataframe(solved_schedule)
+            task_df: pd.DataFrame = schedule_to_dataframe(solved_schedule)
+
+            if debug:
+                # Log solved task order for debugging
+                logging.info("Solved task order:")
+                for _, row in task_df.iterrows():
+                    logging.info(
+                        f"Project: {row['Project']}, Sequence: {row['Sequence']}, Task: {row['Task'][:30]}, Start: {row['Start']}"
+                    )
+
+            task_df = task_df[
+                [
+                    "Project",
+                    "Sequence",
+                    "Employee",
+                    "Task",
+                    "Start",
+                    "End",
+                    "Duration (hours)",
+                    "Required Skill",
+                ]
+            ].sort_values(["Start"])
+
+            # Check if hard constraints are violated (infeasible solution)
+            status_message = ScheduleService._generate_status_message(solved_schedule)
+
+            return emp_df, task_df, job_id, status_message, solved_schedule
+
+        return None, None, job_id, "Solving...", schedule
+
+    @staticmethod
+    async def auto_poll(
+        job_id: str, llm_output: dict, debug: bool = False
+    ) -> Tuple[pd.DataFrame, pd.DataFrame, str, str, dict]:
+        """
+        Poll for updates asynchronously.
+
+        Args:
+            job_id: Job identifier to poll for
+            llm_output: Current LLM output state
+            debug: Enable debug logging
+
+        Returns:
+            Tuple of (emp_df, task_df, job_id, status_message, llm_output)
+        """
+        try:
+            if job_id and app_state.has_solved_schedule(job_id):
+                schedule = app_state.get_solved_schedule(job_id)
+                emp_df = employees_to_dataframe(schedule)
+                task_df = schedule_to_dataframe(schedule)
+
+                # Sort tasks by start time for display
+                task_df = task_df.sort_values("Start")
+
+                if debug:
+                    logging.info(f"Polling for job {job_id}")
+                    logging.info(f"Current schedule state: {task_df.head()}")
+
+                # Generate status message based on constraint satisfaction
+                status_message = ScheduleService._generate_status_message(schedule)
+
+                return emp_df, task_df, job_id, status_message, llm_output
+
+        except Exception as e:
+            logging.error(f"Error polling: {e}")
+            return (
+                gr.update(),
+                gr.update(),
+                job_id,
+                f"Error polling: {str(e)}",
+                llm_output,
+            )
+
+        return (
+            gr.update(),
+            gr.update(),
+            None,
+            "No updates",
+            llm_output,
+        )
+
+    @staticmethod
+    def _generate_status_message(schedule: EmployeeSchedule) -> str:
+        """Generate status message based on schedule score and constraint violations"""
+        status_message = "Solution updated"
+
+        if schedule.score is not None:
+            hard_score = schedule.score.hard_score
+            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)
+                )
+                suggestions = ConstraintViolationAnalyzer.generate_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}"
+                )
+                logging.warning(
+                    f"Infeasible solution detected. Hard score: {hard_score}"
+                )
+            else:
+                soft_score = schedule.score.soft_score
+                status_message = f"✅ Solved successfully! Score: {hard_score}/{soft_score} (hard/soft)"
+                logging.info(
+                    f"Feasible solution found. Score: {hard_score}/{soft_score}"
+                )
+
+        return status_message
+
+    @staticmethod
+    def start_timer(job_id: str, llm_output: Any) -> gr.Timer:
+        """Start a timer for polling (Gradio-specific functionality)"""
+        return gr.Timer(active=True)

src/state.py

@@ -0,0 +1,34 @@
+from typing import Dict
+from constraint_solvers.timetable.domain import EmployeeSchedule
+
+
+class AppState:
+    """Central state management for the Yuga Planner application."""
+
+    def __init__(self):
+        self._solved_schedules: Dict[str, EmployeeSchedule] = {}
+
+    @property
+    def solved_schedules(self) -> Dict[str, EmployeeSchedule]:
+        """Get the solved schedules dictionary."""
+        return self._solved_schedules
+
+    def add_solved_schedule(self, key: str, schedule: EmployeeSchedule) -> None:
+        """Add a solved schedule to the state."""
+        self._solved_schedules[key] = schedule
+
+    def get_solved_schedule(self, key: str) -> EmployeeSchedule | None:
+        """Get a specific solved schedule by key."""
+        return self._solved_schedules.get(key)
+
+    def clear_solved_schedules(self) -> None:
+        """Clear all solved schedules."""
+        self._solved_schedules.clear()
+
+    def has_solved_schedule(self, key: str) -> bool:
+        """Check if a solved schedule exists for the given key."""
+        return key in self._solved_schedules
+
+
+# Global app state instance
+app_state = AppState()

src/utils/__init__.py

@@ -0,0 +1,3 @@
+"""
+Utils package initialization.
+"""

src/utils/extract_calendar.py

@@ -0,0 +1,31 @@
+from icalendar import Calendar
+
+
+def extract_ical_entries(file_bytes):
+    try:
+        cal = Calendar.from_ical(file_bytes)
+        entries = []
+        for component in cal.walk():
+            if component.name == "VEVENT":
+                summary = str(component.get("summary", ""))
+                dtstart = component.get("dtstart", "")
+                dtend = component.get("dtend", "")
+
+                def to_iso(val):
+                    if hasattr(val, "dt"):
+                        dt = val.dt
+                        if hasattr(dt, "isoformat"):
+                            return dt.isoformat()
+                        return str(dt)
+                    return str(val)
+
+                entries.append(
+                    {
+                        "summary": summary,
+                        "dtstart": to_iso(dtstart),
+                        "dtend": to_iso(dtend),
+                    }
+                )
+        return entries, None
+    except Exception as e:
+        return None, str(e)

src/utils/load_secrets.py

@@ -0,0 +1,32 @@
+import os, logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+### SECRETS ###
+def load_secrets(secrets_file: str):
+    """
+    Load secrets from Python file into environment variables.
+
+    Args:
+        secrets_file (str): Path to the Python file containing secrets
+
+    Returns:
+        bool: True if secrets were loaded successfully
+    """
+    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)
+
+        # Set environment variables
+        os.environ["NEBIUS_API_KEY"] = secrets.NEBIUS_API_KEY
+        os.environ["NEBIUS_MODEL"] = secrets.NEBIUS_MODEL
+        return True
+
+    except Exception as e:
+        logger.error(f"Failed to load secrets from {secrets_file}: {str(e)}")
+        return False

src/utils/markdown_analyzer.py

@@ -0,0 +1,686 @@
+"""
+Markdown Analyzer Library
+
+This library provides a comprehensive Markdown parsing and analysis system. It consists of three main components:
+
+1. MarkdownParser: Converts Markdown text into a stream of tokens representing different structural elements
+   (headers, paragraphs, lists, code blocks, etc.). It handles both block-level and inline elements.
+
+2. InlineParser: Processes inline Markdown elements within block tokens, such as:
+   - Links and images
+   - Inline code
+   - Emphasis (bold, italic)
+   - Footnotes
+   - HTML inline elements
+
+3. MarkdownAnalyzer: The main interface that combines parsing and analysis. It:
+   - Parses the input text into tokens
+   - Processes inline elements within tokens
+   - Provides methods to identify and analyze different Markdown elements
+   - Generates statistics about the document structure
+
+Usage:
+    analyzer = MarkdownAnalyzer(markdown_text)
+    analysis = analyzer.analyze()  # Get document statistics
+    headers = analyzer.identify_headers()  # Get all headers
+    links = analyzer.identify_links()  # Get all links
+    # etc.
+
+The library supports standard Markdown features including:
+- Headers (ATX and Setext style)
+- Lists (ordered, unordered, and task lists)
+- Code blocks (fenced and inline)
+- Blockquotes
+- Tables
+- Links and images
+- Footnotes
+- HTML blocks and inline elements
+"""
+
+import re
+from collections import defaultdict
+
+
+### MAIN INTERFACE ###
+class MarkdownAnalyzer:
+    # def __init__(self, file_path, encoding='utf-8'):
+    def __init__(self, text):
+        # with open(file_path, 'r', encoding=encoding) as f:
+        #     self.text = f.read()
+        self.text = text
+        parser = MarkdownParser(self.text)
+        self.tokens = parser.parse()
+        self.references = parser.references
+        self.footnotes = parser.footnotes
+        self.inline_parser = InlineParser(
+            references=self.references, footnotes=self.footnotes
+        )
+
+        self._parse_inline_tokens()
+
+    def _parse_inline_tokens(self):
+        inline_types = ("paragraph", "header", "blockquote")
+        for token in self.tokens:
+            if token.type in inline_types and token.content:
+                inline_data = self.inline_parser.parse_inline(token.content)
+                token.meta.update(inline_data)
+
+    def identify_headers(self):
+        result = defaultdict(list)
+        for token in self.tokens:
+            if token.type == "header":
+                result["Header"].append(
+                    {"line": token.line, "level": token.level, "text": token.content}
+                )
+        return dict(result)
+
+    def identify_paragraphs(self):
+        result = defaultdict(list)
+        for token in self.tokens:
+            if token.type == "paragraph":
+                result["Paragraph"].append(token.content)
+        return dict(result)
+
+    def identify_blockquotes(self):
+        result = defaultdict(list)
+        for token in self.tokens:
+            if token.type == "blockquote":
+                result["Blockquote"].append(token.content)
+        return dict(result)
+
+    def identify_code_blocks(self):
+        result = defaultdict(list)
+        for token in self.tokens:
+            if token.type == "code":
+                result["Code block"].append(
+                    {
+                        "start_line": token.line,
+                        "content": token.content,
+                        "language": token.meta.get("language"),
+                    }
+                )
+        return dict(result)
+
+    def identify_lists(self):
+        result = defaultdict(list)
+        for token in self.tokens:
+            if token.type == "ordered_list":
+                result["Ordered list"].append(token.meta["items"])
+            elif token.type == "unordered_list":
+                result["Unordered list"].append(token.meta["items"])
+        return dict(result)
+
+    def identify_tables(self):
+        result = defaultdict(list)
+        for token in self.tokens:
+            if token.type == "table":
+                result["Table"].append(
+                    {"header": token.meta["header"], "rows": token.meta["rows"]}
+                )
+        return dict(result)
+
+    def identify_links(self):
+        result = defaultdict(list)
+        for token in self.tokens:
+            if "text_links" in token.meta:
+                for l in token.meta["text_links"]:
+                    result["Text link"].append(
+                        {"line": token.line, "text": l["text"], "url": l["url"]}
+                    )
+            if "image_links" in token.meta:
+                for img in token.meta["image_links"]:
+                    result["Image link"].append(
+                        {
+                            "line": token.line,
+                            "alt_text": img["alt_text"],
+                            "url": img["url"],
+                        }
+                    )
+        return dict(result)
+
+    def identify_footnotes(self):
+        result = []
+        seen = set()
+        for token in self.tokens:
+            if "footnotes_used" in token.meta:
+                for fn in token.meta["footnotes_used"]:
+                    key = (fn["id"], fn["content"])
+                    if key not in seen:
+                        seen.add(key)
+                        result.append(
+                            {
+                                "line": token.line,
+                                "id": fn["id"],
+                                "content": fn["content"],
+                            }
+                        )
+        return result
+
+    def identify_inline_code(self):
+        codes = []
+        for token in self.tokens:
+            if "inline_code" in token.meta:
+                for c in token.meta["inline_code"]:
+                    codes.append({"line": token.line, "code": c})
+        return codes
+
+    def identify_emphasis(self):
+        ems = []
+        for token in self.tokens:
+            if "emphasis" in token.meta:
+                for e in token.meta["emphasis"]:
+                    ems.append({"line": token.line, "text": e})
+        return ems
+
+    def identify_task_items(self):
+        tasks = []
+        for token in self.tokens:
+            if token.type in ("ordered_list", "unordered_list"):
+                for it in token.meta["items"]:
+                    if it.get("task_item"):
+                        tasks.append(
+                            {
+                                "line": token.line,
+                                "text": it["text"],
+                                "checked": it["checked"],
+                            }
+                        )
+        return tasks
+
+    def identify_html_blocks(self):
+        # Gets HTML blocks
+        result = []
+        for token in self.tokens:
+            if token.type == "html_block":
+                result.append({"line": token.line, "content": token.content})
+        return result
+
+    def identify_html_inline(self):
+        # Gets HTML tags from inline tokens
+        result = []
+        inline_types = ("paragraph", "header", "blockquote")
+        for token in self.tokens:
+            if token.type in inline_types and "html_inline" in token.meta:
+                for h in token.meta["html_inline"]:
+                    result.append({"line": token.line, "html": h})
+        return result
+
+    def count_words(self):
+        words = self.text.split()
+        return len(words)
+
+    def count_characters(self):
+        characters = [char for char in self.text if not char.isspace()]
+        return len(characters)
+
+    def analyze(self):
+        headers = self.identify_headers().get("Header", [])
+        paragraphs = self.identify_paragraphs().get("Paragraph", [])
+        blockquotes = self.identify_blockquotes().get("Blockquote", [])
+        code_blocks = self.identify_code_blocks().get("Code block", [])
+        lists = self.identify_lists()
+        ordered_lists = lists.get("Ordered list", [])
+        unordered_lists = lists.get("Unordered list", [])
+        tables = self.identify_tables().get("Table", [])
+        html_blocks = self.identify_html_blocks()
+        html_inline = self.identify_html_inline()
+
+        analysis = {
+            "headers": len(headers),
+            "paragraphs": len(paragraphs),
+            "blockquotes": len(blockquotes),
+            "code_blocks": len(code_blocks),
+            "ordered_lists": sum(len(l) for l in ordered_lists),
+            "unordered_lists": sum(len(l) for l in unordered_lists),
+            "tables": len(tables),
+            "html_blocks": len(html_blocks),
+            "html_inline_count": len(html_inline),
+            "words": self.count_words(),
+            "characters": self.count_characters(),
+        }
+        return analysis
+
+
+### PARSING CLASSES ###
+class BlockToken:
+    """Represents a block-level Markdown element with its type, content, and metadata."""
+
+    def __init__(self, type_, content="", level=None, meta=None, line=None):
+        self.type = type_  # Type of block (header, paragraph, code, etc.)
+        self.content = content  # The actual content of the block
+        self.level = level  # Used for headers (h1-h6) and list indentation
+        self.meta = meta or {}  # Additional metadata (language for code blocks, etc.)
+        self.line = line  # Line number in the original document
+
+
+class InlineParser:
+    # Regular expressions for matching inline Markdown elements
+    IMAGE_OR_LINK_RE = re.compile(
+        r"(!?\[([^\]]*)\])(\(([^\)]+)\)|\[([^\]]+)\])"
+    )  # Matches [text](url) or ![alt](url)
+    CODE_INLINE_RE = re.compile(r"`([^`]+)`")  # Matches `code`
+    EMPHASIS_RE = re.compile(
+        r"(\*\*|__)(.*?)\1|\*(.*?)\*|_(.*?)_"
+    )  # Matches **bold**, *italic*, _underline_
+    FOOTNOTE_RE = re.compile(r"\[\^([^\]]+)\]")  # Matches [^footnote]
+    HTML_INLINE_RE = re.compile(r"<[a-zA-Z/][^>]*>")  # Matches HTML tags
+    HTML_INLINE_BLOCK_RE = re.compile(
+        r"<([a-zA-Z]+)([^>]*)>(.*?)</\1>", re.DOTALL
+    )  # Matches HTML blocks with content
+
+    def __init__(self, references=None, footnotes=None):
+        # Initialize with optional reference links and footnotes from the document
+        self.references = references or {}  # For [text][ref] style links
+        self.footnotes = footnotes or {}  # For [^footnote] style references
+
+    def parse_inline(self, text):
+        """Parse inline Markdown elements within a block of text."""
+        result = {
+            "text_links": [],  # Regular [text](url) links
+            "image_links": [],  # ![alt](url) images
+            "inline_code": [],  # `code` blocks
+            "emphasis": [],  # **bold**, *italic* text
+            "footnotes_used": [],  # [^footnote] references
+            "html_inline": [],  # HTML tags and blocks
+        }
+
+        # Process footnotes first to avoid conflicts with other patterns
+        used_footnotes = set()
+        for fm in self.FOOTNOTE_RE.finditer(text):
+            fid = fm.group(1)
+            if fid in self.footnotes and fid not in used_footnotes:
+                used_footnotes.add(fid)
+                result["footnotes_used"].append(
+                    {"id": fid, "content": self.footnotes[fid]}
+                )
+
+        # Find inline code blocks
+        for cm in self.CODE_INLINE_RE.finditer(text):
+            code = cm.group(1)
+            result["inline_code"].append(code)
+
+        # Find emphasized text (bold, italic, underline)
+        for em_match in self.EMPHASIS_RE.finditer(text):
+            emphasized_text = (
+                em_match.group(2) or em_match.group(3) or em_match.group(4)
+            )
+            if emphasized_text:
+                result["emphasis"].append(emphasized_text)
+
+        # Process HTML blocks first to avoid conflicts with other patterns
+        temp_text = text
+        for block_match in self.HTML_INLINE_BLOCK_RE.finditer(text):
+            html_content = block_match.group(0)
+            result["html_inline"].append(html_content)
+            temp_text = temp_text.replace(html_content, "")
+
+        # Process links and images
+        for mm in self.IMAGE_OR_LINK_RE.finditer(temp_text):
+            prefix = mm.group(1)  # The [text] or ![alt] part
+            inner_text = mm.group(2)  # The text inside []
+            url = mm.group(4)  # The (url) part
+            ref_id = mm.group(5)  # The [ref] part for reference-style links
+
+            is_image = prefix.startswith("!")
+            final_url = url
+            if ref_id and ref_id.lower() in self.references:
+                final_url = self.references[ref_id.lower()]
+
+            if is_image:
+                if final_url:
+                    result["image_links"].append(
+                        {"alt_text": inner_text, "url": final_url}
+                    )
+            else:
+                if final_url:
+                    result["text_links"].append({"text": inner_text, "url": final_url})
+        return result
+
+
+class MarkdownParser:
+    # Regular expressions for matching block-level Markdown elements
+    FRONTMATTER_RE = re.compile(r"^---\s*$")  # Matches YAML frontmatter delimiters
+    ATX_HEADER_RE = re.compile(r"^(#{1,6})\s+(.*)$")  # Matches # Header style
+    SETEXT_H1_RE = re.compile(r"^=+\s*$")  # Matches ==== style h1
+    SETEXT_H2_RE = re.compile(r"^-+\s*$")  # Matches ---- style h2
+    FENCE_RE = re.compile(r"^```([^`]*)$")  # Matches code fence start
+    BLOCKQUOTE_RE = re.compile(r"^(>\s?)(.*)$")  # Matches > quote style
+    ORDERED_LIST_RE = re.compile(r"^\s*\d+\.\s+(.*)$")  # Matches 1. list style
+    UNORDERED_LIST_RE = re.compile(r"^\s*[-+*]\s+(.*)$")  # Matches - list style
+    HR_RE = re.compile(r"^(\*{3,}|-{3,}|_{3,})\s*$")  # Matches horizontal rules
+    TABLE_SEPARATOR_RE = re.compile(
+        r"^\|?(\s*:?-+:?\s*\|)+\s*:?-+:?\s*\|?\s*$"
+    )  # Matches table separators
+    REFERENCE_DEF_RE = re.compile(
+        r"^\[([^\]]+)\]:\s+(.*?)\s*$", re.MULTILINE
+    )  # Matches [ref]: url definitions
+    FOOTNOTE_DEF_RE = re.compile(
+        r"^\[\^([^\]]+)\]:\s+(.*?)\s*$", re.MULTILINE
+    )  # Matches [^footnote]: content
+    HTML_BLOCK_START = re.compile(
+        r"^(<([a-zA-Z]+)([^>]*)>|<!--)"
+    )  # Matches HTML block start
+    HTML_BLOCK_END_COMMENT = re.compile(r"-->\s*$")  # Matches HTML comment end
+
+    def __init__(self, text):
+        """Initialize parser with the Markdown text to parse."""
+        self.lines = text.split("\n")
+        self.length = len(self.lines)
+        self.pos = 0  # Current position in the text
+        self.tokens = []  # List of parsed tokens
+        self.text = text
+        self.references = {}  # Reference-style link definitions
+        self.footnotes = {}  # Footnote definitions
+        self.extract_references_and_footnotes()
+
+    def extract_references_and_footnotes(self):
+        """Extract all reference-style links and footnotes from the document."""
+        for m in self.REFERENCE_DEF_RE.finditer(self.text):
+            rid, url = m.groups()
+            self.references[rid.lower()] = url
+
+        for m in self.FOOTNOTE_DEF_RE.finditer(self.text):
+            fid, content = m.groups()
+            self.footnotes[fid] = content
+
+    def parse(self):
+        """Main parsing method that processes the entire document."""
+        # Check for frontmatter at the start
+        if self.pos < self.length and self.FRONTMATTER_RE.match(
+            self.lines[self.pos].strip()
+        ):
+            self.parse_frontmatter()
+
+        # Process the document line by line
+        while self.pos < self.length:
+            if self.pos >= self.length:
+                break
+            line = self.lines[self.pos]
+            if not line.strip():
+                self.pos += 1
+                continue
+
+            # Check for table start
+            if self.is_table_start():
+                self.parse_table()
+                continue
+
+            # Check for HTML block
+            if self.is_html_block_start(line):
+                self.parse_html_block()
+                continue
+
+            # Check for ATX-style headers (# Header)
+            m = self.ATX_HEADER_RE.match(line)
+            if m:
+                level = len(m.group(1))
+                text = m.group(2).strip()
+                self.tokens.append(
+                    BlockToken("header", content=text, level=level, line=self.pos + 1)
+                )
+                self.pos += 1
+                continue
+
+            # Check for Setext-style headers (=== or ---)
+            if self.pos + 1 < self.length:
+                next_line = self.lines[self.pos + 1].strip()
+                if self.SETEXT_H1_RE.match(next_line):
+                    text = line.strip()
+                    self.tokens.append(
+                        BlockToken("header", content=text, level=1, line=self.pos + 1)
+                    )
+                    self.pos += 2
+                    continue
+                if self.SETEXT_H2_RE.match(next_line):
+                    text = line.strip()
+                    self.tokens.append(
+                        BlockToken("header", content=text, level=2, line=self.pos + 1)
+                    )
+                    self.pos += 2
+                    continue
+
+            # Check for horizontal rule
+            if self.HR_RE.match(line.strip()):
+                self.tokens.append(BlockToken("hr", line=self.pos + 1))
+                self.pos += 1
+                continue
+
+            # Check for fenced code block
+            fm = self.FENCE_RE.match(line.strip())
+            if fm:
+                lang = fm.group(1).strip()
+                self.parse_fenced_code_block(lang)
+                continue
+
+            # Check for blockquote
+            bm = self.BLOCKQUOTE_RE.match(line)
+            if bm:
+                self.parse_blockquote()
+                continue
+
+            # Check for lists
+            om = self.ORDERED_LIST_RE.match(line)
+            um = self.UNORDERED_LIST_RE.match(line)
+            if om or um:
+                self.parse_list(ordered=bool(om))
+                continue
+
+            # If no other block type matches, treat as paragraph
+            self.parse_paragraph()
+
+        return self.tokens
+
+    def is_html_block_start(self, line):
+        # Verify if line seems to be HTML
+        return self.HTML_BLOCK_START.match(line.strip()) is not None
+
+    def parse_html_block(self):
+        start = self.pos
+        lines = []
+        first_line = self.lines[self.pos].strip()
+        comment_mode = first_line.startswith("<!--")
+
+        # Read HTML block until empty line / eof
+        while self.pos < self.length:
+            line = self.lines[self.pos]
+            lines.append(line)
+            self.pos += 1
+
+            if comment_mode and self.HTML_BLOCK_END_COMMENT.search(line):
+                break
+            else:
+                # If next line is empty or doesn't exist, stop
+                if self.pos < self.length:
+                    nxt_line = self.lines[self.pos]
+                    if not nxt_line.strip():
+                        # End of block
+                        break
+                else:
+                    # End of file
+                    break
+
+        content = "\n".join(lines)
+        self.tokens.append(BlockToken("html_block", content=content, line=start + 1))
+
+    def starts_new_block_peek(self):
+        # Check next line without advancing
+        if self.pos < self.length:
+            nxt = self.lines[self.pos].strip()
+            return self.starts_new_block(nxt)
+        return False
+
+    def is_table_start(self):
+        if self.pos + 1 < self.length:
+            line = self.lines[self.pos].strip()
+            next_line = self.lines[self.pos + 1].strip()
+            if (
+                "|" in line
+                and "|" in next_line
+                and self.TABLE_SEPARATOR_RE.match(next_line)
+            ):
+                return True
+        return False
+
+    def parse_table(self):
+        start = self.pos
+        header_line = self.lines[self.pos].strip()
+        separator_line = self.lines[self.pos + 1].strip()
+        self.pos += 2
+        rows = []
+        while self.pos < self.length:
+            line = self.lines[self.pos].strip()
+            if not line or self.starts_new_block(line):
+                break
+            rows.append(line)
+            self.pos += 1
+
+        header_cells = [
+            h.strip() for h in header_line.strip("|").split("|") if h.strip()
+        ]
+        data_rows = []
+        for r in rows:
+            data_rows.append([c.strip() for c in r.strip("|").split("|") if c.strip()])
+
+        self.tokens.append(
+            BlockToken(
+                "table",
+                meta={"header": header_cells, "rows": data_rows},
+                line=start + 1,
+            )
+        )
+
+    def starts_new_block(self, line):
+        return (
+            self.ATX_HEADER_RE.match(line)
+            or self.FRONTMATTER_RE.match(line)
+            or self.FENCE_RE.match(line)
+            or self.BLOCKQUOTE_RE.match(line)
+            or self.ORDERED_LIST_RE.match(line)
+            or self.UNORDERED_LIST_RE.match(line)
+            or self.HR_RE.match(line)
+            or self.SETEXT_H1_RE.match(line)
+            or self.SETEXT_H2_RE.match(line)
+            or self.HTML_BLOCK_START.match(line)
+        )
+
+    def parse_frontmatter(self):
+        self.pos += 1
+        start = self.pos
+        while self.pos < self.length:
+            if self.FRONTMATTER_RE.match(self.lines[self.pos].strip()):
+                content = "\n".join(self.lines[start : self.pos])
+                self.tokens.append(BlockToken("frontmatter", content=content))
+                self.pos += 1
+                return
+            self.pos += 1
+        content = "\n".join(self.lines[start:])
+        self.tokens.append(BlockToken("frontmatter", content=content))
+        self.pos = self.length
+
+    def parse_fenced_code_block(self, lang):
+        self.pos += 1
+        start = self.pos
+        while self.pos < self.length:
+            line = self.lines[self.pos]
+            if line.strip().startswith("```"):
+                content = "\n".join(self.lines[start : self.pos])
+                self.tokens.append(
+                    BlockToken(
+                        "code", content=content, meta={"language": lang}, line=start + 1
+                    )
+                )
+                self.pos += 1
+                return
+            self.pos += 1
+        content = "\n".join(self.lines[start:])
+        self.tokens.append(
+            BlockToken("code", content=content, meta={"language": lang}, line=start + 1)
+        )
+        self.pos = self.length
+
+    def parse_blockquote(self):
+        start = self.pos
+        lines = []
+        while self.pos < self.length:
+            line = self.lines[self.pos]
+            bm = self.BLOCKQUOTE_RE.match(line)
+            if bm:
+                lines.append(bm.group(2))
+                self.pos += 1
+            else:
+                break
+        content = "\n".join(lines)
+        self.tokens.append(BlockToken("blockquote", content=content, line=start + 1))
+
+    def parse_list(self, ordered):
+        start = self.pos
+        items = []
+        current_item = []
+        list_pattern = self.ORDERED_LIST_RE if ordered else self.UNORDERED_LIST_RE
+
+        while self.pos < self.length:
+            line = self.lines[self.pos]
+            if not line.strip():
+                if current_item:
+                    items.append("\n".join(current_item).strip())
+                    current_item = []
+                self.pos += 1
+                continue
+
+            if self.starts_new_block(line.strip()) and not (
+                self.ORDERED_LIST_RE.match(line.strip())
+                or self.UNORDERED_LIST_RE.match(line.strip())
+            ):
+                break
+
+            lm = list_pattern.match(line)
+            if lm:
+                if current_item:
+                    items.append("\n".join(current_item).strip())
+                    current_item = []
+                current_item.append(lm.group(1))
+                self.pos += 1
+            else:
+                current_item.append(line.strip())
+                self.pos += 1
+
+        if current_item:
+            items.append("\n".join(current_item).strip())
+
+        task_re = re.compile(r"^\[( |x)\]\s+(.*)$")
+        final_items = []
+        for it in items:
+            lines = it.split("\n")
+            first_line = lines[0].strip()
+            m = task_re.match(first_line)
+            if m:
+                state = m.group(1)
+                text = m.group(2)
+                task_checked = state == "x"
+                final_items.append(
+                    {"text": text, "task_item": True, "checked": task_checked}
+                )
+            else:
+                final_items.append({"text": it, "task_item": False})
+
+        list_type = "ordered_list" if ordered else "unordered_list"
+        self.tokens.append(
+            BlockToken(list_type, meta={"items": final_items}, line=start + 1)
+        )
+
+    def parse_paragraph(self):
+        start = self.pos
+        lines = []
+        while self.pos < self.length:
+            line = self.lines[self.pos]
+            if not line.strip():
+                self.pos += 1
+                break
+            if self.starts_new_block(line.strip()):
+                break
+            lines.append(line)
+            self.pos += 1
+
+        content = "\n".join(lines).strip()
+        if content:
+            self.tokens.append(BlockToken("paragraph", content=content, line=start + 1))

tests/__init__.py

@@ -0,0 +1,3 @@
+"""
+Tests package initialization.
+"""

tests/data/calendar.ics

@@ -0,0 +1,56 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Mock Calendar//EN
+CALSCALE:GREGORIAN
+
+BEGIN:VEVENT
+UID:recur-meeting-1@mock
+DTSTAMP:20240523T000000Z
+DTSTART;TZID=UTC:20250603T100000
+DTEND;TZID=UTC:20250603T110000
+RRULE:FREQ=WEEKLY;BYDAY=TU,TH
+SUMMARY:Team Sync
+END:VEVENT
+
+BEGIN:VEVENT
+UID:recur-meeting-2@mock
+DTSTAMP:20240523T000000Z
+DTSTART;TZID=UTC:20250602T140000
+DTEND;TZID=UTC:20250602T150000
+RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR
+SUMMARY:Project Review
+END:VEVENT
+
+BEGIN:VEVENT
+UID:single-event-1@mock
+DTSTAMP:20240523T000000Z
+DTSTART;TZID=UTC:20250605T130000
+DTEND;TZID=UTC:20250605T140000
+SUMMARY:Client Call
+END:VEVENT
+
+BEGIN:VEVENT
+UID:single-event-2@mock
+DTSTAMP:20240523T000000Z
+DTSTART;TZID=UTC:20250616T110000
+DTEND;TZID=UTC:20250616T120000
+SUMMARY:Workshop
+END:VEVENT
+
+BEGIN:VEVENT
+UID:single-event-3@mock
+DTSTAMP:20240523T000000Z
+DTSTART;TZID=UTC:20250707T150000
+DTEND;TZID=UTC:20250707T163000
+SUMMARY:Planning Session
+END:VEVENT
+
+BEGIN:VEVENT
+UID:single-event-4@mock
+DTSTAMP:20240523T000000Z
+DTSTART;TZID=UTC:20250722T093000
+DTEND;TZID=UTC:20250722T103000
+SUMMARY:Demo
+END:VEVENT
+
+END:VCALENDAR

tests/secrets/nebius_secrets.py.template

@@ -0,0 +1,3 @@
+# Nebius API credentials
+NEBIUS_API_KEY = ""
+NEBIUS_MODEL = ""

tests/test_calendar_operations.py

@@ -0,0 +1,23 @@
+import icalendar
+
+from pathlib import Path
+
+
+def test_calendar_operations():
+    ics_path = Path("tests/data/calendar.ics")
+
+    calendar = icalendar.Calendar.from_ical(ics_path.read_bytes())
+
+    for event in calendar.events:
+        print(event.get("summary"))
+
+        def to_iso(val):
+            if hasattr(val, "dt"):
+                dt = val.dt
+                if hasattr(dt, "isoformat"):
+                    return dt.isoformat()
+                return str(dt)
+            return str(val)
+
+        print(to_iso(event.get("dtstart")))
+        print(to_iso(event.get("dtend")))

tests/test_factory.py

@@ -0,0 +1,72 @@
+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")
+
+import factory.data_provider as data_provider
+from src.utils.extract_calendar import extract_ical_entries
+
+
+@pytest.mark.asyncio
+async def test_factory_demo_agent():
+    # Use a simple string as the project description
+    test_input = "Test project for schedule generation."
+
+    # Generate schedule data using generate_agent_data
+    schedule = await data_provider.generate_agent_data(test_input)
+
+    # Assert basic schedule properties
+    assert len(schedule.employees) > 0
+    assert schedule.schedule_info.total_slots > 0
+    assert len(schedule.tasks) > 0
+
+    # Verify employee skills
+    for employee in schedule.employees:
+        assert len(employee.skills) > 0
+        # Check that each employee has at least one required skill
+        assert any(
+            skill in data_provider.SKILL_SET.required_skills
+            for skill in employee.skills
+        )
+
+    # Verify task properties
+    for task in schedule.tasks:
+        assert task.duration_slots > 0
+        assert task.required_skill
+        assert hasattr(task, "project_id")
+
+    # Print schedule details for debugging
+    print("Employee names:", [e.name for e in schedule.employees])
+    print("Tasks count:", len(schedule.tasks))
+    print("Total slots:", schedule.schedule_info.total_slots)
+
+
+@pytest.mark.asyncio
+async def test_factory_mcp():
+    # Load the real calendar.ics file
+    with open("tests/data/calendar.ics", "rb") as f:
+        file_bytes = f.read()
+    entries, err = extract_ical_entries(file_bytes)
+    assert err is None
+    assert entries is not None
+    assert len(entries) > 0
+
+    print("\nEntries:")
+    print(entries)
+
+    # Use a made-up user message
+    user_message = "Create a new AWS VPC."
+
+    # Call generate_mcp_data directly
+    df = await data_provider.generate_mcp_data(entries, user_message)
+
+    # Assert the DataFrame is not empty
+    assert df is not None
+    assert not df.empty
+
+    # Print the DataFrame for debug
+    print(df)

tests/test_task_composer_agent.py

@@ -0,0 +1,60 @@
+import pytest, logging
+
+
+from src.utils.load_secrets import load_secrets
+
+# Configure logging
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+# Load environment variables
+load_secrets("tests/secrets/creds.py")
+# Import task_composer_agent after environment variables are set
+from src.agents.task_composer_agent import TaskComposerAgent
+
+
+@pytest.mark.asyncio
+async def test_task_composer_agent():
+    logger.info("\n=== Test Environment ===")
+
+    logger.info("\n=== Starting Test ===")
+
+    # Create agent
+    logger.info("\nInitializing task_composer_agent...")
+    agent = TaskComposerAgent()
+
+    # Test input
+    test_input = "Plan a weekend trip to Paris"
+    logger.info(f"\n=== Test Input ===")
+    logger.info(f"Task: {test_input}")
+
+    # Run workflow
+    logger.info("\n=== Running Workflow ===")
+    result = await agent.run_workflow(test_input)
+
+    # Print the result
+    logger.info(f"\n=== Final Result ===")
+    logger.info("Task breakdown with estimated times:")
+    for task, duration, skill in result:
+        logger.info(f"- {task}: {duration} units (Skill: {skill})")
+
+    # Calculate total time
+    total_time = sum(
+        int(time) if str(time).isdigit() and str(time) != "" else 0
+        for _, time, _ in result
+    )
+    logger.info(
+        f"\nTotal estimated time: {total_time} units ({total_time * 30} minutes)"
+    )
+
+    # Verify the result is a list of 3-tuples
+    assert isinstance(result, list), f"Expected a list, got {type(result)}"
+    assert all(
+        isinstance(item, tuple) and len(item) == 3 for item in result
+    ), "Expected a list of (task, duration, skill) tuples"
+    logger.info("\n=== Test Summary ===")
+    logger.info("✓ Test passed!")
+    logger.info(f"✓ Task: {test_input}")
+    logger.info(
+        f"✓ Total estimated time: {total_time} units ({total_time * 30} minutes)"
+    )