Candidate Generation

Relevant source files

• internal/domain/ai/call_candidates.go
• internal/domain/ai/call_candidates_test.go
• internal/domain/ai/candidate.go
• internal/domain/ai/candidate_builder.go
• internal/domain/ai/candidate_builder_test.go
• internal/domain/ai/candidate_score.go
• internal/domain/ai/candidate_test.go
• internal/domain/ai/evaluator_test.go
• internal/domain/ai/self_turn_candidates.go
• internal/domain/ai/self_turn_candidates_test.go
• internal/domain/ai/win_estimator.go
• internal/domain/ai/win_estimator_test.go
• internal/domain/ai/win_goals.go
• internal/domain/ai/win_trials.go

The Candidate Generation phase is the first stage of the ManueAgent.Decide() pipeline. It transforms raw legal actions provided by the domain layer into actionCandidate objects. These candidates represent not just an immediate action, but a potential future state (hand composition, shanten, and goals) used by the Monte Carlo simulation to evaluate the action's value.

The actionCandidate Structure

Every potential move is encapsulated in an actionCandidate struct. This structure links the immediate domain action with the resulting hand state and shanten analysis.

Field	Description
traceKey	A unique string identifier (e.g., -1.5m, 0.3p) used for logging and tracking trial results.
evaluationGroup	Integer used to group related candidates (e.g., all discards after a specific Pon belong to the same group).
action	The domain action.Action to be executed if this candidate is selected.
riichi	Boolean indicating if this candidate involves declaring Riichi.
scoreAsRiichi	Boolean indicating if future win values should include the Riichi yaku.
pruneToTenpai	Boolean indicating if non-tenpai goals should be removed before win estimation.
afterDiscardHand	The VisibleHand state after the action and its associated discard are performed.
shanten	The shanten of the hand after the discard.
shantenGoals	A list of service.Goal objects representing optimal paths to a winning hand.

Sources: internal/domain/ai/candidate.go14-36 internal/domain/ai/self_turn_candidates.go103-129

Self-Turn Generation (buildSelfTurnCandidates)

When it is the agent's turn to discard, buildSelfTurnCandidates processes the available legal actions.

Implementation Details

1. Hand Construction: It retrieves the current hand via selfTurnHand internal/domain/ai/self_turn_candidates.go14-17
2. Shanten Analysis: It calls service.AnalyzeShanten to identify all possible winning hand structures and their current shanten internal/domain/ai/self_turn_candidates.go18
3. Tsumogiri Preference: normalizedSelfTurnDiscards ensures that if a tile can be discarded from the hand or via tsumogiri, the agent keeps only the tsumogiri action to match original Manue behavior internal/domain/ai/self_turn_candidates.go81-101
4. Riichi Branching:
   • If a Riichi action is legal, the generator creates a candidate with riichi: true.
   • It filters out Riichi candidates that do not result in Tenpai (shanten <= 0) internal/domain/ai/self_turn_candidates.go42-58
   • scoreAsRiichi and pruneToTenpai are set to true for immediate Riichi candidates internal/domain/ai/self_turn_candidates.go53-55
5. Policy Exclusions: Concealed Kans (Ankan), Promoted Kans (Kakan), and Kyushukyuhai are intentionally ignored by the candidate generator and are not selected by the AI policy internal/domain/ai/self_turn_candidates.go21-22

Candidate Trace Key Mapping

The traceKey for self-turn discards follows a specific format:

• Normal Discard: -1.[tile] (e.g., -1.5m)
• Riichi Discard: 0.[tile] (e.g., 0.5m)

Sources: internal/domain/ai/self_turn_candidates.go13-79 internal/domain/ai/self_turn_candidates_test.go13-58

Reaction Generation (buildReactionCandidates)

When another player discards or declares a Kan, the agent generates reaction candidates.

Call + Discard Branching

Unlike self-turn candidates, a single "Call" action (Chi, Pon) results in multiple candidates—one for every legal discard after the call is made.

1. Pass Candidate: A none candidate is created if a Pass action is available. This candidate uses "future-riichi" scoring (scoreAsRiichi: true) because the hand remains closed internal/domain/ai/call_candidates.go22-40
2. Call Execution: For each legal call (Chi, Pon, CalledKan):
   • The agent simulates the call by updating the hand and adding the new meld internal/domain/ai/call_candidates.go68-72
   • Swap-Call (Kuikae) Filtering: The agent identifies tiles that would result in an illegal swap-call using callSwapTiles and filters them out internal/domain/ai/call_candidates.go94-97
   • Distinct Discards: For each remaining distinct tile in the hand, a new actionCandidate is generated internal/domain/ai/call_candidates.go100-118
   • Called Kan Exception: For CalledKan (Daiminkan), no discard follows, so a single candidate with discardTile: ? is returned internal/domain/ai/call_candidates.go78-92

Trace Key Logic

• Pass: none
• Call Discards: [callIndex].[tile] (e.g., 0.3p for a discard after the first legal call option).

Sources: internal/domain/ai/call_candidates.go15-59 internal/domain/ai/call_candidates.go61-120

Candidate Logic Flow

The following diagram illustrates how the ManueAgent transforms domain Action objects into evaluation-ready actionCandidate objects.

Entity Mapping: Actions to Candidates

Sources: internal/domain/ai/self_turn_candidates.go13-79 internal/domain/ai/call_candidates.go15-59

Shanten Integration and Goal Pruning

Candidates perform early shanten analysis to optimize the subsequent Monte Carlo simulation.

1. Base Shanten: The shanten calculated before the discard internal/domain/ai/candidate.go32
2. Candidate Shanten: Calculated after the discard. If the discarded tile is not in the ThrowableVector for a specific goal, that goal is filtered out during win estimation internal/domain/ai/win_goals.go55-60
3. Goal Pruning: filteredWinEstimateGoals removes goals based on the candidate's state:
   • If pruneToTenpai is true (Riichi), non-tenpai goals are removed internal/domain/ai/win_goals.go49-51
   • If the base shanten is high (>3), goals that increase shanten are removed internal/domain/ai/win_goals.go52-54

Selection and Red-Dora Logic

When selecting the best candidate (chooseBestCandidate), the agent compares candidateScore (average rank, then expected points). If there is a tie and preferBlack is enabled, the agent chooses the non-red version of the tile by checking the red boolean on the actionCandidate internal/domain/ai/candidate.go43-74

Reaction Candidate Branching

Sources: internal/domain/ai/call_candidates.go61-120 internal/domain/ai/candidate.go61-74