Skip to content
Blog

Patient Intake Agents: Form Understanding and EHR Integration

Build an intake agent that classifies patient forms, extracts fields from handwriting and checkboxes with Hugging Face transformers, redacts PII, validates schemas, and maps to HL7 FHIR before write-back.

Published on • November 16, 2026

AI Assistant

The waiting-room clipboard is still healthcare’s least interoperable system: medications crammed into a too-small box, an ambiguous checkbox, “tylenol pm” in cursive — then someone retypes it into the EHR, or doesn’t, and the allergy list stays stale for another visit.

The fix is not “OCR and hope.” It is a pipeline: classify what the form is, extract fields into typed values, redact identifiers before anything crosses a boundary, validate against a required schema, map to HL7 FHIR resources, and verify whatever the model was unsure about with a human.

In this post, you will learn how to build that intake agent using Hugging Face transformers — token classification for entity extraction and text classification for form routing — plus Pydantic schema validation, deterministic PII redaction, FHIR-shaped write-back, and a confidence-gated human review queue.

Compliance caveat first: this is a technical walkthrough, not compliance advice. The HIPAA notes below are practical engineering guidance, not a certification path — have your privacy officers review any system that touches PHI.

Prerequisites

  • Python 3.10+ with pip install transformers torch datasets evaluate pydantic.
  • Optional: huggingface_hub with a token for private models or hosted inference.
  • Comfort with Python and JSON, plus basic FHIR awareness (Patient, QuestionnaireResponse suffice).
  • Synthetic or de-identified sample forms while developing — never real PHI in a scratch notebook.

The Hugging Face docs index what we use: transformers for models, datasets/evaluate for metrics, huggingface_hub for model access.

The Pipeline at a Glance

raw form ─► classify ─► extract (NER) ─► redact + validate ─► FHIR ─► low confidence? ─► review ─► write-back

The ordering is deliberate: redaction happens before validation and mapping, and low-confidence fields route before write-back. Everything after extraction is deterministic code you can test.

Step 1: Classify the Form Before You Parse It

Different forms have different required fields. A medication history form parsed with an allergy schema produces confident garbage, so route first.

Text classification is the standard Hugging Face task for this — the text classification guide covers AutoModelForSequenceClassification, id2label, Trainer, and accuracy metrics. At inference it collapses to a pipeline:

# intake/classify.py
from transformers import pipeline

# Fine-tuned on synthetic intake forms:
# new_patient, medication_history, consent, insurance, allergy_update.
classifier = pipeline("text-classification",
                      model="acme/intake-form-classifier", top_k=3)


def classify_form(text: str) -> tuple[str, float]:
    """Return (form_type, confidence) from the top-ranked label."""
    best = classifier(text)[0]
    return best["label"], float(best["score"])

The score is the first gate in your escalation logic. If the best label returns 0.51, do not proceed to extraction — send the form to a human router, because every downstream field is suspect. Without a fine-tuned model, bootstrap with a zero-shot pipeline over your label set, then fine-tune on the result; zero-shot is a launcher, not a production dependency.

Step 2: Extract Fields With Token Classification

Named entity recognition is the token classification task: assign a label to each token. The token classification guide explains the B-/I- scheme — B- begins an entity, I- continues it, O marks everything else — which is how multi-token values like 20 mg twice daily get captured.

# intake/extract.py
from transformers import pipeline

extractor = pipeline("ner", model="acme/intake-ner",
                     aggregation_strategy="simple")  # merges B-/I- spans


def extract_fields(text: str, min_score: float = 0.75) -> dict:
    """Pull entity spans out of the form text, keeping provenance."""
    fields: dict[str, list[dict]] = {}
    for span in extractor(text):
        if span["score"] < min_score:
            continue
        fields.setdefault(span["entity_group"], []).append(
            {"value": span["word"], "score": float(span["score"]),
             "start": span["start"], "end": span["end"]}
        )
    return fields

Notice what is retained: score and character offsets per value. Offsets let the review UI highlight the original text; scores drive the human-in-the-loop routing in Step 6. Dropping either turns an auditable extraction into an unexplainable one.

Without aggregation_strategy you get raw B-/I- labels per subword — useful only for training-time alignment (the guide’s word_ids() trick labels the first subtoken and assigns -100 to specials). Always aggregate at serving time, and expect lower scores on handwriting: let the confidence gate work rather than tuning thresholds upward.

Step 3: Validate Against a Required Schema

Extraction gives you spans; the EHR needs records. Put a hard schema between them:

# intake/schema.py
from pydantic import BaseModel, Field, field_validator


