Analysis (src/analysis/)

evaluate_position(player::Player, game::ReversiGame) -> Dict

Score every legal move at game's current state using player. Returns a JSON-friendly dict with:

• "scores" — vector of (row, col, score) named tuples
• "best" — best move position as (row, col) or nothing
• "player" — current player (BLACK or WHITE)
• "heatmap" — 8×8 matrix of scores for legal moves (zeros elsewhere)

make_evaluator(name::AbstractString) -> Player

Construct an evaluator player from a short name:

• "heuristic" → HeuristicPlayer()
• "corner" → CornerPlayer()
• "mobility" → MobilityPlayer()
• "greedy" → GreedyPlayer()
• "minimax-N" → MinimaxPlayer(N) (N = 1..6)
• "mcts-N" → MCTSPlayer(N) (N = 20..500)

principal_variation(player::Player, game::ReversiGame, depth::Int) -> Dict

Trace the "principal variation" — the sequence of moves that would be played if both sides followed player's evaluation for depth plies.

Returns a dict with:

• "moves" — Vector of (row, col, notation, player) tuples, one per ply
• "boards" — Vector of 8×8 board snapshots after each ply (absolute encoding)
• "final_score" — (black, white) piece counts after the last traced move

score_move(player::Player, game::ReversiGame, move::Position) -> Float64

Return a scalar score for move in the current game, according to player's evaluation. Higher is better (from the current player's perspective).

OpeningBook

A Zobrist-hash-keyed opening book built from WTHOR professional game data.

• entries : map from board hash → aggregated statistics
• source_file : path of the .wtb file the book was built from
• game_count : number of WTHOR games consumed
• max_depth : maximum ply depth recorded per game (book is limited to the opening)

OpeningBookEntry

Aggregated statistics for a single board position in an opening book.

• total : number of games that passed through this position
• black_wins : games in which BLACK won
• white_wins : games in which WHITE won
• draws : games ending in a draw
• next_moves : Dict mapping next-move notation ("f5" etc.) to play count

build_opening_book(path::AbstractString; max_depth::Int=20) -> OpeningBook

Read a WTHOR .wtb file and build an opening book keyed by Zobrist hash. Each game is replayed from the empty board; at each ply up to max_depth, the current position hash is used to aggregate total games, wins by colour, and next-move frequencies.

Games that fail to replay cleanly (illegal moves) are skipped.

load_opening_book(path::AbstractString) -> OpeningBook

Deserialize an opening book previously saved with save_opening_book.

lookup_opening(book::OpeningBook, game::ReversiGame) -> Union{OpeningBookEntry,Nothing}

Return the opening-book entry for the current position of game, or nothing if the position was not observed in the source data.

opening_book_lookup_dict(book::OpeningBook, game::ReversiGame) -> Dict

Return a JSON-friendly lookup result for game's current position.

opening_book_summary(book::OpeningBook) -> Dict

Return a JSON-friendly summary: source file, game count, entry count, max depth.

save_opening_book(book::OpeningBook, path::AbstractString)

Serialize book to path using Julia's Serialization stdlib.