docs/getting-started/installation.md

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)
• 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

# 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:

# 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:

# 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:

   cp .env.example .env
   

2. Edit .env with your settings:

   # 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 for all options.

Verify Installation

Run the quality checks to verify everything works:

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:

uv run python src/app.py

Open http://localhost:7860 in your browser.

Docker Installation

For containerized deployment:

# Build the image
docker build -t deepboner .

# Run the container
docker run -p 7860:7860 --env-file .env deepboner

See Docker Deployment for details.

Troubleshooting

Common Issues

uv not found

pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh

Python version mismatch

# Check your Python version
python --version

# Should be 3.11 or higher
# Use pyenv to manage versions if needed

Pre-commit hook failures

# Run formatting to fix most issues
make format

Import errors after install

# Ensure you're using uv run
uv run python -c "import src.app"

See Troubleshooting for more solutions.

Next Steps

• Quickstart Guide - Run your first query
• Configuration Guide - Configure all options
• Architecture Overview - Understand the system