belote-cli 0.9.0__py3-none-any.whl

belote/ai.py

@@ -0,0 +1,412 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from enum import Enum
+
+from .deck import Card, Rank, Suit, trick_rank, card_points as card_points_fn
+from .game import (
+    GameState,
+    Seat,
+    Phase,
+    legal_cards,
+    team_of,
+    partner,
+)
+
+
+class Difficulty(Enum):
+    EASY = "easy"
+    MEDIUM = "medium"
+    HARD = "hard"
+
+
+class AIMemory:
+    """Tracks information about played cards and inferred voids."""
+
+    def __init__(self) -> None:
+        self.played: set[Card] = set()
+        self.known_voids: dict[Seat, set[Suit]] = {}
+        self.partner_hand: set[Card] = set()
+
+
+class AIPlayer:
+    def __init__(self, seat: Seat, difficulty: Difficulty = Difficulty.MEDIUM) -> None:
+        self.seat = seat
+        self.difficulty = difficulty
+        self.memory = AIMemory()
+        self._rng = random.Random()
+
+    def update_memory(self, state: GameState) -> None:
+        """Update memory with currently visible information."""
+        # Track all cards in completed tricks
+        for trick in state.completed_tricks:
+            for tc in trick:
+                self.memory.played.add(tc.card)
+        for tc in state.current_trick:
+            self.memory.played.add(tc.card)
+
+        # Partner's hand is visible (for NS team, South sees North's plays)
+        # In this implementation, AI tracks what it can see
+        p = partner(self.seat)
+        if state.phase in (Phase.PLAYING, Phase.SCORING):
+            # Partner's remaining cards
+            for card in state.hand_of(p):
+                self.memory.partner_hand.add(card)
+
+    def decide_bid(self, state: GameState) -> Suit | None:
+        """Decide whether to bid and which suit."""
+        hand = state.hand_of(self.seat)
+
+        if self.difficulty == Difficulty.EASY:
+            bid = self._easy_bid(hand)
+        elif self.difficulty == Difficulty.MEDIUM:
+            bid = self._medium_bid(hand, state)
+        else:
+            bid = self._hard_bid(hand, state)
+
+        # Respect bidding round rules
+        if state.bidding_round == 1:
+            # Round 1: only take the up-card's suit
+            if bid == state.up_card.suit: # type: ignore[union-attr]
+                return bid
+            return None
+        else:
+            # Round 2: pick any suit except the one from Round 1
+            if bid == state.up_card.suit: # type: ignore[union-attr]
+                return None
+            return bid
+
+    def decide_card(self, state: GameState) -> Card:
+        """Decide which card to play."""
+        hand = state.hand_of(self.seat)
+        legal = legal_cards(state, self.seat)
+
+        if not hand:
+            # Should never happen — game state is invalid if hand is empty mid-play.
+            raise ValueError(
+                f"AI {self.seat.name}: hand is empty during PLAYING phase — "
+                "likely a deal bug (check deck.deal gives 8 cards per player)."
+            )
+        if not legal:
+            # Defensive: legal_cards should never be empty mid-play.
+            # Fall back to full hand rather than constructing a phantom card.
+            # The old fallback Card(Suit.SPADES, Rank.ACE) caused crashes when
+            # that card wasn't in the player's hand.
+            legal = hand
+
+        if self.difficulty == Difficulty.EASY:
+            return self._easy_play(state, legal)
+        elif self.difficulty == Difficulty.MEDIUM:
+            return self._medium_play(state, legal)
+        else:
+            return self._hard_play(state, legal)
+
+    # ---- Easy AI ----
+
+    def _easy_bid(self, hand: tuple[Card, ...]) -> Suit | None:
+        """Bid if hand has >= 2 trump honors (J, 9, A) in any suit."""
+        honors = {Rank.JACK, Rank.NINE, Rank.ACE}
+        for suit in Suit:
+            count = sum(1 for c in hand if c.suit == suit and c.rank in honors)
+            if count >= 2:
+                return suit
+        return None
+
+    def _easy_play(self, state: GameState, legal: tuple[Card, ...]) -> Card:
+        """Uniform random over legal moves."""
+        return self._rng.choice(legal)
+
+    # ---- Medium AI ----
+
+    def _medium_bid(self, hand: tuple[Card, ...], state: GameState) -> Suit | None:
+        """Heuristic score per suit."""
+        suit_scores: dict[Suit, int] = {s: 0 for s in Suit}
+        honor_values = {
+            Rank.JACK: 4,
+            Rank.NINE: 3,
+            Rank.ACE: 2,
+            Rank.KING: 1,
+            Rank.QUEEN: 1,
+        }
+
+        for card in hand:
+            if card.rank in honor_values:
+                suit_scores[card.suit] += honor_values[card.rank]
+            # Count cards in suit
+            suit_scores[card.suit] += 0.1
+
+        # Void/singleton bonuses for potential discards
+        for suit in Suit:
+            count = sum(1 for c in hand if c.suit == suit)
+            if count == 0:
+                for other in Suit:
+                    if other != suit:
+                        suit_scores[other] += 0.5
+
+        best_suit = max(Suit, key=lambda s: suit_scores[s])
+        if suit_scores[best_suit] >= 4:
+            return best_suit
+        return None
+
+    def _medium_play(self, state: GameState, legal: tuple[Card, ...]) -> Card:
+        """Strategic play: lead high, cover partner, duck when winning."""
+        trump = state.trump
+        trick = state.current_trick
+
+        if not trick:
+            # Leading
+            return self._medium_lead(legal, trump)
+
+        lead_card = trick[0].card
+        lead_suit = lead_card.suit
+        p = partner(self.seat)
+
+        # Check if partner is winning
+        from .game import _current_trick_winner
+        current_winner = _current_trick_winner(
+            [tc for tc in trick if tc.seat != self.seat], trump, lead_suit
+        )
+        partner_winning = current_winner is not None and current_winner == p
+
+        if partner_winning and lead_suit != trump:
+            # Partner winning, discard low
+            return min(legal, key=lambda c: trick_rank(c, trump))
+
+        if lead_suit == trump:
+            # Trump led
+            my_trumps = [c for c in legal if c.suit == trump]
+            if my_trumps:
+                if current_winner is not None and current_winner == p:
+                    # Partner winning trump, play lowest trump
+                    return min(my_trumps, key=lambda c: trick_rank(c, trump))
+                else:
+                    # Try to win if we can afford it
+                    return max(my_trumps, key=lambda c: trick_rank(c, trump))
+            # No trumps, discard low non-trump
+            return min(legal, key=lambda c: card_points_fn(c, trump))
+
+        # Non-trump led
+        my_suit = [c for c in legal if c.suit == lead_suit]
+        if my_suit:
+            # Must follow
+            if current_winner is not None and current_winner == p:
+                return min(my_suit, key=lambda c: trick_rank(c, trump))
+            else:
+                return max(my_suit, key=lambda c: trick_rank(c, trump))
+
+        # Void - must trump or discard
+        my_trumps = [c for c in legal if c.suit == trump]
+        if my_trumps:
+            return max(my_trumps, key=lambda c: trick_rank(c, trump))
+
+        return min(legal, key=lambda c: card_points_fn(c, trump))
+
+    def _medium_lead(self, legal: tuple[Card, ...], trump: Suit | None) -> Card:
+        """Lead strategy: high non-trump A first, then trump pulls."""
+        if not trump:
+            return legal[0]
+
+        # Try to lead Ace of non-trump suit
+        for card in legal:
+            if card.rank == Rank.ACE and card.suit != trump:
+                return card
+
+        # Lead lowest trump to pull
+        trumps = [c for c in legal if c.suit == trump]
+        if trumps:
+            return min(trumps, key=lambda c: trick_rank(c, trump))
+
+        # Lead lowest non-trump
+        non_trumps = [c for c in legal if c.suit != trump]
+        if non_trumps:
+            return min(non_trumps, key=lambda c: trick_rank(c, trump))
+
+        return legal[0]
+
+    # ---- Hard AI ----
+
+    def _hard_bid(self, hand: tuple[Card, ...], state: GameState) -> Suit | None:
+        """Monte-Carlo-lite bidding evaluation."""
+        suit_scores: dict[Suit, float] = {s: 0.0 for s in Suit}
+
+        for suit in Suit:
+            # Count honors and cards in suit
+            trump_cards = [c for c in hand if c.suit == suit]
+            honor_count = sum(1 for c in trump_cards if c.rank in (Rank.JACK, Rank.NINE, Rank.ACE))
+            point_total = sum(card_points_fn(c, suit) for c in trump_cards)
+
+            # Base score from points
+            suit_scores[suit] = point_total * 0.5 + honor_count * 3
+
+            # Dealer position bonus
+            if state.dealer == self.seat or state.dealer == partner(self.seat):
+                suit_scores[suit] *= 1.1
+
+            # Void bonuses
+            for other in Suit:
+                if other != suit:
+                    other_count = sum(1 for c in hand if c.suit == other)
+                    if other_count == 0:
+                        suit_scores[suit] += 2
+                    elif other_count == 1:
+                        suit_scores[suit] += 1
+
+        best_suit = max(Suit, key=lambda s: suit_scores[s])
+        if suit_scores[best_suit] >= 6:
+            return best_suit
+        return None
+
+    def _hard_play(self, state: GameState, legal: tuple[Card, ...]) -> Card:
+        """1-ply lookahead with void inference."""
+        trump = state.trump
+        trick = state.current_trick
+
+        if not trump:
+            return legal[0]
+
+        # Update void inferences from completed tricks
+        self._update_voids(state)
+
+        if not trick:
+            return self._hard_lead(legal, trump, state)
+
+        lead_suit = trick[0].card.suit
+        p = partner(self.seat)
+
+        from .game import _current_trick_winner
+        current_winner = _current_trick_winner(
+            [tc for tc in trick if tc.seat != self.seat], trump, lead_suit
+        )
+        partner_winning = current_winner is not None and current_winner == p
+
+        # Score each legal card by expected outcome
+        best_card = legal[0]
+        best_score = -999
+
+        for card in legal:
+            score = self._score_card_play(card, state, trump, trick, partner_winning)
+            if score > best_score:
+                best_score = score
+                best_card = card
+
+        return best_card
+
+    def _score_card_play(
+        self,
+        card: Card,
+        state: GameState,
+        trump: Suit,
+        trick: tuple,
+        partner_winning: bool,
+    ) -> float:
+        """Score a card play decision."""
+        score = 0.0
+        points = card_points_fn(card, trump)
+        rank = trick_rank(card, trump)
+
+        # Base: card point value
+        score += points * 0.1
+
+        if not trick:
+            # Leading
+            if card.suit == trump:
+                # Leading trump is generally good for pulling
+                score += 2
+            elif card.rank == Rank.ACE:
+                score += 3
+            elif points == 0:
+                # Leading waste card
+                score += 1
+            return score
+
+        lead_suit = trick[0].card.suit
+
+        if partner_winning and lead_suit != trump:
+            # Partner winning - discard low value cards
+            score -= points * 0.5
+            if card.suit != trump:
+                score += 1
+            return score
+
+        # Try to win the trick
+        highest_rank = max(trick_rank(tc.card, trump) for tc in trick)
+        if rank > highest_rank:
+            score += 10  # Winning is valuable
+
+        # Trump considerations
+        if card.suit == trump:
+            if lead_suit != trump:
+                # Trumping a non-trump trick
+                trump_in_trick = [tc for tc in trick if tc.card.suit == trump]
+                if trump_in_trick:
+                    highest_trump = max(trick_rank(tc.card, trump) for tc in trump_in_trick)
+                    if rank > highest_trump:
+                        score += 5  # Overtrumping
+                    else:
+                        score -= 3  # Wasting a trump
+                else:
+                    score += 4  # First trump in trick
+            else:
+                # Trump led
+                if rank > highest_rank:
+                    score += 5
+                else:
+                    score -= 2
+
+        # Don't waste high-point cards unnecessarily
+        if points >= 10 and rank <= highest_rank:
+            score -= 5
+
+        # Strand opponent honors: if we know opponent is void in lead suit,
+        # playing a low card of lead suit forces them to trump or discard
+        opp = self.seat.next_seat()
+        if opp in self.memory.known_voids:
+            voids = self.memory.known_voids[opp]
+            if lead_suit in voids and card.suit == lead_suit:
+                score += 3
+
+        return score
+
+    def _hard_lead(
+        self, legal: tuple[Card, ...], trump: Suit, state: GameState
+    ) -> Card:
+        """Strategic lead with void awareness."""
+        # Prefer leading suit where opponent is known void
+        for card in legal:
+            if card.suit != trump:
+                opp = self.seat.next_seat()
+                if opp in self.memory.known_voids and card.suit in self.memory.known_voids[opp]:
+                    return card
+
+        # Lead Ace of non-trump
+        for card in legal:
+            if card.rank == Rank.ACE and card.suit != trump:
+                return card
+
+        # Lead low trump for pulling
+        trumps = [c for c in legal if c.suit == trump]
+        if trumps:
+            return min(trumps, key=lambda c: trick_rank(c, trump))
+
+        # Lead lowest non-trump
+        non_trumps = [c for c in legal if c.suit != trump]
+        if non_trumps:
+            return min(non_trumps, key=lambda c: trick_rank(c, trump))
+
+        return legal[0]
+
+    def _update_voids(self, state: GameState) -> None:
+        """Infer voids from played cards."""
+        for seat in Seat:
+            if seat not in self.memory.known_voids:
+                self.memory.known_voids[seat] = set()
+
+        for trick in state.completed_tricks:
+            if len(trick) < 2:
+                continue
+            lead_suit = trick[0].card.suit
+            for tc in trick[1:]:
+                if tc.card.suit != lead_suit:
+                    # This player didn't follow suit - likely void
+                    self.memory.known_voids[tc.seat].add(lead_suit)

