Installation - ClinicalPilot

Prerequisites

Python 3.10+

Requiredpython.org or brew install [email protected]

Git 2.x+

Requiredbrew install git or git-scm.com

Ollama

OptionalOnly for local LLM (MedGemma)

Quick Install (5 Minutes)

Clone Repository

git clone <your-repo-url> clinicalpilot
cd clinicalpilot

Create Virtual Environment

python3 -m venv venv
source venv/bin/activate

Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

This downloads ~560MB for the spaCy language model. On some systems, spacy download fails — see troubleshooting below.

Install SpaCy Model

The PHI anonymization layer requires a spaCy language model. Install directly via pip:

pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_lg-3.7.1/en_core_web_lg-3.7.1-py3-none-any.whl

For a smaller model (~12MB vs 560MB), use en_core_web_sm and set SPACY_MODEL=en_core_web_sm in .env

Configure Environment

cp .env.example .env
# Edit .env with your API keys

Minimum required:

OPENAI_API_KEY=sk-your-key-here
NCBI_EMAIL=[email protected]

Run the Server

python -m uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

Open http://localhost:8000

Detailed Dependencies

Core Framework

fastapi==0.115.0
uvicorn[standard]==0.30.0
python-multipart==0.0.9
python-dotenv==1.0.1
pydantic==2.9.0
pydantic-settings==2.5.0
certifi  # macOS SSL fix

LLM & Agents

openai==1.50.0
groq>=0.9.0  # For AI Chat
langchain==0.3.0
langchain-openai==0.2.0
langchain-community==0.3.0

Vector DB & Embeddings

lancedb==0.13.0
sentence-transformers==3.1.0

LanceDB is embedded/serverless — no separate database server required. It auto-creates at data/lancedb/ on first run.

Document Parsing

PyPDF2==3.0.1
unstructured==0.15.0

PHI Anonymization

presidio-analyzer==2.2.355
presidio-anonymizer==2.2.355
spacy==3.7.0
# Then: pip install en_core_web_lg (see above)

External APIs

biopython==1.84  # PubMed E-utilities
httpx==0.27.0
aiohttp==3.10.0

Observability

langsmith==0.1.120

API Keys Setup

OpenAI (Required)

Get API Key

Go to platform.openai.com/api-keys
Create a new API key
Copy the key (starts with sk-)

Add to .env

OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o
OPENAI_FAST_MODEL=gpt-4o-mini

gpt-4o is used for Clinical, Safety, Critic, and Synthesizer agents
gpt-4o-mini is used for Literature agent (faster, cheaper)

Groq (Required for AI Chat)

Get API Key

Go to console.groq.com/keys
Create a free API key
Copy the key (starts with gsk_)

Add to .env

GROQ_API_KEY=gsk_your-key-here
GROQ_MODEL=llama-3.3-70b-versatile

Without this key, the /api/chat endpoint returns 503. The rest of the app works fine.

PubMed / NCBI (Recommended)

Go to ncbi.nlm.nih.gov/account
Create a free account
Navigate to Settings → API Key Management → Create API Key

Add to .env

NCBI_EMAIL=[email protected]
NCBI_API_KEY=your-key-here

Without an API key: PubMed limits you to 3 requests/secondWith an API key: 10 requests/second

LangSmith (Optional — Observability)

Go to smith.langchain.com
Sign up (free tier available)
Create an API key

Add to .env

LANGSMITH_API_KEY=lsv2_your-key-here
LANGCHAIN_TRACING_V2=true
LANGCHAIN_PROJECT=clinicalpilot

With LangSmith enabled, you get:

Real-time agent call tracing
Token usage per agent
Latency breakdown
Debate round visualization

FDA API (Optional)

Request Key

Go to open.fda.gov/apis/authentication
Request an API key (instant approval)

Add to .env

FDA_API_KEY=your-key-here

Works without a key but has lower rate limits (240 requests/minute vs 1000 with key).

Data Downloads

DrugBank Open Data (Optional)

Download

Go to go.drugbank.com/releases/latest#open-data
Create a free account
Download DrugBank Vocabulary CSV

Place in Data Directory

cp ~/Downloads/drugbank_vocabulary.csv data/drugbank/

If you skip this step, the system still works — it uses FDA API and RxNorm for safety checks instead. DrugBank adds offline drug name resolution.

Sample FHIR Data (Included)

The repo includes sample FHIR R4 bundles:

