Metadata-Version: 2.4
Name: shogiarena
Version: 0.4.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 <charmer.popopo@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.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.11
Requires-Dist: aiohttp>=3.12.15
Requires-Dist: asyncssh>=2.21.0
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: pydantic>=2.12.5
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rshogi-py-avx2==0.10.3
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

[![CI](https://github.com/nyoki-mtl/ShogiArena/actions/workflows/public-ci.yml/badge.svg)](https://github.com/nyoki-mtl/ShogiArena/actions/workflows/public-ci.yml)
[![Docs](https://github.com/nyoki-mtl/ShogiArena/actions/workflows/public-docs.yml/badge.svg)](https://nyoki-mtl.github.io/ShogiArena/index.html)
[![PyPI](https://img.shields.io/pypi/v/shogiarena)](https://pypi.org/project/shogiarena/)
[![Python](https://img.shields.io/pypi/pyversions/shogiarena)](https://pypi.org/project/shogiarena/)
[![License](https://img.shields.io/github/license/nyoki-mtl/ShogiArena)](https://github.com/nyoki-mtl/ShogiArena/blob/main/LICENSE)

> [!NOTE]
> This project is still moving quickly. Public APIs are being clarified, and breaking changes are accepted during development. See [CHANGELOG](CHANGELOG.md) for release notes.

**Documentation:** [https://nyoki-mtl.github.io/ShogiArena/index.html](https://nyoki-mtl.github.io/ShogiArena/index.html)
**Japanese README:** [README_ja.md](README_ja.md)

ShogiArena is a platform for running shogi engine tournaments, statistical testing, dashboard monitoring, and engine automation.

## Public Python API

Supported import paths:

- `shogiarena.engine`
- `shogiarena.tournament`
- `shogiarena.cli`
- `shogiarena.composition`

Implementation modules live under `shogiarena._core`. They are importable but internal, and not covered by compatibility guarantees.

## Installation

```bash
pip install shogiarena
```

Optional environment initialization:

```bash
shogiarena config init
```

This is useful when you need artifact-based engine resolution, placeholder variables such as `{output_dir}` / `{engine_dir}`, or shared cache settings.

## Quick Examples

### Use a USI engine from Python

```python
import asyncio

from shogiarena.engine import UsiThinkRequest, create_engine


async def main() -> None:
    async with await create_engine("engine.yaml") as engine:
        result = await engine.think(
            sfen="startpos",
            request=UsiThinkRequest(movetime=5_000),
        )
        print(result.bestmove)


asyncio.run(main())
```

### Run a tournament from Python

```python
import asyncio

from shogiarena.tournament import run_tournament


async def main() -> None:
    await run_tournament(
        "tournament.yaml",
        run_dir="runs/example",
    )


asyncio.run(main())
```

### Advanced runner construction

```python
import asyncio

from shogiarena.tournament import (
    build_tournament_runner,
    create_run_storage,
    load_tournament_config,
)


async def main() -> None:
    config = load_tournament_config("tournament.yaml")
    storage = create_run_storage("runs/example")
    runner = build_tournament_runner(config, storage=storage)
    await runner.run()


asyncio.run(main())
```

## CLI Examples

```bash
shogiarena run tournament configs/run/tournament/example.yaml
shogiarena run sprt examples/configs/run/sprt/example.yaml
shogiarena run spsa examples/configs/run/spsa/example.yaml
```

`tournament` and `sprt` are available both from CLI and the public Python API. `spsa` is currently CLI-first; its Python surface is not yet formalized.

## Documentation

- [Getting Started](https://nyoki-mtl.github.io/ShogiArena/getting-started/)
- [User Guide](https://nyoki-mtl.github.io/ShogiArena/user-guide/)
- [API Reference](https://nyoki-mtl.github.io/ShogiArena/api/)
- [Technical Notes](https://nyoki-mtl.github.io/ShogiArena/technical/)
- [Contributing](https://nyoki-mtl.github.io/ShogiArena/development/contributing/)

## License

MIT. See [LICENSE](LICENSE).
