multi-agent-rlenv 3.3.0__tar.gz → 3.3.1__tar.gz

{multi_agent_rlenv-3.3.0 → multi_agent_rlenv-3.3.1}/.github/workflows/ci.yaml

@@ -21,8 +21,8 @@ jobs:
       matrix:
         os:
           - ubuntu-latest
-          - windows-latest
           - macOS-latest
+          - windows-latest
         target:
           - x86_64
           - aarch64
@@ -43,16 +43,16 @@ jobs:
       - name: Install uv
         uses: yezz123/setup-uv@v4
         with:
-          uv-version: 0.5.6
+          uv-version: 0.6.4
       - name: Install dependencies and run pytest
         run: |
-          uv sync
+          uv sync --extra overcooked --extra gym --extra pettingzoo
           uv run pytest
 
   build:
     name: 📦 Build package
     if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
-    needs: test
+    needs: [test]
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4

{multi_agent_rlenv-3.3.0 → multi_agent_rlenv-3.3.1}/.github/workflows/docs.yaml

@@ -4,7 +4,7 @@ name: Deploy static content to Pages
 on:
   # Runs on pushes targeting the default branch
   push:
-    branches: ["main"]
+    branches: ["main", "master"]
     # Only deploy the documentation on new version tags
     tags:
         - 'v[0-9]+.[0-9]+.[0-9]+'

multi_agent_rlenv-3.3.0/README.md → multi_agent_rlenv-3.3.1/PKG-INFO

@@ -1,8 +1,65 @@
-# `marlenv` - A unified interface for muti-agent reinforcement learning
+Metadata-Version: 2.4
+Name: multi-agent-rlenv
+Version: 3.3.1
+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.10
+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: overcooked-ai; 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'
+Provides-Extra: gym
+Requires-Dist: gymnasium>=0.29.1; extra == 'gym'
+Provides-Extra: overcooked
+Requires-Dist: overcooked-ai>=1.1.0; extra == 'overcooked'
+Requires-Dist: scipy>=1.10; 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'
+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 `marlenv` with existing libraries
 `marlenv` unifies multiple popular libraries under a single interface. Namely, `marlenv` supports `smac`, `gymnasium` and `pettingzoo`.
 
@@ -32,7 +89,7 @@ from marlenv import RLEnv, DiscreteActionSpace, Observation
 N_AGENTS = 3
 N_ACTIONS = 5
 
