AI Deep Dive:
How the Computer Thinks

var own_hand: Array = []        # the Alley's OWN cards (its 6 to discard, or its play hand)
var played: Array = []          # the public pegging pile, in order
var running_count: int = 0      # public running count in the current pegging sub-round
var opp_card_count: int = 0     # how many cards the opponent HOLDS (a COUNT, never the cards)
var starter = null              # the cut/starter card -- public once cut (null before)
var crib_is_alley: bool = false
var dealer: String = ""
var scores: Dictionary = {}     # public {"player": int, "alley": int}

static func for_discard(own_six: Array, crib_is_alley_in: bool, ...) -> AlleyObservation:
    var o := AlleyObservation.new()
    o.own_hand = own_six
    o.crib_is_alley = crib_is_alley_in
    # ...dealer, scores -- but NEVER the opponent's cards
    return o

static func for_play(own_hand_in: Array, played_in: Array,
        running_count_in: int, opp_card_count_in: int, starter_in = null, ...) -> AlleyObservation:
    var o := AlleyObservation.new()
    o.own_hand = own_hand_in
    o.played = played_in
    o.running_count = running_count_in
    o.opp_card_count = opp_card_count_in   # a COUNT (int), not the actual cards
    o.starter = starter_in
    return o

func choose_discard(obs: AlleyObservation, skill: float, decision_seed: int) -> Array:
    _o = obs
    var hand: Array = obs.own_hand
    if hand.size() <= 2:
        return hand.duplicate()
    var ranked := _eval_discards(hand, obs.crib_is_alley)   # rank all 15 possible throws
    if ranked.is_empty():
        return hand.slice(0, 2)
    var t := _temperature(skill)         # 0 = expert (exact argmax), >0 = weighted random
    if t <= 0.0:
        return (ranked[0]["thrown"] as Array).duplicate()   # expert: always the best EV throw
    var roll := RandomNumberGenerator.new()
    roll.seed = decision_seed
    # build a probability distribution over ALL ranked options, weighted by EV
    var vals: Array = []
    for r in ranked:
        vals.append(float(r["score"]))
    var pick := _softmax_pick(vals, t, roll)
    return (ranked[pick]["thrown"] as Array).duplicate()

func _eval_discards(hand: Array, my_crib: bool, ranked_order := false) -> Array:
    var results: Array = []
    var cuts := _unseen_cuts(hand)         # the 46 cards not in the AI's hand
    var inv := 1.0 / float(maxi(1, cuts.size()))
    for i in range(n):
        for j in range(i + 1, n):
            var thrown: Array = [hand[i], hand[j]]
            var kept: Array = []          # the 4 cards the AI would keep
            for k in range(n):
                if k != i and k != j:
                    kept.append(hand[k])
            var avg_hand := _avg_hand(kept, cuts) * inv          # E[hand points | cut]
            var own_only := _avg_own_crib(thrown, cuts) * inv    # E[these 2 cards in crib | cut]
            var avg_crib := StatsScript.crib_value(thrown[0].rank, thrown[1].rank, my_crib)
            var expected := avg_hand + avg_crib
            var net := avg_hand - avg_crib        # dealer wants to maximise; pone wants to minimise crib
            var safety := avg_hand + (own_only if my_crib else -own_only)
            results.append({
                "thrown": thrown, "avg_hand": avg_hand, "avg_crib": avg_crib,
                "expected": expected, "net": net, "safety": safety,
                "score": expected if my_crib else net,
            })

func _unseen_cuts(hand: Array) -> Array:
    var seen := {}
    for c in hand:
        seen[c.rank * 4 + c.suit] = true
    var cuts: Array = []
    for su in range(4):
        for rk in range(1, 14):
            if not seen.has(rk * 4 + su):
                cuts.append(Card.new(rk, su))
    return cuts

func _cmp_disc(a: Dictionary, b: Dictionary) -> bool:
    if absf(float(a["score"]) - float(b["score"])) > 0.001:
        return float(a["score"]) > float(b["score"])
    return float(a["safety"]) > float(b["safety"])  # within 0.001 EV: prefer safer throw

