How cryolite/kanachan works
Main Components
• Data Preprocessing and Annotation:
– The annotation tool lives in src/annotation and the bin/annotate4rl directory. These components extract decision-making points from raw game records (collected externally) and convert them into learning annotations.
– The paishan module (src/paishan) restores the full tile wall from game records.
– The xiangting module (src/xiangting) computes shanten (xiang ting) values by constructing a LOUDS-based trie.
• Simulation Engine:
– The simulation library in src/simulation (and its Python wrapper in kanachan/simulation) implements the Mahjong game logic accurately. This code is used to validate annotations (with the test/annotation_vs_simulation framework) and is also used as part of the game play simulation during training.
• AI Model Training:
– The training pipelines are implemented in the kanachan/training directory. There are several submodules (aiayn, bert, cql, ilql, iql) that represent different training methodologies/phases which together form the curriculum fine-tuning process.
– These components are built on PyTorch and use the encoder–decoder split where the encoder is shared across training phases while the decoder is replaced.
• Auxiliary and Infrastructure Components:
– The prerequisites directory holds tools and dependencies (available as Docker images) needed by developers.
– The mjai.app directory provides an application layer (with Dockerfiles and scripts) that likely serves as a front-end or an integration point for real-game scenarios.
– Configuration and build files (CMakeLists.txt, setup.py, pyproject.toml, etc.) and container definitions (.devcontainer, multiple Dockerfiles) orchestrate building, testing, and deployment in a containerized environment.
Relationships and Interactions
• Data Flow:
• Game records (collected externally) are input to the annotation components (src/annotation and/or bin/annotate4rl). The output is a set of annotations capturing decision points.
• These annotations are also validated using the simulation engine (test/annotation_vs_simulation checks consistency).
• Model Training:
• The annotated data from the preprocessing stage goes into the training pipelines in kanachan/training.
• Intermediate models (shared encoders) are refined via curriculum fine-tuning across the various training phases (aiayn, bert, cql, ilql, iql).
• Simulation and Verification:
• The simulation engine (src/simulation) provides a sandbox to test the game logic by running simulated rounds and comparing with annotation outputs.
• Containerization and Deployment:
• Dockerfiles in different subdirectories (e.g., in bin/annotate4rl, kanachan/simulation, prerequisites, mjai.app, etc.) indicate that each major component is containerized. This informs infrastructural boundaries and deployment units.
Architectural Patterns and Design Principles
• Modularization:
• Each major functional area (annotation, simulation, training) is split into separate directories with clear responsibilities.
• Separation of Concerns:
• The preprocessing (C++ tools) is decoupled from the training processes (Python/PyTorch), and the simulation engine (both C++ and Python) works independently for testing game logic.
• Containerization:
• The presence of Dockerfiles and development containers (.devcontainer) suggests that each component may be developed, tested, and deployed independently.
• Curriculum Learning:
• The training modules demonstrate a two-part design, with the encoder capturing general Mahjong knowledge and the decoder tailored to different objectives (e.g., imitation vs. score maximization).
• Interoperability:
• The design ensures that C++ tools and Python libraries can interact, for example via wrappers or shared data formats (annotations).
Relevant Technologies, Frameworks, and Libraries
• C++ components managed via CMake (CMakeLists.txt in various directories).
• Python modules and training code using PyTorch (referenced in the README).
• Container orchestration using Docker (.devcontainer, Dockerfiles).
• Trie data structures implemented via LOUDS (referenced for xiangting).
• Testing with GoogleTest (visible under prerequisites/googletest) for C++ modules.
• Continuous integration/development environment is emphasized via configuration and build scripts.
• Labels that mention key technologies (e.g., CMake for building C++, PyTorch for training, Docker for deployment) and brief notes about each module’s function.
• That components like curriculum fine-tuning and the encoder–decoder reuse strategy in the training layer are clearly highlighted.