Skip to content

Steer-06: Real-Time Chat Entity Extraction

Read first: specs/sdd-mvp/04-agent-pipeline.md, specs/sdd-mvp/05-ehr-builder.md, specs/sdd-mvp/08-conversation-design.md

Context & Goal

When a patient mentions clinical information in chat ("I have diabetes", "I take metformin", "I'm allergic to latex"), the system should extract structured entities in real-time, create FHIR resources, update the EHR, and show inline confirmation — all within the same conversational turn.

Backend (curaway-ai/curaway-backend)

Step 1: Chat Entity Extractor

Create app/services/chat_entity_extractor.py: - Takes a chat message + existing patient context - Uses Claude Haiku to extract: conditions (ICD-10), medications (name + dosage), allergies (substance + severity), demographics (age, weight, BMI), preferences - Returns structured ExtractedEntities with confidence scores per entity - Only extracts if entities are present — returns empty for non-clinical messages

Step 2: Integration with Intake Agent

In Intake Agent collect_information node: - After generating conversational response, run chat entity extractor on patient message - If entities found: call ehr_builder_service.update_from_chat() for each entity - Include extracted entities in response metadata (for frontend inline indicators) - Recalculate intake_progress

Step 3: Deduplication Logic

Before creating FHIR resources from chat extraction: - Check if condition/medication/allergy already exists in patient's FHIR resources - If duplicate with same ICD code: skip (don't create duplicate) - If similar but different (e.g., "high blood pressure" → I10, but I11 already exists): flag for review - If new: create and emit event

Step 4: Tests

  • Test extraction: "I have diabetes and take metformin 1000mg twice daily" → E11 condition + metformin medication
  • Test deduplication: same condition mentioned twice → only one FHIR resource
  • Test non-clinical message: "What's the next step?" → no extraction
  • Test multi-entity: "I'm allergic to latex and penicillin" → two AllergyIntolerance resources

Backend Verification

python -m pytest tests/test_chat_extraction.py -v

Frontend (curaway-ai/curaway-frontend)

Step 1: Inline Extraction Indicators

Create src/components/chat/ExtractionIndicator.tsx: - Small teal badges below agent response: "✓ Added to your record: Type 2 diabetes (E11)" - Multiple badges for multiple extractions - Animated fade-in appearance - Click → scrolls to relevant section in EHR summary (left panel)

Step 2: EHR Live Update

When extraction indicators appear: - EHR Summary in left panel highlights newly added items (brief glow animation) - Progress strip updates percentage - Document checklist may update if extraction revealed conditional requirements (e.g., diabetes → HbA1c now required)

Frontend Verification

npm run build
npx tsc --noEmit
# Manual: type "I have diabetes", verify extraction badge appears + EHR updates

Checklist

  • [ ] Error codes: EXTRACT_CHAT_001, EXTRACT_DEDUP_001
  • [ ] Feature flag: chat_entity_extraction
  • [ ] Unit tests: extraction, dedup, non-clinical skip
  • [ ] PostHog: chat_entity_extracted, extraction_indicator_clicked
  • [ ] Mobile: extraction badges wrap on small screens
  • [ ] CLAUDE.md: update chat extraction description
  • [ ] Rollback: disable flag → no inline extraction, intake still works conversationally