KataGoAnal

Inject KataGo analysis — winrate, score lead, uncertainty — into SGF game records as standard C[...] comments. The output is readable by any SGF viewer (Sabaki, LGS, OGS, etc.), not just Sabaki. 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               # Inject analysis as C[...] comments 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 analysis (winrate, score lead, uncertainty)
katagoanal <file.sgf> --visits 500 -o <dir>   # Custom visits and output directory
katagoanal <file.sgf> -l zh                    # Chinese comment labels
katagoanal <file.sgf> --clear-comments         # Overwrite existing comments

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/

# Chinese labels
katagoanal record/*.sgf --visits 800 -o injected/ -l zh

# Clear existing comments before writing
katagoanal record/*.sgf --visits 800 -o injected/ --clear-comments

# Directories expand to *.sgf automatically
katagoanal record/

• -o/--output: Output directory (must already exist; default: current directory). Produces <stem>.injected.sgf.
• -l/--language: Comment language — en (English) or zh (Chinese). Controls field labels and colon style. Numeric values are always in Arabic numerals. (default: en).
• --clear-comments: Clear any existing C[...] comments on each node before writing new analysis data. By default, new content is prepended before existing comments, separated by a blank line.
• --visits: KataGo search visits per move (default: maxVisits from config.cfg, falling back to 800).

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.
• Analysis data is written into the standard C[...] comment property on each node, with perspective dynamically switching per move (Black's turn → Black perspective, White's turn → White perspective). The root node also gets a full metadata header including engine info, match rates, and key deviations.
• Per-move comments include winrate/score lead with inline ± uncertainty (from KataGo's rawStWrError/rawStScoreError), deltas versus the previous position, komi, and an engine info suffix line.