{"id":30117329,"url":"https://github.com/pythonhealthdatascience/des_agent","last_synced_at":"2025-08-10T10:41:34.001Z","repository":{"id":307332939,"uuid":"1020084885","full_name":"pythonhealthdatascience/des_agent","owner":"pythonhealthdatascience","description":"An AI agent that can discovery, run, experiment, and report results from any DES model setup as a MCP server.","archived":false,"fork":false,"pushed_at":"2025-08-07T15:06:55.000Z","size":899,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-07T16:31:49.373Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pythonhealthdatascience.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-15T10:12:03.000Z","updated_at":"2025-07-30T16:33:30.000Z","dependencies_parsed_at":"2025-07-30T19:10:03.528Z","dependency_job_id":null,"html_url":"https://github.com/pythonhealthdatascience/des_agent","commit_stats":null,"previous_names":["pythonhealthdatascience/des_agent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/pythonhealthdatascience/des_agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pythonhealthdatascience%2Fdes_agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pythonhealthdatascience%2Fdes_agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pythonhealthdatascience%2Fdes_agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pythonhealthdatascience%2Fdes_agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pythonhealthdatascience","download_url":"https://codeload.github.com/pythonhealthdatascience/des_agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pythonhealthdatascience%2Fdes_agent/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269712874,"owners_count":24463215,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-10T10:41:30.609Z","updated_at":"2025-08-10T10:41:33.970Z","avatar_url":"https://github.com/pythonhealthdatascience.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DES Experimentation Agent\n\n\u003e **Advanced AI agents for discrete event simulation using self-reflection and task planning**\n\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16616715.svg)](https://doi.org/10.5281/zenodo.16616715)\n\nAn intelligent agent system that demonstrates reasoning patterns for simulation experimentation through the **Model Content Protocol (MCP)**. This project showcases two agent architectures—**self-reflection** and **task planning**—applied to a healthcare call centre optimization problem.\n\n\u003cimg src=\"images/agent_self_reflect_demo.gif\" width=\"600\" alt=\"Demo animation\"\u003e\n\n## 🎯 Overview\n\nThis pilot project explores how AI agents can autonomously discover, configure, and experiment with discrete event simulation models. By implementing advanced reasoning patterns like **self-reflection** and **multi-step task planning**, the agents can intelligently reason about simulation parameters, learn from validation failures, and run models based on natural language interaction.\n\n### Key Innovations\n\n- **🧠 Self-Reflection Agent**: Uses LangGraph state machines to iteratively refine parameters through validation feedback loops\n- **📋 Planning Agent**: Employs LangChain and a dual-LLM architecture for task decomposition and execution planning  \n- **🔄 MCP Integration**: Uses the Model Content Protocol for standardized tool and resource access to the simulation model\n- **⚡ Intelligent Parameter Generation**: Converts natural language to structured simulation parameters with validation\n- **🎯 Application**: Healthcare call centre optimization with nurse callback modeling\n\n## 🏗️ Architecture\n\nThe system consists of three main layers connected through the Model Content Protocol:\n\n\u003cimg src=\"./images/des_agent_architecture.png\" alt=\"drawing\" width=\"500\"/\u003e\n\n### 🤖 Agent Layer\nTwo complementary agent architectures demonstrate different reasoning approaches:\n\n**Planning Agent** (`agent_planning_workflow.py`)\n- **Dual LLM Architecture**: Separate models for reasoning/planning and result summarization\n- **Dynamic Task Planning**: LLM generates step-by-step execution plans from available MCP capabilities\n- **Memory-Driven Execution**: Maintains state between plan steps for complex workflows\n- **Flexible Model Selection**: Command-line options for different LLM models and debug modes\n\n**Self-Reflection Agent** (`agent_self_reflection.py`)  \n- **LangGraph State Machine**: Graph-based workflow with conditional routing and retry logic\n- **Validation-Driven Learning**: Analyzes parameter validation failures and iteratively improves\n- **Bounded Retry Logic**: Intelligent bailout mechanisms prevent infinite loops\n- **Failure Analysis**: Tracks validation history and provides detailed error reporting\n\n### 🌐 MCP Layer\n**FastMCP Server** (`mcp_server.py`) provides standardized access to:\n- **🛠️ Tools**: Simulation execution and parameter validation\n- **📚 Resources**: Schema definition for the model parameters and model documentation  \n- **💬 Prompts**: LLM templates for parameter generation\n- **🔍 Auto-Discovery**: Dynamic capability enumeration for agent planning\n\n### 🏥 Simulation Layer\n**Healthcare Call Centre Model** (`model.py`) - A simple discrete event simulation featuring:\n\n#### Model Components\n- **👥 Resources**: Call operators and nurses with configurable capacity\n- **📞 Patient Flow**: Exponential arrival patterns with triangular service times\n- **🔄 Nurse Callbacks**: 40% of patients require follow-up consultations\n- **📊 Performance Metrics**: Wait times, utilization rates, and callback statistics\n\n#### Simulation Features\n- **🎲 Stochastic Modeling**: Multiple probability distributions (Exponential, Triangular, Uniform, Bernoulli)\n- **🔀 Multiple Random Streams**: Reproducible results, using common random numbers\n- **⏱️ Event-Driven Processing**: `SimPy` based discrete event engine\n- **🎛️ Configurable Parameters**: Staff levels, demand patterns, service times, callback probabilities\n\n#### Key Metrics\n- **Mean waiting times** for operators and nurses\n- **Resource utilization rates** for staff optimization\n- **Callback rates** for service quality assessment\n- **Patient throughput** for capacity planning\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- Python 3.11+\n- [Ollama](https://ollama.ai/) server running locally\n- Mamba/conda or pip for environment management\n\n### Development Environment\n\nThis project was developed and tested on the following system configuration:\n\n**Hardware Specifications:**\n- **System**: Dell XPS 8960\n- **CPU**: 13th Gen Intel i9-13900K (32 cores) @ 5.900GHz\n- **GPU**: NVIDIA GeForce RTX 4080\n- **RAM**: 64GB\n- **Operating System**: Ubuntu 24.04\n\n**Performance Notes:**\n- LLM inference with larger models (gemma3:27b, deepseek-r1:32b) benefits significantly from the high-core CPU and substantial RAM\n- GPU acceleration is utilized for compatible models through Ollama\n- The system handles concurrent agent execution and simulation processing efficiently\n\n*Note: While these specifications represent the development environment, the project can run on more modest hardware configurations. Minimum requirements are Python 3.11+ and sufficient RAM for your chosen LLM models.*\n\n\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/pythonhealthdatascience/des_agent\n   cd des-agent\n   ```\n\n2. **Create and activate environment**\n   ```bash\n   # Using mamba (recommended)\n   mamba env create -f environment.yml\n   mamba activate des-agent\n   ```\n\n   ```bash\n   # Or using pip\n   pip install fastmcp pandas simpy langgraph langchain langchain-ollama rich\n   ```\n\n3. **Set up Ollama models**\n   ```bash\n   # Install recommended models\n   ollama pull gemma3:27b     # Best performance for planning and parameter generation\n   ollama pull llama3:latest  # Good for summarization\n   ollama pull mistral:7b     # Potentially faster alternative for self-reflection\n   ```\n\n### Quick Start\n\n1. **Start the MCP server**\n   ```bash\n   python mcp_server.py\n   ```\n   Server will be available at `http://localhost:8001/mcp`\n\n2. **Run the Self-Reflection Agent**\n   ```bash\n   python agent_self_reflection.py --llm gemma3:27b\n   ```\n   \n   Example interaction:\n   ```\n   Simulation request: Simulate 14 operators, 12 nurses and 5% extra demand\n   ```\n\n3. **Run the Planning Agent**\n   ```bash\n   python agent_planning_workflow.py --planning gemma3:27b --summary llama3:latest\n   ```\n\n## 💡 Usage Examples\n\n### Self-Reflection Agent\nThe self-reflection agent demonstrates error recovery and learning:\n```bash\npython agent_self_reflection.py --llm gemma3:27b\n```\n\n**Natural Language Input:**\n- `\"Simulate 14 operators, 12 nurses and 5% extra demand\"`\n- `\"Run scenario with high staffing and normal call volume\"`  \n- `\"Test configuration with minimal staff\"`\n\n\u003cimg src=\"./images/simple_agent_self_reflection.png\" alt=\"drawing\" width=\"300\"/\u003e\n\n**Key Features:**\n- ✅ **Automatic Parameter Validation**: Catches invalid parameters and self-corrects\n- 🔄 **Retry Logic**: Up to 4 attempts with validation feedback incorporation\n- 📈 **Learning from Errors**: Uses validation messages to improve subsequent attempts\n- 📊 **Detailed Reporting**: Shows validation history and failure analysis\n\n### Planning Agent  \nThe planning agent showcases sophisticated task decomposition:\n\n```bash\npython agent_planning_workflow.py --planning gemma3:27b --summary llama3:latest --debug\n```\n\n**Workflow Demonstration:**\n1. **🧠 Task Planning**: LLM analyzes available MCP capabilities and creates execution plan\n2. **📋 Step Execution**: Dynamically executes each planned step (resource queries, parameter generation, validation, simulation)\n3. **💾 Memory Management**: Maintains state between steps for complex workflows\n4. **📊 Result Formatting**: Second LLM summarizes parameters and results in structured tables\n\n## 🔧 Configuration\n\n### Model Selection\nBoth agents support flexible LLM model configuration:\n\n```bash\n# Self-reflection agent\npython agent_self_reflection.py --llm mistral:7b\n\n# Planning agent with dual models\npython agent_planning_workflow.py \\\n  --planning deepseek-r1:32b \\\n  --summary llama3.1:8b \\\n  --debug\n```\n\n### Simulation Parameters\nThe healthcare call centre model supports extensive configuration through the JSON schema:\n\n```json\n{\n  \"n_operators\": 14,        // Call operators (1-100)\n  \"n_nurses\": 12,           // Nurses for callbacks (1-50) \n  \"mean_iat\": 0.57,         // Inter-arrival time (0.1-10.0 minutes)\n  \"call_low\": 5.0,          // Min call duration \n  \"call_mode\": 7.0,         // Most likely call duration\n  \"call_high\": 10.0,        // Max call duration\n  \"callback_prob\": 0.4,     // Nurse callback probability (0-1)\n  \"nurse_consult_low\": 10.0, // Min nurse consultation time\n  \"nurse_consult_high\": 20.0, // Max nurse consultation time\n  \"run_length\": 1000,       // Simulation runtime (minutes)\n  \"random_seed\": 42         // For reproducible results\n}\n```\n\n## 🧪 Advanced Features\n\n### Self-Reflection Capabilities\nThe LangGraph-based agent demonstrates sophisticated error handling:\n\n- **🔍 Validation Analysis**: Parses structured error messages from parameter validation\n- **🔄 Iterative Improvement**: Incorporates feedback into subsequent parameter generation attempts  \n- **📊 History Tracking**: Maintains detailed logs of validation attempts and outcomes\n- **🎯 Bounded Retry**: Intelligent bailout after maximum attempts to prevent infinite loops\n\n### Task Planning \u0026 Reasoning\nThe planning agent showcases advanced reasoning about task decomposition:\n\n- **🧠 Dynamic Planning**: Generates execution plans based on available MCP server capabilities\n- **📋 Step-by-Step Execution**: Breaks complex requests into manageable subtasks\n- **🔗 Dependency Management**: Ensures information dependencies are resolved in correct order\n- **💾 Stateful Execution**: Maintains memory across plan steps for complex workflows\n\n### MCP Protocol Integration\nBoth agents leverage the full Model Content Protocol specification:\n\n- **🛠️ Tool Discovery**: Dynamic enumeration of available simulation and validation tools\n- **📚 Resource Access**: Automatic retrieval of schemas, documentation, and configuration data\n- **💬 Prompt Templates**: Server-provided LLM prompts ensure consistent parameter generation\n- **🔄 Standardized Communication**: JSON-RPC messaging for reliable agent-server interaction\n\n## 📊 Results \u0026 Outputs\n\n### Simulation Metrics\nThe healthcare model provides the following performance metrics:\n\n| Metric | Description | Use Case |\n|--------|-------------|----------|\n| Mean Waiting Time | Average time patients wait for operators | Service quality assessment |\n| Operator Utilization | Percentage of time operators are busy | Staffing optimization |\n| Nurse Waiting Time | Average wait for nurse callbacks | Callback service efficiency |\n| Nurse Utilization | Percentage of nurse availability used | Nurse staffing planning |\n| Callback Rate | Percentage of calls requiring nurse follow-up | Service complexity analysis |\n\n\u003c!-- ### Agent Performance Analysis\nBoth agents provide detailed execution reporting:\n\n- **📈 Self-Reflection Agent**: Validation history, retry statistics, error analysis\n- **📋 Planning Agent**: Step-by-step execution logs, planning duration, memory usage\n- **🎯 Success Metrics**: Parameter validation, simulation completion times --\u003e\n\n## 🔬 Research Applications\n\nThis project demonstrates several cutting-edge research areas:\n\n### Agent Reasoning Patterns\n- **🔄 Self-Reflection**: How agents can learn from failures and iteratively improve\n- **📋 Task Planning**: LLM-driven decomposition of complex multi-step workflows\n- **🧠 Meta-Reasoning**: Agents reasoning about their own reasoning processes\n\n### Simulation Integration\n- **🤖 AI-Driven Modeling**: Natural language interfaces for complex simulation configuration\n- **⚡ Automated Experimentation**: Agents conducting systematic simulation studies\n- **📊 Intelligent Analysis**: Automated interpretation of simulation results\n\n### Protocol Standardization  \n- **🌐 MCP Adoption**: Practical implementation of Anthropic's Model Content Protocol\n- **🔧 Tool Integration**: Seamless connection of AI agents with external systems\n- **📋 Capability Discovery**: Dynamic enumeration and utilization of available tools\n\n## 🚀 Future Enhancements\n\n### Multi-Agent Orchestration\n- **👥 Agent Collaboration**: Multiple agents working together on complex experiments\n- **🎯 Specialized Roles**: Planning, execution, analysis, and reporting agents\n- **🔄 Workflow Coordination**: Advanced orchestration patterns for simulation studiea\n\n### Advanced Simulation Features\n- **🏥 Multi-Model Support**: Integration with diverse simulation domains beyond healthcare\n- **📊 Real-time Analytics**: Live dashboard updates during simulation execution\n- **🎛️ Interactive Parameter Tuning**: Dynamic adjustment of simulation parameters\n\n### Enhanced Reasoning\n- **🧠 Causal Reasoning**: Understanding cause-and-effect relationships in simulation results\n- **📈 Optimization Integration**: Automatic parameter optimization using simulation feedback\n- **🎯 Goal-Oriented Planning**: Agents working backwards from desired outcomes\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n**MCP Server Connection Failed**\n- Ensure the MCP server is running on `http://localhost:8001/mcp`\n- Check that no other processes are using port 8001\n- Verify FastMCP installation: `pip install fastmcp`\n\n**Ollama Model Not Found**\n- Confirm model installation: `ollama list`\n- Pull missing models: `ollama pull gemma3:27b`\n- Check Ollama server status: `ollama serve`\n\n**Parameter Validation Failures**\n- Review the schema.json file for parameter constraints\n- Ensure numeric values are within specified ranges\n- Verify all required parameters are provided\n\n**Agent Timeout or Performance Issues**\n- Try smaller LLM models (e.g., `llama3:latest` instead of `gemma3:27b`)\n- Increase retry limits in agent configuration\n- Monitor system resources during execution\n\nFor additional support, please open an issue with detailed error logs and system information.\n\n## 🤝 Contributing\n\nThis project welcomes contributions in several areas:\n\n- **🔬 New Agent Architectures**: Alternative reasoning patterns and workflow designs\n- **🏥 Simulation Models**: Additional domains and model types\n- **🛠️ MCP Extensions**: New tools, resources, and capabilities\n- **📊 Analysis Features**: Enhanced result interpretation and visualization\n\n\u003c!-- ## 📚 References \u0026 Related Work\n\nThis project builds upon and demonstrates several key research areas:\n\n- **Model Content Protocol**: [Anthropic's MCP Specification](https://modelcontextprotocol.io/)\n- **LangGraph**: [Agent Workflow Orchestration](https://langchain-ai.github.io/langgraph/)\n- **SimPy**: [Discrete Event Simulation in Python](https://simpy.readthedocs.io/)\n- **Self-Reflection in AI**: [Reflexion Framework](https://arxiv.org/abs/2303.11366)\n- **Agent Planning**: [Task Decomposition and Planning](https://research.csiro.au/ss/science/projects/agent-design-pattern-catalogue/) --\u003e\n\n## 📜 License\n\nThis project is released under the MIT License. See `LICENSE` file for details.\n\n---\n\n**Built for the future of intelligent simulation** 🚀\n\n*This project demonstrates advanced AI agent capabilities for simulation experimentation, showcasing self-reflection, task planning, and protocol standardization through practical healthcare optimization applications.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpythonhealthdatascience%2Fdes_agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpythonhealthdatascience%2Fdes_agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpythonhealthdatascience%2Fdes_agent/lists"}