last changes

mathema/actors/cortex.py

@@ -6,6 +6,41 @@ log = logging.getLogger(__name__)
 
 
 class Cortex(Actor):
+    """
+        Cortex actor coordinating a network of Sensors, Neurons, and Actuators.
+
+        The Cortex is responsible for driving the network forward in discrete
+        computation cycles, collecting fitness feedback from all actuators, and
+        reporting evaluation results to an Exoself (supervisor) actor.
+
+        High-level behavior:
+        - At the start of an episode, the cortex triggers a new cycle:
+            1) It tells all neurons to prepare recurrent state for the new cycle
+               via ("cycle_start",).
+            2) It optionally triggers neurons via ("tick",) (scheduler hook).
+            3) It tells all sensors to produce outputs via ("sync",).
+        - Actuators eventually send back ("sync", aid, fitness, halt_flag).
+        - Once all actuators have synchronized for the current cycle, the cortex
+          either:
+            * ends the evaluation if any actuator requested a halt (halt_flag > 0),
+              and reports ("evaluation_completed", total_fitness, cycles, elapsed)
+              to the exoself, or
+            * starts the next cycle.
+
+        Message protocol (inbox):
+        - ("register_actuators", aids):
+            Provide/replace the set of actuator IDs that must sync each cycle.
+            Used when actuators are created dynamically or not known at init.
+        - ("sync", aid, fitness, halt_flag):
+            Fitness feedback from an actuator for the current cycle.
+            The cortex accumulates fitness and checks halt conditions.
+        - ("reactivate",):
+            Restart a new evaluation episode (reset counters and kick sensors).
+        - ("terminate",):
+            Terminate the cortex and cascade termination to sensors/neurons/actuators.
+        - ("backup_from_neuron", nid, idps...):
+            Forward neuron backup data upstream to the exoself.
+        """
     def __init__(self, cid, exoself_pid, sensor_pids, neuron_pids, actuator_pids):
         super().__init__(f"Cortex-{cid}")
         self.cid = cid