docs: add docs to CB

Pretty much every class and method should have documentation now.

ref: N25B-295

src/control_backend/agents/bdi/bdi_program_manager.py

@@ -11,8 +11,14 @@ from control_backend.schemas.program import Program
 
 class BDIProgramManager(BaseAgent):
     """
-    Will interpret programs received from the HTTP endpoint. Extracts norms, goals, triggers and
-    forwards them to the BDI as beliefs.
+    BDI Program Manager Agent.
+
+    This agent is responsible for receiving high-level programs (sequences of instructions/goals)
+    from the external HTTP API (via ZMQ) and translating them into core beliefs (norms and goals)
+    for the BDI Core Agent. In the future, it will be responsible for determining when goals are
+    met, and passing on new norms and goals accordingly.
+
+    :ivar sub_socket: The ZMQ SUB socket used to receive program updates.
     """
 
     def __init__(self, **kwargs):
@@ -20,6 +26,18 @@ class BDIProgramManager(BaseAgent):
         self.sub_socket = None
 
     async def _send_to_bdi(self, program: Program):
+        """
+        Convert a received program into BDI beliefs and send them to the BDI Core Agent.
+
+        Currently, it takes the **first phase** of the program and extracts:
+        -   **Norms**: Constraints or rules the agent must follow.
+        -   **Goals**: Objectives the agent must achieve.
+
+        These are sent as a ``BeliefMessage`` with ``replace=True``, meaning they will
+        overwrite any existing norms/goals of the same name in the BDI agent.
+
+        :param program: The program object received from the API.
+        """
         first_phase = program.phases[0]
         norms_belief = Belief(
             name="norms",
@@ -44,7 +62,10 @@ class BDIProgramManager(BaseAgent):
 
     async def _receive_programs(self):
         """
-        Continuously receive programs from the HTTP endpoint, sent to us over ZMQ.
+        Continuous loop that receives program updates from the HTTP endpoint.
+
+        It listens to the ``program`` topic on the internal ZMQ SUB socket.
+        When a program is received, it is validated and forwarded to BDI via :meth:`_send_to_bdi`.
         """
         while True:
             topic, body = await self.sub_socket.recv_multipart()
@@ -58,6 +79,12 @@ class BDIProgramManager(BaseAgent):
             await self._send_to_bdi(program)
 
     async def setup(self):
+        """
+        Initialize the agent.
+
+        Connects the internal ZMQ SUB socket and subscribes to the 'program' topic.
+        Starts the background behavior to receive programs.
+        """
         context = Context.instance()
 
         self.sub_socket = context.socket(zmq.SUB)