static func temperature_for_skill(skill: float) -> float:
    var s := clampf(skill, 0.0, 1.0)
    var anchors := [
        [0.0, 6.0],     # skill 0.0  -> T 6.0  (essentially random)
        [0.12, 4.5],   # skill 0.12 -> T 4.5  (Easy)
        [0.35, 1.6],   # skill 0.35 -> T 1.6  (Normal)
        [0.85, 0.65],  # skill 0.85 -> T 0.65 (Hard)
        [1.0, 0.0]     # skill 1.0  -> T 0    (Expert: exact argmax)
    ]
    for i in range(1, anchors.size()):
        if s <= float(anchors[i][0]):
            var a: Array = anchors[i - 1]
            var b: Array = anchors[i]
            var f := (s - float(a[0])) / maxf(0.000001, float(b[0]) - float(a[0]))
            return lerpf(float(a[1]), float(b[1]), f)
    return 0.0

static func _softmax_pick(vals: Array, t: float, roll: RandomNumberGenerator) -> int:
    var best := -1.0e20
    for v in vals:
        best = maxf(best, float(v))
    var weights: Array = []
    var total := 0.0
    for v in vals:
        var w := exp(-(best - float(v)) / t)    # best option always gets weight 1.0
        weights.append(w)                          # worse options get fractional weight
        total += w
    var x := roll.randf() * total              # uniform draw scaled to total weight
    for i in range(weights.size()):
        x -= float(weights[i])
        if x <= 0.0:
            return i                           # this is the chosen option
    return 0

func choose_play(obs: AlleyObservation, profile: StrategyProfile, rng, sample_seed := 0):
    _o = obs
    var legal: Array = _legal_plays(obs.own_hand, obs.running_count)
    if legal.is_empty():
        return null
    var t := profile.temperature
    if profile.peg_depth >= 2:                      # Hard & Expert: 2-ply expectimax
        var vals2 := _play_line_values(legal, profile, sample_seed)
        if not vals2.is_empty():
            if t <= 0.0:
                return legal[_argmax(vals2)]     # Expert: best full line, exactly
            return legal[_softmax_pick(vals2, t, rng)]   # Hard: softmax over line values
    if t <= 0.0:
        return _best_play(...)                      # exact argmax over 1-ply values
    var vals: Array = []
    for card in legal:
        vals.append(_net_value(card, profile))      # tier knowledge gates apply inside
    return legal[_softmax_pick(vals, t, rng)]

func _net_value(card, profile: StrategyProfile) -> float:
    var new_count: int = _o.running_count + card_value
    var score: float = 0.0
    if new_count == 15: score += 2.0               # fifteen-for-two
    if new_count == 31: score += 2.0               # thirty-one
    score += pairs_and_runs(pile + card)           # pairs, pairs royal, runs

    # Minus the card-counted reply threat. Board position (Rule of 26), the 121-endgame,
    # fourth street, and whose-count-comes-first each re-weight it -- IF this tier has
    # learned that lesson (profile.knows_* gates).
    if profile.threat_weight > 0.0 and new_count < 31:
        score -= threat_w * _opponent_threat(new_count, ...)

    # Classic heuristics (all tiers):
    if new_count == 5 or new_count == 21: score -= 1.0   # leaves easy 15 or 31
    if _o.running_count == 0 and card.rank == 5: score -= 1.2  # don't lead a 5

    # Plus the Academy-lesson terms this tier knows: safe fifteen-proof leads,
    # holding a magic eleven, saving closers for after the Go, taking a peg-out
    # that wins on the spot. (Exact weights: our secret sauce.)
    return score