class Medication(BaseModel):
    name: str
    dose: str | None = None
    route: str | None = None
    frequency: str | None = None
    confidence: float = Field(ge=0.0, le=1.0)


class IntakeRecord(BaseModel):
    form_type: str
    patient_name: str | None = None
    date_of_birth: str | None = Field(None, pattern=r"^\d{4}-\d{2}-\d{2}$")
    medications: list[Medication] = []
    allergies: list[str] = []
    chief_complaint: str | None = None
    missing_required: list[str] = []

    @field_validator("allergies")
    @classmethod
    def normalize_allergies(cls, v: list[str]) -> list[str]:
        return sorted({a.strip().lower() for a in v if a.strip()})


REQUIRED_BY_FORM = {
    "medication_history": ["medications"],
    "allergy_update": ["allergies"],
    "new_patient": ["patient_name", "date_of_birth"],
    "insurance": ["patient_name"],
}


def validate_record(record: IntakeRecord) -> IntakeRecord:
    """Flag missing required fields instead of guessing defaults."""
    required = REQUIRED_BY_FORM.get(record.form_type, [])
    record.missing_required = [f for f in required if not getattr(record, f, None)]
    return record

Pydantic gives you three things a prompt-only pipeline cannot: a pattern that rejects 2026-13-45, an explicit missing_required list instead of silent None defaults, and a validator collapsing ["Penicillin ", "penicillin"] to one entry. Never fabricate a missing required field — a missing medication list is a routing decision, not a gap for a model to fill.

Step 4: Redact PII Before Anything Leaves the Boundary

PHI minimization separates a demo from something a compliance officer will sign. Redact at the earliest point — after extraction, before validation, mapping, logging, or any outbound call.

# intake/redact.py
import re
from transformers import pipeline

# Local, deterministic patterns — run these regardless of model output.
PATTERNS = [
    (re.compile(r"\b\d{3}-\d{2}-\d{4}\b"), "[SSN]"),
    (re.compile(r"\b\d{1,2}/\d{1,2}/\d{4}\b"), "[DOB]"),
    (re.compile(r"\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b"), "[PHONE]"),
    (re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.]+\b"), "[EMAIL]"),
]

pii_detector = pipeline("token-classification", model="acme/pii-detector",
                        aggregation_strategy="simple")


def redact(text: str) -> str:
    """Mask PII using model-detected spans, then deterministic regexes."""
    spans = [s for s in pii_detector(text)
             if s["score"] >= 0.85
             and s["entity_group"] in {"PERSON", "LOCATION", "DATE", "ID", "PHONE"}]
    for span in sorted(spans, key=lambda s: s["start"], reverse=True):
        text = text[:span["start"]] + f"[{span['entity_group']}]" + text[span["end"]:]
    for pattern, token in PATTERNS:
        text = pattern.sub(token, text)
    return text

Order matters: the NER pass uses character offsets, so spans must be replaced in reverse offset order or later offsets corrupt. The regexes then backstop whatever the model missed — a \b\d{3}-\d{2}-\d{4}\b match never needs a model.

Keep the unredacted original only if clinical accuracy demands it — encrypted at rest, scoped access, logged reads. Logs, traces, analytics, and LLM prompts all get the redacted string.

Step 5: Map to HL7 FHIR Resources

Write-back is where integration happens; the mapping itself is pure code.

# intake/fhir.py
import uuid
from datetime import datetime, timezone
from intake.schema import IntakeRecord


def to_fhir(record: IntakeRecord, mrn: str) -> dict:
    """Map a validated intake record to FHIR R4 resources."""
    now = datetime.now(timezone.utc).isoformat()
    patient_id = str(uuid.uuid4())

    patient = {
        "resourceType": "Patient",
        "id": patient_id,
        "identifier": [{"system": "urn:hospital:mrn", "value": mrn}],
        "name": [{"text": record.patient_name or "UNKNOWN"}],
        "birthDate": record.date_of_birth,
        "active": True,
    }

    medications = [
        {"resourceType": "MedicationStatement", "status": "active",
         "medicationCodeableConcept": {"text": m.name},
         "dosage": [{"text": " ".join(p for p in [m.dose, m.route, m.frequency] if p)}],
         "subject": {"reference": f"Patient/{patient_id}"},
         "meta": {"tag": [{"code": f"confidence-{m.confidence:.2f}"}]}}
        for m in record.medications
    ]

    allergies = [
        {"resourceType": "AllergyIntolerance", "code": {"text": a},
         "patient": {"reference": f"Patient/{patient_id}"}}
        for a in record.allergies
    ]

    questionnaire_response = {
        "resourceType": "QuestionnaireResponse",
        "status": "completed",
        "authored": now,
        "questionnaire": f"Questionnaire/{record.form_type}",
        "item": [{"linkId": "chief_complaint",
                  "answer": [{"valueString": record.chief_complaint}]}],
    }

    return {"patient": patient, "medications": medications, "allergies": allergies,
            "questionnaire_response": questionnaire_response,
            "blocked": bool(record.missing_required)}