data/sample_fhir/
├── stemi_case.json
├── stroke_case.json
└── pe_case.json

To add your own:

# Export FHIR R4 Bundle JSON from your EHR
# Place in data/sample_fhir/
cp ~/Downloads/patient_bundle.json data/sample_fhir/

# Upload via API
curl -X POST http://localhost:8000/api/upload/fhir \
  -H "Content-Type: application/json" \
  -d @data/sample_fhir/patient_bundle.json

Local LLM Setup (Optional — MedGemma via Ollama)

Install Ollama

brew install ollama

Start Ollama Server

ollama serve
# Runs on http://localhost:11434 by default

Pull MedGemma Model

# ~5GB download, needs 16GB RAM
ollama pull medgemma2:9b

Configure .env

USE_LOCAL_LLM=true
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=medgemma2:9b

Fallback behavior: If Ollama is unreachable, the system automatically falls back to OpenAI.

LanceDB Initialization

LanceDB is serverless/embedded — no separate server needed.

Auto-Creation

The vector store auto-creates at data/lancedb/ on first run. No manual setup required.

Manual Initialization (Optional)

python -m backend.rag.lancedb_store --init

Add Custom Medical Documents

# Place PDF/TXT files in data/rag_documents/
mkdir -p data/rag_documents
cp ~/medical_papers/*.pdf data/rag_documents/

# Ingest into vector store
python -m backend.rag.lancedb_store --ingest data/rag_documents/

Running the Application

Development Mode

# With auto-reload on code changes
python -m uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

Production Mode

# Multi-worker for production
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000 --workers 4

Docker (Optional)

docker-compose up --build

Verification Checklist

After installation, verify everything works:

Health Check

curl http://localhost:8000/api/health

Expected:

{
  "status": "ok",
  "service": "clinicalpilot",
  "version": "1.0.0",
  "model": "gpt-4o",
  "local_llm": false
}

Test AI Chat

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "What are red flags for chest pain?"}]}'

Test Analysis Pipeline

curl -X POST http://localhost:8000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "45-year-old male with acute chest pain radiating to left arm, diaphoresis, SOB. Hx HTN, DM2. Meds: metformin 1000mg BID, lisinopril 20mg daily."}'

This takes ~100 seconds. Returns full SOAP note + debate state + safety panel.

Test Emergency Mode

curl -X POST http://localhost:8000/api/emergency \
  -H "Content-Type: application/json" \
  -d '{"text": "Unconscious, no pulse, CPR in progress"}'

Returns in <5 seconds with ESI score + differentials + red flags.

Check API Docs

Open http://localhost:8000/docs for interactive API documentation.

Troubleshooting

ModuleNotFoundError: No module named 'backend'

Ensure you’re running from the project root:

cd /path/to/clinicalpilot
python -m uvicorn backend.main:app --reload

Presidio / SpaCy Errors

Force reinstall and use direct pip install for the model:

pip install presidio-analyzer presidio-anonymizer --force-reinstall
pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_lg-3.7.1/en_core_web_lg-3.7.1-py3-none-any.whl

If issues persist, use the smaller model:

pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.7.1/en_core_web_sm-3.7.1-py3-none-any.whl
echo "SPACY_MODEL=en_core_web_sm" >> .env

macOS SSL Certificate Errors

The app auto-patches SSL using certifi. If you still see CERTIFICATE_VERIFY_FAILED:

# Option 1: Run macOS certificate installer (recommended)
/Applications/Python\ 3.12/Install\ Certificates.command

# Option 2: Reinstall certifi
pip install certifi --upgrade

LanceDB Import Errors

pip install lancedb --upgrade

OPENAI_API_KEY not set

cp .env.example .env
# Edit .env and add your OpenAI API key
nano .env

Port 8000 Already in Use

Find and kill the process:

lsof -ti:8000 | xargs kill -9

Or use a different port:

python -m uvicorn backend.main:app --reload --port 8001

Ollama Connection Refused

Make sure Ollama is running:

ollama serve
# Check it's accessible
curl http://localhost:11434/api/tags

Platform-Specific Notes

macOS (Apple Silicon)
macOS (Intel)
Linux
Windows

macOS M1/M2/M3

All dependencies work natively on Apple Silicon
Ollama runs natively with Metal acceleration
SpaCy large model may take a few minutes to download
SSL certificate fix: The app auto-patches using certifi, but you can also run:
```
/Applications/Python\ 3.12/Install\ Certificates.command
```

Ubuntu/Debian

Install system packages for PDF parsing:

sudo apt-get update
sudo apt-get install -y poppler-utils tesseract-ocr libmagic1

Environment Variables Reference

Variable	Required	Default	Description
`OPENAI_API_KEY`	Yes	-	OpenAI API key for GPT-4o/4o-mini
`OPENAI_MODEL`	No	`gpt-4o`	Model for main agents
`OPENAI_FAST_MODEL`	No	`gpt-4o-mini`	Model for Literature agent
`GROQ_API_KEY`	No*	-	Groq API key for AI Chat
`GROQ_MODEL`	No	`llama-3.3-70b-versatile`	Groq model name
`USE_LOCAL_LLM`	No	`false`	Use Ollama/MedGemma
`OLLAMA_BASE_URL`	No	`http://localhost:11434`	Ollama server URL
`OLLAMA_MODEL`	No	`medgemma2:9b`	Ollama model name
`NCBI_EMAIL`	Yes**	-	Email for PubMed API
`NCBI_API_KEY`	No	-	PubMed API key (10 req/s vs 3)
`LANGSMITH_API_KEY`	No	-	LangSmith tracing key
`LANGCHAIN_TRACING_V2`	No	`false`	Enable LangSmith tracing
`LANGCHAIN_PROJECT`	No	`clinicalpilot`	LangSmith project name
`FDA_API_KEY`	No	-	FDA API key (higher limits)
`LANCEDB_PATH`	No	`data/lancedb`	Vector store directory
`DRUGBANK_CSV_PATH`	No	`data/drugbank/drugbank_vocabulary.csv`	DrugBank data file
`SPACY_MODEL`	No	`en_core_web_lg`	SpaCy model for PHI detection
`LOG_LEVEL`	No	`INFO`	Logging level
`CORS_ORIGINS`	No	`["*"]`	CORS allowed origins
`EMERGENCY_TIMEOUT_SEC`	No	`5`	Emergency mode timeout
`MAX_DEBATE_ROUNDS`	No	`3`	Max debate iterations

* Required only for AI Chat feature** Required by NCBI for E-utilities access

Updating

To update ClinicalPilot:

git pull
pip install -r requirements.txt --upgrade
# Restart the server

Next Steps

Quickstart

Run your first SOAP note analysis in 5 minutes

Architecture

Learn how the multi-agent debate system works

API Reference

Explore all endpoints and schemas

Configuration

Advanced settings and customization

Get Started

Core Concepts

Guides

​Prerequisites

Python 3.10+

Git 2.x+

Ollama

​Quick Install (5 Minutes)

​Detailed Dependencies

​Core Framework

​LLM & Agents

​Vector DB & Embeddings

​Document Parsing

​PHI Anonymization

​External APIs

​Observability

​API Keys Setup

​OpenAI (Required)

​Groq (Required for AI Chat)

​PubMed / NCBI (Recommended)

​LangSmith (Optional — Observability)

​FDA API (Optional)

​Data Downloads

​DrugBank Open Data (Optional)

​Sample FHIR Data (Included)

​Local LLM Setup (Optional — MedGemma via Ollama)

​LanceDB Initialization

​Running the Application

​Development Mode

​Production Mode

​Docker (Optional)

​Verification Checklist

​Troubleshooting

​Platform-Specific Notes

​macOS M1/M2/M3

​macOS Intel

​Ubuntu/Debian

​Windows 10/11

​Environment Variables Reference

​Updating

​Next Steps

Quickstart

Architecture

API Reference

Configuration

Build docs developers (and LLMs) love

Prerequisites

Quick Install (5 Minutes)

Detailed Dependencies

Core Framework

LLM & Agents

Vector DB & Embeddings

Document Parsing

PHI Anonymization

External APIs

Observability

API Keys Setup

OpenAI (Required)

Groq (Required for AI Chat)

PubMed / NCBI (Recommended)

LangSmith (Optional — Observability)

FDA API (Optional)

Data Downloads

DrugBank Open Data (Optional)

Sample FHIR Data (Included)

Local LLM Setup (Optional — MedGemma via Ollama)

LanceDB Initialization

Running the Application

Development Mode

Production Mode

Docker (Optional)

Verification Checklist

Troubleshooting

Platform-Specific Notes

macOS M1/M2/M3

macOS Intel

Ubuntu/Debian

Windows 10/11

Environment Variables Reference

Updating

Next Steps