belote/ansi.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import re
+
+_RESET_RE = re.compile(r"\x1b\[[0-9;?]*[A-Za-z]")
+
+RESET = "\x1b[0m"
+
+
+def visible_len(s: str) -> int:
+    """Return length of string with ANSI escape codes stripped."""
+    return len(_RESET_RE.sub("", s))
+
+
+def ansi_center(s: str, width: int) -> str:
+    """Center a string by visible width, ignoring ANSI escape codes."""
+    vlen = visible_len(s)
+    pad = max(0, width - vlen)
+    left = pad // 2
+    return " " * left + s
+
+
+def ansi_ljust(s: str, width: int) -> str:
+    """Left-justify a string to `width` visible characters, ANSI-aware.
+    Never use str.ljust() on ANSI strings — it counts escape bytes as chars.
+    """
+    vlen = visible_len(s)
+    pad = max(0, width - vlen)
+    return s + " " * pad
+
+
+def fg(r: int, g: int, b: int) -> str:
+    return f"\x1b[38;2;{r};{g};{b}m"
+
+
+def bg(r: int, g: int, b: int) -> str:
+    return f"\x1b[48;2;{r};{g};{b}m"
+
+
+BOLD = "\x1b[1m"
+DIM = "\x1b[2m"
+REVERSE = "\x1b[7m"
+UNDERLINE = "\x1b[4m"
+STRIKETHROUGH = "\x1b[9m"
+
+
+def move(row: int, col: int) -> str:
+    return f"\x1b[{row};{col}H"
+
+
+def clear_screen() -> str:
+    return "\x1b[2J" + move(1, 1)
+
+
+def clear_line() -> str:
+    return "\x1b[2K"
+
+
+def clear_to_eol() -> str:
+    return "\x1b[K"
+
+
+def hide_cursor() -> str:
+    return "\x1b[?25l"
+
+
+def show_cursor() -> str:
+    return "\x1b[?25h"
+
+
+def alt_screen_on() -> str:
+    return "\x1b[?1049h"
+
+
+def alt_screen_off() -> str:
+    return "\x1b[?1049l"
+
+
+def save_cursor() -> str:
+    return "\x1b7"
+
+
+def restore_cursor() -> str:
+    return "\x1b8"
+
+
+def scroll_region(top: int, bottom: int) -> str:
+    return f"\x1b[{top};{bottom}r"
+
+
+# Palette constants
+def felt_bg() -> str:
+    return bg(20, 90, 50)
+
+
+def red_fg() -> str:
+    return fg(220, 60, 60)
+
+
+def black_fg() -> str:
+    return fg(20, 20, 20)
+
+
+def card_face_bg() -> str:
+    return bg(245, 245, 235)
+
+
+def face_card_bg() -> str:
+    return bg(255, 245, 180)
+
+
+def card_back_bg() -> str:
+    return bg(120, 30, 30)
+
+
+def highlight_bg() -> str:
+    return bg(240, 200, 80)
+
+
+def gold_fg() -> str:
+    return fg(240, 200, 80)
+
+
+def white_fg() -> str:
+    return fg(240, 240, 240)
+
+
+def light_gray_fg() -> str:
+    return fg(180, 180, 180)
+
+
+def green_fg() -> str:
+    return fg(80, 220, 120)
+
+
+def banner_bg() -> str:
+    return bg(60, 60, 180)
+
+
+def banner_fg() -> str:
+    return fg(255, 255, 100)

