xiangqibench 0.1.0__tar.gz

xiangqibench-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Secrets: keys belong in the environment, never in the repository
+.env
+.env.*
+!.env.example
+*.key
+config/*.yaml
+!config/*.example.yaml
+*api*.yaml
+!src/xiangqibench/example_config.yaml
+
+# Run outputs
+runs/
+output/
+*.log
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+.DS_Store
+.idea/
+.vscode/

xiangqibench-0.1.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-09-26
+
+First public release. It packages the XiangqiBench protocol, the 119 positions, the Pikafish
+defender, and the scoring used in the paper.
+
+### Added
+
+- The `xiangqibench` package and CLI, with the subcommands `run`, `score`, `modes`, `prompt`,
+  `cases`, `doctor`, `init`, and `play`.
+- Six evaluation modes, selected by `mode:` in the config file or by `--mode`:
+  - the paper settings `sighted` and `restricted`;
+  - the observation-ablation arms `S`, `S-NT`, `R-T`, and `R`.
+- YAML configuration with `${VAR}` / `${VAR:-default}` expansion from the environment, strict
+  key validation, and command-line overrides.
+- Model clients for Chat Completions (OpenAI, OpenRouter, vLLM, SGLang, or any compatible
+  server), Azure OpenAI, the OpenAI Responses API, and Anthropic. Calls are retried, and a
+  trial whose calls all fail writes no record.
+- The Pikafish defender, with a per-position fallback to a depth-5 rule search. Each defender
+  move records its backend, and the engine id and NNUE sha256 are stored with every trial.
+- A resumable, parallel suite runner. Each worker has its own engine, and records are written
+  atomically.
+- Scoring: pass@k, pass^k, earliest-three selection per cell, and 95% case-bootstrap intervals
+  with the paper's seeds.
+- `xiangqibench.replay.replay_record`, which re-verifies an archived trial against the current
+  code.
+- Conformance tests:
+  - archived prompts for all six settings, byte for byte;
+  - replay of 14 archived trials;
+  - rules, protocol, config, scoring, runner, and CLI tests.
+
+### Fixed (relative to the code that produced the paper's archive)
+
+These fixes change what future runs record. Archived results are scored as they were recorded.
+The effect of each fix on the paper's analyses is described in the paper.
+
+- **Check flag.** Feedback used to report `Check: No` after every move, including checking and
+  mating moves, and mates were labelled `stalemate`. The flag is now computed on the position
+  after the move, and mates are labelled `checkmate`. The trajectory's `in_check` is also set on
+  the final, game-ending move. Winners were never affected.
+- **Engine failures.** An engine that failed during search, for example on a network it cannot
+  load, silently handed every defender move to the rule fallback. It now stops the run with an
+  error, and only positions the engine rejects use the fallback.
+- **Repetition.** A threefold repetition in which one side checked on every one of its moves now
+  loses for that side (perpetual check) instead of being a draw.
+- **Forfeit move list.** Forfeit turns appended a copy of the previous move to `moves`, so
+  `plies` was one too high for forfeits after at least one move. Forfeits now append nothing.
+- **Statistics.** The simulation counter in `stats` was never incremented. All counters now use
+  their documented keys.
+- **Defender timing.** The defender's `duration_ms` now includes the engine search time.
+- **Record size.** Per-call prompt snapshots are off by default. The full message history is
+  still stored once per trial.
+
+[0.1.0]: https://github.com/floatai/xiangqibench/releases/tag/v0.1.0

xiangqibench-0.1.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use XiangqiBench, please cite the paper below."
+title: "XiangqiBench"
+type: software
+authors:
+  - name: "XiangqiBench authors"
+version: 0.1.0
+date-released: 2026-09-26
+license: MIT
+repository-code: "https://github.com/floatai/xiangqibench"
+keywords:
+  - llm-agents
+  - benchmark
+  - xiangqi
+  - chinese-chess
+preferred-citation:
+  type: article
+  title: "Finding the Move Is Not Winning the Game: XiangqiBench for Closed-Loop Evaluation of LLM Agents"
+  authors:
+    - name: "XiangqiBench authors"
+  year: 2026
+  url: "https://github.com/floatai/xiangqibench"

xiangqibench-0.1.0/DATA_CARD.md

@@ -0,0 +1,92 @@
+# Data card: XiangqiBench positions
+
+## Summary
+
+`src/xiangqibench/data/cases.jsonl` holds 119 composed xiangqi endgames. In every one, Red is to
+move and can force checkmate. Load them with `xiangqibench.load_cases()` or list them with
+`xiangqibench cases`.
+
+| | |
+|---|---|
+| Positions | 119 (116 *Shi Qing Ya Qu*, 3 *Jianghu*) |
+| Side to move | Red in all positions (the agent plays Red) |
+| Stored mate distance | 3–11 plies, median 9 |
+| Categories | 106 `threatmate_race`, 13 `forced_mate` |
+| Admission | 117 confirmed by Pikafish (`verified_by: engine`), 2 by a checks-only mate search (`solver_proof`) |
+| sha256 | `3cb4e29148f82cb6d9a881e28336676549225cfe86dd8fb947ccf580f1633d42` |
+
+## Provenance
+
+- ***Shi Qing Ya Qu*** (适情雅趣) is a Ming-dynasty treatise of composed endgames, printed in
+  1570. Digitized entries were taken from
+  [xqipu.com](https://www.xqipu.com/canjugupu/1547). Case ids are
+  `xq_shi_qing_ya_qu_<n>`, and `raw_index` is the entry's position in that digitization.
+- ***Jianghu*** (江湖) is a classical collection of street endgames. Case ids are
+  `xq_jianghu_endgames_<n>`.
+
+Both sources are several centuries old and are in the public domain. The historical solution
+text is not included, is never shown to agents, and is not used for scoring. They may still
+appear in pre-training corpora, so first-move agreement can partly reflect recall.
+
+## Admission
+
+Source solutions were not trusted. Each position was screened with a single-threaded,
+time-limited Pikafish search and admitted when the engine reported a forced mate for Red. The
+engine's mate distance and preferred first move are stored as `engine_mate_plies` and
+`first_winning_move`.
+
+Pikafish does not confirm a mate in two compositions, `xq_jianghu_endgames_084` and
+`xq_jianghu_endgames_327`. They were admitted by a checks-only mate search and carry
+`verified_by: solver_proof`. All 119 positions were also checked by hand.
+Admission relies on bounded search, so the positions are *search-supported* rather than formally
+proved.
+
+**Categories.** The same search was run with Black to move. If Black then also has a forced mate
+(`defender_threat_in_plies`), the position is a `threatmate_race`: a slow Red move can let Black
+mate first. Otherwise it is a `forced_mate`.
+
+## Fields
+
+| Field | Meaning |
+|---|---|
+| `id` | Stable case id |
+| `source`, `raw_index`, `name` | Source collection, index in the digitization, original title |
+| `fen` | Start position (FEN, Red to move) |
+| `challenger` | Side played by the agent (`red`) |
+| `category` | `threatmate_race` or `forced_mate` |
+| `win_in_plies` | Stored mate distance (engine or solver) |
+| `engine_mate_plies` | Pikafish mate distance, or `null` if the engine does not confirm a mate |
+| `defender_threat_in_plies` | Black's mate distance if Black were to move, or `null` |
+| `first_winning_move` | Reference root move from the engine (used only for first-move analysis) |
+| `legal_move_count` | Number of legal Red moves at the root |
+| `verified_by` | `engine` or `solver_proof` |
+| `difficulty_score`, `tier`, `piece_theme`, `tags` | Descriptive metadata; not used for scoring |
+
+The stored distances are admission metadata. They do not limit the game: every trial may run up
+to 40 plies.
+
+## Splits
+
+| Split | Cases | Use |
+|---|---|---|
+| `main` | 119 | Leaderboard (paper settings `sighted` and `restricted`) |
+| `ablation-gemini-3.1-pro` | 20 | Observation ablation for Gemini 3.1 Pro |
+| `ablation-gpt-5.5` | 21 | Observation ablation for GPT-5.5 |
+
+The ablation subsets are **model-specific**. Each contains positions that the model won at
+least once in the paper's Sighted trials, so the ablation measures how much of a demonstrated
+ability survives each observation change.
+
+- For GPT-5.5 the subset contains every such position.
+- For Gemini 3.1 Pro it is a stratified sample by mate distance, with a quota
+  {5: 3, 7: 6, 9: 5, 11: 6} and seed 20260926.
+
+Ablation numbers are therefore not comparable across models or with the `main` split.
+
+## Engine coverage
+
+Pikafish refuses to search two positions reachable in the benchmark: the start positions of
+`xq_jianghu_endgames_084` and `xq_jianghu_endgames_327`, and the positions after their first
+move. For such positions, the defender falls back to a depth-5 rule search. Each defender move
+records which backend chose it, so the share of rule-chosen moves can be computed from any set
+of records.

xiangqibench-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FloatAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xiangqibench-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.5
+Name: xiangqibench
+Version: 0.1.0
+Summary: Tool-grounded xiangqi endgames for evaluating LLM agents against a Pikafish defender.
+Project-URL: Homepage, https://github.com/floatai/xiangqibench
+Project-URL: Repository, https://github.com/floatai/xiangqibench
+Project-URL: Issues, https://github.com/floatai/xiangqibench/issues
+Project-URL: Changelog, https://github.com/floatai/xiangqibench/blob/main/CHANGELOG.md
+Author: XiangqiBench authors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,benchmark,chinese-chess,evaluation,llm,pikafish,xiangqi
+Classifier: Development Status :: 4 - Beta
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Board Games
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: cchess<1.26,>=1.25.5
+Requires-Dist: numpy>=1.24
+Requires-Dist: openai>=1.60
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# XiangqiBench
+
+[![Paper](https://img.shields.io/badge/paper-arXiv-b31b1b.svg)][paper]
+[![PyPI](https://img.shields.io/pypi/v/xiangqibench.svg)](https://pypi.org/project/xiangqibench/)
+[![Python](https://img.shields.io/pypi/pyversions/xiangqibench.svg)](https://pypi.org/project/xiangqibench/)
+[![CI](https://github.com/floatai/xiangqibench/actions/workflows/ci.yml/badge.svg)](https://github.com/floatai/xiangqibench/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**[Paper][paper]** | **[Data card](DATA_CARD.md)** | **[Changelog](CHANGELOG.md)** | **[Citation](#citation)**
+
+This repository contains the official implementation of *Finding the Move Is Not Winning the
+Game: XiangqiBench for Closed-Loop Evaluation of LLM Agents*.
+
+XiangqiBench asks an LLM agent to convert 119 composed xiangqi (Chinese chess) endgames into
+checkmate against a Pikafish defender. The agent acts through a small command protocol under
+per-turn budgets and is scored only on whether it actually delivers mate: finding the right
+first move is not enough.
+
+## Installation
+
+```bash
+pip install xiangqibench                  # OpenAI-compatible and Azure endpoints
+pip install "xiangqibench[anthropic]"     # adds the native Anthropic client
+```
+
+XiangqiBench requires Python 3.10 or later and a [Pikafish](https://github.com/official-pikafish/Pikafish)
+binary for the defender:
+
+```bash
+git clone https://github.com/official-pikafish/Pikafish && make -C Pikafish/src -j build
+export PIKAFISH_PATH=$PWD/Pikafish/src/pikafish
+xiangqibench doctor                       # checks the engine and prints its build and NNUE hash
+```
+
+The paper's defender was Pikafish `fd168f68` with the network whose sha256 begins `a2f41d4d`,
+searched to depth 18 with one thread and a 256 MB hash. Upstream has since replaced that network,
+and older builds cannot load the new one, so build the current Pikafish as shown above. Its
+moves can differ from the paper's defender. Every record stores the engine build and the network
+hash.
+
+## Usage
+
+```bash
+export OPENAI_API_KEY=...
+xiangqibench run --model gpt-5.5 --mode sighted --limit 5
+xiangqibench score runs/
+```
+
+Full runs are configured with a single YAML file; `xiangqibench init` writes a commented
+example. API keys are read from the environment, never from the file.
+
+```yaml
+mode: restricted                # sighted | restricted | S | S-NT | R-T | R
+model:
+  name: qwen3-235b
+  provider: openai              # openai | azure | openai-responses | anthropic
+  base_url: http://localhost:8000/v1
+  api_key_env: VLLM_API_KEY
+run:
+  trials: 3
+  workers: 8
+```
+
+```bash
+xiangqibench run -c my_run.yaml           # resumable: re-running fills in missing trials
+```
+
+Command-line flags override the file, and unknown keys are rejected.
+
+### Modes
+
+| Mode | Observation | Tools |
+|---|---|---|
+| `sighted` | Board, FEN, and legal moves after every ply | `view_board`, `simulate`, `get_legal_moves` |
+| `restricted` | Starting position once, then move diffs only | none |
+| `S`, `S-NT`, `R-T`, `R` | Observation ablations: state push (S/R) × tool access (T/NT) | as named |
+
+`sighted` and `restricted` are the paper's two settings. `xiangqibench prompt --mode <mode>`
+prints the exact system prompt for any mode.
+
+### Scoring
+
+`xiangqibench score` reports pass@k and pass^k over the earliest three scored trials per
+(model, mode, case), with 95% case-bootstrap intervals using the paper's seeds. Trials cut short
+by infrastructure errors are excluded and re-run automatically. Runs that change the standard
+budgets or defender settings are marked `standard: false`.
+
+### Python API
+
+```python
+from xiangqibench import load_config
+from xiangqibench.runner import run_suite
+
+report = run_suite(load_config("my_run.yaml"))
+```
+
+Any object with a `name` attribute and a `complete(messages) -> Completion` method can be
+evaluated as an agent; see `xiangqibench.runner.play_trial`.
+
+## Reproducibility
+
+Every trial is stored as one JSON record with the full message history, the move list, the
+resolved configuration, and the defender's identity, including which backend chose each
+defender move. The test suite replays archived trials from the paper against this code and checks
+every environment message and verdict (`xiangqibench.replay`). Known differences from the code
+that produced the paper's archive are listed in the [changelog](CHANGELOG.md).
+
+```bash
+pip install -e ".[dev]" && pytest
+```
+
+## Citation
+
+```bibtex
+@article{xiangqibench2026,
+  title   = {Finding the Move Is Not Winning the Game: {XiangqiBench} for Closed-Loop
+             Evaluation of {LLM} Agents},
+  author  = {XiangqiBench authors},
+  year    = {2026},
+  url     = {https://github.com/floatai/xiangqibench}
+}
+```
+
+## License
+
+The code is released under the [MIT License](LICENSE). The historical positions are in the
+public domain. Pikafish is licensed under GPL-3.0; it is not distributed with this package and
+runs as a separate process.
+
+[paper]: https://arxiv.org/abs/XXXX.XXXXX

xiangqibench-0.1.0/README.md

@@ -0,0 +1,130 @@
+# XiangqiBench
+
+[![Paper](https://img.shields.io/badge/paper-arXiv-b31b1b.svg)][paper]
+[![PyPI](https://img.shields.io/pypi/v/xiangqibench.svg)](https://pypi.org/project/xiangqibench/)
+[![Python](https://img.shields.io/pypi/pyversions/xiangqibench.svg)](https://pypi.org/project/xiangqibench/)
+[![CI](https://github.com/floatai/xiangqibench/actions/workflows/ci.yml/badge.svg)](https://github.com/floatai/xiangqibench/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**[Paper][paper]** | **[Data card](DATA_CARD.md)** | **[Changelog](CHANGELOG.md)** | **[Citation](#citation)**
+
+This repository contains the official implementation of *Finding the Move Is Not Winning the
+Game: XiangqiBench for Closed-Loop Evaluation of LLM Agents*.
+
+XiangqiBench asks an LLM agent to convert 119 composed xiangqi (Chinese chess) endgames into
+checkmate against a Pikafish defender. The agent acts through a small command protocol under
+per-turn budgets and is scored only on whether it actually delivers mate: finding the right
+first move is not enough.
+
+## Installation
+
+```bash
+pip install xiangqibench                  # OpenAI-compatible and Azure endpoints
+pip install "xiangqibench[anthropic]"     # adds the native Anthropic client
+```
+
+XiangqiBench requires Python 3.10 or later and a [Pikafish](https://github.com/official-pikafish/Pikafish)
+binary for the defender:
+
+```bash
+git clone https://github.com/official-pikafish/Pikafish && make -C Pikafish/src -j build
+export PIKAFISH_PATH=$PWD/Pikafish/src/pikafish
+xiangqibench doctor                       # checks the engine and prints its build and NNUE hash
+```
+
+The paper's defender was Pikafish `fd168f68` with the network whose sha256 begins `a2f41d4d`,
+searched to depth 18 with one thread and a 256 MB hash. Upstream has since replaced that network,
+and older builds cannot load the new one, so build the current Pikafish as shown above. Its
+moves can differ from the paper's defender. Every record stores the engine build and the network
+hash.
+
+## Usage
+
+```bash
+export OPENAI_API_KEY=...
+xiangqibench run --model gpt-5.5 --mode sighted --limit 5
+xiangqibench score runs/
+```
+
+Full runs are configured with a single YAML file; `xiangqibench init` writes a commented
+example. API keys are read from the environment, never from the file.
+
+```yaml
+mode: restricted                # sighted | restricted | S | S-NT | R-T | R
+model:
+  name: qwen3-235b
+  provider: openai              # openai | azure | openai-responses | anthropic
+  base_url: http://localhost:8000/v1
+  api_key_env: VLLM_API_KEY
+run:
+  trials: 3
+  workers: 8
+```
+
+```bash
+xiangqibench run -c my_run.yaml           # resumable: re-running fills in missing trials
+```
+
+Command-line flags override the file, and unknown keys are rejected.
+
+### Modes
+
+| Mode | Observation | Tools |
+|---|---|---|
+| `sighted` | Board, FEN, and legal moves after every ply | `view_board`, `simulate`, `get_legal_moves` |
+| `restricted` | Starting position once, then move diffs only | none |
+| `S`, `S-NT`, `R-T`, `R` | Observation ablations: state push (S/R) × tool access (T/NT) | as named |
+
+`sighted` and `restricted` are the paper's two settings. `xiangqibench prompt --mode <mode>`
+prints the exact system prompt for any mode.
+
+### Scoring
+
+`xiangqibench score` reports pass@k and pass^k over the earliest three scored trials per
+(model, mode, case), with 95% case-bootstrap intervals using the paper's seeds. Trials cut short
+by infrastructure errors are excluded and re-run automatically. Runs that change the standard
+budgets or defender settings are marked `standard: false`.
+
+### Python API
+
+```python
+from xiangqibench import load_config
+from xiangqibench.runner import run_suite
+
+report = run_suite(load_config("my_run.yaml"))
+```
+
+Any object with a `name` attribute and a `complete(messages) -> Completion` method can be
+evaluated as an agent; see `xiangqibench.runner.play_trial`.
+
+## Reproducibility
+
+Every trial is stored as one JSON record with the full message history, the move list, the
+resolved configuration, and the defender's identity, including which backend chose each
+defender move. The test suite replays archived trials from the paper against this code and checks
+every environment message and verdict (`xiangqibench.replay`). Known differences from the code
+that produced the paper's archive are listed in the [changelog](CHANGELOG.md).
+
+```bash
+pip install -e ".[dev]" && pytest
+```
+
+## Citation
+
+```bibtex
+@article{xiangqibench2026,
+  title   = {Finding the Move Is Not Winning the Game: {XiangqiBench} for Closed-Loop
+             Evaluation of {LLM} Agents},
+  author  = {XiangqiBench authors},
+  year    = {2026},
+  url     = {https://github.com/floatai/xiangqibench}
+}
+```
+
+## License
+
+The code is released under the [MIT License](LICENSE). The historical positions are in the
+public domain. Pikafish is licensed under GPL-3.0; it is not distributed with this package and
+runs as a separate process.
+
+[paper]: https://arxiv.org/abs/XXXX.XXXXX

xiangqibench-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xiangqibench"
+dynamic = ["version"]
+description = "Tool-grounded xiangqi endgames for evaluating LLM agents against a Pikafish defender."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "XiangqiBench authors" }]
+keywords = ["llm", "agents", "benchmark", "evaluation", "xiangqi", "chinese-chess", "pikafish"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Games/Entertainment :: Board Games",
+]
+dependencies = [
+    "cchess>=1.25.5,<1.26",
+    "numpy>=1.24",
+    "pyyaml>=6.0",
+    "openai>=1.60",
+]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.40"]
+all = ["anthropic>=0.40"]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.6", "mypy>=1.10", "types-PyYAML", "build>=1.2", "twine>=5"]
+
+[project.scripts]
+xiangqibench = "xiangqibench.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/floatai/xiangqibench"
+Repository = "https://github.com/floatai/xiangqibench"
+Issues = "https://github.com/floatai/xiangqibench/issues"
+Changelog = "https://github.com/floatai/xiangqibench/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/xiangqibench/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/xiangqibench"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/xiangqibench", "tests", "README.md", "CHANGELOG.md", "CITATION.cff", "LICENSE", "DATA_CARD.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+markers = ["engine: requires a Pikafish binary (set PIKAFISH_PATH)"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["RUF001", "RUF002", "RUF003", "E501", "SIM105"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011"]
+
+[tool.mypy]
+# numpy's stubs need >= 3.12; runtime 3.10 compatibility is enforced by ruff (target py310) and CI.
+python_version = "3.12"
+ignore_missing_imports = true
+warn_unused_ignores = true

xiangqibench-0.1.0/src/xiangqibench/__init__.py

@@ -0,0 +1,9 @@
+"""XiangqiBench: tool-grounded xiangqi endgames for evaluating LLM agents."""
+
+__version__ = "0.1.0"
+
+from xiangqibench.cases import EndgameCase, load_cases
+from xiangqibench.config import Config, load_config
+from xiangqibench.modes import MODES, get_mode
+
+__all__ = ["MODES", "Config", "EndgameCase", "__version__", "get_mode", "load_cases", "load_config"]