#2887 - Resolve conflicts from merge

docs/source/how_to_guides/extensible_actions.rst

@@ -0,0 +1,67 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+
+Extensible Actions
+******************
+
+
+Changes to Actions class Structure.
+===================================
+
+Actions within PrimAITE have been updated to inherit from a base class, AbstractAction, standardising their format and allowing for easier creation of custom actions. Actions now use a ``ConfigSchema`` to define the possible configuration variables, and use pydantic to enforce correct parameters are passed through.
+
+
+Developing Custom Actions.
+==========================
+
+Custom actions within PrimAITE must be a sub-class of `AbstractAction`, and contain 3 key items:
+
+#. ConfigSchema class
+
+#. Unique Identifier
+
+#. `form_request` method.
+
+
+ConfigSchema
+############
+
+The ConfigSchema sub-class of the action must contain all `configurable` variables within the action, that would be specified within the environments configuration YAML file.
+
+
+Unique Identifier
+#################
+
+When declaring a custom class, it must have a unique identifier string, that allows PrimAITE to generate the correct action when needed.
+
+.. code:: Python
+
+    class CreateDirectoryAction(AbstractAction, identifier="node_folder_create")
+
+        config: CreateDirectoryAction.ConfigSchema
+
+        class ConfigSchema(AbstractAction.ConfigSchema):
+
+            verb: ClassVar[str] = "create"
+            node_name: str
+            directory_name: str
+
+        def form_request(cls, config: ConfigSchema) -> RequestFormat:
+            return ["network",
+                    "node",
+                    config.node_name,
+                    "file_system",
+                    config.verb,
+                    "folder",
+                    config.directory_name,
+                ]
+
+The above action would fail pydantic validation as the identifier "node_folder_create" is already used by the `NodeFolderCreateAction`, and would create a duplicate listing within `AbstractAction._registry`.
+
+
+form_request method
+###################
+
+PrimAITE actions need to have a `form_request` method, which can be passed to the `RequestManager` for processing. This allows the custom action to be actioned within the simulation environment.

docs/source/how_to_guides/extensible_agents.rst

@@ -0,0 +1,78 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _about:
+
+Extensible Agents
+*****************
+
+Agents defined within PrimAITE have been updated to allow for easier creation of new bespoke agents for use in custom environments.
+
+
+Developing Agents for PrimAITE
+==============================
+
+All agent types within PrimAITE must be subclassed from ``AbstractAgent`` in order to be used from configuration YAML files. This then allows you to implement any custom agent logic for the new agent in your training scenario. Examples of implementing custom agent logic can be seen in pre-existing agents, such as the ``DataManipulationBot`` and ``RandomAgent``.
+
+The core features that should be implemented in any new agent are detailed below:
+
+#. **ConfigSchema**:
+
+    Configurable items within a new agent within PrimAITE should contain a ``ConfigSchema`` which holds all configurable variables of the agent. This should not include parameters related to its *state*, these would be listed seperately.
+	Agent generation will fail pydantic checks if incorrect or invalid parameters are passed to the ConfigSchema of the chosen Agent.
+
+
+    .. code-block:: python
+
+        class ExampleAgent(AbstractAgent, identifier = "ExampleAgent"):
+            """An example agent for demonstration purposes."""
+
+            config: "ExampleAgent.ConfigSchema" = Field(default_factory= lambda: ExampleAgent.ConfigSchema())
+            """Agent configuration"""
+            num_executions: int = 0
+            """Number of action executions by agent"""
+
+            class ConfigSchema(AbstractAgent.ConfigSchema):
+                """ExampleAgent configuration schema"""
+
+                type: str = "ExampleAgent
+                """Name of agent"""
+                starting_host: int
+                """Host node that this agent should start from in the given environment."""
+
+
+	.. code-block:: yaml
+
+		- ref: example_green_agent
+		  team: GREEN
+		  type: ExampleAgent
+
+		  action_space:
+			action_map:
+				0:
+					action: do_nothing
+					options: {}
+		  reward_function:
+		  	reward_components:
+				- type: DUMMY
+
+		  agent_settings:
+			start_step: 25
+			frequency: 20
+			variance: 5
+			starting_host: "Server_1"
+
+
+#. **Identifiers**:
+
+    All agent classes should have an ``identifier`` attribute, a unique kebab-case string, for when they are added to the base ``AbstractAgent`` registry. This is then specified in your configuration YAML, and used by PrimAITE to generate the correct Agent.
+
+Changes to YAML file
+====================
+
+PrimAITE v4.0.0 introduces some breaking changes to how environment configuration yaml files are created. YAML files created for Primaite versions 3.3.0 should be compatible through a translation function, though it is encouraged that these are updated to reflect the updated format of 4.0.0+.
+
+Agents now follow a more standardised settings definition, so should be more consistent across YAML files and the available agent types with PrimAITE.
+
+All configurable items for agents sit under the ``agent_settings`` heading within your YAML files. There is no need for the inclusion of  a ``start_settings``. Please see the above YAML example for full changes to agents.