multi-agent-rlenv 3.7.2__py3-none-any.whl → 3.7.4__py3-none-any.whl

marlenv/__init__.py

@@ -1,65 +1,114 @@
 """
 `marlenv` is a strongly typed library for multi-agent and multi-objective reinforcement learning.
 
+Install the library with
+```sh
+$ pip install multi-agent-rlenv      # Basics
+$ pip install multi-agent-rlenv[all] # With all optional dependecies
+$ pip install multi-agent-rlenv[smac,overcooked] # Only SMACv2 & Overcooked
+```
+
 It aims to provide a simple and consistent interface for reinforcement learning environments by providing abstraction models such as `Observation`s or `Episode`s. `marlenv` provides adapters for popular libraries such as `gym` or `pettingzoo` and provides utility wrappers to add functionalities such as video recording or limiting the number of steps.
 
-Almost every class is a dataclassto enable seemless serialiation with the `orjson` library.
+Almost every class is a dataclass to enable seemless serialiation with the `orjson` library.
 
-# Existing environments
-The `MARLEnv` class represents a multi-agent RL environment and is at the center of this library, and `marlenv` provides an adapted implementation of multiple common MARL environments (gym, pettingzoo, smac and overcooked) in `marlenv.adapters`. Note that these adapters will only work if you have the corresponding library installed.
+# Fundamentals
+## States & Observations
+`MARLEnv.reset()` returns a pair of `(Observation, State)` and `MARLEnv.step()` returns a `Step`.
 
-```python
-from marlenv.adapters import Gym, PettingZoo, SMAC, Overcooked
-import marlenv
+- `Observation` contains:
+  - `data`: shape `[n_agents, *observation_shape]`
+  - `available_actions`: boolean mask `[n_agents, n_actions]`
+  - `extras`: extra features per agent (default shape `(n_agents, 0)`)
+- `State` represents the environment state and can also carry `extras`.
+- `Step` bundles `obs`, `state`, `reward`, `done`, `truncated`, and `info`.
 
-env1 = Gym("CartPole-v1")
-env2 = marlenv.make("CartPole-v1")
-env3 = PettingZoo("prospector_v4")
-env4 = SMAC("3m")
-env5 = Overcooked.from_layout("cramped_room")
-```
+Rewards are stored as `np.float32` arrays. Multi-objective envs use reward vectors with `reward_space.size > 1`.
 
-# Wrappers & Builder
-To facilitate the create of an environment with common wrappers, `marlenv` provides a `Builder` class that can be used to chain the creation of multiple wrappers.
+## Extras
+Extras are auxiliary features appended by wrappers (agent id, last action, time ratio, available actions, ...).
+Wrappers that add extras must update both `extras_shape` and `extras_meanings` so downstream users can interpret them.
+`State` extras should stay in sync with `Observation` extras when applicable.
+
+# Environment catalog
+`marlenv.catalog` exposes curated environments and lazily imports optional dependencies.
 
 ```python
-from marlenv import make, Builder
+from marlenv import catalog
 
-env = <your env>
-env = Builder(env).agent_id().time_limit(50).record("videos").build()
+env1 = catalog.overcooked().from_layout("scenario4")
+env2 = catalog.lle().level(6)
+env3 = catalog.DeepSea(mex_depth=5)
 ```
 
-# Using the library
-A typical environment loop would look like this:
+Catalog entries require their corresponding extras at install time (e.g., `marlenv[overcooked]`, `marlenv[lle]`).
+
+# Wrappers & builders
+Wrappers are composable through `RLEnvWrapper` and can be chained via `Builder` for fluent configuration.
 
 ```python
-from marlenv import DiscreteMockEnv, Builder, Episode
-
-env = Builder(DicreteMockEnv()).agent_id().build()
-obs, state = env.reset()
-terminated = False
-episode = Episode.new(obs, state)
-while not episode.is_finished:
-    action = env.sample_action() # a valid random action
-    step = env.step(action) # Step data `step.obs`, `step.reward`, ...
-    episode.add(step, action) # Progressively build the episode
+from marlenv import Builder
+from marlenv.adapters import SMAC
+
+env = (
+    Builder(SMAC("3m"))
+    .agent_id()
+    .time_limit(20)
+    .available_actions()
+    .build()
+)
 ```
 
-# Extras
-To cope with complex observation spaces, `marlenv` distinguishes the "main" observation data from the "extra" observation data. A typical example would be the observation of a gridworld environment with a time limit. In that case, the main observation has shape (height, width), i.e. the content of the grid, but the current time is an extra observation data of shape (1, ).
+Common wrappers include time limits, delayed rewards, masking available actions, and video recording.
+
+# Using the library
+## Adapters for existing libraries
+Adapters normalize external APIs into `MARLEnv`:
 
 ```python
-env = GridWorldEnv()
-print(env.observation_shape) # (height, width)
-print(env.extras_shape) # (0, )
+import marlenv
+
+gym_env = marlenv.make("CartPole-v1", seed=25)
 
-env = Builder(env).time_limit(25).build()
-print(env.observation_shape) # (height, width)
-print(env.extras_shape) # (1, )
+from marlenv.adapters import SMAC
+smac_env = SMAC("3m", debug=True, difficulty="9")
+
+from pettingzoo.sisl import pursuit_v4
+from marlenv.adapters import PettingZoo
+env = PettingZoo(pursuit_v4.parallel_env())
 ```
 
-# Creating a new environment
-If you want to create a new environment, you can simply create a class that inherits from `MARLEnv`. If you want to create a wrapper around an existing `MARLEnv`, you probably want to subclass `RLEnvWrapper` which implements a default behaviour for every method.
+## Designing a custom environment
+Create a custom environment by inheriting from `MARLEnv` and implementing `reset`, `step`, `get_observation`, and `get_state`.
+
+```python
+import numpy as np
+from marlenv import MARLEnv, DiscreteSpace, Observation, State, Step
+
+class CustomEnv(MARLEnv[DiscreteSpace]):
+    def __init__(self):
+        super().__init__(
+            n_agents=3,
+            action_space=DiscreteSpace.action(5).repeat(3),
+            observation_shape=(4,),
+            state_shape=(2,),
+        )
+        self.t = 0
+
+    def reset(self):
+        self.t = 0
+        return self.get_observation(), self.get_state()
+
+    def step(self, action):
+        self.t += 1
+        return Step(self.get_observation(), self.get_state(), reward=0.0, done=False)
+
+    def get_observation(self):
+        return Observation(np.zeros((3, 4), dtype=np.float32), self.available_actions())
+
+    def get_state(self):
+        return State(np.array([self.t, 0], dtype=np.float32))
+```
 """
 
 from importlib.metadata import version, PackageNotFoundError

