Bioinformatics Retrieval Augmented Digital (BRAD) Assistant

BRAD is a digital assistant designed to streamline bioinformatics workflows by leveraging the power of Large Language Models (LLMs). Built as a Python package, BRAD integrates computational tools, databases, and scientific literature into a unified system, enabling information retrieval and workflow automation. BRAD supports retrieval-augmented generation (RAG), database integration, executing external codes, and provides flexibility to integrate new tools. BRAD is a Python package and Graphical User Interface, and not dependent on a specific LLM.

Scope of this README

This README is intended as a quick reference for installing, setting up, and a few examples of the BRAD software. For additional information about this project, see the main page available here and for implementation and configuration details regarding how the software works, consult the software manual here.

System Requirements:

Any machine capable of running Docker should be able to run BRAD. This includes Windows, MAC, and Linux machines. BRAD was tested on the following operating systems:

• Windows 11 Enterprise, 22H2
• Ubuntu 22.04.4 LTS
• and several others

The GUI does not have significant compute requirements, and has been tested on systems with 16 GB of RAM. If a user installs the Python version or the development version of BRAD, the software dependencies can be installed from the below instructions. If a user wishes to run BRAD while running LLM inference locally, the user will require sufficient hardware and compute resources to run the LLM, separate from the dependencies of BRAD. The full list of softare dependencies used throughout this repository can be found here.

Quickstart

BRAD can be installed either as a Python package or through Docker. Follow the instructions below to get started.

Python Instillation

Brad can be installed directly from pip:

pip install -U BRAD-Chat

Python Quickstart

Once installed, you can verify the instillation worked with the following import:

from BRAD import agent

See the examples below for how to being using the package or the software manual for documentation of the installed package.

Docker Instillation

Download and install docker desktop and follow the instructions. Click on download docker and double click the .exe file on windows or .dmg file on mac to start the installation. You will have to restart the system to get docker desktop running.

Once installed, pull the latest BRAD docker image with the command:

docker pull thedoodler/brad:main

This will download the BRAD container image and prepare it for deployment. This instillation should take several minutes.

Docker Turn on

Start the BRAD container using the following command:

docker run -e OPENAI_API_KEY=<YOUR_OPENAI_API_KEY> \
           -e PYDANTIC_SKIP_VALIDATING_CORE_SCHEMAS='True' \
           -p 5002:5000 -p 3000:3000 \
           thedoodler/brad:main

Note: You may need to adjust how environment variables are specified to match your terminal's expectations.

Replace <YOUR_OPENAI_API_KEY> with your OpenAI API key. If using LLMs hosted by NVIDIA, you can include the NVIDIA API key as well:

docker run -e OPENAI_API_KEY=<YOUR_OPENAI_API_KEY> \
           -e NVIDIA_API_KEY=<YOUR_NVIDIA_API_KEY> \
           -e PYDANTIC_SKIP_VALIDATING_CORE_SCHEMAS='True' \
           -p 5002:5000 -p 3000:3000 \
           thedoodler/brad:main

Once the container is running, open your browser and navigate to http://localhost:3000 to access the BRAD GUI.

BRAD-Examples

• GUI Tutorial
  A simple tutorial for how to set up and use BRAD's Graphical User Interface.

• Hello World
  A simple "Hello, World!" example to help you understand the basics of using the BRAD chatbot.

• Search and Retrieval-Augmented Generation (RAG)
  Demonstrates how to use BRAD to scrape online data and integrate it into a Retrieval-Augmented Generation pipeline.

• Using the Scanpy Package with BRAD
  Explores how BRAD can streamline workflows involving Scanpy, including preprocessing and visualization of single-cell data.

• Biomarker Selection Pipeline
  Illustrates how BRAD can assist in selecting biomarkers from datasets using machine learning and bioinformatics tools.

• Video RAG BRAD operates as a RAG with a video database to interact with the past decade of Michigan Bioinformatics seminars

https://github.com/user-attachments/assets/293d7bf0-5e6b-4bcb-b62b-e4b8fd17e65f

