poker-cli 0.11.2__py3-none-any.whl

poker_cli/controllers.py

@@ -0,0 +1,539 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+import json
+import os
+import random
+import re
+import shutil
+import signal
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+from typing import Callable
+import urllib.error
+import urllib.request
+
+from .cards import Card
+from .models import Action, ActionKind, Observation, Street
+from .strategy import estimate_equity
+from .usage import ModelUsageTracker, parse_claude_result, parse_codex_usage
+
+
+class Controller(ABC):
+    @abstractmethod
+    def act(self, observation: Observation) -> Action:
+        raise NotImplementedError
+
+
+class HumanController(Controller):
+    def act(self, observation: Observation) -> Action:
+        legal = observation.legal_actions
+        while True:
+            pieces = []
+            if legal.can_check:
+                pieces.append("check")
+            if legal.call_amount:
+                pieces.append(f"call {legal.call_amount}")
+            if legal.can_fold:
+                pieces.append("fold")
+            if legal.min_raise_to is not None:
+                pieces.append(f"raise {legal.min_raise_to}-{legal.max_raise_to}")
+            raw = input(f"你的行动 [{', '.join(pieces)}] > ").strip().lower()
+            action = parse_action(raw)
+            if action is not None and is_legal(action, observation):
+                return action
+            print("无效行动，请按提示输入，例如 check、call、fold 或 raise 80。")
+
+
+@dataclass(frozen=True)
+class BotProfile:
+    key: str
+    name: str
+    description: str
+    value_raise: float
+    bluff_rate: float
+    trap_rate: float
+    fold_bias: float
+    bet_sizes: tuple[float, ...]
+
+
+BOT_PROFILES = {
+    "balanced": BotProfile(
+        "balanced",
+        "均衡型",
+        "价值下注、半诈唬和控池都有，行动相对稳定",
+        0.64,
+        0.07,
+        0.12,
+        0.00,
+        (0.50, 0.66, 0.75, 1.00),
+    ),
+    "tight": BotProfile(
+        "tight",
+        "紧手型",
+        "入池谨慎，强牌持续施压，很少做纯诈唬",
+        0.70,
+        0.02,
+        0.16,
+        0.05,
+        (0.33, 0.50, 0.66),
+    ),
+    "aggressive": BotProfile(
+        "aggressive",
+        "松凶型",
+        "宽范围入池，频繁施压，包含较多诈唬和超池下注",
+        0.57,
+        0.17,
+        0.05,
+        -0.04,
+        (0.50, 0.75, 1.00, 1.25, 1.50),
+    ),
+    "tricky": BotProfile(
+        "tricky",
+        "诡诈型",
+        "强牌慢打、弱牌突袭，行动频率更难预测",
+        0.62,
+        0.13,
+        0.30,
+        -0.01,
+        (0.33, 0.50, 0.75, 1.25),
+    ),
+}
+
+
+class OfflineBot(Controller):
+    def __init__(
+        self,
+        profile: str = "balanced",
+        rng: random.Random | None = None,
+        samples: int = 450,
+    ) -> None:
+        if profile not in BOT_PROFILES:
+            raise ValueError(f"unknown offline profile: {profile}")
+        self.profile = BOT_PROFILES[profile]
+        self.rng = rng or random.Random()
+        self.samples = samples
+
+    def act(self, observation: Observation) -> Action:
+        hole = [Card.parse(code) for code in observation.hole_cards]
+        board = [Card.parse(code) for code in observation.community_cards]
+        equity = estimate_equity(
+            hole,
+            board,
+            opponents=observation.active_opponents,
+            samples=self.samples,
+            rng=self.rng,
+        )
+        legal = observation.legal_actions
+        to_call = legal.call_amount
+        pot_odds = to_call / (observation.pot + to_call) if to_call else 0
+        noise = self.rng.uniform(-0.045, 0.045)
+        perceived_equity = max(0.0, min(1.0, equity + noise))
+        can_raise = legal.min_raise_to is not None
+        bluff = can_raise and self.rng.random() < self.profile.bluff_rate
+        strong = perceived_equity >= self.profile.value_raise
+
+        if to_call:
+            fold_threshold = max(0.16, pot_odds + self.profile.fold_bias)
+            if perceived_equity < fold_threshold and not bluff:
+                return Action(ActionKind.FOLD)
+            if can_raise and (strong or bluff):
+                if strong and self.rng.random() < self.profile.trap_rate:
+                    return Action(ActionKind.CALL)
+                return Action(ActionKind.RAISE, self._raise_target(observation))
+            return Action(ActionKind.CALL)
+
+        if can_raise:
+            medium_probe = 0.46 <= perceived_equity < self.profile.value_raise
+            probe_rate = 0.16 + self.profile.bluff_rate
+            if strong and self.rng.random() >= self.profile.trap_rate:
+                return Action(ActionKind.RAISE, self._raise_target(observation))
+            if bluff or (medium_probe and self.rng.random() < probe_rate):
+                return Action(ActionKind.RAISE, self._raise_target(observation))
+        return Action(ActionKind.CHECK)
+
+    def _raise_target(self, observation: Observation) -> int:
+        legal = observation.legal_actions
+        assert legal.min_raise_to is not None and legal.max_raise_to is not None
+        size = self.rng.choice(self.profile.bet_sizes)
+        to_call = legal.call_amount
+        if observation.street.value == "preflop":
+            extra = round(observation.big_blind * max(2.0, size * 3.0))
+        else:
+            extra = round(max(observation.big_blind, observation.pot * size))
+        target = observation.own_street_bet + to_call + extra
+        return min(legal.max_raise_to, max(legal.min_raise_to, target))
+
+
+class StrategyBot(OfflineBot):
+    """Backwards-compatible name for the balanced offline bot."""
+
+    def __init__(self, rng: random.Random | None = None, samples: int = 450) -> None:
+        super().__init__("balanced", rng=rng, samples=samples)
+
+
+ThinkingSink = Callable[[str, str | None], None]
+NoticeSink = Callable[[str], None]
+FastForwardCheck = Callable[[], bool]
+OnlineDecisionCheck = Callable[[Observation], bool]
+
+POKER_ACTION_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "action": {
+            "type": "string",
+            "enum": ["fold", "check", "call", "raise"],
+        },
+        "amount": {"type": "integer"},
+    },
+    "required": ["action", "amount"],
+    "additionalProperties": False,
+}
+
+
+class FastForwardRequested(RuntimeError):
+    pass
+
+
+class OnlineDecisionBudget:
+    """Share a small model-call budget across every online seat in one hand."""
+
+    def __init__(self, max_calls_per_hand: int = 3) -> None:
+        self.max_calls_per_hand = max_calls_per_hand
+        self.hand_id = 0
+        self.calls = 0
+
+    def claim(self, observation: Observation) -> bool:
+        if observation.hand_id != self.hand_id:
+            self.hand_id = observation.hand_id
+            self.calls = 0
+        if self.calls >= self.max_calls_per_hand:
+            return False
+        big_blind = max(1, observation.big_blind)
+        meaningful_call = observation.legal_actions.call_amount >= big_blind * 2
+        developed_pot = observation.pot >= big_blind * 6
+        late_decision = (
+            observation.street in {Street.TURN, Street.RIVER}
+            and observation.pot >= big_blind * 3
+        )
+        if not (meaningful_call or developed_pot or late_decision):
+            return False
+        self.calls += 1
+        return True
+
+
+class LocalAgentCLIController(Controller):
+    """Poker opponent backed by an authenticated local Codex or Claude CLI.
+
+    Only the immutable Observation payload is serialized for the agent. The
+    engine, deck, and other players' hole cards never enter the prompt.
+    """
+
+    def __init__(
+        self,
+        provider: str,
+        actor_name: str,
+        *,
+        thinking_sink: ThinkingSink | None = None,
+        notice_sink: NoticeSink | None = None,
+        timeout: int = 120,
+        fallback: Controller | None = None,
+        persona: str = "",
+        fast_forward: FastForwardCheck | None = None,
+        online_decision: OnlineDecisionCheck | None = None,
+        model: str | None = None,
+        usage_tracker: ModelUsageTracker | None = None,
+    ) -> None:
+        if provider not in {"codex", "claude"}:
+            raise ValueError(f"unknown local agent provider: {provider}")
+        if shutil.which(provider) is None:
+            raise ValueError(f"找不到本地 {provider} 命令")
+        self.provider = provider
+        self.actor_name = actor_name
+        self.thinking_sink = thinking_sink
+        self.notice_sink = notice_sink
+        self.timeout = timeout
+        self.fallback = fallback or OfflineBot("balanced", samples=40)
+        self.persona = persona
+        self.fast_forward = fast_forward
+        self.online_decision = online_decision
+        self.model = model
+        self.usage_tracker = usage_tracker
+
+    def act(self, observation: Observation) -> Action:
+        if self.fast_forward is not None and self.fast_forward():
+            return self.fallback.act(observation)
+        if self.online_decision is not None and not self.online_decision(observation):
+            return self.fallback.act(observation)
+        if self.thinking_sink is not None:
+            self.thinking_sink(self.actor_name, self.provider)
+        try:
+            prompt = build_local_agent_prompt(observation, self.persona)
+            content = self._run_codex(prompt) if self.provider == "codex" else self._run_claude(prompt)
+            action = parse_llm_action(content)
+            if action is None or not is_legal(action, observation):
+                raise ValueError("返回了非法或无法解析的行动")
+            return action
+        except FastForwardRequested:
+            return self.fallback.act(observation)
+        except (OSError, subprocess.SubprocessError, ValueError) as error:
+            if self.notice_sink is not None:
+                self.notice_sink(
+                    f"{self.actor_name} 的 {self.provider} 不可用，已使用离线决策：{error}"
+                )
+            return self.fallback.act(observation)
+        finally:
+            if self.thinking_sink is not None:
+                self.thinking_sink(self.actor_name, None)
+
+    def _run_codex(self, prompt: str) -> str:
+        with tempfile.TemporaryDirectory(prefix="poker-opponent-") as temp_dir:
+            output_path = Path(temp_dir) / "action.txt"
+            schema_path = Path(temp_dir) / "action-schema.json"
+            schema_path.write_text(
+                json.dumps(POKER_ACTION_SCHEMA, separators=(",", ":")),
+                encoding="utf-8",
+            )
+            command = [
+                "codex",
+                "exec",
+                "--ephemeral",
+                "--ignore-user-config",
+                "--ignore-rules",
+                "--disable",
+                "plugins",
+                "--disable",
+                "remote_plugin",
+                "--disable",
+                "apps",
+                "--sandbox",
+                "read-only",
+                "--skip-git-repo-check",
+                "--color",
+                "never",
+                "--json",
+                "--output-last-message",
+                str(output_path),
+                "--output-schema",
+                str(schema_path),
+            ]
+            if self.model:
+                command.extend(("-m", self.model))
+            command.extend(("-c", 'model_reasoning_effort="low"', "-"))
+            completed = self._run(command, prompt, cwd=temp_dir)
+            usage = parse_codex_usage(completed.stdout)
+            if usage is not None and self.usage_tracker is not None:
+                self.usage_tracker.record("codex", usage)
+            if not output_path.exists():
+                raise ValueError("Codex 没有生成行动")
+            return output_path.read_text(encoding="utf-8").strip()
+
+    def _run_claude(self, prompt: str) -> str:
+        command = [
+            "claude",
+            "-p",
+            "--safe-mode",
+            "--tools",
+            "",
+            "--permission-mode",
+            "dontAsk",
+            "--no-session-persistence",
+            "--model",
+            self.model or "haiku",
+            "--effort",
+            "low",
+            "--system-prompt",
+            "Choose quickly. Never use tools.",
+            "--json-schema",
+            json.dumps(POKER_ACTION_SCHEMA, separators=(",", ":")),
+            "--output-format",
+            "json",
+        ]
+        content, usage = parse_claude_result(self._run(command, prompt).stdout)
+        if usage is not None and self.usage_tracker is not None:
+            self.usage_tracker.record("claude", usage)
+        return content
+
+    def _run(
+        self,
+        command: list[str],
+        prompt: str,
+        *,
+        cwd: str | None = None,
+    ) -> subprocess.CompletedProcess[str]:
+        with tempfile.TemporaryFile(mode="w+", encoding="utf-8") as stdout_file, (
+            tempfile.TemporaryFile(mode="w+", encoding="utf-8")
+        ) as stderr_file:
+            try:
+                process = subprocess.Popen(
+                    command,
+                    stdin=subprocess.PIPE,
+                    stdout=stdout_file,
+                    stderr=stderr_file,
+                    text=True,
+                    cwd=cwd,
+                    start_new_session=True,
+                )
+            except OSError:
+                raise
+            assert process.stdin is not None
+            process.stdin.write(prompt)
+            process.stdin.close()
+            process.stdin = None
+            deadline = time.monotonic() + self.timeout
+            while process.poll() is None:
+                if self.fast_forward is not None and self.fast_forward():
+                    self._terminate_process_group(process)
+                    raise FastForwardRequested
+                if time.monotonic() >= deadline:
+                    self._terminate_process_group(process)
+                    raise ValueError(f"{self.provider} 思考超时")
+                time.sleep(0.05)
+            stdout_file.seek(0)
+            stderr_file.seek(0)
+            completed = subprocess.CompletedProcess(
+                command,
+                process.returncode,
+                stdout_file.read(),
+                stderr_file.read(),
+            )
+        if completed.returncode != 0:
+            details = completed.stderr.strip().splitlines()
+            suffix = f"：{details[-1]}" if details else ""
+            raise ValueError(f"{self.provider} 调用失败{suffix}")
+        return completed
+
+    @staticmethod
+    def _terminate_process_group(process: subprocess.Popen[str]) -> None:
+        try:
+            os.killpg(process.pid, signal.SIGTERM)
+            process.wait(timeout=0.5)
+        except (ProcessLookupError, subprocess.TimeoutExpired):
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+            process.wait()
+
+
+def build_local_agent_prompt(observation: Observation, persona: str = "") -> str:
+    packet = observation.to_dict()
+    return (
+        "Pick one legal no-limit Hold'em action with a simple human heuristic. "
+        "Use at most 3 brief internal checks. Use only your cards and public state. "
+        f"Tendency: {persona or 'balanced'}. "
+        "For raise, amount is the total street bet inside the legal range; otherwise 0. "
+        f"STATE={json.dumps(packet, ensure_ascii=False, separators=(',', ':'))}"
+    )
+
+
+class LLMController(Controller):
+    """OpenAI-compatible chat-completions adapter.
+
+    The adapter only accepts an Observation, which intentionally contains no
+    opponent hole cards or undealt deck state.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        model: str | None = None,
+        timeout: float = 20,
+        fallback: Controller | None = None,
+    ) -> None:
+        self.base_url = (base_url or os.getenv("POKER_LLM_BASE_URL", "")).rstrip("/")
+        self.api_key = api_key or os.getenv("POKER_LLM_API_KEY", "")
+        self.model = model or os.getenv("POKER_LLM_MODEL", "")
+        self.timeout = timeout
+        self.fallback = fallback or StrategyBot()
+        if not self.base_url or not self.model:
+            raise ValueError("LLM opponent requires POKER_LLM_BASE_URL and POKER_LLM_MODEL")
+
+    def act(self, observation: Observation) -> Action:
+        payload = {
+            "model": self.model,
+            "temperature": 0.35,
+            "messages": [
+                {
+                    "role": "system",
+                    "content": (
+                        "你是一个无限注德州扑克牌手。你只能使用用户提供的公开信息和自己的手牌。"
+                        "只输出 JSON：{\"action\":\"fold|check|call|raise\",\"amount\":整数}。"
+                        "raise 的 amount 表示本轮下注总额，必须落在合法范围。"
+                    ),
+                },
+                {
+                    "role": "user",
+                    "content": json.dumps(observation.to_dict(), ensure_ascii=False),
+                },
+            ],
+        }
+        request = urllib.request.Request(
+            f"{self.base_url}/chat/completions",
+            data=json.dumps(payload).encode(),
+            headers={
+                "Content-Type": "application/json",
+                **({"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}),
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                body = json.loads(response.read())
+            content = body["choices"][0]["message"]["content"]
+            action = parse_llm_action(content)
+            if action is None or not is_legal(action, observation):
+                return self.fallback.act(observation)
+            return action
+        except (urllib.error.URLError, TimeoutError, KeyError, ValueError, json.JSONDecodeError):
+            return self.fallback.act(observation)
+
+
+def parse_action(raw: str) -> Action | None:
+    parts = raw.split()
+    aliases = {"f": "fold", "x": "check", "c": "call", "r": "raise"}
+    if not parts:
+        return None
+    kind_text = aliases.get(parts[0], parts[0])
+    try:
+        kind = ActionKind(kind_text)
+    except ValueError:
+        return None
+    if kind == ActionKind.RAISE:
+        if len(parts) != 2 or not parts[1].isdigit():
+            return None
+        return Action(kind, int(parts[1]))
+    return Action(kind)
+
+
+def parse_llm_action(content: str) -> Action | None:
+    match = re.search(r"\{.*?\}", content, re.DOTALL)
+    if not match:
+        return None
+    try:
+        value = json.loads(match.group(0))
+        kind = ActionKind(str(value["action"]).lower())
+        amount = int(value.get("amount", 0))
+        return Action(kind, amount)
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+        return None
+
+
+def is_legal(action: Action, observation: Observation) -> bool:
+    legal = observation.legal_actions
+    if action.kind == ActionKind.FOLD:
+        return legal.can_fold
+    if action.kind == ActionKind.CHECK:
+        return legal.can_check
+    if action.kind == ActionKind.CALL:
+        return legal.call_amount > 0
+    if action.kind == ActionKind.RAISE:
+        if legal.min_raise_to is None or legal.max_raise_to is None:
+            return False
+        return legal.min_raise_to <= action.amount <= legal.max_raise_to
+    return False