SmartBot

A full-featured algorithmic chess engine for three-player hexagonal chess with a 7-stage evaluation pipeline.

Overview & Architecture

Triumvirate_Smartbot (view on GitHub) implements:

Complete game logic with all three-player rules (check, checkmate, stalemate, castling, en passant, promotion)
AI move evaluation and selection with multi-component scoring
HTTP REST API client for connecting to the Triumvirate server
Move tracing and session analytics
GUI (NiceGUI) and CLI interfaces
Multi-game mode (parallel + sequential games)

Project Modules

Module	Purpose
`board/`	Hexagonal board geometry, coordinates (A1–L12), adjacency, segments, bridges, rosettes, ray tables
`pieces/`	Piece classes (King, Queen, Rook, Bishop, Knight, Pawn) with movement logic
`pawn/`	Pawn special rules: direction, double move, en passant, promotion, stuck pawns, triple diagonal
`engine/`	Game class, Move dataclass, Executor (execute/undo moves)
`rules/`	Validator, check, checkmate, stalemate, castling, draw, double check, inherited check, mate author
`players/`	Player class, colors, turn order, piece inheritance
`state/`	GameState, BoardState, CastlingRights, history, serialization
`evaluation/`	AI evaluation pipeline (7 stages)
`bot/`	Move builder: constructs Move objects from coordinate pairs
`game_io/`	Import/export: TPGN, 3PF, JSON formats
`tracing/`	Per-move trace logging (schema, collector, serializer)
`trace_parser/`	Analytics: 28 metrics, session comparison, NiceGUI viewer

Installation & Setup

# Clone the repository
git clone <smartbot-repo-url>
cd Triumvirate_Smartbot

# Install dependencies
pip install -r requirements.txt

# Run with GUI (desktop window)
python main.py

# Run as web server
python main.py --web --port 8091

# Run in CLI mode
python cli.py --url http://localhost:8000 --name SmartBot

Settings are stored in smartbot_settings.json and persist between runs.

Evaluation Pipeline

SmartBot evaluates every legal move through a 7-stage pipeline. Each stage produces a component score, combined into a final MoveRating.

1. Piece Values & Position

▶

Base material values for each piece type, adjusted by game phase (opening/middlegame/endgame) and positional modifiers (pawn advancement, centralization).

get_base_value() — raw piece value
position_modifier() — bonuses for central cells, advanced pawns
material_score() — total material evaluation

2. Threat Analysis

▶

Identifies all threats on the board with severity classification:

CRITICAL — threats to kings, checkmate threats
HIGH — threats to queens and rooks
MEDIUM — threats to bishops and knights
LOW — threats to pawns

Includes third-player factor analysis (amplifier when the third player attacks the same target).

3. Defense Analysis

▶

Evaluates whether a move addresses existing threats:

analyze_defenses() — checks if the move blocks, captures attacker, or moves the threatened piece
find_threat_addressed() — matches moves to specific threats

4. Exchange Evaluation (Pseudo-SEE)

▶

Evaluates capture sequences to determine if an exchange is favorable:

Winning — captures a higher-value piece
Favorable — net positive material exchange
Equal — even trade
Unfavorable/Losing — net negative exchange

5. Positional Scoring

▶

Evaluates non-material positional factors:

Centralization — bonus for pieces on central cells
Mobility — bonus for moves that increase piece mobility
Pawn advancement — bonus for pushing pawns toward promotion
Locked pieces penalty — penalty for pieces with no mobility

6. Tactical Verification

▶

Post-filter that checks for immediate tactical opportunities:

Checkmate in 1 move
Discovered attacks
Fork detection

7. Move Selection (Softmax)

▶

Final selection uses softmax with configurable temperature:

Low temperature — nearly deterministic (picks the best move)
High temperature — more randomness (exploratory play)

All rated moves are sorted by total score, then a weighted random choice is made based on softmax probabilities.

Tracing & Logging

Each move is logged as a JSON file in logs/{color}_{game_id}/move_NNN.json:

Full board state before the move
All evaluation scores for each candidate move
Selected move and reasoning
Game metadata (game_meta.json)

Trace Parser

A built-in analytics tool that computes 28 metrics from trace logs:

# CLI mode
python -m trace_parser --logs ./logs

# GUI mode (NiceGUI)
python -m trace_parser --gui --logs ./logs

Supports session comparison for analyzing performance across multiple games.

Multi-Game Mode

SmartBot can play multiple games in parallel or sequence:

# CLI: 5 games sequentially
python cli.py --games 5

# CLI: 3 games in parallel
python cli.py --parallel 3

# GUI: configure in settings panel

Results are aggregated into summary_multi_*.json and .csv files.

Configuration Reference

Settings in smartbot_settings.json:

Key	Default	Description
`server_url`	`http://localhost:8000`	Triumvirate server URL
`bot_name`	`"SmartBot"`	Display name in lobby
`move_delay`	`0.5`	Seconds to wait between moves
`verbose`	`false`	Detailed console output
`tracing_enabled`	`true`	Enable per-move JSON trace logging

Evaluation constants are centralized in evaluation/config.py (piece values, weights, temperature, political matrix).

Triumvirate Notation in SmartBot

SmartBot internally uses the same server coordinate system (A1–L12) and piece names (King, Queen, etc.) as the game engine. However, when analyzing SmartBot traces or comparing with LLM bot output, the following mapping applies:

Piece Mapping

SmartBot / Engine	Triumvirate v4.0	Evaluation Role
King (K)	Leader (L)	Protected target, highest priority
Queen (Q)	Marshal (M)	Highest material value, primary attack piece
Rook (R)	Train (T)	High value, castling partner
Bishop (B)	Drone (D)	Diagonal control, medium value
Knight (N)	Noctis (N)	Fork potential, unique jump movement
Pawn (P)	Private (P)	Advancement bonus, promotion potential

Positional Analysis with Triumvirate Coordinates

The evaluation pipeline concepts map naturally to Triumvirate notation (see the full Triumvirate v4.0 specification for complete mapping tables):

Centralization — Ring 0 (rosette cells like C/W.B) and Ring 1 cells have the highest positional bonus
Pawn advancement — lower Ring value = more advanced (Ring 0 > Ring 1 > Ring 2 > Ring 3)
Buried level (Ring + Depth) — 0 = most active at rosette, 6 = most passive at corners
Sector awareness — the sector letter (W/B/R) instantly identifies which player's territory a cell belongs to