# 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