training-and-cli

Training and CLI

Use this sub-skill when the task is to run MuZero General, build a safe training or testing command, use the MuZero Python API, adjust a JSON config override, understand Ray workers, inspect the upstream CartPole CI recipe, or debug training/runtime startup failures.

Fast route

1. Read training-workflows.md for self-contained bundled-source entry points, Python API patterns, TensorBoard usage, hyperparameter search, and safe smoke overrides.

2. Read api-reference.md when you need verified signatures, constructor behavior, worker roles, checkpoint lifecycle, or replay/trainer/shared-storage interactions.

3. Read troubleshooting.md for invalid game/config names, Ray startup failures, GPU resource conflicts, long-running training, TensorBoard confusion, Gym/Ray warnings, or interactive menu blocking.

4. Run the bundled safe smoke helper before real training:

   python sub-skills/training-and-cli/scripts/muzero_cli_smoke.py --game tictactoe --training-steps 0 --json
   

   The helper imports the bundled runtime/source/ snapshot by default, constructs MuZero, applies CPU-safe overrides, reports key config/checkpoint facts, and shuts Ray down. It does not train unless --run-train is explicitly supplied. Use --repo-root only for a staged editable copy or another target checkout.

Primary workflows

• Self-contained entry point: from the skill root, use python scripts/run_muzero.py --game <game> --config-json '<json-config>' --mode construct|train|test. It runs against bundled runtime/source/ unless --repo-root points to an intentionally staged copy or target checkout. Use JSON overrides for bounded runs such as {"training_steps": 0, "num_simulations": 1, "max_moves": 1, "save_model": false}.
• Python API run: instantiate MuZero(game_name, config=None, split_resources_in=1), optionally call load_model(...), then call train(log_in_tensorboard=True|False) or test(render=False, ...).
• Smoke before training: prefer the bundled helper or python scripts/run_muzero.py --game tictactoe --safe-smoke --mode construct --json before launching Ray workers that can run indefinitely.
• Real training: choose a game/config in sibling games-and-configs, validate model/search shapes in models-and-mcts, then run training with a deliberate result path and TensorBoard plan.
• Checkpoint-aware runs: read checkpoints-and-diagnostics before loading model.checkpoint or replay_buffer.pkl artifacts.

Safety boundaries

• Do not run the upstream interactive menu (runtime/source/muzero.py with no args) in automation unless the user explicitly wants prompts. Prefer scripts/run_muzero.py, which has no interactive menu mode.
• Do not run the upstream 7,500-step CartPole CI recipe as a normal smoke; it is an expensive native candidate, not the default verification path.
• Do not enable train_on_gpu, selfplay_on_gpu, or reanalyse_on_gpu while setting max_num_gpus = 0.
• Do not assume all optional games are installed. Atari, LunarLander/Box2D, MiniGrid, and OpenSpiel need extra packages; route those checks to games-and-configs.

When to stop and ask

Ask for user approval before long training, installing optional game dependencies, downloading Atari ROM/assets, using GPUs for a heavy run, or overwriting/checkpointing into a user-important results directory. Otherwise use bounded CPU-safe smoke checks first.