3110 - Add module-level docstrings

src/primaite/config/__init__.py

@@ -1,2 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
-"""Configuration parameters for running experiments."""
+"""A collection of example configuration files."""

src/primaite/config/load.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Convenience methods for finding filepaths to default PrimAITE configs."""
 from pathlib import Path
 from typing import Dict, Final, Union
 

src/primaite/exceptions.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""PrimAITE-specific exceptions."""
 class PrimaiteError(Exception):
     """The root PrimAITE Error."""
 

src/primaite/game/agent/__init__.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Agents that act in the environment, including RL and scripted agents, their actions, observations, and rewards."""
 from primaite.game.agent.interface import ProxyAgent
 from primaite.game.agent.scripted_agents.data_manipulation_bot import DataManipulationAgent
 from primaite.game.agent.scripted_agents.probabilistic_agent import ProbabilisticAgent

src/primaite/game/agent/actions/__init__.py

@@ -1,5 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
-
+"""Actions convert CAOS data into the request format for the PrimAITE simulation."""
 from primaite.game.agent.actions import (
     abstract,
     acl,

src/primaite/game/agent/actions/abstract.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Action base class."""
 from __future__ import annotations
 
 from abc import ABC

src/primaite/game/agent/actions/acl.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Actions for manipulating Access Control Lists (ACLs)."""
 from __future__ import annotations
 
 from abc import ABC

src/primaite/game/agent/actions/application.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Actions for interacting with applications on network hosts."""
 from abc import ABC
 from typing import ClassVar
 

src/primaite/game/agent/actions/file.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Actions for interacting with the files on network hosts."""
 from abc import ABC
 from typing import ClassVar
 

src/primaite/game/agent/actions/folder.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Actions for interacting with folders on network hosts."""
 from abc import ABC
 from typing import ClassVar
 

src/primaite/game/agent/actions/host_nic.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Actions for interacting with network interfact cards (NICs) on network hosts."""
 from abc import ABC
 from typing import ClassVar
 

src/primaite/game/agent/actions/manager.py

@@ -1,15 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
-"""yaml example.
-
-agents:
-  - name: agent_1
-    action_space:
-      actions:
-        - do-nothing
-        - node-service-start
-        - node-service-stop
-      action_map:
-"""
+"""Validate and keep track of an agent's action set."""
 
 from __future__ import annotations
 

src/primaite/game/agent/actions/network.py

@@ -1,5 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
-
+"""Actions for interacting with network ports of routers, switches, and firewalls."""
 from abc import ABC
 from typing import ClassVar
 

src/primaite/game/agent/actions/node.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Actions for interacting with nodes on the network."""
 from abc import ABC, abstractmethod
 from typing import ClassVar, List, Literal, Optional, Union
 

src/primaite/game/agent/actions/service.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Actions for interacting with services on network hosts."""
 from abc import ABC
 from typing import ClassVar
 

src/primaite/game/agent/actions/session.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Actions for performing login and logout on local and remote hosts."""
 from abc import ABC, abstractmethod
 
 from primaite.game.agent.actions.manager import AbstractAction

src/primaite/game/agent/actions/software.py

@@ -1,5 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
-
+"""Actions for configuring software on network hosts."""
 from typing import List, Optional, Union
 
 from pydantic import ConfigDict, Field

src/primaite/game/agent/agent_log.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Optional logger for internal agent decisions and debugging."""
 import logging
 from pathlib import Path
 from typing import Optional

src/primaite/game/agent/observations/__init__.py

@@ -1,6 +1,7 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 # flake8: noqa
 # Pre-import all the observations when we load up the observations module so that they can be resolved by the parser.
+"""Converts PrimAITE simulation data into numerical RL-ready observations."""
 from primaite.game.agent.observations.acl_observation import ACLObservation
 from primaite.game.agent.observations.file_system_observations import FileObservation, FolderObservation
 from primaite.game.agent.observations.firewall_observation import FirewallObservation

src/primaite/game/agent/scripted_agents/__init__.py

@@ -1,5 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
-
+"""Agents that automatically choose their behaviour according to scripted rules."""
 from primaite.game.agent import interface
 from primaite.game.agent.scripted_agents import (
     abstract_tap,

src/primaite/game/agent/utils.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Utility functions used in the PrimAITE game layer."""
 from typing import Any, Dict, Hashable, Optional, Sequence
 
 NOT_PRESENT_IN_STATE = object()

src/primaite/game/science.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Mathematical methods used in PrimAITE."""
 from random import random
 from typing import Any, Iterable, Mapping
 

src/primaite/interface/__init__.py

@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""The interface between the simulation and game layers of PrimAITE."""

src/primaite/session/__init__.py

@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Gymnasium and other RL environments for interfacing PrimAITE with RL models."""

src/primaite/session/environment.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Main Gymnasium entrypoint for RL agents into PrimAITE."""
 import json
 import random
 import sys

src/primaite/session/episode_schedule.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Strategies for selecting the game configuration between different episodes of a session."""
 import copy
 from abc import ABC, abstractmethod
 from itertools import chain

src/primaite/session/io.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Utilities for reading settings and writing of log files."""
 import json
 from datetime import datetime
 from pathlib import Path

src/primaite/session/ray_envs.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Entrypoint for Ray RLLib single- and multi-agent environments."""
 import json
 from typing import Dict, SupportsFloat, Tuple
 

src/primaite/setup/reset_demo_notebooks.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Clear the user data directory of example notebooks and copy fresh copies in."""
 import filecmp
 import shutil
 from logging import Logger

src/primaite/setup/reset_example_configs.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Clear user data folder of example config files and put fresh copies in."""
 import filecmp
 import os
 import shutil

src/primaite/simulator/__init__.py

@@ -1,5 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
-"""Warning: SIM_OUTPUT is a mutable global variable for the simulation output directory."""
+"""The PrimAITE simulation layer."""
 from datetime import datetime
 from enum import IntEnum
 from pathlib import Path

src/primaite/simulator/core.py

@@ -1,6 +1,6 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 # flake8: noqa
-"""Core of the PrimAITE Simulator."""
+"""Baseclasses for the PrimAITE Simulator."""
 import warnings
 from abc import abstractmethod
 from typing import Callable, Dict, Iterable, List, Literal, Optional, Tuple, Union

src/primaite/simulator/domain/__init__.py

@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Currently not used."""

src/primaite/simulator/file_system/__init__.py

@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""File system for nodes."""

src/primaite/simulator/file_system/file.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Simulation of a file on a computer file system."""
 from __future__ import annotations
 
 import hashlib

src/primaite/simulator/file_system/file_system.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Computer file system."""
 from __future__ import annotations
 
 from pathlib import Path

src/primaite/simulator/file_system/folder.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Simulation of a folder on a computer file system."""
 from __future__ import annotations
 
 import warnings

src/primaite/simulator/network/__init__.py

@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Top-level network object."""

src/primaite/simulator/sim_container.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Top-level simulation object that holds references to all child simulation components."""
 from typing import Dict
 
 from primaite.interface.request import RequestResponse

src/primaite/simulator/system/__init__.py

@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Software and system on nodes."""

src/primaite/simulator/system/applications/__init__.py

@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Software applications."""

src/primaite/simulator/system/processes/__init__.py

@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Software processes. Not yet implemented."""

src/primaite/simulator/system/services/__init__.py

@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Software services."""

src/primaite/simulator/system/software.py

@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Base class for system software."""
 import copy
 from abc import ABC, abstractmethod
 from datetime import datetime