belote/bidding.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from .deck import Card, Suit
+from .game import (
+    GameState,
+    Phase,
+    Seat,
+    get_bidder,
+    place_bid,
+    play_card,
+    legal_cards,
+    trick_winner_seat,
+)
+
+
+def bidding_turn(state: GameState) -> Seat:
+    """Return the seat whose turn it is to bid."""
+    return get_bidder(state.dealer, state.bidder_index)
+
+
+def process_bid(state: GameState, bid: Suit | None) -> GameState:
+    """Process a bid and return the new state."""
+    return place_bid(state, bid)
+
+
+def run_bidding_round(
+    state: GameState,
+    bid_decisions: dict[Seat, Suit | None],
+) -> GameState:
+    """Run through all bidding turns using pre-decided bids."""
+    current = state
+    while current.phase == Phase.BIDDING:
+        bidder = bidding_turn(current)
+        bid = bid_decisions.get(bidder)
+        if bid is None and bidder not in bid_decisions:
+            break
+        current = process_bid(current, bid_decisions.get(bidder))
+    return current
+
+
+def run_play_turn(state: GameState, card: Card) -> GameState:
+    """Play a single card and advance state."""
+    return play_card(state, card)
+
+
+def is_round_complete(state: GameState) -> bool:
+    """Check if the current round's play phase is complete."""
+    return len(state.completed_tricks) >= 8
+
+
+def is_game_over(state: GameState) -> bool:
+    """Check if the game has ended (someone reached target score)."""
+    ns, ew = state.team_scores
+    return ns >= state.target or ew >= state.target
+
+
+def winning_team(state: GameState) -> int | None:
+    """Return 0 (NS) or 1 (EW) if game is over, else None."""
+    ns, ew = state.team_scores
+    if ns >= state.target and ew >= state.target:
+        # Both crossed - taker wins if they succeeded, defenders if they failed
+        # Simplified: higher score wins
+        return 0 if ns >= ew else 1
+    if ns >= state.target:
+        return 0
+    if ew >= state.target:
+        return 1
+    return None