docs/roadmap.md

Roadmap - Caro5 Hugging Face Space

Phase 1 - Space Baseline

• Serve the prebuilt React/Pixi client from the Gradio/FastAPI Space.
• Route / to /local-setup so visitors can play without a separate websocket server.
• Expose /healthz for deployment checks.

Phase 2 - Hybrid Server Bot

• Add a Python bot package inside this Space for server-side bot decisions.
• Port the required main-project game logic: board coordinates, move validation, win/no-overline checks, candidate generation, and tactical scoring.
• Port alpha-beta tactical search as the first decision layer.
• Port model feature encoding compatible with the current ONNX policy/value metadata.
• Add ONNX inference with env-configured model paths:
  • CARO5_MODEL_ONNX
  • CARO5_MODEL_METADATA
• Add PUCT/MCTS as the strategic decision layer, using the ONNX model when available and heuristic priors otherwise.
• Combine alpha-beta and MCTS so the bot is not pure MCTS:
  • alpha-beta checks immediate wins, forced blocks, and short tactical lines first
  • alpha-beta can hard-override the search for forced tactical moves
  • otherwise alpha-beta scores bias candidate ordering and priors
  • model-guided or heuristic MCTS compares the remaining strategic candidates
• Add two server profiles:
  • balanced: responsive search budget for normal play
  • expert: deeper alpha-beta and higher MCTS budget

Phase 3 - Space API

• Add GET /api/bot/status to report model availability, active model path, metadata, and supported profiles.
• Add POST /api/bot/move to accept board state, rules, current player, move number, and profile.
• Return legal moves with source metadata such as alpha_beta, hybrid, fallback, profile, and elapsed milliseconds.
• Keep the endpoint deterministic when a seed is supplied, but use a stable default seed for normal play.
• Fail safely when the model is unavailable, metadata mismatches, or no legal move exists.

Phase 4 - Client Integration

• Update the local bot turn path to call /api/bot/move instead of always using the browser-only MinimaxAlphaBetaBot.
• Add a local setup control for bot profile: balanced or expert.
• Preserve the current browser minimax bot as fallback when the server bot is unavailable or times out.
• Rebuild the client from the main project and copy the new client/dist into this Space.

Phase 5 - Verification

• Add Python tests for move validation, win/block detection, feature tensor shape, ONNX load failure, and legal bot responses.
• Add focused Python tests for tactical move validation, win/block detection, and legal bot responses.
• Add API tests for /api/bot/status and /api/bot/move.
• Add or update client tests for bot profile selection, server bot calls, and fallback behavior.
• Run the Space locally and verify /healthz, /api/bot/status, and a real bot move request.
• Smoke-test human vs bot and bot vs bot from /local-setup.

Defaults

• Keep this as a Gradio SDK Hugging Face Space; do not switch to Docker for this phase.
• Use the current best available ONNX artifact as the bundled default, even if the epoch is weak.
• Prefer a working Space-native hybrid bot first; exact parity with the sibling TypeScript arena can be tightened later.