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

{multi_agent_rlenv-3.2.2 → 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
@@ -63,7 +63,7 @@ jobs:
     - name: Install UV
       uses: yezz123/setup-uv@v4
       with:
-          uv-version: 0.5.6
+          uv-version: 0.6.4
     - name: Build wheels
       run: |
         uv venv

multi_agent_rlenv-3.3.1/.github/workflows/docs.yaml

@@ -0,0 +1,58 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main", "master"]
+    # Only deploy the documentation on new version tags
+    tags:
+        - 'v[0-9]+.[0-9]+.[0-9]+'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    name: 📚 Build docs
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - name: Install UV
+        uses: yezz123/setup-uv@v4
+        with:
+          uv-version: 0.6.4
+      - name: Install dependencies
+        run: |
+          uv sync
+          uv run pdoc python/marlenv -o ./docs --docformat=google
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: './docs'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

multi_agent_rlenv-3.2.2/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.2.2/PKG-INFO → multi_agent_rlenv-3.3.1/README.md

@@ -1,23 +1,30 @@
-Metadata-Version: 2.4
-Name: multi-agent-rlenv
-Version: 3.2.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.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.2.2 → 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", "pytest>=8.3.2"]
+dev = ["orjson>=3.10.12", "pdoc>=15.0.1", "pytest>=8.3.2"]

multi_agent_rlenv-3.3.1/src/marlenv/__init__.py

@@ -0,0 +1,111 @@
+"""
+`marlenv` is a strongly typed library for multi-agent and multi-objective reinforcement learning.
+
+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.
+
+# 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.
+
+```python
+from marlenv.adapters import Gym, PettingZoo, SMAC, Overcooked
+import marlenv
+
+env1 = Gym("CartPole-v1")
+env2 = marlenv.make("CartPole-v1")
+env3 = PettingZoo("prospector_v4")
+env4 = SMAC("3m")
+env5 = Overcooked.from_layout("cramped_room")
+```
+
+# 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.
+
+```python
+from marlenv import make, Builder
+
+env = <your env>
+env = Builder(env).agent_id().time_limit(50).record("videos").build()
+```
+
+# Using the library
+A typical environment loop would look like this:
+
+```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
+```
+
+# 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, ).
+
+```python
+env = GridWorldEnv()
+print(env.observation_shape) # (height, width)
+print(env.extras_shape) # (0, )
+
+env = Builder(env).time_limit(25).build()
+print(env.observation_shape) # (height, width)
+print(env.extras_shape) # (1, )
+```
+
+# 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.
+"""
+
+__version__ = "3.3.1"
+
+from . import models
+from . import wrappers
+from . import adapters
+from .models import spaces
+
+
+from .env_builder import make, Builder
+from .models import (
+    MARLEnv,
+    State,
+    Step,
+    Observation,
+    Episode,
+    Transition,
+    DiscreteSpace,
+    ContinuousSpace,
+    ActionSpace,
+    DiscreteActionSpace,
+    ContinuousActionSpace,
+)
+from .wrappers import RLEnvWrapper
+from .mock_env import DiscreteMockEnv, DiscreteMOMockEnv
+
+__all__ = [
+    "models",
+    "wrappers",
+    "adapters",
+    "spaces",
+    "make",
+    "Builder",
+    "MARLEnv",
+    "Step",
+    "State",
+    "Observation",
+    "Episode",
+    "Transition",
+    "ActionSpace",
+    "DiscreteSpace",
+    "ContinuousSpace",
+    "DiscreteActionSpace",
+    "ContinuousActionSpace",
+    "DiscreteMockEnv",
+    "DiscreteMOMockEnv",
+    "RLEnvWrapper",
+]

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.2.2 → multi_agent_rlenv-3.3.1}/src/marlenv/adapters/gym_adapter.py

@@ -1,3 +1,5 @@
+import sys
+import cv2
 from dataclasses import dataclass
 from typing import Sequence
 
