Metadata-Version: 2.4
Name: atomheart
Version: 0.3.1
Summary: Board game environments and Valanga adapters
License-Expression: GPL-3.0-only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=15.0.0
Requires-Dist: valanga==0.3.0
Requires-Dist: PyYAML>=6.0.3
Provides-Extra: chess
Requires-Dist: chess>=1.11.2; extra == "chess"
Provides-Extra: chess-rust
Requires-Dist: chess>=1.11.2; extra == "chess-rust"
Requires-Dist: shakmaty_python_binding>=0.1.5; extra == "chess-rust"
Provides-Extra: all
Requires-Dist: chess>=1.11.2; extra == "all"
Requires-Dist: shakmaty_python_binding>=0.1.5; extra == "all"
Provides-Extra: test
Requires-Dist: pytest==9.1.1; extra == "test"
Requires-Dist: coverage==7.17.0; extra == "test"
Requires-Dist: pytest-cov==7.1.0; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff==0.17.3; extra == "lint"
Requires-Dist: pylint==4.1.3; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy==2.4.0; extra == "typecheck"
Requires-Dist: pyright[nodejs]==1.1.414; extra == "typecheck"
Requires-Dist: types-PyYAML==6.0.12.20260906; extra == "typecheck"
Provides-Extra: dev
Requires-Dist: tox==4.67.2; extra == "dev"
Requires-Dist: types-PyYAML==6.0.12.20260906; extra == "dev"
Requires-Dist: ruff==0.17.3; extra == "dev"
Requires-Dist: pylint==4.1.3; extra == "dev"
Requires-Dist: black==26.10.1; extra == "dev"
Requires-Dist: mypy==2.4.0; extra == "dev"
Requires-Dist: pyright[nodejs]==1.1.414; extra == "dev"
Requires-Dist: build==1.6.1; extra == "dev"
Requires-Dist: twine==7.0.0; extra == "dev"
Requires-Dist: sphinx==9.2.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme==3.1.0; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints==3.17.3; extra == "dev"
Requires-Dist: pre-commit==4.7.0; extra == "dev"
Dynamic: license-file

# atomheart

A Python chess library providing a unified interface for chess board operations and move handling.

## Release 0.3.1

Morpion candidate occupancy now stops after the second missing point. Ordered
legal actions, symmetry orbits, terminality, successors, and the Valanga 0.3.0
dependency remain unchanged.

## Release 0.3.0

This release requires Python 3.14 and the published `valanga==0.3.0`. It preserves
the validated Morpion rules, canonical identities, checkpoints, and core game
behavior, with precise generic state and undo-token contracts. The base package
remains installable without either optional chess backend.

## Features

- Chess board representation and manipulation
- Move generation and validation
- Board modification tracking
- Support for both Python-chess and Rust-based backends
- FEN notation support
- Morpion Solitaire environment (5T and 5D variants)

## About

atomheart is a wrapper library that provides a unified interface over popular chess engines:
- [python-chess](https://github.com/niklasf/python-chess) - Pure Python chess library
- [shakmaty](https://github.com/niklasf/shakmaty) - Rust chess library via Python bindings

This unified interface is designed for use in chess search algorithms and AI agents, allowing seamless switching between backends for optimal performance.

See the repos
- [chipiron](github.com/victorgabillon/chipiron) - Lear AI agents for chess (and maybe later other games).
- [anemone](github.com/victorgabillon/anemone) - Tree search library

## Installation

```bash
pip install atomheart==0.3.1
pip install 'atomheart[chess]==0.3.1'
pip install 'atomheart[chess-rust]==0.3.1'
pip install 'atomheart[all]==0.3.1'
```

The base install keeps the lightweight core games available. Chess support is
optional, and the Rust-backed chess board is enabled by the `chess-rust` extra.

## Quick Start

```python
from atomheart.board import create_board
from atomheart.board.utils import FenPlusHistory

# Create a chess board
board = create_board(
    fen_with_history=FenPlusHistory(current_fen="rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"),
    use_rust_boards=True
)

# Make a move
move_key = board.get_move_key_from_uci("e2e4")
board_modification = board.play_move_key(move_key)
```

## Python 3.14 development

```bash
uv venv --python 3.14
uv pip install -e '.[test,dev,all]'
source .venv/bin/activate
tox
```

Core annotations use Python 3.14 deferred evaluation with runtime imports needed
by `typing.get_type_hints`. The lazy chess/Rust factories retain string
annotations so optional native types need not be imported. For these factories,
`annotationlib.get_annotations(..., format=annotationlib.Format.STRING)` can
inspect annotations without loading the optional backend.

The acting-role state classes retain their type-checking-only protocol bases to
preserve slotted dataclass layout. Morpion rules, canonical move identities,
checkpoint payloads and stable hashing are unchanged.

`shakmaty_python_binding==0.1.5` currently needs a source build on CPython 3.14
on Linux; its published binary wheel targets CPython 3.11. The complete chess
suite must be run against the actual compiled binding.

Tests, lint, and typing install `valanga==0.3.0` from PyPI. CI and release
workflows use the same published dependency through tox. The optional Rust
binding has no established published CPython 3.14 wheel; a local source build
was validated on Linux, and availability on other platforms is not guaranteed.