func _unseen_rank_counts() -> Dictionary:
    if _rc_for == _o and _o != null:
        return _rc_cached      # memoized per observation -- computed once per decision
    var counts: Dictionary = {}
    for r in range(1, 14):
        counts[r] = 4         # start: 4 of every rank
    for c in _o.own_hand:
        counts[c.rank] = int(counts[c.rank]) - 1    # subtract own cards
    for c in _o.played:
        counts[c.rank] = int(counts[c.rank]) - 1    # subtract public pile
    if _o.starter != null:
        counts[_o.starter.rank] = maxi(0, int(counts[_o.starter.rank]) - 1)  # subtract starter
    _rc_for = _o
    _rc_cached = counts
    return counts

func _opponent_threat(new_count: int, played_rank: int, expected := false) -> float:
    var rank_remaining := _unseen_rank_counts()
    var opp_cards: int = _o.opp_card_count
    if opp_cards <= 0 or unseen_total <= 0:
        return 0.0
    var threat: float = 0.0
    for r in range(1, 14):
        var copies: int = rank_remaining[r]
        if copies <= 0: continue
        var pts: int = reply_points(r, new_count)   # points if opp plays this rank
        if pts <= 0: continue
        var weighted: float = float(pts) * _prob_opponent_holds(copies, unseen_total, opp_cards)
        if expected:
            threat += weighted       # Hard & Expert: read the WHOLE table
        elif weighted > threat:
            threat = weighted        # Easy & Normal: fear the single worst reply
    return threat

func _prob_opponent_holds(copies: int, pool: int, hand_size: int) -> float:
    if copies <= 0 or hand_size <= 0: return 0.0
    if copies >= pool: return 1.0
    var p_none: float = 1.0
    for k in range(hand_size):
        p_none *= float(pool - copies - k) / float(pool - k)
        if p_none <= 0.0: return 1.0
    return 1.0 - p_none   # P(holds at least one copy) = 1 - P(holds zero copies)

static func _find_fifteens(cards: Array) -> Array:
    var events: Array = []
    var n: int = cards.size()
    for mask in range(1, 1 << n):   # enumerate all 2^n - 1 non-empty subsets
        var sum: int = 0
        var combo: Array = []
        for i in range(n):
            if mask & (1 << i):         # bit i set = card i is in this subset
                sum += cards[i].get_cribbage_value()
                combo.append(cards[i])
        if sum == 15 and combo.size() >= 2:
            events.append({"type": "fifteen", "points": 2, ...})
    return events

# Runs: consecutive-rank streaks; each streak of length L>=3 scores
# L * (product of counts) -- identical to enumerating the cartesian combos.
var streak_len: int = 0
var streak_mult: int = 1
for r in range(1, 15):
    if r <= 13 and rc[r] > 0:
        streak_len += 1
        streak_mult *= rc[r]    # multiply by copies of this rank
    else:
        if streak_len >= 3:
            pts += streak_len * streak_mult    # double runs, triple runs etc. arise naturally
        streak_len = 0
        streak_mult = 1

static func is_perfect_29(hand: Array, starter) -> bool:
    if starter.rank != 5: return false
    var has_jack := false
    var five_count := 0
    var jack_suit := -1
    for c in hand:
        if c.rank == 11:    # Jack
            has_jack = true
            jack_suit = c.suit
        elif c.rank == 5:
            five_count += 1
    return has_jack and five_count == 3 and jack_suit == starter.suit

# Computed by tools/gen_crib_table.py via exact enumeration of all 58,800 crib completions
const AVG_CRIB := [
    #  A     2     3     4     5     6     7     8     9    10     J     Q     K
    [5.53, 4.45, 4.57, 5.47, 5.74, 4.26, 4.09, 4.13, 4.04, 3.96, 4.20, 3.86, 3.75], # A
    ...
    [5.74, 5.77, 6.43, 7.00, 8.99, 7.10, 6.42, 5.76, 5.74, 7.03, 7.26, 6.93, 6.82], # 5
]

static func crib_value(rank_a: int, rank_b: int, my_crib: bool) -> float:
    var a := clampi(rank_a, 1, 13) - 1
    var b := clampi(rank_b, 1, 13) - 1
    if my_crib:
        return AVG_CRIB_DEALER[a][b]   # seat-conditioned: opponent completes defensively
    else:
        return AVG_CRIB_PONE[a][b]    # seat-conditioned: opponent completes greedily

