Skip to main content

Overview

The /api/analyze endpoint runs the complete ClinicalPilot analysis pipeline:
  1. Anonymize — Remove PHI from input text
  2. Parse — Extract structured patient data
  3. Multi-Agent Debate — Clinical, Literature, Safety, and Critic agents collaborate
  4. Safety Panel — Parallel medication error prevention checks
  5. Synthesize — Generate final SOAP note with consensus
Expected latency: 15-30 seconds for complex cases

Endpoint

POST http://localhost:8000/api/analyze

Request Body

text
string
Free-text clinical input (chief complaint, history, exam findings, etc.)
fhir_bundle
object
FHIR R4 Bundle resource (alternative to text)
patient_context
PatientContext
Pre-parsed patient data (alternative to text or fhir_bundle)
You must provide one of: text, fhir_bundle, or patient_context

PatientContext Schema

Response

soap
SOAPNote
Final SOAP note with structured clinical output
debate
DebateState
Complete debate state with all agent outputs
med_error_panel
MedErrorPanel
Medication safety analysis results

SOAPNote Schema

MedErrorPanel Schema

Example Request

curl -X POST http://localhost:8000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "text": "65 yo M with PMH of HTN, DM2, CKD stage 3. Presents with 2 days of chest pain, worse with exertion. BP 145/92, HR 88. Troponin 0.08 (ref <0.04). On metformin 1000mg BID, lisinopril 20mg daily, aspirin 81mg daily."
  }'

Example Response

{
  "soap": {
    "subjective": "65-year-old male with history of hypertension, diabetes mellitus type 2, and chronic kidney disease stage 3 presents with 2 days of exertional chest pain.",
    "objective": "Vital signs: BP 145/92 mmHg, HR 88 bpm. Labs: Troponin 0.08 ng/mL (reference <0.04, elevated).",
    "assessment": "1. Acute coronary syndrome (ACS) — NSTEMI likely given elevated troponin and exertional chest pain.\n2. Hypertension — currently elevated, may contribute to cardiac stress.\n3. Diabetes mellitus type 2 — on metformin, increases cardiovascular risk.\n4. Chronic kidney disease stage 3 — requires contrast caution for imaging.",
    "plan": "1. Cardiology consult for urgent catheterization.\n2. Start dual antiplatelet therapy (aspirin already on, add clopidogrel 300mg load).\n3. Beta-blocker (metoprolol 25mg BID) if no contraindications.\n4. Statin (atorvastatin 80mg daily).\n5. Serial troponins, continuous telemetry.\n6. Hold metformin if contrast imaging planned (AKI risk).\n7. Admit to cardiac unit.",
    "differentials": [
      {
        "diagnosis": "Non-ST elevation myocardial infarction (NSTEMI)",
        "likelihood": "most likely",
        "reasoning": "Elevated troponin with exertional chest pain and cardiovascular risk factors.",
        "confidence": "high",
        "supporting_evidence": [
          "Troponin 0.08 ng/mL (elevated)",
          "Exertional chest pain pattern",
          "Multiple cardiovascular risk factors (HTN, DM2, CKD)"
        ]
      },
      {
        "diagnosis": "Unstable angina",
        "likelihood": "possible",
        "reasoning": "Could represent demand ischemia without infarction, though troponin elevation argues against this.",
        "confidence": "low",
        "supporting_evidence": []
      }
    ],
    "risk_scores": {
      "HEART Score": "6 — High risk (>50% chance of major adverse cardiac event)"
    },
    "uncertainty": "medium",
    "uncertainty_reasoning": "Troponin is elevated but not critically high. ECG findings not provided. Clinical picture consistent with ACS but requires further workup.",
    "citations": [
      "2020 ESC Guidelines for NSTEMI (PMID: 32860058)",
      "HEART Score validation study (PMID: 23465554)"
    ],
    "safety_flags": [
      "Metformin + CKD + possible contrast exposure = lactic acidosis risk. Hold metformin 48h before and after contrast."
    ],
    "debate_summary": "Clinical agent proposed NSTEMI diagnosis. Literature agent cited ESC guidelines supporting dual antiplatelet therapy. Safety agent flagged metformin-contrast interaction. Critic confirmed consensus.",
    "dissent_log": [],
    "model_used": "gpt-4o",
    "total_tokens": 12847,
    "latency_ms": 18230
  },
  "debate": {
    "round_number": 1,
    "clinical_outputs": [...],
    "literature_outputs": [...],
    "safety_outputs": [...],
    "critic_outputs": [...],
    "final_consensus": true,
    "flagged_for_human": false
  },
  "med_error_panel": {
    "drug_interactions": [],
    "contraindications": [
      {
        "drug": "metformin",
        "disease": "chronic kidney disease stage 3",
        "severity": "moderate",
        "description": "Metformin clearance reduced in CKD, increasing lactic acidosis risk.",
        "recommendation": "Use with caution. Contraindicated if eGFR <30. Hold 48h before contrast."
      }
    ],
    "dosing_alerts": [
      {
        "drug": "lisinopril",
        "alert_type": "renal",
        "description": "ACE inhibitors require dose adjustment in CKD stage 3.",
        "recommendation": "Monitor serum creatinine and potassium. Max dose 20mg daily in CKD stage 3."
      }
    ],
    "population_flags": [],
    "summary": "Moderate safety concerns identified. Primary issue: metformin use in CKD with potential contrast exposure. ACE inhibitor dose appropriate but requires monitoring."
  }
}

Error Responses

400 Bad Request

{
  "detail": "Must provide text, fhir_bundle, or patient_context"
}

500 Internal Server Error

{
  "detail": "Analysis failed: [error details]"
}

Notes

The analyze endpoint is compute-intensive and may take 15-30 seconds for complex cases. For time-critical triage, use the Emergency endpoint instead.
All input text is automatically anonymized before processing to remove PHI (Protected Health Information).

Build docs developers (and LLMs) love