refactor: program restructure

Also includes some AgentSpeak generation.

ref: N25B-376

src/control_backend/schemas/program.py

@@ -1,64 +1,204 @@
+from enum import Enum
+
 from pydantic import BaseModel
 
 
-class Norm(BaseModel):
+class ProgramElement(BaseModel):
     """
-    Represents a behavioral norm.
+    Represents a basic element of our behavior program.
 
+    :ivar name: The researcher-assigned name of the element.
     :ivar id: Unique identifier.
-    :ivar label: Human-readable label.
-    :ivar norm: The actual norm text describing the behavior.
     """
 
-    id: str
-    label: str
-    norm: str
+    name: str
+    id: int
 
 
-class Goal(BaseModel):
+class LogicalOperator(Enum):
+    AND = "AND"
+    OR = "OR"
+
+
+type Belief = KeywordBelief | SemanticBelief | InferredBelief
+type BasicBelief = KeywordBelief | SemanticBelief
+
+
+class KeywordBelief(ProgramElement):
     """
-    Represents an objective to be achieved.
+    Represents a belief that is set when the user spoken text contains a certain keyword.
 
-    :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.
+    :ivar keyword: The keyword on which this belief gets set.
     """
 
-    id: str
-    label: str
-    description: str
-    achieved: bool
-
-
-class TriggerKeyword(BaseModel):
-    id: str
+    name: str = ""
+    id: int = -1
     keyword: str
 
 
-class KeywordTrigger(BaseModel):
-    id: str
-    label: str
-    type: str
-    keywords: list[TriggerKeyword]
+class SemanticBelief(ProgramElement):
+    """
+    Represents a belief that is set by semantic LLM validation.
+
+    :ivar description: Description of how to form the belief, used by the LLM.
+    """
+
+    name: str = ""
+    id: int = -1
+    description: str
 
 
-class Phase(BaseModel):
+class InferredBelief(ProgramElement):
+    """
+    Represents a belief that gets formed by combining two beliefs with a logical AND or OR.
+
+    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.
+    """
+
+    name: str = ""
+    id: int = -1
+    operator: LogicalOperator
+    left: Belief
+    right: Belief
+
+
+type Norm = BasicNorm | ConditionalNorm
+
+
+class BasicNorm(ProgramElement):
+    """
+    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).
+    """
+
+    name: str = ""
+    id: int = -1
+    norm: str
+    critical: bool = False
+
+
+class ConditionalNorm(BasicNorm):
+    """
+    Represents a norm that is only active when a condition is met (i.e., a certain belief holds).
+
+    :ivar condition: When to activate this norm.
+    """
+
+    name: str = ""
+    id: int = -1
+    condition: Belief
+
+
+type PlanElement = Goal | Action
+
+
+class Plan(ProgramElement):
+    """
+    Represents a list of steps to execute. Each of these steps can be a goal (with its own plan)
+    or a simple action.
+
+    :ivar steps: The actions or subgoals to execute, in order.
+    """
+
+    name: str = ""
+    id: int = -1
+    steps: list[PlanElement]
+
+
+class Goal(ProgramElement):
+    """
+    Represents an objective to be achieved. To reach the goal, we should execute
+    the corresponding plan. If we can fail to achieve a goal after executing the plan,
+    for example when the achieving of the goal is dependent on the user's reply, this means
+    that the achieved status will be set from somewhere else in the program.
+
+    :ivar plan: The plan to execute.
+    :ivar can_fail: Whether we can fail to achieve the goal after executing the plan.
+    """
+
+    id: int = -1
+    plan: Plan
+    can_fail: bool = True
+
+
+type Action = SpeechAction | GestureAction | LLMAction
+
+
+class SpeechAction(ProgramElement):
+    """
+    Represents the action of the robot speaking a literal text.
+
+    :ivar text: The text to speak.
+    """
+
+    name: str = ""
+    id: int = -1
+    text: str
+
+
+# TODO: gestures
+class Gesture(Enum):
+    RAISE_HAND = "RAISE_HAND"
+
+
+class GestureAction(ProgramElement):
+    """
+    Represents the action of the robot performing a gesture.
+
+    :ivar gesture: The gesture to perform.
+    """
+
+    name: str = ""
+    id: int = -1
+    gesture: Gesture
+
+
+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.
+
+    :ivar goal: The extra (temporary) goal to add to the LLM.
+    """
+
+    name: str = ""
+    id: int = -1
+    goal: str
+
+
+class Trigger(ProgramElement):
+    """
+    Represents a belief-based trigger. When a belief is set, the corresponding plan is executed.
+
+    :ivar condition: When to activate the trigger.
+    :ivar plan: The plan to execute.
+    """
+
+    name: str = ""
+    id: int = -1
+    condition: Belief
+    plan: Plan
+
+
+class Phase(ProgramElement):
     """
     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
+    name: str = ""
     norms: list[Norm]
     goals: list[Goal]
-    triggers: list[KeywordTrigger]
+    triggers: list[Trigger]
 
 
 class Program(BaseModel):