HemaGuide

Clinical decision support in hematological malignancies using a case-grounded AI agent.

Research Use Only – This software is intended for research purposes only. Generated decisions require validation by qualified medical professionals and must not be used for clinical care without proper oversight.

System Requirements

Developed and tested on Mac Studio M3 Ultra, 96GB RAM. We used Python 3.12.

Prerequisites

Install Python 3.12+ from python.org or via your package manager.

Quick Start

The fastest path is the bundled launcher:

1. Install Ollama
2. Clone the repository:

git clone https://github.com/Friedrich-Lab/HemaGuide

3. Double-click HemaGuide.command

It installs Python tools, pulls the required models, creates the virtual environment, starts the server, and opens the web interface at http://localhost:8000. The interface ships pre-built — no Node.js required. Double-click HemaGuide-Stop.command to stop it.

Processing cases also needs a .env file and a built knowledge base — see Step-by-step.

Step-by-step

1. Setup

python3 -m venv HemaGuide_venv             # Create virtual environment
source HemaGuide_venv/bin/activate         # Activate it
pip install -r requirements.txt             # Install dependencies

Create a .env file with:

# Required (at least one LLM provider)
OPENAI_API_KEY=sk-...        # OpenAI API
OLLAMA_API_KEY=...           # Ollama Cloud (if using --llm-mode ollama-cloud)

# Required for PubMed
PUBMED_EMAIL=your@email.com  # NCBI Entrez API requires valid email

# Optional
NCBI_API_KEY=...             # Increases PubMed rate limit (3 → 10 req/sec)
ONCOKB_API_KEY=...           # OncoKB API for molecular classification
CROSSREF_EMAIL=...           # CrossRef API (falls back to PUBMED_EMAIL)

The following step is mandatory as we calculate the embeddings ALWAYS locally.

For default mode local Ollama embeddings and --llm-mode ollama-local: Download Ollama from ollama.com and run it, then:

ollama pull embeddinggemma:300m             # Pull required models

Optional: COSMIC Data (for hotspot classification)

For enhanced molecular variant classification, download COSMIC data:

1. Register at COSMIC
2. Download from COSMIC Downloads:
   • File: Cosmic_CompleteTargetedScreensMutant_v103_GRCh38.tsv (~7GB)
3. Place in data/cosmic/:

mkdir -p data/cosmic
mv ~/Downloads/Cosmic_CompleteTargetedScreensMutant_v103_GRCh38.tsv data/cosmic/

Without this file, hotspot criteria will use the cancerhotspots.org API only.

2. CLI (run first to process data)

python build_kb.py              # Build knowledge base
python process_query_input.py   # Extract queries
python agent.py                 # Run agent

3. Backend

cd backend && python main.py

4. Frontend

cd frontend && npm install && npm run dev

Data Structure

kb_input/
└── tumorboards/
    └── *.docx          ← Clinical Case Memory cases

query_input/
└── *.docx              ← Query cases to process

results/
└── agent_decisions/
    └── *.json          ← Generated decisions (output)

Disclaimer

This software is provided as proof-of-concept for research purposes only and is not intended for clinical use.

• We do not ship non-public data (flowcharts, COSMIC data) and offer a prebuilt UI for demonstration (frontend/dist/)
• All patient documents must be de-identified before processing online
• Generated clinical decisions require validation by qualified medical professionals
• Not approved for production clinical decision-making
• Users are responsible for ensuring compliance with local regulations and institutional policies