refactor(gepa): unify ReAct module key handling and use constant

- Replace all magic string 'react_module' with REACT_MODULE_PREFIX constant
- Unify path normalization pattern across gepa.py and gepa_utils.py
- Rename 'prefix' to 'normalized_path' for clarity
- Simplify module lookup by using consistent normalization
- Remove awkward OR clause in ReAct module matching logic

This makes the codebase more maintainable with a single source of truth
for the module prefix and consistent naming throughout.

Author: Ju-usc

dspy/teleprompt/gepa/gepa.py

@@ -12,7 +12,7 @@
 from dspy.clients.lm import LM
 from dspy.predict.react import ReAct
 from dspy.primitives import Example, Module, Prediction
-from dspy.teleprompt.gepa.gepa_utils import DspyAdapter, DSPyTrace, PredictorFeedbackFn, ScoreWithFeedback
+from dspy.teleprompt.gepa.gepa_utils import DspyAdapter, DSPyTrace, PredictorFeedbackFn, REACT_MODULE_PREFIX, ScoreWithFeedback
 from dspy.teleprompt.teleprompt import Teleprompter
 from dspy.utils.annotation import experimental
 
@@ -539,12 +539,14 @@ def feedback_fn(
                 # Only process ReAct modules
                 if not isinstance(module, ReAct):
                     continue
-                prefix = module_path.removeprefix("self.") if module_path != "self" else ""
+                normalized_path = module_path.removeprefix("self.") if module_path != "self" else ""
 
                 # Get first predictor name as module identifier
                 for pred_name, _ in module.named_predictors():
-                    comp_name = pred_name if not prefix else f"{prefix}.{pred_name}"
-                    module_key = f"react_module:{comp_name.split('.')[0]}" if prefix else "react_module"
+                    comp_name = pred_name if not normalized_path else f"{normalized_path}.{pred_name}"
+                    # Use full normalized path to avoid collapsing nested modules
+                    # e.g., "multi_agent.coordinator" not "multi_agent"
+                    module_key = f"{REACT_MODULE_PREFIX}:{normalized_path}" if normalized_path else REACT_MODULE_PREFIX
 
                     # Build JSON config with tool args for reflection
                     config = {
@@ -563,15 +565,15 @@ def feedback_fn(
 
                     # Replace predictor keys with module key and extract key to prevent duplicates
                     base_program.pop(comp_name, None)
-                    extract_key = f"{prefix}.extract.predict" if prefix else "extract.predict"
+                    extract_key = f"{normalized_path}.extract.predict" if normalized_path else "extract.predict"
                     base_program.pop(extract_key, None)
                     base_program[module_key] = json.dumps(config, indent=2)
                     break
 
         # Log base_program keys for debugging
         logger.info(f"Initialized base_program with {len(base_program)} components:")
         for key in sorted(base_program.keys()):
-            if key.startswith("react_module"):
+            if key.startswith(REACT_MODULE_PREFIX):
                 logger.info(f"  {key}: <ReAct module JSON config>")
             else:
                 logger.info(f"  {key}: <instruction>")

dspy/teleprompt/gepa/gepa_utils.py

@@ -162,8 +162,8 @@ def propose_component_texts(
 
                 # Otherwise, route to appropriate proposers
                 # Separate react_module components from regular instruction components
-                react_module_components = [c for c in components_to_update if c.startswith("react_module")]
-                instruction_components = [c for c in components_to_update if not c.startswith("react_module")]
+                react_module_components = [c for c in components_to_update if c.startswith(REACT_MODULE_PREFIX)]
+                instruction_components = [c for c in components_to_update if not c.startswith(REACT_MODULE_PREFIX)]
 
                 results: dict[str, str] = {}
 
@@ -234,8 +234,8 @@ def build_program(self, candidate: dict[str, str]):
                     continue
 
                 # Build module key
-                prefix = module_path.removeprefix("self.") if module_path != "self" else ""
-                module_key = "react_module" if prefix == "" else f"react_module:{prefix}"
+                normalized_path = module_path.removeprefix("self.") if module_path != "self" else ""
+                module_key = REACT_MODULE_PREFIX if normalized_path == "" else f"{REACT_MODULE_PREFIX}:{normalized_path}"
 
                 # Check if this module was optimized
                 if module_key not in candidate:
@@ -342,16 +342,19 @@ def make_reflective_dataset(
             logger.info(f"Processing component: {pred_name}")
 
             # Handle ReAct module components - use extract predictor for final outputs
-            if pred_name.startswith("react_module"):
+            if pred_name.startswith(REACT_MODULE_PREFIX):
                 # Extract the target path from the key
-                target_path = pred_name.replace("react_module:", "") if ":" in pred_name else ""
+                target_path = pred_name.removeprefix(f"{REACT_MODULE_PREFIX}:") if ":" in pred_name else ""
 
                 # Find the ReAct module by traversing program structure (same as regular predictors)
                 react_module = None
                 for module_path, m in program.named_sub_modules():
-                    clean_path = module_path.removeprefix("self.")
-                    # For top-level ReAct (target_path=""), match "self" or empty string
-                    if isinstance(m, ReAct) and (clean_path == target_path or (target_path == "" and clean_path == "self")):
+                    if not isinstance(m, ReAct):
+                        continue
+                    
+                    # Normalize path (same pattern as build_program)
+                    normalized_path = module_path.removeprefix("self.") if module_path != "self" else ""
+                    if normalized_path == target_path:
                         react_module = m
                         break
 
@@ -392,7 +395,7 @@ def make_reflective_dataset(
                     continue
 
                 # For ReAct modules, use LAST extract invocation (has trajectory + final outputs)
-                if pred_name.startswith("react_module"):
+                if pred_name.startswith(REACT_MODULE_PREFIX):
                     selected = trace_instances[-1]
                     logger.debug(f"  Using LAST extract call ({len(trace_instances)} total) with trajectory + final outputs")
                     if "trajectory" in selected[1]:
@@ -485,7 +488,7 @@ def make_reflective_dataset(
                 items.append(d)
 
                 # Log exact reflective example that reflection LM will see
-                if pred_name.startswith("react_module") and len(items) == 1:
+                if pred_name.startswith(REACT_MODULE_PREFIX) and len(items) == 1:
                     logger.info(f"  First reflective example for {pred_name}:")
                     logger.info(f"    Inputs: {list(d['Inputs'].keys())}")
                     if "trajectory" in d["Inputs"]: