docs: add missing docs

ref: N25B-115

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)