docs: add missing docs

ref: N25B-115

src/control_backend/agents/user_interrupt/user_interrupt_agent.py

@@ -50,10 +50,8 @@ class UserInterruptAgent(BaseAgent):
 
     async def setup(self):
         """
-        Initialize the agent.
-
-        Connects the internal ZMQ SUB socket and subscribes to the 'button_pressed' topic.
-        Starts the background behavior to receive the user interrupts.
+        Initialize the agent by setting up ZMQ sockets for receiving button events and
+        publishing updates.
         """
         context = Context.instance()
 
@@ -68,18 +66,15 @@ class UserInterruptAgent(BaseAgent):
 
     async def _receive_button_event(self):
         """
-        The behaviour of the UserInterruptAgent.
-        Continuous loop that receives button_pressed events from the button_pressed HTTP endpoint.
-        These events contain a type and a context.
+        Main loop to receive and process button press events from the UI.
 
-        These are the different types and contexts:
-        - type: "speech", context: string that the robot has to say.
-        - type: "gesture", context: single gesture name that the robot has to perform.
-        - type: "override", context: id that belongs to the goal/trigger/conditional norm.
-        - type: "override_unachieve", context: id that belongs to the conditional norm to unachieve.
-        - type: "next_phase", context: None, indicates to the BDI Core to
-        - type: "pause", context: boolean indicating whether to pause
-        - type: "reset_phase", context: None, indicates to the BDI Core to
+        Handles different event types:
+        - `speech`: Triggers immediate robot speech.
+        - `gesture`: Triggers an immediate robot gesture.
+        - `override`: Forces a belief, trigger, or goal completion in the BDI core.
+        - `override_unachieve`: Removes a belief from the BDI core.
+        - `pause`: Toggles the system's pause state.
+        - `next_phase` / `reset_phase`: Controls experiment flow.
         """
         while True:
             topic, body = await self.sub_socket.recv_multipart()
@@ -172,7 +167,10 @@ class UserInterruptAgent(BaseAgent):
 
     async def handle_message(self, msg: InternalMessage):
         """
-        Handle commands received from other internal Python agents.
+        Handles internal messages from other agents, such as program updates or trigger
+        notifications.
+
+        :param msg: The incoming :class:`~control_backend.core.agent_system.InternalMessage`.
         """
         match msg.thread:
             case "new_program":
@@ -217,8 +215,9 @@ class UserInterruptAgent(BaseAgent):
 
     async def _broadcast_cond_norms(self, active_slugs: list[str]):
         """
-        Sends the current state of all conditional norms to the UI.
-        :param active_slugs: A list of slugs (strings) currently active in the BDI core.
+        Broadcasts the current activation state of all conditional norms to the UI.
+
+        :param active_slugs: A list of sluggified norm names currently active in the BDI core.
         """
         updates = []
         for asl_slug, ui_id in self._cond_norm_reverse_map.items():
@@ -235,7 +234,9 @@ class UserInterruptAgent(BaseAgent):
 
     def _create_mapping(self, program_json: str):
         """
-        Create mappings between UI IDs and ASL slugs for triggers, goals, and conditional norms
+        Creates a bidirectional mapping between UI identifiers and AgentSpeak slugs.
+
+        :param program_json: The JSON representation of the behavioral program.
         """
         try:
             program = Program.model_validate_json(program_json)
@@ -277,8 +278,10 @@ class UserInterruptAgent(BaseAgent):
 
     async def _send_experiment_update(self, data, should_log: bool = True):
         """
-        Sends an update to the 'experiment' topic.
-        The SSE endpoint will pick this up and push it to the UI.
+        Publishes an experiment state update to the internal ZMQ bus for the UI.
+
+        :param data: The update payload.
+        :param should_log: Whether to log the update.
         """
         if self.pub_socket:
             topic = b"experiment"