docs: add docs to CB

Pretty much every class and method should have documentation now.

ref: N25B-295

src/control_backend/core/agent_system.py

@@ -30,19 +30,30 @@ class AgentDirectory:
 
 class BaseAgent(ABC):
     """
-    Abstract base class for all agents. To make a new agent, inherit from
-    `control_backend.agents.BaseAgent`, not this class. That ensures that a
-    logger is present with the correct name pattern.
+    Abstract base class for all agents in the system.
 
-    When subclassing, the `setup()` method needs to be overwritten. To handle
-    messages from other agents, overwrite the `handle_message()` method. To
-    send messages to other agents, use the `send()` method. To add custom
-    behaviors/tasks to the agent, use the `add_background_task()` method.
+    This class provides the foundational infrastructure for agent lifecycle management, messaging
+    (both intra-process and inter-process via ZMQ), and asynchronous behavior execution.
+
+    .. warning::
+        Do not inherit from this class directly for creating new agents. Instead, inherit from
+        :class:`control_backend.agents.base.BaseAgent`, which ensures proper logger configuration.
+
+    :ivar name: The unique name of the agent.
+    :ivar inbox: The queue for receiving internal messages.
+    :ivar _tasks: A set of currently running asynchronous tasks/behaviors.
+    :ivar _running: A boolean flag indicating if the agent is currently running.
+    :ivar logger: The logger instance for the agent.
     """
 
     logger: logging.Logger
 
     def __init__(self, name: str):
+        """
+        Initialize the BaseAgent.
+
+        :param name: The unique identifier for this agent.
+        """
         self.name = name
         self.inbox: asyncio.Queue[InternalMessage] = asyncio.Queue()
         self._tasks: set[asyncio.Task] = set()
@@ -53,11 +64,27 @@ class BaseAgent(ABC):
 
     @abstractmethod
     async def setup(self):
-        """Overwrite this to initialize resources."""
+        """
+        Initialize agent-specific resources.
+
+        This method must be overridden by subclasses. It is called after the agent has started
+        and the ZMQ sockets have been initialized. Use this method to:
+
+        *   Initialize connections (databases, APIs, etc.)
+        *   Add initial behaviors using :meth:`add_behavior`
+        """
         pass
 
     async def start(self):
-        """Starts the agent and its loops."""
+        """
+        Start the agent and its internal loops.
+
+        This method:
+        1. Sets the running state to True.
+        2. Initializes ZeroMQ PUB/SUB sockets for inter-process communication.
+        3. Calls the user-defined :meth:`setup` method.
+        4. Starts the inbox processing loop and the ZMQ receiver loop.
+        """
         self.logger.info(f"Starting agent {self.name}")
         self._running = True
 
@@ -79,7 +106,11 @@ class BaseAgent(ABC):
         await self.add_behavior(self._receive_internal_zmq_loop())
 
     async def stop(self):
-        """Stops the agent."""
+        """
+        Stop the agent.
+
+        Sets the running state to False and cancels all running background tasks.
+        """
         self._running = False
         for task in self._tasks:
             task.cancel()
@@ -87,7 +118,16 @@ class BaseAgent(ABC):
 
     async def send(self, message: InternalMessage):
         """
-        Sends a message to another agent.
+        Send a message to another agent.
+
+        This method intelligently routes the message:
+
+        *   If the target agent is in the same process (found in :class:`AgentDirectory`),
+            the message is put directly into its inbox.
+        *   If the target agent is not found locally, the message is serialized and sent
+            via ZeroMQ to the internal publication address.
+
+        :param message: The message to send.
         """
         target = AgentDirectory.get(message.to)
         if target:
@@ -101,7 +141,11 @@ class BaseAgent(ABC):
             self.logger.debug(f"Sent message {message.body} to {message.to} via ZMQ.")
 
     async def _process_inbox(self):
-        """Default loop: equivalent to a CyclicBehaviour receiving messages."""
+        """
+        Internal loop that processes messages from the inbox.
+
+        Reads messages from ``self.inbox`` and passes them to :meth:`handle_message`.
+        """
         while self._running:
             msg = await self.inbox.get()
             self.logger.debug(f"Received message from {msg.sender}.")
@@ -109,8 +153,11 @@ class BaseAgent(ABC):
 
     async def _receive_internal_zmq_loop(self):
         """
-        Listens for internal messages sent from agents on another process via ZMQ
-        and puts them into the normal inbox.
+        Internal loop that listens for ZMQ messages.
+
+        Subscribes to ``internal/<agent_name>`` topics. When a message is received,
+        it is deserialized into an :class:`InternalMessage` and put into the local inbox.
+        This bridges the gap between inter-process ZMQ communication and the intra-process inbox.
         """
         while self._running:
             try:
@@ -125,15 +172,24 @@ class BaseAgent(ABC):
                 self.logger.exception("Could not process ZMQ message.")
 
     async def handle_message(self, msg: InternalMessage):
-        """Override this to handle incoming messages."""
+        """
+        Handle an incoming message.
+
+        This method must be overridden by subclasses to define how the agent reacts to messages.
+
+        :param msg: The received message.
+        :raises NotImplementedError: If not overridden by the subclass.
+        """
         raise NotImplementedError
 
     async def add_behavior(self, coro: Coroutine):
         """
-        Helper to add a behavior to the agent. To add asynchronous behavior to an agent, define
-        an `async` function and add it to the task list by calling :func:`add_behavior`
-        with it. This should happen in the :func:`setup` method of the agent. For an example, see:
-        :func:`~control_backend.agents.bdi.BDICoreAgent`.
+        Add a background behavior (task) to the agent.
+
+        This is the preferred way to run continuous loops or long-running tasks within an agent.
+        The task is tracked and will be automatically cancelled when :meth:`stop` is called.
+
+        :param coro: The coroutine to execute as a task.
         """
         task = asyncio.create_task(coro)
         self._tasks.add(task)