33 lines
2.6 KiB
Markdown
33 lines
2.6 KiB
Markdown
# 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.
|