docs: add missing docs

ref: N25B-115

src/control_backend/schemas/program.py

@@ -20,6 +20,10 @@ class ProgramElement(BaseModel):
 
 
 class LogicalOperator(Enum):
+    """
+    Logical operators for combining beliefs.
+    """
+
     AND = "AND"
     OR = "OR"
 
@@ -30,9 +34,9 @@ type BasicBelief = KeywordBelief | SemanticBelief
 
 class KeywordBelief(ProgramElement):
     """
-    Represents a belief that is set when the user spoken text contains a certain keyword.
+    Represents a belief that is activated when a specific keyword is detected in the user's speech.
 
-    :ivar keyword: The keyword on which this belief gets set.
+    :ivar keyword: The string to look for in the transcription.
     """
 
     name: str = ""
@@ -41,9 +45,11 @@ class KeywordBelief(ProgramElement):
 
 class SemanticBelief(ProgramElement):
     """
-    Represents a belief that is set by semantic LLM validation.
+    Represents a belief whose truth value is determined by an LLM analyzing the conversation
+    context.
 
-    :ivar description: Description of how to form the belief, used by the LLM.
+    :ivar description: A natural language description of what this belief represents,
+    used as a prompt for the LLM.
     """
 
     description: str
@@ -51,13 +57,11 @@ class SemanticBelief(ProgramElement):
 
 class InferredBelief(ProgramElement):
     """
-    Represents a belief that gets formed by combining two beliefs with a logical AND or OR.
+    Represents a belief derived from other beliefs using logical operators.
 
-    These beliefs can also be :class:`InferredBelief`, leading to arbitrarily deep nesting.
-
-    :ivar operator: The logical operator to apply.
-    :ivar left: The left part of the logical expression.
-    :ivar right: The right part of the logical expression.
+    :ivar operator: The :class:`LogicalOperator` (AND/OR) to apply.
+    :ivar left: The left operand (another belief).
+    :ivar right: The right operand (another belief).
     """
 
     name: str = ""
@@ -67,6 +71,13 @@ class InferredBelief(ProgramElement):
 
 
 class Norm(ProgramElement):
+    """
+    Base class for behavioral norms that guide the robot's interactions.
+
+    :ivar norm: The textual description of the norm.
+    :ivar critical: Whether this norm is considered critical and should be strictly enforced.
+    """
+
     name: str = ""
     norm: str
     critical: bool = False
@@ -74,10 +85,7 @@ class Norm(ProgramElement):
 
 class BasicNorm(Norm):
     """
-    Represents a behavioral norm.
-
-    :ivar norm: The actual norm text describing the behavior.
-    :ivar critical: When true, this norm should absolutely not be violated (checked separately).
+    A simple behavioral norm that is always considered for activation when its phase is active.
     """
 
     pass
@@ -85,9 +93,9 @@ class BasicNorm(Norm):
 
 class ConditionalNorm(Norm):
     """
-    Represents a norm that is only active when a condition is met (i.e., a certain belief holds).
+    A behavioral norm that is only active when a specific condition (belief) is met.
 
-    :ivar condition: When to activate this norm.
+    :ivar condition: The :class:`Belief` that must hold for this norm to be active.
     """
 
     condition: Belief
@@ -140,9 +148,9 @@ type Action = SpeechAction | GestureAction | LLMAction
 
 class SpeechAction(ProgramElement):
     """
-    Represents the action of the robot speaking a literal text.
+    An action where the robot speaks a predefined literal text.
 
-    :ivar text: The text to speak.
+    :ivar text: The text content to be spoken.
     """
 
     name: str = ""
@@ -151,11 +159,10 @@ class SpeechAction(ProgramElement):
 
 class Gesture(BaseModel):
     """
-    Represents a gesture to be performed. Can be either a single gesture,
-    or a random gesture from a category (tag).
+    Defines a physical gesture for the robot to perform.
 
-    :ivar type: The type of the gesture, "tag" or "single".
-    :ivar name: The name of the single gesture or tag.
+    :ivar type: Whether to use a specific "single" gesture or a random one from a "tag" category.
+    :ivar name: The identifier for the gesture or tag.
     """
 
     type: Literal["tag", "single"]
@@ -164,9 +171,9 @@ class Gesture(BaseModel):
 
 class GestureAction(ProgramElement):
     """
-    Represents the action of the robot performing a gesture.
+    An action where the robot performs a physical gesture.
 
-    :ivar gesture: The gesture to perform.
+    :ivar gesture: The :class:`Gesture` definition.
     """
 
     name: str = ""
@@ -175,10 +182,9 @@ class GestureAction(ProgramElement):
 
 class LLMAction(ProgramElement):
     """
-    Represents the action of letting an LLM generate a reply based on its chat history
-    and an additional goal added in the prompt.
+    An action that triggers an LLM-generated conversational response.
 
-    :ivar goal: The extra (temporary) goal to add to the LLM.
+    :ivar goal: A temporary conversational goal to guide the LLM's response generation.
     """
 
     name: str = ""
@@ -187,10 +193,10 @@ class LLMAction(ProgramElement):
 
 class Trigger(ProgramElement):
     """
-    Represents a belief-based trigger. When a belief is set, the corresponding plan is executed.
+    Defines a reactive behavior: when the condition (belief) is met, the plan is executed.
 
-    :ivar condition: When to activate the trigger.
-    :ivar plan: The plan to execute.
+    :ivar condition: The :class:`Belief` that triggers this behavior.
+    :ivar plan: The :class:`Plan` to execute upon activation.
     """
 
     condition: Belief
@@ -199,11 +205,11 @@ class Trigger(ProgramElement):
 
 class Phase(ProgramElement):
     """
-    A distinct phase within a program, containing norms, goals, and triggers.
+    A logical stage in the interaction program, grouping norms, goals, and triggers.
 
-    :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.
+    :ivar norms: List of norms active during this phase.
+    :ivar goals: List of goals the robot pursues in this phase.
+    :ivar triggers: List of reactive behaviors defined for this phase.
     """
 
     name: str = ""
@@ -214,9 +220,9 @@ class Phase(ProgramElement):
 
 class Program(BaseModel):
     """
-    Represents a complete interaction program, consisting of a sequence or set of phases.
+    The top-level container for a complete robot behavior definition.
 
-    :ivar phases: The list of phases that make up the program.
+    :ivar phases: An ordered list of :class:`Phase` objects defining the interaction flow.
     """
 
     phases: list[Phase]