Metadata-Version: 2.4
Name: katagoanal
Version: 0.4.0
Summary: A lightweight CLI tool to inject KataGo win-rate (SBKV) and score lead (SBKS) into SGF files (Sabaki-readable).
Author-email: Hoigin <laihoigin@gmail.com>
Project-URL: Homepage, https://github.com/hoigin/KataGoAnal
Project-URL: Repository, https://github.com/hoigin/KataGoAnal
Project-URL: Issues, https://github.com/hoigin/KataGoAnal/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: sgfmill>=1.1.1

[![EN](https://img.shields.io/badge/lang-English-blue)](./README.md)
[![ZH](https://img.shields.io/badge/lang-中文-red)](./README_zh.md)

# 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

| File | Purpose | Consumer |
|---|---|---|
| `pyproject.toml` | pip packaging metadata: name, version, dependencies, entry point, package scope | `pip install` |
| `KataGoAnal/configs/config.cfg` | Bundled KataGo engine parameter template: `reportAnalysisWinratesAs=BLACK`, `maxVisits`, `numAnalysisThreads`, etc. | Copied by `configure` on first run |
| `~/.config/katagoanal/paths.json` | Three user-configured paths: binary, model, config | `katagoanal` at runtime |
| `~/.config/katagoanal/config.cfg` | User copy (`configure` copies from bundled template and rewrites threads/visits) | `katago analysis` subprocess |

## Installation

```bash
pip install katagoanal          # Regular install
```

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

## Configuration

```bash
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

```bash
# 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.