Development Environment and Software Requirements

To contribute or modify BRAD, you need to set up a development environment. Follow the detailed instructions below for both Python and GUI development.

Python Development Environment

1. Clone the Repository
   Download the BRAD repository from GitHub:

git clone https://github.com/Jpickard1/BRAD.git
cd BRAD

2. Configure Settings
   Update the configuration file located at ./BRAD/config/config.json to match your preferences. Specifically, update the log_path key to point to a directory on your local system for storing logs.

    "log_path": "/usr/src/brad/logs",                       // Replace this line

3. Set up Python Environment (optional)
   Ensure Python 3.8 or higher is installed. For better isolation and to avoid dependency conflicts, use Conda to create a separate environment:

conda create -n brad-dev
conda activate brad-dev

Our recommendation is to use a self managed conda environment. environment.yml provides a template to build the environment, but package management may depend on different software requirements for new tools being integrated to BRAD.

4. Install Python Requirements
   Install all dependencies using the provided requirements file:

pip install -r requirements_frozen.txt

If additional dependencies are needed during development, remember to update this file after installation.

Note: This will install the requirements associated only with the Python package. It will not install the full set of software dependencies, which can be found here.

GUI Development

Follow these instructions to install the development version of BRAD's GUI:

1. Install NPM and Node.js
   BRAD's GUI requires Node.js version 20.18.0 and npm version 10.8.2. You can install these either:
   • Directly from the Node.js website
   • Or using nvm (recommended for managing multiple Node.js versions):

curl -o- https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash
source ~/.nvm/nvm.sh
nvm install 20.18.0
nvm use 20.18.0

Our recommendation is to use nvm:

https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash
source ~/.nvm/nvm.sh \
nvm install 20.18.0 \
nvm use 20.18.0

2. Install GUI Dependencies
   Navigate to the frontend directory and install required packages:

npm install --prefix ./brad-chat

3. Start the Backend
   Start BRAD backend with:

PYDANTIC_SKIP_VALIDATING_CORE_SCHEMAS=True \
OPENAI_API_KEY=<your_openai_api_key> \
NVIDIA_API_KEY=<your_nvidia_api_key> \            (optional)
flask --app app run --host=0.0.0.0 --port=5000

4. Start the Frontend
   Start BRAD frontend with

cd brad-chat
npm start

5. Access BRAD
   The above process will start BRAD with:

• Flask server at http://localhost:3000
• GUI at http://localhost:5000

Open a browser and navigate to http://localhost:5000 to view the GUI.

Docker

The Docker build can be used to deploy brad without having to install packages manually. After installing either docker desktop or docker engine docker intsallation, you can follow one of the following commands to install and run BRAD

1. Use with docker compose:

cd deployment
docker compose up -d

2. OR with just docker

docker run -e OPENAI_API_KEY=your_open_ai_key -e  PYDANTIC_SKIP_VALIDATING_CORE_SCHEMAS='True' -p 5001:5000 -p 3000:3000  brad:full_frontend

3. To build the dockerfile yourself:

docker build -t brad:local .

Then proceed to http://localhost:3000 to view the frontend

Documentation

To build the projects documentation in the ReadTheDocs html formatting, in the docs/ directory, run the command make html. This will populate the docs/build/html directory with the webpages. The docs/build/ directory is excluded from git but will automatically be built when pushing to main.

To remove the documentation from docs/build/ run make clean from the same directory where you built it.

Cite Us

@article{pickard2024language,
  title={Language Model Powered Digital Biology with BRAD},
  author={Pickard, Joshua and Prakash, Ram and Choi, Marc Andrew and Oliven, Natalie and
          Stansbury, Cooper and Cwycyshyn, Jillian
          and Gorodetsky, Alex and Velasquez, Alvaro and Rajapakse, Indika},
  journal={arXiv preprint arXiv:2409.02864},
  url={https://arxiv.org/abs/2409.02864},
  year={2024}
}