feat(examples): add Phase 6-8 demos for full stack demonstration

- Add embeddings_demo: semantic search & deduplication (no API keys)
- Add hypothesis_demo: mechanistic reasoning (requires LLM)
- Add full_stack_demo: complete pipeline with mock and real modes
- Update examples README with comprehensive documentation

Examples demonstrate:
- Text embedding with sentence-transformers
- ChromaDB vector storage and similarity search
- Semantic deduplication by meaning
- Drug -> Target -> Pathway -> Effect hypothesis generation
- Structured scientific report generation

examples/README.md

@@ -1,28 +1,181 @@
-# Examples
+# DeepCritical Examples
 
-Demo scripts for DeepCritical functionality.
+Demo scripts demonstrating each phase of the drug repurposing research agent.
+
+## Quick Start
+
+```bash
+# Run without API keys (mock modes available)
+uv run python examples/embeddings_demo/run_embeddings.py
+uv run python examples/full_stack_demo/run_full.py --mock
+
+# Run with API keys (set OPENAI_API_KEY or ANTHROPIC_API_KEY)
+uv run python examples/full_stack_demo/run_full.py "metformin cancer"
+```
+
+---
 
 ## 1. Search Demo (Phase 2)
 
-Demonstrates parallel search across PubMed and Web. **No API keys required.**
+Demonstrates parallel search across PubMed and Web sources. **No API keys required.**
 
 ```bash
 uv run python examples/search_demo/run_search.py "metformin cancer"
 ```
 
+**What it shows:**
+- PubMed E-utilities search
+- DuckDuckGo web search
+- Scatter-gather orchestration
+- Evidence model with citations
+
+---
+
 ## 2. Agent Demo (Phase 4)
 
-Demonstrates the full search-judge-synthesize loop.
+Demonstrates the search-judge-synthesize loop.
 
-**Option A: Mock Mode (No Keys)**
-Test the logic/mechanics without an LLM.
+**Mock Mode (No API Keys):**
 ```bash
 uv run python examples/orchestrator_demo/run_agent.py "metformin cancer" --mock
 ```
 
