KataGoAnal

Inject KataGo win-rate (SBKV) and score lead (SBKS) into SGF game records. Sabaki recognizes these properties natively to render dual winrate/score-lead graphs. Designed exclusively for KataGo and cross-platform (Linux / macOS / Windows).

Project Structure

KataGoAnal/
├── pyproject.toml              # pip packaging metadata (name, version, dependencies, entry point)
├── README.md                   # This document
│
├── KataGoAnal/                 # Python package (the body of pip install)
│   ├── __init__.py             # Package declaration
│   ├── cli.py                  # Command dispatch + argparse (-h/-c/-m/-v/-o/--visits)
│   ├── configure.py            # katagoanal configure / init interactive setup
│   ├── sgf_io.py               # SGF read/write (sgfmill wrapper)
│   ├── katago_driver.py        # KataGo analysis subprocess driver
│   ├── inject.py               # Write SBKV/SBKS into game records
│   ├── paths.py                # User config directory + paths.json I/O + cfg read/write
│   └── configs/
│       └── config.cfg          # Bundled KataGo engine parameter template (shipped with package)
│
└── tests/                      # Test suite (pytest tests/)
    ├── fixtures.py             # Synthetic SGF test data
    ├── test_cli.py             # CLI tests
    ├── test_configure.py       # Configuration flow tests
    ├── test_sgf_io.py          # SGF logic tests
    ├── test_katago_driver.py   # Driver logic tests
    ├── test_inject.py          # Injection logic tests
    └── test_paths.py           # Paths I/O tests

Configuration Files

Installation

pip install katagoanal          # Regular install

The console command katagoanal is available after installation. Manual configuration is required before first use.

Configuration

katagoanal configure

Interactive flow (brackets show the saved path; empty on a fresh install):

KataGo engine path []: /home/user/katago/katago
Model file (.bin) []: /home/user/katago/model.bin
Config file (.cfg) [/home/user/.config/katagoanal/config.cfg]:
Threads [8]:
Visits [800]:

• Fresh install: brackets are empty — you must enter the paths.
• Reconfigure: brackets show previously saved paths — press Enter to keep.
• Non-existent paths are rejected with an error and you are prompted again.

Commands

katagoanal -h, --help           # Help
katagoanal -v, --version        # Version number
katagoanal -c, --config         # Current configuration (3 paths + visits/threads)
katagoanal -m, --model          # Model weight path + engine version
katagoanal configure | init     # Interactive setup
katagoanal <file.sgf>           # Inject win-rate + score lead
katagoanal <file.sgf> --visits 500 -o <dir>   # Custom visits and output directory

Usage

# Basic usage
katagoanal game.sgf

# Specify visits and output directory
katagoanal game.sgf --visits 500 -o output/

# Batch processing
katagoanal record/*.sgf --visits 800 -o injected/

# Directories expand to *.sgf automatically
katagoanal record/

• --visits: KataGo search visits per move (default: maxVisits from config.cfg, falling back to 800).
• -o/--output: Output directory (must already exist; default: current directory). Produces <stem>.injected.sgf.

Parameter Priority

• Komi, rules (RU), board size, and handicap from the SGF are always sent with every query and take priority.
• Rules are read from the SGF RU property; if absent, they are inferred from komi.
• config.cfg holds only engine-level defaults (visits, threads, Black perspective) and never overrides game-specific parameters.
• Injected SBKV (Black winrate, 0–100) and SBKS (Black score lead) are obtained directly from reportAnalysisWinratesAs=BLACK — no per-move flipping needed.