{"openapi":"3.0.3","info":{"title":"Maternal Intelligence — CDS Engine","description":"Tanzania STG 2021-grounded Clinical Decision Support REST API. Evaluates maternal and obstetric patient data in real time — scoring risk, firing guideline alerts, generating ICD-10 codes, and producing prioritised STG-referenced interventions. Covers maternal conditions plus SCD (Sickle Cell Disease) in pregnancy.\n\n**Built by Swahili Developers Tanzania (SDT)**\n\n**Clinical Reference:** Tanzania Standard Treatment Guidelines 2021 (STG 2021) + ANC 2018 Guidelines + WHO SCD in Pregnancy Guidelines.\n\n**Base URL (production):** `https://mama.swahilidevelopers.com`\n\n**Interactive demo:** [Hugging Face Space](https://huggingface.co/spaces/Japhari/maternal-clinical-decision-support-ai)","version":"1.0.0","contact":{"name":"Swahili Developers Tanzania","email":"japharimbaru@gmail.com","url":"https://swahilidevelopers.com"},"license":{"name":"MIT"}},"servers":[{"url":"https://mama.swahilidevelopers.com","description":"Production — mama.swahilidevelopers.com"},{"url":"http://localhost:4000","description":"Local development"}],"tags":[{"name":"Evaluation","description":"Core CDS evaluation endpoints — structured intake and free-text narrative"},{"name":"Patient","description":"Per-patient risk snapshot and longitudinal timeline"},{"name":"Explainability","description":"Plain-language explanation of an evaluation result"},{"name":"System","description":"Health check and service status"}],"paths":{"/cds/evaluate":{"post":{"tags":["Evaluation"],"summary":"Evaluate a structured patient payload","description":"The core CDS endpoint. Accepts a structured clinical payload, fires STG 2021 rules, scores 0–100 composite risk, maps an ICD-10 code, generates prioritised interventions, and appends the visit to the patient's longitudinal timeline.","operationId":"evaluatePatient","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateRequest"},"examples":{"preeclampsia":{"summary":"Pre-eclampsia with severe features at 34w","value":{"patientId":"P-PRE-001","condition":"preeclampsia","ga":34,"bpSyst":158,"bpDiast":102,"proteinuria":"++","headache":true,"visualDisturbance":true,"epigastricPain":false}},"severe_preeclampsia":{"summary":"Severe pre-eclampsia (BP ≥160/110) — MgSO4 indicated","value":{"patientId":"P-PRE-002","condition":"preeclampsia","ga":36,"bpSyst":172,"bpDiast":114,"proteinuria":"+++","headache":true,"visualDisturbance":true,"epigastricPain":true}},"postpartum_hemorrhage":{"summary":"Major PPH at delivery (blood loss ≥1000 ml)","value":{"patientId":"P-PPH-001","condition":"postpartum_hemorrhage","daysPostpartum":0,"bloodLoss":1200,"pulse":128,"systolicBP":88,"ongoingBleedingMinutes":20,"uterusTone":"soft"}},"pph_moderate":{"summary":"Moderate PPH (500–999 ml)","value":{"patientId":"P-PPH-002","condition":"postpartum_hemorrhage","daysPostpartum":0,"bloodLoss":650,"pulse":102,"systolicBP":98,"uterusTone":"soft"}},"sepsis":{"summary":"Puerperal sepsis day 5 postpartum","value":{"patientId":"P-SEP-001","condition":"sepsis","daysPostpartum":5,"temperature":38.9,"pulse":118,"systolicBP":86,"foulLochia":true}},"sepsis_early":{"summary":"Early sepsis indicators day 2","value":{"patientId":"P-SEP-002","condition":"sepsis","daysPostpartum":2,"temperature":38.2,"pulse":98,"systolicBP":105,"foulLochia":true}},"anaemia_severe":{"summary":"Severe anaemia (Hb < 7 g/dL)","value":{"patientId":"P-ANA-001","condition":"anaemia","ga":30,"hb":6.5}},"anaemia_moderate":{"summary":"Moderate anaemia (Hb 7–10.9 g/dL)","value":{"patientId":"P-ANA-002","condition":"anaemia","ga":22,"hb":9.2}},"gestational_diabetes":{"summary":"Gestational diabetes — elevated fasting glucose","value":{"patientId":"P-GDM-001","condition":"gestational_diabetes","ga":26,"glucoseTestDone":false,"glucoseFasting":5.6,"glucoseRandom":10.4}},"anc_routine":{"summary":"ANC routine visit — overdue IPTp and TT gaps","value":{"patientId":"P-ANC-001","condition":"anc_routine","ga":24,"lastIPTpWeek":18,"ttDoseCount":1,"dewormingGiven":false}},"pnc_routine":{"summary":"PNC routine visit day 4 with hypertension + depression screen","value":{"patientId":"P-PNC-001","condition":"pnc_routine","daysPostpartum":4,"pncVisitDone":false,"bpSyst":146,"bpDiast":94,"postnatalDepressionScore":12,"breastfeedingDifficulty":true}},"obstructed_labor":{"summary":"Obstructed labour — arrested descent + foetal distress","value":{"patientId":"P-OBL-001","condition":"obstructed_labor","ga":40,"laborDurationHours":18,"descentArrested":true,"foetalDistress":true,"moulding":3,"cervixDilation":8}},"maternal_default":{"summary":"Maternal default — general intake with borderline BP","value":{"patientId":"P-DEF-001","condition":"maternal_default","ga":28,"bpSyst":132,"bpDiast":86,"hb":10.8,"temperature":36.8}},"scd_acute_chest":{"summary":"SCD — acute chest syndrome with hypoxia","value":{"patientId":"TZ-SCD-001","condition":"SCD","temperature":39,"hb":4.5,"oxygenSat":90,"cough":true,"difficultyBreathing":true,"fever":true,"crisesPerYear":4,"strokeHistory":false,"admitted":true}},"scd_vaso_occlusive":{"summary":"SCD — vaso-occlusive crisis with fever","value":{"patientId":"TZ-SCD-002","condition":"SCD","temperature":38.5,"hb":6.2,"oxygenSat":96,"fever":true,"cough":false,"difficultyBreathing":false,"crisesPerYear":3,"strokeHistory":false,"admitted":true}},"scd_stroke_history":{"summary":"SCD — prior stroke, high-risk pregnancy","value":{"patientId":"TZ-SCD-003","condition":"SCD","temperature":37.2,"hb":7.8,"oxygenSat":97,"fever":false,"cough":false,"difficultyBreathing":false,"crisesPerYear":5,"strokeHistory":true,"admitted":false}}}}}},"responses":{"200":{"description":"Full CDS evaluation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateResponse"},"example":{"patientId":"P-PRE-001","condition":"preeclampsia","icd10":{"primary":"O14.9"},"icd10Code":"O14.9","icd10Reason":"Hypertension with proteinuria and symptoms at 34 weeks","alerts":[{"id":"PRE_ECLAMPSIA_SUSPECTED","severity":"critical","message":"Suspected pre-eclampsia. Start close BP and urine protein monitoring. Prepare for possible escalation.","stgRef":"STG 2021 11.7.3"},{"id":"HEADACHE_VISUAL_DISTURBANCE","severity":"high","message":"Neurological symptoms present. Rule out impending eclampsia.","stgRef":"STG 2021 11.7.4"}],"risk":{"level":"high","score":68,"factors":["hypertension","significant_proteinuria","rule_alerts_2"]},"interventions":[{"code":"PRE_ECLAMPSIA_SUSPECTED","priority":"critical","action":"Suspected pre-eclampsia. Start close BP and urine protein monitoring. Prepare for possible escalation.","reference":"STG 2021 11.7.3"},{"code":"REFERRAL_URGENT","priority":"emergency","action":"Initiate urgent referral with pre-referral stabilization, IV line, and referral note.","reference":"National Referral Guideline"}],"longitudinal":{"trend":"stable","carePlan":[]}}}}},"400":{"description":"Missing required field (patientId)","content":{"application/json":{"example":{"message":"patientId is required","status":400}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"example":{"message":"Unexpected error","status":500}}}}}}},"/cds/story":{"post":{"tags":["Evaluation"],"summary":"Free-text clinical narrative intake","description":"Submit a plain-language clinical narrative. The NLP parser extracts condition, vitals (BP, GA, Hb, blood loss, temperature), and symptom flags automatically, then runs the full CDS evaluation pipeline. Returns the raw story, extracted structured case, and full evaluation.","operationId":"storyIntake","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["story"],"properties":{"story":{"type":"string","description":"Plain-language clinical narrative","example":"32 year old woman 34 weeks pregnant BP 158/102 headache visual disturbance proteinuria ++"}}},"examples":{"preeclampsia_story":{"summary":"Pre-eclampsia narrative","value":{"story":"32 year old woman 34 weeks pregnant BP 158/102 headache visual disturbance proteinuria ++"}},"haemorrhage_story":{"summary":"PPH narrative","value":{"story":"Patient delivered 2 hours ago, estimated blood loss 1200ml, pulse 128, BP 88 systolic, uterus feels soft"}},"sepsis_story":{"summary":"Sepsis narrative","value":{"story":"5 days postpartum, temperature 38.9, pulse 118, foul smelling lochia, BP 86 systolic"}},"anaemia_story":{"summary":"Anaemia narrative","value":{"story":"Patient 30 weeks pregnant, Hb 6.5 g/dL on routine screening, feeling very tired and breathless"}}}}}},"responses":{"200":{"description":"Extracted case + full evaluation","content":{"application/json":{"example":{"story":"32 year old woman 34 weeks pregnant BP 158/102 headache visual disturbance proteinuria ++","structuredCase":{"patientId":"TZA-847291","condition":"preeclampsia","ga":34,"bpSyst":158,"bpDiast":102,"proteinuria":"++","headache":true,"visualDisturbance":true},"evaluation":{"risk":{"level":"high","score":68,"factors":["hypertension","significant_proteinuria"]},"icd10Code":"O14.9","alerts":[{"id":"PRE_ECLAMPSIA_SUSPECTED","severity":"critical","stgRef":"STG 2021 11.7.3"}],"interventions":[{"code":"REFERRAL_URGENT","priority":"emergency"}]}}}}},"400":{"description":"Missing story field","content":{"application/json":{"example":{"message":"story is required","status":400}}}}}}},"/cds/risk/{patientId}":{"get":{"tags":["Patient"],"summary":"Latest risk snapshot for a patient","description":"Returns the most recent risk score, level, and contributing factors from the patient's stored visit timeline.","operationId":"getPatientRisk","parameters":[{"name":"patientId","in":"path","required":true,"schema":{"type":"string"},"examples":{"preeclampsia":{"value":"P-PRE-001","summary":"Pre-eclampsia patient"},"pph":{"value":"P-PPH-001","summary":"PPH patient"},"sepsis":{"value":"P-SEP-001","summary":"Sepsis patient"}}}],"responses":{"200":{"description":"Latest risk for the patient","content":{"application/json":{"example":{"patientId":"P-PRE-001","risk":{"level":"high","score":68,"factors":["hypertension","significant_proteinuria"]}}}}},"404":{"description":"No timeline found for patient","content":{"application/json":{"example":{"message":"No timeline found for patient"}}}}}}},"/cds/timeline/{patientId}":{"get":{"tags":["Patient"],"summary":"Full visit timeline + longitudinal trend","description":"Returns all recorded visits for the patient with timestamps and risk per visit, plus a derived longitudinal trend: `improving`, `stable`, or `worsening`.","operationId":"getPatientTimeline","parameters":[{"name":"patientId","in":"path","required":true,"schema":{"type":"string"},"example":"P-PRE-001"}],"responses":{"200":{"description":"Patient visits and longitudinal summary","content":{"application/json":{"example":{"patientId":"P-PRE-001","visits":[{"timestamp":1719600000000,"risk":{"level":"medium","score":38}},{"timestamp":1719686400000,"risk":{"level":"high","score":68}}],"longitudinal":{"trend":"worsening"}}}}}}}},"/cds/explain":{"post":{"tags":["Explainability"],"summary":"Plain-language explanation of an evaluation","description":"Accepts a full evaluation result object and returns a human-readable sentence summarising the risk level, contributing factors, and active guideline alerts. Useful for generating patient-facing or clinician summary text.","operationId":"explainEvaluation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["evaluation"],"properties":{"evaluation":{"$ref":"#/components/schemas/EvaluateResponse"}}},"example":{"evaluation":{"risk":{"level":"high","score":68,"factors":["hypertension","significant_proteinuria"]},"alerts":[{"id":"PRE_ECLAMPSIA_SUSPECTED","severity":"critical","message":"Suspected pre-eclampsia. Start close BP and urine monitoring.","stgRef":"STG 2021 11.7.3"}]}}}}},"responses":{"200":{"description":"Plain-language explanation","content":{"application/json":{"example":{"explanation":"Risk level is high (score 68). Key triggers: hypertension, significant_proteinuria. Active guideline alerts: PRE_ECLAMPSIA_SUSPECTED: Suspected pre-eclampsia. Start close BP and urine monitoring. (STG 2021 11.7.3)."}}}}}}},"/health":{"get":{"tags":["System"],"summary":"Service health check","description":"Returns service status. Use for load-balancer probes and uptime monitoring.","operationId":"healthCheck","responses":{"200":{"description":"Service is running","content":{"application/json":{"example":{"status":"ok","service":"cdstai-maternal"}}}}}}}},"components":{"schemas":{"EvaluateRequest":{"type":"object","required":["patientId"],"description":"Structured patient clinical payload. Include only the fields relevant to the condition being evaluated.","properties":{"patientId":{"type":"string","description":"Unique patient identifier","example":"P-001"},"condition":{"type":"string","description":"Condition key","enum":["preeclampsia","postpartum_hemorrhage","sepsis","anaemia","gestational_diabetes","anc_routine","pnc_routine","obstructed_labor","maternal_default","SCD"],"example":"preeclampsia"},"ga":{"type":"number","description":"Gestational age in weeks","example":34},"bpSyst":{"type":"number","description":"Systolic blood pressure (mmHg)","example":158},"bpDiast":{"type":"number","description":"Diastolic blood pressure (mmHg)","example":102},"proteinuria":{"type":"string","description":"Urine protein dipstick result","enum":["None","+","++","+++"],"example":"++"},"hb":{"type":"number","description":"Haemoglobin g/dL","example":9.5},"temperature":{"type":"number","description":"Body temperature °C","example":37.5},"bloodLoss":{"type":"number","description":"Estimated blood loss in ml","example":500},"glucoseFasting":{"type":"number","description":"Fasting glucose mmol/L","example":5.6},"glucoseRandom":{"type":"number","description":"Random glucose mmol/L","example":10.4},"headache":{"type":"boolean","description":"Persistent headache present","example":true},"visualDisturbance":{"type":"boolean","description":"Visual disturbance / blurred vision","example":true},"epigastricPain":{"type":"boolean","description":"Epigastric pain present","example":false},"daysPostpartum":{"type":"number","description":"Days since delivery","example":0},"pulse":{"type":"number","description":"Pulse rate bpm","example":118},"systolicBP":{"type":"number","description":"Systolic BP (alias for bpSyst)","example":88},"foulLochia":{"type":"boolean","description":"Foul-smelling lochia present","example":true},"uterusTone":{"type":"string","description":"Uterus tone on palpation","example":"soft"},"ongoingBleedingMinutes":{"type":"number","description":"Duration of ongoing bleeding in minutes","example":20},"lastIPTpWeek":{"type":"number","description":"Gestational week of last IPTp dose","example":18},"ttDoseCount":{"type":"number","description":"Number of TT immunisation doses received","example":1},"dewormingGiven":{"type":"boolean","description":"Deworming given this pregnancy","example":false},"pncVisitDone":{"type":"boolean","description":"PNC visit completed within 24h of delivery","example":false},"postnatalDepressionScore":{"type":"number","description":"EPDS postnatal depression screening score","example":12},"breastfeedingDifficulty":{"type":"boolean","description":"Breastfeeding difficulty reported","example":true},"laborDurationHours":{"type":"number","description":"Duration of labour in hours","example":18},"descentArrested":{"type":"boolean","description":"Foetal head descent arrested","example":true},"foetalDistress":{"type":"boolean","description":"Foetal distress signs present","example":true},"moulding":{"type":"number","description":"Degree of moulding (1–3)","example":3},"cervixDilation":{"type":"number","description":"Cervical dilation in cm","example":8},"oxygenSat":{"type":"number","description":"Peripheral oxygen saturation % (SpO2)","example":92},"cough":{"type":"boolean","description":"Cough present","example":true},"difficultyBreathing":{"type":"boolean","description":"Difficulty breathing / respiratory distress","example":true},"fever":{"type":"boolean","description":"Fever present (clinically assessed)","example":true},"crisesPerYear":{"type":"number","description":"Number of SCD vaso-occlusive crises in the past 12 months","example":4},"strokeHistory":{"type":"boolean","description":"Previous stroke history","example":false},"admitted":{"type":"boolean","description":"Patient currently admitted as inpatient","example":true}}},"EvaluateResponse":{"type":"object","properties":{"patientId":{"type":"string"},"condition":{"type":"string"},"icd10Code":{"type":"string","description":"Most specific ICD-10 code for this encounter"},"icd10Reason":{"type":"string","description":"Reason for ICD-10 code selection"},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"risk":{"$ref":"#/components/schemas/RiskScore"},"interventions":{"type":"array","items":{"$ref":"#/components/schemas/Intervention"}},"longitudinal":{"type":"object","properties":{"trend":{"type":"string","enum":["improving","stable","worsening"]},"carePlan":{"type":"array","items":{"type":"object"}}}}}},"Alert":{"type":"object","properties":{"id":{"type":"string","description":"Machine-readable rule identifier"},"severity":{"type":"string","enum":["low","medium","high","critical","emergency"]},"message":{"type":"string","description":"Clinical action message"},"stgRef":{"type":"string","description":"Tanzania STG 2021 chapter reference"}}},"RiskScore":{"type":"object","properties":{"level":{"type":"string","enum":["low","medium","high","critical"],"description":"Risk classification"},"score":{"type":"number","minimum":0,"maximum":100,"description":"Composite risk score 0–100"},"factors":{"type":"array","items":{"type":"string"},"description":"Contributing risk factors"}}},"Intervention":{"type":"object","properties":{"code":{"type":"string","description":"Intervention code (matches alert ID when alert-driven)"},"priority":{"type":"string","enum":["low","medium","high","critical","emergency"]},"action":{"type":"string","description":"Specific clinical action to take"},"reference":{"type":"string","description":"Guideline or protocol reference"}}}}}}