@@ -79,7 +81,10 @@ class Gym(MARLEnv[Sequence | npt.NDArray, ActionSpace]):
         return self.last_obs, self.get_state()
 
     def get_image(self):
-        return self.env.render()
+        image = np.array(self.env.render())
+        if sys.platform in ("linux", "linux2"):
+            image = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
+        return image
 
     def seed(self, seed_value: int):
         self.env.reset(seed=seed_value)

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

@@ -0,0 +1,164 @@
+import sys
+from dataclasses import dataclass
+from typing import Literal, Sequence
+
+import cv2
+import numpy as np
+import numpy.typing as npt
+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
+
+
+@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,
+                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 = 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()[0], np.array([self.time_step / self.horizon]))
+
+    def get_observation(self) -> Observation:
+        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)
+        actions = self._mdp.get_actions(self._oenv.state)
+        for agent_num, agent_actions in enumerate(actions):
+            for action in agent_actions:
+                available_actions[agent_num, Action.ACTION_TO_INDEX[action]] = True
+        return np.array(available_actions)
+
+    def step(self, actions: Sequence[int] | npt.NDArray[np.int32 | np.int64]) -> Step:
+        actions = [Action.ALL_ACTIONS[a] for a in actions]
+        _, reward, done, info = self._oenv.step(actions, display_phi=True)
+        return Step(
+            obs=self.get_observation(),
+            state=self.get_state(),
+            reward=np.array([reward]),
+            done=done,
+            truncated=False,
+            info=info,
+        )
+
+    def get_image(self):
+        rewards_dict = {}  # dictionary of details you want rendered in the UI
+        for key, value in self._oenv.game_stats.items():
+            if key in [
+                "cumulative_shaped_rewards_by_agent",
+                "cumulative_sparse_rewards_by_agent",
+            ]:
+                rewards_dict[key] = value
+
+        image = self.visualizer.render_state(
+            state=self._oenv.state,
+            grid=self._mdp.terrain_mtx,
+            hud_data=StateVisualizer.default_hud_data(self._oenv.state, **rewards_dict),
+        )
+
+        image = pygame.surfarray.array3d(image)
+        image = np.flip(np.rot90(image, 3), 1)
+        # Depending on the platform, the image may need to be converted to RGB
+        if sys.platform in ("linux", "linux2"):
+            image = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
+        return image
+
+    @staticmethod
+    def from_layout(
+        layout: Literal[
+            "asymmetric_advantages",
+            "asymmetric_advantages_tomato",
+            "bonus_order_test",
+            "bottleneck",
+            "centre_objects",
+            "centre_pots",
+            "coordination_ring",
+            "corridor",
+            "counter_circuit",
+            "counter_circuit_o_1order",
+            "cramped_corridor",
+            "cramped_room",
+            "cramped_room_o_3orders",
+            "cramped_room_single",
+            "cramped_room_tomato",
+            "five_by_five",
+            "forced_coordination",
+            "forced_coordination_tomato",
+            "inverse_marshmallow_experiment",
+            "large_room",
+            "long_cook_time",
+            "marshmallow_experiment_coordination",
+            "marshmallow_experiment",
+            "mdp_test",
+            "m_shaped_s",
+            "multiplayer_schelling",
+            "pipeline",
+            "scenario1_s",
+            "scenario2",
+            "scenario2_s",
+            "scenario3",
+            "scenario4",
+            "schelling",
+            "schelling_s",
+            "simple_o",
+            "simple_o_t",
+            "simple_tomato",
+            "small_corridor",
+            "soup_coordination",
+            "tutorial_0",
+            "tutorial_1",
+            "tutorial_2",
+            "tutorial_3",
+            "unident",
+            "you_shall_not_pass",
+        ],
+        horizon: int = 400,
+    ):
+        mdp = OvercookedGridworld.from_layout_name(layout)
+        return Overcooked(OvercookedEnv.from_mdp(mdp, horizon=horizon))