Metadata-Version: 2.4
Name: rulesatlas
Version: 0.0.1
Summary: Rule-based state transitions and outcomes for sports and games
Author-email: RiskDataScience GmbH <riskdatascience@web.de>
License-Expression: MIT
Project-URL: Source, https://github.com/rds0001/rulesatlas-python
Project-URL: Issues, https://github.com/rds0001/rulesatlas-python/issues
Project-URL: Documentation, https://github.com/rds0001/rulesatlas-python#readme
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: jsonschema>=4; extra == "test"
Dynamic: license-file

# rulesatlas

All and only the state needed to check game rules: plausible states, permitted next events, rule consequences and outcomes. No simulation or physical model.


A native rule library for game-state validation, legal next actions, transitions
and outcomes, with a bounded interpreter for user-defined JSON rules.
`list_games()` lists accepted profiles. All 212 retained profiles have accepted, explicitly bounded variants. Read `get_game(id)` for the exact
variant, required inputs and limitations; acceptance does not certify every
commercial or federation edition.


```python
import rulesatlas

rulesatlas.register_rules("first_to_three.json")
state = rulesatlas.new_state(
    "user.first_to_three", players=[{"id": "alice"}, {"id": "bob"}],
    ruleset_version="1.0.0",
)
state = rulesatlas.apply_action(state, {"type": "score", "params": {"player": 0}})
print(rulesatlas.outcome(state))
```

Supply a local JSON rulepack matching the bundled contract examples. Registration
is process-local and copies input data. Changed rules require a new version;
`overwrite=True` does not replace an immutable registered version. Nonempty
variants are not yet supported by the custom interpreter and are rejected.

Expressions use a fixed operator whitelist. Effects read the old state and commit
atomically after validation. No executable code, shell, network, randomness or
strategy is invoked by rules. Unknown rules and invalid actions raise `RuleError`
with a stable `code`. `validate_rules` and `validate_state` return structured
issues. Custom validation checks structure and declared fields, not arbitrary
historical reachability.

Finite parameter domains are enumerated up to 512 combinations; larger domains
return guarded event types with `completeness=False`. Winners are participant
IDs. Built-in candidates are visible only with `list_games(True)` until accepted.

The PyPI distribution and Python import name are both `rulesatlas`.

```sh
python -m pip install rulesatlas
```

## Built-in match rules

`S001` implements compact football match rules: goals, per-player cards,
eligibility, substitutions, phases and optional knockout progression.
Use `get_game("S001")` for its declared variant and limitations, and
`legal_actions(state)` for phase-dependent event types and remaining allowances.
The repository includes a Python football example in `examples/football.py`.
No ball motion, possession or injury state is stored.

## GitHub source repository

Repository: `rds0001/rulesatlas-python`. The package name remains unchanged.

Install from this repository root:

```sh
python -m pip install .
```

Source repository: https://github.com/rds0001/rulesatlas-python

CI results: https://github.com/rds0001/rulesatlas-python/actions

Release artifacts are checked before publication to PyPI.
