Haruki Sekai Deck Recommendation C++

Team Haruki's maintained fork of the C++ Project Sekai deck recommendation engine. The previous C++ optimization project lives at NeuraXmy/sekai-deck-recommend-cpp. Some modifications are based on moe-sekai/sekai-deck-recommend-cpp.

This project provides Python bindings and a WebAssembly target for the Haruki ecosystem, including the original brute-force search algorithm and additional randomized / heuristic recommendation algorithms.

Install Python package

Using uv:

uv add haruki-sekai-deck-recommend-cpp

To install into the current Python environment:

uv pip install haruki-sekai-deck-recommend-cpp

pip is still supported for users who are not using uv:

pip install haruki-sekai-deck-recommend-cpp

Install from source

Prerequisites

• CMake ≥ 3.15
• C++20 compatible compiler (GCC/Clang/MSVC)
• Python 3.10+ with development headers
• uv (recommended; pip workflows are also supported)

Steps

# Clone with submodules
git clone --recursive https://github.com/Team-Haruki/sekai-deck-recommend-cpp.git
cd sekai-deck-recommend-cpp

# Create a local virtual environment and install the package in editable mode
uv venv
uv pip install -e . -v

# Smoke test the Python binding
uv run python -c "import sekai_deck_recommend_cpp"

If you are not using uv, pip install -e . -v remains supported.

Usage

from sekai_deck_recommend_cpp import (
    SekaiDeckRecommend, 
    DeckRecommendOptions,
    DeckRecommendCardConfig
)
   
sekai_deck_recommend = SekaiDeckRecommend()

sekai_deck_recommend.update_masterdata("base/dir/of/masterdata", "jp")
sekai_deck_recommend.update_musicmetas("file/path/of/musicmetas.json", "jp")

options = DeckRecommendOptions()

# optimizing target in ["score", "power", "skill", "bonus"], default is "score"
options.target = "score"

# one of ["dfs", "ga", "dfs_ga", "rl", "sa"], default is "ga"
# ("dfs" for challenge live types).
#   dfs    - exact branch-and-bound; for score target on marathon/banner events
#            and challenge live it completes the full card pool in ~100ms with
#            provably optimal results (give world bloom / mysekai a timeout_ms)
#   rl     - lowest latency (~30ms) with learned cross-request warm starts;
#            recommended for high-throughput services
#   dfs_ga - adaptive: exact DFS result when it completes in budget,
#            GA refinement otherwise
#   ga     - genetic algorithm baseline; sa - legacy simulated annealing
options.algorithm = "ga"   

options.region = "jp"
options.user_data_file_path = "user/data/file/path.json"
options.live_type = "multi"
options.music_id = 74
options.music_diff = "expert"
options.event_id = 160
options.single_card_configs = [
    {
        "card_id": 12345,
        "level": 60,
        "skill_level": 4,
        "master_rank": 5,
        "episode_read_count": 2,
        "canvas": True,
    }
]

result = sekai_deck_recommend.recommend(options)

For more details of options, please refer the docstring of sekai_deck_recommend.DeckRecommendOptions

WebAssembly npm package

The WebAssembly npm package scaffold lives in npm/haruki-sekai-deck-recommend-cpp. It publishes only the generated Embind loader, the .wasm binary, JavaScript wrapper helpers, and TypeScript declarations. Master data, music metas, and user data are intentionally loaded by the application instead of being bundled into the npm package.

With emsdk activated:

emcmake cmake -S . -B build_wasm -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build_wasm -j
cd npm/haruki-sekai-deck-recommend-cpp
npm pack

Acknowledgments

• Original implementation by xfl03/sekai-calculator
• Previous C++ optimization project by NeuraXmy/sekai-deck-recommend-cpp
• Some modifications based on moe-sekai/sekai-deck-recommend-cpp
• JSON parsing and WebAssembly JSON payloads by yyjson
• Python bindings powered by pybind11

Performance & Concurrency

• recommend_batch(options_list) (Python) / recommendBatch(jsonArray) (wasm) runs multiple requests — different algorithms, musics or targets — in one call and returns results in input order.
• Engine-internal parallelism is opt-in via the DECK_ENGINE_THREADS environment variable or set_engine_thread_count() (default is fully serial and bit-identical to historical behavior). The Python recommend releases the GIL, so calls can also run concurrently from Python threads.
• A pthreads wasm variant can be built with -DSEKAI_WASM_THREADS=ON (requires COOP/COEP headers for SharedArrayBuffer).
• Local benchmark / regression tooling lives in tools/bench/ (see its README for the verification methodology used for performance changes).