func grade_play(own_hand: Array, pile: Array, count: int, opp_count: int,
        chosen, starter = null) -> Dictionary:
    var obs := AlleyObservation.for_play(own_hand, pile, count, opp_count, starter)
    var best_val: float = _brain.peg_best_value(obs)
    var chosen_val: float = _brain.peg_play_value(obs, chosen)
    var ev_lost: float = maxf(0.0, best_val - chosen_val)

    # Named trap detection
    var led_five: bool = (count == 0 and chosen.rank == 5)
    var left_danger: bool = new_count in [5, 10, 11, 21, 22]

    return {
        "best": ev_lost <= PEG_BEST,      # within 0.05 of optimal
        "ok": ev_lost < PEG_SLACK,        # within 0.35 -- no nagging
        "ev_lost": ev_lost,
        "best_card": best_card,
        "reason": ...,
        "tags": tags,
    }

func analyze_lead(player_cards: Array, unseen_pool: Array,
        opp_count: int, chosen, max_samples: int = 120) -> Dictionary:
    var samples: Array = _sample_hands(unseen_pool, opp_count, max_samples)
    for oc in samples:
        for c in player_cards:
            totals[c] += _play_recurse(player_cards, oc, [], 0, P, c)  # player maximises
            # opponent inside _sim() plays fair greedy -- AlleyBrain.peg_best_card(obs)

func begin_match(master_seed: int, client_seed_in: String = "") -> String:
    client_seed = client_seed_in
    var ctx := HashingContext.new()
    ctx.start(HashingContext.HASH_SHA256)
    ctx.update(_seed_bytes(master_seed))
    ctx.update(("|%s|server" % client_seed).to_utf8_buffer())
    server_secret = ctx.finish()
    commit_hex = _sha256_hex(server_secret)    # this goes to the player BEFORE dealing
    return commit_hex

func hand_seed(hand_index: int) -> int:
    var ctx := HashingContext.new()
    ctx.start(HashingContext.HASH_SHA256)
    ctx.update(server_secret)
    ctx.update(("|%s|%d" % [client_seed, hand_index]).to_utf8_buffer())
    var d: PackedByteArray = ctx.finish()
    var s: int = 0
    for i in range(8): s = (s << 8) | int(d[i])
    return s & 0x7FFFFFFFFFFFFFFF  # 63-bit positive seed

static func hash_roll(seed_val: int, tag: String, n: int) -> float:
    # roll(seed, "aid", 0) for discard; roll(seed, "aip", n) for nth pegging play
    # Returns a uniform float in [0, 1) derived from SHA-256
    var ctx := HashingContext.new()
    ctx.start(HashingContext.HASH_SHA256)
    ctx.update(b)                              # seed as big-endian 8 bytes
    ctx.update(("|%s|%d" % [tag, n]).to_utf8_buffer())
    var v: int = 0
    for i in range(7): v = (v << 8) | int(d[i])
    v = v >> 3                               # 53 bits
    return float(v) / 9007199254740992.0     # / 2^53

# AI-5 spacing targets -- the weaker tier's win rate vs Expert should land near:
#   Easy   2-5%   (expert wins 95-98%)
#   Normal 15-25% (expert wins 75-85%)
#   Hard   35-45% (expert wins 55-65%)
# Outside those bands => retune the _temperature() anchors in core/AlleyBrain.gd.
const N_MAIN := 10000     # expert vs random -- headline sanity check
const N_LADDER := 3000    # expert vs each weaker tier

func _wilson(k: int, n: int) -> Array:
    var z := 1.96    # z* for 95% CI
    var p := float(k) / float(n)
    var denom := 1.0 + z * z / float(n)
    var centre := (p + z * z / (2.0 * float(n))) / denom
    var margin := (z * sqrt(p * (1.0 - p) / float(n) + z * z / (4.0 * float(n) * float(n)))) / denom
    return [(centre - margin) * 100.0, (centre + margin) * 100.0]

