How sanderland/katrain works
1. KaTrain is a desktop Go client built around a local KataGo analysis engine. Its main purpose is to load or create games, maintain a move tree, query KataGo for analysis, and render that information in a Kivy-based GUI.
2. The top-level entrypoints are katrain.py and katrain/__main__.py, which boot the application package. The katrain/core/base_katrain.py module is the central application/controller layer that connects UI events, game state, engine access, configuration, and persistence.
3. The core game model lives in katrain/core/game.py and katrain/core/game_node.py. These modules represent the board position, move tree, branches, comments, and analysis annotations that appear in SGF review and teaching mode.
4. Engine integration is isolated in katrain/core/engine.py and katrain/core/ai.py. This is the boundary to KataGo: the app sends analysis requests, receives candidate moves/evaluations/ownership data, and uses those results both for review and for AI play. katrain/core/contribute_engine.py adds a separate engine mode for distributed training contribution.
5. File-format handling is in katrain/core/sgf_parser.py. SGF import/export is a major data path: games can be loaded from disk or clipboard, analyzed, edited in the move tree, and written back out with engine-derived annotations.
6. The GUI is a Kivy application defined by katrain/gui.kv, katrain/popups.kv, and the Python modules under katrain/gui/. badukpan.py is the board view, controlspanel.py handles the right-side controls and analysis panels, popups.py manages dialogs, and the widget modules provide specialized UI components such as file browsing, graphs, move-tree navigation, sliders, and progress display.
7. The main runtime flow is: user action in the GUI -> core game state update -> engine query if needed -> engine response -> UI redraw and annotation update. This same flow supports several modes: normal play, post-game analysis, teaching games, and continuous/“pondering” analysis.
8. The repository bundles its own KataGo runtime assets under katrain/KataGo/, including platform binaries and config files, plus a packaged model under katrain/models/. This means the app can ship as a self-contained desktop analyzer without requiring the user to assemble the engine separately, though the README notes that the engine command can also be overridden for remote or custom setups.
9. Localization is built in. The katrain/i18n/ tree contains compiled and source message catalogs for multiple languages, and i18n.py plus katrain/core/lang.py support translation/runtime language selection. This is a user-facing subsystem rather than just documentation.
10. Visual customization is also packaged. themes/ contains downloadable theme archives, while katrain/gui/theme.py and the KV layer define how colors, board appearance, and UI styling are applied. Fonts and flags are bundled under katrain/fonts/ and katrain/img/.
11. Sound is a small but distinct subsystem under katrain/sounds/ and katrain/gui/sound.py, used for move feedback and alerts during play and analysis. It is part of the user experience loop rather than core game logic.
12. The repo includes a significant amount of test and packaging infrastructure. tests/ covers AI behavior, board/game logic, SGF parsing, and versioning; spec/ contains packaging metadata for builds; .github/workflows/ and custom GitHub actions automate CI and release-related tasks. This indicates the project is distributed as an end-user desktop application, not just a library.
Main entry points: base_katrain.py App Core · engine.py KataGo Engine · badukpan.py Board View · test_ai.py Tests
Components 25
Core
Application controller, game model, engine integration, and file format handling.
- Entrypoints · Top-level launch scripts that start the application package.
katrain.py - Module Main · Package entrypoint used for module execution.
katrain/__main__.py - App Core · Main application/controller layer wiring UI, game state, engine access, config, and persistence.
katrain/core/base_katrain.py - Game State · Board position, move tree, branches, comments, and annotations.
katrain/core/game.py - Move Node · Per-node move metadata and analysis annotations in the tree.
katrain/core/game_node.py - KataGo Engine · Boundary for sending analysis requests and receiving evaluations, ownership, and candidates.
katrain/core/engine.py - AI Logic · Analysis consumption and AI move selection built on engine output.
katrain/core/ai.py - Contribute Mode · Distributed training contribution engine path.
katrain/core/contribute_engine.py - SGF I/O · Import/export of games and engine annotations through SGF.
katrain/core/sgf_parser.py
GUI
Kivy widgets, board rendering, dialogs, and theming.
- Board View · Main board rendering and interaction surface.
katrain/gui/badukpan.py - Control Panel · Side controls, analysis panels, and play/review actions.
katrain/gui/controlspanel.py - Dialogs · Popups and dialog flow for file, settings, and status interactions.
katrain/gui/popups.py - Themeing · Color, board appearance, and UI styling logic.
katrain/gui/theme.py - Widgets · Specialized supporting widgets such as file browsing, graphs, move-tree navigation, sliders, and progress display.
katrain/gui/widgets/graph.py - KV UI · Kivy declarative UI definitions for the main screen and dialogs.
katrain/gui.kv - Popup KV · Declarative popup/dialog layout definitions.
katrain/popups.kv
Assets
Bundled runtime assets, localization, media, and downloadable themes.
- Language · Runtime language selection and translation support.
katrain/core/lang.py - KataGo Bundle · Packaged KataGo binaries and configs shipped with the app.
katrain/KataGo/katago - Model Pack · Bundled KataGo network model used for local analysis.
katrain/models/kata1-b18c384nbt-s9996604416-d4316597426.bin.gz - Translations · Compiled and source message catalogs for multiple languages.
katrain/i18n/locales/en/LC_MESSAGES/katrain.po - Sounds · Move feedback and alert sound effects.
katrain/sounds/stone1.wav - Themes · Packaged downloadable theme archives.
themes/koast-theme.zip
Ops
Tests, packaging, and CI/release automation.
- Tests · Coverage for AI behavior, board/game logic, SGF parsing, and versioning.
tests/test_ai.py - Packaging · Build and packaging metadata for desktop distribution.
spec/KaTrain.spec - CI Workflows · GitHub Actions workflows for testing, building, and release-related automation.
.github/workflows/test_and_build.yaml
Connections 29
- Entrypoints → App Core: starts · Launch script bootstraps the main app controller.
- Module Main → App Core: starts · Module execution enters the same application controller.
- App Core → Game State: owns · Controller maintains current game state and move tree.
- App Core → KataGo Engine: queries · Controller sends analysis requests and receives responses.
- App Core → SGF I/O: loads/saves · Controller orchestrates import, export, and persistence.
- App Core → Board View: drives · Controller updates board UI from state changes.
- App Core → Control Panel: drives · Controller feeds control and analysis panels.
- Game State → Move Node: contains · Game state is structured as a move tree of nodes.
- AI Logic → KataGo Engine: uses · AI logic depends on engine analysis outputs.
- Contribute Mode → KataGo Engine: specializes · Contribution mode wraps the engine boundary with a distinct workflow.
- KataGo Engine → KataGo Bundle: runs · Engine integration targets bundled KataGo binaries and configs.
- KataGo Engine → Model Pack: loads · Engine uses the packaged analysis model.
- SGF I/O → Game State: serializes · SGF parsing maps files into and out of game state.
- SGF I/O → Move Node: annotates · SGF export/import preserves node-level comments and analysis.
- Board View → Themeing: styles · Board view is styled by theme logic.
- Control Panel → Widgets: composes · Control panel is built from shared widget components.
- Dialogs → Popup KV: binds · Popup logic pairs with popup KV layout definitions.
- Board View → KV UI: binds · Main UI layout defines board placement and interactions.
- Control Panel → KV UI: binds · Main UI layout defines control panel structure.
- Language → Translations: uses · Runtime language selection consumes message catalogs.
- App Core → Language: selects · Application controller coordinates localization setup.
- Board View → Sounds: plays · Move feedback and alerts use packaged sounds.
- Tests → Game State: verifies · Tests cover core game logic.
- Tests → SGF I/O: verifies · Tests cover SGF parsing and export paths.
- Tests → AI Logic: verifies · Tests cover AI behavior and engine-facing logic.
- Packaging → KataGo Bundle: packages · Build spec includes bundled engine runtime assets.
- Packaging → Model Pack: packages · Build spec includes the packaged model.
- CI Workflows → Tests: runs · Workflows execute the test suite.
- CI Workflows → Packaging: builds · Workflows drive packaging and build validation.