File size: 3,813 Bytes
c6e9843 21dd8fe c6e9843 21dd8fe c6e9843 21dd8fe c6e9843 21dd8fe c6e9843 21dd8fe c6e9843 |
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 |
# DeepBoner Architecture
> **Last Updated**: 2025-12-03
---
## How It Works (Simple Version)
```text
┌─────────────────────────────────────────────────────────────┐
│ UNIFIED ARCHITECTURE │
│ │
│ User provides API key? │
│ │
│ NO (Free Tier) YES (Paid Tier) │
│ ────────────── ─────────────── │
│ HuggingFace backend OpenAI backend │
│ Qwen 2.5 7B (free) GPT-5 (paid) │
│ │
│ SAME orchestration logic for both │
│ ONE codebase, different LLM backends │
└─────────────────────────────────────────────────────────────┘
```
**That's it.** No "modes." Just: do you have an API key or not?
---
## Current Status
**Both tiers are WORKING** as of December 2025.
- **Free Tier**: Uses Accumulator Pattern to bypass upstream repr bug
- **Paid Tier**: Full OpenAI GPT-5 integration
---
## Key Fixes Applied
| Issue | Fix | PR |
|-------|-----|-----|
| Tool execution failure | Removed premature `__function_invoking_chat_client__` marker | fix/P1-free-tier |
| Repr garbage in output | Accumulator Pattern bypasses upstream bug | PR #117 |
| 72B model routing failures | Switched to 7B (native HF infra) | PR #118 |
| Evidence deduplication | Cross-source dedup by PMID/DOI | PR #122 |
---
## Framework Stack
DeepBoner uses TWO frameworks that work TOGETHER:
| Framework | What It Does | Where Used |
|-----------|--------------|------------|
| **Microsoft Agent Framework** | Multi-agent orchestration | `src/orchestrators/advanced.py` |
| **Pydantic AI** | Structured outputs, validation | `src/agent_factory/judges.py`, `src/agents/*.py` |
**They are NOT mutually exclusive.** Microsoft AF handles the orchestration (Manager → Search → Judge → Report). Pydantic AI handles structured outputs within those agents.
---
## LLM Backend Selection
Auto-detected by `src/clients/factory.py`:
```python
def get_chat_client():
if settings.has_openai_key:
return OpenAIChatClient(...) # Paid tier
else:
return HuggingFaceChatClient(...) # Free tier
```
| Condition | Backend | Model |
|-----------|---------|-------|
| User provides OpenAI key | OpenAI | GPT-5 |
| No API key provided | HuggingFace | Qwen 2.5 7B (free) |
---
## Key Files
| File | Purpose |
|------|---------|
| `src/orchestrators/advanced.py` | Multi-agent orchestration (Microsoft AF) |
| `src/clients/factory.py` | Auto-selects LLM backend |
| `src/clients/huggingface.py` | HuggingFace adapter for free tier |
| `src/agent_factory/judges.py` | Judge logic (Pydantic AI) |
| `src/agents/*.py` | Individual agents (Pydantic AI) |
---
## What Was Deleted
`simple.py` (778 lines) was a SEPARATE orchestrator that created a "parallel universe." It's gone. Now there's ONE orchestrator with different backends.
---
## References
- [Pydantic AI](https://ai.pydantic.dev/) - Structured outputs framework
- [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) - Multi-agent orchestration
- [AG-UI Protocol](https://www.copilotkit.ai/blog/introducing-pydantic-ai-integration-with-ag-ui) - How they integrate
|