Three integration decisions are visible in this code:

  • meta.tag carries extraction confidence, so the EHR can still display “extracted, 0.82 confidence” beside the medication years later.
  • blocked is computed, not implied — a record with missing_required must never be POSTed as a completed intake.
  • References are stable strings. Patient/{id} is how everything hangs together: generate the patient ID once and reuse it.

Step 6: Human-in-the-Loop for Low Confidence

The rule is simple: any required field below your confidence bar, or any missing_required entry, routes to a human. Nothing else does.

# intake/review.py
from intake.schema import IntakeRecord, validate_record

CONFIDENCE_FLOOR = 0.85


def needs_human(record: IntakeRecord) -> tuple[bool, list[str]]:
    reasons = [f"medication '{m.name}' at {m.confidence:.2f}"
               for m in record.medications if m.confidence < CONFIDENCE_FLOOR]
    if record.missing_required:
        reasons.append(f"missing: {', '.join(record.missing_required)}")
    if record.patient_name is None and record.date_of_birth is None:
        reasons.append("identity fields absent — verify against ID")
    return bool(reasons), reasons


def submit(record: IntakeRecord) -> dict:
    record = validate_record(record)
    flagged, reasons = needs_human(record)
    if flagged:
        return {"status": "queued_for_review", "reasons": reasons,
                "record": record.model_dump()}
    return {"status": "ready_for_writeback", "record": record.model_dump()}

The reviewer’s UI should show each extracted value beside the highlighted source span — that is why Step 2 kept start/end; reviewers resolve disagreements in seconds when they can see the original handwriting. Log every correction: it is free labeled data for the next fine-tuning round.

Putting It All Together

# intake/main.py
from intake.classify import classify_form
from intake.extract import extract_fields
from intake.redact import redact
from intake.fhir import to_fhir
from intake.review import submit

raw = open("form.txt").read()

form_type, conf = classify_form(raw)
if conf < 0.6:
    raise SystemExit("Route to human router: form type uncertain")

fields = extract_fields(redact(raw))       # PHI never leaves unmasked
record = build_record(form_type, fields)   # extraction -> IntakeRecord
result = submit(record)                    # schema validation + confidence gate

if result["status"] == "ready_for_writeback":
    resources = to_fhir(record, mrn="MRN-004512")
    # POST to the EHR FHIR endpoint with an audit-logged service token
else:
    print("Queued for review:", result["reasons"])

A legible medication form produces a Patient, one MedicationStatement per drug with a confidence tag, any AllergyIntolerance entries, and a QuestionnaireResponse. A blurry sample reading “warfarin 5 mg” at 0.63 lands in the review queue with its reason attached instead of in the chart.

HIPAA and PHI: The Non-Negotiables

  • Where inference runs determines your compliance scope. The docs offer local transformers, Inference Endpoints (dedicated), and Inference Providers (partner-hosted). Never send PHI through third-party hosted inference without a signed BAA covering that provider; when in doubt, run the model inside your own boundary.
  • Model choice affects data flow. A fine-tuned local model avoids the question and usually wins on latency and cost.
  • Minimum necessary. Redact before logging — traces, exceptions, and print() debugging are all disclosures.
  • Access control and audit. Write-back uses a scoped service identity; FHIR’s meta.security/meta.tag carry classification labels.
  • Retention and deletion. Know where records live, how long derived artifacts persist, and how deletion propagates to caches and vector stores.

Conclusion and Next Steps

You built an intake agent end to end: form classification with a text-classification pipeline, entity extraction with aggregated B-/I- spans, validation that flags rather than fabricates, offset-aware PII redaction before any boundary crossing, FHIR mapping with confidence provenance, and a review queue that escalates only what the model could not read.

Homework:

  • Fine-tune on your own form distribution. The token classification guide walks through Trainer and seqeval — measure F1 per entity type and watch which fields are weakest.
  • Add a vision stage for scanned forms, feeding a Hub vision model’s output into the same IntakeRecord.
  • Build an eval set of messy forms — crossed-out entries, arrows, margin notes — and fail CI when extraction F1 drops below a floor.
  • Emit OpenTelemetry spans per stage so a rejected write-back is diagnosable in one trace.

The clipboard is not going away this quarter. But every form routed through this pipeline is one fewer transcription error in the chart.