BioAnalyzer Package

Extracts five core BugSigDB curation fields from scientific papers using LLMs, plus ontology mappings (NCBITaxon/UBERON/EFO) for the three that have one. Pulls metadata and full text from PubMed/PMC, then analyzes papers to determine if they're ready for curation.

Works on Ubuntu with Docker. Python 3.8+ for local installs.

Full documentation: docs/

What It Does

Takes a PMID, fetches the paper from PubMed, and extracts:

1. Host Species (Human, Mouse, etc.) — mapped to NCBITaxon
2. Body Site (Gut, Oral, Skin, etc.) — mapped to UBERON
3. Condition (disease/treatment being studied) — mapped to EFO
4. Sequencing Type (16S, metagenomics, etc.)
5. Sample Size (number of samples/participants)

...plus whether the paper reports differential abundance and whether it's already in BugSigDB. Each field's PRESENT/PARTIALLY_PRESENT/ABSENT status, confidence, and ontology-mapping tier (auto-applied vs. needs curator review) are computed internally and used to build the curator-facing output; see docs/CURATOR_DESK_CSV_FORMAT.md for the exact export format.

Quick Start

Prerequisites

• Docker 20.0+ (recommended) or Python 3.8+
• NCBI API key (required)
• At least one LLM API key: Gemini (easiest), OpenAI, Anthropic, or Ollama (local)

Docker (Recommended)

git clone https://github.com/waldronlab/bioanalyzer-backend.git
cd BioAnalyzer-Backend

chmod +x install.sh
./install.sh

BioAnalyzer build
BioAnalyzer start
BioAnalyzer status   # confirm running

API docs at http://localhost:8000/docs when the API is running.

Custom API host/port (no hardcoded localhost)

The CLI and dev/ops scripts read the API URL from BIOANALYZER_API_URL.

You can set it to either the root URL (recommended) or the /api/v1 base:

# Root URL
export BIOANALYZER_API_URL="http://127.0.0.1:8001"

# Or /api/v1 base
export BIOANALYZER_API_URL="http://127.0.0.1:8001/api/v1"

Local Install

git clone https://github.com/waldronlab/bioanalyzer-backend.git
cd BioAnalyzer-Backend

python3 -m venv .venv
source .venv/bin/activate

pip install -e .

# Set API keys
export NCBI_API_KEY=your_key
export GEMINI_API_KEY=your_key

Usage

CLI

# Analyze a paper
BioAnalyzer analyze 12345678

# Batch analysis
BioAnalyzer analyze 12345678,87654321
BioAnalyzer analyze --file pmids.txt

# Retrieve paper data
BioAnalyzer retrieve 12345678

# System management
BioAnalyzer start
BioAnalyzer stop
BioAnalyzer status

# Curator table (sortable/searchable predictions)
BioAnalyzer run table

API

v1 (simple, fast):

curl http://localhost:8000/api/v1/analyze/12345678

v2 (RAG-enhanced, more accurate):

curl "http://localhost:8000/api/v2/analyze/12345678?use_rag=true"

v2 uses RAG to improve accuracy but costs more API calls. Use v1 for quick checks, v2 when you need better results.

Configuration

Required

• NCBI_API_KEY - Get from NCBI account settings
• EMAIL - Contact email for NCBI requests

LLM Provider

Set one of:

• GEMINI_API_KEY - Google Gemini (recommended, cheapest)
• OPENAI_API_KEY - OpenAI
• ANTHROPIC_API_KEY - Anthropic
• OLLAMA_BASE_URL - Local Ollama (default: http://localhost:11434)

Auto-detects provider from available keys. Override with LLM_PROVIDER=gemini|openai|anthropic|ollama.

RAG Settings (v2 API)

# Fast (good for batch jobs)
export RAG_SUMMARY_QUALITY=fast
export RAG_RERANK_METHOD=keyword
export RAG_TOP_K_CHUNKS=5

# Balanced (default, good tradeoff)
export RAG_SUMMARY_QUALITY=balanced
export RAG_RERANK_METHOD=hybrid
export RAG_TOP_K_CHUNKS=10

# High accuracy (slower, more expensive)
export RAG_SUMMARY_QUALITY=high
export RAG_RERANK_METHOD=llm
export RAG_TOP_K_CHUNKS=20

Performance

• USE_FULLTEXT=true - Enable full text retrieval (slower but more accurate)
• API_TIMEOUT=30 - Request timeout in seconds
• CACHE_VALIDITY_HOURS=24 - How long to cache results

Architecture

Standard layered setup:

app/
├── api/          # FastAPI routes (v1 and v2)
├── services/     # Business logic
│   ├── data_retrieval.py      # PubMed fetching
│   ├── bugsigdb_analyzer.py   # Field extraction
│   ├── advanced_rag.py         # RAG pipeline
│   └── cache_manager.py       # SQLite cache
├── models/       # LLM wrappers
│   ├── llm_provider.py        # LiteLLM manager
│   └── unified_qa.py          # QA interface
└── utils/        # Helpers

Flow:

1. Fetch paper from PubMed (cached in SQLite)
2. Chunk text if full text available
3. For each field: query LLM (v1) or use RAG pipeline (v2)
4. Validate and score results
5. Cache and return

v2 adds chunk re-ranking and contextual summarization before querying the LLM. Worth the extra cost for better accuracy.

LLM Providers

Uses LiteLLM for provider abstraction. Supports:

• Gemini - Good balance of cost and quality
• OpenAI - Expensive but reliable
• Anthropic - Good for complex reasoning
• Ollama - Free but requires local setup
• Llamafile - Self-contained local models

Gemini is the default because it's cheap and works well for this use case.

Performance

• v1: ~2-5 seconds per paper, 10-20 papers/min
• v2: ~5-10 seconds per paper, 5-10 papers/min
• Memory: ~100-200MB base, +50MB per concurrent request
• Cache hit rate: 60-80% for frequently analyzed papers

Cache is SQLite-based, stored in cache/analysis_cache.db. Results valid for 24 hours by default.

Validation & Benchmarking

BioAnalyzer includes a formal validation workflow to compare automated predictions against expert curator annotations:

• Ground truth: Expert annotations in feedback.csv for the five core BugSigDB curation fields
• Predictions: BioAnalyzer outputs in a predictions CSV (e.g. analysis_results.csv or new.csv), already aligned by PMID with the ground-truth file (the align_pmids.py script this step used to reference no longer exists in the repo - align manually or write a one-off script for now)
• Evaluation: scripts/eval/confusion_matrix_analysis.py computes 3-class confusion matrices (ABSENT, PARTIALLY_PRESENT, PRESENT) and per-field accuracy
• Outputs: Metrics and PNG confusion matrices are written to confusion_matrix_results/

create_validation_dataset.py, previously used to flatten results into a Study, PMID, Experiment, Outcome of the experiment, Prediction CSV for the Deliverables/ folder, no longer exists in the repo either.

Development

# Install dev dependencies
pip install -e .[dev]

# Run tests
pytest

# Format code
black .

# Lint
flake8 .

Adding Features

• Services go in app/services/
• API routes in app/api/routers/
• CLI commands go in scripts/cli.py (root cli.py is just a backward-compat shim)
• API request/response models go in app/api/models/

See docs/DEVELOPER_GUIDE.md for extension workflows and docs/FOLDER_STRUCTURE.md for the full directory map. Contributing changes? See CONTRIBUTING.md.

Troubleshooting

Import errors:

• Use Docker, or ensure virtual environment is activated
• Check Python version (3.8+)

API not responding:

docker compose ps
docker compose logs

Missing API keys:

• Check .env file or environment variables
• System will warn but continue (with limited functionality)

Rate limiting:

• NCBI enforces 3 requests/second. We throttle automatically.
• LLM providers have their own limits. Check your quota.

Documentation

All documentation lives in the docs/ folder:

• docs/README.md – Index of all documentation
• Getting started: QUICKSTART, SETUP_GUIDE, QUICK_REFERENCE
• Architecture: ARCHITECTURE, ARCHITECTURE_FLOW
• CLI: CLI_DOCUMENTATION
• Features: RAG_GUIDE, CURATOR_TABLE_DESIGN, CURATOR_TABLE_USER_GUIDE
• Deployment: DOCKER_DEPLOYMENT, PRODUCTION_DEPLOYMENT
• Development: TESTING, DEVELOPER_GUIDE, FOLDER_STRUCTURE, CONTRIBUTING

When the API is running, interactive API docs: http://localhost:8000/docs

License

MIT License - see LICENSE file.