Quickstart

Prerequisites

Before you begin, ensure you have:

Python 3.10+

Download from python.org or use brew install [email protected]

OpenAI API Key

The AI Chat feature requires a Groq API key (free at console.groq.com). The rest of the system works with just OpenAI.

Installation

Clone the Repository

git clone <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 will download ~560MB for the spaCy language model. On macOS, you may see SSL certificate warnings — the app auto-patches this at startup.

Configure Environment Variables

cp .env.example .env
# Edit .env and add your API keys

Minimum required in .env:

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

Optional (for AI Chat):

GROQ_API_KEY=gsk_your-key-here

Start the Server

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

You should see:

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     ClinicalPilot starting up...
INFO:     Tracing enabled: True
INFO:     ClinicalPilot ready.

Your First Analysis

Web UI
cURL
Python SDK

Open the Frontend

Navigate to http://localhost:8000 in your browser.

Enter Clinical Data

In the Analysis tab, paste this example case:

45-year-old male presenting with acute chest pain radiating to left arm,
diaphoresis, and shortness of breath. History of hypertension and type 2
diabetes. Current medications: metformin 1000mg BID, lisinopril 20mg daily.

Run Analysis

Click Analyze. You’ll see real-time updates:

Parsing clinical input
Running Clinical Agent
Running Literature & Safety Agents
Critic Agent reviewing
Generating final SOAP note
Running medication safety panel

This takes ~100 seconds (14 LLM calls + external API lookups). Watch the WebSocket stream for progress.

Review Results

You’ll get:

Full SOAP Note (Subjective, Objective, Assessment, Plan)
Differential Diagnoses with confidence scores and ICD-10 codes
PubMed Citations (4-5 references)
Safety Alerts (drug interactions, dosing warnings)
Medical Error Panel (drug-drug interactions, contraindications)

Test Health Check

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

Expected response:

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

Run Full Analysis

curl -X POST http://localhost:8000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "text": "45-year-old male presenting with acute chest pain radiating to left arm, diaphoresis, and shortness of breath. History of hypertension and type 2 diabetes. Current medications: metformin 1000mg BID, lisinopril 20mg daily."
  }'

This will take ~100 seconds. You’ll receive a JSON response with:

soap: Full SOAP note structure
debate: Debate state with all agent outputs
med_error_panel: Safety alerts and drug interactions

Try Emergency Mode

For urgent cases, use the fast-path endpoint:

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

Returns in <5 seconds with:

ESI triage score
Top 3 differential diagnoses
Red flags
Immediate action items

import requests

# Full Analysis
response = requests.post(
    "http://localhost:8000/api/analyze",
    json={
        "text": """
        45-year-old male presenting with acute chest pain radiating to left arm,
        diaphoresis, and shortness of breath. History of hypertension and type 2
        diabetes. Current medications: metformin 1000mg BID, lisinopril 20mg daily.
        """
    },
    timeout=180  # Analysis takes ~100s
)

result = response.json()

# Extract SOAP note
soap = result["soap"]
print(f"Subjective: {soap['subjective']}")
print(f"Assessment: {len(soap['assessment'])} differentials")

# Extract safety alerts
med_panel = result["med_error_panel"]
print(f"Drug interactions: {len(med_panel['drug_interactions'])}")
print(f"Dosing alerts: {len(med_panel['dosing_alerts'])}")

# Emergency Mode (fast)
emergency_response = requests.post(
    "http://localhost:8000/api/emergency",
    json={"text": "Unconscious patient, no pulse, CPR in progress"},
    timeout=10
)

emergency = emergency_response.json()["emergency"]
print(f"ESI Score: {emergency['esi_score']}")
print(f"Red flags: {emergency['red_flags']}")

Understanding the Output

SOAP Note Structure

{
  "subjective": "Patient-reported symptoms and history...",
  "objective": "Clinical findings, vital signs, exam results...",
  "assessment": [
    {
      "diagnosis": "Acute Myocardial Infarction (STEMI)",
      "confidence": "high",
      "icd10": "I21.9",
      "reasoning": "Typical chest pain radiation, risk factors, urgent presentation"
    },
    {
      "diagnosis": "Unstable Angina",
      "confidence": "medium",
      "icd10": "I20.0",
      "reasoning": "Alternative if troponin negative"
    }
  ],
  "plan": "Immediate: STEMI protocol activation, ASA 325mg, O2...",
  "citations": [
    {
      "pmid": "33501848",
      "title": "2020 ESC Guidelines for ACS",
      "relevance": "STEMI management protocol"
    }
  ],
  "uncertainty": "Awaiting troponin, ECG confirmation needed",
  "model_used": "gpt-4o",
  "latency_ms": 102450
}

