Spaces:
Paused
Paused
| title: Yuga Planner | |
| emoji: 🐍 | |
| colorFrom: purple | |
| colorTo: gray | |
| sdk: docker | |
| app_port: 7860 | |
| license: apache-2.0 | |
| tags: ["agent-demo-track"] | |
| # 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, 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. | |
| ## 🚀 Try It Now | |
| **Live Demo:** | |
| [https://huggingface.co/spaces/blackopsrepl/yuga-planner](https://huggingface.co/spaces/blackopsrepl/yuga-planner) | |
| **Source Code on GitHub:** | |
| [https://github.com/blackopsrepl/yuga-planner](https://github.com/blackopsrepl/yuga-planner) | |
| ### MCP Chat Interface Usage | |
| 1. **Navigate to the Chat tab** in the Gradio interface | |
| 2. **Upload your calendar file (.ics)** to provide existing commitments (optional) | |
| 3. **Type your scheduling request** using natural language: | |
| ``` | |
| "Create a new EC2 instance on AWS" | |
| "Create a Svelte UI that allows me to query a postgresql database" | |
| "Develop a chatbot UI based on Gradio" | |
| ``` | |
| 4. **Receive intelligent responses** that combine conversational AI with task scheduling capabilities | |
| 5. **View formatted schedules** with rich table output and status indicators | |
| ### MCP Tool Usage | |
| 1. **In any MCP-compatible chatbot or agent platform:** | |
| ``` | |
| use yuga-planner mcp tool | |
| Task Description: [Your task description] | |
| ``` | |
| 2. **Attach your calendar file (.ics)** to provide existing commitments | |
| 3. **Receive optimized schedule** that integrates your new task with existing calendar events | |
| ## Architecture | |
| Yuga Planner follows a **service-oriented architecture** with clear separation of concerns: | |
| ### Core Services Layer | |
| - **DataService:** Handles data loading, processing, and format conversion from various sources (Markdown, calendars) | |
| - **ScheduleService:** Orchestrates schedule generation, solver management, and solution polling | |
| - **StateService:** Centralized state management for job tracking and schedule storage | |
| - **LoggingService:** Real-time log streaming for UI feedback and debugging | |
| - **MockProjectService:** Provides sample project data for testing and demos | |
| - **MCPClientWrapper:** Manages MCP server functionality and tool definitions | |
| ### MCP Integration Components | |
| - **ToolCallAssembler:** Processes streaming tool call deltas from Nebius API into complete tool calls | |
| - **ToolCallProcessor:** Executes completed tool calls via MCP backend with JSON repair functionality | |
| - **Chat Interface:** Unified conversational AI + task scheduling with intelligent tool detection | |
| - **Streaming Handler:** Real-time response processing with progress indicators and error recovery | |
| ### System Components | |
| - **Gradio UI:** Modern web interface with real-time updates and interactive schedule visualization | |
| - **Task Composer Agent:** Uses [LLamaIndex](https://www.llamaindex.ai/) + [Nebius AI](https://nebius.ai/) for intelligent task decomposition and estimation | |
| - **Constraint Solver:** [Timefold](http://www.timefold.ai) optimization engine for optimal task-to-employee assignments | |
| - **MCP Integration:** Model Context Protocol endpoint for agent workflow integration | |
| --- | |
| ## 🌟 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 & Pinning** | Extracts and preserves calendar events from .ics files at original times | ✅ | | |
| | **Business Hours Enforcement** | Respects 9:00-18:00 working hours with lunch break exclusion | ✅ | | |
| | **Weekend Scheduling Prevention** | Hard constraint preventing weekend task assignments | ✅ | | |
| | **MCP Endpoint** | API endpoint for MCP tool integration with calendar support | ✅ | | |
| | **Chat Interface with MCP** | Unified conversational AI + task scheduling interface | ✅ | | |
| | **Streaming Tool Calls** | Real-time processing of tool calls from Nebius API | ✅ | | |
| | **Intelligent Tool Detection** | Keyword-based detection for scheduling requests | ✅ | | |
| | **JSON Repair & Recovery** | Robust handling of malformed streaming data | ✅ | | |
| | **Dual Response System** | Nebius API with MCP fallback for reliability | ✅ | | |
| ## 🎯 Two Usage Modes | |
| Yuga Planner operates as **two separate systems** serving different use cases: | |
| ### 1. 💬 MCP Chat Interface | |
| **Purpose:** Conversational AI with integrated task scheduling capabilities | |
| - **Access:** Chat tab in the Gradio interface | |
| - **Input:** Natural language requests + optional `.ics` calendar files | |
| - **Features:** | |
| - Intelligent tool detection based on scheduling keywords | |
| - Streaming responses with real-time tool call assembly | |
| - Rich table formatting for schedule results | |
| - Dual response system (Nebius API + MCP fallback) | |
| - **Use Case:** Interactive scheduling through natural conversation | |
| ### 2. 🤖 MCP Personal Tool | |
| **Purpose:** Individual task scheduling integrated with personal calendars | |
| - **Access:** Through MCP-compatible chatbots and agent platforms | |
| - **Input:** Attach `.ics` calendar files + natural language task descriptions | |
| - **Team:** Schedules against your **personal calendar** and existing commitments | |
| - **Use Case:** Personal productivity and task planning around existing appointments | |
| **Example MCP Usage:** | |
| ``` | |
| User: use yuga-planner mcp tool | |
| Task Description: Create a new EC2 instance on AWS | |
| [Attaches calendar.ics file] | |
| Tool Response: Optimized schedule created - EC2 setup task assigned to | |
| available time slots around your existing meetings | |
| ``` | |
| ## 🧩 MCP Chat Interface Technical Details | |
| ### Intelligent Tool Detection | |
| The chat interface automatically detects scheduling requests using keyword analysis: | |
| ```python | |
| scheduling_keywords = [ | |
| 'schedule', 'task', 'calendar', 'plan', 'organize', | |
| 'meeting', 'appointment', 'project', 'deadline', | |
| 'create', 'setup', 'implement', 'develop' | |
| ] | |
| ``` | |
| ### Streaming Tool Call Processing | |
| - **Delta Assembly:** Collects 200+ streaming deltas into complete tool calls | |
| - **JSON Repair:** Handles malformed JSON from streaming responses | |
| - **Progress Indicators:** Real-time feedback during tool processing | |
| - **Timeout Protection:** 60-second timeout for MCP operations | |
| ### Dual Response System | |
| - **Primary:** Nebius API with tool calling capabilities | |
| - **Fallback:** Direct MCP backend invocation when tool assembly fails | |
| - **Error Recovery:** Comprehensive error handling and graceful degradation | |
| **Features:** | |
| - Accepts calendar files and user task descriptions via chat interface | |
| - Parses existing calendar events and new task requirements | |
| - **Full schedule solving support** - generates optimized task assignments | |
| - Returns complete solved schedules integrated with personal calendar | |
| - Designed for seamless chatbot and agent workflow integration | |
| **Current Limitations:** | |
| - **Multi-timezone support:** Currently operates in a single timezone context with UTC conversion for consistency. Calendar events from different timezones are normalized to the same scheduling context. | |
| See the [CHANGELOG.md](CHANGELOG.md) for details on recent MCP-related changes. | |
| ### Work in Progress | |
| - **🔧 Gradio UI overhaul:** Enhanced user experience and visual improvements | |
| - **🔍 Migration to Pydantic models:** Type-safe data validation and serialization | |
| - **⚡ Enhanced timezone support:** Multi-timezone calendar integration for international scheduling | |
| ### Future Work | |
| #### System Integration Roadmap | |
| - **Unified scheduling engine** that can handle both team management and personal productivity in one interface | |
| - **Hybrid workflows** where personal tasks can be coordinated with team projects | |
| - **Cross-system data sharing** between web demo projects and personal MCP calendars | |
| - **Seamless switching** between team management and individual task planning modes | |
| #### Core Feature Enhancements | |
| - **Multi-Tool Support:** Extend chat interface to support additional MCP tools beyond scheduling | |
| - **Calendar Integration:** Direct calendar service integration (Google, Outlook) | |
| - **Performance Optimization:** Enhanced streaming assembly for large tool calls | |
| - **RAG:** validation of task decomposition and estimation against industry relevant literature | |
| - **More granular task dependency:** representation of tasks in a DAG 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 | |
| - **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. **Create a virtual environment:** | |
| ```bash | |
| make venv | |
| ``` | |
| 3. **Install dependencies:** | |
| ```bash | |
| make install | |
| ``` | |
| 4. **Set up environment variables / secrets:** | |
| ```bash | |
| make setup-secrets | |
| # Then edit tests/secrets/cred.py to add your API credentials | |
| ``` | |
| 5. **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:7860 yuga-planner | |
| ``` | |
| --- | |
| ## 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/) | |