# After the player locks in their throw, the discard evaluator runs.
# It calls AlleyBrain.eval_discards() -- the same function the AI used for its own throw.
var ranked: Array = _ranked_discards(six, dealer == _seat_me)
# Level 1 (Flags only): speaks up only when EV lost >= threshold, or a named bad throw
# Level 2 (Full): always shows the best keep + EV delta for the player's actual throw
# Grades the TWO cards you TOSSED, after the throw is locked. Feedback only.
# Never marks the game "assisted" (the throw cannot be changed).

func _coach_grade_peg(card) -> void:
    var obs := AlleyObservation.for_play(own, pile, count, opp_count, _match.starter)
    var g: Dictionary = _coach_eval().grade_play(own, pile, count, opp_count, card, _match.starter)
    # Accumulates pegging accuracy stats regardless of display level:
    _deal["peg_plays"] = int(_deal.get("peg_plays", 0)) + 1
    if bool(g.get("best", false)):
        _deal["peg_best"] = int(_deal.get("peg_best", 0)) + 1
    _deal["sum_peg_ev_lost"] = float(_deal.get("sum_peg_ev_lost", 0.0)) + float(g.get("ev_lost", 0.0))
    # Level-gated display:
    var p_lvl := _coach_level("coach_pegging", 0)
    if p_lvl <= 0 or not _coaching_allowed(): return
    if p_lvl == 1:          # flags only: led 5, danger count, or lost >= 1.0 EV
        if bool(g.get("led_five", false)) or bool(g.get("danger_count", false)) \
                or float(g.get("ev_lost", 0.0)) >= 1.0:
            _log("  [color=#e6b34a]Peg analysis: %s[/color]" % g.get("reason", ""))
    else:                   # full: every play, green if best, amber if not
        var col := "#4ade80" if g.get("ok", false) else "#ffd166"
        _log("  [color=%s]Peg analysis: %s[/color]" % [col, g.get("reason", "")])

func _compute_show_recap() -> Dictionary:
    var ranked: Array = _ranked_discards(six, dealer == _seat_me)
    var best_thrown: Array = ranked[0]["thrown"]
    var best_keep: Array = ...   # the 4 cards that would have been kept
    var best_pts: int = ScoreEngine.get_total_points(
        ScoreEngine.score_show(best_keep, starter, false))
    return {"your": player_show_total, "best": best_pts, "keep": best_keep, "thrown": best_thrown}

# Each time the player makes a fresh LEAD (count 0, pile empty) during PvE:
if count == 0 and pile.is_empty() and coach_deep_analysis and _pve_context():
    _coach_moves.append({"hand": own.duplicate(), "chosen": card,
        "opp_count": opp_count, "unseen": _unseen_for_player(own, pile)})

# After the game ends, runs CoachEval.analyze_lead() on each recorded lead
# on a background WorkerThreadPool task (non-blocking UI):
var work := func() -> void:
    for m in moves:
        var r: Dictionary = ce.analyze_lead(m["hand"], m["unseen"], m["opp_count"], m["chosen"], 60)
        if float(r.get("gain", 0.0)) >= 1.0:
            findings.append({"m": m, "r": r})   # only real misses (>=1 expected peg gained)
WorkerThreadPool.add_task(work)     # runs async, modal stays responsive

func _coach_hint_on() -> bool:
    return bool(settings.get("coach_discard_hint", false)) and _pve_context()
    # Never active in daily / online / LAN matches, regardless of the toggle.

# When ON: before the player commits, the UI highlights the EV-optimal 4-card keep.
# This is REAL assistance -- it changes the decision the player hasn't made yet.
# Consequence:
_coach_assisted = true   # set the moment a hint is shown; cannot be unset this game
# Assisted games: no achievements, no skill-stat accumulation, no streak credit.

func _coaching_allowed() -> bool:
    if bool(settings.get("coach_ranked_off", true)) and not _pve_context():
        return false    # silences discard log, pegging log, show recap in daily/online/LAN
    return true