Metadata-Version: 2.1
Name: clubs-gym
Version: 0.1.3
Summary: clubs is an open ai gym environment for running arbitrary poker configurations.
Home-page: https://github.com/fschlatt/clubs_gym
Author: Ferdinand Schlatt
License: GPL-3.0
Project-URL: Bug Reports, https://github.com/fschlatt/clubs_gym/issues
Project-URL: Source, https://github.com/fschlatt/clubs_gym/
Keywords: reinforcement learning,poker,AI,gym
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: numpy (>=1.16.6)
Requires-Dist: clubs (>=0.1.2)
Requires-Dist: gym (>=0.18.0)

<div align="center">

<img src="./clubs_gym/resources/images/black_red_logo.svg" alt="Logo" width=200px>

</div>

# clubs_gym

[![PyPI Status](https://badge.fury.io/py/clubs_gym.svg)](https://badge.fury.io/py/clubs_gym)
[![PyPI Status](https://pepy.tech/badge/clubs_gym)](https://pepy.tech/project/clubs_gym)
[![codecov](https://codecov.io/gh/fschlatt/clubs_gym/branch/master/graph/badge.svg)](https://codecov.io/gh/fschlatt/clubs_gym)
[![CodeFactor](https://www.codefactor.io/repository/github/fschlatt/clubs_gym/badge)](https://www.codefactor.io/repository/github/fschlatt/clubs_gym)

clubs_gym is a [gym](https://gym.openai.com/) wrapper around the [clubs](https://github.com/fschlatt/clubs) python poker library. [clubs](https://github.com/fschlatt/clubs) is used for running arbitrary configurations of community card poker games. This includes anything from simple Leduc or [Kuhn](https://en.wikipedia.org/wiki/Kuhn_poker) poker to full n-player [No Limit Texas Hold'em](https://en.wikipedia.org/wiki/Texas_hold_%27em) or [Pot Limit Omaha](https://en.wikipedia.org/wiki/Omaha_hold_%27em#Pot-limit_Omaha).
## Install

Install using `pip install clubs-gym`.

# How to use

By running `import clubs_gym`, several pre-defined poker clubs poker configurations are registered with gym (call `clubs_gym.ENVS` for a full list). Custom environments can be registered with `clubs.envs.register({"{environment_name}": {config_dictionary})}`. Environment names must follow the gym environment name convention ({title-case}-v{version_number}). Check the [clubs documentation](https://clubs.readthedocs.io/en/latest/index.html) for additional information about the structure of a configuration dictionary.

Since [gym](https://gym.openai.com/) isn't designed for multi-agent games, the api is extended to enable registering agents. This is not required, but ensures each agent only receives the information it's supposed to. An agent needs to inherit from the `clubs_gym.agent.base.BaseAgent` class and implement the `act` mathod. `act` receives a game state dictionary and needs to output an integer bet size. A list of agents the length of the number of players can then be registered with the environment using `env.register_agents`. By calling `env.act({observation_dictionary})`, the observation dictionary is passed to the correct agent and the agent's bet is returned. This can then be passed on the `env.step` function. An example with an optimal Kuhn agent (`clubs_gym.agent.kuhn.NashKuhnAgent`) is given below.

## Example

```python
import gym

import clubs_gym

env = gym.make("KuhnTwoPlayer-v0")
env.register_agents([clubs.agent.kuhn.NashKuhnAgent(0.3)] * 2)
obs = env.reset()

while True:
    bet = env.act(obs)
    obs, rewards, done, info = env.step(bet)

    if all(done):
        break

print(rewards)
```

