docs: add missing docs

ref: N25B-115

src/control_backend/agents/__init__.py

@@ -1 +1,5 @@
+"""
+This package contains all agent implementations for the PepperPlus Control Backend.
+"""
+
 from .base import BaseAgent as BaseAgent

src/control_backend/agents/actuation/__init__.py

@@ -1,2 +1,6 @@
+"""
+Agents responsible for controlling the robot's physical actions, such as speech and gestures.
+"""
+
 from .robot_gesture_agent import RobotGestureAgent as RobotGestureAgent
 from .robot_speech_agent import RobotSpeechAgent as RobotSpeechAgent

src/control_backend/agents/bdi/__init__.py

@@ -1,3 +1,8 @@
+"""
+Agents and utilities for the BDI (Belief-Desire-Intention) reasoning system,
+implementing AgentSpeak(L) logic.
+"""
+
 from control_backend.agents.bdi.bdi_core_agent import BDICoreAgent as BDICoreAgent
 
 from .text_belief_extractor_agent import (

src/control_backend/agents/bdi/agentspeak_ast.py

@@ -80,7 +80,7 @@ class AstTerm(AstExpression, ABC):
 @dataclass(eq=False)
 class AstAtom(AstTerm):
     """
-    Grounded expression in all lowercase.
+    Represents a grounded atom in AgentSpeak (e.g., lowercase constants).
     """
 
     value: str
@@ -92,7 +92,7 @@ class AstAtom(AstTerm):
 @dataclass(eq=False)
 class AstVar(AstTerm):
     """
-    Ungrounded variable expression. First letter capitalized.
+    Represents an ungrounded variable in AgentSpeak (e.g., capitalized names).
     """
 
     name: str
@@ -103,6 +103,10 @@ class AstVar(AstTerm):
 
 @dataclass(eq=False)
 class AstNumber(AstTerm):
+    """
+    Represents a numeric constant in AgentSpeak.
+    """
+
     value: int | float
 
     def _to_agentspeak(self) -> str:
@@ -111,6 +115,10 @@ class AstNumber(AstTerm):
 
 @dataclass(eq=False)
 class AstString(AstTerm):
+    """
+    Represents a string literal in AgentSpeak.
+    """
+
     value: str
 
     def _to_agentspeak(self) -> str:
@@ -119,6 +127,10 @@ class AstString(AstTerm):
 
 @dataclass(eq=False)
 class AstLiteral(AstTerm):
+    """
+    Represents a literal (functor and terms) in AgentSpeak.
+    """
+
     functor: str
     terms: list[AstTerm] = field(default_factory=list)
 
@@ -142,6 +154,10 @@ class BinaryOperatorType(StrEnum):
 
 @dataclass
 class AstBinaryOp(AstExpression):
+    """
+    Represents a binary logical or relational operation in AgentSpeak.
+    """
+
     left: AstExpression
     operator: BinaryOperatorType
     right: AstExpression
@@ -167,6 +183,10 @@ class AstBinaryOp(AstExpression):
 
 @dataclass
 class AstLogicalExpression(AstExpression):
+    """
+    Represents a logical expression, potentially negated, in AgentSpeak.
+    """
+
     expression: AstExpression
     negated: bool = False
 
@@ -208,6 +228,10 @@ class AstStatement(AstNode):
 
 @dataclass
 class AstRule(AstNode):
+    """
+    Represents an inference rule in AgentSpeak. If there is no condition, it always holds.
+    """
+
     result: AstExpression
     condition: AstExpression | None = None
 
@@ -231,6 +255,10 @@ class TriggerType(StrEnum):
 
 @dataclass
 class AstPlan(AstNode):
+    """
+    Represents a plan in AgentSpeak, consisting of a trigger, context, and body.
+    """
+
     type: TriggerType
     trigger_literal: AstExpression
     context: list[AstExpression]
@@ -260,6 +288,10 @@ class AstPlan(AstNode):
 
 @dataclass
 class AstProgram(AstNode):
+    """
+    Represents a full AgentSpeak program, consisting of rules and plans.
+    """
+
     rules: list[AstRule] = field(default_factory=list)
     plans: list[AstPlan] = field(default_factory=list)
 

src/control_backend/agents/bdi/agentspeak_generator.py

@@ -40,9 +40,23 @@ from control_backend.schemas.program import (
 
 
 class AgentSpeakGenerator:
+    """
+    Generator class that translates a high-level :class:`~control_backend.schemas.program.Program`
+    into AgentSpeak(L) source code.
+
+    It handles the conversion of phases, norms, goals, and triggers into AgentSpeak rules and plans,
+    ensuring the robot follows the defined behavioral logic.
+    """
+
     _asp: AstProgram
 
     def generate(self, program: Program) -> str:
+        """
+        Translates a Program object into an AgentSpeak source string.
+
+        :param program: The behavior program to translate.
+        :return: The generated AgentSpeak code as a string.
+        """
         self._asp = AstProgram()
 
         if program.phases:

src/control_backend/agents/bdi/text_belief_extractor_agent.py

@@ -18,6 +18,12 @@ type JSONLike = None | bool | int | float | str | list["JSONLike"] | dict[str, "
 
 
 class BeliefState(BaseModel):
+    """
+    Represents the state of inferred semantic beliefs.
+
+    Maintains sets of beliefs that are currently considered true or false.
+    """
+
     true: set[InternalBelief] = set()
     false: set[InternalBelief] = set()
 
@@ -338,7 +344,7 @@ class TextBeliefExtractorAgent(BaseAgent):
 
 class SemanticBeliefInferrer:
     """
-    Class that handles only prompting an LLM for semantic beliefs.
+    Infers semantic beliefs from conversation history using an LLM.
     """
 
     def __init__(
@@ -464,6 +470,10 @@ Respond with a JSON similar to the following, but with the property names as giv
 
 
 class GoalAchievementInferrer(SemanticBeliefInferrer):
+    """
+    Infers whether specific conversational goals have been achieved using an LLM.
+    """
+
     def __init__(self, llm: TextBeliefExtractorAgent.LLM):
         super().__init__(llm)
         self.goals: set[BaseGoal] = set()

src/control_backend/agents/communication/__init__.py

@@ -1 +1,5 @@
+"""
+Agents responsible for external communication and service discovery.
+"""
+
 from .ri_communication_agent import RICommunicationAgent as RICommunicationAgent

src/control_backend/agents/llm/__init__.py

@@ -1 +1,5 @@
+"""
+Agents that interface with Large Language Models for natural language processing and generation.
+"""
+
 from .llm_agent import LLMAgent as LLMAgent

src/control_backend/agents/perception/__init__.py

@@ -1,3 +1,8 @@
+"""
+Agents responsible for processing sensory input, such as audio transcription and voice activity
+detection.
+"""
+
 from .transcription_agent.transcription_agent import (
     TranscriptionAgent as TranscriptionAgent,
 )

src/control_backend/agents/perception/transcription_agent/transcription_agent.py

@@ -74,7 +74,7 @@ class TranscriptionAgent(BaseAgent):
 
     def _connect_audio_in_socket(self):
         """
-        Helper to connect the ZMQ SUB socket for audio input.
+        Connects the ZMQ SUB socket for receiving audio data.
         """
         self.audio_in_socket = azmq.Context.instance().socket(zmq.SUB)
         self.audio_in_socket.setsockopt_string(zmq.SUBSCRIBE, "")

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"