{"slug": "from-scribbles-to-standards-converting-unstructured-medical-notes-to-hl7-fhir-4o", "title": "From Scribbles to Standards: Converting Unstructured Medical Notes to HL7 FHIR with GPT-4o", "summary": "A developer outlined a pipeline that uses GPT-4o with few-shot prompting and OpenAI's Structured Outputs to convert unstructured clinical notes into validated HL7 FHIR R4 Observation resources. The approach pairs Pydantic schema definitions with the API's response_format parameter to force model output into strict FHIR-compliant JSON, with invalid results routed to retry or human review.", "body_md": "Let’s be honest: doctors are famous for two things—saving lives and having handwriting that looks like a caffeinated spider crawled across a page. For **Data Engineers** in the healthcare space, this \"unstructured data\" is a nightmare. \n\nTraditional OCR and Regex-based parsers often fail because medical notes aren't just messy; they are context-heavy. To achieve true **healthcare interoperability**, we need to transform these scribbles into the **HL7 FHIR** (Fast Healthcare Interoperability Resources) standard. \n\nIn this tutorial, we are diving into the \"Dark Arts\" of medical data cleaning. We'll leverage **GPT-4o**, **Few-shot prompting**, and **JSON Schema** to build a robust pipeline that turns raw clinical text into valid FHIR resources.\n\nBefore we write any code, we need a solid strategy. We aren't just \"asking\" the AI to format text; we are building a validation engine.\n\n``` php\ngraph TD\n    A[Raw Unstructured Medical Note] --> B{GPT-4o Engine}\n    B -->|Few-Shot Context| C[Extraction Logic]\n    C --> D[JSON Schema Validation]\n    D -->|Valid| E[FHIR Patient/Observation Resource]\n    D -->|Invalid| F[Retry/Human-in-the-loop]\n    E --> G[(Clinical Data Repository)]\n\n    style B fill:#f9f,stroke:#333,stroke-width:2px\n    style E fill:#00ff00,stroke:#333\n```\n\nTo follow along, you'll need:\n\n`openai`, `pydantic` (for schema validation), and a basic understanding of FHIR is strict. If your JSON doesn't match the resource definition exactly, the receiving server will reject it. We’ll use **Pydantic** to define a simplified FHIR `Observation` resource to ensure our LLM output is production-ready.\n\n``` python\nfrom pydantic import BaseModel, Field\nfrom typing import List, Optional\n\nclass FHIRCoding(BaseModel):\n    system: str\n    code: str\n    display: str\n\nclass FHIRQuantity(BaseModel):\n    value: float\n    unit: str\n    system: str = \"http://unitsofmeasure.org\"\n    code: str\n\nclass FHIRObservation(BaseModel):\n    resourceType: str = \"Observation\"\n    status: str\n    category: List[dict]\n    code: dict  # Should contain a LOINC code\n    subject: dict # Reference to Patient\n    valueQuantity: Optional[FHIRQuantity] = None\n    note: Optional[List[dict]] = None\n```\n\nThe secret to converting \"Dark Data\" is **Few-shot prompting**. By providing the LLM with 2-3 examples of \"Messy Input -> Valid FHIR,\" we drastically reduce hallucinations.\n\n```\nSYSTEM_PROMPT = \"\"\"\nYou are a specialized Medical Informatics Agent. \nYour task is to parse unstructured clinical notes into valid HL7 FHIR R4 JSON.\nFocus on extracting Vital Signs into 'Observation' resources.\nUse LOINC codes for observations (e.g., 85354-9 for Blood Pressure).\n\"\"\"\n\nFEW_SHOT_EXAMPLES = \"\"\"\nInput: \"Pt seen today. BP 120/80. HR 72. Complaining of mild headache.\"\nOutput: {\n  \"resourceType\": \"Observation\",\n  \"status\": \"final\",\n  \"code\": { \"coding\": [{\"system\": \"http://loinc.org\", \"code\": \"85354-9\", \"display\": \"Blood Pressure\"}] },\n  \"component\": [\n    {\"code\": {\"text\": \"Systolic\"}, \"valueQuantity\": {\"value\": 120, \"unit\": \"mmHg\"}},\n    {\"code\": {\"text\": \"Diastolic\"}, \"valueQuantity\": {\"value\": 80, \"unit\": \"mmHg\"}}\n  ]\n}\n\"\"\"\n```\n\nOpenAI recently released **Structured Outputs**, which forces the model to adhere strictly to a provided JSON Schema. This is a game-changer for **Data Engineering** pipelines.\n\n``` python\nimport openai\nimport json\n\nclient = openai.OpenAI()\n\ndef extract_medical_data(raw_text: str):\n    response = client.beta.chat.completions.parse(\n        model=\"gpt-4o-2024-08-06\",\n        messages=[\n            {\"role\": \"system\", \"content\": SYSTEM_PROMPT},\n            {\"role\": \"user\", \"content\": f\"Extract from this note: {raw_text}\"}\n        ],\n        response_format=FHIRObservation, # Enforcing the Pydantic schema!\n    )\n\n    return response.choices[0].message.parsed\n\n# Example Usage\nraw_note = \"Subject: John Doe. The patient presents with a fever of 102F and a rapid heart rate of 110bpm.\"\nfhir_data = extract_medical_data(raw_note)\nprint(fhir_data.model_dump_json(indent=2))\n```\n\nIn the world of **Medical Data Engineering**, accuracy isn't just a metric; it's a safety requirement. Using LLMs as a \"reasoning bridge\" between raw text and structured standards like FHIR allows us to unlock insights from millions of legacy records that were previously \"dark\" (unsearchable and unusable).\n\n💡 **Pro-Tip**: For production-ready examples and advanced patterns on handling HIPAA-compliant data pipelines, check out the specialized guides over at the [WellAlly Blog](https://www.wellally.tech/blog). They have fantastic resources on scaling medical AI without compromising on data integrity.\n\nWe’ve moved past the era of manual data entry. By combining the reasoning power of **GPT-4o** with the structural rigor of **FHIR** and **Pydantic**, we can automate the most tedious parts of healthcare tech.\n\n**What's next?**\n\nAre you working with medical data? What's the craziest \"doctor handwriting\" you've ever had to parse? Let me know in the comments! 👇", "url": "https://wpnews.pro/news/from-scribbles-to-standards-converting-unstructured-medical-notes-to-hl7-fhir-4o", "canonical_source": "https://dev.to/beck_moulton/from-scribbles-to-standards-converting-unstructured-medical-notes-to-hl7-fhir-with-gpt-4o-3cpg", "published_at": "2026-11-16 00:12:00+00:00", "updated_at": "2026-11-16 00:21:00.620059+00:00", "lang": "en", "topics": ["large-language-models", "ai-tools", "developer-tools", "structured-data", "artificial-intelligence"], "entities": ["OpenAI", "GPT-4o", "HL7 FHIR", "Pydantic", "LOINC"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/from-scribbles-to-standards-converting-unstructured-medical-notes-to-hl7-fhir-4o", "markdown": "https://wpnews.pro/news/from-scribbles-to-standards-converting-unstructured-medical-notes-to-hl7-fhir-4o.md", "text": "https://wpnews.pro/news/from-scribbles-to-standards-converting-unstructured-medical-notes-to-hl7-fhir-4o.txt", "jsonld": "https://wpnews.pro/news/from-scribbles-to-standards-converting-unstructured-medical-notes-to-hl7-fhir-4o.jsonld"}}