hexbot

A Python framework for building AI bots for Hexagonal Tic-Tac-Toe (Connect-6 on an infinite hex grid). Fast C game engine, multiple neural network architectures, AlphaZero training pipeline, and a live training dashboard.

Home of the Orca bot.

Full guides, learning path, and feature reference live on the Wiki. Start with Quickstart or Concepts. Try it now in Colab (free T4 GPU, ~5 minutes).

Built a great bot with this? Open an issue or get in touch, and I'll feature it here.

Model Zoo

Share bots with the community. Download by name, upload your trained checkpoints. Built-in metadata (architecture, ELO, author, description) keeps everything interoperable.

from orca.zoo import Zoo

# See what others have shared
Zoo.list()

# Try someone else's bot
bot = Zoo.download('orca-v3')

# Share yours
Zoo.package('hex_checkpoint_500.pt',
            name='my-bot-v1', author='You', elo=1450,
            description='Trained 500 iterations with hex-masked')
Zoo.upload('my-bot-v1.pt', name='my-bot-v1')

Trained something interesting? Publish it and the next person can pull it with one line. See the Evaluation and Sharing wiki page for the full lifecycle (Arena, Leaderboard, Zoo).

Featured Community Bots

No community bots rated yet. Train one, then Leaderboard().rate(bot, name='my-bot-v1') to land here. See Evaluation and Sharing.

This table is regenerated from leaderboard.json by scripts/update_featured_bots.py (runs in CI on every push to main).

Installation

pip install hexbot

Or from source (for development):

git clone https://github.com/Saiki77/hexbot-building-framework.git
cd hexbot-building-framework
pip install -e .               # core (game engine + torch)
pip install -e '.[dashboard]'  # + dashboard UI
pip install -e '.[all]'        # everything

The C engine auto-compiles on first import (cc/gcc/clang required).

Quick Start

from hexbot import HexGame, Bot, Arena

game = HexGame()
game.place(0, 0)         # P0: 1 stone first turn
game.place(1, 0)         # P1: first of 2
game.place(1, -1)        # P1: second stone

# Any function is a bot
def my_bot(game):
    return game.legal_moves()[0]

result = Arena(my_bot, Bot.heuristic(), num_games=20).play()

Orca Bot

Pre-trained AlphaZero-style bot. The included checkpoint is early-stage (65 iterations) - gets significantly stronger with more training.

from hexbot import Bot
orca = Bot.orca()
move = orca.best_move(game)

Train

# From game collections (fast bootstrap)
python -m orca.scrape --games 5000 --output games.jsonl
python -m orca.sft --data games.jsonl --then-selfplay 50

# Pure self-play
python -m orca.train --iterations 100

# With web dashboard
python train_dashboard.py

Network Architectures

python -m orca.train --config hex-gnn --iterations 50

Features

Bot Approaches

Architecture

hexbot.py              Framework API (Bot, Arena, 30+ analysis functions)
hexgame.py             Game engine (wraps C engine via ctypes)
engine.c               2,300 lines optimized C (bitboard win detection)
bot.py                 Neural networks, MCTS, training pipeline
dashboard.py           Dashboard API (REST + WebSocket)
train_dashboard.py     Training dashboard with web UI
pyproject.toml         pip install config
orca/
  __init__.py          Orca bot loader
  config.py            All tunable parameters
  train.py             Training pipeline (CLI + library)
  sft.py               Supervised fine-tuning from games
  scrape.py            Game downloader
  solver.py            Endgame solver
  openings.py          Opening book
  curriculum.py        Skill-based curriculum
  ensemble.py          Multi-checkpoint ensemble
  distributed.py       Multi-GPU / Ray training
  zoo.py               Model zoo
  leaderboard.py       Bot rating system
  transformer_net.py   Transformer architecture
  hex_gnn.py           Graph neural network
  multiscale_net.py    Multi-scale architecture
  benchmark.py         Platform benchmark (compare Mac/CUDA/CPU)
  checkpoint.pt        Pre-trained weights
docs/                  Detailed documentation
examples/              Example bot scripts

Benchmark

Compare performance across platforms:

python -m orca.benchmark --quick    # ~30 seconds

Measures: C engine speed, NN inference, MCTS search, self-play, training steps, augmentation.

Device Support

Documentation

Full docs live on the Wiki (16 pages organized by Learn / Build / Train / Evaluate / Reference).

Good starting points:

Contributing

Built for the Hexagonal Tic-Tac-Toe community. Contributions welcome.

License

MIT