shogiarena 0.1.0

Asynchronous tournament and SPSA tuning platform for USI shogi engines

ShogiArena

Looking for Japanese documentation? Read README_ja.md.

ShogiArena is an asynchronous tournament and SPSA tuning platform for USI shogi engines, featuring a live dashboard and remote execution support.

Installation

From PyPI (recommended)

pip install shogiarena

From source

git clone https://github.com/nyoki-mtl/ShogiArena.git
cd ShogiArena
make sync  # installs Python dependencies via uv

Basic Usage

Unified CLI (shogiarena)

The project now ships a single entry point that wraps the most common workflows:

# Analyze a position once with an engine binary or YAML config
shogiarena run analyze /path/to/engine --nodes 1000000 "sfen ..."

# Run a mate search
shogiarena run mate configs/engine/example.yaml "startpos moves 7g7f"

# Run tournament/SPSA via subcommands
shogiarena run tournament configs/arena/example.yaml --log-level INFO
shogiarena run spsa configs/spsa/example.yaml --engine-trace
shogiarena run tournament configs/arena/example.yaml --run-name nightly
shogiarena run tournament configs/arena/example.yaml --run-dir /tmp/shogi-run

# Generate kifu via selfplay config
shogiarena run generate configs/arena/selfplay.yaml

Any command accepts --help for detailed flags (instances, engine options, provisioning, etc.). All subcommands also honour a global --root-dir flag when you need to run against a specific runtime directory without modifying your saved settings.

Initialise runtime directories (pip install)

# Interactive mode (default) - guides you through setup
shogiarena config init
# Or use the compatibility alias:
shogiarena init

# Non-interactive mode (for CI/automation)
shogiarena config init --non-interactive --output-dir /path/to/output --engine-dir /path/to/engines

By default, config init runs interactively to guide you through setup, including adding repositories like YaneuraOu. Use --non-interactive for CI/automation scenarios.

The command writes settings.yaml under your platform config directory (for example ~/.config/shogiarena/settings.yaml).

When settings.yaml is not configured, default values are used:

• output_dir: ./shogiarena_output (subdirectory in current working directory)
• engine_dir: Temporary directory (e.g., /tmp/shogiarena-engines on Linux)

When settings.yaml is configured via config init, you can specify custom locations:

• Linux: ~/.local/share/shogiarena/output (default)
• Windows: %LOCALAPPDATA%\\shogiarena\\output (default)
• macOS: ~/Library/Application Support/shogiarena/output (default)

Subsequent CLI invocations resolve placeholders such as {output_dir} and {engine_dir} based on this file. You can override the output directory per invocation via --root-dir. If you use private GitHub repositories, store a fine-grained token with Contents (read-only) permission in settings.yaml under github_token.

Inspect or update repository paths

# Show the currently configured directories
shogiarena config show

# Edit settings interactively (use config init instead)
shogiarena config init

# Register a repo used by artifacts
shogiarena config repo set yaneuraou \
  --path ~/repos/YaneuraOu \
  --url https://github.com/yaneurao/YaneuraOu.git \
  --build-config ~/.config/shogiarena/builds/yaneuraou.yaml

# Remove a repo entry
shogiarena config repo remove yaneuraou

Supported placeholders in configs and options:

• {output_dir} – the configured output directory
• {engine_dir} – the configured engine cache directory

Sample configurations and binary/evaluation assets that previously lived under configs/ and data/ have been moved to .sandbox/ to avoid polluting the repository. Copy whatever you need from there into your own configured output directory before running the CLI commands above.

Default run output layout

By default, run outputs are written under:

{output_dir}/tournament/<config_stem>-<hash8>/YYYYMMDDHHmmSS/

Run a local tournament

shogiarena run tournament configs/arena/example.yaml --log-level INFO

Run an SPSA tuning session

shogiarena run spsa configs/spsa/example.yaml --log-level INFO

Serve dashboard for a completed run

# Resolve run directory from the original config
shogiarena dashboard serve --config .sandbox/configs/run/tournament/gauntlet.yaml

# Or point directly at the run directory
shogiarena dashboard serve --run-dir output_dir/tournament/gauntlet-<hash8>/YYYYMMDDHHmmSS

Execute a remote single game (smoke test)

shogiarena _internal remote-run-pair --spec-file path/to/spec.json

The spec schema is documented in shogiarena/cli/commands/remote.py and accepts engine binaries, option maps, and per-side time controls. (The subcommand is hidden from the public help output because it is intended for orchestrator-internal use.)

Directory Layout

ShogiArena/
├── configs/                # Arena and engine configuration templates
│   ├── arena/              # Tournament YAML files
│   └── spsa/               # SPSA tuning setups
├── src/
│   └── shogiarena/
│       ├── arena/          # Core arena logic (engines, orchestrators, services)
│       ├── shogidb/        # Database helpers and models
│       └── utils/          # Shared utilities (board handling, paths, etc.)
├── tests/
│   ├── unit/               # Unit tests
│   ├── integration/        # Integration tests
│   └── property/           # Property-based tests
├── agent-docs/             # Internal task logs and design notes
├── _refs/                  # Vendored reference implementations (read-only)
├── data/                   # Local data assets (engines, eval files)
└── output_dir/             # Generated run artifacts (ignored by Git)

Dashboard Frontend

• Dashboard JavaScript lives under src/shogiarena/web/dashboard/static/js/.
• Each tab owns a folder named after the tab (for example live/, games/, engines/, instances/, tournament/, spsa/, rules/). The entry point for a tab is always <tab>/<tab>.js and registers a single window.Dashboard<Tab> namespace.
• Shared helpers are bundled in shared/ modules (api.js, dom.js, notices.js, core.js). Tabs call into DashboardCore for state and event wiring instead of the deprecated Arena* globals.
• The dashboard Engines tab uses static/js/engines/engines.js. Standalone templates such as engine.html have been retired; all views now live inside the dashboard tabs.

Frontend quality checks

• Install-time dependencies already include Knip for dead-code detection. Run npm run frontend:knip whenever you touch src/shogiarena/web/dashboard/frontend. The script pins --tsConfig src/shogiarena/web/dashboard/frontend/tsconfig.json, so the @/* path aliases resolve correctly even though the dashboard code lives outside the repository root.
• The Knip configuration lives in knip.ts and scopes analysis to the dashboard workspace while wiring the nested Vite, Vitest, Tailwind CSS, and PostCSS config files so that build-only dependencies (e.g. tailwindcss, autoprefixer) are treated as used. Adjust the globs there if you add new entry points or configs under src/shogiarena/web/dashboard/frontend.
• The current configuration runs clean (exit code 0). Keep npm run frontend:knip in your local workflow or CI to spot dead code regressions early—any newly introduced unused files, dependencies, or exports will fail the check.

Additional Resources

• configs/resources/instances/README.md — details about remote instance configuration
• agent-docs/tasks/ — ongoing engineering task logs and decisions
• shogiarena run --help — list of execution subcommands (tournament / spsa / sprt / generate / mate / analyze)