From 0d93981ef837573d22d50a7cbddaf5233d47e0fe Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Wed, 26 Feb 2025 12:03:00 +0000 Subject: [PATCH] Updates to documentation pages --- docs/source/how_to_guides/custom_actions.rst | 18 ++++++++++++------ ...environment.rst => custom_environments.rst} | 7 ++++++- docs/source/how_to_guides/custom_software.rst | 4 +++- .../how_to_guides/extensible_actions.rst | 2 ++ .../source/how_to_guides/extensible_agents.rst | 2 +- docs/source/how_to_guides/extensible_nodes.rst | 2 +- .../how_to_guides/extensible_rewards.rst | 2 +- ...Command-and-Control-E2E-Demonstration.ipynb | 2 +- 8 files changed, 27 insertions(+), 12 deletions(-) rename docs/source/how_to_guides/{custom_environment.rst => custom_environments.rst} (68%) diff --git a/docs/source/how_to_guides/custom_actions.rst b/docs/source/how_to_guides/custom_actions.rst index bebabfdb..ae865b3d 100644 --- a/docs/source/how_to_guides/custom_actions.rst +++ b/docs/source/how_to_guides/custom_actions.rst @@ -2,7 +2,7 @@ © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK -.. _custom_action: +.. _custom_actions: Creating Custom Actions in PrimAITE *********************************** @@ -19,18 +19,24 @@ Actions within PrimAITE follow a default format, as seen below and in ``actions. class ExampleActionClass(AbstractAction, identifier="ExampleActions"): """Example Action Class""" - def __init__(self, manager: "ActionManager", num_nodes: int, num_folders: int, **kwargs) -> None: - super().__init(manager, num_nodes=num_nodes, num_folders=num_folders, **kwargs) - self.verb: str = "ExampleAction" + config: ExampleAction.ConfigSchema(AbstractAction.ConfigSchema) + + class ConfigSchema(AbstractAction.ConfigSchema) + + node_name: str + + @classmethod + def form_request(cls, config: ConfigSchema) -> RequestFormat: + return [config.node_name, "example_action"] Integration with PrimAITE ActionManager -========================================== +======================================= Any custom actions should then be added to the `ActionManager` class, and the `act_class_identifiers` dictionary. This will map the action class to the corresponding action type string that would be passed through the PrimAITE `request_system`. Interaction with the PrimAITE Request Manager -================================================ +============================================== Where an action would cause a request to be sent through the PrimAITE RequestManager, a `form_request` method is expected to be defined within the Action Class. This should format the action into a format that can be ingested by the `RequestManager`. Examples of this include the `NodeFolderCreateAction`, which sends a formed request to create a folder on a given node (seen below). diff --git a/docs/source/how_to_guides/custom_environment.rst b/docs/source/how_to_guides/custom_environments.rst similarity index 68% rename from docs/source/how_to_guides/custom_environment.rst rename to docs/source/how_to_guides/custom_environments.rst index 8674d0fa..928fc101 100644 --- a/docs/source/how_to_guides/custom_environment.rst +++ b/docs/source/how_to_guides/custom_environments.rst @@ -2,7 +2,7 @@ © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK -.. _custom_environment: +.. _custom_environments: Creating Custom Environments for PrimAITE ***************************************** @@ -13,6 +13,9 @@ You configuration file should follow the hierarchy seen below: .. code:: yaml + metadata: + version: 4.0 + io_settings: ... game: @@ -22,5 +25,7 @@ You configuration file should follow the hierarchy seen below: simulation: ... +It's important to include the metadata tag within your YAML file, as this is used to ensure PrimAITE can interpret the configuration correctly. This should also include any plugins that are required for the defined environment, along with their respective version. For detailed information about each configuration item found within the configuration file, see :ref:`Configurable Items`. + diff --git a/docs/source/how_to_guides/custom_software.rst b/docs/source/how_to_guides/custom_software.rst index d970755f..fa0671d7 100644 --- a/docs/source/how_to_guides/custom_software.rst +++ b/docs/source/how_to_guides/custom_software.rst @@ -2,6 +2,8 @@ © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK +.. _custom_software: + Creating Custom Software for PrimAITE ************************************* @@ -10,7 +12,7 @@ This page aims to provide a how-to guide on how to create your own custom softwa PrimAITE has a base software class which should be inherited from when building custom software. Examples of this can be seen in the ``IOSoftware`` and ``Process`` classes. It's important that any new software created within PrimAITE has the ``identifier`` attribute defined, for use when generating the environment. -Some default attributes may need to be adjusted to align with the intended application of the custom software. +Some default attributes may need to be adjusted to align with the intended application of the custom software. .. code:: Python diff --git a/docs/source/how_to_guides/extensible_actions.rst b/docs/source/how_to_guides/extensible_actions.rst index c2cc07bf..4a7ed35c 100644 --- a/docs/source/how_to_guides/extensible_actions.rst +++ b/docs/source/how_to_guides/extensible_actions.rst @@ -2,6 +2,7 @@ © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK +.. _extensible_actions: Extensible Actions ****************** @@ -48,6 +49,7 @@ When declaring a custom class, it must have a unique discriminator string, that node_name: str directory_name: str + @classmethod def form_request(cls, config: ConfigSchema) -> RequestFormat: return ["network", "node", diff --git a/docs/source/how_to_guides/extensible_agents.rst b/docs/source/how_to_guides/extensible_agents.rst index 1d765417..5225e63c 100644 --- a/docs/source/how_to_guides/extensible_agents.rst +++ b/docs/source/how_to_guides/extensible_agents.rst @@ -2,7 +2,7 @@ © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK -.. _about: +.. _extensible_agents: Extensible Agents ***************** diff --git a/docs/source/how_to_guides/extensible_nodes.rst b/docs/source/how_to_guides/extensible_nodes.rst index 4819cbb2..9219ca31 100644 --- a/docs/source/how_to_guides/extensible_nodes.rst +++ b/docs/source/how_to_guides/extensible_nodes.rst @@ -2,7 +2,7 @@ © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK -.. _about: +.. _extensible_nodes: Extensible Nodes diff --git a/docs/source/how_to_guides/extensible_rewards.rst b/docs/source/how_to_guides/extensible_rewards.rst index d3053a49..34a2f4fe 100644 --- a/docs/source/how_to_guides/extensible_rewards.rst +++ b/docs/source/how_to_guides/extensible_rewards.rst @@ -2,7 +2,7 @@ © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK -.. _about: +.. _extensible_rewards: Extensible Rewards ****************** diff --git a/src/primaite/notebooks/Command-and-Control-E2E-Demonstration.ipynb b/src/primaite/notebooks/Command-and-Control-E2E-Demonstration.ipynb index f187c8d5..7e64c3c5 100644 --- a/src/primaite/notebooks/Command-and-Control-E2E-Demonstration.ipynb +++ b/src/primaite/notebooks/Command-and-Control-E2E-Demonstration.ipynb @@ -1688,7 +1688,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3.10.11" } }, "nbformat": 4,