# Texas Hold X

一个标准库实现的多 AI Agent 德州扑克服务。核心代码不依赖第三方包，便于先验证规则和 Agent 协议，再接入 LLM、远程 Agent 或更完整的前端。

## 已实现能力

- 一盘游戏支持 2-12 个 Agent，开局筹码相同。
- 一盘游戏可以连续运行多局 Texas Hold'em。
- 服务按真实牌局顺序向当前行动 Agent 发送观察信息。
- 观察信息包含玩家筹码、公共牌、当前玩家手牌、底池、历史动作、可用动作和跟注/加注边界。
- 支持盲注、四条街下注、弃牌、过牌、跟注、下注、加注、全下、边池和摊牌结算。
- 支持本地 Agent 和 HTTP Agent。
- 支持 Human Agent 和 OpenAI-compatible AI Agent 的终端过程输出。
- 游戏运行中可以并发查询状态；查询返回上一手完成后的稳定快照。

## 运行服务

```bash
python -m texas_holdem.server --host 127.0.0.1 --port 8000
```

创建一盘 3 人游戏：

```bash
curl -X POST http://127.0.0.1:8000/games \
  -H 'Content-Type: application/json' \
  -d '{
    "game_id": "demo",
    "seed": 42,
    "starting_stack": 1000,
    "small_blind": 5,
    "big_blind": 10,
    "players": [
      {"id": "agent_1", "name": "Agent 1", "type": "calling"},
      {"id": "agent_2", "name": "Agent 2", "type": "random"},
      {"id": "agent_3", "name": "Agent 3", "type": "calling"}
    ]
  }'
```

运行 10 局：

```bash
curl -X POST http://127.0.0.1:8000/games/demo/hands/run \
  -H 'Content-Type: application/json' \
  -d '{"count": 10, "until_one_left": false}'
```

查看游戏状态：

```bash
curl http://127.0.0.1:8000/games/demo
```

也可以使用单数别名：

```bash
curl http://127.0.0.1:8000/game/demo
```

## HTTP Agent 协议

玩家配置可以使用远程 HTTP Agent：

```json
{
  "id": "llm_agent",
  "name": "LLM Agent",
  "agent": {
    "type": "http",
    "endpoint": "http://127.0.0.1:9101",
    "timeout_seconds": 10,
    "game_update_timeout_seconds": 3,
    "retries": 2,
    "retry_backoff_seconds": 0.25
  }
}
```

服务会向 `endpoint + /game` 推送每手开始时的游戏快照，向 `endpoint + /act` 发送当前行动玩家的观察 JSON。`endpoint` 也可以传入历史形式的 `/act` 或 `/game` 后缀，服务会归一化为 base URL。

同一个 HTTP Agent endpoint 不能同时被不同游戏占用；后创建的游戏会返回错误。服务会给 HTTP Agent 请求自动重试，`/act` 重试仍失败时，规则引擎会按 `check > call > fold` 选择默认动作，避免整桌卡死。

Agent 返回：

```json
{"action": "call"}
```

可用动作包括：

- `fold`
- `check`
- `call`
- `bet`
- `raise`
- `all_in`

`bet` 和 `raise` 的 `amount` 表示当前下注轮中该玩家希望达到的总下注额，也就是观察中 `amount_mode: "street_total"` 的含义。

## AI Agent

启动一个可接入 OpenAI-compatible Chat Completions API 的 AI Agent：

```bash
python -m texas_holdem.ai_client \
  --host 127.0.0.1 \
  --port 9101 \
  --base-url https://api.openai.com/v1 \
  --api-key "$OPENAI_API_KEY" \
  --model gpt-4o-mini \
  --keep-history
```

AI Agent 会在终端输出：

- 收到的 `/game` 游戏快照；
- 收到的 `/act` 行动请求；
- 大模型流式返回内容，默认灰色显示；
- 最终解析出的 action，或失败时的 fallback action。

默认每次 `/act` 会清屏，和 Human Agent 一致；加 `--keep-history` 后保留历史滚动输出。可用 `--no-stream` 关闭流式请求，用 `--no-color` 关闭灰色 ANSI 输出。

## 测试

```bash
python -m unittest discover -v
```

## Web 回放与控制台

启动核心游戏服务后，可以单独启动 Web 回放服务：

```bash
python -m texas_holdem_replay.server --host 127.0.0.1 --port 8088
```

打开 `http://127.0.0.1:8088`。页面通过自身的代理接口访问核心服务，
避免浏览器跨域限制；它不会导入或耦合 `texas_holdem.engine` 内部代码。

页面支持：

- 拉取 `GET /games/{game_id}` 快照并按 `hands[].actions` 生成逐帧回放。
- 通过代理调用核心服务运行指定数量手牌。
- 可选覆盖下一批手牌的大小盲。
- 上传或粘贴静态 JSON 快照进行离线回放。
- 自动轮询正在运行的游戏，保留当前历史查看位置。