Warehouse Multi-Agent System (MAS)

Deterministic grid-based multi-agent warehouse coordination with explicit planning, bounded safety verification, and counterexample-driven refinement.

What This Project Does

Robots operate on a 2D grid:

• pick requested shelves,
• deliver them to goal cells,
• avoid vertex and edge collisions,
• and optionally run verification/refinement loops to improve safety.

This is a non-ML system. Behavior is algorithmic and reproducible (optionally with --seed).

Demo

Also available as video: docs/demo.mp4.

Core Components

• main.py: CLI entry point and orchestration.
• env.py: warehouse environment dynamics, rewards, collisions, rendering hooks, evaluation loop.
• agent.py: robot state/action primitives (FORWARD, TURN_LEFT, TURN_RIGHT, PICK_DROP, WAIT).
• pathfinding.py: cooperative planner with:
  • time-aware A* on (x, y, direction, t),
  • rolling reservations (position + edge),
  • assignment logic,
  • idle tracking and deadlock escape behavior,
  • injected hard constraints from refinement.
• symmetry_reduction.py: role-orbit detection and canonical quotient keys.
• verification.py: bounded quotient-state safety checks and counterexample extraction.
• refinement.py: conflict/trace-to-constraint conversion.
• renderer.py: pygame renderer (grid, robots, shelves, goals, conflict overlays).
• config.py + config.yaml: defaults + YAML overrides.

Installation

pip install -r requirements.txt

Dependencies currently listed:

• pygame
• pyyaml

Quick Start

Interactive mode (default mode):

python main.py

Batch simulation:

python main.py --mode simulate --episodes 8 --steps-per-episode 200

Evaluation:

python main.py --mode eval --eval-episodes 3 --steps-per-episode 150

Verification + refinement:

python main.py --verify-refine --verify-horizon 30 --verify-trials 20

Symmetry/orbit inspection:

python main.py --detect-symmetry

CLI Reference

main.py --help exposes:

• --mode {interactive,simulate,eval} (default: interactive)
• --render (enables rendering in simulate mode; interactive always renders)
• --config CONFIG (default: config.yaml)
• --seed SEED
• --cell-size CELL_SIZE
• --episodes EPISODES (default: 8)
• --steps-per-episode STEPS_PER_EPISODE (default: 200)
• --log-interval LOG_INTERVAL (default: 1)
• --eval-episodes EVAL_EPISODES (default: 3)
• --plan-horizon PLAN_HORIZON
• --detect-symmetry
• --verify-refine
• --verify-horizon VERIFY_HORIZON
• --verify-trials VERIFY_TRIALS
• --verify-include-shelves
• --verify-progress VERIFY_PROGRESS (default: 1)
• --min-separation MIN_SEPARATION
• --refine-iterations REFINE_ITERATIONS
• --refine-max-constraints REFINE_MAX_CONSTRAINTS

Configuration (config.yaml)

The runtime loads config.yaml via cfg.load_from_yaml(...). CLI flags override config values when provided.

grid:
  width: 16
  height: 16
  cell_size: 30

agents:
  num_agents: 6
  num_shelves: 8
  goals:
    - [7, 14]
    - [8, 14]

planning:
  horizon: 30
  astar_max_nodes: 3500
  idle_limit: 4
  reservation_window: 8
  unplanned_hold_steps: 2
  escape_idle_steps: 6

render:
  fps: 1

verification:
  min_separation: 1
  horizon: 30
  trials: 20

refinement:
  iterations: 2
  max_constraints: 100

paths:
  model_dir: models

Note: paths.model_dir is present in YAML but is not consumed by the current runtime code.

Controls (Interactive/Rendered)

• Close window or press Q: quit.
• Left click robot cell: select agent.
• Tab, Right, .: next agent.
• Left, ,: previous agent.

Testing

Run bundled suite runner:

python tests/run_tests.py

Run individual suites directly:

python tests/test_rewards.py
python tests/test_env.py
python tests/test_agent.py
python tests/test_training.py
python tests/test_integration.py
python tests/test_refinement.py
python tests/test_verification_refinement.py

Documentation

• Web documentation site: docs/index.html
• Alternate reader view: docs/reader.html
• PDF/Markdown chapter library: docs/pdf/
  • includes architecture, planning, verification, refinement, CLI/config, and execution playbooks
• Full compiled documentation PDF:
  • docs/pdf/Warehouse_MAS_Documentation.pdf

Repository Layout

Top-level runtime files are at the project root (main.py, env.py, pathfinding.py, etc.).

The repository also contains src/warehouse_mas/... package directories (algorithms, coordination, simulation, visualization, etc.) as a broader project structure scaffold.

License

MIT License. See LICENSE.