refactor(examples): apply CodeRabbit feedback (validations, complexity, formatting)

examples/README.md

@@ -107,7 +107,7 @@ uv run python examples/hypothesis_demo/run_hypothesis.py "sildenafil heart failu
 
 ---
 
-### 6. Full Stack Demo (LLM Required)
+### 6. Full-Stack Demo (LLM Required)
 
 **THE COMPLETE PIPELINE** - All phases working together.
 
@@ -142,7 +142,7 @@ Output: Publication-quality research report with validated citations.
 
 ## Architecture
 
-```
+```text
 User Query
     |
     v

examples/full_stack_demo/run_full.py

@@ -77,6 +77,33 @@ async def _run_search_iteration(
     return all_evidence
 
 
+async def _handle_judge_step(
+    judge_handler: Any, query: str, all_evidence: list[Evidence], evidence_store: dict[str, Any]
+) -> tuple[bool, str]:
+    """Handle the judge assessment step. Returns (should_stop, next_query)."""
+    print("\n[Judge] Assessing evidence quality (REAL LLM)...")
+    assessment = await judge_handler.assess(query, all_evidence)
+    print(f"  Mechanism Score: {assessment.details.mechanism_score}/10")
+    print(f"  Clinical Score:  {assessment.details.clinical_evidence_score}/10")
+    print(f"  Confidence:      {assessment.confidence:.0%}")
+    print(f"  Recommendation:  {assessment.recommendation.upper()}")
+
+    if assessment.recommendation == "synthesize":
+        print("\n[Judge] Evidence sufficient! Proceeding to report generation...")
+        evidence_store["last_assessment"] = assessment.details.model_dump()
+        return True, query
+
+    next_queries = assessment.next_search_queries[:2] if assessment.next_search_queries else []
+    if next_queries:
+        print(f"\n[Judge] Need more evidence. Next queries: {next_queries}")
+        return False, next_queries[0]
+
+    print(
+        "\n[Judge] Need more evidence but no suggested queries. " "Continuing with original query."
+    )
+    return False, query
+
+
 async def run_full_demo(query: str, max_iterations: int) -> None:
     """Run the REAL full stack pipeline."""
     print_header("DeepCritical Full Stack Demo (REAL)")
@@ -124,22 +151,12 @@ async def run_full_demo(query: str, max_iterations: int) -> None:
             _print_truncated(hyp_response.messages[0].text)
 
         # Step 3: REAL Judge
-        print("\n[Judge] Assessing evidence quality (REAL LLM)...")
-        assessment = await judge_handler.assess(query, all_evidence)
-        print(f"  Mechanism Score: {assessment.details.mechanism_score}/10")
-        print(f"  Clinical Score:  {assessment.details.clinical_evidence_score}/10")
-        print(f"  Confidence:      {assessment.confidence:.0%}")
-        print(f"  Recommendation:  {assessment.recommendation.upper()}")
-
-        if assessment.recommendation == "synthesize":
-            print("\n[Judge] Evidence sufficient! Proceeding to report generation...")
-            evidence_store["last_assessment"] = assessment.details.model_dump()
+        should_stop, query = await _handle_judge_step(
+            judge_handler, query, all_evidence, evidence_store
+        )
+        if should_stop:
             break
 
-        next_queries = assessment.next_search_queries[:2]
-        print(f"\n[Judge] Need more evidence. Next queries: {next_queries}")
-        query = assessment.next_search_queries[0] if assessment.next_search_queries else query
-
     # Step 4: REAL Report generation
     print_step(iteration + 1, "REPORT GENERATION (REAL LLM)")
     report_agent = ReportAgent(evidence_store, embedding_service)
@@ -184,6 +201,10 @@ Examples:
 
     args = parser.parse_args()
 
+    if args.iterations < 1:
+        print("Error: iterations must be at least 1")
+        sys.exit(1)
+
     # Fail fast: require API key
     if not (os.getenv("OPENAI_API_KEY") or os.getenv("ANTHROPIC_API_KEY")):
         print("=" * 70)

examples/hypothesis_demo/run_hypothesis.py

@@ -28,60 +28,68 @@ from src.tools.websearch import WebTool
 
 async def run_hypothesis_demo(query: str) -> None:
     """Run the REAL hypothesis generation pipeline."""
-    print(f"\n{'='*60}")
-    print("DeepCritical Hypothesis Agent Demo (Phase 7)")
-    print(f"Query: {query}")
-    print("Mode: REAL (Live API calls)")
-    print(f"{'='*60}\n")
-
-    # Step 1: REAL Search
-    print("[Step 1] Searching PubMed + Web...")
-    search_handler = SearchHandler(tools=[PubMedTool(), WebTool()], timeout=30.0)
-    result = await search_handler.execute(query, max_results_per_tool=5)
-
-    print(f"  Found {result.total_found} results from {result.sources_searched}")
-    if result.errors:
-        print(f"  Warnings: {result.errors}")
-
-    if not result.evidence:
-        print("\nNo evidence found. Try a different query.")
-        return
-
-    # Step 2: REAL Embeddings - Deduplicate
-    print("\n[Step 2] Semantic deduplication...")
-    embedding_service = EmbeddingService()
-    unique_evidence = await embedding_service.deduplicate(result.evidence, threshold=0.85)
-    print(f"  {len(result.evidence)} -> {len(unique_evidence)} unique papers")
-
-    # Show what we found
-    print("\n[Evidence collected]")
-    max_title_len = 50
-    for i, e in enumerate(unique_evidence[:5], 1):
-        raw_title = e.citation.title
-        title = raw_title[:max_title_len] + "..." if len(raw_title) > max_title_len else raw_title
-        print(f"  {i}. [{e.citation.source.upper()}] {title}")
-
-    # Step 3: REAL LLM - Generate hypotheses
-    print("\n[Step 3] Generating mechanistic hypotheses (LLM)...")
-    evidence_store: dict[str, Any] = {"current": unique_evidence, "hypotheses": []}
-    agent = HypothesisAgent(evidence_store, embedding_service)
-
-    print("-" * 60)
-    response = await agent.run(query)
-    print(response.messages[0].text)
-    print("-" * 60)
-
-    # Show stored hypotheses
-    hypotheses = evidence_store.get("hypotheses", [])
-    print(f"\n{len(hypotheses)} hypotheses stored")
-
-    if hypotheses:
-        print("\nGenerated search queries for further investigation:")
-        for h in hypotheses:
-            queries = h.to_search_queries()
-            print(f"  {h.drug} -> {h.target}:")
-            for q in queries[:3]:
-                print(f"    - {q}")
+    try:
+        print(f"\n{'='*60}")
+        print("DeepCritical Hypothesis Agent Demo (Phase 7)")
+        print(f"Query: {query}")
+        print("Mode: REAL (Live API calls)")
+        print(f"{'='*60}\n")
+
+        # Step 1: REAL Search
+        print("[Step 1] Searching PubMed + Web...")
+        search_handler = SearchHandler(tools=[PubMedTool(), WebTool()], timeout=30.0)
+        result = await search_handler.execute(query, max_results_per_tool=5)
+
+        print(f"  Found {result.total_found} results from {result.sources_searched}")
+        if result.errors:
+            print(f"  Warnings: {result.errors}")
+
+        if not result.evidence:
+            print("\nNo evidence found. Try a different query.")
+            return
+
+        # Step 2: REAL Embeddings - Deduplicate
+        print("\n[Step 2] Semantic deduplication...")
+        embedding_service = EmbeddingService()
+        unique_evidence = await embedding_service.deduplicate(result.evidence, threshold=0.85)
+        print(f"  {len(result.evidence)} -> {len(unique_evidence)} unique papers")
+
+        # Show what we found
+        print("\n[Evidence collected]")
+        max_title_len = 50
+        for i, e in enumerate(unique_evidence[:5], 1):
+            raw_title = e.citation.title
+            if len(raw_title) > max_title_len:
+                title = raw_title[:max_title_len] + "..."
+            else:
+                title = raw_title
+            print(f"  {i}. [{e.citation.source.upper()}] {title}")
+
+        # Step 3: REAL LLM - Generate hypotheses
+        print("\n[Step 3] Generating mechanistic hypotheses (LLM)...")
+        evidence_store: dict[str, Any] = {"current": unique_evidence, "hypotheses": []}
+        agent = HypothesisAgent(evidence_store, embedding_service)
+
+        print("-" * 60)
+        response = await agent.run(query)
+        print(response.messages[0].text)
+        print("-" * 60)
+
+        # Show stored hypotheses
+        hypotheses = evidence_store.get("hypotheses", [])
+        print(f"\n{len(hypotheses)} hypotheses stored")
+
+        if hypotheses:
+            print("\nGenerated search queries for further investigation:")
+            for h in hypotheses:
+                queries = h.to_search_queries()
+                print(f"  {h.drug} -> {h.target}:")
+                for q in queries[:3]:
+                    print(f"    - {q}")
+
+    except Exception as e:
+        print(f"\n❌ Error during hypothesis generation: {e}")
+        raise
 
 
 async def main() -> None:

examples/orchestrator_demo/run_agent.py

@@ -29,6 +29,8 @@ from src.tools.search_handler import SearchHandler
 from src.tools.websearch import WebTool
 from src.utils.models import OrchestratorConfig
 
+MAX_ITERATIONS = 10
+
 
 async def main() -> None:
     """Run the REAL agent demo."""
@@ -51,6 +53,10 @@ Examples:
     parser.add_argument("--iterations", type=int, default=3, help="Max iterations (default: 3)")
     args = parser.parse_args()
 
+    if not 1 <= args.iterations <= MAX_ITERATIONS:
+        print(f"Error: iterations must be between 1 and {MAX_ITERATIONS}")
+        sys.exit(1)
+
     # Fail fast: require API key
     if not (os.getenv("OPENAI_API_KEY") or os.getenv("ANTHROPIC_API_KEY")):
         print("=" * 60)