Add environment modules

examples/distributed_parallel_optimization/main.py

@@ -53,7 +53,7 @@ def parse_args() -> argparse.Namespace:
             model_config_name="my_model",
         )
         if args.use_dist:
-            answerer = answerer.to_dist(lazy_launch=False)
+            answerer = answerer.to_dist()
         answerers.append(answerer)
 
     user_agent = UserAgent()

examples/environments/envs/__init__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for environment"""
+from .mutable import MutableEnv
+from .immutable import ImmutableEnv
+from .point2d import Point2D, EnvWithPoint2D
+from .map2d import Map2D
+from .chatroom import ChatRoom

examples/environments/envs/chatroom.py

@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+"""An env used as a chatroom."""
+from typing import List
+from copy import deepcopy
+
+from agentscope.agents import AgentBase
+from agentscope.message import Msg
+from agentscope.exception import (
+    EnvListenerError,
+)
+from agentscope.environment import (
+    Env,
+    BasicEnv,
+    EventListener,
+    Event,
+    event_func,
+)
+
+
+class ChatRoomMember(BasicEnv):
+    """A member of chatroom."""
+
+    def __init__(
+        self,
+        name: str,
+        agent: AgentBase,
+        history_idx: int = 0,
+    ) -> None:
+        super().__init__(name)
+        self._agent = agent
+        self._history_idx = history_idx
+
+    @property
+    def agent_name(self) -> str:
+        """Get the name of the agent."""
+        return self._agent.name
+
+    @property
+    def history_idx(self) -> int:
+        """Get the history index of the agent."""
+        return self._history_idx
+
+    @property
+    def agent(self) -> AgentBase:
+        """Get the agent of the member."""
+        return self._agent
+
+
+class ChatRoom(BasicEnv):
+    """A chatroom env."""
+
+    def __init__(
+        self,
+        name: str = None,
+        announcement: Msg = None,
+        participants: List[AgentBase] = None,
+        all_history: bool = False,
+    ) -> None:
+        """Init a ChatRoom instance.
+
+        Args:
+            name (`str`): The name of the chatroom.
+            announcement (`Msg`): The announcement message.
+            participants (`List[AgentBase]`): A list of agents
+            all_history (`bool`): If `True`, new participant can see all
+            history messages, else only messages generated after joining
+            can be seen. Default to `False`.
+        """
+        super().__init__(
+            name=name,
+        )
+        self.children = {
+            p.name: p for p in (participants if participants else [])
+        }
+        self.event_listeners = {}
+        self.all_history = all_history
+        self.history = []
+        self.announcement = announcement
+
+    @event_func
+    def join(self, agent: AgentBase) -> bool:
+        """Add a participant to the chatroom."""
+        if agent.agent_id in self.children:
+            return False
+        self.children[agent.agent_id] = ChatRoomMember(
+            name=agent.agent_id,
+            agent=agent,
+            history_idx=len(self.history),
+        )
+        return True
+
+    @event_func
+    def leave(self, agent: AgentBase) -> bool:
+        """Remove the participant agent from the chatroom."""
+        if agent.agent_id not in self.children:
+            return False
+        del self.children[agent.agent_id]
+        return True
+
+    @event_func
+    def speak(self, message: Msg) -> None:
+        """Speak a message in the chatroom."""
+        self.history.append(message)
+
+    @event_func
+    def get_history(self, agent_id: str) -> List[Msg]:
+        """Get all history messages, since the participant join in the
+        chatroom"""
+        if agent_id not in self.children:
+            # only participants can get history message
+            return []
+        if self.all_history:
+            history_idx = 0
+        else:
+            history_idx = self.children[agent_id].history_idx
+        return deepcopy(self.history[history_idx:])
+
+    @event_func
+    def set_announcement(self, announcement: Msg) -> None:
+        """Set the announcement of the chatroom."""
+        self.announcement = announcement
+
+    @event_func
+    def get_announcement(self) -> Msg:
+        """Get the announcement of the chatroom."""
+        return deepcopy(self.announcement)
+
+    # Syntaic sugar, not an event function
+    def listen_to(
+        self,
+        target_names: List[str],
+        listener: EventListener,
+    ) -> None:
+        """The listener will be called when a message whose name is in
+        `target_names` is send to the chatroom."""
+        if target_names is None or len(target_names) == 0:
+            return
+
+        class ListenTo(EventListener):
+            """A middleware that activates `target_listener`"""
+
+            def __init__(
+                self,
+                name: str,
+                target_names: List[str],
+                target_listener: EventListener,
+            ) -> None:
+                super().__init__(name=name)
+                self.target_names = target_names
+                self.target_listener = target_listener
+
+            def __call__(self, env: Env, event: Event) -> None:
+                if event.args["message"].name in self.target_names:
+                    self.target_listener(env, event)
+
+        if not self.add_listener(
+            "speak",
+            listener=ListenTo(
+                name=f"listen_to_{listener.name}",
+                target_names=target_names,
+                target_listener=listener,
+            ),
+        ):
+            raise EnvListenerError("Fail to add listener.")

examples/environments/envs/immutable.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""An env that is immutable and only support get."""
+
+from typing import List, Any
+from copy import deepcopy
+
+from agentscope.environment import (
+    Env,
+    BasicEnv,
+    EventListener,
+    event_func,
+)
+from agentscope.environment.event import Getable
+
+
+class ImmutableEnv(BasicEnv, Getable):
+    """An immutable env that can be get and set."""
+
+    def __init__(
+        self,
+        name: str,
+        value: Any,
+        listeners: dict[str, List[EventListener]] = None,
+        children: List[Env] = None,
+        parent: Env = None,
+    ) -> None:
+        super().__init__(
+            name=name,
+            listeners=listeners,
+            children=children,
+            parent=parent,
+        )
+        self._value = value
+
+    @property
+    def value(self) -> Any:
+        """Get the value of the env."""
+        return self.get()
+
+    @event_func
+    def get(self) -> Any:
+        return deepcopy(self._value)