{"id":47766135,"url":"https://github.com/hsu-aut/blocksworld_simulation","last_synced_at":"2026-04-03T07:01:07.298Z","repository":{"id":327558139,"uuid":"1013775799","full_name":"hsu-aut/blocksworld_simulation","owner":"hsu-aut","description":"Visual blocksworld simulation with Pygame GUI and Flask REST API for AI planning research. Features 50 scenarios, multiple constraint sets, and LLM integration via MCP.","archived":false,"fork":false,"pushed_at":"2026-02-03T08:23:44.000Z","size":380,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-03T21:23:54.979Z","etag":null,"topics":["ai-agents","ai-planning","ai-research","automated-planning","blocksworld","large-language-model","llm","mcp","model-context-protocol","simulation","tower-of-hanoi"],"latest_commit_sha":null,"homepage":"","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/hsu-aut.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-04T12:52:30.000Z","updated_at":"2026-02-03T08:23:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hsu-aut/blocksworld_simulation","commit_stats":null,"previous_names":["hsu-aut/blocksworld_simulation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hsu-aut/blocksworld_simulation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hsu-aut%2Fblocksworld_simulation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hsu-aut%2Fblocksworld_simulation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hsu-aut%2Fblocksworld_simulation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hsu-aut%2Fblocksworld_simulation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hsu-aut","download_url":"https://codeload.github.com/hsu-aut/blocksworld_simulation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hsu-aut%2Fblocksworld_simulation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31341829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T06:57:30.245Z","status":"ssl_error","status_checked_at":"2026-04-03T06:57:29.849Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-agents","ai-planning","ai-research","automated-planning","blocksworld","large-language-model","llm","mcp","model-context-protocol","simulation","tower-of-hanoi"],"created_at":"2026-04-03T07:00:32.954Z","updated_at":"2026-04-03T07:01:07.287Z","avatar_url":"https://github.com/hsu-aut.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧱 Blocksworld Simulation\n\nA visual simulation environment for the classic Blocksworld AI planning problem. The simulation features a robot arm that can manipulate colored blocks across multiple stacks, with support for both interactive GUI control and programmatic access via a REST API.\n\n## ✨ Features\n\n- **Interactive GUI**: Pygame-based visual simulation with real-time block manipulation\n- **REST API**: Complete Flask-based API for programmatic control and automation\n- **LLM-Ready**: Compatible with AI assistants through our [MCP Server](https://github.com/hsu-aut/llmstudy_mcp-server)\n- **Predefined Scenarios**: 50 built-in challenges across 5 categories with varying difficulty levels\n- **Plan Execution \u0026 Verification**: Test AI-generated plans before execution\n- **Constraint Sets**: Multiple rule sets including standard blocksworld, size-based constraints, and partial observability\n- **Keyboard Control**: Quick manual testing and experimentation\n\n## 📊 Benchmark Leaderboard\n\nThe following table shows benchmark results for different approaches on the given blocksworld scenarios.\n\n| Metric                             | Category   | [Single Agent](https://github.com/hsu-aut/blocksworld_single-agent) (OpenAI o3) | Approach 2 | Approach 3 |\n|------------------------------------|------------|---------------------------------------------------------------------------------|------------|------------|\n| **Success Rate**                   | C1         | 80%                                                                             |            |            |\n|                                    | C2         | 70%                                                                             |            |            |\n|                                    | C3         | 100%                                                                            |            |            |\n|                                    | C4         | 70%                                                                             |            |            |\n|                                    | C5         | 60%                                                                             |            |            |\n|                                    | **total**  | **76%**                                                                         |            |            |\n| **Avg. Time [s]**                  | C1         | 75.70                                                                           |            |            |\n|                                    | C2         | 290.00                                                                          |            |            |\n|                                    | C3         | 124.90                                                                          |            |            |\n|                                    | C4         | 731.50                                                                          |            |            |\n|                                    | C5         | 676.30                                                                          |            |            |\n|                                    | **total**  | **379.68**                                                                      |            |            |\n| **Avg. Attempts**                  | C1         | 1.10                                                                            |            |            |\n|                                    | C2         | 1.70                                                                            |            |            |\n|                                    | C3         | 1.80                                                                            |            |            |\n|                                    | C4         | 2.20                                                                            |            |            |\n|                                    | C5         | 3.10                                                                            |            |            |\n|                                    | **total**  | **1.98**                                                                        |            |            |\n| **Avg. Token**                     | C1         | 35,126                                                                          |            |            |\n|                                    | C2         | 111,721                                                                         |            |            |\n|                                    | C3         | 18,195                                                                          |            |            |\n|                                    | C4         | 143,714                                                                         |            |            |\n|                                    | C5         | 192,245                                                                         |            |            |\n|                                    | **total**  | **58,832**                                                                      |            |            |\n| **Avg. Steps vs. Optimum**         | C1         | 1.00                                                                            |            |            |\n|                                    | C2         | 1.20                                                                            |            |            |\n|                                    | C3         | 1.00                                                                            |            |            |\n|                                    | C4         | 1.08                                                                            |            |            |\n|                                    | C5         | 0.90                                                                            |            |            |\n|                                    | **total**  | **1.03**                                                                        |            |            |\n| **Avg. Execution Tool Errors**     | C1         | 0.00                                                                            |            |            |\n|                                    | C2         | 0.00                                                                            |            |            |\n|                                    | C3         | 0.00                                                                            |            |            |\n|                                    | C4         | 0.00                                                                            |            |            |\n|                                    | C5         | 0.50                                                                            |            |            |\n|                                    | **total**  | **0.16**                                                                        |            |            |\n\n## 🚀 Quick Start\n\n### Installation\n\nThe project uses [Poetry](https://python-poetry.org/docs/#installation) for dependency management.\n\n1. Clone the repository:\n\n    ```bash\n    git clone \u003crepository-url\u003e\n    cd blocksworld-simulation\n    ```\n\n2. Install dependencies:\n\n    ```bash\n    poetry install\n    ```\n\n3. Run the simulation:\n\n    ```bash\n    poetry run blocksworld-simulation\n    ```\n\nThe GUI will open, and the REST API will be available at `http://127.0.0.1:5001`.\n\n## 🤖 LLM Integration\n\nWant to use this simulation with your own AI agents or just try it out with LLMs like Claude or ChatGPT? Check out our **[MCP Server for Blocksworld Simulation](https://github.com/hsu-aut/llmstudy_mcp-server)** that exposes the simulation as MCP tools.\n\nThe MCP server allows LLMs to:\n\n- Interact with the simulation through natural language\n- Execute block manipulation actions as tool calls\n- Query the simulation state and rules\n- Verify and execute multi-step plans\n\nPerfect for AI planning research, testing LLM reasoning capabilities, or building AI agents!\n\n## 🎮 Control Methods\n\n### Keyboard Control\n\n- **Start random simulation**: Press `SPACE` (when no simulation is running)\n- **Pick up/Unstack**: Press the letter of the block you want to pick up\n- **Put down**: Press `SPACE` to place the held block on the ground\n- **Stack**: While holding a block, press the letter of the target block to stack on top of it\n- **Stop simulation**: Press `ESC` to stop the current simulation and start a new one\n\n### REST API Control\n\nThe API provides 14 endpoints for complete programmatic control:\n\n#### Simulation Control\n\n- `POST /start_simulation` - Start with a scenario or custom configuration\n- `POST /stop_simulation` - Stop the current simulation\n- `POST /quit` - Quit the application\n\n#### Block Actions\n\n- `POST /pick_up` - Pick up a block from the ground\n- `POST /put_down` - Put down a held block\n- `POST /stack` - Stack one block on another\n- `POST /unstack` - Unstack one block from another\n\n#### Plan Execution\n\n- `POST /execute_plan` - Execute a sequence of actions with GUI animation\n- `POST /verify_plan` - Verify a plan without executing it\n\n#### Information\n\n- `GET /get_status` - Get current simulation state (respects partial observability)\n- `GET /get_full_status` - Get complete simulation state (bypasses partial observability)\n- `GET /get_rules` - Get active constraint rules\n- `GET /scenarios` - List all available scenarios\n- `GET /scenarios/\u003cname_or_id\u003e` - Get details for a specific scenario\n\nFor detailed API documentation with request/response examples, see the [REST API Documentation](./docs/rest-api.md).\n\n## 📋 Example Workflow\n\n```bash\n# 1. Get a scenario with its optimal plan\ncurl http://127.0.0.1:5001/scenarios/Tower%20Building%20Challenge\n\n# 2. Start the scenario\ncurl -X POST http://127.0.0.1:5001/start_simulation \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"scenario_id\": \"Tower Building Challenge\"}'\n\n# 3. Verify your plan before executing\ncurl -X POST http://127.0.0.1:5001/verify_plan \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"plan\": [\n      {\"action\": \"pick_up\", \"block\": \"A\"},\n      {\"action\": \"stack\", \"block1\": \"A\", \"block2\": \"B\"}\n    ]\n  }'\n\n# 4. Execute the plan (watch it in the GUI!)\ncurl -X POST http://127.0.0.1:5001/execute_plan \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"plan\": [\n      {\"action\": \"pick_up\", \"block\": \"A\"},\n      {\"action\": \"stack\", \"block1\": \"A\", \"block2\": \"B\"}\n    ]\n  }'\n```\n\n## 🎯 Constraint Sets\n\nThe simulation supports different rule sets:\n\n- **`base`** (default): Standard blocksworld with limited ground positions\n- **`block_size`**: Blocks with varying sizes - blocks can only be placed on larger or equal-sized blocks\n- **`partial_observability`**: Limited visibility of simulation state\n\nSpecify the constraint set when starting a simulation:\n\n```bash\ncurl -X POST http://127.0.0.1:5001/start_simulation \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"initial_stacks\": [[\"A\"], [\"B\"], [\"C\"]], \"constraint_set\": \"block_size\"}'\n```\n\n## 📚 Documentation\n\n- [REST API Documentation](./docs/rest-api.md) - Complete API reference with examples\n- [MCP Server Repository](https://github.com/hsu-aut/llmstudy_mcp-server) - LLM integration via Model Context Protocol\n- Scenario definitions: `src/blocksworld_simulation/scenarios/definitions/`\n\n## 🔗 Related Projects\n\n- **[Blocksworld MCP Server](https://github.com/hsu-aut/llmstudy_mcp-server)** - Enable LLMs to control the simulation through MCP tools\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhsu-aut%2Fblocksworld_simulation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhsu-aut%2Fblocksworld_simulation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhsu-aut%2Fblocksworld_simulation/lists"}