examples/README.md

DeepCritical Examples

Demo scripts demonstrating each phase of the drug repurposing research agent.

Quick Start

# 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 sources. No API keys required.

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 search-judge-synthesize loop.

Mock Mode (No API Keys):

uv run python examples/orchestrator_demo/run_agent.py "metformin cancer" --mock

Real Mode (Requires API Keys):

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.

# 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.

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.

# 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):

uv run python examples/full_stack_demo/run_full.py --mock

Real Mode:

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