last changes

mathema/core/morphology.py

@@ -12,6 +12,16 @@ def generate_id() -> str:
 
 
 def get_InitSensor(morphology: MorphologyType):
+    """
+    Return the initial sensor configuration for a given morphology.
+
+    This helper selects a minimal starting set of sensors used to bootstrap a
+    new agent's morphology. It resolves the full sensor list for the provided
+    morphology and returns a list containing only the first sensor entry.
+
+    Raises:
+        ValueError: If the resolved morphology provides no sensors.
+    """
     sensors = get_Sensors(morphology)
     if not sensors:
         log.error("Morphology has no sensors.")
@@ -20,6 +30,17 @@ def get_InitSensor(morphology: MorphologyType):
 
 
 def get_InitActuator(morphology: MorphologyType):
+    """
+    Return the initial actuator configuration for a given morphology.
+
+    This helper selects a minimal starting set of actuators used to bootstrap
+    a new agent's morphology. It resolves the full actuator list for the
+    provided morphology and returns a list containing only the first actuator
+    entry.
+
+    Raises:
+        ValueError: If the resolved morphology provides no actuators.
+    """
     actuators = get_Actuators(morphology)
     if not actuators:
         log.error("Morphology has no actuators.")
@@ -28,22 +49,74 @@ def get_InitActuator(morphology: MorphologyType):
 
 
 def get_Sensors(morphology: MorphologyType) -> List[Dict[str, Any]]:
+    """
+    Resolve and return the list of sensor specifications for a morphology.
+
+    The morphology may be provided as:
+    - a callable that accepts a kind string ("sensors" or "actuators"),
+    - a registered string key mapping to a known morphology implementation,
+    - or a module-like object exposing a callable 'xor_mimic' function.
+
+    Args:
+        morphology: Morphology selector (callable, string key, or module-like).
+
+    Returns:
+        A list of sensor specification dictionaries, each describing a sensor
+        actor (e.g., name, vector length, and associated scape).
+    """
     fn = _resolve_morphology(morphology)
     return fn("sensors")
 
 
 def get_Actuators(morphology: MorphologyType) -> List[Dict[str, Any]]:
+    """
+    Resolve and return the list of actuator specifications for a morphology.
+
+    The morphology may be provided as:
+    - a callable that accepts a kind string ("sensors" or "actuators"),
+    - a registered string key mapping to a known morphology implementation,
+    - or a module-like object exposing a callable 'xor_mimic' function.
+
+    Args:
+        morphology: Morphology selector (callable, string key, or module-like).
+
+    Returns:
+        A list of actuator specification dictionaries, each describing an
+        actuator actor (e.g., name, vector length, and associated scape).
+    """
     fn = _resolve_morphology(morphology)
     return fn("actuators")
 
 
 def _resolve_morphology(morphology: MorphologyType) -> Callable[[str], List[Dict[str, Any]]]:
+    """
+    Resolve a morphology selector into a callable that can produce sensor or actuator specs.
+
+    This function normalizes different morphology representations into a
+    single callable interface: fn(kind) -> List[Dict[str, Any]]. Supported
+    inputs are:
+
+    - A callable: returned as-is.
+    - A string key: looked up in a registry of known morphologies.
+    - A module-like object: if it exposes a callable attribute 'xor_mimic',
+      that callable is used.
+
+    Args:
+        morphology: Morphology selector (callable, string key, or module-like).
+
+    Returns:
+        A callable that accepts "sensors" or "actuators" and returns the
+        corresponding specification list.
+
+    Raises:
+        ValueError: If a string key is provided but not registered.
+        TypeError: If morphology cannot be resolved to a valid callable.
+    """
     if callable(morphology):
         return morphology
 
     if isinstance(morphology, str):
         reg = {
-            "xor_mimic": xor_mimic,
             "car_racing_features": car_racing_features
         }
         if morphology in reg:
@@ -62,31 +135,23 @@ def _resolve_morphology(morphology: MorphologyType) -> Callable[[str], List[Dict
     raise TypeError("morphology must be a callable, a module with 'xor_mimic', or a registered string key")
 
 
-def xor_mimic(kind: str) -> List[Dict[str, Any]]:
-    if kind == "sensors":
-        return [
-            {
-                "name": "xor_GetInput",
-                "vector_length": 2,
-                "scape": "xor_sim"
-            }
-        ]
-    elif kind == "actuators":
-        return [
-            {
-                "name": "xor_SendOutput",
-                "vector_length": 1,
-                "scape": "xor_sim"
-            }
-        ]
-    else:
-        log.error(f"xor_mimic: unsupported kind '{kind}', expected 'sensors' or 'actuators'")
-        raise ValueError(f"xor_mimic: unsupported kind '{kind}', expected 'sensors' or 'actuators'")
-
-
 def car_racing_features(kind: str) -> List[Dict[str, Any]]:
     """
-    car racing morphology
+    Provide a feature-based CarRacing morphology specification.
+
+    This morphology exposes:
+    - One sensor ("car_GetFeatures") producing a fixed-length feature vector
+      derived from a look-ahead horizon plus additional scalar features.
+    - One actuator ("car_ApplyAction") consuming a 3-element action vector.
+
+    Args:
+        kind: Either "sensors" or "actuators".
+
+    Returns:
+        A list containing a single specification dictionary for the requested kind.
+
+    Raises:
+        ValueError: If kind is not "sensors" or "actuators".
     """
     LOOK_AHEAD = 10
     feature_len = LOOK_AHEAD + 6