first prototype

wizard_ai/README.md

@@ -0,0 +1,27 @@
+# wizard_ai
+
+AI player for the Wizard server. The actual RL model is still to be implemented; this package
+provides everything around it.
+
+- `agents/` — `Agent` interface (`act(observation) -> action`) plus `RandomAgent`,
+  `HeuristicAgent` (baseline / fallback) and `ModelAgent` (wraps a `Policy`)
+- `model/encoding.py` — observation → fixed-size feature vector (`FEATURE_SIZE`), and the fixed
+  action space (21 bids + 60 cards + 4 trump suits) with legal-action masks; works for 3–6 players
+- `model/policy.py` — **the place to plug in the model**: subclass `Policy`, implement
+  `select`, `update`, `save_weights`/`load`, register with `@register_policy`.
+  `UniformPolicy` is a placeholder so the pipeline runs end to end.
+- `training/env.py` — turn-based multi-agent environment around `wizard_game`
+  (reward = score change per round / 100)
+- `training/self_play.py` — self-play loop collecting per-player trajectories and calling
+  `Policy.update`, with checkpointing
+- `training/evaluate.py` — play agents against each other (mean score, win rate)
+- `service/client.py` — production: connects to `ws://wizard_server:8083/internal/ai`,
+  answers `decide` requests, reconnects automatically
+
+```bash
+pip install -r requirements-dev.txt
+python -m wizard_ai train --episodes 5000 --out models/latest
+python -m wizard_ai evaluate --agents model,heuristic,random,random --games 200
+python -m wizard_ai serve   # env: SERVER_URL, AI_SHARED_SECRET, AGENT, MODEL_PATH
+pytest
+```