File size: 13,016 Bytes
59ce7b1 c7a2e77 59ce7b1 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 |
# Architecture Overview
> **Last Updated**: 2025-12-06
This document provides a comprehensive overview of DeepBoner's architecture.
## System Purpose
DeepBoner is an **AI-native sexual health research agent** that autonomously:
1. Searches biomedical databases (PubMed, ClinicalTrials.gov, Europe PMC, OpenAlex)
2. Evaluates evidence quality
3. Synthesizes research reports with citations
## High-Level Architecture
```
┌─────────────────────────────────────────────────────────────────────┐
│ USER INTERFACE │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Gradio UI │ │ MCP Server │ │ Examples │ │
│ │ (src/app) │ │(mcp_tools.py)│ │ (scripts) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼───────────────────┼───────────────────┼───────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ ORCHESTRATION LAYER │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ AdvancedOrchestrator │ │
│ │ (Microsoft Agent Framework) │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Search │ → │ Judge │ → │ Report │ │ │
│ │ │ Agent │ │ Agent │ │ Agent │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ LangGraph Orchestrator │ │
│ │ (Experimental) │ │
│ └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ LLM BACKENDS │
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ OpenAI Client │ │ HuggingFace Client │ │
│ │ (GPT-5) │ │ (Qwen 2.5 7B) │ │
│ │ Premium Tier │ │ Free Tier │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
│ Auto-selected by ClientFactory based on API key │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ SEARCH TOOLS │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────┐ │
│ │ PubMed │ │ClinicalTrials│ │EuropePMC │ │ OpenAlex │ │
│ └──────────┘ └──────────────┘ └──────────┘ └──────────┘ │
│ │
│ SearchHandler: Parallel scatter-gather │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ SERVICES │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Embeddings │ │ LlamaIndex │ │ Research │ │
│ │ Service │ │ RAG │ │ Memory │ │
│ │ (local) │ │ (premium) │ │ (shared) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ChromaDB Vector Store │
└─────────────────────────────────────────────────────────────────────┘
```
## Core Research Loop
The system operates on a **search-and-judge loop**:
```
User Question
│
▼
┌─────────────┐
│ SEARCH │ ← Query PubMed, ClinicalTrials, Europe PMC, OpenAlex
└──────┬──────┘
│
▼
┌─────────────┐
│ GATHER │ ← Collect and deduplicate evidence (PMID/DOI)
└──────┬──────┘
│
▼
┌─────────────┐ ┌──────────────────┐
│ JUDGE │ ──► │ "Enough evidence?"│
└──────┬──────┘ └────────┬─────────┘
│ │
│ ┌────────────────┴────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐
│ REFINE │ ← NO: Expand query │ SYNTHESIZE │ ← YES: Generate report
│ & LOOP │ and search again └─────────────┘
└─────────────┘
```
**Break Conditions:**
- Judge approves evidence as sufficient
- Token budget exceeded (50K max)
- Max iterations reached (default 10)
## Framework Integration
DeepBoner combines two AI frameworks:
| Framework | Role | Usage |
|-----------|------|-------|
| **Microsoft Agent Framework** | Multi-agent orchestration | Manager → Agent coordination |
| **Pydantic AI** | Structured outputs | Evidence models, judge assessments |
They work together - Microsoft AF handles the workflow, Pydantic AI handles data validation.
## Dual-Backend Architecture
The system auto-selects LLM backend:
```python
# src/clients/factory.py
def get_chat_client():
if settings.has_openai_key:
return OpenAIChatClient(...) # Premium
else:
return HuggingFaceChatClient(...) # Free
```
| Tier | Backend | Model | Features |
|------|---------|-------|----------|
| Free | HuggingFace | Qwen 2.5 7B | Full functionality, slower |
| Premium | OpenAI | GPT-5 | Full functionality, faster |
**Same orchestration logic** - only the LLM differs.
## Key Components
### Orchestrators (`src/orchestrators/`)
| Component | File | Purpose |
|-----------|------|---------|
| AdvancedOrchestrator | `advanced.py` | Main multi-agent orchestrator |
| OrchestratorFactory | `factory.py` | Backend selection |
| LangGraphOrchestrator | `langgraph_orchestrator.py` | Experimental workflow engine |
### Agents (`src/agents/`)
| Agent | File | Role | Status |
|-------|------|------|--------|
| SearchAgent | `search_agent.py` | Evidence retrieval | ✅ Active |
| JudgeAgent | `judge_agent.py` | Evidence evaluation | ✅ Active |
| ReportAgent | `report_agent.py` | Report synthesis | ✅ Active |
| HypothesisAgent | `hypothesis_agent.py` | Mechanistic pathway analysis | ✅ Active |
| RetrievalAgent | `retrieval_agent.py` | Web search (DuckDuckGo) | ⚠️ Not wired (see #134) |
### Tools (`src/tools/`)
| Tool | File | API |
|------|------|-----|
| PubMed | `pubmed.py` | NCBI E-utilities |
| ClinicalTrials | `clinicaltrials.py` | ClinicalTrials.gov |
| EuropePMC | `europepmc.py` | Europe PMC API |
| OpenAlex | `openalex.py` | OpenAlex API |
| SearchHandler | `search_handler.py` | Parallel orchestration |
### Services (`src/services/`)
| Service | File | Purpose |
|---------|------|---------|
| EmbeddingService | `embeddings.py` | Local embeddings (sentence-transformers) |
| LlamaIndexRAG | `llamaindex_rag.py` | Premium RAG (OpenAI embeddings) |
| ResearchMemory | `research_memory.py` | Shared state across agents |
## Data Flow
1. **User Input** → Gradio UI / MCP Client
2. **Query** → AdvancedOrchestrator
3. **Search** → SearchHandler → [PubMed, ClinicalTrials, EuropePMC, OpenAlex]
4. **Evidence** → Deduplicated by PMID/DOI
5. **Judge** → LLM evaluates sufficiency
6. **Loop or Synthesize** → Based on judge decision
7. **Report** → Structured output with citations
8. **Response** → Back to user
## Configuration
Settings are loaded from environment via Pydantic Settings:
```python
# src/utils/config.py
class Settings(BaseSettings):
openai_api_key: str | None
huggingface_model: str = "Qwen/Qwen2.5-7B-Instruct"
max_iterations: int = 10
# ...
```
See [Configuration Reference](../reference/configuration.md) for all options.
## Related Documentation
- [Component Inventory](component-inventory.md) - Complete module catalog
- [Data Models](data-models.md) - Pydantic model reference
- [System Registry](system-registry.md) - Service wiring specification
- [Workflow Diagrams](workflow-diagrams.md) - Visual documentation
---
*"Architecturally rock solid."* 🏛️
|