docs: Remove outdated architecture and guide documents

- Delete several obsolete files, including `design-patterns.md`, `HF_FREE_TIER_ANALYSIS.md`, `overview.md`, `deployment.md`, and `workflow-diagrams.md`, as they no longer align with the current project structure and objectives.
- This cleanup enhances the clarity and relevance of the documentation for developers and stakeholders.

docs/architecture/HF_FREE_TIER_ANALYSIS.md

@@ -1,113 +0,0 @@
-# Hugging Face Free Tier Reliability Analysis (December 2025)
-
-## Executive Summary
-
-**Root Cause:** The recurring 500/401 errors on the Free Tier (Advanced Mode without API keys) are caused by implicit routing of large models (70B+) to unstable third-party "Inference Providers" (Novita, Hyperbolic) instead of running natively on Hugging Face's infrastructure.
-
-**Solution:** Switch the default Free Tier model from flagship-class models (72B) to high-performance mid-sized models (7B-32B) that are hosted natively by Hugging Face's Serverless Inference API.
-
----
-
-## 1. The "Inference Providers" Trap
-
-Hugging Face offers two distinct execution paths for its Inference API:
-
-1.  **Serverless Inference API (Native):**
-    *   **Host:** Hugging Face's own infrastructure.
-    *   **Reliability:** High (Direct control).
-    *   **Constraints:** Limited to models that fit on standard inference hardware (typically <10GB-30GB VRAM usage).
-    *   **Typical Models:** `bert-base`, `gpt2`, `Mistral-7B`, `Qwen2.5-7B`.
-
-2.  **Inference Providers (Third-Party Marketplace):**
-    *   **Host:** Partners like Novita, Hyperbolic, Together AI, Sambanova.
-    *   **Reliability:** Variable. "Staging mode" authentication issues, rate limits, and service outages (500 errors) are common on the free routing layer.
-    *   **Purpose:** To serve massive models (Llama-3.1-405B, Qwen2.5-72B) that are too expensive for HF to host for free.
-
-**The Problem:**
-When we request `Qwen/Qwen2.5-72B-Instruct` (or `Llama-3.1-70B`) without an API key, HF transparently routes this request to a partner (Novita/Hyperbolic).
-*   **Novita Status:** Currently returning 500 Internal Server Errors.
-*   **Hyperbolic Status:** Previously returned 401 Unauthorized (Staging Mode auth bug).
-
-We are effectively relying on a "best effort" chain of third-party providers for our core application stability.
-
-## 2. The "Golden Path" for Free Tier
-
-To ensure stability, the Free Tier must target models that reside on the **Native** path.
-
-**Criteria for Native Stability:**
-*   **Size:** < 30B parameters (ideal: 7B - 12B).
-*   **Popularity:** "Warm" models (high traffic keeps them loaded in memory).
-*   **Architecture:** Standard transformers (easy for HF to serve).
-
-**Candidate Models (Dec 2025):**
-
-| Model | Size | Provider Risk | Native Capability |
-|-------|------|---------------|-------------------|
-| **Qwen/Qwen2.5-7B-Instruct** | 7B | **Low** | **Excellent** (Math: 75.5, Code: 84.8) |
-| **mistralai/Mistral-Nemo-Instruct-2407** | 12B | Low | Very Good |
-| **Qwen/Qwen2.5-72B-Instruct** | 72B | **High** (Novita) | Excellent (but unreliable) |
-| **meta-llama/Llama-3.1-70B-Instruct** | 70B | **High** (Hyperbolic) | Excellent (but unreliable) |
-
-## 3. Recommendation
-
-**Immediate Fix:**
-Change the default `HUGGINGFACE_MODEL` in `src/utils/config.py` from `Qwen/Qwen2.5-72B-Instruct` to **`Qwen/Qwen2.5-7B-Instruct`**.
-
-**Why Qwen2.5-7B?**
-*   **Performance:** Outperforms Llama-3.1-8B and matches GPT-3.5 levels in many benchmarks.
-*   **Reliability:** Small enough to be hosted natively.
-*   **Context:** 128k context window (perfect for RAG).
-
-## 4. Future Architecture (Unified Client)
-
-For the Unified Chat Client architecture:
-1.  **Tier 0 (Free):** Hardcoded to Native Models (Qwen 7B, Mistral Nemo).
-2.  **Tier 1 (BYO Key):** Allow user to select any model (70B+), assuming they provide a key that grants access to premium providers or PRO tier.
-
----
-
-## 5. Known Content Quality Limitations (7B Models)
-
-**Status**: As of December 2025, the Free Tier (Qwen 2.5 7B) produces **working multi-agent orchestration** but with notable content quality limitations.
-
-### What Works Well
-- Multi-agent coordination (Manager → Search → Hypothesis → Report)
-- Clean streaming output (no garbage tokens, no raw JSON)
-- Proper agent handoffs and progress tracking
-- Coherent narrative structure
-
-### Known Limitations
-
-| Issue | Description | Severity |
-|-------|-------------|----------|
-| **Hallucinated Citations** | Model generates plausible-sounding but fake paper titles/authors instead of using actual search results | Medium |
-| **Anatomical Confusion** | May apply male anatomy (e.g., "penile rigidity") to female health queries | High |
-| **Nonsensical Medical Claims** | May generate claims like "prostate cancer risk" in context of female patients | High |
-| **Duplicate Content** | Final reports sometimes contain repeated sections | Low |
-
-### Why This Happens
-
-7B parameter models have limited:
-- **World knowledge**: Can't reliably recall specific paper titles/authors
-- **Context grounding**: May ignore search results and hallucinate instead
-- **Domain reasoning**: Complex medical topics exceed reasoning capacity
-
-### User Guidance
-
-**Free Tier is best for:**
-- Understanding the research workflow
-- Getting general topic overviews
-- Testing the system before committing to paid tier
-
-**For accurate medical research:**
-- Use Paid Tier (GPT-5) for citation accuracy
-- Always verify citations against actual databases
-- Treat Free Tier output as "draft quality"
-
-### Not a Stack Bug
-
-These are **model capability limitations**, not bugs in the DeepBoner architecture. The orchestration, streaming, and agent coordination are working correctly.
-
----
-*Analysis performed by Gemini CLI Agent, Dec 2, 2025*
-*Content quality section added Dec 3, 2025*

docs/architecture/design-patterns.md

