docs: add docs to CB

Pretty much every class and method should have documentation now.

ref: N25B-295

src/control_backend/schemas/belief_message.py

@@ -2,10 +2,22 @@ from pydantic import BaseModel
 
 
 class Belief(BaseModel):
+    """
+    Represents a single belief in the BDI system.
+
+    :ivar name: The functor or name of the belief (e.g., 'user_said').
+    :ivar arguments: A list of string arguments for the belief.
+    :ivar replace: If True, existing beliefs with this name should be replaced by this one.
+    """
+
     name: str
     arguments: list[str]
     replace: bool = False
 
 
 class BeliefMessage(BaseModel):
+    """
+    A container for transporting a list of beliefs between agents.
+    """
+
     beliefs: list[Belief]

src/control_backend/schemas/internal_message.py

@@ -3,7 +3,12 @@ from pydantic import BaseModel
 
 class InternalMessage(BaseModel):
     """
-    Represents a message to an agent.
+    Standard message envelope for communication between agents within the Control Backend.
+
+    :ivar to: The name of the destination agent.
+    :ivar sender: The name of the sending agent.
+    :ivar body: The string payload (often a JSON-serialized model).
+    :ivar thread: An optional thread identifier/topic to categorize the message (e.g., 'beliefs').
     """
 
     to: str

src/control_backend/schemas/llm_prompt_message.py

@@ -2,6 +2,17 @@ from pydantic import BaseModel
 
 
 class LLMPromptMessage(BaseModel):
+    """
+    Payload sent from the BDI agent to the LLM agent.
+
+    Contains the user's text input along with the dynamic context (norms and goals)
+    that the LLM should use to generate a response.
+
+    :ivar text: The user's input text.
+    :ivar norms: A list of active behavioral norms.
+    :ivar goals: A list of active goals to pursue.
+    """
+
     text: str
     norms: list[str]
     goals: list[str]

src/control_backend/schemas/message.py

@@ -2,4 +2,8 @@ from pydantic import BaseModel
 
 
 class Message(BaseModel):
+    """
+    A simple generic message wrapper, typically used for simple API responses.
+    """
+
     message: str

src/control_backend/schemas/program.py

@@ -2,12 +2,29 @@ from pydantic import BaseModel
 
 
 class Norm(BaseModel):
+    """
+    Represents a behavioral norm.
+
+    :ivar id: Unique identifier.
+    :ivar label: Human-readable label.
+    :ivar norm: The actual norm text describing the behavior.
+    """
+
     id: str
     label: str
     norm: str
 
 
 class Goal(BaseModel):
+    """
+    Represents an objective to be achieved.
+
+    :ivar id: Unique identifier.
+    :ivar label: Human-readable label.
+    :ivar description: Detailed description of the goal.
+    :ivar achieved: Status flag indicating if the goal has been met.
+    """
+
     id: str
     label: str
     description: str
@@ -27,6 +44,16 @@ class KeywordTrigger(BaseModel):
 
 
 class Phase(BaseModel):
+    """
+    A distinct phase within a program, containing norms, goals, and triggers.
+
+    :ivar id: Unique identifier.
+    :ivar label: Human-readable label.
+    :ivar norms: List of norms active in this phase.
+    :ivar goals: List of goals to pursue in this phase.
+    :ivar triggers: List of triggers that define transitions out of this phase.
+    """
+
     id: str
     label: str
     norms: list[Norm]
@@ -35,4 +62,10 @@ class Phase(BaseModel):
 
 
 class Program(BaseModel):
+    """
+    Represents a complete interaction program, consisting of a sequence or set of phases.
+
+    :ivar phases: The list of phases that make up the program.
+    """
+
     phases: list[Phase]

src/control_backend/schemas/ri_message.py

@@ -5,16 +5,34 @@ from pydantic import BaseModel
 
 
 class RIEndpoint(str, Enum):
+    """
+    Enumeration of valid endpoints for the Robot Interface (RI).
+    """
+
     SPEECH = "actuate/speech"
     PING = "ping"
     NEGOTIATE_PORTS = "negotiate/ports"
 
 
 class RIMessage(BaseModel):
+    """
+    Base schema for messages sent to the Robot Interface.
+
+    :ivar endpoint: The target endpoint/action on the RI.
+    :ivar data: The payload associated with the action.
+    """
+
     endpoint: RIEndpoint
     data: Any
 
 
 class SpeechCommand(RIMessage):
+    """
+    A specific command to make the robot speak.
+
+    :ivar endpoint: Fixed to ``RIEndpoint.SPEECH``.
+    :ivar data: The text string to be spoken.
+    """
+
     endpoint: RIEndpoint = RIEndpoint(RIEndpoint.SPEECH)
     data: str