multi-agent-rlenv 3.5.4__tar.gz → 3.6.0__tar.gz

{multi_agent_rlenv-3.5.4 → multi_agent_rlenv-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-agent-rlenv
-Version: 3.5.4
+Version: 3.6.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>
@@ -13,7 +13,8 @@ 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: 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'
@@ -22,9 +23,10 @@ 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-ai>=1.1.0; extra == 'overcooked'
-Requires-Dist: scipy>=1.10; 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'
@@ -62,9 +64,24 @@ $ 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` unifies multiple popular libraries under a single interface. Namely, `marlenv` supports `smac`, `gymnasium` and `pettingzoo`.
+`marlenv` provides adapters from most popular libraries to unify them under a single interface. Namely, `marlenv` supports `smac`, `gymnasium` and `pettingzoo`.
 
 ```python
 import marlenv
@@ -74,7 +91,7 @@ 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 = env2 = SMAC("3m", debug=True, difficulty="9")
+smac_env = SMAC("3m", debug=True, difficulty="9")
 
 # pettingzoo is also supported
 from pettingzoo.sisl import pursuit_v4

{multi_agent_rlenv-3.5.4 → multi_agent_rlenv-3.6.0}/README.md

@@ -24,9 +24,24 @@ $ 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` unifies multiple popular libraries under a single interface. Namely, `marlenv` supports `smac`, `gymnasium` and `pettingzoo`.
+`marlenv` provides adapters from most popular libraries to unify them under a single interface. Namely, `marlenv` supports `smac`, `gymnasium` and `pettingzoo`.
 
 ```python
 import marlenv
@@ -36,7 +51,7 @@ 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 = env2 = SMAC("3m", debug=True, difficulty="9")
+smac_env = SMAC("3m", debug=True, difficulty="9")
 
 # pettingzoo is also supported
 from pettingzoo.sisl import pursuit_v4

{multi_agent_rlenv-3.5.4 → multi_agent_rlenv-3.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "multi-agent-rlenv"
-dynamic = ["version"]
+version = "3.6.0"
 description = "A strongly typed Multi-Agent Reinforcement Learning framework"
 authors = [
     { "name" = "Yannick Molinghen", "email" = "yannick.molinghen@ulb.be" },
@@ -19,14 +19,16 @@ dependencies = ["numpy>=2.0.0", "opencv-python>=4.0", "typing_extensions>=4.0"]
 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"]
+overcooked = ["overcooked>=0.1.0"]
+lle = ["laser-learning-environment>=2.6.1"]
 torch = ["torch>=2.0"]
 all = [
     "gymnasium>0.29.1",
     "pettingzoo>=1.20",
-    "overcooked-ai",
+    "overcooked>=0.1.0",
     "smac",
     "pysc2",
+    "laser-learning-environment>=2.6.1",
     "pymunk>=6.0",
     "scipy>=1.10",
     "torch>=2.0",
@@ -42,9 +44,6 @@ line-length = 140
 [tool.hatch.build.targets.wheel]
 packages = ["src/marlenv"]
 
-[tool.hatch]
-version = { "path" = "src/marlenv/__init__.py", "attr" = "__version__" }
-
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{multi_agent_rlenv-3.5.4 → multi_agent_rlenv-3.6.0}/src/marlenv/__init__.py

@@ -62,7 +62,13 @@ 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.5.4"
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("overcooked")
+except PackageNotFoundError:
+    __version__ = "0.0.0"  # fallback pratique en dev/CI
+
 
 from . import models
 from .models import (
@@ -82,16 +88,19 @@ from .models import (
 
 from . import wrappers
 from . import adapters
-from .env_builder import make, Builder
+from .env_builder import Builder
 from .wrappers import RLEnvWrapper
 from .mock_env import DiscreteMockEnv, DiscreteMOMockEnv
+from . import catalog
+from .adapters import make
 
 __all__ = [
     "models",
+    "make",
+    "catalog",
     "wrappers",
     "adapters",
     "spaces",
-    "make",
     "Builder",
     "MARLEnv",
     "Step",

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

@@ -0,0 +1,33 @@
+from importlib.util import find_spec
+from .pymarl_adapter import PymarlAdapter
+from marlenv.utils import DummyClass, dummy_function
+
+HAS_GYM = find_spec("gymnasium") is not None
+if HAS_GYM:
+    from .gym_adapter import Gym, make
+else:
+    Gym = DummyClass("gymnasium")
+    make = dummy_function("gymnasium")
+
+HAS_PETTINGZOO = find_spec("pettingzoo") is not None
+if HAS_PETTINGZOO:
+    from .pettingzoo_adapter import PettingZoo
+else:
+    PettingZoo = DummyClass("pettingzoo")
+
+HAS_SMAC = find_spec("smac") is not None
+if HAS_SMAC:
+    from .smac_adapter import SMAC
+else:
+    SMAC = DummyClass("smac", "https://github.com/oxwhirl/smac.git")
+
+__all__ = [
+    "PymarlAdapter",
+    "Gym",
+    "make",
+    "PettingZoo",
+    "SMAC",
+    "HAS_GYM",
+    "HAS_PETTINGZOO",
+    "HAS_SMAC",
+]

{multi_agent_rlenv-3.5.4 → multi_agent_rlenv-3.6.0}/src/marlenv/adapters/gym_adapter.py

@@ -78,3 +78,9 @@ class Gym(MARLEnv[Space]):
 
     def seed(self, seed_value: int):
         self._gym_env.reset(seed=seed_value)
+
+
+def make(env_id: str, **kwargs):
+    """Make an RLEnv from str (Gym) or PettingZoo"""
+    gym_env = gym.make(env_id, render_mode="rgb_array", **kwargs)
+    return Gym(gym_env)

multi_agent_rlenv-3.6.0/src/marlenv/catalog/__init__.py

@@ -0,0 +1,26 @@
+from importlib.util import find_spec
+from ..utils.import_placeholders import DummyClass
+from marlenv.adapters import SMAC
+from .deepsea import DeepSea
+
+
+HAS_LLE = find_spec("lle") is not None
+if HAS_LLE:
+    from lle import LLE  # pyright: ignore[reportMissingImports]
+else:
+    LLE = DummyClass("lle", "laser-learning-environment")
+
+HAS_OVERCOOKED = find_spec("overcooked") is not None
+if HAS_OVERCOOKED:
+    from overcooked import Overcooked  # pyright: ignore[reportMissingImports]
+else:
+    Overcooked = DummyClass("overcooked", "overcooked")
+
+__all__ = [
+    "Overcooked",
+    "SMAC",
+    "LLE",
+    "DeepSea",
+    "HAS_LLE",
+    "HAS_OVERCOOKED",
+]

multi_agent_rlenv-3.6.0/src/marlenv/catalog/deepsea.py

@@ -0,0 +1,73 @@
+from typing import Sequence
+import numpy as np
+from marlenv import MARLEnv, MultiDiscreteSpace, DiscreteSpace, Observation, State, Step
+from dataclasses import dataclass
+
+
+LEFT = 0
+RIGHT = 1
+
+
+@dataclass
+class DeepSea(MARLEnv[MultiDiscreteSpace]):
+    """
+    Deep Sea single-agent environment to test for deep exploration. The probability of reaching the goal state under random exploration is 2^(-max_depth).
+
+    The agent explores a 2D grid where the bottom-right corner (max_depth, max_depth) is the goal and is the only state to yield a reward.
+    The agent starts in the top-left corner (0, 0).
+    The agent has two actions: left or right, and taking an action makes the agent dive one row deeper. The agent can not go beyond the grid boundaries.
+    Going right gives a penalty of (0.01 / max_depth).
+    """
+
+    max_depth: int
+
+    def __init__(self, max_depth: int):
+        super().__init__(
+            n_agents=1,
+            action_space=DiscreteSpace(size=2, labels=["left", "right"]).repeat(1),
+            observation_shape=(2,),
+            state_shape=(2,),
+        )
+        self.max_depth = max_depth
+        self._row = 0
+        self._col = 0
+        self._step_right_penalty = -0.01 / self.max_depth
+
+    def get_observation(self) -> Observation:
+        return Observation(np.array([self._row, self._col], dtype=np.float32), self.available_actions())
+
+    def get_state(self) -> State:
+        return State(np.array([self._row, self._col], dtype=np.float32))
+
+    def reset(self):
+        self._row = 0
+        self._col = 0
+        return self.get_observation(), self.get_state()
+
+    def step(self, action: Sequence[int]):
+        self._row += 1
+        if action[0] == LEFT:
+            self._col -= 1
+        else:
+            self._col += 1
+        self._col = max(0, self._col)
+        if action[0] == RIGHT:
+            if self._row == self.max_depth:
+                reward = 1.0
+            else:
+                reward = self._step_right_penalty
+        else:
+            reward = 0.0
+        return Step(
+            self.get_observation(),
+            self.get_state(),
+            reward,
+            done=self._row == self.max_depth,
+        )
+
+    def set_state(self, state: State):
+        self._row, self._col = state.data
+
+    @property
+    def agent_state_size(self):
+        return 2

{multi_agent_rlenv-3.5.4 → multi_agent_rlenv-3.6.0}/src/marlenv/env_builder.py

@@ -1,73 +1,13 @@
 from dataclasses import dataclass
-from typing import Generic, Literal, Optional, TypeVar, overload
+from typing import Generic, Literal, Optional, TypeVar
 import numpy as np
 import numpy.typing as npt
 
 from . import wrappers
-from marlenv import adapters
 from .models import Space, MARLEnv
 
 AS = TypeVar("AS", bound=Space)
 
-if adapters.HAS_PETTINGZOO:
-    from .adapters import PettingZoo
-    from pettingzoo import ParallelEnv
-
-    @overload
-    def make(env: ParallelEnv) -> PettingZoo: ...
-
-
-if adapters.HAS_GYM:
-    from .adapters import Gym
-    from gymnasium import Env
-    import gymnasium
-
-    @overload
-    def make(env: Env) -> Gym: ...
-
-    @overload
-    def make(env: str, **kwargs) -> Gym:
-        """
-        Make an RLEnv from the `gymnasium` registry (e.g: "CartPole-v1").
-        """
-
-
-if adapters.HAS_SMAC:
-    from .adapters import SMAC
-    from smac.env import StarCraft2Env
-
-    @overload
-    def make(env: StarCraft2Env) -> SMAC: ...
-
-
-if adapters.HAS_OVERCOOKED:
-    from .adapters import Overcooked
-    from overcooked_ai_py.mdp.overcooked_env import OvercookedEnv
-
-    @overload
-    def make(env: OvercookedEnv) -> Overcooked: ...
-
-
-def make(env, **kwargs):
-    """Make an RLEnv from str (Gym) or PettingZoo"""
-    match env:
-        case MARLEnv():
-            return env
-        case str(env_id):
-            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)}")
-
 
 @dataclass
 class Builder(Generic[AS]):

{multi_agent_rlenv-3.5.4 → multi_agent_rlenv-3.6.0}/src/marlenv/models/episode.py

@@ -2,20 +2,22 @@ from dataclasses import dataclass
 from functools import cached_property
 from typing import Any, Callable, Optional, Sequence, overload
 
+import cv2
 import numpy as np
 import numpy.typing as npt
-import cv2
 
+from marlenv.exceptions import EnvironmentMismatchException, ReplayMismatchException
+from marlenv.utils import CachedPropertyInvalidator
+
+from .env import MARLEnv
 from .observation import Observation
 from .state import State
 from .step import Step
 from .transition import Transition
-from .env import MARLEnv
-from marlenv.exceptions import EnvironmentMismatchException, ReplayMismatchException
 
 
 @dataclass
-class Episode:
+class Episode(CachedPropertyInvalidator):
     """Episode model made of observations, actions, rewards, ..."""
 
     all_observations: list[npt.NDArray[np.float32]]
@@ -153,12 +155,12 @@ class Episode:
         """Get the next extra features"""
         return self.all_extras[1:]
 
-    @cached_property
+    @property
     def n_agents(self):
         """The number of agents in the episode"""
         return self.all_extras[0].shape[0]
 
-    @cached_property
+    @property
     def n_actions(self):
         """The number of actions"""
         return len(self.all_available_actions[0][0])
@@ -267,7 +269,7 @@ class Episode:
     def __len__(self):
         return self.episode_len
 
-    @cached_property
+    @property
     def score(self) -> list[float]:
         """The episode score (sum of all rewards across all objectives)"""
         score = []

{multi_agent_rlenv-3.5.4 → multi_agent_rlenv-3.6.0}/src/marlenv/models/spaces.py

@@ -105,7 +105,7 @@ class MultiDiscreteSpace(Space):
     def sample(self, mask: Optional[npt.NDArray[np.bool] | list[npt.NDArray[np.bool]]] = None):
         if mask is None:
             return np.array([space.sample() for space in self.spaces], dtype=np.int32)
-        return np.array([space.sample(mask=mask) for mask, space in zip(mask, self.spaces)], dtype=np.int32)
+        return np.array([space.sample(mask=mask) for mask, space in zip(mask, self.spaces)], dtype=np.int32)  # type: ignore
 
     def __eq__(self, value: object) -> bool:
         if not isinstance(value, MultiDiscreteSpace):

multi_agent_rlenv-3.6.0/src/marlenv/utils/__init__.py

@@ -0,0 +1,15 @@
+from .cached_property_collector import CachedPropertyCollector, CachedPropertyInvalidator
+from .schedule import ExpSchedule, LinearSchedule, MultiSchedule, RoundedSchedule, Schedule
+from .import_placeholders import DummyClass, dummy_function
+
+__all__ = [
+    "Schedule",
+    "LinearSchedule",
+    "ExpSchedule",
+    "MultiSchedule",
+    "RoundedSchedule",
+    "CachedPropertyCollector",
+    "CachedPropertyInvalidator",
+    "DummyClass",
+    "dummy_function",
+]

multi_agent_rlenv-3.6.0/src/marlenv/utils/cached_property_collector.py

@@ -0,0 +1,17 @@
+from functools import cached_property
+
+
+class CachedPropertyCollector(type):
+    def __init__(cls, name: str, bases: tuple, namespace: dict):
+        super().__init__(name, bases, namespace)
+        cls.CACHED_PROPERTY_NAMES = [key for key, value in namespace.items() if isinstance(value, cached_property)]
+
+
+class CachedPropertyInvalidator(metaclass=CachedPropertyCollector):
+    def __init__(self):
+        super().__init__()
+
+    def invalidate_cached_properties(self):
+        for key in self.__class__.CACHED_PROPERTY_NAMES:
+            if hasattr(self, key):
+                delattr(self, key)

multi_agent_rlenv-3.6.0/src/marlenv/utils/import_placeholders.py

@@ -0,0 +1,30 @@
+from typing import Optional, Any
+
+
+class DummyClass:
+    def __init__(self, module_name: str, package_name: Optional[str] = None):
+        self.module_name = module_name
+        if package_name is None:
+            self.package_name = module_name
+        else:
+            self.package_name = package_name
+
+    def _raise_error(self):
+        raise ImportError(
+            f"The optional dependency `{self.module_name}` is not installed.\nInstall the `{self.package_name}` package (e.g. pip install {self.package_name})."
+        )
+
+    def __getattr__(self, _):
+        self._raise_error()
+
+    def __call__(self, *args, **kwargs):
+        self._raise_error()
+
+
+def dummy_function(module_name: str, package_name: Optional[str] = None):
+    dummy = DummyClass(module_name, package_name)
+
+    def fail(*args, **kwargs) -> Any:
+        dummy()
+
+    return fail

{multi_agent_rlenv-3.5.4 → multi_agent_rlenv-3.6.0}/src/marlenv/utils/schedule.py

@@ -1,6 +1,6 @@
 from abc import abstractmethod
 from dataclasses import dataclass
-from typing import Callable, Optional, TypeVar
+from typing import Any, Callable, Optional, TypeVar
 
 T = TypeVar("T")
 
@@ -142,6 +142,21 @@ class Schedule:
     def __int__(self) -> int:
         return int(self.value)
 
+    @staticmethod
+    def from_json(data: dict[str, Any]):
+        """Create a Schedule from a JSON-like dictionary."""
+        classname = data.get("name")
+        if classname == "LinearSchedule":
+            return LinearSchedule(data["start_value"], data["end_value"], data["n_steps"])
+        elif classname == "ExpSchedule":
+            return ExpSchedule(data["start_value"], data["end_value"], data["n_steps"])
+        elif classname == "ConstantSchedule":
+            return ConstantSchedule(data["value"])
+        elif classname == "ArbitrarySchedule":
+            raise NotImplementedError("ArbitrarySchedule cannot be deserialized from JSON")
+        else:
+            raise ValueError(f"Unknown schedule type: {classname}")
+
 
 @dataclass(eq=False)
 class LinearSchedule(Schedule):

{multi_agent_rlenv-3.5.4 → multi_agent_rlenv-3.6.0}/src/marlenv/wrappers/__init__.py

@@ -11,6 +11,7 @@ from .centralised import Centralized
 from .available_actions_mask import AvailableActionsMask
 from .delayed_rewards import DelayedReward
 from .potential_shaping import PotentialShaping
+from .action_randomizer import ActionRandomizer
 
 __all__ = [
     "RLEnvWrapper",
@@ -28,4 +29,5 @@ __all__ = [
     "Centralized",
     "DelayedReward",
     "PotentialShaping",
+    "ActionRandomizer",
 ]

multi_agent_rlenv-3.6.0/src/marlenv/wrappers/action_randomizer.py

@@ -0,0 +1,17 @@
+from .rlenv_wrapper import RLEnvWrapper, AS, MARLEnv
+import numpy as np
+
+
+class ActionRandomizer(RLEnvWrapper[AS]):
+    def __init__(self, env: MARLEnv[AS], p: float):
+        super().__init__(env)
+        self.p = p
+
+    def step(self, action):
+        if np.random.rand() < self.p:
+            action = self.action_space.sample()
+        return super().step(action)
+
+    def seed(self, seed_value: int):
+        np.random.seed(seed_value)
+        super().seed(seed_value)