Skip to main content

Installation

Requirements​

  • Python 3.12+
  • uv (recommended) or pip
# Clone the repository
git clone https://github.com/Sahandfer/PatientHub.git
cd PatientHub

# Install dependencies
uv sync

# Activate the environment
source .venv/bin/activate

Install with pip​

# Clone the repository
git clone https://github.com/Sahandfer/PatientHub.git
cd PatientHub

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install
pip install -e .

Configuration​

Create a .env file in the project root:

Cloud Models​

OPENAI_API_KEY=<your API key>
OPENAI_BASE_URL=https://api.openai.com
Using Other Providers

PatientHub supports cloud and local models. See Configuration for details.

Local Models via vLLM​

PatientHub does not bundle torch or transformers — local inference runs via an external vLLM (or any OpenAI-compatible) server that PatientHub calls over HTTP via LOCAL_BASE_URL.

  1. Install vLLM on the serving machine (GPU recommended):
pip install -U vllm
  1. Serve a model with the OpenAI-compatible endpoint (example):
vllm serve Qwen/Qwen2.5-7B-Instruct --host 0.0.0.0 --port 8000
  1. Point PatientHub to the server in your .env:
LOCAL_BASE_URL=http://<SERVER_HOST>:8000/v1
LOCAL_API_KEY=EMPTY

Then set your config to use model_type=LOCAL and model_name to the model name exposed by your vLLM server.

Local Reranker Models via vLLM​

ConsistentMI can also use a local reranker served by vLLM's OpenAI-compatible /rerank endpoint.

  1. Start a reranker model with vLLM:
vllm serve BAAI/bge-reranker-v2-m3 --host 0.0.0.0 --port 7891
  1. Point LOCAL_BASE_URL at the reranker server:
LOCAL_BASE_URL=http://127.0.0.1:7891/v1
LOCAL_API_KEY=EMPTY
  1. Use the LiteLLM vLLM route in ConsistentMI:
client:
  agent_name: consistentMI
  reranker_model_type: LOCAL
  reranker_model_name: hosted_vllm/BAAI/bge-reranker-v2-m3
Localhost vs 0.0.0.0

Use 0.0.0.0 for the server listen address, but use 127.0.0.1 or the machine's real IP in LOCAL_BASE_URL.

Proxy settings

If your shell exports http_proxy or https_proxy, local requests to the reranker can be sent to the proxy instead of your vLLM server. For local testing, either unset those variables or set:

export NO_PROXY=127.0.0.1,localhost
vLLM fails to start

it’s usually a CUDA/driver mismatch on the serving machine—check your NVIDIA driver/CUDA runtime and use a vLLM version compatible with your environment.

Verify Installation​

uv run python -c "from patienthub.clients import CLIENT_REGISTRY; print(list(CLIENT_REGISTRY.keys()))"

You should see a list of available client agents:

['patientPsi', 'roleplayDoh', 'eeyore', 'psyche', 'simPatient', 'consistentMI', ...]

Optional: Web Demo Dependencies​

To run the Chainlit web demo:

# Chainlit is already included in dependencies
chainlit run app.py

Troubleshooting​

Common Issues​

API Key not found: Make sure your .env file is in the project root and contains valid credentials.

Module not found: Ensure you've activated the virtual environment:

source .venv/bin/activate