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/.

Build, Test, and Development Commands

• python -m unittest discover -v runs the full test suite.
• 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.

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. 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 server and agent 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 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.