# Roadmap - Caro5 Hugging Face Space

## Phase 1 - Space Baseline
- [x] Serve the prebuilt React/Pixi client from the Gradio/FastAPI Space.
- [x] Route `/` to `/local-setup` so visitors can play without a separate websocket server.
- [x] Expose `/healthz` for deployment checks.

## Phase 2 - Hybrid Server Bot
- [x] Add a Python bot package inside this Space for server-side bot decisions.
- [x] Port the required main-project game logic: board coordinates, move validation, win/no-overline checks, candidate generation, and tactical scoring.
- [x] Port alpha-beta tactical search as the first decision layer.
- [x] Port model feature encoding compatible with the current ONNX policy/value metadata.
- [x] Add ONNX inference with env-configured model paths:
  - `CARO5_MODEL_ONNX`
  - `CARO5_MODEL_METADATA`
- [x] Add PUCT/MCTS as the strategic decision layer, using the ONNX model when available and heuristic priors otherwise.
- [x] 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
- [x] Add two server profiles:
  - `balanced`: responsive search budget for normal play
  - `expert`: deeper alpha-beta and higher MCTS budget

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

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

## Phase 5 - Verification
- [x] Add Python tests for move validation, win/block detection, feature tensor shape, ONNX load failure, and legal bot responses.
- [x] Add focused Python tests for tactical move validation, win/block detection, and legal bot responses.
- [x] Add API tests for `/api/bot/status` and `/api/bot/move`.
- [x] Add or update client tests for bot profile selection, server bot calls, and fallback behavior.
- [x] Run the Space locally and verify `/healthz`, `/api/bot/status`, and a real bot move request.
- [x] 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.