Metadata-Version: 2.4
Name: shogiarena
Version: 0.1.0
Summary: Asynchronous tournament and SPSA tuning platform for USI shogi engines
Project-URL: Homepage, https://github.com/nyoki-mtl/ShogiArena
Project-URL: Repository, https://github.com/nyoki-mtl/ShogiArena
Project-URL: Documentation, https://nyoki-mtl.github.io/ShogiArena
Project-URL: Changelog, https://github.com/nyoki-mtl/ShogiArena/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/nyoki-mtl/ShogiArena/issues
Author-email: Hiroki Taniai <nyoki.mtl@gmail.com>
License: MIT
License-File: LICENSE
Keywords: engine,shogi,spsa,tournament,tuning,usi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.12.15
Requires-Dist: asyncssh>=2.21.0
Requires-Dist: cshogi>=0.9.6
Requires-Dist: matplotlib>=3.10.5
Requires-Dist: omegaconf>=2.3.0
Requires-Dist: pandas>=2.3.2
Requires-Dist: psutil>=6.0.0
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: sqlalchemy>=2.0.43
Requires-Dist: tqdm>=4.67.1
Requires-Dist: types-pyyaml>=6.0.12.20250822
Description-Content-Type: text/markdown

# ShogiArena

> Looking for Japanese documentation? Read [README_ja.md](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)
```bash
pip install shogiarena
```

### From source
```bash
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:

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

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

```bash
# 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
```bash
shogiarena run tournament configs/arena/example.yaml --log-level INFO
```

### Run an SPSA tuning session
```bash
shogiarena run spsa configs/spsa/example.yaml --log-level INFO
```

### Serve dashboard for a completed run
```bash
# 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)
```bash
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](https://github.com/webpro-nl/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`)
