docs: Add comprehensive documentation structure

Add professional documentation structure with:

Root-level standard docs:
- CONTRIBUTING.md - Contribution guidelines
- CHANGELOG.md - Release history tracking
- SECURITY.md - Vulnerability reporting policy
- CODE_OF_CONDUCT.md - Community standards

Documentation index:
- docs/README.md - Navigation and overview

Getting started guides:
- installation.md - Setup instructions
- quickstart.md - 5-minute guide
- configuration.md - Configuration options
- troubleshooting.md - Common issues

Architecture documentation:
- overview.md - High-level architecture
- component-inventory.md - Complete module catalog
- data-models.md - Pydantic model reference
- exception-hierarchy.md - Exception types

Development guides:
- testing.md - Testing strategy and patterns
- code-style.md - Style conventions
- release-process.md - Release workflow

Deployment guides:
- docker.md - Container deployment
- huggingface-spaces.md - Cloud deployment
- mcp-integration.md - MCP server setup

Technical debt tracking:
- index.md - Debt overview
- debt-registry.md - Itemized debt items (14 tracked)

Reference documentation:
- configuration.md - All config options
- environment-variables.md - Env var reference

CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to DeepBoner will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive documentation structure (CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md)
+- Technical debt tracking documentation
+- Component inventory documentation
+- Data models reference documentation
+
+## [0.1.0] - 2025-12-04
+
+### Added
+- **Core Research Agent**
+  - Search-and-judge loop with multi-tool orchestration
+  - PubMed E-utilities API integration
+  - ClinicalTrials.gov API integration
+  - Europe PMC API integration
+  - OpenAlex API integration
+  - LLM-based evidence quality assessment (Judge)
+  - Research report synthesis with citations
+
+- **Multi-Agent Architecture**
+  - Microsoft Agent Framework integration (Magentic)
+  - SearchAgent, JudgeAgent, ReportAgent coordination
+  - Pydantic AI structured outputs
+  - LangGraph workflow state management (experimental)
+
+- **Dual-Backend LLM Support**
+  - Free tier: HuggingFace Inference API (Qwen 2.5 7B)
+  - Paid tier: OpenAI GPT-5 (auto-detected with API key)
+  - Factory pattern for backend selection
+
+- **Evidence Processing**
+  - Cross-source deduplication by PMID/DOI
+  - ChromaDB + Sentence-Transformers for embeddings
+  - LlamaIndex RAG support (premium tier)
+  - Citation validation and formatting
+
+- **User Interface**
+  - Gradio streaming UI
+  - MCP (Model Context Protocol) server integration
+  - Claude Desktop tool support
+
+- **Developer Experience**
+  - Makefile with common commands
+  - Pre-commit hooks (ruff, mypy)
+  - Comprehensive test suite (unit, integration, e2e)
+  - GitHub Actions CI/CD pipeline
+  - Docker support with model pre-loading
+
+- **Documentation**
+  - README with quick start guide
+  - CLAUDE.md/AGENTS.md for AI agent guidance
+  - Architecture documentation with Mermaid diagrams
+  - Example scripts for all major features
+
+### Technical Notes
+
+This release represents the completion of Phases 1-14 of the original development plan:
+
+1. Foundation (project structure, TDD setup)
+2. PubMed search implementation
+3. ClinicalTrials.gov integration
+4. Basic orchestrator loop
+5. Evidence quality judgment
+6. Report synthesis
+7. Europe PMC integration
+8. Evidence deduplication
+9. Advanced search refinement
+10. Hypothesis generation
+11. Mechanistic pathway analysis
+12. LangGraph workflow
+13. Microsoft Agent Framework integration
+14. Demo submission
+
+### Known Issues
+
+See `docs/technical-debt/` for documented technical debt and known issues.
+
+---
+
+## Release Notes Format
+
+For each release, document:
+
+### Added
+New features and capabilities
+
+### Changed
+Changes to existing functionality
+
+### Deprecated
+Features that will be removed in future versions
+
+### Removed
+Features that were removed
+
+### Fixed
+Bug fixes
+
+### Security
+Security-related changes
+
+---
+
+[Unreleased]: https://github.com/The-Obstacle-Is-The-Way/DeepBoner/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/The-Obstacle-Is-The-Way/DeepBoner/releases/tag/v0.1.0

CODE_OF_CONDUCT.md

@@ -0,0 +1,111 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Project-Specific Guidelines
+
+Given DeepBoner's focus on sexual health research:
+
+### Respectful Discussion
+- Sexual health is a legitimate medical topic deserving serious discussion
+- Approach all topics with professionalism and scientific rigor
+- Avoid jokes or comments that trivialize sexual health issues
+- Remember that users may be dealing with personal health concerns
+
+### Inclusive Language
+- Use inclusive, gender-neutral language when possible
+- Recognize that sexual health affects all genders
+- Avoid assumptions about users' identities or experiences
+
+### Scientific Integrity
+- Base discussions on peer-reviewed evidence when possible
+- Clearly distinguish between established science and speculation
+- Respect the complexity of medical topics
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, including:
+- GitHub repository (issues, PRs, discussions)
+- Discord/Slack channels (if applicable)
+- Project-related social media
+- Events and meetups
+
+It also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement via:
+
+1. GitHub's reporting features
+2. Direct message to maintainers
+3. Email to repository owners
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional.
+
+**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved for a specified period. This includes avoiding interactions in community spaces as well as external channels. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved is allowed. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+---
+
+*"We take evidence-based community standards very seriously."* 🤝

CONTRIBUTING.md

