texas_hold_x/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

Core poker service code lives in texas_holdem/. Important modules include engine.py for Texas Hold'em rules, service.py for game management, server.py for the HTTP API, agents.py for local/HTTP agents, and ai_client.py / human_client.py for standalone agents. Prompt templates live in texas_holdem/prompts/.

Replay UI code lives in texas_holdem_replay/, with static browser assets under texas_holdem_replay/static/. Tests are in tests/, named by feature area such as test_engine.py, test_service.py, and test_replay_server.py. Design notes belong in docs/.

Build, Test, and Development Commands

• python -m unittest discover -v runs the full test suite.
• python -m compileall texas_holdem texas_holdem_replay tests checks import and syntax validity.
• python -m texas_holdem.server --host 127.0.0.1 --port 8000 starts the game service.
• python -m texas_holdem.human_client --port 9001 --keep-history starts an interactive human HTTP agent.
• python -m texas_holdem.ai_client --port 9101 --api-key "$OPENAI_API_KEY" --model gpt-4o-mini starts an OpenAI-compatible AI agent.
• python -m texas_holdem_replay.server --port 8088 starts the replay viewer.

Coding Style & Naming Conventions

Use Python 3.11+ standard-library APIs unless a dependency is intentionally added to pyproject.toml. Keep modules focused and prefer explicit dataclasses for wire/state models. Use 4-space indentation, type hints, snake_case for functions and variables, PascalCase for classes, and concise comments only where logic is non-obvious.

Testing Guidelines

Use unittest. Add tests near the behavior changed: engine rules in tests/test_engine.py, HTTP/service behavior in tests/test_service.py, agent transport in tests/test_agents.py, and replay UI server helpers in tests/test_replay_server.py. New bug fixes should include a regression test. Avoid tests that require external network access or real LLM calls.

Commit & Pull Request Guidelines

History uses short Conventional Commit-style subjects, for example feat: add replay server and web client and fix: game service api block when a game is running. Keep commits scoped to one behavior change. Pull requests should include a short summary, test commands run, linked issue or motivation, and screenshots only for replay UI or visible terminal-output changes.

Security & Configuration Tips

Do not commit API keys. Pass LLM credentials through OPENAI_API_KEY or CLI flags in local shells only. HTTP Agent endpoints are exclusive per active game; preserve this invariant when changing service concurrency.