Merge remote-tracking branch 'origin/dev' into bugfix/1587-hardcoded-agent

src/primaite/agents/__init__.py

@@ -0,0 +1 @@
+"""Common interface between RL agents from different libraries and PrimAITE."""

src/primaite/agents/agent.py

@@ -42,12 +42,21 @@ class AgentSessionABC(ABC):
     """
     An ABC that manages training and/or evaluation of agents in PrimAITE.
 
-    This class cannot be directly instantiated and must be inherited from
-    with all implemented abstract methods implemented.
+    This class cannot be directly instantiated and must be inherited from with all implemented abstract methods
+    implemented.
     """
 
     @abstractmethod
     def __init__(self, training_config_path, lay_down_config_path):
+        """
+        Initialise an agent session from config files.
+
+        :param training_config_path: YAML file containing configurable items defined in
+            `primaite.config.training_config.TrainingConfig`
+        :type training_config_path: Union[path, str]
+        :param lay_down_config_path: YAML file containing configurable items for generating network laydown.
+        :type lay_down_config_path: Union[path, str]
+        """
         if not isinstance(training_config_path, Path):
             training_config_path = Path(training_config_path)
         self._training_config_path: Final[Union[Path, str]] = training_config_path
@@ -55,7 +64,7 @@ class AgentSessionABC(ABC):
 
         if not isinstance(lay_down_config_path, Path):
             lay_down_config_path = Path(lay_down_config_path)
-        self._lay_down_config_path: Final[Union[Path]] = lay_down_config_path
+        self._lay_down_config_path: Final[Union[Path, str]] = lay_down_config_path
         self._lay_down_config: Dict = lay_down_config.load(self._lay_down_config_path)
         self.sb3_output_verbose_level = self._training_config.sb3_output_verbose_level
 
@@ -305,11 +314,20 @@ class HardCodedAgentSessionABC(AgentSessionABC):
     """
     An Agent Session ABC for evaluation deterministic agents.
 
-    This class cannot be directly instantiated and must be inherited from
-    with all implemented abstract methods implemented.
+    This class cannot be directly instantiated and must be inherited from with all implemented abstract methods
+    implemented.
     """
 
     def __init__(self, training_config_path, lay_down_config_path):
+        """
+        Initialise a hardcoded agent session.
+
+        :param training_config_path: YAML file containing configurable items defined in
+            `primaite.config.training_config.TrainingConfig`
+        :type training_config_path: Union[path, str]
+        :param lay_down_config_path: YAML file containing configurable items for generating network laydown.
+        :type lay_down_config_path: Union[path, str]
+        """
         super().__init__(training_config_path, lay_down_config_path)
         self._setup()
 

src/primaite/agents/hardcoded_acl.py

@@ -439,7 +439,8 @@ class HardCodedACLAgent(HardCodedAgentSessionABC):
         return action
 
     def _calculate_action_basic_view(self, obs: np.ndarray) -> int:
-        """Calculate a good acl-based action for the blue agent to take.
+        """
+        Calculate a good acl-based action for the blue agent to take.
 
         Uses ONLY information from the current observation with NO knowledge
         of previous actions taken and NO reward feedback.

src/primaite/agents/rllib.py

@@ -44,6 +44,18 @@ class RLlibAgent(AgentSessionABC):
     """An AgentSession class that implements a Ray RLlib agent."""
 
     def __init__(self, training_config_path, lay_down_config_path):
+        """
+        Initialise the RLLib Agent training session.
+
+        :param training_config_path: YAML file containing configurable items defined in
+            `primaite.config.training_config.TrainingConfig`
+        :type training_config_path: Union[path, str]
+        :param lay_down_config_path: YAML file containing configurable items for generating network laydown.
+        :type lay_down_config_path: Union[path, str]
+        :raises ValueError: If the training config contains an unexpected value for agent_framework (should be "RLLIB")
+        :raises ValueError: If the training config contains an unexpected value for agent_identifies (should be `PPO`
+            or `A2C`)
+        """
         super().__init__(training_config_path, lay_down_config_path)
         if not self._training_config.agent_framework == AgentFramework.RLLIB:
             msg = f"Expected RLLIB agent_framework, " f"got {self._training_config.agent_framework}"

src/primaite/agents/sb3.py

@@ -19,6 +19,18 @@ class SB3Agent(AgentSessionABC):
     """An AgentSession class that implements a Stable Baselines3 agent."""
 
     def __init__(self, training_config_path, lay_down_config_path):
+        """
+        Initialise the SB3 Agent training session.
+
+        :param training_config_path: YAML file containing configurable items defined in
+            `primaite.config.training_config.TrainingConfig`
+        :type training_config_path: Union[path, str]
+        :param lay_down_config_path: YAML file containing configurable items for generating network laydown.
+        :type lay_down_config_path: Union[path, str]
+        :raises ValueError: If the training config contains an unexpected value for agent_framework (should be "SB3")
+        :raises ValueError: If the training config contains an unexpected value for agent_identifies (should be `PPO`
+            or `A2C`)
+        """
         super().__init__(training_config_path, lay_down_config_path)
         if not self._training_config.agent_framework == AgentFramework.SB3:
             msg = f"Expected SB3 agent_framework, " f"got {self._training_config.agent_framework}"

src/primaite/agents/simple.py

@@ -17,8 +17,7 @@ class DummyAgent(HardCodedAgentSessionABC):
     """
     A Dummy Agent.
 
-    All action spaces setup so dummy action is always 0 regardless of action
-    type used.
+    All action spaces setup so dummy action is always 0 regardless of action type used.
     """
 
     def _calculate_action(self, obs):

src/primaite/agents/utils.py

@@ -67,7 +67,8 @@ def transform_action_acl_readable(action: List[str]) -> List[Union[str, int]]:
 
 
 def is_valid_node_action(action: List[int]) -> bool:
-    """Is the node action an actual valid action.
+    """
+    Is the node action an actual valid action.
 
     Only uses information about the action to determine if the action has an effect