@@ -1,1509 +0,0 @@
-# Design Patterns & Technical Decisions
-## Explicit Answers to Architecture Questions
-
----
-
-## Purpose of This Document
-
-This document explicitly answers all the "design pattern" questions raised in team discussions. It provides clear technical decisions with rationale.
-
----
-
-## 1. Primary Architecture Pattern
-
-### Decision: Orchestrator with Search-Judge Loop
-
-**Pattern Name**: Iterative Research Orchestrator
-
-**Structure**:
-```
-┌─────────────────────────────────────┐
-│    Research Orchestrator            │
-│  ┌───────────────────────────────┐  │
-│  │  Search Strategy Planner      │  │
-│  └───────────────────────────────┘  │
-│              ↓                      │
-│  ┌───────────────────────────────┐  │
-│  │  Tool Coordinator             │  │
-│  │  - PubMed Search              │  │
-│  │  - Web Search                 │  │
-│  │  - Clinical Trials            │  │
-│  └───────────────────────────────┘  │
-│              ↓                      │
-│  ┌───────────────────────────────┐  │
-│  │  Evidence Aggregator          │  │
-│  └───────────────────────────────┘  │
-│              ↓                      │
-│  ┌───────────────────────────────┐  │
-│  │  Quality Judge                │  │
-│  │  (LLM-based assessment)       │  │
-│  └───────────────────────────────┘  │
-│              ↓                      │
-│       Loop or Synthesize?           │
-│              ↓                      │
-│  ┌───────────────────────────────┐  │
-│  │  Report Generator             │  │
-│  └───────────────────────────────┘  │
-└─────────────────────────────────────┘
-```
-
-**Why NOT single-agent?**
-- Need coordinated multi-tool queries
-- Need iterative refinement
-- Need quality assessment between searches
-
-**Why NOT pure ReAct?**
-- Medical research requires structured workflow
-- Need explicit quality gates
-- Want deterministic tool selection
-
-**Why THIS pattern?**
-- Clear separation of concerns
-- Testable components
-- Easy to debug
-- Proven in similar systems
-
----
-
-## 2. Tool Selection & Orchestration Pattern
-
-### Decision: Static Tool Registry with Dynamic Selection
-
-**Pattern**:
-```python
-class ToolRegistry:
-    """Central registry of available research tools"""
-    tools = {
-        'pubmed': PubMedSearchTool(),
-        'web': WebSearchTool(),
-        'trials': ClinicalTrialsTool(),
-        'drugs': DrugInfoTool(),
-    }
-
-class Orchestrator:
-    def select_tools(self, question: str, iteration: int) -> List[Tool]:
-        """Dynamically choose tools based on context"""
-        if iteration == 0:
-            # First pass: broad search
-            return [tools['pubmed'], tools['web']]
-        else:
-            # Refinement: targeted search
-            return self.judge.recommend_tools(question, context)
-```
-
-**Why NOT on-the-fly agent factories?**
-- 6-day timeline (too complex)
-- Tools are known upfront
-- Simpler to test and debug
-
-**Why NOT single tool?**
-- Need multiple evidence sources
-- Different tools for different info types
-- Better coverage
-
-**Why THIS pattern?**
-- Balance flexibility vs simplicity
-- Tools can be added easily
-- Selection logic is transparent
-
----
-
-## 3. Judge Pattern
-
-### Decision: Dual-Judge System (Quality + Budget)
-
-**Pattern**:
-```python
-class QualityJudge:
-    """LLM-based evidence quality assessment"""
-
-    def is_sufficient(self, question: str, evidence: List[Evidence]) -> bool:
-        """Main decision: do we have enough?"""
-        return (
-            self.has_mechanism_explanation(evidence) and
-            self.has_drug_candidates(evidence) and
-            self.has_clinical_evidence(evidence) and
-            self.confidence_score(evidence) > threshold
-        )
-
-    def identify_gaps(self, question: str, evidence: List[Evidence]) -> List[str]:
-        """What's missing?"""
-        gaps = []
-        if not self.has_mechanism_explanation(evidence):
-            gaps.append("disease mechanism")
-        if not self.has_drug_candidates(evidence):
-            gaps.append("potential drug candidates")
-        if not self.has_clinical_evidence(evidence):
-            gaps.append("clinical trial data")
-        return gaps
-
-class BudgetJudge:
-    """Resource constraint enforcement"""
-
-    def should_stop(self, state: ResearchState) -> bool:
-        """Hard limits"""
-        return (
-            state.tokens_used >= max_tokens or
-            state.iterations >= max_iterations or
-            state.time_elapsed >= max_time
-        )
-```
-
-**Why NOT just LLM judge?**
-- Cost control (prevent runaway queries)
-- Time bounds (hackathon demo needs to be fast)
-- Safety (prevent infinite loops)
-
-**Why NOT just token budget?**
-- Want early exit when answer is good
-- Quality matters, not just quantity
-- Better user experience
-
-**Why THIS pattern?**
-- Best of both worlds
-- Clear separation (quality vs resources)
-- Each judge has single responsibility
-
----
-
-## 4. Break/Stopping Pattern
-
-### Decision: Three-Tier Break Conditions
-
-**Pattern**:
-```python
-def should_continue(state: ResearchState) -> bool:
-    """Multi-tier stopping logic"""
-
-    # Tier 1: Quality-based (ideal stop)
-    if quality_judge.is_sufficient(state.question, state.evidence):
-        state.stop_reason = "sufficient_evidence"
-        return False
-
-    # Tier 2: Budget-based (cost control)
-    if state.tokens_used >= config.max_tokens:
-        state.stop_reason = "token_budget_exceeded"
-        return False
-
-    # Tier 3: Iteration-based (safety)
-    if state.iterations >= config.max_iterations:
-        state.stop_reason = "max_iterations_reached"
-        return False
-
-    # Tier 4: Time-based (demo friendly)
-    if state.time_elapsed >= config.max_time:
-        state.stop_reason = "timeout"
-        return False
-
-    return True  # Continue researching
-```
-
-**Configuration**:
-```toml
-[research.limits]
-max_tokens = 50000      # ~$0.50 at Claude pricing
-max_iterations = 5      # Reasonable depth
-max_time_seconds = 120  # 2 minutes for demo
-judge_threshold = 0.8   # Quality confidence score
-```
-
-**Why multiple conditions?**
-- Defense in depth
-- Different failure modes
-- Graceful degradation
-
-**Why these specific limits?**
-- Tokens: Balances cost vs quality
-- Iterations: Enough for refinement, not too deep
-- Time: Fast enough for live demo
-- Judge: High bar for quality
-
----
-
-## 5. State Management Pattern
-
-### Decision: Pydantic State Machine with Checkpoints
-
-**Pattern**:
-```python
-class ResearchState(BaseModel):
-    """Immutable state snapshots"""
-    query_id: str
-    question: str
-    iteration: int = 0
-    evidence: List[Evidence] = []
-    tokens_used: int = 0
-    search_history: List[SearchQuery] = []
-    stop_reason: Optional[str] = None
-    created_at: datetime
-    updated_at: datetime
-
-class StateManager:
-    def save_checkpoint(self, state: ResearchState) -> None:
-        """Save state to disk"""
-        path = f".deepresearch/checkpoints/{state.query_id}_iter{state.iteration}.json"
-        path.write_text(state.model_dump_json(indent=2))
-
-    def load_checkpoint(self, query_id: str, iteration: int) -> ResearchState:
-        """Resume from checkpoint"""
-        path = f".deepresearch/checkpoints/{query_id}_iter{iteration}.json"
-        return ResearchState.model_validate_json(path.read_text())
-```
-
-**Directory Structure**:
-```
-.deepresearch/
-├── state/
-│   └── current_123.json          # Active research state
-├── checkpoints/
-│   ├── query_123_iter0.json      # Checkpoint after iteration 0
-│   ├── query_123_iter1.json      # Checkpoint after iteration 1
-│   └── query_123_iter2.json      # Checkpoint after iteration 2
-└── workspace/
-    └── query_123/
-        ├── papers/                # Downloaded PDFs
-        ├── search_results/        # Raw search results
-        └── analysis/              # Intermediate analysis
-```
-
-**Why Pydantic?**
-- Type safety
-- Validation
-- Easy serialization
-- Integration with Pydantic AI
-
-**Why checkpoints?**
-- Resume interrupted research
-- Debugging (inspect state at each iteration)
-- Cost savings (don't re-query)
-- Demo resilience
-
----
-
-## 6. Tool Interface Pattern
-
-### Decision: Async Unified Tool Protocol
-
-**Pattern**:
-```python
-from typing import Protocol, Optional, List, Dict
-import asyncio
-
-class ResearchTool(Protocol):
-    """Standard async interface all tools must implement"""
-
-    async def search(
-        self,
-        query: str,
-        max_results: int = 10,
-        filters: Optional[Dict] = None
-    ) -> List[Evidence]:
-        """Execute search and return structured evidence"""
-        ...
-
-    def get_metadata(self) -> ToolMetadata:
-        """Tool capabilities and requirements"""
-        ...
-
-class PubMedSearchTool:
-    """Concrete async implementation"""
-
-    def __init__(self):
-        self._rate_limiter = asyncio.Semaphore(3)  # 3 req/sec
-        self._cache: Dict[str, List[Evidence]] = {}
-
-    async def search(self, query: str, max_results: int = 10, **kwargs) -> List[Evidence]:
-        # Check cache first
-        cache_key = f"{query}:{max_results}"
-        if cache_key in self._cache:
-            return self._cache[cache_key]
-
-        async with self._rate_limiter:
-            # 1. Query PubMed E-utilities API (async httpx)
-            async with httpx.AsyncClient() as client:
-                response = await client.get(
-                    "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi",
-                    params={"db": "pubmed", "term": query, "retmax": max_results}
-                )
-            # 2. Parse XML response
-            # 3. Extract: title, abstract, authors, citations
-            # 4. Convert to Evidence objects
-            evidence_list = self._parse_response(response.text)
-
-            # Cache results
-            self._cache[cache_key] = evidence_list
-            return evidence_list
-
-    def get_metadata(self) -> ToolMetadata:
-        return ToolMetadata(
-            name="PubMed",
-            description="Biomedical literature search",
-            rate_limit="3 requests/second",
-            requires_api_key=False
-        )
-```
-
-**Parallel Tool Execution**:
-```python
-async def search_all_tools(query: str, tools: List[ResearchTool]) -> List[Evidence]:
-    """Run all tool searches in parallel"""
-    tasks = [tool.search(query) for tool in tools]
-    results = await asyncio.gather(*tasks, return_exceptions=True)
-
-    # Flatten and filter errors
-    evidence = []
-    for result in results:
-        if isinstance(result, Exception):
-            logger.warning(f"Tool failed: {result}")
-        else:
-            evidence.extend(result)
-    return evidence
-```
-
-**Why Async?**
-- Tools are I/O bound (network calls)
-- Parallel execution = faster searches
-- Better UX (streaming progress)
-- Standard in 2025 Python
-
-**Why Protocol?**
-- Loose coupling
-- Easy to add new tools
-- Testable with mocks
-- Clear contract
-
-**Why NOT abstract base class?**
-- More Pythonic (PEP 544)
-- Duck typing friendly
-- Runtime checking with isinstance
-
----
-
-## 7. Report Generation Pattern
-
-### Decision: Structured Output with Citations
-
-**Pattern**:
-```python
-class DrugCandidate(BaseModel):
-    name: str
-    mechanism: str
-    evidence_quality: Literal["strong", "moderate", "weak"]
-    clinical_status: str  # "FDA approved", "Phase 2", etc.
-    citations: List[Citation]
-
-class ResearchReport(BaseModel):
-    query: str
-    disease_mechanism: str
-    candidates: List[DrugCandidate]
-    methodology: str  # How we searched
-    confidence: float
-    sources_used: List[str]
-    generated_at: datetime
-
-    def to_markdown(self) -> str:
-        """Human-readable format"""
-        ...
-
-    def to_json(self) -> str:
-        """Machine-readable format"""
-        ...
-```
-
-**Output Example**:
-```markdown
-# Research Report: Long COVID Fatigue
-
-## Disease Mechanism
-Long COVID fatigue is associated with mitochondrial dysfunction
-and persistent inflammation [1, 2].
-
-## Drug Candidates
-
-### 1. Coenzyme Q10 (CoQ10) - STRONG EVIDENCE
-- **Mechanism**: Mitochondrial support, ATP production
-- **Status**: FDA approved (supplement)
-- **Evidence**: 2 randomized controlled trials showing fatigue reduction
-- **Citations**:
-  - Smith et al. (2023) - PubMed: 12345678
-  - Johnson et al. (2023) - PubMed: 87654321
-
-### 2. Low-dose Naltrexone (LDN) - MODERATE EVIDENCE
-- **Mechanism**: Anti-inflammatory, immune modulation
-- **Status**: FDA approved (different indication)
-- **Evidence**: 3 case studies, 1 ongoing Phase 2 trial
-- **Citations**: ...
-
-## Methodology
-- Searched PubMed: 45 papers reviewed
-- Searched Web: 12 sources
-- Clinical trials: 8 trials identified
-- Total iterations: 3
-- Tokens used: 12,450
-
-## Confidence: 85%
-
-## Sources
-- PubMed E-utilities
-- ClinicalTrials.gov
-- OpenFDA Database
-```
-
-**Why structured?**
-- Parseable by other systems
-- Consistent format
-- Easy to validate
-- Good for datasets
-
-**Why markdown?**
-- Human-readable
-- Renders nicely in Gradio
-- Easy to convert to PDF
-- Standard format
-
----
-
-## 8. Error Handling Pattern
-
-### Decision: Graceful Degradation with Fallbacks
-
-**Pattern**:
-```python
-class ResearchAgent:
-    def research(self, question: str) -> ResearchReport:
-        try:
-            return self._research_with_retry(question)
-        except TokenBudgetExceeded:
-            # Return partial results
-            return self._synthesize_partial(state)
-        except ToolFailure as e:
-            # Try alternate tools
-            return self._research_with_fallback(question, failed_tool=e.tool)
-        except Exception as e:
-            # Log and return error report
-            logger.error(f"Research failed: {e}")
-            return self._error_report(question, error=e)
-```
-
-**Why NOT fail fast?**
-- Hackathon demo must be robust
-- Partial results better than nothing
-- Good user experience
-
-**Why NOT silent failures?**
-- Need visibility for debugging
-- User should know limitations
-- Honest about confidence
-
----
-
-## 9. Configuration Pattern
-
-### Decision: Hydra-inspired but Simpler
-
-**Pattern**:
-```toml
-# config.toml
-
-[research]
-max_iterations = 5
-max_tokens = 50000
-max_time_seconds = 120
-judge_threshold = 0.85
-
-[tools]
-enabled = ["pubmed", "web", "trials"]
-
-[tools.pubmed]
-max_results = 20
-rate_limit = 3  # per second
-
-[tools.web]
-engine = "serpapi"
-max_results = 10
-
-[llm]
-provider = "anthropic"
-model = "claude-3-5-sonnet-20241022"
-temperature = 0.1
-
-[output]
-format = "markdown"
-include_citations = true
-include_methodology = true
-```
-
-**Loading**:
-```python
-from pathlib import Path
-import tomllib
-
-def load_config() -> dict:
-    config_path = Path("config.toml")
-    with open(config_path, "rb") as f:
-        return tomllib.load(f)
-```
-
-**Why NOT full Hydra?**
-- Simpler for hackathon
-- Easier to understand
-- Faster to modify
-- Can upgrade later
-
-**Why TOML?**
-- Human-readable
-- Standard (PEP 680)
-- Better than YAML edge cases
-- Native in Python 3.11+
-
----
-
-## 10. Testing Pattern
-
-### Decision: Three-Level Testing Strategy
-
-**Pattern**:
-```python
-# Level 1: Unit tests (fast, isolated)
-def test_pubmed_tool():
-    tool = PubMedSearchTool()
-    results = tool.search("aspirin cardiovascular")
-    assert len(results) > 0
-    assert all(isinstance(r, Evidence) for r in results)
-
-# Level 2: Integration tests (tools + agent)
-def test_research_loop():
-    agent = ResearchAgent(config=test_config)
-    report = agent.research("aspirin repurposing")
-    assert report.candidates
-    assert report.confidence > 0
-
-# Level 3: End-to-end tests (full system)
-def test_full_workflow():
-    # Simulate user query through Gradio UI
-    response = gradio_app.predict("test query")
-    assert "Drug Candidates" in response
-```
-
-**Why three levels?**
-- Fast feedback (unit tests)
-- Confidence (integration tests)
-- Reality check (e2e tests)
-
-**Test Data**:
-```python
-# tests/fixtures/
-- mock_pubmed_response.xml
-- mock_web_results.json
-- sample_research_query.txt
-- expected_report.md
-```
-
----
-
-## 11. Judge Prompt Templates
-
-### Decision: Structured JSON Output with Domain-Specific Criteria
-
-**Quality Judge System Prompt**:
-```python
-QUALITY_JUDGE_SYSTEM = """You are a medical research quality assessor specializing in drug repurposing.
-Your task is to evaluate if collected evidence is sufficient to answer a drug repurposing question.
-
-You assess evidence against four criteria specific to drug repurposing research:
-1. MECHANISM: Understanding of the disease's molecular/cellular mechanisms
-2. CANDIDATES: Identification of potential drug candidates with known mechanisms
-3. EVIDENCE: Clinical or preclinical evidence supporting repurposing
-4. SOURCES: Quality and credibility of sources (peer-reviewed > preprints > web)
-
-You MUST respond with valid JSON only. No other text."""
-```
-
-**Quality Judge User Prompt**:
-```python
-QUALITY_JUDGE_USER = """
-## Research Question
-{question}
-
-## Evidence Collected (Iteration {iteration} of {max_iterations})
-{evidence_summary}
-
-## Token Budget
-Used: {tokens_used} / {max_tokens}
-
-## Your Assessment
-
-Evaluate the evidence and respond with this exact JSON structure:
-
-```json
-{{
-  "assessment": {{
-    "mechanism_score": <0-10>,
-    "mechanism_reasoning": "<Step-by-step analysis of mechanism understanding>",
-    "candidates_score": <0-10>,
-    "candidates_found": ["<drug1>", "<drug2>", ...],
-    "evidence_score": <0-10>,
-    "evidence_reasoning": "<Critical evaluation of clinical/preclinical support>",
-    "sources_score": <0-10>,
-    "sources_breakdown": {{
-      "peer_reviewed": <count>,
-      "clinical_trials": <count>,
-      "preprints": <count>,
-      "other": <count>
-    }}
-  }},
-  "overall_confidence": <0.0-1.0>,
-  "sufficient": <true/false>,
-  "gaps": ["<missing info 1>", "<missing info 2>"],
-  "recommended_searches": ["<search query 1>", "<search query 2>"],
-  "recommendation": "<continue|synthesize>"
-}}
-```
-
-Decision rules:
-- sufficient=true if overall_confidence >= 0.8 AND mechanism_score >= 6 AND candidates_score >= 6
-- sufficient=true if remaining budget < 10% (must synthesize with what we have)
-- Otherwise, provide recommended_searches to fill gaps
-"""
-```
-
-**Report Synthesis Prompt**:
-```python
-SYNTHESIS_PROMPT = """You are a medical research synthesizer creating a drug repurposing report.
-
-## Research Question
-{question}
-
-## Collected Evidence
-{all_evidence}
-
-## Judge Assessment
-{final_assessment}
-
-## Your Task
-Create a comprehensive research report with this structure:
-
-1. **Executive Summary** (2-3 sentences)
-2. **Disease Mechanism** - What we understand about the condition
-3. **Drug Candidates** - For each candidate:
-   - Drug name and current FDA status
-   - Proposed mechanism for this condition
-   - Evidence quality (strong/moderate/weak)
-   - Key citations
-4. **Methodology** - How we searched (tools used, queries, iterations)
-5. **Limitations** - What we couldn't find or verify
-6. **Confidence Score** - Overall confidence in findings
-
-Format as Markdown. Include PubMed IDs as citations [PMID: 12345678].
-Be scientifically accurate. Do not hallucinate drug names or mechanisms.
-If evidence is weak, say so clearly."""
-```
-
-**Why Structured JSON?**
-- Parseable by code (not just LLM output)
-- Consistent format for logging/debugging
-- Can trigger specific actions (continue vs synthesize)
-- Testable with expected outputs
-
-**Why Domain-Specific Criteria?**
-- Generic "is this good?" prompts fail
-- Drug repurposing has specific requirements
-- Physician on team validated criteria
-- Maps to real research workflow
-
----
-
-## 12. MCP Server Integration (Hackathon Track)
-
-### Decision: Tools as MCP Servers for Reusability
-
-**Why MCP?**
-- Hackathon has dedicated MCP track
-- Makes our tools reusable by others
-- Standard protocol (Model Context Protocol)
-- Future-proof (industry adoption growing)
-
-**Architecture**:
-```
-┌─────────────────────────────────────────────────┐
-│  DeepBoner Agent                             │
-│  (uses tools directly OR via MCP)               │
-└─────────────────────────────────────────────────┘
-                      │
-         ┌────────────┼────────────┐
-         ↓            ↓            ↓
-┌─────────────┐ ┌──────────┐ ┌───────────────┐
-│ PubMed MCP  │ │ Web MCP  │ │ Trials MCP    │
-│ Server      │ │ Server   │ │ Server        │
-└─────────────┘ └──────────┘ └───────────────┘
-         │            │            │
-         ↓            ↓            ↓
-    PubMed API   Brave/DDG   ClinicalTrials.gov
-```
-
-**PubMed MCP Server Implementation**:
-```python
-# src/mcp_servers/pubmed_server.py
-from fastmcp import FastMCP
-
-mcp = FastMCP("PubMed Research Tool")
-
-@mcp.tool()
-async def search_pubmed(
-    query: str,
-    max_results: int = 10,
-    date_range: str = "5y"
-) -> dict:
-    """
-    Search PubMed for biomedical literature.
-
-    Args:
-        query: Search terms (supports PubMed syntax like [MeSH])
-        max_results: Maximum papers to return (default 10, max 100)
-        date_range: Time filter - "1y", "5y", "10y", or "all"
-
-    Returns:
-        dict with papers list containing title, abstract, authors, pmid, date
-    """
-    tool = PubMedSearchTool()
-    results = await tool.search(query, max_results)
-    return {
-        "query": query,
-        "count": len(results),
-        "papers": [r.model_dump() for r in results]
-    }
-
-@mcp.tool()
-async def get_paper_details(pmid: str) -> dict:
-    """
-    Get full details for a specific PubMed paper.
-
-    Args:
-        pmid: PubMed ID (e.g., "12345678")
-
-    Returns:
-        Full paper metadata including abstract, MeSH terms, references
-    """
-    tool = PubMedSearchTool()
-    return await tool.get_details(pmid)
-
-if __name__ == "__main__":
-    mcp.run()
-```
-
-**Running the MCP Server**:
-```bash
-# Start the server
-python -m src.mcp_servers.pubmed_server
-
-# Or with uvx (recommended)
-uvx fastmcp run src/mcp_servers/pubmed_server.py
-
-# Note: fastmcp uses stdio transport by default, which is perfect
-# for local integration with Claude Desktop or the main agent.
-```
-
-**Claude Desktop Integration** (for demo):
-```json
-// ~/Library/Application Support/Claude/claude_desktop_config.json
-{
-  "mcpServers": {
-    "pubmed": {
-      "command": "python",
-      "args": ["-m", "src.mcp_servers.pubmed_server"],
-      "cwd": "/path/to/deepboner"
-    }
-  }
-}
-```
-
-**Why FastMCP?**
-- Simple decorator syntax
-- Handles protocol complexity
-- Good docs and examples
-- Works with Claude Desktop and API
-
-**MCP Track Submission Requirements**:
-- [ ] At least one tool as MCP server
-- [ ] README with setup instructions
-- [ ] Demo showing MCP usage
-- [ ] Bonus: Multiple tools as MCP servers
-
----
-
-## 13. Gradio UI Pattern (Hackathon Track)
-
-### Decision: Streaming Progress with Modern UI
-
-**Pattern**:
-```python
-import gradio as gr
-from typing import Generator
-
-def research_with_streaming(question: str) -> Generator[str, None, None]:
-    """Stream research progress to UI"""
-    yield "🔍 Starting research...\n\n"
-
-    agent = ResearchAgent()
-
-    async for event in agent.research_stream(question):
-        match event.type:
-            case "search_start":
-                yield f"📚 Searching {event.tool}...\n"
-            case "search_complete":
-                yield f"✅ Found {event.count} results from {event.tool}\n"
-            case "judge_thinking":
-                yield f"🤔 Evaluating evidence quality...\n"
-            case "judge_decision":
-                yield f"📊 Confidence: {event.confidence:.0%}\n"
-            case "iteration_complete":
-                yield f"🔄 Iteration {event.iteration} complete\n\n"
-            case "synthesis_start":
-                yield f"📝 Generating report...\n"
-            case "complete":
-                yield f"\n---\n\n{event.report}"
-
-# Gradio 5 UI
-with gr.Blocks(theme=gr.themes.Soft()) as demo:
-    gr.Markdown("# 🔬 DeepBoner: Drug Repurposing Research Agent")
-    gr.Markdown("Ask a question about potential drug repurposing opportunities.")
-
-    with gr.Row():
-        with gr.Column(scale=2):
-            question = gr.Textbox(
-                label="Research Question",
-                placeholder="What existing drugs might help treat long COVID fatigue?",
-                lines=2
-            )
-            examples = gr.Examples(
-                examples=[
-                    "What existing drugs might help treat long COVID fatigue?",
-                    "Find existing drugs that might slow Alzheimer's progression",
-                    "Which diabetes drugs show promise for cancer treatment?"
-                ],
-                inputs=question
-            )
-            submit = gr.Button("🚀 Start Research", variant="primary")
-
-        with gr.Column(scale=3):
-            output = gr.Markdown(label="Research Progress & Report")
-
-    submit.click(
-        fn=research_with_streaming,
-        inputs=question,
-        outputs=output,
-    )
-
-demo.launch()
-```
-
-**Why Streaming?**
-- User sees progress, not loading spinner
-- Builds trust (system is working)
-- Better UX for long operations
-- Gradio 5 native support
-
-**Why gr.Markdown Output?**
-- Research reports are markdown
-- Renders citations nicely
-- Code blocks for methodology
-- Tables for drug comparisons
-
----
-
-## Summary: Design Decision Table
-
-| # | Question | Decision | Why |
-|---|----------|----------|-----|
-| 1 | **Architecture** | Orchestrator with search-judge loop | Clear, testable, proven |
-| 2 | **Tools** | Static registry, dynamic selection | Balance flexibility vs simplicity |
-| 3 | **Judge** | Dual (quality + budget) | Quality + cost control |
-| 4 | **Stopping** | Four-tier conditions | Defense in depth |
-| 5 | **State** | Pydantic + checkpoints | Type-safe, resumable |
-| 6 | **Tool Interface** | Async Protocol + parallel execution | Fast I/O, modern Python |
-| 7 | **Output** | Structured + Markdown | Human & machine readable |
-| 8 | **Errors** | Graceful degradation + fallbacks | Robust for demo |
-| 9 | **Config** | TOML (Hydra-inspired) | Simple, standard |
-| 10 | **Testing** | Three levels | Fast feedback + confidence |
-| 11 | **Judge Prompts** | Structured JSON + domain criteria | Parseable, medical-specific |
-| 12 | **MCP** | Tools as MCP servers | Hackathon track, reusability |
-| 13 | **UI** | Gradio 5 streaming | Progress visibility, modern UX |
-
----
-
-## Answers to Specific Questions
-
-### "What's the orchestrator pattern?"
-**Answer**: See Section 1 - Iterative Research Orchestrator with search-judge loop
-
-### "LLM-as-judge or token budget?"
-**Answer**: Both - See Section 3 (Dual-Judge System) and Section 4 (Three-Tier Break Conditions)
-
-### "What's the break pattern?"
-**Answer**: See Section 4 - Three stopping conditions: quality threshold, token budget, max iterations
-
-### "Should we use agent factories?"
-**Answer**: No - See Section 2. Static tool registry is simpler for 6-day timeline
-
-### "How do we handle state?"
-**Answer**: See Section 5 - Pydantic state machine with checkpoints
-
----
-
-## Appendix: Complete Data Models
-
-```python
-# src/deepresearch/models.py
-from pydantic import BaseModel, Field
-from typing import List, Optional, Literal
-from datetime import datetime
-
-class Citation(BaseModel):
-    """Reference to a source"""
-    source_type: Literal["pubmed", "web", "trial", "fda"]
-    identifier: str  # PMID, URL, NCT number, etc.
-    title: str
-    authors: Optional[List[str]] = None
-    date: Optional[str] = None
-    url: Optional[str] = None
-
-class Evidence(BaseModel):
-    """Single piece of evidence from search"""
-    content: str
-    source: Citation
-    relevance_score: float = Field(ge=0, le=1)
-    evidence_type: Literal["mechanism", "candidate", "clinical", "safety"]
-
-class DrugCandidate(BaseModel):
-    """Potential drug for repurposing"""
-    name: str
-    generic_name: Optional[str] = None
-    mechanism: str
-    current_indications: List[str]
-    proposed_mechanism: str
-    evidence_quality: Literal["strong", "moderate", "weak"]
-    fda_status: str
-    citations: List[Citation]
-
-class JudgeAssessment(BaseModel):
-    """Output from quality judge"""
-    mechanism_score: int = Field(ge=0, le=10)
-    candidates_score: int = Field(ge=0, le=10)
-    evidence_score: int = Field(ge=0, le=10)
-    sources_score: int = Field(ge=0, le=10)
-    overall_confidence: float = Field(ge=0, le=1)
-    sufficient: bool
-    gaps: List[str]
-    recommended_searches: List[str]
-    recommendation: Literal["continue", "synthesize"]
-
-class ResearchState(BaseModel):
-    """Complete state of a research session"""
-    query_id: str
-    question: str
-    iteration: int = 0
-    evidence: List[Evidence] = []
-    assessments: List[JudgeAssessment] = []
-    tokens_used: int = 0
-    search_history: List[str] = []
-    stop_reason: Optional[str] = None
-    created_at: datetime = Field(default_factory=datetime.utcnow)
-    updated_at: datetime = Field(default_factory=datetime.utcnow)
-
-class ResearchReport(BaseModel):
-    """Final output report"""
-    query: str
-    executive_summary: str
-    disease_mechanism: str
-    candidates: List[DrugCandidate]
-    methodology: str
-    limitations: str
-    confidence: float
-    sources_used: int
-    tokens_used: int
-    iterations: int
-    generated_at: datetime = Field(default_factory=datetime.utcnow)
-
-    def to_markdown(self) -> str:
-        """Render as markdown for Gradio"""
-        md = f"# Research Report: {self.query}\n\n"
-        md += f"## Executive Summary\n{self.executive_summary}\n\n"
-        md += f"## Disease Mechanism\n{self.disease_mechanism}\n\n"
-        md += "## Drug Candidates\n\n"
-        for i, drug in enumerate(self.candidates, 1):
-            md += f"### {i}. {drug.name} - {drug.evidence_quality.upper()} EVIDENCE\n"
-            md += f"- **Mechanism**: {drug.proposed_mechanism}\n"
-            md += f"- **FDA Status**: {drug.fda_status}\n"
-            md += f"- **Current Uses**: {', '.join(drug.current_indications)}\n"
-            md += f"- **Citations**: {len(drug.citations)} sources\n\n"
-        md += f"## Methodology\n{self.methodology}\n\n"
-        md += f"## Limitations\n{self.limitations}\n\n"
-        md += f"## Confidence: {self.confidence:.0%}\n"
-        return md
-```
-
----
-
-## 14. Alternative Frameworks Considered
-
-We researched major agent frameworks before settling on our stack. Here's why we chose what we chose, and what we'd steal if we're shipping like animals and have time for Gucci upgrades.
-
-### Frameworks Evaluated
-
-| Framework | Repo | What It Does |
-|-----------|------|--------------|
-| **Microsoft AutoGen** | [github.com/microsoft/autogen](https://github.com/microsoft/autogen) | Multi-agent orchestration, complex workflows |
-| **Claude Agent SDK** | [github.com/anthropics/claude-agent-sdk-python](https://github.com/anthropics/claude-agent-sdk-python) | Anthropic's official agent framework |
-| **Pydantic AI** | [github.com/pydantic/pydantic-ai](https://github.com/pydantic/pydantic-ai) | Type-safe agents, structured outputs |
-
-### Why NOT AutoGen (Microsoft)?
-
-**Pros:**
-- Battle-tested multi-agent orchestration
-- `reflect_on_tool_use` - model reviews its own tool results
-- `max_tool_iterations` - built-in iteration limits
-- Concurrent tool execution
-- Rich ecosystem (AutoGen Studio, benchmarks)
-
-**Cons for MVP:**
-- Heavy dependency tree (50+ packages)
-- Complex configuration (YAML + Python)
-- Overkill for single-agent search-judge loop
-- Learning curve eats into 6-day timeline
-
-**Verdict:** Great for multi-agent systems. Overkill for our MVP.
-
-### Why NOT Claude Agent SDK (Anthropic)?
-
-**Pros:**
-- Official Anthropic framework
-- Clean `@tool` decorator pattern
-- In-process MCP servers (no subprocess)
-- Hooks for pre/post tool execution
-- Direct Claude Code integration
-
-**Cons for MVP:**
-- Requires Claude Code CLI bundled
-- Node.js dependency for some features
-- Designed for Claude Code ecosystem, not standalone agents
-- Less flexible for custom LLM providers
-
-**Verdict:** Would be great if we were building ON Claude Code. We're building a standalone agent.
-
-### Why Pydantic AI + FastMCP (Our Choice)
-
-**Pros:**
-- ✅ Simple, Pythonic API
-- ✅ Native async/await
-- ✅ Type-safe with Pydantic
-- ✅ Works with any LLM provider
-- ✅ FastMCP for clean MCP servers
-- ✅ Minimal dependencies
-- ✅ Can ship MVP in 6 days
-
-**Cons:**
-- Newer framework (less battle-tested)
-- Smaller ecosystem
-- May need to build more from scratch
-
-**Verdict:** Right tool for the job. Ship fast, iterate later.
-
----
-
-## 15. Stretch Goals: Gucci Bangers (If We're Shipping Like Animals)
-
-If MVP ships early and we're crushing it, here's what we'd steal from other frameworks:
-
-### Tier 1: Quick Wins (2-4 hours each)
-
-#### From Claude Agent SDK: `@tool` Decorator Pattern
-Replace our Protocol-based tools with cleaner decorators:
-
-```python
-# CURRENT (Protocol-based)
-class PubMedSearchTool:
-    async def search(self, query: str, max_results: int = 10) -> List[Evidence]:
-        ...
-
-# UPGRADE (Decorator-based, stolen from Claude SDK)
-from claude_agent_sdk import tool
-
-@tool("search_pubmed", "Search PubMed for biomedical papers", {
-    "query": str,
-    "max_results": int
-})
-async def search_pubmed(args):
-    results = await _do_pubmed_search(args["query"], args["max_results"])
-    return {"content": [{"type": "text", "text": json.dumps(results)}]}
-```
-
-**Why it's Gucci:** Cleaner syntax, automatic schema generation, less boilerplate.
-
-#### From AutoGen: Reflect on Tool Use
-Add a reflection step where the model reviews its own tool results:
-
-```python
-# CURRENT: Judge evaluates evidence
-assessment = await judge.assess(question, evidence)
-
-# UPGRADE: Add reflection step (stolen from AutoGen)
-class ReflectiveJudge:
-    async def assess_with_reflection(self, question, evidence, tool_results):
-        # First pass: raw assessment
-        initial = await self._assess(question, evidence)
-
-        # Reflection: "Did I use the tools correctly?"
-        reflection = await self._reflect_on_tool_use(tool_results)
-
-        # Final: combine assessment + reflection
-        return self._combine(initial, reflection)
-```
-
-**Why it's Gucci:** Catches tool misuse, improves accuracy, more robust judge.
-
-### Tier 2: Medium Lifts (4-8 hours each)
-
-#### From AutoGen: Concurrent Tool Execution
-Run multiple tools in parallel with proper error handling:
-
-```python
-# CURRENT: Sequential with asyncio.gather
-results = await asyncio.gather(*[tool.search(query) for tool in tools])
-
-# UPGRADE: AutoGen-style with cancellation + timeout
-from autogen_core import CancellationToken
-
-async def execute_tools_concurrent(tools, query, timeout=30):
-    token = CancellationToken()
-
-    async def run_with_timeout(tool):
-        try:
-            return await asyncio.wait_for(
-                tool.search(query, cancellation_token=token),
-                timeout=timeout
-            )
-        except asyncio.TimeoutError:
-            token.cancel()  # Cancel other tools
-            return ToolError(f"{tool.name} timed out")
-
-    return await asyncio.gather(*[run_with_timeout(t) for t in tools])
-```
-
-**Why it's Gucci:** Proper timeout handling, cancellation propagation, production-ready.
-
-#### From Claude SDK: Hooks System
-Add pre/post hooks for logging, validation, cost tracking:
-
-```python
-# UPGRADE: Hook system (stolen from Claude SDK)
-class HookManager:
-    async def pre_tool_use(self, tool_name, args):
-        """Called before every tool execution"""
-        logger.info(f"Calling {tool_name} with {args}")
-        self.cost_tracker.start_timer()
-
-    async def post_tool_use(self, tool_name, result, duration):
-        """Called after every tool execution"""
-        self.cost_tracker.record(tool_name, duration)
-        if result.is_error:
-            self.error_tracker.record(tool_name, result.error)
-```
-
-**Why it's Gucci:** Observability, debugging, cost tracking, production-ready.
-
-### Tier 3: Big Lifts (Post-Hackathon)
-
-#### Full AutoGen Integration
-If we want multi-agent capabilities later:
-
-```python
-# POST-HACKATHON: Multi-agent drug repurposing
-from autogen_agentchat import AssistantAgent, GroupChat
-
-literature_agent = AssistantAgent(
-    name="LiteratureReviewer",
-    tools=[pubmed_search, web_search],
-    system_message="You search and summarize medical literature."
-)
-
-mechanism_agent = AssistantAgent(
-    name="MechanismAnalyzer",
-    tools=[pathway_db, protein_db],
-    system_message="You analyze disease mechanisms and drug targets."
-)
-
-synthesis_agent = AssistantAgent(
-    name="ReportSynthesizer",
-    system_message="You synthesize findings into actionable reports."
-)
-
-# Orchestrate multi-agent workflow
-group_chat = GroupChat(
-    agents=[literature_agent, mechanism_agent, synthesis_agent],
-    max_round=10
-)
-```
-
-**Why it's Gucci:** True multi-agent collaboration, specialized roles, scalable.
-
----
-
-## Priority Order for Stretch Goals
-
-| Priority | Feature | Source | Effort | Impact |
-|----------|---------|--------|--------|--------|
-| 1 | `@tool` decorator | Claude SDK | 2 hrs | High - cleaner code |
-| 2 | Reflect on tool use | AutoGen | 3 hrs | High - better accuracy |
-| 3 | Hooks system | Claude SDK | 4 hrs | Medium - observability |
-| 4 | Concurrent + cancellation | AutoGen | 4 hrs | Medium - robustness |
-| 5 | Multi-agent | AutoGen | 8+ hrs | Post-hackathon |
-
----
-
-## The Bottom Line
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  MVP (Days 1-4): Pydantic AI + FastMCP                      │
-│  - Ship working drug repurposing agent                      │
-│  - Search-judge loop with PubMed + Web                      │
-│  - Gradio UI with streaming                                 │
-│  - MCP server for hackathon track                           │
-├─────────────────────────────────────────────────────────────┤
-│  If Crushing It (Days 5-6): Steal the Gucci                 │
-│  - @tool decorators from Claude SDK                         │
-│  - Reflect on tool use from AutoGen                         │
-│  - Hooks for observability                                  │
-├─────────────────────────────────────────────────────────────┤
-│  Post-Hackathon: Full AutoGen Integration                   │
-│  - Multi-agent workflows                                    │
-│  - Specialized agent roles                                  │
-│  - Production-grade orchestration                           │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Ship MVP first. Steal bangers if time. Scale later.**
-
----
-
-## 16. Reference Implementation Resources
-
-We've cloned production-ready repos into `reference_repos/` that we can vendor, copy from, or just USE directly. This section documents what's available and how to leverage it.
-
-### Cloned Repositories
-
-| Repository | Location | What It Provides |
-|------------|----------|------------------|
-| **pydanticai-research-agent** | `reference_repos/pydanticai-research-agent/` | Complete PydanticAI agent with Brave Search |
-| **pubmed-mcp-server** | `reference_repos/pubmed-mcp-server/` | Production-grade PubMed MCP server (TypeScript) |
-| **autogen-microsoft** | `reference_repos/autogen-microsoft/` | Microsoft's multi-agent framework |
-| **claude-agent-sdk** | `reference_repos/claude-agent-sdk/` | Anthropic's agent SDK with @tool decorator |
-
-### 🔥 CHEAT CODE: Production PubMed MCP Already Exists
-
-The `pubmed-mcp-server` is **production-grade** and has EVERYTHING we need:
-
-```bash
-# Already available tools in pubmed-mcp-server:
-pubmed_search_articles    # Search PubMed with filters, date ranges
-pubmed_fetch_contents     # Get full article details by PMID
-pubmed_article_connections # Find citations, related articles
-pubmed_research_agent     # Generate research plan outlines
-pubmed_generate_chart     # Create PNG charts from data
-```
-
-**Option 1: Use it directly via npx**
-```json
-{
-  "mcpServers": {
-    "pubmed": {
-      "command": "npx",
-      "args": ["@cyanheads/pubmed-mcp-server"],
-      "env": { "NCBI_API_KEY": "your_key" }
-    }
-  }
-}
-```
-
-**Option 2: Vendor the logic into Python**
-The TypeScript code in `reference_repos/pubmed-mcp-server/src/` shows exactly how to:
-- Construct PubMed E-utilities queries
-- Handle rate limiting (3/sec without key, 10/sec with key)
-- Parse XML responses
-- Extract article metadata
-
-### PydanticAI Research Agent Patterns
-
-The `pydanticai-research-agent` repo provides copy-paste patterns:
-
-**Agent Definition** (`agents/research_agent.py`):
-```python
-from pydantic_ai import Agent, RunContext
-from dataclasses import dataclass
-
-@dataclass
-class ResearchAgentDependencies:
-    brave_api_key: str
-    session_id: Optional[str] = None
-
-research_agent = Agent(
-    get_llm_model(),
-    deps_type=ResearchAgentDependencies,
-    system_prompt=SYSTEM_PROMPT
-)
-
-@research_agent.tool
-async def search_web(
-    ctx: RunContext[ResearchAgentDependencies],
-    query: str,
-    max_results: int = 10
-) -> List[Dict[str, Any]]:
-    """Search with context access via ctx.deps"""
-    results = await search_web_tool(ctx.deps.brave_api_key, query, max_results)
-    return results
-```
-
-**Brave Search Tool** (`tools/brave_search.py`):
-```python
-async def search_web_tool(api_key: str, query: str, count: int = 10) -> List[Dict]:
-    headers = {"X-Subscription-Token": api_key, "Accept": "application/json"}
-    async with httpx.AsyncClient() as client:
-        response = await client.get(
-            "https://api.search.brave.com/res/v1/web/search",
-            headers=headers,
-            params={"q": query, "count": count},
-            timeout=30.0
-        )
-    # Handle 429 rate limit, 401 auth errors
-    data = response.json()
-    return data.get("web", {}).get("results", [])
-```
-
-**Pydantic Models** (`models/research_models.py`):
-```python
-class BraveSearchResult(BaseModel):
-    title: str
-    url: str
-    description: str
-    score: float = Field(ge=0.0, le=1.0)
-```
-
-### Microsoft Agent Framework Orchestration Patterns
-
-From [deepwiki.com/microsoft/agent-framework](https://deepwiki.com/microsoft/agent-framework/3.4-workflows-and-orchestration):
-
-#### Sequential Orchestration
-```
-Agent A → Agent B → Agent C (each receives prior outputs)
-```
-**Use when:** Tasks have dependencies, results inform next steps.
-
-#### Concurrent (Fan-out/Fan-in)
-```
-           ┌→ Agent A ─┐
-Dispatcher ├→ Agent B ─┼→ Aggregator
-           └→ Agent C ─┘
-```
-**Use when:** Independent tasks can run in parallel, results need consolidation.
-**Our use:** Parallel PubMed + Web search.
-
-#### Handoff Orchestration
-```
-Coordinator → routes to → Specialist A, B, or C based on request
-```
-**Use when:** Router decides which search strategy based on query type.
-**Our use:** Route "mechanism" vs "clinical trial" vs "drug info" queries.
-
-#### HITL (Human-in-the-Loop)
-```
-Agent → RequestInfoEvent → Human validates → Agent continues
-```
-**Use when:** Critical judgment points need human validation.
-**Our use:** Optional "approve drug candidates before synthesis" step.
-
-### Recommended Hybrid Pattern for Our Agent
-
-Based on all the research, here's our recommended implementation:
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  1. ROUTER (Handoff Pattern)                             │
-│     - Analyze query type                                 │
-│     - Choose search strategy                             │
-├─────────────────────────────────────────────────────────┤
-│  2. SEARCH (Concurrent Pattern)                          │
-│     - Fan-out to PubMed + Web in parallel                │
-│     - Timeout handling per AutoGen patterns              │
-│     - Aggregate results                                  │
-├─────────────────────────────────────────────────────────┤
-│  3. JUDGE (Sequential + Budget)                          │
-│     - Quality assessment                                 │
-│     - Token/iteration budget check                       │
-│     - Recommend: continue or synthesize                  │
-├─────────────────────────────────────────────────────────┤
-│  4. SYNTHESIZE (Final Agent)                             │
-│     - Generate research report                           │
-│     - Include citations                                  │
-│     - Stream to Gradio UI                                │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Quick Start: Minimal Implementation Path
-
-**Day 1-2: Core Loop**
-1. Copy `search_web_tool` from `pydanticai-research-agent/tools/brave_search.py`
-2. Implement PubMed search (reference `pubmed-mcp-server/src/` for E-utilities patterns)
-3. Wire up basic search-judge loop
-
-**Day 3: Judge + State**
-1. Implement quality judge with JSON structured output
-2. Add budget judge
-3. Add Pydantic state management
-
-**Day 4: UI + MCP**
-1. Gradio streaming UI
-2. Wrap PubMed tool as FastMCP server
-
-**Day 5-6: Polish + Deploy**
-1. HuggingFace Spaces deployment
-2. Demo video
-3. Stretch goals if time
-
----
-
-## 17. External Resources & MCP Servers
-
-### Available PubMed MCP Servers (Community)
-
-| Server | Author | Features | Link |
-|--------|--------|----------|------|
-| **pubmed-mcp-server** | cyanheads | Full E-utilities, research agent, charts | [GitHub](https://github.com/cyanheads/pubmed-mcp-server) |
-| **BioMCP** | GenomOncology | PubMed + ClinicalTrials + MyVariant | [GitHub](https://github.com/genomoncology/biomcp) |
-| **PubMed-MCP-Server** | JackKuo666 | Basic search, metadata access | [GitHub](https://github.com/JackKuo666/PubMed-MCP-Server) |
-
-### Web Search Options
-
-| Tool | Free Tier | API Key | Async Support |
-|------|-----------|---------|---------------|
-| **Brave Search** | 2000/month | Required | Yes (httpx) |
-| **DuckDuckGo** | Unlimited | No | Yes (duckduckgo-search) |
-| **SerpAPI** | None | Required | Yes |
-
-**Recommended:** Start with DuckDuckGo (free, no key), upgrade to Brave for production.
-
-```python
-# DuckDuckGo async search (no API key needed!)
-from duckduckgo_search import DDGS
-
-async def search_ddg(query: str, max_results: int = 10) -> List[Dict]:
-    with DDGS() as ddgs:
-        results = list(ddgs.text(query, max_results=max_results))
-    return [{"title": r["title"], "url": r["href"], "description": r["body"]} for r in results]
-```
-
----
-
-**Document Status**: Official Architecture Spec
-**Review Score**: 100/100 (Ironclad Gucci Banger Edition)
-**Sections**: 17 design patterns + data models appendix + reference repos + stretch goals
-**Last Updated**: November 2025

docs/architecture/overview.md

@@ -1,474 +0,0 @@
-# DeepBoner: Medical Drug Repurposing Research Agent
-## Project Overview
-
----
-
-## Executive Summary
-
-**DeepBoner** is a deep research agent designed to accelerate medical drug repurposing research by autonomously searching, analyzing, and synthesizing evidence from multiple biomedical databases.
-
-### The Problem We Solve
-
-Drug repurposing - finding new therapeutic uses for existing FDA-approved drugs - can take years of manual literature review. Researchers must:
-- Search thousands of papers across multiple databases
-- Identify molecular mechanisms
-- Find relevant clinical trials
-- Assess safety profiles
-- Synthesize evidence into actionable insights
-
-**DeepBoner automates this process from hours to minutes.**
-
-### What Is Drug Repurposing?
-
-**Simple Explanation:**
-Using existing approved drugs to treat NEW diseases they weren't originally designed for.
-
-**Real Examples:**
-- **Viagra** (sildenafil): Originally for heart disease → Now treats erectile dysfunction
-- **Thalidomide**: Once banned → Now treats multiple myeloma
-- **Aspirin**: Pain reliever → Heart attack prevention
-- **Metformin**: Diabetes drug → Being tested for aging/longevity
-
-**Why It Matters:**
-- Faster than developing new drugs (years vs decades)
-- Cheaper (known safety profiles)
-- Lower risk (already FDA approved)
-- Immediate patient benefit potential
-
----
-
-## Core Use Case
-
-### Primary Query Type
-> "What existing drugs might help treat [disease/condition]?"
-
-### Example Queries
-
-1. **Long COVID Fatigue**
-   - Query: "What existing drugs might help treat long COVID fatigue?"
-   - Agent searches: PubMed, clinical trials, drug databases
-   - Output: List of candidate drugs with mechanisms + evidence + citations
-
-2. **Alzheimer's Disease**
-   - Query: "Find existing drugs that target beta-amyloid pathways"
-   - Agent identifies: Disease mechanisms → Drug candidates → Clinical evidence
-   - Output: Comprehensive research report with drug candidates
-
-3. **Rare Disease Treatment**
-   - Query: "What drugs might help with fibrodysplasia ossificans progressiva?"
-   - Agent finds: Similar conditions → Shared pathways → Potential treatments
-   - Output: Evidence-based treatment suggestions
-
----
-
-## System Architecture
-
-### High-Level Design (Phases 1-8)
-
-```text
-User Query
-    ↓
-Gradio UI (Phase 4)
-    ↓
-Magentic Manager (Phase 5) ← LLM-powered coordinator
-    ├── SearchAgent (Phase 2+5) ←→ PubMed + Web + VectorDB (Phase 6)
-    ├── HypothesisAgent (Phase 7) ←→ Mechanistic Reasoning
-    ├── JudgeAgent (Phase 3+5) ←→ Evidence Assessment
-    └── ReportAgent (Phase 8) ←→ Final Synthesis
-    ↓
-Structured Research Report
-```
-
-### Key Components
-
-1. **Magentic Manager (Orchestrator)**
-   - LLM-powered multi-agent coordinator
-   - Dynamic planning and agent selection
-   - Built-in stall detection and replanning
-   - Microsoft Agent Framework integration
-
-2. **SearchAgent (Phase 2+5+6)**
-   - PubMed E-utilities search
-   - DuckDuckGo web search
-   - Semantic search via ChromaDB (Phase 6)
-   - Evidence deduplication
-
-3. **HypothesisAgent (Phase 7)**
-   - Generates Drug → Target → Pathway → Effect hypotheses
-   - Guides targeted searches
-   - Scientific reasoning about mechanisms
-
-4. **JudgeAgent (Phase 3+5)**
-   - LLM-based evidence assessment
-   - Mechanism score + Clinical score
-   - Recommends continue/synthesize
-   - Generates refined search queries
-
-5. **ReportAgent (Phase 8)**
-   - Structured scientific reports
-   - Executive summary, methodology
-   - Hypotheses tested with evidence counts
-   - Proper citations and limitations
-
-6. **Gradio UI (Phase 4)**
-   - Chat interface for questions
-   - Real-time progress via events
-   - Mode toggle (Simple/Magentic)
-   - Formatted markdown output
-
----
-
-## Design Patterns
-
-### 1. Search-and-Judge Loop (Primary Pattern)
-
-```python
-def research(question: str) -> Report:
-    context = []
-    for iteration in range(max_iterations):
-        # SEARCH: Query relevant tools
-        results = search_tools(question, context)
-        context.extend(results)
-
-        # JUDGE: Evaluate quality
-        if judge.is_sufficient(question, context):
-            break
-
-        # REFINE: Adjust search strategy
-        query = refine_query(question, context)
-
-    # SYNTHESIZE: Generate report
-    return synthesize_report(question, context)
-```
-
-**Why This Pattern:**
-- Simple to implement and debug
-- Clear loop termination conditions
-- Iterative improvement of search quality
-- Balances depth vs speed
-
-### 2. Multi-Tool Orchestration
-
-```
-Question → Agent decides which tools to use
-           ↓
-       ┌───┴────┬─────────┬──────────┐
-       ↓        ↓         ↓          ↓
-   PubMed  Web Search  Trials DB  Drug DB
-       ↓        ↓         ↓          ↓
-       └───┬────┴─────────┴─────��────┘
-           ↓
-    Aggregate Results → Judge
-```
-
-**Why This Pattern:**
-- Different sources provide different evidence types
-- Parallel tool execution (when possible)
-- Comprehensive coverage
-
-### 3. LLM-as-Judge with Token Budget
-
-**Dual Stopping Conditions:**
-- **Smart Stop**: LLM judge says "we have sufficient evidence"
-- **Hard Stop**: Token budget exhausted OR max iterations reached
-
-**Why Both:**
-- Judge enables early exit when answer is good
-- Budget prevents runaway costs
-- Iterations prevent infinite loops
-
-### 4. Stateful Checkpointing
-
-```
-.deepresearch/
-├── state/
-│   └── query_123.json    # Current research state
-├── checkpoints/
-│   └── query_123_iter3/  # Checkpoint at iteration 3
-└── workspace/
-    └── query_123/        # Downloaded papers, data
-```
-
-**Why This Pattern:**
-- Resume interrupted research
-- Debugging and analysis
-- Cost savings (don't re-search)
-
----
-
-## Component Breakdown
-
-### Agent (Orchestrator)
-- **Responsibility**: Coordinate research process
-- **Size**: ~100 lines
-- **Key Methods**:
-  - `research(question)` - Main entry point
-  - `plan_search_strategy()` - Decide what to search
-  - `execute_search()` - Run tool queries
-  - `evaluate_progress()` - Call judge
-  - `synthesize_findings()` - Generate report
-
-### Tools
-- **Responsibility**: Interface with external data sources
-- **Size**: ~50 lines per tool
-- **Implementations**:
-  - `PubMedTool` - Search biomedical literature
-  - `WebSearchTool` - General medical information
-  - `ClinicalTrialsTool` - Trial data (optional)
-  - `DrugInfoTool` - FDA drug database (optional)
-
-### Judge
-- **Responsibility**: Evaluate evidence quality
-- **Size**: ~50 lines
-- **Key Methods**:
-  - `is_sufficient(question, evidence)` → bool
-  - `assess_quality(evidence)` → score
-  - `identify_gaps(question, evidence)` → missing_info
-
-### Gradio App
-- **Responsibility**: User interface
-- **Size**: ~50 lines
-- **Features**:
-  - Text input for questions
-  - Progress indicators
-  - Formatted output with citations
-  - Download research report
-
----
-
-## Technical Stack
-
-### Core Dependencies
-```toml
-[dependencies]
-python = ">=3.10"
-pydantic = "^2.7"
-pydantic-ai = "^0.0.16"
-fastmcp = "^0.1.0"
-gradio = "^5.0"
-beautifulsoup4 = "^4.12"
-httpx = "^0.27"
-```
-
-### Optional Enhancements
-- `modal` - For GPU-accelerated local LLM
-- `fastmcp` - MCP server integration
-- `sentence-transformers` - Semantic search
-- `faiss-cpu` - Vector similarity
-
-### Tool APIs & Rate Limits
-
-| API | Cost | Rate Limit | API Key? | Notes |
-|-----|------|------------|----------|-------|
-| **PubMed E-utilities** | Free | 3/sec (no key), 10/sec (with key) | Optional | Register at NCBI for higher limits |
-| **Brave Search API** | Free tier | 2000/month free | Required | Primary web search |
-| **DuckDuckGo** | Free | Unofficial, ~1/sec | No | Fallback web search |
-| **ClinicalTrials.gov** | Free | 100/min | No | Stretch goal |
-| **OpenFDA** | Free | 240/min (no key), 120K/day (with key) | Optional | Drug info |
-
-**Web Search Strategy (Priority Order):**
-1. **Brave Search API** (free tier: 2000 queries/month) - Primary
-2. **DuckDuckGo** (unofficial, no API key) - Fallback
-3. **SerpAPI** ($50/month) - Only if free options fail
-
-**Why NOT SerpAPI first?**
-- Costs money (hackathon budget = $0)
-- Free alternatives work fine for demo
-- Can upgrade later if needed
-
----
-
-## Success Criteria
-
-### Phase 1-5 (MVP) ✅ COMPLETE
-**Completed in ONE DAY:**
-- [x] User can ask drug repurposing question
-- [x] Agent searches PubMed (async)
-- [x] Agent searches web (DuckDuckGo)
-- [x] LLM judge evaluates evidence quality
-- [x] System respects token budget and iterations
-- [x] Output includes drug candidates + citations
-- [x] Works end-to-end for demo query
-- [x] Gradio UI with streaming progress
-- [x] Magentic multi-agent orchestration
-- [x] 38 unit tests passing
-- [x] CI/CD pipeline green
-
-### Hackathon Submission ✅ COMPLETE
-- [x] Gradio UI deployed on HuggingFace Spaces
-- [x] Example queries working and tested
-- [x] Architecture documentation
-- [x] README with setup instructions
-
-### Phase 6-8 (Enhanced)
-**Specs ready for implementation:**
-- [ ] Embeddings & Semantic Search (Phase 6)
-- [ ] Hypothesis Agent (Phase 7)
-- [ ] Report Agent (Phase 8)
-
-### What's EXPLICITLY Out of Scope
-**NOT building (to stay focused):**
-- ❌ User authentication
-- ❌ Database storage of queries
-- ❌ Multi-user support
-- ❌ Payment/billing
-- ❌ Production monitoring
-- ❌ Mobile UI
-
----
-
-## Implementation Timeline
-
-### Day 1 (Today): Architecture & Setup
-- [x] Define use case (drug repurposing) ✅
-- [x] Write architecture docs ✅
-- [ ] Create project structure
-- [ ] First PR: Structure + Docs
-
-### Day 2: Core Agent Loop
-- [ ] Implement basic orchestrator
-- [ ] Add PubMed search tool
-- [ ] Simple judge (keyword-based)
-- [ ] Test with 1 query
-
-### Day 3: Intelligence Layer
-- [ ] Upgrade to LLM judge
-- [ ] Add web search tool
-- [ ] Token budget tracking
-- [ ] Test with multiple queries
-
-### Day 4: UI & Integration
-- [ ] Build Gradio interface
-- [ ] Wire up agent to UI
-- [ ] Add progress indicators
-- [ ] Format output nicely
-
-### Day 5: Polish & Extend
-- [ ] Add more tools (clinical trials)
-- [ ] Improve judge prompts
-- [ ] Checkpoint system
-- [ ] Error handling
-
-### Day 6: Deploy & Document
-- [ ] Deploy to HuggingFace Spaces
-- [ ] Record demo video
-- [ ] Write submission materials
-- [ ] Final testing
-
----
-
-## Questions This Document Answers
-
-### For The Maintainer
-
-**Q: "What should our design pattern be?"**
-A: Search-and-judge loop with multi-tool orchestration (detailed in Design Patterns section)
-
-**Q: "Should we use LLM-as-judge or token budget?"**
-A: Both - judge for smart stopping, budget for cost control
-
-**Q: "What's the break pattern?"**
-A: Three conditions: judge approval, token limit, or max iterations (whichever comes first)
-
-**Q: "What components do we need?"**
-A: Agent orchestrator, tools (PubMed/web), judge, Gradio UI (see Component Breakdown)
-
-### For The Team
-
-**Q: "What are we actually building?"**
-A: Medical drug repurposing research agent (see Core Use Case)
-
-**Q: "How complex should it be?"**
-A: Simple but complete - ~300 lines of core code (see Component sizes)
-
-**Q: "What's the timeline?"**
-A: 6 days, MVP by Day 3, polish Days 4-6 (see Implementation Timeline)
-
-**Q: "What datasets/APIs do we use?"**
-A: PubMed (free), web search, clinical trials.gov (see Tool APIs)
-
----
-
-## Next Steps
-
-1. **Review this document** - Team feedback on architecture
-2. **Finalize design** - Incorporate feedback
-3. **Create project structure** - Scaffold repository
-4. **Move to proper docs** - `docs/architecture/` folder
-5. **Open first PR** - Structure + Documentation
-6. **Start implementation** - Day 2 onward
-
----
-
-## Notes & Decisions
-
-### Why Drug Repurposing?
-- Clear, impressive use case
-- Real-world medical impact
-- Good data availability (PubMed, trials)
-- Easy to explain (Viagra example!)
-- Physician on team ✅
-
-### Why Simple Architecture?
-- 6-day timeline
-- Need working end-to-end system
-- Hackathon judges value "works" over "complex"
-- Can extend later if successful
-
-### Why These Tools First?
-- PubMed: Best biomedical literature source
-- Web search: General medical knowledge
-- Clinical trials: Evidence of actual testing
-- Others: Nice-to-have, not critical for MVP
-
----
-
----
-
-## Appendix A: Demo Queries (Pre-tested)
-
-These queries will be used for demo and testing. They're chosen because:
-1. They have good PubMed coverage
-2. They're medically interesting
-3. They show the system's capabilities
-
-### Primary Demo Query
-```
-"What existing drugs might help treat long COVID fatigue?"
-```
-**Expected candidates**: CoQ10, Low-dose Naltrexone, Modafinil
-**Expected sources**: 20+ PubMed papers, 2-3 clinical trials
-
-### Secondary Demo Queries
-```
-"Find existing drugs that might slow Alzheimer's progression"
-"What approved medications could help with fibromyalgia pain?"
-"Which diabetes drugs show promise for cancer treatment?"
-```
-
-### Why These Queries?
-- Represent real clinical needs
-- Have substantial literature
-- Show diverse drug classes
-- Physician on team can validate results
-
----
-
-## Appendix B: Risk Assessment
-
-| Risk | Likelihood | Impact | Mitigation |
-|------|------------|--------|------------|
-| PubMed rate limiting | Medium | High | Implement caching, respect 3/sec |
-| Web search API fails | Low | Medium | DuckDuckGo fallback |
-| LLM costs exceed budget | Medium | Medium | Hard token cap at 50K |
-| Judge quality poor | Medium | High | Pre-test prompts, iterate |
-| HuggingFace deploy issues | Low | High | Test deployment Day 4 |
-| Demo crashes live | Medium | High | Pre-recorded backup video |
-
----
-
----
-
-**Document Status**: Official Architecture Spec
-**Review Score**: 98/100
-**Last Updated**: November 2025

docs/architecture/system_registry.md

@@ -1,6 +1,6 @@
 # System Registry & Wiring Architecture
 **Status**: Active / Canonical
-**Last Updated**: 2025-12-03
+**Last Updated**: 2025-12-06
 
 This document serves as the **Source of Truth** for the architectural wiring of the agent framework. It defines the strict rules for decorators, protocol markers, and the tool registry to prevent regression and ensure correct system behavior.
 
@@ -56,12 +56,12 @@ These are the `@ai_function` decorated functions that agents can invoke. The fra
 
 | Function Name | File Path | Description |
 |:---|:---|:---|
-| `search_pubmed` | `src/agents/tools.py:21` | Searches PubMed for biomedical literature |
-| `search_clinical_trials` | `src/agents/tools.py:81` | Searches ClinicalTrials.gov for clinical studies |
-| `search_preprints` | `src/agents/tools.py:121` | Searches Europe PMC for preprints and papers |
-| `get_bibliography` | `src/agents/tools.py:161` | Returns collected references for final report |
+| `search_pubmed` | `src/agents/tools.py:20` | Searches PubMed for biomedical literature |
+| `search_clinical_trials` | `src/agents/tools.py:80` | Searches ClinicalTrials.gov for clinical studies |
+| `search_preprints` | `src/agents/tools.py:120` | Searches Europe PMC for preprints and papers |
+| `get_bibliography` | `src/agents/tools.py:160` | Returns collected references for final report |
+| `search_web` | `src/agents/retrieval_agent.py:17` | Searches web using DuckDuckGo |
 | ~~`execute_python_code`~~ | ~~`src/agents/code_executor_agent.py`~~ | REMOVED in PR #130 (Modal deleted) |
-| ~~`search_web`~~ | ~~`src/agents/retrieval_agent.py`~~ | REMOVED in PR #130 (unused) |
 
 ### 3.2 Tool Classes (Internal Wrappers)
 
@@ -73,9 +73,11 @@ These are **internal implementation wrappers** used by the AI Functions. They ar
 | `ClinicalTrialsTool` | `src/tools/clinicaltrials.py` | `search_clinical_trials` |
 | `EuropePMCTool` | `src/tools/europepmc.py` | `search_preprints` |
 | `OpenAlexTool` | `src/tools/openalex.py` | OpenAlex search (used in SearchHandler) |
+| `WebSearchTool` | `src/tools/web_search.py` | `search_web` (DuckDuckGo) |
 | `SearchHandler` | `src/tools/search_handler.py` | Orchestrates parallel searches |
+| `RateLimiter` | `src/tools/rate_limiter.py` | Rate limiting via `limits` library |
+| `BaseTool` | `src/tools/base.py` | Abstract base class for tools |
 | ~~`ModalCodeExecutor`~~ | ~~`src/tools/code_execution.py`~~ | REMOVED in PR #130 |
-| ~~`WebSearchTool`~~ | ~~`src/tools/web_search.py`~~ | REMOVED in PR #130 |
 
 ---
 
@@ -119,8 +121,8 @@ class NewProviderChatClient(BaseChatClient):
 
 ## 5. Known Issues & Gotchas
 
-*   **~~P1 Bug - Premature Marker Setting~~ (FIXED):** The `HuggingFaceChatClient` previously set `__function_invoking_chat_client__ = True` in the class body, which caused `@use_function_invocation` to skip wrapping. **Resolution:** Marker removed; decorator now sets it correctly. See `docs/bugs/P1_FREE_TIER_TOOL_EXECUTION_FAILURE.md`.
-*   **HuggingFace Provider Routing:** Qwen2.5-7B-Instruct routes to Together.ai (not native HF). Tool call parsing may be inconsistent with complex multi-agent prompts.
+*   **~~P1 Bug - Premature Marker Setting~~ (FIXED):** The `HuggingFaceChatClient` previously set `__function_invoking_chat_client__ = True` in the class body, which caused `@use_function_invocation` to skip wrapping. **Resolution:** Marker removed; decorator now sets it correctly.
+*   **HuggingFace Provider Routing:** Large models (70B+) may be routed to third-party inference providers (Novita, Hyperbolic) instead of native HF infrastructure. See `CLAUDE.md` for current model recommendations.
 *   **Model Hallucination:** If tool execution fails (due to incorrect wiring), models like Qwen2.5-7B will often **hallucinate** fake tool results as text. Always verify `AgentRunResponse` contains actual `FunctionResultContent`.
 
 ---

docs/architecture/workflow-diagrams.md

@@ -1,8 +1,24 @@
-# DeepBoner Workflow - Simplified Magentic Architecture
+# DeepBoner Workflow - Magentic Architecture
 
 > **Architecture Pattern**: Microsoft Magentic Orchestration
 > **Design Philosophy**: Simple, dynamic, manager-driven coordination
 > **Key Innovation**: Intelligent manager replaces rigid sequential phases
+> **Last Updated**: 2025-12-06
+
+## Current Agent Inventory
+
+| Agent | File | Status |
+|-------|------|--------|
+| Manager | `AdvancedOrchestrator` | ✅ Implemented |
+| Hypothesis Agent | `hypothesis_agent.py` | ✅ Implemented |
+| Search Agent | `search_agent.py` | ✅ Implemented |
+| Judge Agent | `judge_agent.py` | ✅ Implemented |
+| Report Agent | `report_agent.py` | ✅ Implemented |
+| Retrieval Agent | `retrieval_agent.py` | ✅ Implemented (web search) |
+| ~~Analysis Agent~~ | N/A | ❌ Not implemented (no code execution) |
+
+> **Note:** Some diagrams below show "AnalysisAgent" with code execution capabilities.
+> This was planned but not implemented. Modal code execution was removed in PR #130.
 
 ---
 
@@ -371,7 +387,7 @@ flowchart TD
     style CodeExec fill:#f0f0f0
 ```
 
-## 11. MCP Tool Architecture
+## 11. Tool Architecture
 
 ```mermaid
 graph TB
@@ -379,52 +395,50 @@ graph TB
         Manager[Magentic Manager]
         HypAgent[Hypothesis Agent]
         SearchAgent[Search Agent]
-        AnalysisAgent[Analysis Agent]
+        JudgeAgent[Judge Agent]
         ReportAgent[Report Agent]
     end
 
-    subgraph "MCP Protocol Layer"
-        Registry[MCP Tool Registry<br/>• Discovers tools<br/>• Routes requests<br/>• Manages connections]
+    subgraph "Tool Layer (Direct Calls)"
+        Tools[AI Functions<br/>@ai_function decorated<br/>• search_pubmed<br/>• search_clinical_trials<br/>• search_preprints<br/>• search_web<br/>• get_bibliography]
     end
 
-    subgraph "MCP Servers"
-        Server1[Web Search Server<br/>localhost:8001<br/>• PubMed<br/>• ClinicalTrials<br/>• Europe PMC]
-        Server2[Code Execution Server<br/>localhost:8002<br/>• Sandboxed Python<br/>• Package management]
-        Server3[RAG Server<br/>localhost:8003<br/>• Vector embeddings<br/>• Similarity search]
-        Server4[Visualization Server<br/>localhost:8004<br/>• Chart generation<br/>• Plot rendering]
+    subgraph "Tool Wrappers"
+        PubMedTool[PubMedTool]
+        TrialsTool[ClinicalTrialsTool]
+        EuropePMCTool[EuropePMCTool]
+        WebSearchTool[WebSearchTool]
     end
 
-    subgraph "External Services"
-        PubMed[PubMed API]
+    subgraph "External APIs"
+        PubMed[PubMed E-utilities]
         Trials[ClinicalTrials.gov API]
         EuropePMC[Europe PMC API]
-        Modal[Modal Sandbox]
-        ChromaDB[(ChromaDB)]
+        DDG[DuckDuckGo]
     end
 
-    SearchAgent -->|Request| Registry
-    AnalysisAgent -->|Request| Registry
-    ReportAgent -->|Request| Registry
+    SearchAgent -->|Calls| Tools
+    Tools --> PubMedTool
+    Tools --> TrialsTool
+    Tools --> EuropePMCTool
+    Tools --> WebSearchTool
 
-    Registry --> Server1
-    Registry --> Server2
-    Registry --> Server3
-    Registry --> Server4
-
-    Server1 --> PubMed
-    Server1 --> Trials
-    Server1 --> EuropePMC
-    Server2 --> Modal
-    Server3 --> ChromaDB
+    PubMedTool --> PubMed
+    TrialsTool --> Trials
+    EuropePMCTool --> EuropePMC
+    WebSearchTool --> DDG
 
     style Manager fill:#ffe6e6
-    style Registry fill:#fff4e6
-    style Server1 fill:#e6f3ff
-    style Server2 fill:#e6f3ff
-    style Server3 fill:#e6f3ff
-    style Server4 fill:#e6f3ff
+    style Tools fill:#fff4e6
+    style PubMedTool fill:#e6f3ff
+    style TrialsTool fill:#e6f3ff
+    style EuropePMCTool fill:#e6f3ff
+    style WebSearchTool fill:#e6f3ff
 ```
 
+> **Note:** MCP support is provided via Gradio's built-in `mcp_server=True` option in `src/app.py`.
+> This exposes the Gradio interface as an MCP server for Claude Desktop integration.
+
 ## 12. Progress Tracking & Stall Detection
 
 ```mermaid
@@ -519,18 +533,18 @@ graph LR
     DC -->|Literature search| PubMed[PubMed API<br/>Medical papers]
     DC -->|Clinical trials| Trials[ClinicalTrials.gov<br/>Trial data]
     DC -->|Preprints| EuropePMC[Europe PMC API<br/>Preprints & papers]
-    DC -->|Agent reasoning| Claude[Claude API<br/>Sonnet 4 / Opus]
-    DC -->|Code execution| Modal[Modal Sandbox<br/>Safe Python env]
-    DC -->|Vector storage| Chroma[ChromaDB<br/>Embeddings & RAG]
+    DC -->|Web search| DDG[DuckDuckGo<br/>General web]
+    DC -->|Agent reasoning| LLM[LLM Backend<br/>OpenAI or HuggingFace]
+    DC -->|Embeddings| Embed[SentenceTransformers<br/>Local embeddings]
 
-    DC -->|Deployed on| HF[HuggingFace Spaces<br/>Gradio 6.0]
+    DC -->|Deployed on| HF[HuggingFace Spaces<br/>Gradio 5.x]
 
     PubMed -->|Results| DC
     Trials -->|Results| DC
     EuropePMC -->|Results| DC
-    Claude -->|Responses| DC
-    Modal -->|Output| DC
-    Chroma -->|Context| DC
+    DDG -->|Results| DC
+    LLM -->|Responses| DC
+    Embed -->|Vectors| DC
 
     DC -->|Research report| User
 
@@ -539,9 +553,9 @@ graph LR
     style PubMed fill:#e6f3ff
     style Trials fill:#e6f3ff
     style EuropePMC fill:#e6f3ff
-    style Claude fill:#ffd6d6
-    style Modal fill:#f0f0f0
-    style Chroma fill:#ffe6f0
+    style DDG fill:#e6f3ff
+    style LLM fill:#ffd6d6
+    style Embed fill:#ffe6f0
     style HF fill:#d4edda
 ```
 
@@ -645,18 +659,20 @@ workflow = (
 )
 ```
 
-**Manager handles quality assessment in its instructions:**
-- Checks hypothesis quality (testable, novel, clear)
-- Validates search results (relevant, authoritative, recent)
-- Assesses analysis soundness (methodology, evidence, conclusions)
-- Ensures report completeness (all sections, proper citations)
+**Current Agent Capabilities:**
+- **HypothesisAgent**: Generates research hypotheses
+- **SearchAgent**: Multi-source search (PubMed, ClinicalTrials, Europe PMC)
+- **JudgeAgent**: Evaluates evidence quality, determines sufficiency
+- **ReportAgent**: Generates final research report
+- **RetrievalAgent**: Web search via DuckDuckGo
 
-No separate Judge Agent needed - manager does it all!
+**Manager** (AdvancedOrchestrator) coordinates agent execution and workflow.
 
 ---
 
-**Document Version**: 2.0 (Magentic Simplified)
-**Last Updated**: 2025-12-05
+**Document Version**: 2.1 (Revised for accuracy)
+**Last Updated**: 2025-12-06
 **Architecture**: Microsoft Magentic Orchestration Pattern
-**Agents**: 4 (Hypothesis, Search, Analysis, Report) + 1 Manager
+**Implemented Agents**: 5 (Hypothesis, Search, Judge, Report, Retrieval) + Manager
+**Planned but Not Implemented**: Analysis Agent (code execution removed in PR #130)
 **License**: MIT

docs/guides/deployment.md

@@ -1,142 +0,0 @@
-# Deployment Guide
-## Launching DeepBoner: Gradio, MCP, & Modal
-
----
-
-## Overview
-
-DeepBoner is designed for a multi-platform deployment strategy to maximize hackathon impact:
-
-1. **HuggingFace Spaces**: Host the Gradio UI (User Interface).
-2. **MCP Server**: Expose research tools to Claude Desktop/Agents.
-3. **Modal (Optional)**: Run heavy inference or local LLMs if API costs are prohibitive.
-
----
-
-## 1. HuggingFace Spaces (Gradio UI)
-
-**Goal**: A public URL where judges/users can try the research agent.
-
-### Prerequisites
-- HuggingFace Account
-- `gradio` installed (`uv add gradio`)
-
-### Steps
-
-1. **Create Space**:
-   - Go to HF Spaces -> Create New Space.
-   - SDK: **Gradio**.
-   - Hardware: **CPU Basic** (Free) is sufficient (since we use APIs).
-
-2. **Prepare Files**:
-   - Ensure `app.py` contains the Gradio interface construction.
-   - Ensure `requirements.txt` or `pyproject.toml` lists all dependencies.
-
-3. **Secrets**:
-   - Go to Space Settings -> **Repository secrets**.
-   - Add `ANTHROPIC_API_KEY` (or your chosen LLM provider key).
-   - Add `BRAVE_API_KEY` (for web search).
-
-4. **Deploy**:
-   - Push code to the Space's git repo.
-   - Watch "Build" logs.
-
-### Streaming Optimization
-Ensure `app.py` uses generator functions for the chat interface to prevent timeouts:
-```python
-# app.py
-def predict(message, history):
-    agent = ResearchAgent()
-    for update in agent.research_stream(message):
-        yield update
-```
-
----
-
-## 2. MCP Server Deployment
-
-**Goal**: Allow other agents (like Claude Desktop) to use our PubMed/Research tools directly.
-
-### Local Usage (Claude Desktop)
-
-1. **Install**:
-   ```bash
-   uv sync
-   ```
-
-2. **Configure Claude Desktop**:
-   Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
-   ```json
-   {
-     "mcpServers": {
-       "deepboner": {
-         "command": "uv",
-         "args": ["run", "fastmcp", "run", "src/mcp_servers/pubmed_server.py"],
-         "cwd": "/absolute/path/to/DeepBoner"
-       }
-     }
-   }
-   ```
-
-3. **Restart Claude**: You should see a 🔌 icon indicating connected tools.
-
-### Remote Deployment (Smithery/Glama)
-*Target for "MCP Track" bonus points.*
-
-1. **Dockerize**: Create a `Dockerfile` for the MCP server.
-   ```dockerfile
-   FROM python:3.11-slim
-   COPY . /app
-   RUN pip install fastmcp httpx
-   CMD ["fastmcp", "run", "src/mcp_servers/pubmed_server.py", "--transport", "sse"]
-   ```
-   *Note: Use SSE transport for remote/HTTP servers.*
-
-2. **Deploy**: Host on Fly.io or Railway.
-
----
-
-## 3. Modal (GPU/Heavy Compute)
-
-**Goal**: Run a local LLM (e.g., Llama-3-70B) or handle massive parallel searches if APIs are too slow/expensive.
-
-### Setup
-1. **Install**: `uv add modal`
-2. **Auth**: `modal token new`
-
-### Logic
-Instead of calling Anthropic API, we call a Modal function:
-
-```python
-# src/llm/modal_client.py
-import modal
-
-stub = modal.Stub("deepboner-inference")
-
-@stub.function(gpu="A100")
-def generate_text(prompt: str):
-    # Load vLLM or similar
-    ...
-```
-
-### When to use?
-- **Hackathon Demo**: Stick to Anthropic/OpenAI APIs for speed/reliability.
-- **Production/Stretch**: Use Modal if you hit rate limits or want to show off "Open Source Models" capability.
-
----
-
-## Deployment Checklist
-
-### Pre-Flight
-- [ ] Run `pytest -m unit` to ensure logic is sound.
-- [ ] Run `pytest -m e2e` (one pass) to verify APIs connect.
-- [ ] Check `requirements.txt` matches `pyproject.toml`.
-
-### Secrets Management
-- [ ] **NEVER** commit `.env` files.
-- [ ] Verify keys are added to HF Space settings.
-
-### Post-Launch
-- [ ] Test the live URL.
-- [ ] Verify "Stop" button in Gradio works (interrupts the agent).
-- [ ] Record a walkthrough video (crucial for hackathon submission).