@@ -0,0 +1,229 @@
+# Contributing to DeepBoner
+
+Thank you for your interest in contributing to DeepBoner! This document provides guidelines and instructions for contributing to the project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+- [Code Style](#code-style)
+- [Documentation](#documentation)
+
+## Code of Conduct
+
+Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) to keep our community welcoming and respectful.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.11 or higher
+- [uv](https://github.com/astral-sh/uv) package manager
+- Git
+
+### Development Setup
+
+1. **Fork the repository** on GitHub
+
+2. **Clone your fork**:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/DeepBoner.git
+   cd DeepBoner
+   ```
+
+3. **Install dependencies**:
+   ```bash
+   make install
+   # or manually:
+   uv sync --all-extras && uv run pre-commit install
+   ```
+
+4. **Copy the environment template**:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your API keys if needed
+   ```
+
+5. **Verify your setup**:
+   ```bash
+   make check
+   ```
+
+## Making Changes
+
+### Branch Naming Convention
+
+- `feature/short-description` - New features
+- `fix/short-description` - Bug fixes
+- `docs/short-description` - Documentation changes
+- `refactor/short-description` - Code refactoring
+- `test/short-description` - Test additions/improvements
+
+### Commit Message Format
+
+We follow conventional commit messages:
+
+```
+type(scope): short description
+
+Optional longer description explaining the change.
+
+Closes #123
+```
+
+Types:
+- `feat` - New feature
+- `fix` - Bug fix
+- `docs` - Documentation only
+- `style` - Code style (formatting, no logic change)
+- `refactor` - Code refactoring
+- `test` - Adding/updating tests
+- `chore` - Build process, tooling, dependencies
+
+Examples:
+```
+feat(tools): add OpenAlex API integration
+fix(pubmed): handle empty search results gracefully
+docs(readme): update quick start instructions
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run with coverage
+make test-cov
+
+# Run specific test file
+uv run pytest tests/unit/utils/test_config.py -v
+
+# Run specific test
+uv run pytest tests/unit/utils/test_config.py::TestSettings::test_default_max_iterations -v
+```
+
+### Test Markers
+
+- `@pytest.mark.unit` - Unit tests (mocked, fast)
+- `@pytest.mark.integration` - Integration tests (real APIs)
+- `@pytest.mark.slow` - Slow tests
+- `@pytest.mark.e2e` - End-to-end tests
+
+### Writing Tests
+
+- **TDD preferred**: Write tests first, then implementation
+- **Location**: Place unit tests in `tests/unit/` mirroring `src/` structure
+- **Mocking**: Use `respx` for httpx, `pytest-mock` for general mocking
+- **Fixtures**: Add reusable fixtures to `tests/conftest.py`
+
+Example test structure:
+```python
+"""Tests for search handler module."""
+import pytest
+from src.tools.search_handler import SearchHandler
+
+class TestSearchHandler:
+    """Tests for SearchHandler class."""
+
+    @pytest.mark.unit
+    def test_parallel_search_returns_results(self, mock_httpx_client):
+        """Verify parallel search aggregates results correctly."""
+        handler = SearchHandler()
+        result = handler.search("test query")
+        assert len(result.evidence) > 0
+```
+
+## Code Style
+
+### Pre-commit Hooks
+
+Pre-commit hooks run automatically on commit:
+- **Ruff** - Linting and formatting
+- **MyPy** - Type checking
+
+To run manually:
+```bash
+make lint      # Check linting
+make format    # Auto-format code
+make typecheck # Type checking
+```
+
+### Style Guidelines
+
+1. **Type hints required** - All functions must have type annotations
+2. **Docstrings** - Use Google-style docstrings for public APIs
+3. **Line length** - Maximum 100 characters
+4. **Imports** - Sorted by isort (handled by ruff)
+
+### Code Quality Rules
+
+We use Ruff with these rule sets:
+- `E` - pycodestyle errors
+- `F` - pyflakes
+- `B` - flake8-bugbear
+- `I` - isort
+- `N` - pep8-naming
+- `UP` - pyupgrade
+- `PL` - pylint
+- `RUF` - ruff-specific
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Ensure tests pass**: `make check`
+2. **Update documentation** if adding features
+3. **Create PR** against `main` branch
+4. **Fill out the PR template** with:
+   - Summary of changes
+   - Related issues
+   - Test plan
+5. **Wait for review** - Address any feedback
+
+### PR Checklist
+
+- [ ] Tests added/updated and passing
+- [ ] `make check` passes locally
+- [ ] Documentation updated (if applicable)
+- [ ] Commit messages follow convention
+- [ ] No secrets or API keys committed
+- [ ] Changes are focused (one concern per PR)
+
+## Documentation
+
+### Where to Document
+
+- **README.md** - User-facing overview and quick start
+- **CLAUDE.md** - Developer/AI agent reference
+- **docs/** - Detailed documentation
+  - `architecture/` - System design
+  - `development/` - Developer guides
+  - `deployment/` - Deployment instructions
+  - `reference/` - API/config reference
+
+### Documentation Standards
+
+- Use clear, concise language
+- Include code examples where helpful
+- Keep diagrams updated (Mermaid format)
+- Link to related documentation
+
+## Getting Help
+
+- **Issues**: Open a GitHub issue for bugs or feature requests
+- **Discussions**: Use GitHub Discussions for questions
+
+## Recognition
+
+Contributors will be recognized in release notes. Thank you for helping make DeepBoner better!
+
+---
+
+*"Peer-reviewed contributions only. We take evidence-based code very seriously."* 🔬

SECURITY.md

@@ -0,0 +1,125 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+We take security seriously. If you discover a security vulnerability in DeepBoner, please report it responsibly.
+
+### How to Report
+
+1. **DO NOT** open a public GitHub issue for security vulnerabilities
+2. Email security concerns to the repository maintainers via GitHub's private vulnerability reporting
+3. Or use GitHub's Security Advisory feature: **Security** tab > **Report a vulnerability**
+
+### What to Include
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+### Response Timeline
+
+- **Acknowledgment**: Within 48 hours
+- **Initial assessment**: Within 7 days
+- **Fix timeline**: Depends on severity
+  - Critical: Within 48 hours
+  - High: Within 7 days
+  - Medium: Within 30 days
+  - Low: Next release cycle
+
+## Security Measures
+
+### API Key Handling
+
+- API keys are loaded from environment variables only
+- Keys are never logged or exposed in error messages
+- `.env` files are gitignored
+- No hardcoded credentials in source code
+
+### Dependency Security
+
+- Regular dependency audits via `pip-audit`
+- Security scanning with `bandit` in CI
+- Pinned dependencies for reproducibility
+- Known CVE fixes:
+  - `mcp>=1.23.0` - Fixes GHSA-9h52-p55h-vw2f
+  - `langgraph-checkpoint-sqlite>=3.0.0` - Fixes GHSA-wwqv-p2pp-99h5
+  - `urllib3>=2.6.0` - Fixes GHSA-gm62-xv2j-4w53 and GHSA-2xpw-w6gg-jr37
+
+### External API Security
+
+- HTTPS enforced for all external API calls
+- Rate limiting prevents abuse
+- No sensitive data sent to external services (only search queries)
+
+### Input Validation
+
+- Pydantic models for strict input validation
+- Query sanitization before external API calls
+- Length limits on user inputs
+
+## Security Best Practices for Users
+
+### API Keys
+
+1. Never commit `.env` files
+2. Use environment variables in production
+3. Rotate keys periodically
+4. Use minimal permissions (read-only where possible)
+
+### Deployment
+
+1. Use the provided Docker image for consistency
+2. Keep dependencies updated
+3. Monitor for security advisories
+4. Use HTTPS in production
+
+### HuggingFace Spaces
+
+1. Use Secrets (not public variables) for API keys
+2. The HF_TOKEN is used server-side only
+3. Users don't need their own tokens
+
+## Known Security Considerations
+
+### Third-Party APIs
+
+DeepBoner queries external biomedical databases:
+- PubMed (NCBI)
+- ClinicalTrials.gov
+- Europe PMC
+- OpenAlex
+
+These are trusted public APIs, but:
+- Query content is visible to these services
+- Rate limits apply
+- Availability depends on upstream services
+
+### LLM Providers
+
+- OpenAI and HuggingFace process your queries
+- Review their privacy policies if handling sensitive research
+- Consider on-premise alternatives for sensitive use cases
+
+### Local Data
+
+- ChromaDB stores embeddings locally
+- Default path: `./chroma_db/`
+- Contains processed search results (not raw user data)
+- Secure or delete when decommissioning
+
+## Security Updates
+
+Security updates will be released as patch versions (e.g., 0.1.1) and announced via:
+- GitHub Security Advisories
+- Release notes
+
+---
+
+*"Security is rock solid. We take evidence-based security very seriously."* 🔐

docs/README.md

@@ -0,0 +1,129 @@
+# DeepBoner Documentation
+
+Welcome to the DeepBoner documentation. This directory contains comprehensive documentation for developers, contributors, and operators.
+
+## Quick Navigation
+
+| Need to... | Go to... |
+|------------|----------|
+| Get started quickly | [Getting Started](getting-started/installation.md) |
+| Understand the architecture | [Architecture Overview](architecture/overview.md) |
+| Set up for development | [Development Guide](development/testing.md) |
+| Deploy the application | [Deployment Guide](deployment/docker.md) |
+| Look up configuration | [Reference](reference/configuration.md) |
+| Track technical debt | [Technical Debt](technical-debt/index.md) |
+
+## Documentation Structure
+
+```
+docs/
+├── README.md                     # This file - documentation index
+│
+├── getting-started/              # Onboarding documentation
+│   ├── installation.md           # Installation guide
+│   ├── quickstart.md             # 5-minute quickstart
+│   ├── configuration.md          # Configuration guide
+│   └── troubleshooting.md        # Common issues and solutions
+│
+├── architecture/                 # System design documentation
+│   ├── overview.md               # High-level architecture
+│   ├── system-registry.md        # Service registry (canonical wiring)
+│   ├── workflow-diagrams.md      # Visual workflow diagrams
+│   ├── component-inventory.md    # Complete component catalog
+│   ├── data-models.md            # Pydantic model documentation
+│   └── exception-hierarchy.md    # Exception types and handling
+│
+├── development/                  # Developer guides
+│   ├── testing.md                # Testing strategy and patterns
+│   ├── code-style.md             # Code style and conventions
+│   └── release-process.md        # Release workflow
+│
+├── deployment/                   # Deployment documentation
+│   ├── docker.md                 # Docker deployment
+│   ├── huggingface-spaces.md     # HuggingFace Spaces deployment
+│   └── mcp-integration.md        # MCP server setup
+│
+├── technical-debt/               # Known issues and improvements
+│   ├── index.md                  # Technical debt overview
+│   └── debt-registry.md          # Itemized debt tracking
+│
+├── reference/                    # API and configuration reference
+│   ├── configuration.md          # All configuration options
+│   └── environment-variables.md  # Environment variable reference
+│
+├── bugs/                         # Bug tracking (existing)
+│   ├── active-bugs.md
+│   └── p3-progress-bar-positioning.md
+│
+├── decisions/                    # Architecture Decision Records (existing)
+│   └── 2025-11-27-pr55-evaluation.md
+│
+└── future-roadmap/               # Future feature specs (existing)
+    └── 16-pubmed-fulltext.md
+```
+
+## Documentation Standards
+
+### File Naming
+- Use **kebab-case** for all filenames (e.g., `getting-started.md`)
+- Keep names descriptive but concise
+
+### Content Guidelines
+- Start each document with a clear title and purpose
+- Include a table of contents for longer documents
+- Use Mermaid diagrams for visual documentation
+- Link to related documentation
+- Keep content current - update when code changes
+
+### Markdown Conventions
+- Use ATX-style headers (`#`, `##`, etc.)
+- Code blocks with language specification
+- Tables for structured data
+- Admonitions for warnings/notes (where supported)
+
+## Key Documents
+
+### For New Developers
+1. [Installation](getting-started/installation.md) - Set up your environment
+2. [Quickstart](getting-started/quickstart.md) - Run your first query
+3. [Architecture Overview](architecture/overview.md) - Understand the system
+4. [Testing](development/testing.md) - Run and write tests
+
+### For Contributors
+1. [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
+2. [Code Style](development/code-style.md) - Style conventions
+3. [Testing](development/testing.md) - Testing requirements
+
+### For Operators
+1. [Docker Deployment](deployment/docker.md) - Container deployment
+2. [HuggingFace Spaces](deployment/huggingface-spaces.md) - Cloud deployment
+3. [Configuration Reference](reference/configuration.md) - All options
+
+### For Understanding the Codebase
+1. [Component Inventory](architecture/component-inventory.md) - All modules
+2. [Data Models](architecture/data-models.md) - Core types
+3. [System Registry](architecture/system-registry.md) - Service wiring
+4. [Technical Debt](technical-debt/index.md) - Known issues
+
+## Related Documentation
+
+- **[README.md](../README.md)** - Project overview and quick start
+- **[CLAUDE.md](../CLAUDE.md)** - AI agent developer reference
+- **[CHANGELOG.md](../CHANGELOG.md)** - Release history
+- **[SECURITY.md](../SECURITY.md)** - Security policy
+- **[CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)** - Community guidelines
+
+## Contributing to Documentation
+
+Documentation is code. Please:
+
+1. Keep docs updated when changing related code
+2. Follow the naming and style conventions
+3. Test links before committing
+4. Add new documents to this index
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for full guidelines.
+
+---
+
+*"Well-documented boners only. We take evidence-based documentation very seriously."* 📚

docs/architecture/component-inventory.md

@@ -0,0 +1,458 @@
+# Component Inventory
+
+> **Last Updated**: 2025-12-06
+
+This document provides a complete catalog of all components in the DeepBoner codebase.
+
+## Source Code Statistics
+
+| Category | Count |
+|----------|-------|
+| Python files in `src/` | ~67 |
+| Python files in `tests/` | ~76 |
+| Total modules | ~143 |
+
+## Directory Structure
+
+```
+src/
+├── app.py                      # Gradio UI entry point
+├── mcp_tools.py                # MCP server tool wrappers
+├── orchestrators/              # Research orchestration
+├── clients/                    # LLM backend adapters
+├── agents/                     # Multi-agent components
+├── agent_factory/              # Agent creation
+├── tools/                      # Search tool implementations
+├── services/                   # Cross-cutting services
+├── prompts/                    # LLM prompt templates
+├── utils/                      # Shared utilities
+├── config/                     # Domain configuration
+├── middleware/                 # Processing middleware
+└── state/                      # State management
+```
+
+---
+
+## Core Entry Points
+
+### `src/app.py`
+**Purpose:** Main application entry point
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `create_demo()` | Function | Creates Gradio interface |
+| `main()` | Function | Application entry point |
+
+**Dependencies:** Gradio, orchestrators, config
+
+### `src/mcp_tools.py`
+**Purpose:** MCP (Model Context Protocol) tool wrappers
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `search_pubmed()` | Tool | PubMed search wrapper |
+| `search_clinical_trials()` | Tool | ClinicalTrials.gov wrapper |
+| `search_europepmc()` | Tool | Europe PMC wrapper |
+| `search_all_sources()` | Tool | Multi-source search |
+
+---
+
+## Orchestrators (`src/orchestrators/`)
+
+### `advanced.py`
+**Purpose:** Main multi-agent orchestrator using Microsoft Agent Framework
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `AdvancedOrchestrator` | Class | Primary research orchestrator |
+| `run()` | Method | Execute research workflow |
+| `_search_phase()` | Method | Search execution |
+| `_judge_phase()` | Method | Evidence evaluation |
+| `_synthesize_phase()` | Method | Report generation |
+
+**Framework:** Microsoft Agent Framework (agent-framework-core)
+
+### `factory.py`
+**Purpose:** Orchestrator selection
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `OrchestratorFactory` | Class | Creates appropriate orchestrator |
+| `create()` | Method | Factory method |
+
+### `base.py`
+**Purpose:** Base orchestrator interface
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `BaseOrchestrator` | ABC | Abstract base class |
+
+### `langgraph_orchestrator.py`
+**Purpose:** LangGraph-based workflow (experimental)
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `LangGraphOrchestrator` | Class | Workflow state machine |
+
+### `hierarchical.py`
+**Purpose:** Hierarchical agent coordination
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `HierarchicalOrchestrator` | Class | Manager-agent hierarchy |
+
+---
+
+## LLM Clients (`src/clients/`)
+
+### `factory.py`
+**Purpose:** Auto-select LLM backend
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `get_chat_client()` | Function | Returns appropriate client |
+
+**Selection Logic:**
+```python
+if settings.has_openai_key:
+    return OpenAIChatClient()
+else:
+    return HuggingFaceChatClient()
+```
+
+### `huggingface.py`
+**Purpose:** HuggingFace Inference API adapter
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `HuggingFaceChatClient` | Class | Free tier LLM client |
+| `chat_completion()` | Method | Generate completion |
+
+**Model:** Qwen 2.5 7B Instruct (free tier)
+
+### `base.py`
+**Purpose:** Client interface
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `BaseChatClient` | ABC | Client interface |
+
+### `providers.py`
+**Purpose:** Provider implementations
+
+### `registry.py`
+**Purpose:** Provider registration
+
+---
+
+## Agents (`src/agents/`)
+
+### `search_agent.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `SearchAgent` | Class | Evidence gathering agent |
+
+### `judge_agent.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `JudgeAgent` | Class | Evidence evaluation |
+
+### `judge_agent_llm.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `LLMJudgeAgent` | Class | LLM-based judge implementation |
+
+### `report_agent.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `ReportAgent` | Class | Report synthesis |
+
+### `retrieval_agent.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `RetrievalAgent` | Class | Evidence retrieval coordination |
+
+### `hypothesis_agent.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `HypothesisAgent` | Class | Mechanistic hypothesis generation |
+
+### `magentic_agents.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Multi-agent mode | Module | Microsoft Agent Framework integration |
+
+### `state.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Agent state models | Module | Shared state definitions |
+
+### `tools.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Tool bindings | Module | Agent tool configuration |
+
+---
+
+## Graph Workflow (`src/agents/graph/`)
+
+### `workflow.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `create_workflow()` | Function | LangGraph workflow builder |
+
+### `nodes.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `search_node()` | Function | Search workflow node |
+| `judge_node()` | Function | Judge workflow node |
+| `report_node()` | Function | Report workflow node |
+
+### `state.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `WorkflowState` | Class | LangGraph state schema |
+
+---
+
+## Agent Factory (`src/agent_factory/`)
+
+### `judges.py`
+**Purpose:** Evidence quality judgment
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `create_judge()` | Function | Judge agent factory |
+| `JudgeResult` | Model | Assessment output |
+
+**Framework:** Pydantic AI
+
+### `agents.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Agent creation | Module | Factory functions |
+
+---
+
+## Search Tools (`src/tools/`)
+
+### `pubmed.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `PubMedTool` | Class | NCBI E-utilities client |
+| `search()` | Method | Execute search |
+
+**API:** PubMed E-utilities (eutils.ncbi.nlm.nih.gov)
+
+### `clinicaltrials.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `ClinicalTrialsTool` | Class | ClinicalTrials.gov client |
+| `search()` | Method | Execute search |
+
+**API:** ClinicalTrials.gov API (uses `requests` due to WAF blocking httpx)
+
+### `europepmc.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `EuropePMCTool` | Class | Europe PMC client |
+| `search()` | Method | Execute search |
+
+**API:** Europe PMC API
+
+### `openalex.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `OpenAlexTool` | Class | OpenAlex client |
+| `search()` | Method | Execute search |
+
+**API:** OpenAlex API
+
+### `search_handler.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `SearchHandler` | Class | Scatter-gather orchestration |
+| `search_all()` | Method | Parallel multi-source search |
+
+### `query_utils.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Query utilities | Module | Query refinement and expansion |
+
+### `rate_limiter.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `RateLimiter` | Class | API rate limiting |
+
+### `base.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `BaseSearchTool` | ABC | Search tool interface |
+
+### `web_search.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Web search | Module | DuckDuckGo integration |
+
+---
+
+## Services (`src/services/`)
+
+### `embeddings.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `EmbeddingService` | Class | Local embedding service |
+| `embed()` | Method | Generate embeddings |
+| `deduplicate()` | Method | Cross-source deduplication |
+
+**Stack:** sentence-transformers + ChromaDB
+
+### `llamaindex_rag.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `LlamaIndexRAG` | Class | Premium RAG service |
+
+**Stack:** LlamaIndex + OpenAI embeddings + ChromaDB
+
+### `embedding_protocol.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `EmbeddingProtocol` | Protocol | Interface for embedding services |
+
+### `research_memory.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `ResearchMemory` | Class | Shared research state |
+
+---
+
+## Utilities (`src/utils/`)
+
+### `config.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `Settings` | Class | Pydantic Settings configuration |
+| `settings` | Instance | Global settings singleton |
+| `get_settings()` | Function | Settings factory |
+| `configure_logging()` | Function | Logging setup |
+
+### `models.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `Evidence` | Model | Evidence with citation |
+| `Citation` | Model | Source citation |
+| `SearchResult` | Model | Search response |
+| `JudgeAssessment` | Model | Judge evaluation |
+| `ResearchReport` | Model | Final report |
+| `AgentEvent` | Model | UI streaming events |
+
+See [Data Models](data-models.md) for complete documentation.
+
+### `exceptions.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `DeepBonerError` | Exception | Base exception |
+| `SearchError` | Exception | Search failures |
+| `JudgeError` | Exception | Judge failures |
+| `ConfigurationError` | Exception | Config errors |
+| `RateLimitError` | Exception | Rate limits |
+
+See [Exception Hierarchy](exception-hierarchy.md) for details.
+
+### `service_loader.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Service loading | Module | Tiered service selection |
+
+### `citation_validator.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Citation validation | Module | URL verification |
+
+### `text_utils.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Text utilities | Module | Text processing |
+
+### `parsers.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Response parsing | Module | LLM output parsing |
+
+### `dataloaders.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Data loading | Module | Data loading utilities |
+
+---
+
+## Configuration (`src/config/`)
+
+### `domain.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| `ResearchDomain` | Enum | Research domain types |
+
+---
+
+## Prompts (`src/prompts/`)
+
+| File | Purpose |
+|------|---------|
+| `search.py` | Query refinement prompts |
+| `judge.py` | Evidence assessment prompts |
+| `hypothesis.py` | Hypothesis generation prompts |
+| `synthesis.py` | Evidence synthesis prompts |
+| `report.py` | Report generation prompts |
+
+---
+
+## Middleware (`src/middleware/`)
+
+### `sub_iteration.py`
+| Component | Type | Description |
+|-----------|------|-------------|
+| Sub-iteration | Module | Nested iteration logic |
+
+---
+
+## Reserved Directories
+
+These directories exist but are placeholders for future features:
+
+| Directory | Purpose |
+|-----------|---------|
+| `src/database_services/` | Future database services |
+| `src/retrieval_factory/` | Future retrieval configuration |
+
+---
+
+## Test Structure
+
+```
+tests/
+├── conftest.py                 # Shared fixtures
+├── unit/                       # Unit tests (mocked)
+│   ├── orchestrators/
+│   ├── agents/
+│   ├── clients/
+│   ├── tools/
+│   ├── services/
+│   ├── utils/
+│   ├── prompts/
+│   ├── agent_factory/
+│   ├── config/
+│   ├── graph/
+│   └── mcp/
+├── integration/                # Integration tests (real APIs)
+└── e2e/                        # End-to-end tests
+```
+
+---
+
+## Related Documentation
+
+- [Architecture Overview](overview.md)
+- [Data Models](data-models.md)
+- [Exception Hierarchy](exception-hierarchy.md)
+- [System Registry](system-registry.md)

docs/architecture/data-models.md

@@ -0,0 +1,342 @@
+# Data Models Reference
+
+> **Last Updated**: 2025-12-06
+
+This document describes all Pydantic models used in DeepBoner.
+
+## Location
+
+All core models are defined in `src/utils/models.py`.
+
+## Type Definitions
+
+### SourceName
+
+```python
+SourceName = Literal["pubmed", "clinicaltrials", "europepmc", "preprint", "openalex", "web"]
+```
+
+Centralized source type. Add new sources here when integrating new databases.
+
+---
+
+## Core Models
+
+### Citation
+
+Represents a citation to a source document.
+
+```python
+class Citation(BaseModel):
+    source: SourceName          # Where this came from
+    title: str                  # Title (1-500 chars)
+    url: str                    # URL to source
+    date: str                   # Publication date (YYYY-MM-DD or 'Unknown')
+    authors: list[str]          # Author list
+
+    MAX_AUTHORS_IN_CITATION: ClassVar[int] = 3
+
+    @property
+    def formatted(self) -> str:
+        """Format as citation string."""
+```
+
+**Example:**
+```python
+citation = Citation(
+    source="pubmed",
+    title="Effects of testosterone on female libido",
+    url="https://pubmed.ncbi.nlm.nih.gov/12345678",
+    date="2024-01-15",
+    authors=["Smith J", "Jones A", "Brown B"]
+)
+print(citation.formatted)
+# "Smith J, Jones A, Brown B (2024-01-15). Effects of testosterone..."
+```
+
+---
+
+### Evidence
+
+A piece of evidence retrieved from search.
+
+```python
+class Evidence(BaseModel):
+    content: str                # The actual text content (min 1 char)
+    citation: Citation          # Source citation
+    relevance: float            # Relevance score 0-1
+    metadata: dict[str, Any]    # Additional metadata
+
+    model_config = {"frozen": True}  # Immutable
+```
+
+**Metadata fields** (source-dependent):
+- `cited_by_count` - Citation count
+- `concepts` - Subject concepts
+- `is_open_access` - OA status
+- `pmid` - PubMed ID
+- `doi` - Digital Object Identifier
+
+**Example:**
+```python
+evidence = Evidence(
+    content="The study found significant improvement...",
+    citation=citation,
+    relevance=0.85,
+    metadata={"pmid": "12345678", "cited_by_count": 42}
+)
+```
+
+---
+
+### SearchResult
+
+Result of a search operation.
+
+```python
+class SearchResult(BaseModel):
+    query: str                      # Original query
+    evidence: list[Evidence]        # Retrieved evidence
+    sources_searched: list[SourceName]  # Which sources were queried
+    total_found: int                # Total matches
+    errors: list[str]               # Any errors encountered
+```
+
+---
+
+## Assessment Models
+
+### AssessmentDetails
+
+Detailed assessment of evidence quality by the Judge.
+
+```python
+class AssessmentDetails(BaseModel):
+    mechanism_score: int            # 0-10: How well explained
+    mechanism_reasoning: str        # Explanation (min 10 chars)
+    clinical_evidence_score: int    # 0-10: Clinical strength
+    clinical_reasoning: str         # Explanation (min 10 chars)
+    drug_candidates: list[str]      # Specific drugs mentioned
+    key_findings: list[str]         # Key findings
+```
+
+---
+
+### JudgeAssessment
+
+Complete assessment from the Judge.
+
+```python
+class JudgeAssessment(BaseModel):
+    details: AssessmentDetails
+    sufficient: bool                # Is evidence sufficient?
+    confidence: float               # 0-1 confidence
+    recommendation: Literal["continue", "synthesize"]
+    next_search_queries: list[str]  # If continue, what to search
+    reasoning: str                  # Overall reasoning (min 20 chars)
+```
+
+**Decision Logic:**
+- `recommendation="continue"` → More evidence needed, loop back
+- `recommendation="synthesize"` → Ready to generate report
+
+---
+
+## Event Models
+
+### AgentEvent
+
+Event emitted by orchestrator for UI streaming.
+
+```python
+class AgentEvent(BaseModel):
+    type: Literal[
+        "started",
+        "thinking",
+        "searching",
+        "search_complete",
+        "judging",
+        "judge_complete",
+        "looping",
+        "synthesizing",
+        "complete",
+        "error",
+        "streaming",
+        "hypothesizing",
+        "analyzing",
+        "analysis_complete",
+        "progress",
+    ]
+    message: str
+    data: Any = None
+    timestamp: datetime
+    iteration: int = 0
+
+    def to_markdown(self) -> str:
+        """Format event as markdown with emoji."""
+```
+
+**Event Types:**
+| Type | Icon | Meaning |
+|------|------|---------|
+| `started` | 🚀 | Research started |
+| `thinking` | ⏳ | Processing |
+| `searching` | 🔍 | Searching databases |
+| `search_complete` | 📚 | Search finished |
+| `judging` | 🧠 | Evaluating evidence |
+| `judge_complete` | ✅ | Judgment done |
+| `looping` | 🔄 | Refining query |
+| `synthesizing` | 📝 | Generating report |
+| `complete` | 🎉 | Research complete |
+| `error` | ❌ | Error occurred |
+| `progress` | ⏱️ | Progress update |
+
+---
+
+## Hypothesis Models
+
+### MechanismHypothesis
+
+A scientific hypothesis about drug mechanism.
+
+```python
+class MechanismHypothesis(BaseModel):
+    drug: str                       # Drug being studied
+    target: str                     # Molecular target
+    pathway: str                    # Biological pathway
+    effect: str                     # Downstream effect
+    confidence: float               # 0-1 confidence
+    supporting_evidence: list[str]  # Supporting PMIDs/URLs
+    contradicting_evidence: list[str]
+    search_suggestions: list[str]
+
+    def to_search_queries(self) -> list[str]:
+        """Generate queries to test hypothesis."""
+```
+
+---
+
+### HypothesisAssessment
+
+Assessment of evidence against hypotheses.
+
+```python
+class HypothesisAssessment(BaseModel):
+    hypotheses: list[MechanismHypothesis]
+    primary_hypothesis: MechanismHypothesis | None
+    knowledge_gaps: list[str]
+    recommended_searches: list[str]
+```
+
+---
+
+## Report Models
+
+### ReportSection
+
+A section of the research report.
+
+```python
+class ReportSection(BaseModel):
+    title: str
+    content: str
+    citations: list[str] = []   # Reserved for inline citations
+```
+
+---
+
+### ResearchReport
+
+Structured scientific report (final output).
+
+```python
+class ResearchReport(BaseModel):
+    title: str
+    executive_summary: str          # 100-1000 chars
+    research_question: str
+
+    methodology: ReportSection
+    hypotheses_tested: list[dict[str, Any]]
+
+    mechanistic_findings: ReportSection
+    clinical_findings: ReportSection
+
+    drug_candidates: list[str]
+    limitations: list[str]
+    conclusion: str
+
+    references: list[dict[str, str]]
+
+    # Metadata
+    sources_searched: list[str]
+    total_papers_reviewed: int
+    search_iterations: int
+    confidence_score: float         # 0-1
+
+    def to_markdown(self) -> str:
+        """Render report as markdown."""
+```
+
+**Reference Format:**
+```python
+{
+    "title": "Paper title",
+    "authors": "Smith J et al.",
+    "source": "pubmed",
+    "date": "2024-01-15",
+    "url": "https://..."
+}
+```
+
+---
+
+## Configuration Models
+
+### OrchestratorConfig
+
+Configuration for the orchestrator.
+
+```python
+class OrchestratorConfig(BaseModel):
+    max_iterations: int = 10        # 1-20
+    max_results_per_tool: int = 10  # 1-50
+    search_timeout: float = 30.0    # 5-120 seconds
+```
+
+---
+
+## Model Relationships
+
+```
+SearchResult
+    └── Evidence[]
+           └── Citation
+
+JudgeAssessment
+    └── AssessmentDetails
+
+ResearchReport
+    ├── ReportSection (methodology)
+    ├── ReportSection (mechanistic_findings)
+    ├── ReportSection (clinical_findings)
+    └── HypothesisAssessment
+           └── MechanismHypothesis[]
+```
+
+---
+
+## Validation Notes
+
+All models use Pydantic v2 with:
+
+- **Field constraints** - `ge=0`, `le=1` for scores, `min_length` for strings
+- **Frozen models** - Evidence is immutable (`frozen=True`)
+- **Default factories** - Lists default to `[]` via `default_factory=list`
+
+---
+
+## Related Documentation
+
+- [Component Inventory](component-inventory.md)
+- [Exception Hierarchy](exception-hierarchy.md)
+- [Architecture Overview](overview.md)

docs/architecture/exception-hierarchy.md

@@ -0,0 +1,350 @@
+# Exception Hierarchy
+
+> **Last Updated**: 2025-12-06
+
+This document describes all custom exceptions in DeepBoner.
+
+## Location
+
+All exceptions are defined in `src/utils/exceptions.py`.
+
+## Exception Tree
+
+```
+Exception (Python builtin)
+    └── DeepBonerError (base)
+            ├── SearchError
+            │       └── RateLimitError
+            ├── JudgeError
+            ├── ConfigurationError
+            ├── EmbeddingError
+            ├── LLMError
+            │       └── QuotaExceededError
+            └── SynthesisError
+```
+
+---
+
+## Base Exception
+
+### DeepBonerError
+
+```python
+class DeepBonerError(Exception):
+    """Base exception for all DeepBoner errors."""
+    pass
+```
+
+**When to use:** Never directly. Use specific subclasses.
+
+**Catch when:** You want to catch all DeepBoner-related errors.
+
+```python
+try:
+    result = orchestrator.run(query)
+except DeepBonerError as e:
+    logger.error(f"Research failed: {e}")
+```
+
+---
+
+## Search Exceptions
+
+### SearchError
+
+```python
+class SearchError(DeepBonerError):
+    """Raised when a search operation fails."""
+    pass
+```
+
+**When raised:**
+- External API returns error status
+- Network timeout
+- Invalid response format
+- No results found (in strict mode)
+
+**Example:**
+```python
+from src.utils.exceptions import SearchError
+
+if response.status_code != 200:
+    raise SearchError(f"PubMed returned {response.status_code}")
+```
+
+---
+
+### RateLimitError
+
+```python
+class RateLimitError(SearchError):
+    """Raised when we hit API rate limits."""
+    pass
+```
+
+**When raised:**
+- HTTP 429 (Too Many Requests)
+- PubMed rate limit exceeded
+- ClinicalTrials.gov throttling
+
+**Handling:**
+```python
+from src.utils.exceptions import RateLimitError
+
+try:
+    results = pubmed.search(query)
+except RateLimitError:
+    await asyncio.sleep(60)  # Wait and retry
+    results = pubmed.search(query)
+```
+
+**Prevention:**
+- Add `NCBI_API_KEY` for higher PubMed limits
+- Use built-in rate limiter (`src/tools/rate_limiter.py`)
+
+---
+
+## Judge Exceptions
+
+### JudgeError
+
+```python
+class JudgeError(DeepBonerError):
+    """Raised when the judge fails to assess evidence."""
+    pass
+```
+
+**When raised:**
+- LLM fails to produce valid assessment
+- Assessment parsing fails
+- Confidence below threshold
+- Invalid judge response format
+
+**Example:**
+```python
+from src.utils.exceptions import JudgeError
+
+if not assessment.details:
+    raise JudgeError("Judge produced incomplete assessment")
+```
+
+---
+
+## Configuration Exceptions
+
+### ConfigurationError
+
+```python
+class ConfigurationError(DeepBonerError):
+    """Raised when configuration is invalid."""
+    pass
+```
+
+**When raised:**
+- Required API key missing
+- Invalid setting value
+- Environment variable malformed
+- Conflicting configuration
+
+**Example:**
+```python
+from src.utils.exceptions import ConfigurationError
+
+def get_api_key(self) -> str:
+    if not self.openai_api_key:
+        raise ConfigurationError("OPENAI_API_KEY not set")
+    return self.openai_api_key
+```
+
+---
+
+## Embedding Exceptions
+
+### EmbeddingError
+
+```python
+class EmbeddingError(DeepBonerError):
+    """Raised when embedding or vector store operations fail."""
+    pass
+```
+
+**When raised:**
+- ChromaDB connection failure
+- Sentence-transformers model load failure
+- Vector dimension mismatch
+- Embedding generation fails
+
+**Example:**
+```python
+from src.utils.exceptions import EmbeddingError
+
+try:
+    embeddings = model.encode(texts)
+except Exception as e:
+    raise EmbeddingError(f"Embedding failed: {e}")
+```
+
+---
+
+## LLM Exceptions
+
+### LLMError
+
+```python
+class LLMError(DeepBonerError):
+    """Raised when LLM operations fail (API errors, parsing errors, etc.)."""
+    pass
+```
+
+**When raised:**
+- LLM API error
+- Response parsing failure
+- Invalid model output
+- Context length exceeded
+
+---
+
+### QuotaExceededError
+
+```python
+class QuotaExceededError(LLMError):
+    """Raised when LLM API quota is exceeded (402 errors)."""
+    pass
+```
+
+**When raised:**
+- OpenAI billing limit hit
+- HuggingFace rate limit exceeded
+- HTTP 402 Payment Required
+
+**Handling:**
+```python
+from src.utils.exceptions import QuotaExceededError
+
+try:
+    response = client.chat_completion(messages)
+except QuotaExceededError:
+    # Fall back to free tier or notify user
+    return fallback_response()
+```
+
+---
+
+## Synthesis Exceptions
+
+### SynthesisError
+
+```python
+class SynthesisError(DeepBonerError):
+    """Raised when report synthesis fails after trying all available models.
+
+    Attributes:
+        message: Human-readable error description
+        attempted_models: List of model IDs that were tried
+        errors: List of error messages from each failed attempt
+    """
+
+    def __init__(
+        self,
+        message: str,
+        attempted_models: list[str] | None = None,
+        errors: list[str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.attempted_models = attempted_models or []
+        self.errors = errors or []
+```
+
+**When raised:**
+- All LLM models fail to synthesize report
+- Report generation exceeds retry limit
+
+**Example:**
+```python
+from src.utils.exceptions import SynthesisError
+
+if all_attempts_failed:
+    raise SynthesisError(
+        "Failed to synthesize report",
+        attempted_models=["gpt-5", "gpt-4o"],
+        errors=["Rate limit", "Context too long"]
+    )
+```
+
+**Accessing details:**
+```python
+try:
+    report = synthesize(evidence)
+except SynthesisError as e:
+    print(f"Failed: {e}")
+    print(f"Tried models: {e.attempted_models}")
+    print(f"Errors: {e.errors}")
+```
+
+---
+
+## Usage Patterns
+
+### Catching Specific Exceptions
+
+```python
+from src.utils.exceptions import (
+    SearchError,
+    RateLimitError,
+    JudgeError,
+)
+
+try:
+    result = orchestrator.run(query)
+except RateLimitError:
+    # Specific handling for rate limits
+    await rate_limiter.wait()
+    result = orchestrator.run(query)
+except SearchError:
+    # General search failure
+    return empty_result()
+except JudgeError:
+    # Judge failed, use default assessment
+    return default_assessment()
+```
+
+### Exception Chaining
+
+```python
+try:
+    response = api_call()
+except requests.RequestException as e:
+    raise SearchError(f"API call failed: {e}") from e
+```
+
+### Logging Exceptions
+
+```python
+import structlog
+
+logger = structlog.get_logger()
+
+try:
+    results = search(query)
+except DeepBonerError as e:
+    logger.error("operation_failed", error=str(e), exc_info=True)
+    raise
+```
+
+---
+
+## Best Practices
+
+1. **Use specific exceptions** - Don't raise `DeepBonerError` directly
+2. **Include context** - Error messages should explain what failed
+3. **Chain exceptions** - Use `from e` to preserve stack trace
+4. **Log before re-raising** - Capture context for debugging
+5. **Handle at boundaries** - Catch exceptions at API/UI boundaries
+
+---
+
+## Related Documentation
+
+- [Component Inventory](component-inventory.md)
+- [Data Models](data-models.md)
+- [Troubleshooting](../getting-started/troubleshooting.md)

docs/architecture/overview.md

@@ -0,0 +1,224 @@
+# 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 |
+|-------|------|------|
+| SearchAgent | `search_agent.py` | Evidence retrieval |
+| JudgeAgent | `judge_agent.py` | Evidence evaluation |
+| ReportAgent | `report_agent.py` | Report synthesis |
+| HypothesisAgent | `hypothesis_agent.py` | Mechanistic pathway analysis |
+
+### 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."* 🏛️

docs/deployment/docker.md

@@ -0,0 +1,290 @@
+# Docker Deployment
+
+> **Last Updated**: 2025-12-06
+
+This guide covers deploying DeepBoner using Docker.
+
+## Quick Start
+
+```bash
+# Build the image
+docker build -t deepboner .
+
+# Run the container
+docker run -p 7860:7860 deepboner
+```
+
+Open http://localhost:7860
+
+## Dockerfile Overview
+
+The project uses a multi-stage approach:
+
+```dockerfile
+FROM python:3.11-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y git curl
+
+# Install uv package manager
+RUN pip install uv==0.5.4
+
+# Copy project files
+COPY pyproject.toml uv.lock src/ README.md .
+
+# Install runtime dependencies (no dev tools)
+RUN uv sync --frozen --no-dev --extra embeddings --extra magentic
+
+# Create non-root user
+RUN useradd --create-home appuser
+USER appuser
+
+# Pre-download embedding model
+RUN uv run python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
+
+# Expose port and run
+EXPOSE 7860
+CMD ["uv", "run", "python", "-m", "src.app"]
+```
+
+## Building
+
+### Basic Build
+
+```bash
+docker build -t deepboner .
+```
+
+### With Build Arguments
+
+```bash
+# Custom tag
+docker build -t deepboner:v0.1.0 .
+
+# No cache (clean build)
+docker build --no-cache -t deepboner .
+```
+
+### Multi-Platform Build
+
+```bash
+docker buildx build --platform linux/amd64,linux/arm64 -t deepboner .
+```
+
+## Running
+
+### Basic Run
+
+```bash
+docker run -p 7860:7860 deepboner
+```
+
+### With Environment Variables
+
+```bash
+docker run -p 7860:7860 \
+  -e OPENAI_API_KEY=sk-your-key \
+  -e NCBI_API_KEY=your-ncbi-key \
+  -e LOG_LEVEL=INFO \
+  deepboner
+```
+
+### Using .env File
+
+```bash
+docker run -p 7860:7860 --env-file .env deepboner
+```
+
+### With Persistent Storage
+
+```bash
+# Persist ChromaDB data
+docker run -p 7860:7860 \
+  -v $(pwd)/data/chroma:/app/chroma_db \
+  deepboner
+```
+
+### Detached Mode
+
+```bash
+docker run -d -p 7860:7860 --name deepboner-app deepboner
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `OPENAI_API_KEY` | OpenAI API key (premium mode) | No |
+| `NCBI_API_KEY` | NCBI API key (higher rate limits) | No |
+| `HF_TOKEN` | HuggingFace token | No |
+| `LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | No |
+| `MAX_ITERATIONS` | Max search iterations (1-50) | No |
+
+### Ports
+
+| Port | Service |
+|------|---------|
+| 7860 | Gradio UI + MCP Server |
+
+### Volumes
+
+| Path | Purpose |
+|------|---------|
+| `/app/chroma_db` | ChromaDB vector store |
+| `/app/.cache` | HuggingFace model cache |
+
+## Health Check
+
+The container includes a health check:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:7860/ || exit 1
+```
+
+Check health status:
+
+```bash
+docker inspect --format='{{.State.Health.Status}}' deepboner-app
+```
+
+## Docker Compose
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  deepboner:
+    build: .
+    ports:
+      - "7860:7860"
+    environment:
+      - LOG_LEVEL=INFO
+    env_file:
+      - .env
+    volumes:
+      - chroma_data:/app/chroma_db
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:7860/"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+volumes:
+  chroma_data:
+```
+
+Run with:
+
+```bash
+docker-compose up -d
+```
+
+## Production Considerations
+
+### Resource Limits
+
+```bash
+docker run -p 7860:7860 \
+  --memory=4g \
+  --cpus=2 \
+  deepboner
+```
+
+### Logging
+
+```bash
+# View logs
+docker logs deepboner-app
+
+# Follow logs
+docker logs -f deepboner-app
+
+# With timestamps
+docker logs -t deepboner-app
+```
+
+### Security
+
+The container runs as non-root user (`appuser`):
+
+```dockerfile
+RUN useradd --create-home appuser
+USER appuser
+```
+
+Do not:
+- Expose ports beyond 7860
+- Mount sensitive host paths
+- Run as root in production
+
+### Reverse Proxy
+
+For production, use a reverse proxy (nginx, traefik):
+
+```nginx
+server {
+    listen 80;
+    server_name deepboner.example.com;
+
+    location / {
+        proxy_pass http://localhost:7860;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+    }
+}
+```
+
+## Troubleshooting
+
+### Container exits immediately
+
+Check logs:
+```bash
+docker logs deepboner-app
+```
+
+Common causes:
+- Missing environment variables
+- Port conflict
+- Insufficient memory
+
+### Slow startup
+
+First run downloads models. Pre-warm the cache:
+```bash
+# Build includes model download
+docker build -t deepboner .
+```
+
+### Out of memory
+
+Increase memory limit:
+```bash
+docker run -p 7860:7860 --memory=8g deepboner
+```
+
+### Cannot connect to port
+
+Check if port is in use:
+```bash
+lsof -i :7860
+```
+
+Use a different port:
+```bash
+docker run -p 8080:7860 deepboner
+```
+
+## Related Documentation
+
+- [HuggingFace Spaces Deployment](huggingface-spaces.md)
+- [MCP Integration](mcp-integration.md)
+- [Configuration Reference](../reference/configuration.md)

docs/deployment/huggingface-spaces.md

@@ -0,0 +1,224 @@
+# HuggingFace Spaces Deployment
+
+> **Last Updated**: 2025-12-06
+
+This guide covers deploying DeepBoner to HuggingFace Spaces.
+
+## Overview
+
+DeepBoner is deployed to HuggingFace Spaces at:
+https://huggingface.co/spaces/MCP-1st-Birthday/DeepBoner
+
+The Space runs the Gradio UI with MCP server support.
+
+## Space Configuration
+
+The Space is configured via the README.md frontmatter:
+
+```yaml
+---
+title: DeepBoner
+emoji: 🍆
+colorFrom: pink
+colorTo: purple
+sdk: gradio
+sdk_version: "6.0.1"
+python_version: "3.11"
+app_file: src/app.py
+pinned: true
+license: apache-2.0
+short_description: "Deep Research Agent for the Strongest Boners"
+tags:
+  - mcp-hackathon
+  - agents
+  - sexual-health
+  - pydantic-ai
+  - pubmed
+---
+```
+
+## Deployment Methods
+
+### Method 1: Git Push (Recommended)
+
+```bash
+# Add HuggingFace remote
+git remote add hf https://huggingface.co/spaces/MCP-1st-Birthday/DeepBoner
+
+# Push to HuggingFace
+git push hf main
+```
+
+### Method 2: HuggingFace Hub
+
+Use the HuggingFace web interface to sync with GitHub.
+
+## Secrets Configuration
+
+Configure secrets in Space Settings → Variables and secrets:
+
+| Secret | Purpose | Required |
+|--------|---------|----------|
+| `HF_TOKEN` | HuggingFace API token | Yes |
+| `NCBI_API_KEY` | Higher PubMed rate limits | No |
+| `OPENAI_API_KEY` | Premium mode (if offered) | No |
+
+### Setting Secrets
+
+1. Go to Space Settings
+2. Click "Variables and secrets"
+3. Add each secret:
+   - Name: `HF_TOKEN`
+   - Value: `hf_...` (your token)
+   - Click "Add"
+
+**Important:** Use Secrets (not Variables) for API keys - secrets are hidden.
+
+## Build Process
+
+When you push to HuggingFace:
+
+1. Space detects changes
+2. Builds from Dockerfile (if present) or requirements.txt
+3. Installs dependencies
+4. Starts the application
+
+Build logs are visible in the Logs tab.
+
+## Collaboration Workflow
+
+### Branch Strategy
+
+```
+GitHub (source of truth)
+├── main          - Production, synced to HF
+└── dev           - Development integration
+
+HuggingFace
+├── main          - Production (from GitHub)
+└── yourname-dev  - Personal dev branches
+```
+
+### Guidelines
+
+- **DO NOT** push directly to `main` on HuggingFace
+- Use personal dev branches: `yourname-dev`
+- GitHub is the source of truth for code review
+- Sync production from GitHub only
+
+### Personal Development
+
+```bash
+# Create your dev branch on HuggingFace
+git checkout -b myname-dev
+git push hf myname-dev
+
+# Test on your branch
+# Space will build from your branch if you switch to it
+```
+
+## Environment Differences
+
+### Local vs Spaces
+
+| Aspect | Local | HuggingFace Spaces |
+|--------|-------|-------------------|
+| API Keys | `.env` file | Secrets |
+| Storage | Persistent | Ephemeral |
+| Port | 7860 | Assigned |
+| Memory | Unlimited | Limited (based on tier) |
+
+### Handling Ephemeral Storage
+
+ChromaDB data is not persisted on Space restart. For production use cases requiring persistence:
+
+1. Use external database
+2. Accept regeneration on restart
+3. Consider paid Spaces with persistent storage
+
+## Hardware Tiers
+
+HuggingFace Spaces offers different hardware:
+
+| Tier | CPU | RAM | GPU | Cost |
+|------|-----|-----|-----|------|
+| Free | 2 | 16GB | None | Free |
+| CPU Basic | 2 | 16GB | None | $0.03/hr |
+| CPU Upgrade | 8 | 32GB | None | $0.07/hr |
+| T4 Small | 4 | 15GB | T4 | $0.60/hr |
+
+DeepBoner runs on Free tier but benefits from CPU Upgrade for:
+- Faster embedding generation
+- More concurrent users
+
+## Monitoring
+
+### Logs
+
+View logs in the Logs tab:
+- Build logs (during deployment)
+- Application logs (runtime)
+
+### Health
+
+Check Space status:
+- Green: Running
+- Yellow: Building
+- Red: Error
+
+## Troubleshooting
+
+### Build fails
+
+1. Check Build Logs tab
+2. Common issues:
+   - Invalid requirements.txt
+   - Missing files
+   - Syntax errors in config
+
+### App crashes on start
+
+1. Check Application Logs
+2. Common issues:
+   - Missing secrets
+   - Import errors
+   - Memory limits
+
+### Slow performance
+
+1. Check if on Free tier
+2. Consider CPU Upgrade
+3. Optimize model loading
+
+### Space sleeping
+
+Free Spaces sleep after inactivity:
+- Wake time: 30-60 seconds
+- Consider "pinned" for popular Spaces
+
+## Git Hooks
+
+To prevent accidental pushes to protected branches:
+
+```bash
+# .git/hooks/pre-push
+#!/bin/bash
+protected_branches=("main" "dev")
+current_branch=$(git rev-parse --abbrev-ref HEAD)
+remote="$1"
+
+if [[ "$remote" == "hf" || "$remote" == "huggingface" ]]; then
+  for branch in "${protected_branches[@]}"; do
+    if [[ "$current_branch" == "$branch" ]]; then
+      echo "Direct push to $branch on HuggingFace is not allowed."
+      exit 1
+    fi
+  done
+fi
+```
+
+## Related Documentation
+
+- [Docker Deployment](docker.md)
+- [MCP Integration](mcp-integration.md)
+- [Configuration Reference](../reference/configuration.md)

docs/deployment/mcp-integration.md

@@ -0,0 +1,226 @@
+# MCP Integration Guide
+
+> **Last Updated**: 2025-12-06
+
+This guide covers setting up DeepBoner's MCP (Model Context Protocol) server for integration with Claude Desktop and other MCP clients.
+
+## Overview
+
+DeepBoner exposes an MCP server via Gradio's built-in support. This allows Claude Desktop and other MCP-compatible clients to use DeepBoner's search tools directly.
+
+## MCP Server URL
+
+When DeepBoner is running:
+
+```
+http://localhost:7860/gradio_api/mcp/
+```
+
+On HuggingFace Spaces:
+```
+https://mcp-1st-birthday-deepboner.hf.space/gradio_api/mcp/
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_pubmed` | Search peer-reviewed biomedical literature |
+| `search_clinical_trials` | Search ClinicalTrials.gov for active/completed trials |
+| `search_europepmc` | Search Europe PMC preprints and papers |
+| `search_all_sources` | Search all sources simultaneously with deduplication |
+
+### Tool Signatures
+
+```python
+def search_pubmed(query: str, max_results: int = 10) -> list[Evidence]:
+    """Search PubMed for biomedical literature."""
+
+def search_clinical_trials(query: str, max_results: int = 10) -> list[Evidence]:
+    """Search ClinicalTrials.gov."""
+
+def search_europepmc(query: str, max_results: int = 10) -> list[Evidence]:
+    """Search Europe PMC."""
+
+def search_all_sources(query: str, max_results_per_source: int = 10) -> SearchResult:
+    """Search all sources with cross-source deduplication."""
+```
+
+## Claude Desktop Setup
+
+### 1. Start DeepBoner
+
+```bash
+uv run python src/app.py
+```
+
+### 2. Configure Claude Desktop
+
+Edit your Claude Desktop configuration:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add the MCP server:
+
+```json
+{
+  "mcpServers": {
+    "deepboner": {
+      "url": "http://localhost:7860/gradio_api/mcp/"
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop
+
+Close and reopen Claude Desktop to load the new configuration.
+
+### 4. Verify Connection
+
+In Claude Desktop, you should see DeepBoner's tools available. Try:
+
+```
+Use the search_pubmed tool to find recent papers on testosterone therapy
+```
+
+## Using with HuggingFace Spaces
+
+Point to the deployed Space:
+
+```json
+{
+  "mcpServers": {
+    "deepboner-cloud": {
+      "url": "https://mcp-1st-birthday-deepboner.hf.space/gradio_api/mcp/"
+    }
+  }
+}
+```
+
+Note: HuggingFace Spaces may sleep after inactivity. The first request will wake the Space (30-60 second delay).
+
+## Tool Implementation
+
+Tools are defined in `src/mcp_tools.py`:
+
+```python
+def search_pubmed(query: str, max_results: int = 10) -> list[Evidence]:
+    """Search PubMed for biomedical literature.
+
+    Args:
+        query: Search query for PubMed
+        max_results: Maximum number of results to return
+
+    Returns:
+        List of Evidence objects with citations
+    """
+    tool = PubMedTool()
+    result = tool.search(query, max_results=max_results)
+    return result.evidence
+```
+
+## Adding New Tools
+
+To expose additional tools via MCP:
+
+1. Add the function to `src/mcp_tools.py`:
+
+```python
+def search_openalex(query: str, max_results: int = 10) -> list[Evidence]:
+    """Search OpenAlex for scholarly metadata."""
+    tool = OpenAlexTool()
+    result = tool.search(query, max_results=max_results)
+    return result.evidence
+```
+
+2. Register in Gradio app (`src/app.py`):
+
+The tools are automatically exposed via Gradio's MCP support when added to the interface.
+
+## Troubleshooting
+
+### Tools not appearing in Claude Desktop
+
+1. Verify DeepBoner is running:
+   ```bash
+   curl http://localhost:7860/gradio_api/mcp/
+   ```
+
+2. Check config syntax:
+   ```bash
+   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool
+   ```
+
+3. Restart Claude Desktop
+
+### Connection refused
+
+- Check DeepBoner is running on port 7860
+- Verify no firewall blocking
+- Try accessing in browser: http://localhost:7860
+
+### Slow responses
+
+- First query loads ML models
+- HuggingFace Space may need to wake up
+- External APIs have rate limits
+
+### Authentication errors
+
+MCP server doesn't require authentication for local use. For production:
+- Use API gateway
+- Implement auth middleware
+
+## Security Considerations
+
+### Local Development
+
+Local MCP server is accessible only from localhost by default.
+
+### Production
+
+For production deployments:
+
+1. **Use HTTPS** - Enable TLS via reverse proxy
+2. **Add authentication** - Consider API keys or OAuth
+3. **Rate limit** - Prevent abuse
+4. **Monitor** - Log tool usage
+
+### Data Privacy
+
+- Search queries are sent to external APIs (PubMed, etc.)
+- Review external API privacy policies
+- Don't expose sensitive research queries
+
+## Protocol Details
+
+### MCP Protocol Version
+
+DeepBoner uses MCP protocol via Gradio 6.x integration.
+
+### Request/Response Format
+
+Requests follow the MCP specification:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "tools/call",
+  "params": {
+    "name": "search_pubmed",
+    "arguments": {
+      "query": "testosterone therapy",
+      "max_results": 10
+    }
+  },
+  "id": 1
+}
+```
+
+## Related Documentation
+
+- [Docker Deployment](docker.md)
+- [HuggingFace Spaces](huggingface-spaces.md)
+- [Component Inventory](../architecture/component-inventory.md)

docs/development/code-style.md

@@ -0,0 +1,373 @@
+# Code Style Guide
+
+> **Last Updated**: 2025-12-06
+
+This guide covers code style conventions and tooling for DeepBoner.
+
+## Quick Reference
+
+```bash
+# Auto-format code
+make format
+
+# Check linting
+make lint
+
+# Type check
+make typecheck
+
+# Run all checks
+make check
+```
+
+## Tooling
+
+### Ruff (Linting & Formatting)
+
+Configuration in `pyproject.toml`:
+
+```toml
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "B",    # flake8-bugbear
+    "I",    # isort
+    "N",    # pep8-naming
+    "UP",   # pyupgrade
+    "PL",   # pylint
+    "RUF",  # ruff-specific
+]
+```
+
+### MyPy (Type Checking)
+
+Configuration in `pyproject.toml`:
+
+```toml
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+disallow_untyped_defs = true
+warn_return_any = true
+```
+
+### Pre-commit Hooks
+
+Hooks run automatically on commit:
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    hooks:
+      - id: ruff
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    hooks:
+      - id: mypy
+```
+
+## Python Style
+
+### Type Hints
+
+All functions must have type annotations:
+
+```python
+# Good
+def search(query: str, limit: int = 10) -> list[Evidence]:
+    """Search for evidence."""
+    pass
+
+# Bad
+def search(query, limit=10):
+    pass
+```
+
+Use modern type hint syntax (Python 3.11+):
+
+```python
+# Good
+def process(items: list[str] | None) -> dict[str, int]:
+    pass
+
+# Avoid (old syntax)
+from typing import List, Dict, Optional
+def process(items: Optional[List[str]]) -> Dict[str, int]:
+    pass
+```
+
+### Docstrings
+
+Use Google-style docstrings for public APIs:
+
+```python
+def search_pubmed(query: str, max_results: int = 10) -> SearchResult:
+    """Search PubMed for biomedical literature.
+
+    Args:
+        query: The search query string.
+        max_results: Maximum number of results to return.
+
+    Returns:
+        SearchResult containing evidence and metadata.
+
+    Raises:
+        SearchError: If the API call fails.
+        RateLimitError: If rate limit is exceeded.
+    """
+    pass
+```
+
+### Class Documentation
+
+```python
+class SearchHandler:
+    """Orchestrates parallel searches across multiple sources.
+
+    This handler implements a scatter-gather pattern to query
+    multiple biomedical databases simultaneously.
+
+    Attributes:
+        sources: List of enabled search sources.
+        timeout: Timeout for each search in seconds.
+
+    Example:
+        handler = SearchHandler()
+        result = handler.search_all("testosterone therapy")
+    """
+
+    def __init__(self, sources: list[str] | None = None) -> None:
+        """Initialize the search handler.
+
+        Args:
+            sources: Optional list of sources to enable.
+                    Defaults to all sources.
+        """
+        pass
+```
+
+### Imports
+
+Imports are sorted by isort (via ruff):
+
+```python
+# Standard library
+import asyncio
+from datetime import datetime
+from typing import Any
+
+# Third-party
+import httpx
+from pydantic import BaseModel
+
+# Local
+from src.utils.config import settings
+from src.utils.exceptions import SearchError
+```
+
+### Line Length
+
+Maximum 100 characters. Break long lines:
+
+```python
+# Good - break at logical points
+result = very_long_function_name(
+    first_argument=value1,
+    second_argument=value2,
+    third_argument=value3,
+)
+
+# Good - string continuation
+message = (
+    "This is a very long message that needs to be "
+    "split across multiple lines for readability."
+)
+```
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Classes | PascalCase | `SearchHandler` |
+| Functions | snake_case | `search_pubmed` |
+| Variables | snake_case | `max_results` |
+| Constants | UPPER_SNAKE | `MAX_ITERATIONS` |
+| Private | leading underscore | `_internal_method` |
+| Type vars | PascalCase | `T`, `ConfigT` |
+
+### Exceptions
+
+Custom exceptions in `src/utils/exceptions.py`:
+
+```python
+from src.utils.exceptions import SearchError
+
+# Raising
+raise SearchError(f"API returned {status_code}")
+
+# With cause
+try:
+    response = client.get(url)
+except httpx.HTTPError as e:
+    raise SearchError(f"Request failed: {e}") from e
+```
+
+## Pydantic Models
+
+### Model Definition
+
+```python
+from pydantic import BaseModel, Field
+
+class Evidence(BaseModel):
+    """A piece of evidence from search."""
+
+    content: str = Field(min_length=1, description="The evidence text")
+    relevance: float = Field(ge=0.0, le=1.0, default=0.0)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"frozen": True}  # Make immutable
+```
+
+### Settings
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    """Application settings from environment."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        case_sensitive=False,
+    )
+
+    max_iterations: int = Field(default=10, ge=1, le=50)
+```
+
+## Async Code
+
+### Async Functions
+
+```python
+async def search_async(query: str) -> SearchResult:
+    """Async search implementation."""
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url)
+        return parse_response(response)
+```
+
+### Concurrent Execution
+
+```python
+async def search_all(query: str) -> list[SearchResult]:
+    """Search all sources concurrently."""
+    tasks = [
+        search_pubmed(query),
+        search_clinicaltrials(query),
+        search_europepmc(query),
+    ]
+    return await asyncio.gather(*tasks, return_exceptions=True)
+```
+
+## Comments
+
+### When to Comment
+
+```python
+# Good: Explain WHY, not WHAT
+# PubMed rate limits without API key - add delay to avoid 429
+await asyncio.sleep(0.34)
+
+# Bad: Obvious comment
+# Increment counter
+counter += 1
+```
+
+### TODO Comments
+
+```python
+# TODO(username): Description of what needs to be done
+# TODO: Short-term fix, proper solution needs X
+```
+
+## Ignored Rules
+
+Some rules are disabled for good reasons:
+
+```toml
+ignore = [
+    "PLR0913",  # Too many arguments (agents need many params)
+    "PLR0912",  # Too many branches (complex orchestrator logic)
+    "PLR2004",  # Magic values (statistical constants)
+    "PLW0603",  # Global statement (singleton pattern)
+    "PLC0415",  # Lazy imports for optional dependencies
+]
+```
+
+## File Organization
+
+### Module Structure
+
+```python
+"""Module docstring explaining purpose."""
+
+# Imports (sorted)
+import ...
+
+# Constants
+MAX_RESULTS = 100
+
+# Type definitions
+ResultType = dict[str, Any]
+
+# Classes
+class MyClass:
+    pass
+
+# Functions
+def my_function():
+    pass
+
+# Module-level code (minimize)
+if __name__ == "__main__":
+    main()
+```
+
+### Package Structure
+
+```
+src/tools/
+├── __init__.py    # Public exports
+├── base.py        # Base classes
+├── pubmed.py      # PubMed implementation
+├── clinicaltrials.py
+└── search_handler.py
+```
+
+## Code Review Checklist
+
+Before submitting a PR:
+
+- [ ] All functions have type hints
+- [ ] Public APIs have docstrings
+- [ ] `make check` passes
+- [ ] No hardcoded credentials
+- [ ] Error cases are handled
+- [ ] Tests cover new code
+
+---
+
+## Related Documentation
+
+- [Testing Guide](testing.md)
+- [Contributing Guide](../../CONTRIBUTING.md)
+- [Architecture Overview](../architecture/overview.md)

docs/development/release-process.md

@@ -0,0 +1,191 @@
+# Release Process
+
+> **Last Updated**: 2025-12-06
+
+This document describes the release workflow for DeepBoner.
+
+## Version Numbering
+
+DeepBoner uses [Semantic Versioning](https://semver.org/):
+
+```
+MAJOR.MINOR.PATCH
+
+1.0.0  - First stable release
+0.2.0  - New features (backwards compatible)
+0.1.1  - Bug fixes only
+```
+
+### Pre-release Versions
+
+```
+0.1.0-alpha.1  - Early development
+0.1.0-beta.1   - Feature complete, testing
+0.1.0-rc.1     - Release candidate
+```
+
+## Release Workflow
+
+### 1. Prepare the Release
+
+```bash
+# Ensure you're on main and up to date
+git checkout main
+git pull origin main
+
+# Run all checks
+make check
+```
+
+### 2. Update Version
+
+Edit `pyproject.toml`:
+
+```toml
+[project]
+version = "0.2.0"  # Update this
+```
+
+### 3. Update CHANGELOG
+
+Add release notes to `CHANGELOG.md`:
+
+```markdown
+## [0.2.0] - 2025-12-15
+
+### Added
+- New feature X
+
+### Fixed
+- Bug in Y
+
+### Changed
+- Improved Z
+```
+
+### 4. Create Release Commit
+
+```bash
+git add pyproject.toml CHANGELOG.md
+git commit -m "release: v0.2.0"
+```
+
+### 5. Tag the Release
+
+```bash
+git tag -a v0.2.0 -m "Release v0.2.0"
+```
+
+### 6. Push
+
+```bash
+git push origin main
+git push origin v0.2.0
+```
+
+### 7. Create GitHub Release
+
+1. Go to GitHub → Releases → New Release
+2. Select the tag (v0.2.0)
+3. Copy release notes from CHANGELOG
+4. Publish release
+
+### 8. Deploy to HuggingFace Spaces
+
+```bash
+# Push to HuggingFace
+git push huggingface-upstream main
+```
+
+## Release Checklist
+
+### Before Release
+
+- [ ] All tests pass (`make check`)
+- [ ] CHANGELOG updated
+- [ ] Version bumped in pyproject.toml
+- [ ] Documentation updated
+- [ ] No outstanding critical bugs
+- [ ] Security audit clean (`uv run pip-audit`)
+
+### After Release
+
+- [ ] GitHub release created
+- [ ] HuggingFace Space updated
+- [ ] Announce release (if significant)
+
+## Hotfix Process
+
+For urgent fixes on released versions:
+
+```bash
+# Create hotfix branch from tag
+git checkout -b hotfix/0.1.1 v0.1.0
+
+# Make fix
+# ...
+
+# Bump patch version
+# Update CHANGELOG
+
+# Commit and tag
+git commit -m "fix: critical bug in X"
+git tag -a v0.1.1 -m "Hotfix v0.1.1"
+
+# Push
+git push origin v0.1.1
+
+# Merge back to main
+git checkout main
+git merge hotfix/0.1.1
+git push origin main
+```
+
+## CI/CD Integration
+
+Releases trigger GitHub Actions:
+
+```yaml
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build and test
+        run: make check
+```
+
+## Rollback Procedure
+
+If a release has critical issues:
+
+```bash
+# Revert to previous version in HuggingFace
+git push huggingface-upstream v0.1.0:main --force
+
+# Document in CHANGELOG
+# Plan hotfix release
+```
+
+## Version Locations
+
+Keep these in sync:
+
+| File | Field |
+|------|-------|
+| `pyproject.toml` | `version = "X.Y.Z"` |
+| `CHANGELOG.md` | `## [X.Y.Z] - YYYY-MM-DD` |
+| Git tag | `vX.Y.Z` |
+
+---
+
+## Related Documentation
+
+- [CHANGELOG](../../CHANGELOG.md)
+- [Contributing Guide](../../CONTRIBUTING.md)
+- [Deployment Guide](../deployment/docker.md)

docs/development/testing.md

@@ -0,0 +1,408 @@
+# Testing Guide
+
+> **Last Updated**: 2025-12-06
+
+This guide covers testing strategy, patterns, and best practices for DeepBoner.
+
+## Quick Reference
+
+```bash
+# Run all tests
+make test
+
+# Run with coverage
+make test-cov
+
+# Run specific file
+uv run pytest tests/unit/utils/test_config.py -v
+
+# Run specific test
+uv run pytest tests/unit/utils/test_config.py::TestSettings::test_default -v
+
+# Run by marker
+uv run pytest -m unit          # Unit tests only
+uv run pytest -m integration   # Integration tests only
+uv run pytest -m "not slow"    # Skip slow tests
+```
+
+## Test Organization
+
+```
+tests/
+├── conftest.py                 # Shared fixtures
+├── unit/                       # Unit tests (mocked, fast)
+│   ├── orchestrators/
+│   ├── agents/
+│   ├── clients/
+│   ├── tools/
+│   ├── services/
+│   ├── utils/
+│   ├── prompts/
+│   ├── agent_factory/
+│   ├── config/
+│   ├── graph/
+│   └── mcp/
+├── integration/                # Integration tests (real APIs)
+└── e2e/                        # End-to-end tests
+```
+
+### Directory Mapping
+
+Tests mirror the `src/` structure:
+- `src/tools/pubmed.py` → `tests/unit/tools/test_pubmed.py`
+- `src/utils/config.py` → `tests/unit/utils/test_config.py`
+
+## Test Markers
+
+### Available Markers
+
+| Marker | Purpose | Example |
+|--------|---------|---------|
+| `@pytest.mark.unit` | Unit tests (mocked) | Most tests |
+| `@pytest.mark.integration` | Real API calls | API testing |
+| `@pytest.mark.slow` | Long-running tests | Full pipeline |
+| `@pytest.mark.e2e` | End-to-end tests | Complete flows |
+
+### Using Markers
+
+```python
+import pytest
+
+@pytest.mark.unit
+def test_search_returns_results():
+    """Unit test with mocked API."""
+    pass
+
+@pytest.mark.integration
+def test_pubmed_real_api():
+    """Integration test with real PubMed API."""
+    pass
+```
+
+### Running by Marker
+
+```bash
+uv run pytest -m unit              # Only unit tests
+uv run pytest -m "not integration" # Skip integration tests
+uv run pytest -m "unit or slow"    # Unit OR slow tests
+```
+
+## Test Fixtures
+
+### Core Fixtures (conftest.py)
+
+#### `mock_httpx_client`
+
+Mocks httpx for HTTP testing:
+
+```python
+def test_pubmed_search(mock_httpx_client):
+    mock_httpx_client.get("https://eutils.ncbi.nlm.nih.gov/...").respond(
+        200,
+        json={"esearchresult": {"idlist": ["12345"]}}
+    )
+
+    tool = PubMedTool()
+    result = tool.search("test query")
+    assert len(result.evidence) > 0
+```
+
+#### `mock_llm_response`
+
+Mocks LLM completions:
+
+```python
+def test_judge_evaluates(mock_llm_response):
+    mock_llm_response("The evidence is sufficient.")
+
+    judge = JudgeAgent()
+    assessment = judge.assess(evidence)
+    assert assessment.sufficient
+```
+
+#### `sample_evidence`
+
+Provides test evidence data:
+
+```python
+def test_synthesis(sample_evidence):
+    report = synthesizer.create_report(sample_evidence)
+    assert report.title
+```
+
+### Creating Fixtures
+
+```python
+# tests/conftest.py
+
+@pytest.fixture
+def mock_search_handler(mocker):
+    """Mock SearchHandler for unit tests."""
+    handler = mocker.Mock(spec=SearchHandler)
+    handler.search_all.return_value = SearchResult(
+        query="test",
+        evidence=[],
+        sources_searched=["pubmed"],
+        total_found=0
+    )
+    return handler
+```
+
+## Mocking Patterns
+
+### HTTP Mocking with respx
+
+```python
+import respx
+from httpx import Response
+
+@pytest.mark.unit
+def test_api_call():
+    with respx.mock:
+        respx.get("https://api.example.com/data").mock(
+            return_value=Response(200, json={"result": "ok"})
+        )
+
+        result = make_api_call()
+        assert result == "ok"
+```
+
+### General Mocking with pytest-mock
+
+```python
+def test_with_mock(mocker):
+    # Mock a function
+    mock_func = mocker.patch("src.tools.pubmed.fetch_results")
+    mock_func.return_value = {"results": []}
+
+    # Mock a class method
+    mocker.patch.object(PubMedTool, "search", return_value=[])
+
+    # Mock a property
+    mocker.patch.object(Settings, "has_openai_key", True)
+```
+
+### Mocking Async Functions
+
+```python
+import pytest
+from unittest.mock import AsyncMock
+
+@pytest.mark.asyncio
+async def test_async_search(mocker):
+    mock_search = AsyncMock(return_value=[])
+    mocker.patch.object(SearchHandler, "search_all", mock_search)
+
+    result = await handler.search_all("query")
+    assert result == []
+```
+
+## Writing Tests
+
+### Test Structure (AAA Pattern)
+
+```python
+def test_search_handler_aggregates_results():
+    """Verify search handler combines results from multiple sources."""
+    # Arrange
+    handler = SearchHandler()
+    query = "testosterone therapy"
+
+    # Act
+    result = handler.search_all(query)
+
+    # Assert
+    assert len(result.evidence) > 0
+    assert "pubmed" in result.sources_searched
+```
+
+### Test Naming
+
+```python
+# Good: Describes behavior
+def test_judge_returns_continue_when_evidence_insufficient():
+    pass
+
+def test_search_raises_rate_limit_error_on_429():
+    pass
+
+# Bad: Vague
+def test_judge():
+    pass
+
+def test_search_error():
+    pass
+```
+
+### Testing Exceptions
+
+```python
+import pytest
+from src.utils.exceptions import SearchError
+
+def test_search_raises_on_api_failure():
+    """Verify SearchError is raised when API returns error."""
+    with pytest.raises(SearchError) as exc_info:
+        search_with_failing_api()
+
+    assert "API returned 500" in str(exc_info.value)
+```
+
+### Async Tests
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_async_search():
+    """Test async search operation."""
+    result = await search_handler.search_all("query")
+    assert result is not None
+```
+
+## Test Data
+
+### Using Factories
+
+```python
+# tests/factories.py
+
+def make_evidence(
+    content: str = "Test content",
+    source: str = "pubmed",
+    relevance: float = 0.8
+) -> Evidence:
+    return Evidence(
+        content=content,
+        citation=Citation(
+            source=source,
+            title="Test Paper",
+            url="https://test.com",
+            date="2024-01-01",
+            authors=["Test Author"]
+        ),
+        relevance=relevance,
+        metadata={}
+    )
+```
+
+### Parameterized Tests
+
+```python
+import pytest
+
+@pytest.mark.parametrize("query,expected_count", [
+    ("testosterone", 10),
+    ("estrogen therapy", 5),
+    ("very specific rare condition", 0),
+])
+def test_search_returns_expected_results(query, expected_count, mock_api):
+    result = search(query)
+    assert len(result.evidence) == expected_count
+```
+
+## Coverage
+
+### Running with Coverage
+
+```bash
+# Terminal report
+make test-cov
+
+# HTML report
+uv run pytest --cov=src --cov-report=html
+open htmlcov/index.html
+```
+
+### Coverage Configuration
+
+From `pyproject.toml`:
+
+```toml
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/__init__.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+```
+
+### Coverage Targets
+
+| Module | Target | Notes |
+|--------|--------|-------|
+| `utils/` | 90%+ | Core utilities |
+| `tools/` | 80%+ | API wrappers |
+| `orchestrators/` | 70%+ | Complex logic |
+| `agents/` | 70%+ | LLM-dependent |
+
+## CI Integration
+
+Tests run in GitHub Actions:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Run Tests
+  run: uv run pytest --cov=src --cov-report=xml
+
+- name: Upload Coverage
+  uses: codecov/codecov-action@v4
+```
+
+## Best Practices
+
+### Do
+
+- Write tests before implementation (TDD)
+- Use descriptive test names
+- Test edge cases and error conditions
+- Keep tests fast (mock external dependencies)
+- Use fixtures for shared setup
+- Test one behavior per test
+
+### Don't
+
+- Test implementation details
+- Make tests dependent on order
+- Use real API keys in tests
+- Skip error handling tests
+- Leave flaky tests unfixed
+
+## Troubleshooting
+
+### Tests pass locally but fail in CI
+
+1. Check for hardcoded paths
+2. Verify timezone handling
+3. Look for async timing issues
+4. Check environment variables
+
+### Async test hangs
+
+```python
+# Add timeout
+@pytest.mark.asyncio
+@pytest.mark.timeout(10)
+async def test_with_timeout():
+    pass
+```
+
+### Mock not working
+
+```python
+# Ensure correct import path
+mocker.patch("src.tools.pubmed.PubMedTool")  # Correct
+mocker.patch("tools.pubmed.PubMedTool")       # Wrong
+```
+
+---
+
+## Related Documentation
+
+- [Code Style Guide](code-style.md)
+- [Contributing Guide](../../CONTRIBUTING.md)
+- [Component Inventory](../architecture/component-inventory.md)

docs/getting-started/configuration.md

@@ -0,0 +1,172 @@
+# Configuration Guide
+
+DeepBoner uses [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) for configuration, loading values from environment variables and `.env` files.
+
+## Configuration Sources
+
+Settings are loaded in this order (later sources override earlier):
+
+1. Default values in code
+2. `.env` file in project root
+3. Environment variables
+
+## Quick Setup
+
+```bash
+# Copy the template
+cp .env.example .env
+
+# Edit with your settings
+nano .env  # or your preferred editor
+```
+
+## Configuration Categories
+
+### LLM Configuration
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `LLM_PROVIDER` | string | `"openai"` | LLM provider: `"openai"` or `"huggingface"` |
+| `OPENAI_API_KEY` | string | None | OpenAI API key (enables premium mode) |
+| `OPENAI_MODEL` | string | `"gpt-5"` | OpenAI model to use |
+| `HUGGINGFACE_MODEL` | string | `"Qwen/Qwen2.5-7B-Instruct"` | HuggingFace model for free tier |
+| `HF_TOKEN` | string | None | HuggingFace token for gated models |
+
+**Notes:**
+- If `OPENAI_API_KEY` is set, OpenAI is used automatically
+- Without any key, free HuggingFace tier is used
+- See CLAUDE.md for critical notes on HuggingFace model selection
+
+### Embedding Configuration
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `OPENAI_EMBEDDING_MODEL` | string | `"text-embedding-3-small"` | OpenAI embedding model (premium RAG) |
+| `LOCAL_EMBEDDING_MODEL` | string | `"all-MiniLM-L6-v2"` | Local sentence-transformers model |
+
+### External Services
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `NCBI_API_KEY` | string | None | NCBI API key for higher PubMed rate limits |
+| `CHROMA_DB_PATH` | string | `"./chroma_db"` | ChromaDB storage path |
+
+### Agent Configuration
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `MAX_ITERATIONS` | int | `10` | Maximum search-judge loop iterations (1-50) |
+| `ADVANCED_MAX_ROUNDS` | int | `5` | Max coordination rounds for multi-agent mode |
+| `ADVANCED_TIMEOUT` | float | `600.0` | Timeout for advanced mode in seconds |
+| `SEARCH_TIMEOUT` | int | `30` | Seconds to wait for each search operation |
+
+### Logging
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `LOG_LEVEL` | string | `"INFO"` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+
+## Example Configurations
+
+### Minimal (Free Tier)
+
+```bash
+# .env - No keys required
+LOG_LEVEL=INFO
+MAX_ITERATIONS=5
+```
+
+### Development
+
+```bash
+# .env
+LOG_LEVEL=DEBUG
+MAX_ITERATIONS=3
+SEARCH_TIMEOUT=15
+```
+
+### Production (With OpenAI)
+
+```bash
+# .env
+OPENAI_API_KEY=sk-your-production-key
+NCBI_API_KEY=your-ncbi-key
+LOG_LEVEL=WARNING
+MAX_ITERATIONS=10
+CHROMA_DB_PATH=/data/chroma_db
+```
+
+### HuggingFace Spaces
+
+```bash
+# Set as Secrets in Space Settings
+HF_TOKEN=hf_your-token
+NCBI_API_KEY=your-ncbi-key
+```
+
+## Backend Selection Logic
+
+The system auto-selects backends based on available keys:
+
+```
+Has OPENAI_API_KEY?
+  ├── YES → OpenAI GPT-5 (premium)
+  └── NO → HuggingFace Qwen 2.5 7B (free)
+```
+
+Both backends use the same orchestration logic - only the LLM differs.
+
+## Programmatic Access
+
+Access settings in code:
+
+```python
+from src.utils.config import settings
+
+# Check available backends
+if settings.has_openai_key:
+    print("Premium mode available")
+
+# Get specific settings
+print(f"Max iterations: {settings.max_iterations}")
+print(f"Log level: {settings.log_level}")
+```
+
+## Validation
+
+Settings are validated on load:
+
+```python
+from src.utils.config import Settings
+
+# These will raise ValidationError
+Settings(max_iterations=100)  # Must be 1-50
+Settings(log_level="TRACE")   # Invalid level
+```
+
+## Security Notes
+
+- Never commit `.env` files to git
+- Use environment variables in production
+- API keys are never logged
+- See [SECURITY.md](../../SECURITY.md) for full security policy
+
+## Troubleshooting
+
+**Settings not loading?**
+- Check file is named `.env` (not `.env.txt`)
+- Verify file is in project root
+- Check for syntax errors (no spaces around `=`)
+
+**API key not working?**
+- Verify key is valid and not expired
+- Check for trailing whitespace
+- Ensure correct variable name
+
+See [Troubleshooting](troubleshooting.md) for more help.
+
+## Related Documentation
+
+- [Environment Variables Reference](../reference/environment-variables.md)
+- [Installation Guide](installation.md)
+- [Deployment Guide](../deployment/docker.md)

docs/getting-started/installation.md

@@ -0,0 +1,164 @@
+# Installation Guide
+
+This guide covers installing DeepBoner for development or local use.
+
+## Prerequisites
+
+### Required
+- **Python 3.11+** - Required for type hints and async features
+- **uv** - Fast Python package manager ([install guide](https://github.com/astral-sh/uv))
+- **Git** - For version control
+
+### Optional
+- **Docker** - For containerized deployment
+- **OpenAI API key** - For premium features (GPT-5)
+- **NCBI API key** - For higher PubMed rate limits
+
+## Quick Install
+
+```bash
+# Clone the repository
+git clone https://github.com/The-Obstacle-Is-The-Way/DeepBoner.git
+cd DeepBoner
+
+# Install all dependencies (including dev tools)
+make install
+```
+
+This runs `uv sync --all-extras && uv run pre-commit install` behind the scenes.
+
+## Manual Installation
+
+If you prefer not to use `make`:
+
+```bash
+# Install uv if not already installed
+pip install uv
+
+# Sync all dependencies
+uv sync --all-extras
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+## Optional Dependencies
+
+DeepBoner has optional dependency groups for specific features:
+
+```bash
+# Core only (no dev tools)
+uv sync
+
+# With development tools
+uv sync --extra dev
+
+# With Microsoft Agent Framework (Magentic)
+uv sync --extra magentic
+
+# With LlamaIndex RAG support
+uv sync --extra rag
+
+# Everything
+uv sync --all-extras
+```
+
+## Environment Configuration
+
+1. Copy the example environment file:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` with your settings:
+   ```bash
+   # Required for premium features
+   OPENAI_API_KEY=sk-your-key-here
+
+   # Optional: Higher PubMed rate limits
+   NCBI_API_KEY=your-ncbi-key-here
+
+   # Optional: HuggingFace token for gated models
+   HF_TOKEN=hf_your-token-here
+   ```
+
+See [Configuration Guide](configuration.md) for all options.
+
+## Verify Installation
+
+Run the quality checks to verify everything works:
+
+```bash
+make check
+```
+
+This runs:
+- Linting (ruff)
+- Type checking (mypy)
+- Unit tests (pytest)
+
+All checks should pass before you start development.
+
+## Running the Application
+
+Start the Gradio UI:
+
+```bash
+uv run python src/app.py
+```
+
+Open http://localhost:7860 in your browser.
+
+## Docker Installation
+
+For containerized deployment:
+
+```bash
+# Build the image
+docker build -t deepboner .
+
+# Run the container
+docker run -p 7860:7860 --env-file .env deepboner
+```
+
+See [Docker Deployment](../deployment/docker.md) for details.
+
+## Troubleshooting
+
+### Common Issues
+
+**uv not found**
+```bash
+pip install uv
+# or
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**Python version mismatch**
+```bash
+# Check your Python version
+python --version
+
+# Should be 3.11 or higher
+# Use pyenv to manage versions if needed
+```
+
+**Pre-commit hook failures**
+```bash
+# Run formatting to fix most issues
+make format
+```
+
+**Import errors after install**
+```bash
+# Ensure you're using uv run
+uv run python -c "import src.app"
+```
+
+See [Troubleshooting](troubleshooting.md) for more solutions.
+
+## Next Steps
+
+- [Quickstart Guide](quickstart.md) - Run your first query
+- [Configuration Guide](configuration.md) - Configure all options
+- [Architecture Overview](../architecture/overview.md) - Understand the system

docs/getting-started/quickstart.md

@@ -0,0 +1,147 @@
+# Quickstart Guide
+
+Get DeepBoner running in 5 minutes.
+
+## Prerequisites
+
+- Python 3.11+ installed
+- Repository cloned and dependencies installed (see [Installation](installation.md))
+
+## 1. Start the Application
+
+```bash
+# From the repository root
+uv run python src/app.py
+```
+
+You should see:
+```
+Running on local URL:  http://127.0.0.1:7860
+```
+
+## 2. Open the UI
+
+Navigate to http://localhost:7860 in your browser.
+
+You'll see a chat interface with:
+- Input field for research questions
+- Optional API key input (for premium features)
+- Research results display
+
+## 3. Ask Your First Question
+
+Try one of these example queries:
+
+```
+What drugs improve female libido post-menopause?
+```
+
+```
+Clinical trials for ED alternatives to PDE5 inhibitors?
+```
+
+```
+Evidence for testosterone therapy in women with HSDD?
+```
+
+## 4. Understanding the Output
+
+DeepBoner will:
+
+1. **Search** multiple biomedical databases:
+   - PubMed (peer-reviewed literature)
+   - ClinicalTrials.gov (active/completed trials)
+   - Europe PMC (preprints and papers)
+   - OpenAlex (scholarly metadata)
+
+2. **Judge** evidence quality using LLM
+
+3. **Loop** if more evidence is needed
+
+4. **Synthesize** a research report with citations
+
+You'll see status updates as each phase completes.
+
+## 5. Free vs Premium Mode
+
+### Free Mode (No API Key)
+
+- Uses HuggingFace Inference API
+- Model: Qwen 2.5 7B Instruct
+- Slower but fully functional
+
+### Premium Mode (With OpenAI Key)
+
+- Enter your OpenAI API key in the UI
+- Uses GPT-5 for better synthesis
+- Faster and more detailed reports
+
+To use premium mode:
+1. Get an API key from [OpenAI](https://platform.openai.com)
+2. Enter it in the "OpenAI API Key" field
+3. Your queries will automatically use GPT-5
+
+## 6. Using MCP Tools
+
+DeepBoner exposes MCP (Model Context Protocol) tools for integration with Claude Desktop and other clients.
+
+### MCP Server URL
+```
+http://localhost:7860/gradio_api/mcp/
+```
+
+### Available Tools
+- `search_pubmed` - Search peer-reviewed literature
+- `search_clinical_trials` - Search clinical trials
+- `search_europepmc` - Search Europe PMC
+- `search_all_sources` - Search all sources with deduplication
+
+### Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "deepboner": {
+      "url": "http://localhost:7860/gradio_api/mcp/"
+    }
+  }
+}
+```
+
+## Example Scripts
+
+For programmatic usage, see the example scripts:
+
+```bash
+# Search demo
+uv run python examples/search_demo/run_search.py
+
+# Full orchestrator demo
+uv run python examples/orchestrator_demo/run_agent.py
+
+# Multi-agent demo (requires OpenAI key)
+uv run python examples/orchestrator_demo/run_magentic.py
+```
+
+## Next Steps
+
+- [Configuration Guide](configuration.md) - Customize settings
+- [MCP Integration](../deployment/mcp-integration.md) - Set up Claude Desktop
+- [Architecture Overview](../architecture/overview.md) - Understand how it works
+
+## Troubleshooting
+
+**Slow first response?**
+- First query loads ML models (sentence-transformers)
+- Subsequent queries are faster
+
+**No results?**
+- Check your internet connection
+- External APIs may have rate limits
+
+**Rate limit errors?**
+- Add NCBI_API_KEY for higher PubMed limits
+- Wait and retry
+
+See [Troubleshooting](troubleshooting.md) for more help.

docs/getting-started/troubleshooting.md

@@ -0,0 +1,280 @@
+# Troubleshooting Guide
+
+Common issues and their solutions.
+
+## Installation Issues
+
+### uv not found
+
+**Symptom:** `command not found: uv`
+
+**Solution:**
+```bash
+# Install uv
+pip install uv
+# or
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Python version mismatch
+
+**Symptom:** `Python 3.11+ required` or syntax errors
+
+**Solution:**
+```bash
+# Check version
+python --version
+
+# Install Python 3.11+ via pyenv
+pyenv install 3.11
+pyenv local 3.11
+```
+
+### Dependency conflicts
+
+**Symptom:** Package version conflicts during install
+
+**Solution:**
+```bash
+# Clean install
+rm -rf .venv uv.lock
+uv sync --all-extras
+```
+
+## Runtime Issues
+
+### Slow first query
+
+**Symptom:** First query takes 30+ seconds
+
+**Cause:** Model loading (sentence-transformers) on first use
+
+**Solution:** This is expected. Subsequent queries are faster.
+
+### Rate limit errors
+
+**Symptom:** `RateLimitError` or 429 HTTP status
+
+**Cause:** Too many requests to external APIs
+
+**Solutions:**
+1. Add NCBI API key for PubMed:
+   ```bash
+   NCBI_API_KEY=your-key-here
+   ```
+2. Wait and retry (rate limits reset)
+3. Reduce `MAX_ITERATIONS`
+
+### No search results
+
+**Symptom:** Empty results from searches
+
+**Possible causes:**
+- Network issues
+- External API downtime
+- Query too specific
+
+**Solutions:**
+1. Check internet connection
+2. Try a broader query
+3. Check API status:
+   - [PubMed Status](https://www.ncbi.nlm.nih.gov/Status/)
+   - [ClinicalTrials.gov](https://clinicaltrials.gov/)
+
+### HuggingFace 500/401 errors
+
+**Symptom:** Internal server errors or auth errors from HuggingFace
+
+**Cause:** Large models (70B+) are routed to unreliable third-party providers
+
+**Solution:** Use default model (Qwen 2.5 7B) which stays on HuggingFace native infrastructure. See CLAUDE.md for details.
+
+### OpenAI API errors
+
+**Symptom:** Authentication errors with OpenAI
+
+**Solutions:**
+1. Verify key is valid: https://platform.openai.com/api-keys
+2. Check for typos in `.env`
+3. Ensure no trailing whitespace
+4. Check quota: https://platform.openai.com/usage
+
+### Import errors
+
+**Symptom:** `ModuleNotFoundError` when running
+
+**Solution:**
+```bash
+# Always use uv run
+uv run python src/app.py
+
+# Not this
+python src/app.py  # Won't find dependencies
+```
+
+### ChromaDB errors
+
+**Symptom:** Embedding or vector store errors
+
+**Solutions:**
+```bash
+# Clear the database
+rm -rf ./chroma_db
+
+# Verify path is writable
+ls -la ./
+```
+
+## Development Issues
+
+### Pre-commit hook failures
+
+**Symptom:** Commits rejected by pre-commit
+
+**Solution:**
+```bash
+# Auto-fix formatting
+make format
+
+# Check manually
+make lint
+make typecheck
+```
+
+### Type checking errors
+
+**Symptom:** mypy errors on valid code
+
+**Solutions:**
+```bash
+# Update stubs
+uv add --dev types-package-name
+
+# Or add ignore comment (last resort)
+# type: ignore[error-code]
+```
+
+### Test failures
+
+**Symptom:** Tests pass locally but fail in CI
+
+**Possible causes:**
+- Environment differences
+- Async timing issues
+- Missing test data
+
+**Solutions:**
+```bash
+# Run exactly like CI
+make check
+
+# Run specific test with verbose output
+uv run pytest tests/unit/path/test_file.py -v -s
+```
+
+## UI Issues
+
+### Gradio not starting
+
+**Symptom:** Application exits immediately or port conflict
+
+**Solutions:**
+```bash
+# Check if port is in use
+lsof -i :7860
+
+# Kill existing process
+kill -9 $(lsof -t -i :7860)
+
+# Or use different port
+uv run python -c "import gradio; print(gradio.__version__)"
+```
+
+### MCP tools not appearing
+
+**Symptom:** Claude Desktop doesn't show DeepBoner tools
+
+**Solutions:**
+1. Verify URL: `http://localhost:7860/gradio_api/mcp/`
+2. Check Claude Desktop config syntax
+3. Restart Claude Desktop after config change
+4. Ensure DeepBoner is running
+
+## Deployment Issues
+
+### Docker build fails
+
+**Symptom:** Dockerfile build errors
+
+**Solutions:**
+```bash
+# Clean build
+docker build --no-cache -t deepboner .
+
+# Check disk space
+docker system df
+docker system prune
+```
+
+### Container exits immediately
+
+**Symptom:** Container starts and stops
+
+**Solution:**
+```bash
+# Check logs
+docker logs <container_id>
+
+# Run interactively
+docker run -it deepboner bash
+```
+
+### HuggingFace Spaces issues
+
+**Symptom:** Space fails to build or run
+
+**Solutions:**
+1. Check Spaces logs in HuggingFace UI
+2. Verify `requirements.txt` matches `pyproject.toml`
+3. Check secrets are set correctly
+
+## Getting More Help
+
+### Enable debug logging
+
+```bash
+LOG_LEVEL=DEBUG uv run python src/app.py
+```
+
+### Check system info
+
+```bash
+uv run python -c "
+import sys
+print(f'Python: {sys.version}')
+
+import src
+print(f'DeepBoner loaded')
+
+from src.utils.config import settings
+print(f'OpenAI key: {bool(settings.openai_api_key)}')
+print(f'HF key: {bool(settings.hf_token)}')
+"
+```
+
+### Report an issue
+
+If you can't resolve the issue:
+
+1. Search existing issues: https://github.com/The-Obstacle-Is-The-Way/DeepBoner/issues
+2. Create a new issue with:
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Environment info (Python version, OS)
+   - Relevant logs (redact API keys)
+
+## Related Documentation
+
+- [Installation Guide](installation.md)
+- [Configuration Guide](configuration.md)
+- [SECURITY.md](../../SECURITY.md)

docs/reference/configuration.md

@@ -0,0 +1,185 @@
+# Configuration Reference
+
+> **Last Updated**: 2025-12-06
+
+Complete reference for all configuration options in DeepBoner.
+
+## Configuration System
+
+DeepBoner uses [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) for configuration management.
+
+### Loading Order
+
+1. Default values in code (`src/utils/config.py`)
+2. `.env` file in project root
+3. Environment variables (highest priority)
+
+### Location
+
+```
+/home/user/DeepBoner/
+├── .env            # Your configuration (not in git)
+├── .env.example    # Template (in git)
+└── src/utils/config.py  # Settings class
+```
+
+## Settings Class
+
+```python
+from src.utils.config import settings
+
+# Access settings
+print(settings.max_iterations)
+print(settings.has_openai_key)
+```
+
+## Configuration Categories
+
+### LLM Configuration
+
+| Setting | Type | Default | Env Variable | Description |
+|---------|------|---------|--------------|-------------|
+| `llm_provider` | Literal["openai", "huggingface"] | `"openai"` | `LLM_PROVIDER` | LLM backend to use |
+| `openai_api_key` | str \| None | None | `OPENAI_API_KEY` | OpenAI API key |
+| `openai_model` | str | `"gpt-5"` | `OPENAI_MODEL` | OpenAI model name |
+| `huggingface_model` | str \| None | `"Qwen/Qwen2.5-7B-Instruct"` | `HUGGINGFACE_MODEL` | HuggingFace model |
+| `hf_token` | str \| None | None | `HF_TOKEN` | HuggingFace API token |
+
+### Embedding Configuration
+
+| Setting | Type | Default | Env Variable | Description |
+|---------|------|---------|--------------|-------------|
+| `openai_embedding_model` | str | `"text-embedding-3-small"` | `OPENAI_EMBEDDING_MODEL` | OpenAI embeddings model |
+| `local_embedding_model` | str | `"all-MiniLM-L6-v2"` | `LOCAL_EMBEDDING_MODEL` | Local sentence-transformers model |
+
+### External Services
+
+| Setting | Type | Default | Env Variable | Description |
+|---------|------|---------|--------------|-------------|
+| `ncbi_api_key` | str \| None | None | `NCBI_API_KEY` | NCBI API key for PubMed |
+| `chroma_db_path` | str | `"./chroma_db"` | `CHROMA_DB_PATH` | ChromaDB storage path |
+
+### Agent Configuration
+
+| Setting | Type | Default | Env Variable | Description |
+|---------|------|---------|--------------|-------------|
+| `max_iterations` | int | 10 | `MAX_ITERATIONS` | Max search-judge iterations (1-50) |
+| `advanced_max_rounds` | int | 5 | `ADVANCED_MAX_ROUNDS` | Max multi-agent rounds (1-20) |
+| `advanced_timeout` | float | 600.0 | `ADVANCED_TIMEOUT` | Advanced mode timeout seconds (60-900) |
+| `search_timeout` | int | 30 | `SEARCH_TIMEOUT` | Per-search timeout seconds |
+
+### Domain Configuration
+
+| Setting | Type | Default | Env Variable | Description |
+|---------|------|---------|--------------|-------------|
+| `research_domain` | ResearchDomain | `SEXUAL_HEALTH` | `RESEARCH_DOMAIN` | Research domain focus |
+
+### Logging
+
+| Setting | Type | Default | Env Variable | Description |
+|---------|------|---------|--------------|-------------|
+| `log_level` | Literal["DEBUG", "INFO", "WARNING", "ERROR"] | `"INFO"` | `LOG_LEVEL` | Logging verbosity |
+
+## Helper Properties
+
+The Settings class provides convenience properties:
+
+```python
+settings.has_openai_key      # bool - Is OpenAI key set?
+settings.has_huggingface_key # bool - Is HF token set?
+settings.has_any_llm_key     # bool - Any LLM key available?
+```
+
+## Helper Methods
+
+```python
+# Get API key for configured provider
+api_key = settings.get_api_key()
+
+# Get OpenAI key (raises ConfigurationError if not set)
+openai_key = settings.get_openai_api_key()
+```
+
+## Backend Selection Logic
+
+```python
+# Automatic backend selection
+if settings.has_openai_key:
+    # Use OpenAI GPT-5
+    client = OpenAIChatClient(api_key=settings.openai_api_key)
+else:
+    # Use HuggingFace free tier
+    client = HuggingFaceChatClient(model=settings.huggingface_model)
+```
+
+## Validation
+
+Settings are validated on load:
+
+```python
+# These will raise ValidationError
+Settings(max_iterations=100)   # Must be 1-50
+Settings(log_level="TRACE")    # Invalid level
+Settings(advanced_timeout=10)  # Minimum is 60
+```
+
+## Example Configurations
+
+### Minimal (Free Tier)
+
+```bash
+# .env
+LOG_LEVEL=INFO
+MAX_ITERATIONS=5
+```
+
+### Development
+
+```bash
+# .env
+LOG_LEVEL=DEBUG
+MAX_ITERATIONS=3
+SEARCH_TIMEOUT=15
+```
+
+### Production (Premium)
+
+```bash
+# .env
+OPENAI_API_KEY=sk-...
+NCBI_API_KEY=...
+LOG_LEVEL=WARNING
+MAX_ITERATIONS=10
+ADVANCED_TIMEOUT=300
+CHROMA_DB_PATH=/data/chroma
+```
+
+### HuggingFace Spaces
+
+Set as Secrets (not Variables) in Space Settings:
+
+```
+HF_TOKEN=hf_...
+NCBI_API_KEY=...
+```
+
+## Programmatic Configuration
+
+Override settings in code (useful for testing):
+
+```python
+from src.utils.config import Settings
+
+# Create with overrides
+test_settings = Settings(
+    max_iterations=3,
+    log_level="DEBUG",
+    _env_file=None  # Ignore .env
+)
+```
+
+## Related Documentation
+
+- [Environment Variables](environment-variables.md)
+- [Getting Started - Configuration](../getting-started/configuration.md)
+- [Troubleshooting](../getting-started/troubleshooting.md)

docs/reference/environment-variables.md

@@ -0,0 +1,284 @@
+# Environment Variables Reference
+
+> **Last Updated**: 2025-12-06
+
+Complete reference for all environment variables used by DeepBoner.
+
+## Quick Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `OPENAI_API_KEY` | No* | - | OpenAI API key |
+| `HF_TOKEN` | No | - | HuggingFace token |
+| `NCBI_API_KEY` | No | - | NCBI/PubMed API key |
+| `LLM_PROVIDER` | No | `openai` | LLM backend |
+| `MAX_ITERATIONS` | No | `10` | Max search iterations |
+| `LOG_LEVEL` | No | `INFO` | Logging level |
+
+*At least one of OPENAI_API_KEY or HF_TOKEN is needed for full functionality.
+
+## LLM Configuration
+
+### OPENAI_API_KEY
+
+OpenAI API key for premium features.
+
+```bash
+OPENAI_API_KEY=sk-proj-xxxx
+```
+
+- **Format:** Starts with `sk-` or `sk-proj-`
+- **Source:** https://platform.openai.com/api-keys
+- **Effect:** Enables OpenAI GPT-5 as the LLM backend
+
+### ANTHROPIC_API_KEY
+
+Anthropic API key (reserved for future use).
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-xxxx
+```
+
+### LLM_PROVIDER
+
+Explicitly select LLM provider.
+
+```bash
+LLM_PROVIDER=openai    # Use OpenAI
+LLM_PROVIDER=huggingface  # Use HuggingFace
+```
+
+- **Default:** `openai`
+- **Note:** Auto-detection uses OPENAI_API_KEY presence
+
+### OPENAI_MODEL
+
+OpenAI model name.
+
+```bash
+OPENAI_MODEL=gpt-5
+OPENAI_MODEL=gpt-4o
+```
+
+- **Default:** `gpt-5`
+
+### HUGGINGFACE_MODEL
+
+HuggingFace model for free tier.
+
+```bash
+HUGGINGFACE_MODEL=Qwen/Qwen2.5-7B-Instruct
+```
+
+- **Default:** `Qwen/Qwen2.5-7B-Instruct`
+- **Warning:** Large models (70B+) route to unreliable third-party providers
+
+### HF_TOKEN
+
+HuggingFace API token.
+
+```bash
+HF_TOKEN=hf_xxxx
+```
+
+- **Source:** https://huggingface.co/settings/tokens
+- **Effect:** Enables gated models and higher rate limits
+
+## Embedding Configuration
+
+### OPENAI_EMBEDDING_MODEL
+
+OpenAI embedding model for premium RAG.
+
+```bash
+OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+OPENAI_EMBEDDING_MODEL=text-embedding-3-large
+```
+
+- **Default:** `text-embedding-3-small`
+- **Requires:** `OPENAI_API_KEY`
+
+### LOCAL_EMBEDDING_MODEL
+
+Local sentence-transformers model.
+
+```bash
+LOCAL_EMBEDDING_MODEL=all-MiniLM-L6-v2
+LOCAL_EMBEDDING_MODEL=all-mpnet-base-v2
+```
+
+- **Default:** `all-MiniLM-L6-v2`
+- **Note:** Downloaded on first use
+
+## External Services
+
+### NCBI_API_KEY
+
+NCBI API key for higher PubMed rate limits.
+
+```bash
+NCBI_API_KEY=xxxx
+```
+
+- **Source:** https://www.ncbi.nlm.nih.gov/account/settings/
+- **Effect:** 10 requests/second instead of 3
+
+### CHROMA_DB_PATH
+
+ChromaDB storage location.
+
+```bash
+CHROMA_DB_PATH=./chroma_db
+CHROMA_DB_PATH=/data/vectors
+```
+
+- **Default:** `./chroma_db`
+- **Note:** Directory is created if it doesn't exist
+
+## Agent Configuration
+
+### MAX_ITERATIONS
+
+Maximum search-judge loop iterations.
+
+```bash
+MAX_ITERATIONS=10
+MAX_ITERATIONS=5   # Faster but less thorough
+MAX_ITERATIONS=20  # More thorough
+```
+
+- **Default:** `10`
+- **Range:** `1` to `50`
+
+### ADVANCED_MAX_ROUNDS
+
+Maximum multi-agent coordination rounds.
+
+```bash
+ADVANCED_MAX_ROUNDS=5
+```
+
+- **Default:** `5`
+- **Range:** `1` to `20`
+
+### ADVANCED_TIMEOUT
+
+Timeout for advanced mode in seconds.
+
+```bash
+ADVANCED_TIMEOUT=600   # 10 minutes
+ADVANCED_TIMEOUT=300   # 5 minutes
+```
+
+- **Default:** `600.0`
+- **Range:** `60.0` to `900.0`
+
+### SEARCH_TIMEOUT
+
+Per-search operation timeout in seconds.
+
+```bash
+SEARCH_TIMEOUT=30
+```
+
+- **Default:** `30`
+
+## Logging
+
+### LOG_LEVEL
+
+Logging verbosity.
+
+```bash
+LOG_LEVEL=DEBUG    # Verbose
+LOG_LEVEL=INFO     # Normal
+LOG_LEVEL=WARNING  # Errors and warnings
+LOG_LEVEL=ERROR    # Errors only
+```
+
+- **Default:** `INFO`
+
+## Gradio Configuration
+
+### GRADIO_SERVER_NAME
+
+Server bind address.
+
+```bash
+GRADIO_SERVER_NAME=0.0.0.0  # All interfaces
+GRADIO_SERVER_NAME=127.0.0.1  # Localhost only
+```
+
+- **Default:** Set in Dockerfile for containers
+
+### GRADIO_SERVER_PORT
+
+Server port.
+
+```bash
+GRADIO_SERVER_PORT=7860
+```
+
+- **Default:** `7860`
+
+## Python Configuration
+
+### PYTHONPATH
+
+Python module search path.
+
+```bash
+PYTHONPATH=/app
+```
+
+- **Note:** Set automatically in Docker
+
+## .env File Format
+
+```bash
+# Comments start with #
+KEY=value           # No quotes needed for simple values
+KEY="value"         # Quotes for values with spaces
+KEY='value'         # Single quotes also work
+
+# Empty lines are ignored
+
+# Multi-line values not supported - use single line
+```
+
+## Security Notes
+
+1. **Never commit .env files** - They're in .gitignore
+2. **Use secrets for production** - HuggingFace Secrets, Docker secrets
+3. **Rotate keys regularly** - Especially for production
+4. **Limit permissions** - Use read-only keys where possible
+
+## Validation
+
+Variables are validated on application startup:
+
+```python
+# Invalid values raise ValidationError
+MAX_ITERATIONS=100  # Error: must be 1-50
+LOG_LEVEL=TRACE     # Error: invalid level
+```
+
+## Debugging
+
+Check loaded configuration:
+
+```bash
+LOG_LEVEL=DEBUG uv run python -c "
+from src.utils.config import settings
+print(f'Provider: {settings.llm_provider}')
+print(f'Has OpenAI: {settings.has_openai_key}')
+print(f'Has HF: {settings.has_huggingface_key}')
+print(f'Max Iterations: {settings.max_iterations}')
+"
+```
+
+## Related Documentation
+
+- [Configuration Reference](configuration.md)
+- [Getting Started - Configuration](../getting-started/configuration.md)
+- [Deployment - Docker](../deployment/docker.md)

docs/technical-debt/debt-registry.md

@@ -0,0 +1,409 @@
+# Technical Debt Registry
+
+> **Last Updated**: 2025-12-06
+
+This document tracks all known technical debt items in the DeepBoner codebase.
+
+## Summary Dashboard
+
+| Category | Open | In Progress | Resolved |
+|----------|------|-------------|----------|
+| Architecture | 3 | 0 | 0 |
+| Code Quality | 4 | 0 | 0 |
+| Testing | 2 | 0 | 0 |
+| Documentation | 2 | 0 | 0 |
+| Performance | 2 | 0 | 0 |
+| Dependencies | 1 | 0 | 0 |
+| **Total** | **14** | **0** | **0** |
+
+---
+
+## Architecture
+
+### DEBT-001: Duplicate Agent Guide Files
+
+**Category:** Architecture
+**Severity:** Low
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+CLAUDE.md, AGENTS.md, and GEMINI.md contain ~95% identical content. This violates DRY (Don't Repeat Yourself) and makes maintenance difficult.
+
+**Impact:**
+- Changes must be made in 3 places
+- Risk of documentation drift
+- Confusion about which file is canonical
+
+**Current Workaround:**
+Manual synchronization when updating.
+
+**Proposed Solution:**
+1. Keep CLAUDE.md as the canonical reference
+2. Make AGENTS.md and GEMINI.md symlinks or include-references
+3. Or consolidate into single DEVELOPMENT.md
+
+**Effort Estimate:** S
+
+---
+
+### DEBT-002: Reserved but Empty Directories
+
+**Category:** Architecture
+**Severity:** Low
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+`src/database_services/` and `src/retrieval_factory/` exist but are empty placeholders for future features.
+
+**Impact:**
+- Confusion about project structure
+- Empty imports may cause issues
+
+**Current Workaround:**
+Document as "reserved" in component inventory.
+
+**Proposed Solution:**
+Either implement the features or remove the directories.
+
+**Effort Estimate:** S
+
+---
+
+### DEBT-003: Experimental LangGraph Orchestrator
+
+**Category:** Architecture
+**Severity:** Medium
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+`src/orchestrators/langgraph_orchestrator.py` is marked as experimental and may not be fully tested or integrated.
+
+**Impact:**
+- Unclear which orchestrator is preferred
+- May have untested edge cases
+- Maintenance burden of two orchestrators
+
+**Current Workaround:**
+Default to AdvancedOrchestrator in production.
+
+**Proposed Solution:**
+Either promote to production status with full testing, or deprecate and remove.
+
+**Effort Estimate:** M
+
+---
+
+## Code Quality
+
+### DEBT-004: Complex Orchestrator Logic
+
+**Category:** Code Quality
+**Severity:** Medium
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+`src/orchestrators/advanced.py` has complex branching logic that required disabling pylint rules (PLR0912, PLR0913).
+
+**Impact:**
+- Difficult to understand and maintain
+- Higher bug risk
+- Harder to test comprehensively
+
+**Current Workaround:**
+Suppressed linter warnings with explicit ignores.
+
+**Proposed Solution:**
+Refactor into smaller, focused methods. Consider command pattern for orchestration steps.
+
+**Effort Estimate:** L
+
+---
+
+### DEBT-005: Magic Numbers in Code
+
+**Category:** Code Quality
+**Severity:** Low
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+Some statistical constants and thresholds are hardcoded (e.g., p-values, score thresholds), requiring PLR2004 ignore.
+
+**Impact:**
+- Difficult to tune parameters
+- Magic numbers obscure intent
+
+**Current Workaround:**
+Documented with comments where used.
+
+**Proposed Solution:**
+Move to configuration or constants module with documentation.
+
+**Effort Estimate:** S
+
+---
+
+### DEBT-006: Global Singleton Pattern
+
+**Category:** Code Quality
+**Severity:** Low
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+Settings uses a singleton pattern (`settings = get_settings()`), requiring PLW0603 ignore.
+
+**Impact:**
+- Harder to test with different configurations
+- Global state can cause issues
+
+**Current Workaround:**
+Test fixtures override settings.
+
+**Proposed Solution:**
+Consider dependency injection for settings, especially in tests.
+
+**Effort Estimate:** M
+
+---
+
+### DEBT-007: ClinicalTrials Uses requests Instead of httpx
+
+**Category:** Code Quality
+**Severity:** Low
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+`src/tools/clinicaltrials.py` uses `requests` library while rest of codebase uses `httpx` because ClinicalTrials.gov WAF blocks httpx.
+
+**Impact:**
+- Inconsistent HTTP client usage
+- Two libraries for same purpose
+
+**Current Workaround:**
+Documented in code comments and pyproject.toml.
+
+**Proposed Solution:**
+1. Investigate httpx headers/options that work with WAF
+2. Or accept this as necessary divergence and document
+
+**Effort Estimate:** M
+
+---
+
+## Testing
+
+### DEBT-008: Integration Tests Require Real APIs
+
+**Category:** Testing
+**Severity:** Medium
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+Integration tests marked with `@pytest.mark.integration` make real API calls, which can be slow and flaky.
+
+**Impact:**
+- Slow CI runs
+- Flaky tests due to network issues
+- Rate limit risks
+
+**Current Workaround:**
+Integration tests are not run in CI by default.
+
+**Proposed Solution:**
+1. Use VCR-style recording for reproducible tests
+2. Set up isolated test environment
+3. Better mock infrastructure for external APIs
+
+**Effort Estimate:** L
+
+---
+
+### DEBT-009: Incomplete E2E Test Coverage
+
+**Category:** Testing
+**Severity:** Medium
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+End-to-end tests exist but don't cover all user scenarios, especially error paths.
+
+**Impact:**
+- Production bugs may not be caught in testing
+- Edge cases untested
+
+**Current Workaround:**
+Manual testing before releases.
+
+**Proposed Solution:**
+Expand E2E test suite with more scenarios, especially:
+- Error handling
+- Rate limit recovery
+- Multiple iterations
+
+**Effort Estimate:** L
+
+---
+
+## Documentation
+
+### DEBT-010: Outdated Inline Comments
+
+**Category:** Documentation
+**Severity:** Low
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+Some code comments may reference old architecture or removed features from rapid hackathon development.
+
+**Impact:**
+- Confusion when reading code
+- Comments don't match implementation
+
+**Current Workaround:**
+None - requires manual review.
+
+**Proposed Solution:**
+Systematic review of comments during code review process.
+
+**Effort Estimate:** M
+
+---
+
+### DEBT-011: Missing API Documentation
+
+**Category:** Documentation
+**Severity:** Low
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+No formal API documentation (e.g., Sphinx-generated) for public interfaces.
+
+**Impact:**
+- Developers must read source code
+- Hard to know public vs internal APIs
+
+**Current Workaround:**
+Docstrings in code serve as documentation.
+
+**Proposed Solution:**
+Consider generating API docs with Sphinx or mkdocs.
+
+**Effort Estimate:** M
+
+---
+
+## Performance
+
+### DEBT-012: Model Loading on First Request
+
+**Category:** Performance
+**Severity:** Low
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+Sentence-transformers model is loaded on first query, causing slow initial response.
+
+**Impact:**
+- First query takes 30+ seconds
+- Poor user experience on first use
+
+**Current Workaround:**
+Docker pre-downloads the model during build.
+
+**Proposed Solution:**
+1. Pre-warm model on application startup
+2. Or accept cold start with loading indicator
+
+**Effort Estimate:** S
+
+---
+
+### DEBT-013: No Connection Pooling
+
+**Category:** Performance
+**Severity:** Low
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+External API calls may not fully utilize connection pooling.
+
+**Impact:**
+- Slower requests due to connection overhead
+- Higher latency under load
+
+**Current Workaround:**
+httpx AsyncClient provides some pooling.
+
+**Proposed Solution:**
+Audit and optimize connection handling for external APIs.
+
+**Effort Estimate:** S
+
+---
+
+## Dependencies
+
+### DEBT-014: Pinned Beta Dependencies
+
+**Category:** Dependencies
+**Severity:** Medium
+**Added:** 2025-12-06
+**Status:** Open
+
+**Description:**
+`agent-framework-core==1.0.0b*` is a beta release, pinned to avoid breaking changes.
+
+**Impact:**
+- May miss bug fixes and improvements
+- Beta software may have stability issues
+
+**Current Workaround:**
+Version pinning with explicit documentation.
+
+**Proposed Solution:**
+1. Monitor for stable release
+2. Upgrade and test when 1.0.0 releases
+3. Add integration tests specific to agent framework
+
+**Effort Estimate:** M
+
+---
+
+## Resolved Items
+
+*No items resolved yet.*
+
+---
+
+## How to Update This Registry
+
+### Adding Items
+
+1. Create new section with next DEBT-XXX number
+2. Fill in all fields
+3. Update summary dashboard
+
+### Resolving Items
+
+1. Change status to "Resolved"
+2. Add resolution notes
+3. Move to "Resolved Items" section
+4. Update summary dashboard
+
+### Review Schedule
+
+- Weekly: Triage new items
+- Sprint: Plan debt reduction
+- Monthly: Review progress

docs/technical-debt/index.md

@@ -0,0 +1,106 @@
+# Technical Debt Overview
+
+> **Last Updated**: 2025-12-06
+
+This directory tracks technical debt, known issues, and areas for improvement in the DeepBoner codebase.
+
+## What is Technical Debt?
+
+Technical debt is the implied cost of future work caused by choosing an easy (but limited) solution now instead of a better approach that would take longer. Like financial debt, it accumulates interest over time.
+
+## Documentation Structure
+
+```
+technical-debt/
+├── index.md           # This file - overview and summary
+└── debt-registry.md   # Itemized debt tracking
+```
+
+## Current Debt Summary
+
+| Category | Count | Severity |
+|----------|-------|----------|
+| Architecture | 3 | Medium |
+| Code Quality | 4 | Low |
+| Testing | 2 | Medium |
+| Documentation | 2 | Low |
+| Performance | 2 | Low |
+| Dependencies | 1 | Medium |
+
+**Total Items:** 14
+
+## Severity Levels
+
+| Level | Description | Action |
+|-------|-------------|--------|
+| **Critical** | Blocks production or security risk | Fix immediately |
+| **High** | Significant impact on reliability | Fix this sprint |
+| **Medium** | Impacts developer experience | Plan for fix |
+| **Low** | Nice to have improvement | Backlog |
+
+## How to Use This Documentation
+
+### For Developers
+
+1. Before starting work, check if your area has known debt
+2. When you encounter issues, document them here
+3. When fixing debt, update the registry
+
+### For Planning
+
+1. Review debt before sprint planning
+2. Allocate capacity for debt reduction
+3. Prioritize by severity and effort
+
+### For New Contributors
+
+1. Read this to understand known limitations
+2. Don't be surprised by documented issues
+3. Consider fixing debt as a contribution
+
+## Adding New Debt Items
+
+Add to `debt-registry.md` using this format:
+
+```markdown
+### DEBT-XXX: Short Title
+
+**Category:** Architecture | Code Quality | Testing | Documentation | Performance | Dependencies
+**Severity:** Critical | High | Medium | Low
+**Added:** YYYY-MM-DD
+**Status:** Open | In Progress | Resolved
+
+**Description:**
+What is the issue?
+
+**Impact:**
+How does this affect the codebase/users?
+
+**Current Workaround:**
+How are we handling this now?
+
+**Proposed Solution:**
+How should we fix this?
+
+**Effort Estimate:** S | M | L | XL
+```
+
+## Debt Reduction Goals
+
+### Phase 1 (Current)
+- Document all known debt (this effort)
+- Prioritize by impact
+
+### Phase 2 (Near-term)
+- Address all High severity items
+- Reduce Medium items by 50%
+
+### Phase 3 (Long-term)
+- Clear all Medium and High items
+- Establish debt budget (no net increase)
+
+## Related Documentation
+
+- [Debt Registry](debt-registry.md) - Complete itemized list
+- [Bugs](../bugs/active-bugs.md) - Active bug tracking
+- [Contributing](../../CONTRIBUTING.md) - How to help