test(gepa): add ReAct module detection tests for nested structures

- Add 3 comprehensive detection tests: single ReAct, mixed workflow (2 ReAct + ChainOfThought), orchestrator with 2 workers
- Tests validate full path preservation (bug fix validation)
- Uses monkey patching to capture base_program from gepa.optimize
- Helper functions for DRY: setup spy, create optimizer, assert detection
- Validates all ReAct components: react, extract, tools, tool metadata

Author: Ju-usc

tests/teleprompt/test_gepa_react_optimization.py

@@ -14,6 +14,7 @@
 
 import dspy
 from dspy import Example
+from dspy.utils.dummies import DummyLM
 
 # Load fixture
 with open("tests/teleprompt/gepa_dummy_lm_react_opt.json") as f:
@@ -172,3 +173,262 @@ def metric(example, prediction, trace=None, pred_name=None, pred_trace=None):
         "toolB argument description should be optimized"
     assert optimized.tools["toolC"].arg_desc != baseline_toolC_arg_desc, \
         "toolC argument description should be optimized"
+
+
+def setup_spy_for_base_program(monkeypatch):
+    """Setup spy to capture base_program from gepa.optimize."""
+    captured_base_program = {}
+    
+    from gepa import optimize as original_optimize
+    
+    def spy_optimize(seed_candidate, **kwargs):
+        captured_base_program.update(seed_candidate)
+        return original_optimize(seed_candidate=seed_candidate, **kwargs)
+    
+    import gepa
+    monkeypatch.setattr(gepa, "optimize", spy_optimize)
+    
+    return captured_base_program
+
+
+def create_gepa_optimizer_for_detection():
+    """Create GEPA optimizer with standard test configuration."""
+    task_lm = DummyLM([{"answer": "test"}] * 10)
+    reflection_lm = DummyLM([{"improved_instruction": "optimized"}] * 10)
+    dspy.settings.configure(lm=task_lm)
+    
+    def simple_metric(example, pred, trace=None, pred_name=None, pred_trace=None):
+        return dspy.Prediction(score=0.5, feedback="ok")
+    
+    optimizer = dspy.GEPA(
+        metric=simple_metric,
+        reflection_lm=reflection_lm,
+        max_metric_calls=2,
+        optimize_react_components=True,
+    )
+    
+    trainset = [Example(question="test", answer="test").with_inputs("question")]
+    
+    return optimizer, trainset
+
+
+def assert_react_module_detected(captured_base_program, module_path, expected_tools):
+    """Assert that a ReAct module was detected with all components."""
+    from dspy.teleprompt.gepa.gepa_utils import REACT_MODULE_PREFIX
+    
+    module_key = REACT_MODULE_PREFIX if module_path == "" else f"{REACT_MODULE_PREFIX}:{module_path}"
+    
+    assert module_key in captured_base_program, f"Expected '{module_key}' to be detected"
+    
+    config = json.loads(captured_base_program[module_key])
+    
+    assert "react" in config, f"{module_key} should have react instruction"
+    assert "extract" in config, f"{module_key} should have extract instruction"
+    assert "tools" in config, f"{module_key} should have tools"
+    
+    for tool_name, expected_desc in expected_tools.items():
+        assert tool_name in config["tools"], f"{module_key} should have '{tool_name}' tool"
+        tool = config["tools"][tool_name]
+        assert "desc" in tool, f"{tool_name} should have desc"
+        assert tool["desc"] == expected_desc, f"{tool_name} desc should match"
+        assert "arg_desc" in tool, f"{tool_name} should have arg_desc"
+    
+    return config
+
+
+def assert_regular_module_detected(captured_base_program, module_key):
+    """Assert that a non-ReAct module was detected."""
+    assert module_key in captured_base_program, f"Expected '{module_key}' to be detected"
+    instruction = captured_base_program[module_key]
+    assert isinstance(instruction, str), f"{module_key} should be string instruction, not JSON"
+    return instruction
+
+
+def test_single_react_module_detection(monkeypatch):
+    """Test GEPA detects a single top-level ReAct module."""
+    from dspy.teleprompt.gepa.gepa_utils import REACT_MODULE_PREFIX
+    
+    captured_base_program = setup_spy_for_base_program(monkeypatch)
+    
+    def search_tool(query: str) -> str:
+        """Search for information."""
+        return f"Results for: {query}"
+    
+    def calculate_tool(expr: str) -> str:
+        """Calculate math expression."""
+        return "42"
+    
+    program = dspy.ReAct(
+        "question -> answer",
+        tools=[
+            dspy.Tool(search_tool, name="search", desc="Search the web"),
+            dspy.Tool(calculate_tool, name="calc", desc="Calculate math"),
+        ],
+        max_iters=3
+    )
+    
+    optimizer, trainset = create_gepa_optimizer_for_detection()
+    
+    try:
+        optimizer.compile(program, trainset=trainset, valset=trainset)
+    except:
+        pass
+    
+    module_key = REACT_MODULE_PREFIX
+    assert module_key in captured_base_program, f"Expected '{module_key}' to be detected"
+    
+    assert_react_module_detected(
+        captured_base_program, 
+        "",
+        {"search": "Search the web", "calc": "Calculate math"}
+    )
+
+
+def test_multi_react_workflow_detection(monkeypatch):
+    """Test GEPA detects multiple ReAct modules (tests bug fix for path truncation)."""
+    from dspy.teleprompt.gepa.gepa_utils import REACT_MODULE_PREFIX
+    
+    captured_base_program = setup_spy_for_base_program(monkeypatch)
+    
+    class ResearchWorkflow(dspy.Module):
+        def __init__(self):
+            super().__init__()
+            
+            def search_papers(query: str) -> str:
+                return f"Papers: {query}"
+            
+            def analyze_data(data: str) -> str:
+                return f"Analysis: {data}"
+            
+            self.coordinator = dspy.ReAct(
+                "task -> plan",
+                tools=[dspy.Tool(search_papers, name="search", desc="Search tool")],
+                max_iters=2
+            )
+            
+            self.researcher = dspy.ReAct(
+                "plan -> findings",
+                tools=[dspy.Tool(analyze_data, name="analyze", desc="Analysis tool")],
+                max_iters=2
+            )
+            
+            self.summarizer = dspy.ChainOfThought("findings -> summary")
+        
+        def forward(self, question):
+            plan = self.coordinator(task=question)
+            findings = self.researcher(plan=plan.plan)
+            summary = self.summarizer(findings=findings.findings)
+            return dspy.Prediction(answer=summary.summary)
+    
+    class MixedWorkflowSystem(dspy.Module):
+        def __init__(self):
+            super().__init__()
+            self.workflow = ResearchWorkflow()
+        
+        def forward(self, question):
+            return self.workflow(question=question)
+    
+    program = MixedWorkflowSystem()
+    
+    optimizer, trainset = create_gepa_optimizer_for_detection()
+    
+    try:
+        optimizer.compile(program, trainset=trainset, valset=trainset)
+    except:
+        pass
+    
+    assert f"{REACT_MODULE_PREFIX}:workflow.coordinator" in captured_base_program
+    assert f"{REACT_MODULE_PREFIX}:workflow.researcher" in captured_base_program
+    
+    react_modules = [k for k in captured_base_program.keys() if k.startswith(REACT_MODULE_PREFIX)]
+    assert len(react_modules) == 2, f"Expected 2 ReAct modules, got {len(react_modules)}"
+    
+    assert_react_module_detected(captured_base_program, "workflow.coordinator", {"search": "Search tool"})
+    assert_react_module_detected(captured_base_program, "workflow.researcher", {"analyze": "Analysis tool"})
+    assert_regular_module_detected(captured_base_program, "workflow.summarizer.predict")
+
+
+def test_nested_react_orchestrator_worker_detection(monkeypatch):
+    """Test GEPA detects orchestrator with 2 worker ReAct modules as tools."""
+    from dspy.teleprompt.gepa.gepa_utils import REACT_MODULE_PREFIX
+    
+    captured_base_program = setup_spy_for_base_program(monkeypatch)
+    
+    class OrchestratorWorkerSystem(dspy.Module):
+        def __init__(self):
+            super().__init__()
+            
+            def search_web(query: str) -> str:
+                return f"Search results: {query}"
+            
+            def analyze_data(data: str) -> str:
+                return f"Analysis: {data}"
+            
+            def research_topic(topic: str) -> str:
+                return f"Research: {topic}"
+            
+            self.analyst = dspy.ReAct(
+                "data -> analysis",
+                tools=[dspy.Tool(analyze_data, name="analyze", desc="Analyze data")],
+                max_iters=2
+            )
+            
+            self.researcher = dspy.ReAct(
+                "topic -> findings",
+                tools=[dspy.Tool(research_topic, name="research", desc="Research topic")],
+                max_iters=2
+            )
+            
+            def use_analyst(data: str) -> str:
+                result = self.analyst(data=data)
+                return str(result.analysis) if hasattr(result, 'analysis') else str(result)
+            
+            def use_researcher(topic: str) -> str:
+                result = self.researcher(topic=topic)
+                return str(result.findings) if hasattr(result, 'findings') else str(result)
+            
+            self.orchestrator = dspy.ReAct(
+                "question -> answer",
+                tools=[
+                    dspy.Tool(search_web, name="search", desc="Search tool"),
+                    dspy.Tool(use_analyst, name="analyst", desc="Use analyst"),
+                    dspy.Tool(use_researcher, name="researcher", desc="Use researcher"),
+                ],
+                max_iters=3
+            )
+        
+        def forward(self, question):
+            result = self.orchestrator(question=question)
+            return dspy.Prediction(answer=result.answer)
+    
+    class MultiAgentSystem(dspy.Module):
+        def __init__(self):
+            super().__init__()
+            self.multi_agent = OrchestratorWorkerSystem()
+        
+        def forward(self, question):
+            return self.multi_agent(question=question)
+    
+    program = MultiAgentSystem()
+    
+    optimizer, trainset = create_gepa_optimizer_for_detection()
+    
+    try:
+        optimizer.compile(program, trainset=trainset, valset=trainset)
+    except:
+        pass
+    
+    assert f"{REACT_MODULE_PREFIX}:multi_agent.orchestrator" in captured_base_program
+    assert f"{REACT_MODULE_PREFIX}:multi_agent.analyst" in captured_base_program
+    assert f"{REACT_MODULE_PREFIX}:multi_agent.researcher" in captured_base_program
+    
+    react_modules = [k for k in captured_base_program.keys() if k.startswith(REACT_MODULE_PREFIX)]
+    assert len(react_modules) == 3, f"Expected 3 ReAct modules, got {len(react_modules)}"
+    
+    assert_react_module_detected(
+        captured_base_program,
+        "multi_agent.orchestrator",
+        {"search": "Search tool", "analyst": "Use analyst", "researcher": "Use researcher"}
+    )
+    assert_react_module_detected(captured_base_program, "multi_agent.analyst", {"analyze": "Analyze data"})
+    assert_react_module_detected(captured_base_program, "multi_agent.researcher", {"research": "Research topic"})