Metadata-Version: 2.4
Name: ludax-agents
Version: 1.0.0
Summary: Pretrained AlphaZero agents for Ludax board games
Author-email: Graham Todd <gdrtodd@gmail.com>, Alexander Padula <alexpadula2001@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/gdrtodd/ludax
Project-URL: Issues, https://github.com/gdrtodd/ludax/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ludax
Requires-Dist: dm-haiku
Requires-Dist: mctx
Requires-Dist: pydantic
Dynamic: license-file

# ludax-agents

Pretrained [AlphaZero](https://www.nature.com/articles/nature24270) agents for games in the [Ludax](https://github.com/gdrtodd/ludax) board game framework.

## Installation

```bash
pip install ludax-agents
```

Or install together with Ludax and its GUI:

```bash
pip install 'ludax[gui,agents]'
```

## What's included

Each bundled agent is a ResNet trained via self-play using Gumbel MuZero search. At inference time the agent runs 256 MCTS simulations per move.

| Game | Checkpoint |
|------|-----------|
| Reversi (Othello) | `reversi.ckpt` |

## Usage

The agents integrate automatically with the Ludax GUI — just install this package and an **alphazero** option will appear in the policy dropdowns for any supported game.

For programmatic use:

```python
from ludax import LudaxEnvironment
from ludax.games import reversi
from ludax_agents import az_checkpoint_policy, get_checkpoint_path

env = LudaxEnvironment(game_str=reversi)
policy = az_checkpoint_policy(env, get_checkpoint_path("reversi"))

# policy(state_b, rng_key) -> action_b
```

## Adding your own checkpoints

Checkpoints are produced by the AlphaZero trainer in [`examples/03-alpha-zero/`](https://github.com/gdrtodd/ludax/tree/main/examples/03-alpha-zero). Copy the best iteration file and rename it `<game_id>.ckpt` (where `game_id` matches a key in `ludax.games.__all__`), then place it in `src/ludax_agents/checkpoints/` and rebuild the package.

## Links

- [Ludax repository](https://github.com/gdrtodd/ludax)
- [Ludax on PyPI](https://pypi.org/project/ludax/)
- [Issues](https://github.com/gdrtodd/ludax/issues)