-**Option B: Real Mode (Requires Keys)**
-Uses the real LLM Judge to evaluate evidence.
-Requires `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` in `.env`.
+**Real Mode (Requires API Keys):**
 ```bash
 uv run python examples/orchestrator_demo/run_agent.py "metformin cancer"
-```
+```
+
+**What it shows:**
+- Iterative search refinement
+- LLM-based evidence assessment
+- Synthesis generation
+- Event streaming for UI updates
+
+---
+
+## 3. Magentic Demo (Phase 5)
+
+Demonstrates multi-agent coordination using Microsoft Agent Framework.
+
+```bash
+# Requires OPENAI_API_KEY (Magentic uses OpenAI)
+uv run python examples/orchestrator_demo/run_magentic.py "metformin cancer"
+```
+
+**What it shows:**
+- MagenticBuilder workflow
+- SearchAgent, JudgeAgent, HypothesisAgent, ReportAgent coordination
+- Manager-based orchestration
+
+---
+
+## 4. Embeddings Demo (Phase 6)
+
+Demonstrates semantic search and deduplication. **No API keys required.**
+
+```bash
+uv run python examples/embeddings_demo/run_embeddings.py
+```
+
+**What it shows:**
+- Text embedding with sentence-transformers
+- ChromaDB vector storage
+- Semantic similarity search
+- Duplicate detection by meaning (not just URL)
+- Cosine similarity calculations
+
+---
+
+## 5. Hypothesis Demo (Phase 7)
+
+Demonstrates mechanistic hypothesis generation.
+
+```bash
+# Requires OPENAI_API_KEY or ANTHROPIC_API_KEY
+uv run python examples/hypothesis_demo/run_hypothesis.py "metformin Alzheimer's"
+uv run python examples/hypothesis_demo/run_hypothesis.py "sildenafil heart failure"
+```
+
+**What it shows:**
+- Drug -> Target -> Pathway -> Effect reasoning
+- Knowledge gap identification
+- Search query suggestions for targeted research
+- Confidence scoring
+
+---
+
+## 6. Full Stack Demo (Phases 1-8)
+
+**The complete pipeline** - demonstrates all phases working together.
+
+**Mock Mode (No API Keys):**
+```bash
+uv run python examples/full_stack_demo/run_full.py --mock
+```
+
+**Real Mode:**
+```bash
+uv run python examples/full_stack_demo/run_full.py "metformin Alzheimer's"
+uv run python examples/full_stack_demo/run_full.py "sildenafil heart failure" -i 3
+```
+
+**What it shows:**
+1. **Search** - PubMed + Web evidence collection
+2. **Embeddings** - Semantic deduplication
+3. **Hypothesis** - Mechanistic reasoning
+4. **Judge** - Evidence quality assessment
+5. **Report** - Structured scientific report generation
+
+Output includes a publication-quality research report with:
+- Executive summary
+- Methodology
+- Hypotheses tested (with support/contradict counts)
+- Mechanistic and clinical findings
+- Drug candidates
+- Limitations
+- Formatted references
+
+---
+
+## API Keys
+
+| Example | Required Keys |
+|---------|--------------|
+| search_demo | None (optional NCBI_API_KEY for higher rate limits) |
+| orchestrator_demo --mock | None |
+| orchestrator_demo | OPENAI_API_KEY or ANTHROPIC_API_KEY |
+| run_magentic | OPENAI_API_KEY |
+| embeddings_demo | None |
+| hypothesis_demo | OPENAI_API_KEY or ANTHROPIC_API_KEY |
+| full_stack_demo --mock | None |
+| full_stack_demo | OPENAI_API_KEY or ANTHROPIC_API_KEY |
+
+---
+
+## Architecture Overview
+
+```
+User Query
+    |
+    v
+[Phase 2: Search] --> PubMed + Web
+    |
+    v
+[Phase 6: Embeddings] --> Semantic Deduplication
+    |
+    v
+[Phase 7: Hypothesis] --> Drug -> Target -> Pathway -> Effect
+    |
+    v
+[Phase 3: Judge] --> "Is evidence sufficient?"
+    |
+    +---> NO --> Refine queries, loop back to Search
+    |
+    +---> YES --> Continue to Report
+    |
+    v
+[Phase 8: Report] --> Structured Scientific Report
+    |
+    v
+Final Output with Citations
+```

examples/embeddings_demo/run_embeddings.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""
+Demo: Semantic Search & Deduplication (Phase 6).
+
+This script demonstrates embedding-based capabilities:
+- Text embedding with sentence-transformers
+- Semantic similarity search via ChromaDB
+- Duplicate detection by meaning (not just URL)
+
+Usage:
+    uv run python examples/embeddings_demo/run_embeddings.py
+
+No API keys required - uses local sentence-transformers model.
+"""
+
+import asyncio
+
+from src.services.embeddings import EmbeddingService
+from src.utils.models import Citation, Evidence
+
+
+def create_sample_evidence() -> list[Evidence]:
+    """Create sample evidence with some semantic duplicates."""
+    return [
+        Evidence(
+            content="Metformin activates AMPK which inhibits mTOR signaling pathway.",
+            citation=Citation(
+                source="pubmed",
+                title="Metformin and AMPK activation",
+                url="https://pubmed.ncbi.nlm.nih.gov/11111/",
+                date="2023",
+                authors=["Smith J"],
+            ),
+        ),
+        Evidence(
+            content="The drug metformin works by turning on AMPK, blocking the mTOR pathway.",
+            citation=Citation(
+                source="pubmed",
+                title="AMPK-mTOR axis in diabetes treatment",
+                url="https://pubmed.ncbi.nlm.nih.gov/22222/",
+                date="2022",
+                authors=["Jones A"],
+            ),
+        ),
+        Evidence(
+            content="Sildenafil increases nitric oxide signaling for vasodilation.",
+            citation=Citation(
+                source="web",
+                title="How Viagra Works",
+                url="https://example.com/viagra-mechanism",
+                date="2023",
+                authors=["WebMD"],
+            ),
+        ),
+        Evidence(
+            content="Clinical trials show metformin reduces cancer incidence in diabetic patients.",
+            citation=Citation(
+                source="pubmed",
+                title="Metformin and cancer prevention",
+                url="https://pubmed.ncbi.nlm.nih.gov/33333/",
+                date="2024",
+                authors=["Lee K", "Park S"],
+            ),
+        ),
+        Evidence(
+            content="Metformin inhibits mTOR through AMPK activation mechanism.",
+            citation=Citation(
+                source="pubmed",
+                title="mTOR inhibition by Metformin",
+                url="https://pubmed.ncbi.nlm.nih.gov/44444/",
+                date="2023",
+                authors=["Brown M"],
+            ),
+        ),
+    ]
+
+
+def create_fresh_service(name_suffix: str = "") -> EmbeddingService:
+    """Create a fresh embedding service with unique collection name."""
+    import uuid
+
+    # Create service with unique collection by modifying the internal collection
+    service = EmbeddingService.__new__(EmbeddingService)
+    service._model = __import__("sentence_transformers").SentenceTransformer("all-MiniLM-L6-v2")
+    service._client = __import__("chromadb").Client()
+    collection_name = f"demo_{name_suffix}_{uuid.uuid4().hex[:8]}"
+    service._collection = service._client.create_collection(
+        name=collection_name, metadata={"hnsw:space": "cosine"}
+    )
+    return service
+
+
+async def demo_embedding() -> None:
+    """Demo single text embedding."""
+    print("\n" + "=" * 60)
+    print("1. TEXT EMBEDDING DEMO")
+    print("=" * 60)
+
+    service = create_fresh_service("embed")
+
+    texts = [
+        "Metformin activates AMPK",
+        "Aspirin reduces inflammation",
+        "Metformin turns on the AMPK enzyme",
+    ]
+
+    print("\nEmbedding sample texts...")
+    embeddings = await service.embed_batch(texts)
+
+    for text, emb in zip(texts, embeddings, strict=False):
+        print(f"  '{text[:40]}...' -> [{emb[0]:.4f}, {emb[1]:.4f}, ... ] (dim={len(emb)})")
+
+    # Calculate similarity between text 0 and text 2 (semantically similar)
+    import numpy as np
+
+    sim_0_2 = np.dot(embeddings[0], embeddings[2]) / (
+        np.linalg.norm(embeddings[0]) * np.linalg.norm(embeddings[2])
+    )
+    sim_0_1 = np.dot(embeddings[0], embeddings[1]) / (
+        np.linalg.norm(embeddings[0]) * np.linalg.norm(embeddings[1])
+    )
+
+    print(f"\nSimilarity (Metformin AMPK) vs (Metformin turns on AMPK): {sim_0_2:.3f}")
+    print(f"Similarity (Metformin AMPK) vs (Aspirin inflammation):    {sim_0_1:.3f}")
+    print("  -> Semantically similar texts have higher cosine similarity!")
+
+
+async def demo_semantic_search() -> None:
+    """Demo semantic similarity search."""
+    print("\n" + "=" * 60)
+    print("2. SEMANTIC SEARCH DEMO")
+    print("=" * 60)
+
+    service = create_fresh_service("search")
+
+    # Add some documents to the vector store
+    docs = [
+        ("doc1", "Metformin activates AMPK enzyme in liver cells", {"source": "pubmed"}),
+        ("doc2", "Aspirin inhibits COX-2 to reduce inflammation", {"source": "pubmed"}),
+        ("doc3", "Statins lower cholesterol by inhibiting HMG-CoA reductase", {"source": "web"}),
+        ("doc4", "AMPK activation leads to improved glucose metabolism", {"source": "pubmed"}),
+        ("doc5", "Sildenafil works via nitric oxide pathway", {"source": "web"}),
+    ]
+
+    print("\nIndexing documents...")
+    for doc_id, content, meta in docs:
+        await service.add_evidence(doc_id, content, meta)
+        print(f"  Added: {doc_id}")
+
+    # Search for semantically related content
+    query = "drugs that activate AMPK"
+    print(f"\nSearching for: '{query}'")
+
+    results = await service.search_similar(query, n_results=3)
+
+    print("\nTop 3 results:")
+    for i, r in enumerate(results, 1):
+        # Lower distance = more similar (cosine distance: 0=identical, 2=opposite)
+        similarity = 1 - r["distance"]
+        print(f"  {i}. [{similarity:.2%} similar] {r['content'][:60]}...")
+
+
+async def demo_deduplication() -> None:
+    """Demo semantic deduplication."""
+    print("\n" + "=" * 60)
+    print("3. SEMANTIC DEDUPLICATION DEMO")
+    print("=" * 60)
+
+    # Create fresh service for clean demo
+    service = create_fresh_service("dedup")
+
+    evidence = create_sample_evidence()
+    print(f"\nOriginal evidence count: {len(evidence)}")
+    for i, e in enumerate(evidence, 1):
+        print(f"  {i}. {e.citation.title}")
+
+    print("\nRunning semantic deduplication (threshold=0.85)...")
+    unique = await service.deduplicate(evidence, threshold=0.85)
+
+    print(f"\nUnique evidence count: {len(unique)}")
+    print(f"Removed {len(evidence) - len(unique)} semantic duplicates\n")
+
+    for i, e in enumerate(unique, 1):
+        print(f"  {i}. {e.citation.title}")
+
+    print("\n  -> Notice: Papers about 'Metformin AMPK mTOR' were deduplicated!")
+    print("     Different titles, same semantic meaning = duplicate removed.")
+
+
+async def main() -> None:
+    """Run all embedding demos."""
+    print("\n" + "=" * 60)
+    print("DeepCritical Embeddings Demo (Phase 6)")
+    print("Using: sentence-transformers + ChromaDB")
+    print("=" * 60)
+
+    await demo_embedding()
+    await demo_semantic_search()
+    await demo_deduplication()
+
+    print("\n" + "=" * 60)
+    print("Demo complete! Embeddings enable:")
+    print("  - Finding papers by MEANING, not just keywords")
+    print("  - Removing duplicate findings automatically")
+    print("  - Building diverse evidence sets for research")
+    print("=" * 60 + "\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/full_stack_demo/run_full.py

@@ -0,0 +1,456 @@
+#!/usr/bin/env python3
+"""
+Demo: Full Stack DeepCritical Agent (Phases 1-8).
+
+This script demonstrates the COMPLETE drug repurposing research pipeline:
+- Phase 2: Search (PubMed + Web)
+- Phase 6: Embeddings (Semantic deduplication)
+- Phase 7: Hypothesis (Mechanistic reasoning)
+- Phase 3: Judge (Evidence assessment)
+- Phase 8: Report (Structured scientific report)
+
+Usage:
+    # Full demo with real searches and LLM (requires API keys)
+    uv run python examples/full_stack_demo/run_full.py "metformin Alzheimer's"
+
+    # Mock mode - demonstrates pipeline without API calls
+    uv run python examples/full_stack_demo/run_full.py --mock
+
+    # With specific iterations
+    uv run python examples/full_stack_demo/run_full.py "sildenafil heart failure" --iterations 2
+"""
+
+import argparse
+import asyncio
+import os
+import sys
+from typing import Any
+
+from src.utils.models import Citation, Evidence, MechanismHypothesis
+
+
+def print_header(title: str) -> None:
+    """Print a formatted section header."""
+    print(f"\n{'='*70}")
+    print(f"  {title}")
+    print(f"{'='*70}\n")
+
+
+def print_step(step: int, name: str) -> None:
+    """Print a step indicator."""
+    print(f"\n[Step {step}] {name}")
+    print("-" * 50)
+
+
+def create_mock_evidence() -> list[Evidence]:
+    """Create comprehensive mock evidence for demo without API calls."""
+    return [
+        Evidence(
+            content=(
+                "Metformin, a first-line treatment for type 2 diabetes, activates "
+                "AMP-activated protein kinase (AMPK). AMPK is a master metabolic "
+                "regulator that inhibits mTOR signaling, reducing protein synthesis "
+                "and cell proliferation. This mechanism has implications beyond "
+                "glucose control."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="Metformin activates AMPK through LKB1-dependent mechanisms",
+                url="https://pubmed.ncbi.nlm.nih.gov/19001324/",
+                date="2023-06",
+                authors=["Zhang L", "Wang H", "Chen Y"],
+            ),
+        ),
+        Evidence(
+            content=(
+                "In transgenic mouse models of Alzheimer's disease, metformin treatment "
+                "reduced tau phosphorylation by 45% and decreased amyloid-beta plaque "
+                "formation. Treated mice showed improved performance on Morris water "
+                "maze tests, suggesting preserved spatial memory."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="Metformin ameliorates tau pathology in AD mouse models",
+                url="https://pubmed.ncbi.nlm.nih.gov/31256789/",
+                date="2024-01",
+                authors=["Kim J", "Lee S", "Park M", "Tanaka K"],
+            ),
+        ),
+        Evidence(
+            content=(
+                "A population-based cohort study of 100,000 diabetic patients found "
+                "that metformin users had 35% lower risk of developing Alzheimer's "
+                "disease compared to sulfonylurea users (HR=0.65, 95% CI: 0.58-0.73). "
+                "The protective effect increased with duration of use."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="Metformin and dementia risk: UK Biobank analysis",
+                url="https://pubmed.ncbi.nlm.nih.gov/34567890/",
+                date="2023-09",
+                authors=["Smith A", "Johnson B", "Williams C"],
+            ),
+        ),
+        Evidence(
+            content=(
+                "mTOR hyperactivation is observed in Alzheimer's disease brain tissue. "
+                "mTOR inhibition by rapamycin or metformin promotes autophagy, which "
+                "clears misfolded proteins including tau and amyloid-beta aggregates. "
+                "This suggests a common therapeutic pathway."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="mTOR-autophagy axis in neurodegeneration",
+                url="https://pubmed.ncbi.nlm.nih.gov/32109876/",
+                date="2023-03",
+                authors=["Brown C", "Davis D", "Miller E"],
+            ),
+        ),
+        Evidence(
+            content=(
+                "Metformin crosses the blood-brain barrier via organic cation "
+                "transporters (OCT1, OCT2). CSF concentrations reach approximately "
+                "1-2% of plasma levels, sufficient for AMPK activation in neurons. "
+                "Brain accumulation is observed in hippocampus and prefrontal cortex."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="Brain pharmacokinetics of metformin in humans",
+                url="https://pubmed.ncbi.nlm.nih.gov/35678901/",
+                date="2024-02",
+                authors=["Wilson E", "Garcia F"],
+            ),
+        ),
+        Evidence(
+            content=(
+                "Phase 2 clinical trial (NCT04098666) showed metformin 2000mg/day "
+                "for 12 months slowed cognitive decline by 18% compared to placebo "
+                "in patients with mild cognitive impairment. Biomarker analysis "
+                "showed reduced CSF tau levels in the treatment group."
+            ),
+            citation=Citation(
+                source="web",
+                title="Metformin for Alzheimer's prevention trial results",
+                url="https://clinicaltrials.gov/ct2/show/NCT04098666",
+                date="2024-03",
+                authors=["NIH Clinical Center"],
+            ),
+        ),
+    ]
+
+
+def create_mock_hypotheses() -> list[MechanismHypothesis]:
+    """Create mock hypotheses for demonstration."""
+    return [
+        MechanismHypothesis(
+            drug="Metformin",
+            target="AMPK",
+            pathway="mTOR inhibition -> Autophagy activation",
+            effect="Clearance of tau and amyloid-beta aggregates",
+            confidence=0.85,
+            supporting_evidence=[
+                "https://pubmed.ncbi.nlm.nih.gov/19001324/",
+                "https://pubmed.ncbi.nlm.nih.gov/32109876/",
+            ],
+            contradicting_evidence=[],
+            search_suggestions=[
+                "AMPK autophagy neurodegeneration",
+                "metformin tau clearance",
+            ],
+        ),
+        MechanismHypothesis(
+            drug="Metformin",
+            target="Glucose metabolism",
+            pathway="Improved neuronal energy homeostasis",
+            effect="Reduced oxidative stress and neuroinflammation",
+            confidence=0.70,
+            supporting_evidence=["https://pubmed.ncbi.nlm.nih.gov/31256789/"],
+            contradicting_evidence=[],
+            search_suggestions=[
+                "metformin brain glucose metabolism",
+                "neuronal insulin resistance alzheimer",
+            ],
+        ),
+    ]
+
+
+async def run_mock_demo() -> None:
+    """Run full pipeline with mock data (no API keys needed)."""
+    print_header("DeepCritical Full Stack Demo (MOCK MODE)")
+    print("Running with synthetic data - no API keys required.\n")
+
+    evidence = create_mock_evidence()
+    hypotheses = create_mock_hypotheses()
+
+    # Step 1: Show evidence
+    print_step(1, "SEARCH (Phase 2) - Evidence Collection")
+    print(f"Collected {len(evidence)} pieces of evidence:\n")
+    for i, e in enumerate(evidence, 1):
+        print(f"  [{i}] {e.citation.source.upper()}: {e.citation.title[:50]}...")
+        print(f"      {e.content[:80]}...")
+        print()
+
+    # Step 2: Embedding deduplication
+    print_step(2, "EMBEDDINGS (Phase 6) - Semantic Deduplication")
+    try:
+        from src.services.embeddings import EmbeddingService
+
+        service = EmbeddingService()
+        unique = await service.deduplicate(evidence, threshold=0.85)
+        print(f"Original: {len(evidence)} papers")
+        print(f"After deduplication: {len(unique)} unique papers")
+        print("(Semantic duplicates removed by meaning, not just URL)")
+    except ImportError:
+        print("Embedding dependencies not installed - skipping deduplication")
+        unique = evidence
+
+    # Step 3: Hypothesis generation
+    print_step(3, "HYPOTHESIS (Phase 7) - Mechanistic Reasoning")
+    print(f"Generated {len(hypotheses)} hypotheses:\n")
+    for i, h in enumerate(hypotheses, 1):
+        print(f"  Hypothesis {i} (Confidence: {h.confidence:.0%})")
+        print(f"  {h.drug} -> {h.target} -> {h.pathway} -> {h.effect}")
+        print(f"  Suggested searches: {', '.join(h.search_suggestions)}")
+        print()
+
+    # Step 4: Judge assessment
+    print_step(4, "JUDGE (Phase 3) - Evidence Assessment")
+    print("Assessment Results:")
+    print("  Mechanism Score:  8/10 (Strong mechanistic evidence)")
+    print("  Clinical Score:   7/10 (Phase 2 trial + observational data)")
+    print("  Confidence:       75%")
+    print("  Recommendation:   SYNTHESIZE (Evidence sufficient)")
+    print()
+
+    # Step 5: Report generation
+    print_step(5, "REPORT (Phase 8) - Structured Scientific Report")
+
+    report = f"""
+# Drug Repurposing Analysis: Metformin for Alzheimer's Disease
+
+## Executive Summary
+This analysis evaluated metformin as a potential therapeutic for Alzheimer's
+disease. Evidence from {len(unique)} sources supports a plausible mechanism
+through AMPK activation and mTOR inhibition, leading to enhanced autophagy
+and clearance of pathological protein aggregates. Clinical data shows
+promising risk reduction in observational studies and early trial results.
+
+## Research Question
+Can metformin, a type 2 diabetes medication, be repurposed for the prevention
+or treatment of Alzheimer's disease?
+
+## Methodology
+- Searched PubMed and web sources for "metformin Alzheimer's disease"
+- Applied semantic deduplication to remove redundant findings
+- Generated mechanistic hypotheses using LLM reasoning
+- Evaluated evidence quality with structured assessment
+
+## Hypotheses Tested
+- **Metformin -> AMPK -> mTOR inhibition -> Neuroprotection** (SUPPORTED)
+  - 4 supporting papers, 0 contradicting
+- **Metformin -> Glucose metabolism -> Reduced oxidative stress** (PARTIAL)
+  - 2 supporting papers, requires more investigation
+
+## Mechanistic Findings
+Strong evidence supports AMPK activation as the primary mechanism. Metformin
+crosses the blood-brain barrier and achieves therapeutic concentrations in
+hippocampus and cortex. Downstream effects include:
+- mTOR inhibition
+- Autophagy activation
+- Tau dephosphorylation
+- Amyloid-beta clearance
+
+## Clinical Findings
+- Observational: 35% risk reduction (HR=0.65, n=100,000)
+- Preclinical: 45% reduction in tau phosphorylation in AD mice
+- Phase 2 trial: 18% slower cognitive decline vs placebo
+
+## Drug Candidates
+- **Metformin** - Primary candidate with established safety profile
+
+## Limitations
+- Abstract-level analysis only
+- Observational data subject to confounding
+- Limited RCT data available
+- Optimal dosing for neuroprotection unclear
+
+## Conclusion
+Metformin shows strong potential for Alzheimer's disease prevention/treatment.
+The AMPK-mTOR-autophagy mechanism is well-supported. Recommend Phase 3 trials
+with cognitive endpoints.
+
+## References
+"""
+    max_authors_display = 2
+    for i, e in enumerate(unique[:6], 1):
+        authors = ", ".join(e.citation.authors[:max_authors_display])
+        if len(e.citation.authors) > max_authors_display:
+            authors += " et al."
+        ref_line = (
+            f"{i}. {authors}. *{e.citation.title}*. "
+            f"{e.citation.source.upper()} ({e.citation.date}). "
+            f"[Link]({e.citation.url})"
+        )
+        report += ref_line + "\n"
+
+    report += f"""
+---
+*Report generated from {len(unique)} papers across 3 search iterations.
+Confidence: 75%*
+"""
+
+    print(report)
+
+
+async def _run_search_iteration(
+    query: str,
+    iteration: int,
+    evidence_store: dict[str, Any],
+    all_evidence: list[Evidence],
+    search_handler: Any,
+    embedding_service: Any,
+) -> list[Evidence]:
+    """Run a single search iteration with deduplication."""
+    search_queries = [query]
+    if evidence_store.get("hypotheses"):
+        for h in evidence_store["hypotheses"][-2:]:
+            search_queries.extend(h.search_suggestions[:1])
+
+    for q in search_queries[:2]:
+        result = await search_handler.execute(q, max_results_per_tool=5)
+        print(f"  '{q}' -> {result.total_found} results")
+        new_unique = await embedding_service.deduplicate(result.evidence)
+        print(f"  After dedup: {len(new_unique)} unique")
+        all_evidence.extend(new_unique)
+
+    evidence_store["current"] = all_evidence
+    evidence_store["iteration_count"] = iteration
+    return all_evidence
+
+
+async def run_real_demo(query: str, max_iterations: int) -> None:
+    """Run full pipeline with real API calls."""
+    print_header("DeepCritical Full Stack Demo")
+    print(f"Query: {query}")
+    print(f"Max iterations: {max_iterations}")
+    print("Mode: REAL (Live API calls)\n")
+
+    # Import real components
+    from src.agent_factory.judges import JudgeHandler
+    from src.agents.hypothesis_agent import HypothesisAgent
+    from src.agents.report_agent import ReportAgent
+    from src.services.embeddings import EmbeddingService
+    from src.tools.pubmed import PubMedTool
+    from src.tools.search_handler import SearchHandler
+    from src.tools.websearch import WebTool
+
+    # Initialize services
+    embedding_service = EmbeddingService()
+    search_handler = SearchHandler(tools=[PubMedTool(), WebTool()], timeout=30.0)
+    judge_handler = JudgeHandler()
+
+    # Shared evidence store
+    evidence_store: dict[str, Any] = {"current": [], "hypotheses": [], "iteration_count": 0}
+    all_evidence: list[Evidence] = []
+
+    for iteration in range(1, max_iterations + 1):
+        print_step(iteration, f"ITERATION {iteration}/{max_iterations}")
+
+        # Step 1: Search
+        print("\n[Search] Querying PubMed and Web...")
+        all_evidence = await _run_search_iteration(
+            query, iteration, evidence_store, all_evidence, search_handler, embedding_service
+        )
+
+        # Step 2: Generate hypotheses (first iteration only)
+        if iteration == 1:
+            print("\n[Hypothesis] Generating mechanistic hypotheses...")
+            hypothesis_agent = HypothesisAgent(evidence_store, embedding_service)
+            hyp_response = await hypothesis_agent.run(query)
+            print(hyp_response.messages[0].text[:500] + "...")
+
+        # Step 3: Judge
+        print("\n[Judge] Assessing evidence quality...")
+        assessment = await judge_handler.assess(query, all_evidence)
+        print(f"  Mechanism: {assessment.details.mechanism_score}/10")
+        print(f"  Clinical: {assessment.details.clinical_evidence_score}/10")
+        print(f"  Recommendation: {assessment.recommendation}")
+
+        if assessment.recommendation == "synthesize":
+            print("\n[Judge says] Evidence sufficient! Generating report...")
+            evidence_store["last_assessment"] = assessment.details.model_dump()
+            break
+
+        next_queries = assessment.next_search_queries[:2]
+        print(f"\n[Judge says] Need more evidence. Next queries: {next_queries}")
+        query = assessment.next_search_queries[0] if assessment.next_search_queries else query
+
+    # Step 4: Generate report
+    print_step(iteration + 1, "REPORT GENERATION")
+    report_agent = ReportAgent(evidence_store, embedding_service)
+    report_response = await report_agent.run(query)
+
+    print("\n" + "=" * 70)
+    print("FINAL RESEARCH REPORT")
+    print("=" * 70)
+    print(report_response.messages[0].text)
+
+
+async def main() -> None:
+    """Entry point."""
+    parser = argparse.ArgumentParser(
+        description="DeepCritical Full Stack Demo (Phases 1-8)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    # Mock mode (no API keys)
+    uv run python examples/full_stack_demo/run_full.py --mock
+
+    # Real mode with metformin query
+    uv run python examples/full_stack_demo/run_full.py "metformin alzheimer"
+
+    # Sildenafil for heart failure
+    uv run python examples/full_stack_demo/run_full.py "sildenafil heart failure" -i 3
+        """,
+    )
+    parser.add_argument(
+        "query",
+        nargs="?",
+        default="metformin Alzheimer's disease",
+        help="Research query",
+    )
+    parser.add_argument(
+        "--mock",
+        action="store_true",
+        help="Run with mock data (no API keys needed)",
+    )
+    parser.add_argument(
+        "-i",
+        "--iterations",
+        type=int,
+        default=2,
+        help="Max search iterations (default: 2)",
+    )
+
+    args = parser.parse_args()
+
+    if args.mock:
+        await run_mock_demo()
+    else:
+        # Check for API keys
+        if not (os.getenv("OPENAI_API_KEY") or os.getenv("ANTHROPIC_API_KEY")):
+            print("Error: Real mode requires OPENAI_API_KEY or ANTHROPIC_API_KEY")
+            print("Use --mock for demo without API keys.")
+            sys.exit(1)
+
+        await run_real_demo(args.query, args.iterations)
+
+    print("\n" + "=" * 70)
+    print("  DeepCritical Full Stack Demo Complete!")
+    print("  Phases demonstrated: Foundation -> Search -> Judge -> UI ->")
+    print("                       Magentic -> Embeddings -> Hypothesis -> Report")
+    print("=" * 70 + "\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/hypothesis_demo/run_hypothesis.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""
+Demo: Hypothesis Generation (Phase 7).
+
+This script demonstrates mechanistic hypothesis generation:
+- Drug -> Target -> Pathway -> Effect reasoning
+- Knowledge gap identification
+- Search query suggestions for targeted research
+
+Usage:
+    # Requires OPENAI_API_KEY or ANTHROPIC_API_KEY
+    uv run python examples/hypothesis_demo/run_hypothesis.py
+
+    # With custom drug query
+    uv run python examples/hypothesis_demo/run_hypothesis.py "aspirin heart disease"
+"""
+
+import argparse
+import asyncio
+import os
+import sys
+from typing import Any
+
+from src.agents.hypothesis_agent import HypothesisAgent
+from src.utils.models import Citation, Evidence
+
+
+def create_metformin_evidence() -> list[Evidence]:
+    """Create sample evidence about metformin for hypothesis generation."""
+    return [
+        Evidence(
+            content=(
+                "Metformin activates AMP-activated protein kinase (AMPK), a master regulator "
+                "of cellular energy homeostasis. AMPK activation leads to inhibition of mTOR "
+                "signaling, reducing protein synthesis and cell proliferation."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="Metformin and AMPK: mechanisms of action",
+                url="https://pubmed.ncbi.nlm.nih.gov/12345/",
+                date="2023",
+                authors=["Zhang L", "Wang H"],
+            ),
+        ),
+        Evidence(
+            content=(
+                "In Alzheimer's disease models, AMPK activation by metformin reduced tau "
+                "phosphorylation and amyloid-beta accumulation. These effects correlated "
+                "with improved cognitive function in transgenic mice."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="Metformin neuroprotective effects in AD models",
+                url="https://pubmed.ncbi.nlm.nih.gov/23456/",
+                date="2024",
+                authors=["Kim J", "Lee S", "Park M"],
+            ),
+        ),
+        Evidence(
+            content=(
+                "Clinical observational studies show diabetic patients on metformin have "
+                "30-40% reduced incidence of Alzheimer's disease compared to those on "
+                "other diabetes medications."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="Metformin use and dementia risk: population study",
+                url="https://pubmed.ncbi.nlm.nih.gov/34567/",
+                date="2023",
+                authors=["Smith A", "Johnson B"],
+            ),
+        ),
+        Evidence(
+            content=(
+                "mTOR inhibition has emerged as a key therapeutic target in neurodegenerative "
+                "diseases. Rapamycin and metformin both reduce mTOR activity, though through "
+                "different upstream mechanisms."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="mTOR pathway in neurodegeneration",
+                url="https://pubmed.ncbi.nlm.nih.gov/45678/",
+                date="2022",
+                authors=["Brown C", "Davis D"],
+            ),
+        ),
+        Evidence(
+            content=(
+                "Metformin crosses the blood-brain barrier and accumulates in the hippocampus "
+                "and cortex. Brain concentrations sufficient for AMPK activation are achieved "
+                "at standard diabetic doses."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="Pharmacokinetics of metformin in brain tissue",
+                url="https://pubmed.ncbi.nlm.nih.gov/56789/",
+                date="2023",
+                authors=["Wilson E"],
+            ),
+        ),
+    ]
+
+
+def create_sildenafil_evidence() -> list[Evidence]:
+    """Create sample evidence about sildenafil (Viagra) for hypothesis generation."""
+    return [
+        Evidence(
+            content=(
+                "Sildenafil inhibits phosphodiesterase type 5 (PDE5), preventing breakdown "
+                "of cGMP. Elevated cGMP causes smooth muscle relaxation and vasodilation "
+                "in pulmonary vasculature."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="PDE5 inhibition mechanism of sildenafil",
+                url="https://pubmed.ncbi.nlm.nih.gov/67890/",
+                date="2022",
+                authors=["Miller F"],
+            ),
+        ),
+        Evidence(
+            content=(
+                "In pulmonary arterial hypertension (PAH), sildenafil reduces pulmonary "
+                "vascular resistance and improves exercise capacity. FDA approved for PAH "
+                "under brand name Revatio."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="Sildenafil in pulmonary hypertension treatment",
+                url="https://pubmed.ncbi.nlm.nih.gov/78901/",
+                date="2023",
+                authors=["Garcia R", "Martinez L"],
+            ),
+        ),
+        Evidence(
+            content=(
+                "PDE5 is expressed in cardiac myocytes. Sildenafil has shown cardioprotective "
+                "effects in animal models of heart failure by enhancing nitric oxide-cGMP "
+                "signaling in the myocardium."
+            ),
+            citation=Citation(
+                source="pubmed",
+                title="Cardiac effects of PDE5 inhibition",
+                url="https://pubmed.ncbi.nlm.nih.gov/89012/",
+                date="2024",
+                authors=["Thompson K"],
+            ),
+        ),
+    ]
+
+
+async def run_hypothesis_demo(query: str) -> None:
+    """Run the hypothesis generation demo."""
+    print(f"\n{'='*60}")
+    print("DeepCritical Hypothesis Agent Demo (Phase 7)")
+    print(f"Query: {query}")
+    print(f"{'='*60}\n")
+
+    # Select appropriate evidence based on query
+    if "sildenafil" in query.lower() or "viagra" in query.lower():
+        evidence = create_sildenafil_evidence()
+        print("Using: Sildenafil evidence set (3 papers)")
+    else:
+        evidence = create_metformin_evidence()
+        print("Using: Metformin evidence set (5 papers)")
+
+    # Create evidence store (shared context between agents)
+    evidence_store: dict[str, Any] = {"current": evidence, "hypotheses": []}
+
+    # Create hypothesis agent
+    agent = HypothesisAgent(evidence_store)
+
+    print("\nGenerating mechanistic hypotheses...\n")
+    print("-" * 60)
+
+    # Run hypothesis generation
+    response = await agent.run(query)
+
+    # Print the formatted response
+    print(response.messages[0].text)
+
+    print("-" * 60)
+
+    # Show stored hypotheses
+    hypotheses = evidence_store.get("hypotheses", [])
+    print(f"\n{len(hypotheses)} hypotheses stored in evidence_store")
+
+    if hypotheses:
+        print("\nHypothesis search queries generated:")
+        for h in hypotheses:
+            queries = h.to_search_queries()
+            print(f"  - {h.drug} -> {h.target}: {queries[:2]}")
+
+
+async def main() -> None:
+    """Run the demo."""
+    parser = argparse.ArgumentParser(description="Hypothesis Generation Demo")
+    parser.add_argument(
+        "query",
+        nargs="?",
+        default="metformin Alzheimer's disease",
+        help="Research query (default: 'metformin Alzheimer\\'s disease')",
+    )
+    args = parser.parse_args()
+
+    # Check for API key
+    if not (os.getenv("OPENAI_API_KEY") or os.getenv("ANTHROPIC_API_KEY")):
+        print("Error: Hypothesis generation requires an LLM.")
+        print("Set OPENAI_API_KEY or ANTHROPIC_API_KEY in your environment.")
+        sys.exit(1)
+
+    await run_hypothesis_demo(args.query)
+
+    print("\n" + "=" * 60)
+    print("Demo complete! The Hypothesis Agent:")
+    print("  - Analyzes evidence to find Drug -> Target -> Pathway -> Effect chains")
+    print("  - Identifies knowledge gaps in current evidence")
+    print("  - Suggests targeted search queries to test hypotheses")
+    print("=" * 60 + "\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())