# 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