run.py

#!/usr/bin/env python
"""GeneralsBot — main CLI entry point.

All pipeline functionality is exposed through this single script.
See README.md for detailed usage examples.

Quick start:
    python run.py                         # GUI game, expander vs random
    python run.py --mode headless         # batch games, periodic stats
    python run.py --mode human            # human vs AI
    python run.py --agent placeholder     # CNN placeholder vs random
    python run.py --grid 15x15 --seed 42  # custom map
"""

from __future__ import annotations

import argparse
import sys
from pathlib import Path

# Ensure src/ and generals-bots/ are on sys.path
PROJECT_ROOT = Path(__file__).resolve().parent
sys.path.insert(0, str(PROJECT_ROOT / "src"))
sys.path.insert(0, str(PROJECT_ROOT / "generals-bots"))


def parse_dims(s: str) -> tuple[int, int]:
    """Parse 'HxW' into (H, W)."""
    parts = s.split("x")
    if len(parts) != 2:
        raise argparse.ArgumentTypeError(f"expected HxW, got '{s}'")
    return int(parts[0]), int(parts[1])


def parse_float_pair(s: str) -> tuple[float, float]:
    """Parse 'X.Y-Z.W' into (float, float)."""
    parts = s.split("-")
    if len(parts) != 2:
        raise argparse.ArgumentTypeError(f"expected X.X-Y.Y, got '{s}'")
    return float(parts[0]), float(parts[1])


def parse_int_pair(s: str) -> tuple[int, int]:
    """Parse 'X-Y' into (int, int)."""
    parts = s.split("-")
    if len(parts) != 2:
        raise argparse.ArgumentTypeError(f"expected X-Y, got '{s}'")
    return int(parts[0]), int(parts[1])


def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        description="GeneralsBot — Non-invasive perception + RL agent for generals.io",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python run.py                                              # GUI game, expander vs random
  python run.py --mode headless --games 500 --stats-interval 50
  python run.py --agent placeholder --grid 8x8
  python run.py --grid 15x15 --seed 42 --mountain-density 0.20-0.30
  python run.py --use-perception                             # full Part A + B pipeline
  python run.py --fps 20 --show-tile-types                   # faster + debug overlay
  python run.py --mode human                                 # play vs AI yourself
  python run.py --mode human --opponent expander             # vs expander bot
  python run.py --mode evaluate --agent model --model-path checkpoints/best.eqx
  python run.py --mode evaluate --agent model --model-path best.eqx --opponent expander --games 200
        """,
    )

    # ── Mode ──────────────────────────────────────────────────────────
    p.add_argument("--mode", choices=["gui", "headless", "human", "evaluate", "live", "simulated_gui", "human_gui"],
                   default="gui",
                   help="Pipeline mode (default: gui). "
                        "'simulated_gui' = headless batch, 'human_gui' = interactive pygame window.")
    p.add_argument("--use-perception", action="store_true",
                   help="Enable Part A perception (full pipeline). "
                        "Default: decision-only (bypass perception).")

    # ── Agents ────────────────────────────────────────────────────────
    p.add_argument("--agent", choices=["placeholder", "random", "expander", "model"],
                   default="expander", help="Our agent type (default: expander)")
    p.add_argument("--opponent", choices=["random", "expander", "model"],
                   default="random", help="Opponent agent type (default: random)")
    p.add_argument("--model-path", default=None,
                   help="Path to trained model weights (for --agent model)")
    p.add_argument("--opponent-model-path", default=None,
                   help="Path to opponent model weights")

    # ── Map generation ────────────────────────────────────────────────
    p.add_argument("--grid", type=parse_dims, default=(10, 10),
                   help="Grid size as HxW (default: 10x10)")
    p.add_argument("--seed", type=int, default=None,
                   help="Random seed for reproducibility (default: random)")
    p.add_argument("--mountain-density", type=parse_float_pair,
                   default=(0.18, 0.26),
                   help="Mountain density range as X.X-Y.Y (default: 0.18-0.26)")
    p.add_argument("--num-cities", type=parse_int_pair, default=(9, 11),
                   help="City count range as X-Y (default: 9-11)")
    p.add_argument("--min-generals-distance", type=int, default=3,
                   help="Min BFS distance between generals (default: 3)")
    p.add_argument("--max-generals-distance", type=int, default=None,
                   help="Max BFS distance between generals (default: unlimited)")
    p.add_argument("--castle-values", type=parse_int_pair, default=(40, 51),
                   help="Castle army value range as X-Y (default: 40-51)")

    # ── Game ──────────────────────────────────────────────────────────
    p.add_argument("--truncation", type=int, default=500,
                   help="Max ticks before forced draw (default: 500)")
    p.add_argument("--fps", type=int, default=10,
                   help="GUI render FPS (default: 10)")
    p.add_argument("--speed", type=float, default=1.0,
                   help="Game speed multiplier (default: 1.0)")

    # ── Headless ──────────────────────────────────────────────────────
    p.add_argument("--num-envs", type=int, default=256,
                   help="Parallel environments in headless mode (default: 256)")
    p.add_argument("--games", type=int, default=100,
                   help="Games to play in headless mode (default: 100)")
    p.add_argument("--stats-interval", type=int, default=10,
                   help="Print stats every N games in headless mode (default: 10)")

    # ── Output ────────────────────────────────────────────────────────
    p.add_argument("--quiet", action="store_true",
                   help="Suppress non-essential output")
    p.add_argument("--show-tile-types", action="store_true",
                   help="Overlay tile-type debug labels on the grid")

    # ── Live ──────────────────────────────────────────────────────────
    p.add_argument("--monitor-idx", type=int, default=0,
                   help="Monitor index for screen capture (default: 0)")

    return p


def main():
    parser = build_parser()
    args = parser.parse_args()

    from generals_bot.config import Config
    from generals_bot.orchestrator import Orchestrator

    cfg = Config(
        mode=args.mode,
        use_perception=args.use_perception or args.mode == "live",
        agent=args.agent,
        opponent=args.opponent,
        model_path=args.model_path,
        opponent_model_path=args.opponent_model_path,
        grid_dims=args.grid,
        seed=args.seed,
        mountain_density=args.mountain_density,
        num_cities=args.num_cities,
        min_generals_distance=args.min_generals_distance,
        max_generals_distance=args.max_generals_distance,
        castle_values=args.castle_values,
        truncation=args.truncation,
        fps=args.fps,
        speed=args.speed,
        num_envs=args.num_envs,
        num_games=args.games,
        stats_interval=args.stats_interval,
        verbose=not args.quiet,
        show_tile_types=args.show_tile_types,
        monitor_idx=args.monitor_idx,
        live_mode=(args.mode == "live"),
    )

    orch = Orchestrator(cfg)
    orch.run()


if __name__ == "__main__":
    main()