docs/ARCHITECTURE.md

DeepBoner Architecture

Last Updated: 2025-12-01

---

How It Works (Simple Version)

┌─────────────────────────────────────────────────────────────┐
│                    UNIFIED ARCHITECTURE                      │
│                                                              │
│   User provides API key?                                     │
│                                                              │
│   NO (Free Tier)              YES (Paid Tier)               │
│   ──────────────              ───────────────               │
│   HuggingFace backend         OpenAI backend                │
│   Qwen 2.5 72B (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

Free Tier is BLOCKED by upstream bug #2562.

Once PR #2566 merges:

1. Update agent-framework dependency
2. Free tier works
3. Done

---

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:

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 72B (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.

---

Upstream Blocker

Bug: Microsoft Agent Framework produces repr() garbage for tool-call-only messages.

Fix: PR #2566 - waiting to merge.

Tracking: Issue #2562

---

References

• Pydantic AI - Structured outputs framework
• Microsoft Agent Framework - Multi-agent orchestration
• AG-UI Protocol - How they integrate