marlenv/adapters/__init__.py

@@ -1,3 +1,18 @@
+"""
+Adapters for external RL libraries.
+
+This submodule provides optional wrappers that normalize third-party APIs into
+`MARLEnv`. Adapters are imported lazily via `try/except` so the base install
+remains lightweight. The availability flags (`HAS_GYM`, `HAS_PETTINGZOO`,
+`HAS_SMAC`) reflect whether the corresponding extra was installed.
+
+Install extras to enable adapters with `uv` or `pip`:
+- `multi-agent-rlenv[all]` for all optional dependencies
+- `multi-agent-rlenv[gym]` for Gymnasium
+- `multi-agent-rlenv[pettingzoo]` for PettingZoo
+- `multi-agent-rlenv[smac]` for SMAC
+"""
+
 from .pymarl_adapter import PymarlAdapter
 from marlenv.utils import dummy_function
 

marlenv/adapters/smac_adapter.py

@@ -3,7 +3,7 @@ from typing import overload
 
 import numpy as np
 import numpy.typing as npt
-from smac.env import StarCraft2Env  # pyright: ignore[reportMissingImports]
+from smacv2.env import StarCraft2Env
 
 from marlenv.models import MARLEnv, Observation, State, Step, MultiDiscreteSpace, DiscreteSpace
 

marlenv/catalog/__init__.py

@@ -1,3 +1,24 @@
+"""
+Environment catalog for `marlenv`.
+
+This submodule exposes curated environments and provides lazy imports for optional
+dependencies to keep the base install lightweight. Use the catalog to construct
+environments without importing their packages directly.
+
+Examples:
+```python
+from marlenv import catalog
+
+env1 = catalog.DeepSea(mex_depth=5)
+env2 = catalog.CoordinatedGrid()
+env3 = catalog.connect_n()(width=7, height=6, n_to_connect=4)
+env4 = catalog.smac()("3m")
+```
+
+Optional entries such as `smac`, `lle`, and `overcooked` require installing their
+corresponding extras (e.g., `marlenv[smac]`, `marlenv[lle]`, `marlenv[overcooked]`).
+"""
+
 from .deepsea import DeepSea
 from .matrix_game import MatrixGame
 from .coordinated_grid import CoordinatedGrid

