feat: SPEC_15 Advanced Mode Performance Optimization (#101)

SPEC_15 Advanced Mode Performance Optimization + CodeRabbit fixes

examples/benchmark_advanced.py

@@ -0,0 +1,42 @@
+"""Benchmark Advanced mode with different max_rounds settings."""
+
+import asyncio
+import time
+
+from src.orchestrators.advanced import AdvancedOrchestrator
+
+
+async def benchmark(max_rounds: int) -> float:
+    """Run benchmark with specified rounds, return elapsed time."""
+    # Pass max_rounds explicitly instead of mutating os.environ
+    orch = AdvancedOrchestrator(max_rounds=max_rounds)
+    start = time.time()
+
+    print(f"\nStarting benchmark with max_rounds={max_rounds}...")
+
+    try:
+        async for event in orch.run("sildenafil erectile dysfunction mechanism"):
+            if event.type == "progress":
+                print(f"  Progress: {event.message}")
+            elif event.type == "complete":
+                print("  Complete!")
+                break
+            elif event.type == "error":
+                print(f"  Error: {event.message}")
+                break
+    except Exception as e:
+        print(f"  Exception: {e}")
+
+    return time.time() - start
+
+
+async def main() -> None:
+    """Run benchmarks for different configurations."""
+    # Only run a quick test for 3 rounds to verify it works
+    rounds = 3
+    elapsed = await benchmark(rounds)
+    print(f"max_rounds={rounds}: {elapsed:.1f}s ({elapsed / 60:.1f}min)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/agents/magentic_agents.py

@@ -89,6 +89,19 @@ When asked to evaluate:
    - Insufficient: Gaps in mechanism OR weak clinical evidence
 4. If insufficient, suggest specific search queries to fill gaps
 
+## CRITICAL OUTPUT FORMAT
+To ensure the workflow terminates when appropriate, you MUST follow these rules:
+
+IF evidence is SUFFICIENT (confidence >= 70%):
+   Start your response with a line like:
+   "✅ SUFFICIENT EVIDENCE (confidence: 72%). STOP SEARCHING. Delegate to ReportAgent NOW."
+   Use your actual numeric confidence instead of 72.
+   Then explain why.
+
+IF evidence is INSUFFICIENT:
+   Start with "❌ INSUFFICIENT: <Reason>."
+   Then provide scores and next queries.
+
 Be rigorous but fair. Look for:
 - Molecular targets and pathways
 - Animal model studies

src/orchestrators/advanced.py

@@ -15,6 +15,7 @@ Design Patterns:
 """
 
 import asyncio
+import os
 from collections.abc import AsyncGenerator
 from typing import TYPE_CHECKING, Any
 
@@ -65,10 +66,10 @@ class AdvancedOrchestrator(OrchestratorProtocol):
 
     def __init__(
         self,
-        max_rounds: int = 10,
+        max_rounds: int | None = None,
         chat_client: OpenAIChatClient | None = None,
         api_key: str | None = None,
-        timeout_seconds: float = 600.0,
+        timeout_seconds: float = 300.0,
         domain: ResearchDomain | str | None = None,
     ) -> None:
         """Initialize orchestrator.
@@ -77,14 +78,33 @@ class AdvancedOrchestrator(OrchestratorProtocol):
             max_rounds: Maximum coordination rounds
             chat_client: Optional shared chat client for agents
             api_key: Optional OpenAI API key (for BYOK)
-            timeout_seconds: Maximum workflow duration (default: 10 minutes)
+            timeout_seconds: Maximum workflow duration (default: 5 minutes)
             domain: Research domain for customization
         """
         # Validate requirements only if no key provided
         if not chat_client and not api_key:
             check_magentic_requirements()
 
-        self._max_rounds = max_rounds
+        # Environment-configurable rounds (default 5 for demos)
+        raw_rounds = os.getenv("ADVANCED_MAX_ROUNDS", "5")
+        try:
+            env_rounds = int(raw_rounds)
+        except ValueError:
+            logger.warning(
+                "Invalid ADVANCED_MAX_ROUNDS value %r, falling back to 5",
+                raw_rounds,
+            )
+            env_rounds = 5
+
+        if env_rounds < 1:
+            logger.warning(
+                "ADVANCED_MAX_ROUNDS must be >= 1, got %d; using 1 instead",
+                env_rounds,
+            )
+            env_rounds = 1
+
+        self._max_rounds = max_rounds if max_rounds is not None else env_rounds
+
         self._timeout_seconds = timeout_seconds
         self.domain = domain
         self.domain_config = get_domain_config(domain)
@@ -163,7 +183,13 @@ class AdvancedOrchestrator(OrchestratorProtocol):
 
         task = f"""Research {self.domain_config.report_focus} for: {query}
 
-Workflow:
+## CRITICAL RULE
+When JudgeAgent says "SUFFICIENT EVIDENCE" or "STOP SEARCHING":
+→ IMMEDIATELY delegate to ReportAgent for synthesis
+→ Do NOT continue searching or gathering more evidence
+→ The Judge has determined evidence quality is adequate
+
+## Standard Workflow
 1. SearchAgent: Find evidence from PubMed, ClinicalTrials.gov, and Europe PMC
 2. HypothesisAgent: Generate mechanistic hypotheses (Drug -> Target -> Pathway -> Effect)
 3. JudgeAgent: Evaluate if evidence is sufficient
@@ -182,8 +208,9 @@ The final output should be a structured research report."""
         yield AgentEvent(
             type="thinking",
             message=(
-                "Multi-agent reasoning in progress... "
-                "This may take 2-5 minutes for complex queries."
+                f"Multi-agent reasoning in progress ({self._max_rounds} rounds max)... "
+                f"Estimated time: {self._max_rounds * 45 // 60}-"
+                f"{self._max_rounds * 60 // 60} minutes."
             ),
             iteration=0,
         )
@@ -198,10 +225,23 @@ The final output should be a structured research report."""
                     if agent_event:
                         if isinstance(event, MagenticAgentMessageEvent):
                             iteration += 1
+
+                            # Progress estimation (clamp to avoid negative values)
+                            rounds_remaining = max(self._max_rounds - iteration, 0)
+                            est_seconds = rounds_remaining * 45
+                            if est_seconds >= 60:
+                                est_display = f"{est_seconds // 60}m {est_seconds % 60}s"
+                            else:
+                                est_display = f"{est_seconds}s"
+
+                            progress_msg = (
+                                f"Round {iteration}/{self._max_rounds} (~{est_display} remaining)"
+                            )
+
                             # Yield progress update before the agent action
                             yield AgentEvent(
                                 type="progress",
-                                message=f"Round {iteration}/{self._max_rounds}...",
+                                message=progress_msg,
                                 iteration=iteration,
                             )
 

tests/unit/orchestrators/test_advanced_orchestrator.py

@@ -0,0 +1,73 @@
+import os
+from unittest.mock import patch
+
+import pytest
+
+from src.orchestrators.advanced import AdvancedOrchestrator
+
+
+@pytest.mark.unit
+class TestAdvancedOrchestratorConfig:
+    """Tests for configuration options."""
+
+    def test_default_max_rounds_is_five(self) -> None:
+        """Default max_rounds should be 5 for faster demos."""
+        with (
+            patch.dict(os.environ, {}, clear=True),
+            patch("src.orchestrators.advanced.check_magentic_requirements"),
+        ):
+            # Clear any existing env var
+            os.environ.pop("ADVANCED_MAX_ROUNDS", None)
+            orch = AdvancedOrchestrator()
+            assert orch._max_rounds == 5
+
+    def test_max_rounds_from_env(self) -> None:
+        """max_rounds should be configurable via environment."""
+        with (
+            patch.dict(os.environ, {"ADVANCED_MAX_ROUNDS": "3"}),
+            patch("src.orchestrators.advanced.check_magentic_requirements"),
+        ):
+            orch = AdvancedOrchestrator()
+            assert orch._max_rounds == 3
+
+    def test_explicit_max_rounds_overrides_env(self) -> None:
+        """Explicit parameter should override environment."""
+        with (
+            patch.dict(os.environ, {"ADVANCED_MAX_ROUNDS": "3"}),
+            patch("src.orchestrators.advanced.check_magentic_requirements"),
+        ):
+            orch = AdvancedOrchestrator(max_rounds=7)
+            assert orch._max_rounds == 7
+
+    def test_timeout_default_is_five_minutes(self) -> None:
+        """Default timeout should be 300s (5 min) for faster failure."""
+        with patch("src.orchestrators.advanced.check_magentic_requirements"):
+            orch = AdvancedOrchestrator()
+            assert orch._timeout_seconds == 300.0
+
+    def test_invalid_env_rounds_falls_back_to_default(self) -> None:
+        """Invalid ADVANCED_MAX_ROUNDS should fall back to 5."""
+        with (
+            patch.dict(os.environ, {"ADVANCED_MAX_ROUNDS": "not_a_number"}),
+            patch("src.orchestrators.advanced.check_magentic_requirements"),
+        ):
+            orch = AdvancedOrchestrator()
+            assert orch._max_rounds == 5
+
+    def test_zero_env_rounds_clamps_to_one(self) -> None:
+        """ADVANCED_MAX_ROUNDS=0 should clamp to 1."""
+        with (
+            patch.dict(os.environ, {"ADVANCED_MAX_ROUNDS": "0"}),
+            patch("src.orchestrators.advanced.check_magentic_requirements"),
+        ):
+            orch = AdvancedOrchestrator()
+            assert orch._max_rounds == 1
+
+    def test_negative_env_rounds_clamps_to_one(self) -> None:
+        """Negative ADVANCED_MAX_ROUNDS should clamp to 1."""
+        with (
+            patch.dict(os.environ, {"ADVANCED_MAX_ROUNDS": "-5"}),
+            patch("src.orchestrators.advanced.check_magentic_requirements"),
+        ):
+            orch = AdvancedOrchestrator()
+            assert orch._max_rounds == 1