Medical Error Panel

{
  "drug_interactions": [
    {
      "drugs": ["Lisinopril", "Potassium"],
      "severity": "major",
      "mechanism": "ACE inhibitor + K supplement → hyperkalemia",
      "recommendation": "Monitor serum K+ closely"
    }
  ],
  "dosing_alerts": [
    {
      "drug": "Metformin",
      "alert": "Hold in acute coronary syndrome",
      "reasoning": "Lactic acidosis risk"
    }
  ],
  "population_flags": [
    {
      "population": "diabetes",
      "note": "2-3x increased cardiac mortality"
    }
  ]
}

Next Steps

Try Emergency Mode

Test the fast-path triage system for urgent cases — returns ESI scores and action items in <5 seconds.

Upload FHIR Data

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

Test AI Chat

Ask clinical questions via the /api/chat endpoint:

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

Check Drug Interactions

curl "http://localhost:8000/api/safety-check?drugs=metformin,lisinopril,aspirin"

WebSocket Streaming

For real-time progress updates, use the WebSocket endpoint:

const ws = new WebSocket('ws://localhost:8000/ws/analyze');

ws.onopen = () => {
  ws.send(JSON.stringify({
    text: "45-year-old male with acute chest pain..."
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  
  if (msg.type === 'status') {
    console.log(`Stage: ${msg.stage} - ${msg.detail}`);
  }
  
  if (msg.type === 'agent_result') {
    console.log(`${msg.agent} agent completed:`, msg.data);
  }
  
  if (msg.type === 'complete') {
    console.log('SOAP Note:', msg.soap);
    console.log('Safety Panel:', msg.med_error_panel);
    ws.close();
  }
};

Troubleshooting

ModuleNotFoundError: No module named 'backend'

Make sure you’re running from the project root:

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

SSL Certificate Errors (macOS)

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

/Applications/Python\ 3.12/Install\ Certificates.command

Analysis Takes Too Long / Times Out

The full pipeline makes 14 LLM calls and takes ~100 seconds. This is expected. For faster results:

Use Emergency Mode (/api/emergency) for <5s responses
Ensure your OpenAI API key has sufficient quota
Check your network latency to OpenAI servers

No GROQ_API_KEY - Chat endpoint returns 503

The AI Chat feature requires a Groq API key. Get one free at console.groq.com and add to .env:

GROQ_API_KEY=gsk_your-key-here

Alternatively, the chat endpoint now falls back to OpenAI if OPENAI_API_KEY is set.

SpaCy Model Download Fails

Install directly via pip instead of spacy download:

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

What’s Next?

Explore the Architecture

Learn how the multi-agent debate system works under the hood.Read Architecture Docs →

Configure Advanced Features

Set up LangSmith tracing, local LLMs with Ollama, and RAG customization.See Installation Guide →

API Reference

Dive into all available endpoints, request/response schemas, and WebSocket events.Browse API Docs →

You just ran your first multi-agent clinical analysis! The system generated differential diagnoses, searched PubMed for evidence, checked for drug interactions, and synthesized a complete SOAP note.

Get Started

Core Concepts

Guides

Prerequisites

Python 3.10+

OpenAI API Key

Installation

Your First Analysis

Understanding the Output

SOAP Note Structure

Medical Error Panel

Next Steps

Try Emergency Mode

Upload FHIR Data

Test AI Chat

Check Drug Interactions

WebSocket Streaming

Troubleshooting

What’s Next?

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Prerequisites

Python 3.10+

OpenAI API Key

​Installation

​Your First Analysis

​Understanding the Output

​SOAP Note Structure

​Medical Error Panel

​Next Steps

Try Emergency Mode

Upload FHIR Data

Test AI Chat

Check Drug Interactions

​WebSocket Streaming

​Troubleshooting

​What’s Next?

Build docs developers (and LLMs) love

Prerequisites

Installation

Your First Analysis

Understanding the Output

SOAP Note Structure

Medical Error Panel

Next Steps

WebSocket Streaming

Troubleshooting

What’s Next?