Merge remote-tracking branch 'origin/feat/reset-experiment-and-phase' into feat/visual-emotion-recognition

src/control_backend/schemas/belief_list.py

@@ -0,0 +1,19 @@
+from pydantic import BaseModel
+
+from control_backend.schemas.program import BaseGoal
+from control_backend.schemas.program import Belief as ProgramBelief
+
+
+class BeliefList(BaseModel):
+    """
+    Represents a list of beliefs, separated from a program. Useful in agents which need to
+    communicate beliefs.
+
+    :ivar: beliefs: The list of beliefs.
+    """
+
+    beliefs: list[ProgramBelief]
+
+
+class GoalList(BaseModel):
+    goals: list[BaseGoal]

src/control_backend/schemas/belief_message.py

@@ -6,20 +6,30 @@ 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.
-    :ivar remove: If True, this belief should be removed from the belief base.
+    :ivar arguments: A list of string arguments for the belief, or None if the belief has no
+        arguments.
     """
 
     name: str
-    arguments: list[str]
-    replace: bool = False
-    remove: bool = False
+    arguments: list[str] | None = None
+
+    # To make it hashable
+    model_config = {"frozen": True}
 
 
 class BeliefMessage(BaseModel):
     """
-    A container for transporting a list of beliefs between agents.
+    A container for communicating beliefs between agents.
+
+    :ivar create: Beliefs to create.
+    :ivar delete: Beliefs to delete.
+    :ivar replace: Beliefs to replace. Deletes all beliefs with the same name, replacing them with
+        one new belief.
     """
 
-    beliefs: list[Belief]
+    create: list[Belief] = []
+    delete: list[Belief] = []
+    replace: list[Belief] = []
+
+    def has_values(self) -> bool:
+        return len(self.create) > 0 or len(self.delete) > 0 or len(self.replace) > 0

src/control_backend/schemas/chat_history.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel
+
+
+class ChatMessage(BaseModel):
+    role: str
+    content: str
+
+
+class ChatHistory(BaseModel):
+    messages: list[ChatMessage]

src/control_backend/schemas/internal_message.py

@@ -14,6 +14,6 @@ class InternalMessage(BaseModel):
     """
 
     to: str | Iterable[str]
-    sender: str
+    sender: str | None = None
     body: str
     thread: str | None = None

src/control_backend/schemas/program.py

@@ -1,64 +1,215 @@
-from pydantic import BaseModel
+from enum import Enum
+from typing import Literal
+
+from pydantic import UUID4, 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: UUID4
+
+    # To make program elements hashable
+    model_config = {"frozen": True}
 
 
-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 = ""
     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.
+    """
+
+    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 = ""
+    operator: LogicalOperator
+    left: Belief
+    right: Belief
+
+
+class Norm(ProgramElement):
+    name: str = ""
+    norm: str
+    critical: bool = False
+
+
+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).
+    """
+
+    pass
+
+
+class ConditionalNorm(Norm):
+    """
+    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.
+    """
+
+    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 = ""
+    steps: list[PlanElement]
+
+
+class BaseGoal(ProgramElement):
+    """
+    Represents an objective to be achieved. This base version does not include a plan to achieve
+    this goal, and is used in semantic belief extraction.
+
+    :ivar description: A description of the goal, used to determine if it has been achieved.
+    :ivar can_fail: Whether we can fail to achieve the goal after executing the plan.
+    """
+
+    description: str = ""
+    can_fail: bool = True
+
+
+class Goal(BaseGoal):
+    """
+    Represents an objective to be achieved. To reach the goal, we should execute the corresponding
+    plan. It inherits from the BaseGoal a variable `can_fail`, which if true will cause the
+    completion to be determined based on the conversation.
+
+    Instances of this goal are not hashable because a plan is not hashable.
+
+    :ivar plan: The plan to execute.
+    """
+
+    plan: Plan
+
+
+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 = ""
+    text: str
+
+
+class Gesture(BaseModel):
+    """
+    Represents a gesture to be performed. Can be either a single gesture,
+    or a random gesture from a category (tag).
+
+    :ivar type: The type of the gesture, "tag" or "single".
+    :ivar name: The name of the single gesture or tag.
+    """
+
+    type: Literal["tag", "single"]
+    name: str
+
+
+class GestureAction(ProgramElement):
+    """
+    Represents the action of the robot performing a gesture.
+
+    :ivar gesture: The gesture to perform.
+    """
+
+    name: str = ""
+    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 = ""
+    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.
+    """
+
+    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
-    norms: list[Norm]
+    name: str = ""
+    norms: list[BasicNorm | ConditionalNorm]
     goals: list[Goal]
-    triggers: list[KeywordTrigger]
+    triggers: list[Trigger]
 
 
 class Program(BaseModel):

src/control_backend/schemas/ri_message.py

@@ -14,6 +14,7 @@ class RIEndpoint(str, Enum):
     GESTURE_TAG = "actuate/gesture/tag"
     PING = "ping"
     NEGOTIATE_PORTS = "negotiate/ports"
+    PAUSE = ""
 
 
 class RIMessage(BaseModel):
@@ -64,3 +65,15 @@ class GestureCommand(RIMessage):
         if self.endpoint not in allowed:
             raise ValueError("endpoint must be GESTURE_SINGLE or GESTURE_TAG")
         return self
+
+
+class PauseCommand(RIMessage):
+    """
+    A specific command to pause or unpause the robot's actions.
+
+    :ivar endpoint: Fixed to ``RIEndpoint.PAUSE``.
+    :ivar data: A boolean indicating whether to pause (True) or unpause (False).
+    """
+
+    endpoint: RIEndpoint = RIEndpoint(RIEndpoint.PAUSE)
+    data: bool