docs: add docs to CB

Pretty much every class and method should have documentation now.

ref: N25B-295

src/control_backend/agents/bdi/belief_collector_agent.py

@@ -10,14 +10,33 @@ from control_backend.schemas.belief_message import Belief, BeliefMessage
 
 class BDIBeliefCollectorAgent(BaseAgent):
     """
-    Continuously collects beliefs/emotions from extractor agents and forwards a
-    unified belief packet to the BDI agent.
+    BDI Belief Collector Agent.
+
+    This agent acts as a central aggregator for beliefs derived from various sources (e.g., text,
+    emotion, vision). It receives raw extracted data from other agents,
+    normalizes them into valid :class:`Belief` objects, and forwards them as a unified packet to the
+    BDI Core Agent.
+
+    It serves as a funnel to ensure the BDI agent receives a consistent stream of beliefs.
     """
 
     async def setup(self):
+        """
+        Initialize the agent.
+        """
         self.logger.info("Setting up %s", self.name)
 
     async def handle_message(self, msg: InternalMessage):
+        """
+        Handle incoming messages from other extractor agents.
+
+        Routes the message to specific handlers based on the 'type' field in the JSON body.
+        Supported types:
+        -   ``belief_extraction_text``: Handled by :meth:`_handle_belief_text`
+        -   ``emotion_extraction_text``: Handled by :meth:`_handle_emo_text`
+
+        :param msg: The received internal message.
+        """
         sender_node = msg.sender
 
         # Parse JSON payload
@@ -49,12 +68,22 @@ class BDIBeliefCollectorAgent(BaseAgent):
 
     async def _handle_belief_text(self, payload: dict, origin: str):
         """
-        Expected payload:
-        {
-            "type": "belief_extraction_text",
-            "beliefs": {"user_said": ["Can you help me?"]}
+        Process text-based belief extraction payloads.
 
-        }
+        Expected payload format::
+
+            {
+                "type": "belief_extraction_text",
+                "beliefs": {
+                    "user_said": ["Can you help me?"],
+                    "intention": ["ask_help"]
+                }
+            }
+
+        Validates and converts the dictionary items into :class:`Belief` objects.
+
+        :param payload: The dictionary payload containing belief data.
+        :param origin: The name of the sender agent.
         """
         beliefs = payload.get("beliefs", {})
 
@@ -90,12 +119,24 @@ class BDIBeliefCollectorAgent(BaseAgent):
         await self._send_beliefs_to_bdi(beliefs, origin=origin)
 
     async def _handle_emo_text(self, payload: dict, origin: str):
-        """TODO: implement (after we have emotional recognition)"""
+        """
+        Process emotion extraction payloads.
+
+        **TODO**: Implement this method once emotion recognition is integrated.
+
+        :param payload: The dictionary payload containing emotion data.
+        :param origin: The name of the sender agent.
+        """
         pass
 
     async def _send_beliefs_to_bdi(self, beliefs: list[Belief], origin: str | None = None):
         """
-        Sends a unified belief packet to the BDI agent.
+        Send a list of aggregated beliefs to the BDI Core Agent.
+
+        Wraps the beliefs in a :class:`BeliefMessage` and sends it via the 'beliefs' thread.
+
+        :param beliefs: The list of Belief objects to send.
+        :param origin: (Optional) The original source of the beliefs (unused currently).
         """
         if not beliefs:
             return