last changes

mathema/actors/actuator.py

@@ -7,6 +7,33 @@ log = logging.getLogger(__name__)
 
 
 class Actuator(Actor):
+    """
+    Actuator actor responsible for collecting outputs from upstream neurons
+    (fanin), assembling them into an action/output vector, interacting with
+    a scape (environment), and synchronizing the result back to the cortex.
+
+    Conceptually, an Actuator represents the *output layer* of a cortex/agent:
+    - It waits for `forward` messages from all expected fanin sources.
+    - Once all signals are received, they are concatenated in the order
+      defined by `fanin_ids` into a flat output vector.
+    - Depending on `aname`, the output is:
+        * used for debugging/testing ("pts"),
+        * sent directly as an action to a scape ("xor_SendOutput"),
+        * mapped to a car control action and sent to a CarRacing scape
+          ("car_ApplyAction"),
+        * or ignored with a default fitness.
+    - After the interaction, the actuator reports the resulting fitness
+      and halt flag back to the cortex via a `"sync"` message.
+
+    Inbox message protocol:
+    - ("forward", from_id, vec):
+        `from_id` is the ID of the sending fanin neuron,
+        `vec` is its output vector.
+    - ("result", fitness, halt_flag):
+        Response from the scape after an action was applied.
+    - ("terminate",):
+        Terminates the actor.
+    """
     def __init__(self, aid, cx_pid, name, fanin_ids, expect_count, scape=None):
         super().__init__(f"Actuator-{aid}")
         self.aid = aid