edh-rules-coach 0.2.2

A conservative, rules-aware coaching engine for Commander-style tabletop game states.

EDH Rules Coach

EDH Rules Coach is a local-first, rules-aware coaching engine for Commander-style tabletop game states. It separates two jobs that AI assistants often blur together:

1. a rules layer determines which actions and targets are legal; and
2. a policy layer ranks legal actions and explains the recommendation.

The project is intentionally conservative. When legality or screen-state confidence cannot be established, it prefers to abstain instead of inventing an action.

This is an independent, community-built project. It is not affiliated with or endorsed by Wizards of the Coast, Scryfall, or the Forge project. See NOTICE.md.

中文说明见 README.zh-CN.md.

Current capabilities

• JSON game-state input and command-line recommendations.
• Conservative fallback action generation when an external engine is unavailable.
• Target validation for permanent types, players, hexproof, shroud, and static protection text.
• Decklist parsing and Commander deck sanity checks.
• Optional local Scryfall bulk-data indexing; no Scryfall dataset is committed.
• Optional Forge integration through a JSON bridge; no Forge source or binaries are committed.
• Heuristic, linear-policy, Forge-prior, and state-policy training/evaluation utilities.
• Screenshot/TTS annotation helpers with a low-confidence abstention gate.
• 130 unit tests.

Project status

This repository is an early public release. The fallback rules are deliberately incomplete and are not a replacement for a full comprehensive-rules engine. For authoritative legality, connect an external engine and provide legal_actions in the input state.

Quick start

Requirements: Python 3.11 or newer. Pillow, NumPy, and headless OpenCV are installed for screenshot and card-image helpers; rules, deck, and text-state workflows otherwise use the Python standard library.

Install a published release from PyPI:

python -m pip install edh-rules-coach
edh-coach --help

Install a development checkout:

git clone https://github.com/stnmftnkgx-rgb/edh-rules-coach.git
cd edh-rules-coach
python -m pip install -e .
edh-coach recommend --state data/sample_state.json --generate-actions --top-k 5

Without installation:

$env:PYTHONPATH = "$PWD\src"
python -m mtg_ai recommend --state data/sample_state.json --generate-actions --top-k 5

Run the test suite:

python -m unittest discover -s tests -v

Run the repository hygiene check:

python scripts/check_repository.py

Build and smoke-test the installable wheel in an isolated environment:

python -m pip wheel . --no-deps --wheel-dir dist
python scripts/smoke_test_wheel.py --wheel-dir dist --fixture data/sample_state.json

Optional card data

Card data is downloaded by each user and remains outside version control:

./scripts/download_card_db.ps1

The downloader uses Scryfall's bulk-data endpoint with an identifying user agent. Review Scryfall's current API documentation and terms before redistributing derived data. This repository does not redistribute card images, bulk JSON, or the generated card-name index.

Optional Forge integration

Forge is a separate GPL-licensed project. Download it from its official repository or releases and place a local runtime under tools/forge-release/, or configure an external JSON rules engine. This repository includes only the small bridge source maintained here; it does not vendor Forge.

./scripts/forge_status.ps1

See docs/architecture.md for the boundary between the coach and external rules engines.

Input contract

The smallest useful state contains players, zones, turn/phase information, and either:

• an authoritative legal_actions list; or
• enough public information for conservative fallback generation.

Start with data/sample_state.json. Do not include private player information in bug reports.

Validate a state before sending it to the coach or an external engine:

edh-coach validate-state --state data/sample_state.json
edh-coach validate-state --state data/sample_state.json --json

The versioned Draft 2020-12 contract is distributed with the package at src/mtg_ai/schemas/game-state.schema.json. Engine-specific extension fields are allowed, while the required core shape and known field types are checked.

Contributing

Issues and pull requests are welcome. Small legality fixes should normally include focused tests for both the fallback rules path and the Forge bridge path when both are affected. Read CONTRIBUTING.md and SECURITY.md before submitting.

Maintainer release instructions are documented in docs/publishing.md.

License

Copyright 2026 stnmftnkgx-rgb and contributors.

Licensed under the GNU General Public License, version 3 or later. See LICENSE.