marlenv/models/__init__.py

@@ -1,3 +1,14 @@
+"""
+Core data models for the `marlenv` API.
+
+This package defines the typed containers and interfaces shared across adapters,
+wrappers, and environments:
+- `MARLEnv`: the abstract environment contract.
+- `Observation` / `State`: structured inputs to agents and state tracking.
+- `Step` / `Transition` / `Episode`: execution results and replayable logs.
+- `Space` variants: action/reward space definitions.
+"""
+
 from .spaces import DiscreteSpace, ContinuousSpace, MultiDiscreteSpace, Space
 from .observation import Observation
 from .step import Step

marlenv/models/step.py

@@ -9,6 +9,15 @@ from .state import State
 
 @dataclass
 class Step:
+    """
+    The result of performing a step in the environment:
+        - the new observation
+        - the new state
+        - the reward received for the step performed
+        - whether the episode is done or truncated
+        - some info (mainly for logging purposes)
+    """
+
     obs: Observation
     """The new observation (1 per agent) of the environment resulting from the agent's action."""
     state: State

multi_agent_rlenv-3.7.4.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: multi-agent-rlenv
+Version: 3.7.4
+Summary: A strongly typed Multi-Agent Reinforcement Learning framework
+Project-URL: repository, https://github.com/yamoling/multi-agent-rlenv
+Author-email: Yannick Molinghen <yannick.molinghen@ulb.be>
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <4,>=3.12
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: opencv-python>=4.0
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: all
+Requires-Dist: gymnasium>0.29.1; extra == 'all'
+Requires-Dist: laser-learning-environment>=2.6.1; extra == 'all'
+Requires-Dist: overcooked>=0.1.0; extra == 'all'
+Requires-Dist: pettingzoo>=1.20; extra == 'all'
+Requires-Dist: pymunk>=6.0; extra == 'all'
+Requires-Dist: scipy>=1.10; extra == 'all'
+Requires-Dist: smacv2; extra == 'all'
+Requires-Dist: torch>=2.0; extra == 'all'
+Provides-Extra: gym
+Requires-Dist: gymnasium>=0.29.1; extra == 'gym'
+Provides-Extra: lle
+Requires-Dist: laser-learning-environment>=2.6.1; extra == 'lle'
+Provides-Extra: overcooked
+Requires-Dist: overcooked>=0.1.0; extra == 'overcooked'
+Provides-Extra: pettingzoo
+Requires-Dist: pettingzoo>=1.20; extra == 'pettingzoo'
+Requires-Dist: pymunk>=6.0; extra == 'pettingzoo'
+Requires-Dist: scipy>=1.10; extra == 'pettingzoo'
+Provides-Extra: smac
+Requires-Dist: pysc2; extra == 'smac'
+Requires-Dist: smacv2; extra == 'smac'
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# `marlenv` - A unified framework for muti-agent reinforcement learning
+**Documentation: [https://yamoling.github.io/multi-agent-rlenv](https://yamoling.github.io/multi-agent-rlenv)**
+
+`marlenv` is a strongly typed library for multi-agent and multi-objective reinforcement learning.
+
+Install the library with
+```sh
+$ pip install multi-agent-rlenv      # Basics
+$ pip install multi-agent-rlenv[all] # With all optional dependecies
+$ pip install multi-agent-rlenv[smac,overcooked] # Only SMACv2 & Overcooked
+```
+
+It aims to provide a simple and consistent interface for reinforcement learning environments by providing abstraction models such as `Observation`s or `Episode`s. `marlenv` provides adapters for popular libraries such as `gym` or `pettingzoo` and provides utility wrappers to add functionalities such as video recording or limiting the number of steps.
+
+Almost every class is a dataclass to enable seemless serialiation with the `orjson` library.
+
+# Fundamentals
+## States & Observations
+`MARLEnv.reset()` returns a pair of `(Observation, State)` and `MARLEnv.step()` returns a `Step`.
+
+- `Observation` contains:
+  - `data`: shape `[n_agents, *observation_shape]`
+  - `available_actions`: boolean mask `[n_agents, n_actions]`
+  - `extras`: extra features per agent (default shape `(n_agents, 0)`)
+- `State` represents the environment state and can also carry `extras`.
+- `Step` bundles `obs`, `state`, `reward`, `done`, `truncated`, and `info`.
+
+Rewards are stored as `np.float32` arrays. Multi-objective envs use reward vectors with `reward_space.size > 1`.
+
+## Extras
+Extras are auxiliary features appended by wrappers (agent id, last action, time ratio, available actions, ...).
+Wrappers that add extras must update both `extras_shape` and `extras_meanings` so downstream users can interpret them.
+`State` extras should stay in sync with `Observation` extras when applicable.
+
+# Environment catalog
+`marlenv.catalog` exposes curated environments and lazily imports optional dependencies.
+
+```python
+from marlenv import catalog
+
+env1 = catalog.overcooked().from_layout("scenario4")
+env2 = catalog.lle().level(6)
+env3 = catalog.DeepSea(mex_depth=5)
+```
+
+Catalog entries require their corresponding extras at install time (e.g., `marlenv[overcooked]`, `marlenv[lle]`).
+
+# Wrappers & builders
+Wrappers are composable through `RLEnvWrapper` and can be chained via `Builder` for fluent configuration.
+
+```python
+from marlenv import Builder
+from marlenv.adapters import SMAC
+
+env = (
+    Builder(SMAC("3m"))
+    .agent_id()
+    .time_limit(20)
+    .available_actions()
+    .build()
+)
+```
+
+Common wrappers include time limits, delayed rewards, masking available actions, and video recording.
+
+# Using the library
+## Adapters for existing libraries
+Adapters normalize external APIs into `MARLEnv`:
+
+```python
+import marlenv
+
+gym_env = marlenv.make("CartPole-v1", seed=25)
+
+from marlenv.adapters import SMAC
+smac_env = SMAC("3m", debug=True, difficulty="9")
+
+from pettingzoo.sisl import pursuit_v4
+from marlenv.adapters import PettingZoo
+env = PettingZoo(pursuit_v4.parallel_env())
+```
+
+## Designing a custom environment
+Create a custom environment by inheriting from `MARLEnv` and implementing `reset`, `step`, `get_observation`, and `get_state`.
+
+```python
+import numpy as np
+from marlenv import MARLEnv, DiscreteSpace, Observation, State, Step
+
+class CustomEnv(MARLEnv[DiscreteSpace]):
+    def __init__(self):
+        super().__init__(
+            n_agents=3,
+            action_space=DiscreteSpace.action(5).repeat(3),
+            observation_shape=(4,),
+            state_shape=(2,),
+        )
+        self.t = 0
+
+    def reset(self):
+        self.t = 0
+        return self.get_observation(), self.get_state()
+
+    def step(self, action):
+        self.t += 1
+        return Step(self.get_observation(), self.get_state(), reward=0.0, done=False)
+
+    def get_observation(self):
+        return Observation(np.zeros((3, 4), dtype=np.float32), self.available_actions())
+
+    def get_state(self):
+        return State(np.array([self.t, 0], dtype=np.float32))
+```
+
+# Related projects
+- MARL: Collection of multi-agent reinforcement learning algorithms based on `marlenv` [https://github.com/yamoling/marl](https://github.com/yamoling/marl)
+- Laser Learning Environment: a multi-agent gridworld that leverages `marlenv`'s capabilities [https://pypi.org/project/laser-learning-environment/](https://pypi.org/project/laser-learning-environment/)

{multi_agent_rlenv-3.7.2.dist-info → multi_agent_rlenv-3.7.4.dist-info}/RECORD

@@ -1,15 +1,15 @@
-marlenv/__init__.py,sha256=mxpDjgGSc5eq67w1PIKat0UWkAg9A7VjchWwtzzsvW8,3881
+marlenv/__init__.py,sha256=5HWxgfUTA1l-uGpvwEt1e8KxRINteqXPKshY-PItlxI,4875
 marlenv/env_builder.py,sha256=RUMFvW7dAJtHMLm8-oPVpjBefDtNliZtjlHci97Xj-Q,3874
 marlenv/env_pool.py,sha256=mJhJUROX9k2A2njwnUOBl2EAuhotksQMugH_Zydg1IU,951
 marlenv/exceptions.py,sha256=gJUC_2rVAvOfK_ypVFc7Myh-pIfSU3To38VBVS_0rZA,1179
 marlenv/mock_env.py,sha256=rvl4QAn046HM79IMMiAj1Aoy3_GBSNBBR1_9fHPutR8,4682
 marlenv/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-marlenv/adapters/__init__.py,sha256=G-PwyGDymdAMFWtCpnlHkHQuSE40Q8bv_-yQ7gVcbbM,600
+marlenv/adapters/__init__.py,sha256=1APqbpC2JmVgMhexdb8FbTifxFs7_mjqrcEkQquug8k,1182
 marlenv/adapters/gym_adapter.py,sha256=DXQ1czcvRoL9hTwcVzfMyXArZeVIHP1gAKqZJO87y7Y,3065
 marlenv/adapters/pettingzoo_adapter.py,sha256=UzSUdP4EUJOt49AB7H45ToA8rUkGmPQgrJKegvK86og,2877
 marlenv/adapters/pymarl_adapter.py,sha256=2s7EY31s1hrml3q-BBaXo_eDMXTjkebozZPvzsgrb9c,3353
-marlenv/adapters/smac_adapter.py,sha256=OIR0_do9KavLlZ2f1YQNJwhl_yLCa6SVvCrp78hwU20,8279
-marlenv/catalog/__init__.py,sha256=l9_lvqpV2wKKMYDrStbW93WGEBDhGw6KjgbZsOcLKx0,570
+marlenv/adapters/smac_adapter.py,sha256=HXECjK4hs4c1zAr1qWUChrJZdcvsu-OhnDovS0_u9Z0,8240
+marlenv/catalog/__init__.py,sha256=YK8w6wUleIZkO85f_5e0Dj_7HEqX3X0u1CgXeTX6IE0,1215
 marlenv/catalog/coordinated_grid.py,sha256=Kq5UzG9rr5gYRO0QWFCmKmO56JIzgIR19an9_pvypJU,4997
 marlenv/catalog/deepsea.py,sha256=yTyvskWZiAZem11L8cZwHedBIDQ4EAxE2IaUKrjKL2U,2413
 marlenv/catalog/matrix_game.py,sha256=zkErnh6ZIa1kBryYMVLw-jeMCd2AJ-BlP2yROxpbb0w,1519
@@ -17,13 +17,13 @@ marlenv/catalog/two_steps.py,sha256=lI-q4-Q8283QZTjY0wk7OfXWB6Ln-lquYUjHyT4URi4,
 marlenv/catalog/connectn/__init__.py,sha256=BKfM0ZofMK6zqGURi2bzILyNFfYjfbZpKTs5ikKiJAk,195
 marlenv/catalog/connectn/board.py,sha256=GVcFA1OJgLUmQoTIfOO9M7nL9dFv-4T3tGrVsP15zyg,6124
 marlenv/catalog/connectn/env.py,sha256=Ot5vfAbzS6eRe3-nLW_AkhEH7F1WVvv4_odoxZU7HNg,1905
-marlenv/models/__init__.py,sha256=uihmRs71Gg5z7Bvau_xtaQVg7xEtX8sTzi74bIHL5P0,443
+marlenv/models/__init__.py,sha256=M6nXAZJWpTdncWm-4wN5V05waUAp4KJ007efw-xbMDQ,854
 marlenv/models/env.py,sha256=BG1iVHxGD_p827mF0ewyOBn6wU2gtFsHLW1b4UtW-V0,7841
 marlenv/models/episode.py,sha256=zsyxsW4LIioPKyY4DZKn64A31e5ZvlwOf3HIGuRUzhs,13531
 marlenv/models/observation.py,sha256=6uY2h0zHBm6g1ECzD8jZLXuSzuuX-U60QW0E_b4qPuc,3569
 marlenv/models/spaces.py,sha256=d_aIPWwPdaOWZeNRUUdzSiDxs9XQb9itPnrE_EyhhfQ,7810
 marlenv/models/state.py,sha256=JvCXwf0l7L2UMHkvYp-WM_aDegJ-hePpQI2yiUw6X_g,2099
-marlenv/models/step.py,sha256=00PhD_ccdCIYAY1SVJdJU91weU0Y_tNIJwK16TN_53I,3056
+marlenv/models/step.py,sha256=xg_7iPyOvahsZ5k7L6On7E_j0dUDEu0h6eyqFsWGR-M,3337
 marlenv/models/transition.py,sha256=UkJVRNxZoyRkjE7YmKtUf_4xA7cOEh20O60dTldbvys,5070
 marlenv/utils/__init__.py,sha256=ky5mz_T7EF65YNaEN1UDCUYZVlz7hFyKResgIJlE_1Q,462
 marlenv/utils/cached_property_collector.py,sha256=IOjbr61f0DqLhcidXKrl7MhN1BOEGiTzCANIKQCxaF0,600
@@ -45,7 +45,7 @@ marlenv/wrappers/rlenv_wrapper.py,sha256=iFSQsDMkUUbQJKEO8l6SosNi-eOUVSh4pIJVu7a
 marlenv/wrappers/state_counter.py,sha256=QmEMb55vOnK-VJuvKsDIIBgcNRsHuovqgpK2pcCY7sA,1211
 marlenv/wrappers/time_limit.py,sha256=HctKeiepPQ2NAIa208SnvknioSkRIuUQ4X-Xhf_XTs0,3974
 marlenv/wrappers/video_recorder.py,sha256=mtWcqaYNCu-zjVXvpa8DJe3_062tpK_TChOu-Xyxs3s,2533
-multi_agent_rlenv-3.7.2.dist-info/METADATA,sha256=loGAqI0-dvtGJEM6txWjaP00TImesivli2RI0Pd2OK0,5751
-multi_agent_rlenv-3.7.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-multi_agent_rlenv-3.7.2.dist-info/licenses/LICENSE,sha256=_eeiGVoIJ7kYt6l1zbIvSBQppTnw0mjnYk1lQ4FxEjE,1074
-multi_agent_rlenv-3.7.2.dist-info/RECORD,,
+multi_agent_rlenv-3.7.4.dist-info/METADATA,sha256=UKdalybcSN3nvAVbJtZXgQFr9R3AEjKq0E3OFvlM3ZE,5971
+multi_agent_rlenv-3.7.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+multi_agent_rlenv-3.7.4.dist-info/licenses/LICENSE,sha256=_eeiGVoIJ7kYt6l1zbIvSBQppTnw0mjnYk1lQ4FxEjE,1074
+multi_agent_rlenv-3.7.4.dist-info/RECORD,,

multi_agent_rlenv-3.7.2.dist-info/METADATA

@@ -1,144 +0,0 @@
-Metadata-Version: 2.4
-Name: multi-agent-rlenv
-Version: 3.7.2
-Summary: A strongly typed Multi-Agent Reinforcement Learning framework
-Project-URL: repository, https://github.com/yamoling/multi-agent-rlenv
-Author-email: Yannick Molinghen <yannick.molinghen@ulb.be>
-License-File: LICENSE
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Requires-Python: <4,>=3.12
-Requires-Dist: numpy>=2.0.0
-Requires-Dist: opencv-python>=4.0
-Requires-Dist: typing-extensions>=4.0
-Provides-Extra: all
-Requires-Dist: gymnasium>0.29.1; extra == 'all'
-Requires-Dist: laser-learning-environment>=2.6.1; extra == 'all'
-Requires-Dist: overcooked>=0.1.0; extra == 'all'
-Requires-Dist: pettingzoo>=1.20; extra == 'all'
-Requires-Dist: pymunk>=6.0; extra == 'all'
-Requires-Dist: pysc2; extra == 'all'
-Requires-Dist: scipy>=1.10; extra == 'all'
-Requires-Dist: smac; extra == 'all'
-Requires-Dist: torch>=2.0; extra == 'all'
-Provides-Extra: gym
-Requires-Dist: gymnasium>=0.29.1; extra == 'gym'
-Provides-Extra: lle
-Requires-Dist: laser-learning-environment>=2.6.1; extra == 'lle'
-Provides-Extra: overcooked
-Requires-Dist: overcooked>=0.1.0; extra == 'overcooked'
-Provides-Extra: pettingzoo
-Requires-Dist: pettingzoo>=1.20; extra == 'pettingzoo'
-Requires-Dist: pymunk>=6.0; extra == 'pettingzoo'
-Requires-Dist: scipy>=1.10; extra == 'pettingzoo'
-Provides-Extra: smac
-Requires-Dist: pysc2; extra == 'smac'
-Requires-Dist: smac; extra == 'smac'
-Provides-Extra: torch
-Requires-Dist: torch>=2.0; extra == 'torch'
-Description-Content-Type: text/markdown
-
-# `marlenv` - A unified framework for muti-agent reinforcement learning
-**Documentation: [https://yamoling.github.io/multi-agent-rlenv](https://yamoling.github.io/multi-agent-rlenv)**
-
-The objective of `marlenv` is to provide a common (typed) interface for many different reinforcement learning environments.
-
-As such, `marlenv` provides high level abstractions of RL concepts such as `Observation`s or `Transition`s that are commonly represented as mere (confusing) lists or tuples.
-
-## Installation
-Install with you preferred package manager (`uv`, `pip`, `poetry`, ...):
-```bash
-$ pip install marlenv[all] # Enable all features
-$ pip install marlenv      # Basic installation
-```
-
-There are multiple optional dependencies if you want to support specific libraries and environments. Available options are:
-- `smac` for StarCraft II environments
-- `gym` for OpenAI Gym environments
-- `pettingzoo` for PettingZoo environments
-- `overcooked` for Overcooked environments
-
-Install them with:
-```bash
-$ pip install marlenv[smac] # Install SMAC
-$ pip install marlenv[gym,smac]  # Install Gym & smac support
-```
-
-## Using the `marlenv` environment catalog
-Some environments are registered in the `marlenv` and can be easily instantiated via its catalog. 
-
-```python
-from marlenv import catalog
-
-env1 = catalog.Overcooked.from_layout("scenario4")
-env2 = catalog.LLE.level(6)
-env3 = catalog.DeepSea(mex_depth=5)
-```
-Note that using the catalog requires the corresponding environment package to be installed. For instance you need to install the `laser-learning-environment` package to use `catalog.LLE`, which can be done by using the corresponding feature when at installation as shown below.
-```bash
-pip install multi-agent-rlenv[lle]
-```
-
-
-## Using `marlenv` with existing libraries
-`marlenv` provides adapters from most popular libraries to unify them under a single interface. Namely, `marlenv` supports `smac`, `gymnasium` and `pettingzoo`.
-
-```python
-import marlenv
-
-# You can instanciate gymnasium environments directly via their registry ID
-gym_env = marlenv.make("CartPole-v1", seed=25)
-
-# You can seemlessly instanciate a SMAC environment and directly pass your required arguments
-from marlenv.adapters import SMAC
-smac_env = SMAC("3m", debug=True, difficulty="9")
-
-# pettingzoo is also supported
-from pettingzoo.sisl import pursuit_v4
-from marlenv.adapters import PettingZoo
-pz_env = PettingZoo(pursuit_v4.parallel_env())
-```
-
-
-## Designing custom environments
-You can create your own custom environment by inheriting from the `RLEnv` class. The below example illustrates a gridworld with a discrete action space. Note that other methods such as `step` or `render` must also be implemented.
-```python
-import numpy as np
-from marlenv import RLEnv, DiscreteActionSpace, Observation
-
-N_AGENTS = 3
-N_ACTIONS = 5
-
-class CustomEnv(MARLEnv[DiscreteActionSpace]):
-    def __init__(self, width: int, height: int):
-        super().__init__(
-            action_space=DiscreteActionSpace(N_AGENTS, N_ACTIONS),
-            observation_shape=(height, width),
-            state_shape=(1,),
-        )
-        self.time = 0
-
-    def reset(self) -> Observation:
-        self.time = 0
-        ...
-        return obs
-
-    def get_state(self):
-        return np.array([self.time])
-```
-
-## Useful wrappers
-`marlenv` comes with multiple common environment wrappers, check the documentation for a complete list. The preferred way of using the wrappers is through a `marlenv.Builder`. The below example shows how to add a time limit (in number of steps) and an agent id to the observations of a SMAC environment.
-
-```python
-from marlenv import Builder
-from marlenv.adapters import SMAC
-
-env = Builder(SMAC("3m")).agent_id().time_limit(20).build()
-print(env.extras_shape) # -> (4, ) because there are 3 agents and the time counter
-```
-
-
-# Related projects
-- MARL: Collection of multi-agent reinforcement learning algorithms based on `marlenv` [https://github.com/yamoling/marl](https://github.com/yamoling/marl)
-- Laser Learning Environment: a multi-agent gridworld that leverages `marlenv`'s capabilities [https://pypi.org/project/laser-learning-environment/](https://pypi.org/project/laser-learning-environment/)