The tools/ directory contains a suite of Command Line Interface (CLI) utilities designed to analyze game logs in MJAI format. These tools facilitate the generation of statistical models and decision trees that are embedded into the agent via the configs/ package to inform its decision-making at runtime.
The tools are primarily focused on two domains: aggregating game-level probabilities (e.g., win rates based on score) and training danger estimation models (deal-in risk) from historical play data.
The following table summarizes the primary tools available in the suite:
| Tool Group | Primary Commands | Output Target | Purpose |
|---|---|---|---|
| Game Statistics | dump_game_stats, dump_light_game_stats | game_stats.json, light_game_stats.json | Generates win probability maps, round duration distributions, and Yamiten frequency. |
| Danger Estimation | estimate_danger extract, estimate_danger tree | danger_tree.all.json | Trains a decision tree model to estimate the probability of dealing into a Riichi hand. |
| Inspection | print_game_stats, estimate_danger dump_tree | Standard Output | Provides human-readable views of the generated JSON/binary data. |
Sources: tools/README.md1-27 .agents/tools-porting.md9-15
The developer tools bridge the gap between raw game logs (.mjson files) and the embedded configuration files used by the ManueAgent. All tools utilize a shared archive package to handle globbing, GZIP decompression, and MJAI message decoding tools/internal/archive/archive.go1-20
The diagram below maps the CLI tools to the internal data structures they generate and the domain entities they utilize.
Sources: tools/README.md9-26 tools/dump_game_stats/main.go233-243 tools/postprocess_light_game_stats/main.go115 tools/internal/archive/archive.go1-20
The statistics tools analyze thousands of game logs to create a baseline of "normal" Mahjong play. This includes the winProbsMap, which the AI uses to evaluate the value of its current score relative to other players across different rounds (e.g., East 1 vs South 4).
dump_game_stats: Aggregates per-game metrics using specialized counters such as yamitenCounter and drawTenpaiCounter tools/dump_game_stats/main.go83-154 It outputs configs.GameStats containing numHoras, ryukyokuRatio, and yamitenStats tools/dump_game_stats/main.go233-243dump_light_game_stats: Extracts round-level score differentials by taking snapshots of player scores at StartKyoku and comparing them to EndGame results tools/dump_light_game_stats/main.go56-65postprocess_light_game_stats: Performs the statistical conversion of raw score differentials into the final WinProbsMap tools/postprocess_light_game_stats/main.go59-90For details, see Game Statistics Tools.
The estimate_danger tool is a comprehensive suite for training and inspecting the deal-in risk model. It uses a feature-based approach, analyzing situations where exactly one player has declared Riichi to determine the safety of various tiles tools/estimate_danger/main.go41-62
The tool extracts feature vectors (e.g., suji, urasuji, dora, visible>=3) and determines if a discard resulted in a "hit" (deal-in) tools/estimate_danger/probabilities.go115-136 These are then used to build a decision tree that splits the data based on confidence intervals to maximize the predictive power of the model tools/estimate_danger/tree.go43-97
For details, see Danger Tree Estimation Tool.
Sources: tools/estimate_danger/main.go41-62 tools/estimate_danger/tree.go168-176 tools/estimate_danger/probabilities.go115-143 tools/estimate_danger/main.go182-201