{"data":{"kind":"file","path":"README.md","version_id":"p0zy2afmgffo5rchk8ie5htl","entry":{"name":"README.md","path":"README.md","is_directory":false,"size":3543,"modified_at":"2025-09-14T14:57:51.709000","content_hash":"ad28431a0540bf991434240379304e819710e4b4bb955d2106b695ab89a28571"},"entries":[],"content":"# MAPP - Multi-Agent Path Planning Environment\n\n## Overview\n- **Environment ID**: `MAPP`\n- **Description**: A turn-based grid environment where multiple agents navigate simultaneously to assigned goals while avoiding obstacles and collisions.\n- **Tags**: pathfinding, multi-agent, grid-world, reinforcement-learning, coordination\n\n## Features\n- Configurable grid sizes and obstacle densities\n- Multiple agents with individual start and goal positions\n- Turn-based movement with **5 possible actions per agent**\n- Collision checking between agents and obstacles\n- Reward system encouraging goal completion, safety, and efficiency\n\n## Coordinate System and Actions\n- Uses a **top-left origin coordinate system** where (0,0) is top-left of the grid\n- Coordinates: x increases rightward, y increases downward\n- Agent action codes and effects (5 actions):\n\n| Action Code | Description | Movement (dx, dy) |\n|-------------|-------------|-------------------|\n| 0           | Move Left   | (-1, 0)           |\n| 1           | Move Up     | (0, -1)           |\n| 2           | Stay        | (0, 0)            |\n| 3           | Move Down   | (0, 1)            |\n| 4           | Move Right  | (1, 0)            |\n\n## Evaluation Metrics\n- **Goal completion rate**: Fraction of agents successfully reaching goals  \n- **Collision count**: Number of collisions encountered  \n- **Path efficiency**: Ratio of shortest path length to actual path taken  \n\n## How to Run\n\nRun evaluation with the repository's vf-eval tool (default settings):\n\n```bash\nuv run vf-eval MAPP\n```\n\nExample of a real evaluation run:\n\n```bash\nvf-eval MAPP -m gpt-4o --api-key-var LLM_API_KEY -n 4 -r 1 -t 1024 -T 0.5 -a '{\"num_scenarios\":10,\"seed\":42,\"max_tries\":50,\"collision_verbose\":true,\"eval_filename\":\"mapp_data/eval_scenarios.json\"}' --verbose\n```\n\n\n## Environment Parameters\n\n| Parameter               | Type                | Default                          | Description                                            |\n|-------------------------|---------------------|----------------------------------|--------------------------------------------------------|\n| `num_scenarios`         | int                 | 128                              | Number of generated training scenarios                 |\n| `grid_sizes`            | List[Tuple[int,int]]| [(5,5),(6,6)]                    | Candidate grid sizes used when generating scenarios    |\n| `agent_counts`          | List[int]           | [2,3,4]                          | Candidate numbers of agents per scenario               |\n| `obstacle_densities`    | List[float]         | [0.1,0.2,0.3]                    | Candidate obstacle densities used during generation    |\n| `max_tries`             | int                 | 200                              | Maximum attempts to generate a valid scenario          |\n| `max_steps`             | int                 | 32                               | Maximum steps per episode                              |\n| `seed`                  | int                 | 42                               | Random seed for scenario generation                    |\n| `scenario_verbose`      | bool                | False                            | If true, scenario generator prints verbose info        |\n| `collision_verbose`     | bool                | False                            | If true, collision checks emit debug output            |\n| `eval_filename`         | Optional[str]       | None                             | Optional path to a dataset of evaluation scenarios     |","encoding":"utf-8","truncated":false,"total_bytes":3543},"status":null}