-class CustomEnv(RLEnv[DiscreteActionSpace]):
+class CustomEnv(MARLEnv[DiscreteActionSpace]):
     def __init__(self, width: int, height: int):
         super().__init__(
             action_space=DiscreteActionSpace(N_AGENTS, N_ACTIONS),

multi_agent_rlenv-3.3.0/PKG-INFO → multi_agent_rlenv-3.3.1/README.md

@@ -1,23 +1,30 @@
-Metadata-Version: 2.4
-Name: multi-agent-rlenv
-Version: 3.3.0
-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.10
-Requires-Dist: gymnasium>=0.29.1
-Requires-Dist: numpy>=2.0.0
-Requires-Dist: opencv-python>=4.10.0.84
-Description-Content-Type: text/markdown
-
-# `marlenv` - A unified interface for muti-agent reinforcement learning
+# `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 `marlenv` with existing libraries
 `marlenv` unifies multiple popular libraries under a single interface. Namely, `marlenv` supports `smac`, `gymnasium` and `pettingzoo`.
 
@@ -47,7 +54,7 @@ from marlenv import RLEnv, DiscreteActionSpace, Observation
 N_AGENTS = 3
 N_ACTIONS = 5
 
-class CustomEnv(RLEnv[DiscreteActionSpace]):
+class CustomEnv(MARLEnv[DiscreteActionSpace]):
     def __init__(self, width: int, height: int):
         super().__init__(
             action_space=DiscreteActionSpace(N_AGENTS, N_ACTIONS),

{multi_agent_rlenv-3.3.0 → multi_agent_rlenv-3.3.1}/pyproject.toml

@@ -7,13 +7,28 @@ authors = [
 ]
 readme = "README.md"
 requires-python = ">=3.10, <4"
-dependencies = ["numpy>=2.0.0", "opencv-python>=4.10.0.84", "gymnasium>=0.29.1"]
 urls = { "repository" = "https://github.com/yamoling/multi-agent-rlenv" }
 classifiers = [
     "Programming Language :: Python :: 3",
     "Operating System :: OS Independent",
 ]
 
+dependencies = ["numpy>=2.0.0", "opencv-python>=4.0", "typing_extensions>=4.0"]
+
+[project.optional-dependencies]
+gym = ["gymnasium>=0.29.1"]
+smac = ["smac", "pysc2"]
+pettingzoo = ["pettingzoo>=1.20", "pymunk>=6.0", "scipy>=1.10"]
+overcooked = ["overcooked-ai>=1.1.0", "scipy>=1.10"]
+all = [
+    "gymnasium>0.29.1",
+    "pettingzoo>=1.20",
+    "overcooked-ai",
+    "smac",
+    "pysc2",
+    "pymunk>=6.0",
+    "scipy>=1.10",
+]
 
 [build-system]
 requires = ["hatchling"]
@@ -35,5 +50,10 @@ pythonpath = "src"
 # Ignore deprecation warnings caused by SMAC
 filterwarnings = "ignore::DeprecationWarning"
 
+[tool.uv.sources]
+smac = { git = "https://github.com/oxwhirl/smac.git" }
+pysc2 = { git = "https://github.com/google-deepmind/pysc2.git" }
+
+
 [dependency-groups]
 dev = ["orjson>=3.10.12", "pdoc>=15.0.1", "pytest>=8.3.2"]

{multi_agent_rlenv-3.3.0 → multi_agent_rlenv-3.3.1}/src/marlenv/__init__.py

@@ -62,7 +62,7 @@ print(env.extras_shape) # (1, )
 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.
 """
 
-__version__ = "3.3.0"
+__version__ = "3.3.1"
 
 from . import models
 from . import wrappers

multi_agent_rlenv-3.3.1/src/marlenv/adapters/__init__.py

@@ -0,0 +1,42 @@
+from importlib.util import find_spec
+from .pymarl_adapter import PymarlAdapter
+
+HAS_GYM = False
+if find_spec("gymnasium") is not None:
+    from .gym_adapter import Gym
+
+    HAS_GYM = True
+
+HAS_PETTINGZOO = False
+if find_spec("pettingzoo") is not None:
+    from .pettingzoo_adapter import PettingZoo
+
+    HAS_PETTINGZOO = True
+
+HAS_SMAC = False
+if find_spec("smac") is not None:
+    from .smac_adapter import SMAC
+
+    HAS_SMAC = True
+
+HAS_OVERCOOKED = False
+if find_spec("overcooked_ai_py.mdp") is not None:
+    import numpy
+
+    # Overcooked assumes a version of numpy <2.0 where np.Inf is available.
+    setattr(numpy, "Inf", numpy.inf)
+    from .overcooked_adapter import Overcooked
+
+    HAS_OVERCOOKED = True
+
+__all__ = [
+    "PymarlAdapter",
+    "Gym",
+    "PettingZoo",
+    "SMAC",
+    "Overcooked",
+    "HAS_GYM",
+    "HAS_PETTINGZOO",
+    "HAS_SMAC",
+    "HAS_OVERCOOKED",
+]

{multi_agent_rlenv-3.3.0 → multi_agent_rlenv-3.3.1}/src/marlenv/adapters/overcooked_adapter.py

@@ -1,41 +1,71 @@
-import numpy as np
-import pygame
-import cv2
 import sys
-from marlenv.models import MARLEnv, State, Observation, Step, DiscreteActionSpace
+from dataclasses import dataclass
 from typing import Literal, Sequence
+
+import cv2
+import numpy as np
 import numpy.typing as npt
-from overcooked_ai_py.mdp.overcooked_mdp import OvercookedGridworld, Action
+import pygame
+from marlenv.models import ContinuousSpace, DiscreteActionSpace, MARLEnv, Observation, State, Step
+
 from overcooked_ai_py.mdp.overcooked_env import OvercookedEnv
+from overcooked_ai_py.mdp.overcooked_mdp import Action, OvercookedGridworld, OvercookedState
 from overcooked_ai_py.visualization.state_visualizer import StateVisualizer
-from dataclasses import dataclass
 
 
 @dataclass
 class Overcooked(MARLEnv[Sequence[int] | npt.NDArray, DiscreteActionSpace]):
+    horizon: int
+
     def __init__(self, oenv: OvercookedEnv):
         self._oenv = oenv
         assert isinstance(oenv.mdp, OvercookedGridworld)
         self._mdp = oenv.mdp
         self.visualizer = StateVisualizer()
+        shape = tuple(int(s) for s in self._mdp.get_lossless_state_encoding_shape())
+        shape = (shape[2], shape[0], shape[1])
         super().__init__(
-            action_space=DiscreteActionSpace(n_agents=self._mdp.num_players, n_actions=Action.NUM_ACTIONS),
-            observation_shape=(1,),
-            state_shape=(1,),
+            action_space=DiscreteActionSpace(
+                n_agents=self._mdp.num_players,
+                n_actions=Action.NUM_ACTIONS,
+                action_names=[Action.ACTION_TO_CHAR[a] for a in Action.ALL_ACTIONS],
+            ),
+            observation_shape=shape,
+            extras_shape=(1,),
+            extras_meanings=["timestep"],
+            state_shape=shape,
+            state_extra_shape=(1,),
+            reward_space=ContinuousSpace.from_shape(1),
         )
+        self.horizon = int(self._oenv.horizon)
+
+    @property
+    def state(self) -> OvercookedState:
+        """Current state of the environment"""
+        return self._oenv.state
+
+    def set_state(self, state: State):
+        raise NotImplementedError("Not yet implemented")
+
+    @property
+    def time_step(self):
+        return self.state.timestep
 
     def _state_data(self):
-        state = self._oenv.state
-        state = np.array(self._mdp.lossless_state_encoding(state))
+        state = np.array(self._mdp.lossless_state_encoding(self.state))
         # Use axes (agents, channels, height, width) instead of (agents, height, width, channels)
         state = np.transpose(state, (0, 3, 1, 2))
         return state
 
     def get_state(self):
-        return State(self._state_data())
+        return State(self._state_data()[0], np.array([self.time_step / self.horizon]))
 
     def get_observation(self) -> Observation:
-        return Observation(self._state_data(), self.available_actions())
+        return Observation(
+            data=self._state_data(),
+            available_actions=self.available_actions(),
+            extras=np.array([[self.time_step / self.horizon]] * self.n_agents),
+        )
 
     def available_actions(self):
         available_actions = np.full((self.n_agents, self.n_actions), False)

{multi_agent_rlenv-3.3.0 → multi_agent_rlenv-3.3.1}/src/marlenv/env_builder.py

@@ -1,32 +1,27 @@
 from dataclasses import dataclass
 from typing import Generic, Literal, Optional, TypeVar, overload
-
 import numpy as np
 import numpy.typing as npt
 
 from . import wrappers
+from marlenv import adapters
 from .models import ActionSpace, MARLEnv
-from .adapters import PettingZoo
 
 A = TypeVar("A")
 AS = TypeVar("AS", bound=ActionSpace)
 
-try:
+if adapters.HAS_PETTINGZOO:
+    from .adapters import PettingZoo
     from pettingzoo import ParallelEnv
 
     @overload
-    def make(
-        env: ParallelEnv,
-    ) -> PettingZoo: ...
-
-    HAS_PETTINGZOO = True
-except ImportError:
-    HAS_PETTINGZOO = False
+    def make(env: ParallelEnv) -> PettingZoo: ...
 
 
-try:
-    from gymnasium import Env
+if adapters.HAS_GYM:
     from .adapters import Gym
+    from gymnasium import Env
+    import gymnasium
 
     @overload
     def make(env: Env) -> Gym: ...
@@ -37,25 +32,21 @@ try:
         Make an RLEnv from the `gymnasium` registry (e.g: "CartPole-v1").
         """
 
-    HAS_GYM = True
-except ImportError:
-    HAS_GYM = False
 
-try:
-    from smac.env import StarCraft2Env
+if adapters.HAS_SMAC:
     from .adapters import SMAC
+    from smac.env import StarCraft2Env
 
     @overload
     def make(env: StarCraft2Env) -> SMAC: ...
 
-    HAS_SMAC = True
-except ImportError:
-    HAS_SMAC = False
 
+if adapters.HAS_OVERCOOKED:
+    from .adapters import Overcooked
+    from overcooked_ai_py.mdp.overcooked_env import OvercookedEnv
 
-@overload
-def make(env: MARLEnv[A, AS]) -> MARLEnv[A, AS]:
-    """Why would you do this ?"""
+    @overload
+    def make(env: OvercookedEnv) -> Overcooked: ...
 
 
 def make(env, **kwargs):
@@ -64,32 +55,18 @@ def make(env, **kwargs):
         case MARLEnv():
             return env
         case str(env_id):
-            try:
-                import gymnasium
-            except ImportError:
-                raise ImportError("Gymnasium is not installed !")
-            from marlenv.adapters import Gym
-
-            gym_env = gymnasium.make(env_id, render_mode="rgb_array", **kwargs)
-            return Gym(gym_env)
-
-    try:
-        from marlenv.adapters import PettingZoo
-
-        if isinstance(env, ParallelEnv):
-            return PettingZoo(env)
-    except ImportError:
-        pass
-    try:
-        from smac.env import StarCraft2Env
-
-        from marlenv.adapters import SMAC
-
-        if isinstance(env, StarCraft2Env):
-            return SMAC(env)
-    except ImportError:
-        pass
-
+            if adapters.HAS_GYM:
+                gym_env = gymnasium.make(env_id, render_mode="rgb_array", **kwargs)
+                return Gym(gym_env)
+
+    if adapters.HAS_PETTINGZOO and isinstance(env, ParallelEnv):
+        return PettingZoo(env)  # type: ignore
+    if adapters.HAS_SMAC and isinstance(env, StarCraft2Env):
+        return SMAC(env)
+    if adapters.HAS_OVERCOOKED and isinstance(env, OvercookedEnv):
+        return Overcooked(env)  # type: ignore
+    if adapters.HAS_GYM and isinstance(env, Env):
+        return Gym(env)
     raise ValueError(f"Unknown environment type: {type(env)}")
 
 

{multi_agent_rlenv-3.3.0 → multi_agent_rlenv-3.3.1}/src/marlenv/env_pool.py

@@ -1,6 +1,5 @@
 from typing import Sequence
 from dataclasses import dataclass
-import numpy as np
 import numpy.typing as npt
 from typing_extensions import TypeVar
 import random

{multi_agent_rlenv-3.3.0 → multi_agent_rlenv-3.3.1}/src/marlenv/models/observation.py

@@ -58,9 +58,14 @@ class Observation:
             available_actions=self.available_actions[agent_id],
         )
 
+    @property
+    def shape(self) -> tuple[int, ...]:
+        """The individual shape of the observation data"""
+        return self.data[0].shape
+
     @property
     def extras_shape(self) -> tuple[int, ...]:
-        """The shape of the observation extras"""
+        """The individual shape of the observation extras"""
         return self.extras[0].shape
 
     def __hash__(self):

{multi_agent_rlenv-3.3.0 → multi_agent_rlenv-3.3.1}/tests/test_adapters.py

@@ -1,31 +1,18 @@
-try:
-    import gymnasium
-
-    skip_gym = False
-except ImportError:
-    skip_gym = True
-
-try:
-    import pettingzoo
-
-    skip_pettingzoo = False
-except ImportError:
-    skip_pettingzoo = True
-
-try:
-    import smac
-
-    skip_smac = False
-except ImportError:
-    skip_smac = True
-
+from importlib.util import find_spec
 
 import numpy as np
 import pytest
 
 import marlenv
-from marlenv import DiscreteActionSpace, DiscreteMockEnv, MARLEnv, Observation, State, ContinuousActionSpace
-from marlenv.adapters import SMAC, PymarlAdapter
+from marlenv import ContinuousActionSpace, DiscreteActionSpace, DiscreteMockEnv, MARLEnv, Observation, State
+from marlenv.adapters import PymarlAdapter
+
+skip_gym = find_spec("gymnasium") is None
+skip_pettingzoo = find_spec("pettingzoo") is None
+skip_smac = find_spec("smac") is None
+# Check for "overcooked_ai_py.mdp" specifically because after uninstalling, the package
+# can still be found because of some remaining .pkl file.
+skip_overcooked = find_spec("overcooked_ai_py.mdp") is None
 
 
 @pytest.mark.skipif(skip_gym, reason="Gymnasium is not installed")
@@ -113,7 +100,10 @@ def test_pettingzoo_adapter_continuous_action():
     assert isinstance(env.action_space, marlenv.ContinuousActionSpace)
 
 
-def _check_env_3m(env: SMAC):
+def _check_env_3m(env):
+    from marlenv.adapters import SMAC
+
+    assert isinstance(env, SMAC)
     obs = env.reset()
     assert isinstance(obs, Observation)
     assert env.n_agents == 3
@@ -147,6 +137,48 @@ def test_smac_render():
     env.render()
 
 
+@pytest.mark.skipif(skip_overcooked, reason="Overcooked is not installed")
+def test_overcooked_attributes():
+    from overcooked_ai_py.mdp.overcooked_mdp import Action
+
+    from marlenv.adapters import Overcooked
+
+    env = Overcooked.from_layout("simple_o")
+    height, width = env._mdp.shape
+    assert env.n_agents == 2
+    assert env.n_actions == Action.NUM_ACTIONS
+    assert env.observation_shape == (26, height, width)
+    assert env.reward_space.shape == (1,)
+    assert env.extras_shape == (1,)
+    assert not env.is_multi_objective
+
+
+@pytest.mark.skipif(skip_overcooked, reason="Overcooked is not installed")
+def test_overcooked_obs_state():
+    from marlenv.adapters import Overcooked
+
+    HORIZON = 100
+    env = Overcooked.from_layout("coordination_ring", horizon=HORIZON)
+    height, width = env._mdp.shape
+    obs, state = env.reset()
+    for i in range(HORIZON):
+        assert obs.shape == (26, height, width)
+        assert obs.extras_shape == (1,)
+        assert state.shape == (26, height, width)
+        assert state.extras_shape == (1,)
+
+        assert np.all(obs.extras == i / HORIZON)
+        assert np.all(state.extras == i / HORIZON)
+
+        step = env.random_step()
+        obs = step.obs
+        state = step.state
+        if i < HORIZON - 1:
+            assert not step.done
+        else:
+            assert step.done
+
+
 def test_pymarl():
     LIMIT = 20
     N_AGENTS = 2

{multi_agent_rlenv-3.3.0 → multi_agent_rlenv-3.3.1}/tests/test_serialization.py

@@ -1,10 +1,15 @@
 import pickle
-import marlenv
+from importlib.util import find_spec
+
 import numpy as np
 import orjson
+import pytest
 
+import marlenv
 from marlenv import DiscreteMockEnv
 
+skip_gym = find_spec("gymnasium") is None
+
 
 def test_registry():
     env = DiscreteMockEnv(4)
@@ -17,6 +22,7 @@ def test_registry():
     assert restored_env.n_actions == env.n_actions
 
 
+@pytest.mark.skipif(skip_gym, reason="Gymnasium is not installed")
 def test_registry_gym():
     env = marlenv.make("CartPole-v1")
     restored_env = pickle.loads(pickle.dumps(env))

multi_agent_rlenv-3.3.0/src/marlenv/adapters/__init__.py

@@ -1,32 +0,0 @@
-from .pymarl_adapter import PymarlAdapter
-from typing import Any
-
-__all__ = ["PymarlAdapter"]
-try:
-    from .gym_adapter import Gym
-
-    __all__.append("Gym")
-except ImportError:
-    Gym = Any
-
-try:
-    from .pettingzoo_adapter import PettingZoo
-
-    __all__.append("PettingZoo")
-except ImportError:
-    PettingZoo = Any
-
-try:
-    from .smac_adapter import SMAC
-
-    __all__.append("SMAC")
-except ImportError:
-    SMAC = Any
-
-
-try:
-    from .overcooked_adapter import Overcooked
-
-    __all__.append("Overcooked")
-except ImportError:
-    Overcooked = Any