Wizard/wizard_ai/README.md

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) 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. Work is bounded: AI_WORKERS (1) parallel decisions, at most AI_MAX_QUEUE (64) requests in progress (more are answered "overloaded"), expired requests are dropped, and from AI_DEGRADE_QUEUE (8) waiting requests — or when the model is too slow — the heuristic decides instead of the model (see ../docs/09-limits-and-performance.md)

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, AI_WORKERS, AI_MAX_QUEUE, AI_DEGRADE_QUEUE
pytest