Deterministic FHIR Assembly from Clinical Narrative

1. Introduction

Clinical reasoning, qualifiers, negations, quantities, timing, and attribution are commonly recorded in prose. Reuse across systems requires those facts to be rendered as structured FHIR resources. Narrative-to-FHIR conversion therefore joins two problems that have different kinds of answers.

The first problem is reading: deciding which facts a narrative states and which phrases refer to the same patient, condition, encounter, medication, or measurement. This is linguistic judgment, and more than one interpretation may be defensible. The second problem is rendering: selecting the datatype, cardinality, identifier, reference, and representation required for a stated fact. These decisions are governed by the FHIR specification and explicit implementation policy.

FHIR at Will treats reading as bounded extraction and rendering as compilation. The model never emits a FHIR object and never chooses FHIR datatypes, references, identifiers, required defaults, or terminology codes. Once the entity stream crosses the trust boundary, ordinary code owns the remainder of the transformation.

1.1 Scope

This page describes the method, implementation boundary, operational controls, and limitations. It intentionally excludes clinical-accuracy claims, experimental results, evaluation metrics, benchmarks, and comparisons with named systems.

1.2 Design objective

The design objective is not to eliminate uncertainty. It is to confine uncertainty to the decisions that genuinely require language interpretation, make those decisions inspectable, and prevent them from controlling specification-defined structure. When representation is unsupported, the system prefers an explicit refusal over a plausible fabrication.

2. Method

2.1 Placement of the trust boundary

Each conversion step is classified by one question: does this step have more than one defensible answer given its input? Language interpretation and instance grouping may, so the model handles them. Datatype selection, entry ordering, identifier minting, reference wiring, coercion, required defaults, provenance, and reporting should not, so deterministic code handles them.

2.2 Pipeline

1. Verbatim transcription, for voice input only. A separate caller-supplied speech-to-text credential is used. The hash-pinned instruction forbids translation, summarization, correction, speaker labeling, and clinical interpretation. Negation and quantities are preserved; unclear speech is marked [inaudible] rather than guessed.
2. Grounded entity extraction. One constrained JSON-mode call identifies facts and grouping. It returns a flat entity list and never emits FHIR JSON.
3. All-or-nothing trust gate. Deterministic checks reject the entire stream when a record has an unknown field, empty value, unsupported catalog entry, invalid instance slug, or exceeds the configured stream ceiling.
4. Deterministic FHIR assembly. Validated entities are grouped, typed, coerced, ordered, linked, tagged, and reported without another model call or external I/O.

Typed narratives enter the second stage directly. Audio enters as a size-capped multipart request body and follows the same extraction path after transcription. The outputs are a FHIR R4 collection Bundle, a value-free assembly report, and, for voice requests, the transcript seen by downstream stages.

2.3 Entity representation

Each extracted entity contains exactly four non-empty strings:

resourceType

A target resource selected from the reviewed catalog.

instance

A lowercase grouping slug for one real-world thing. It must not echo patient names, identifiers, or dates.

keyword

The most specific allowed element for the selected resource type.

value

The source wording, preserved with minimal normalization.

The catalog closes the model’s output space and is included in the prompt fingerprint. FHIR datatypes are deliberately absent from the prompt. The explicit instance field externalizes the highest-risk judgment—whether facts belong together—instead of hiding that decision in completion order.

2.4 Reviewed extraction rules

The rule pack is ordered and versioned. Rules may name only elements that the assembler can build, and they may never request an invented value. Reviewer-facing rationales are retained with each rule but are not sent to the model.

1. An age is not a birth date. Preserve stated age as an Age Observation; do not calculate a plausible birth date.
2. One measurement per value. Split compound readings into separate measurements instead of forcing them into one Quantity.
3. Anchor relative dates only to a stated date. Never anchor to “today,” and do not create unsupported precision.
4. Preserve denial and attribution. Do not convert negation or a relative’s history into an active diagnosis for the patient.
5. Split medication phrases. Separate medication identity from dose, route, frequency, and timing.
6. Use one instance per real-world thing. Assign distinct grouping keys to separate measurements, conditions, encounters, and medications.

3. Deterministic implementation

3.1 Trust-gate contract

A record must contain only the four declared fields, and every field must be a non-empty string. Resource and element names must belong to the reviewed catalog. The instance must match [a-z0-9][a-z0-9-]{0,63}. A single malformed entity rejects the stream; retaining only valid records would present a partial extraction as an apparently complete Bundle. Passing this gate confirms conformance to the assembler’s input contract, not correctness of the model’s interpretation.

3.2 Assembly sequence

1. Group. Bucket records by resource type and instance; each group becomes one Bundle entry.
2. Order. Apply a reviewed resource rank so model output order cannot control Bundle order.
3. Mint identifiers. Derive UUIDv5 fullUrls from a fixed namespace, conversion seed, resource type, and instance.
4. Resolve datatypes. Reflect over typed FHIR R4 models rather than model output or a handwritten datatype map.
5. Coerce or refuse. Accept only values supported by datatype-specific coercers; drop and report failures.
6. Wire references. Resolve a target only when the expected resource type has exactly one instance.
7. Inject subject. Point required subject fields to the sole Patient when unambiguous.
8. Apply reviewed defaults. Fill only required 1..1 elements covered by an explicit policy constant.
9. Tag provenance. Distinguish model-derived content from entries containing policy-inferred defaults.

3.3 Coercion and terminology policy

Date and time values must match supported FHIR forms. A Quantity requires a leading number, while compound readings such as blood pressure are rejected as one Quantity. CodeableConcept and Coding values receive text or display only. Quantities may retain a stated unit, but the assembler never invents a terminology system or code. Backbone elements, extensions, Money, and other unsupported single-string shapes are dropped and reported rather than approximated.

3.4 Determinism and versioning

Given a fixed entity stream and conversion seed, assembly is a pure function. The same inputs receive the same ordering, identifiers, coercion policy, references, defaults, tags, and report treatment. Determinism does not extend upstream: another model run may produce a different entity stream from the same narrative.

The prompt set is hash-pinned. The resource catalog participates in that fingerprint, and the extraction rule pack is ordered and versioned. Tests require every element named by a rule to exist in the assembler’s catalog, keeping model guidance aligned with buildable output.

4. Provenance and operational controls

4.1 Assembly report

Every non-plain placement emits a note containing an entry index, resource type, element, action, and reason. Actions are dropped, inferred, wired, unresolved, and conflict. Notes exclude clinical values and model-authored instance slugs, allowing the report to be handled separately from the sensitive Bundle.

4.2 Resource provenance

Every entry is tagged ai-derived. Entries containing a required value supplied by reviewed policy also receive machine-inferred. Structural reference wiring is reported as wired but is not mislabeled as inference. These tags disclose origin and never imply human review.

4.3 Credentials, egress, and logging

Provider credentials arrive per request and are not logged or serialized. Extraction and transcription can use separate caller-supplied keys. External clinical-data egress requires an allowlisted host and explicit acknowledgement; this policy gate is not itself a compliance determination.

Clinical content remains in request and response bodies rather than URL parameters. Narratives, prompts, completions, transcripts, provider responses, resource bodies, and other clinical payloads stay out of logs. The Bundle and transcript remain sensitive; only the value-free assembly report is designed for aggregation.

5. Where the architecture excels

The following are architectural properties, not measured claims of clinical superiority and not comparisons with named products.

Bounded model authority

The model proposes facts and grouping but cannot choose resource structure, datatypes, references, identifiers, defaults, or codes.

Specification-owned rendering

Typed FHIR models determine representation and cardinality instead of prompt memory.

Visible grouping

The instance key exposes which facts the model believes belong together, concentrating review on the highest-risk judgment.

Refusal over approximation

Unsupported shapes and failed coercions become explicit report entries rather than plausible substitutions.

Replayable assembly

A fixed entity stream and seed produce the same structural decisions and identifiers.

Separable evidence

The Bundle, transcript, provenance tags, and PHI-free report preserve different evidence about how output was produced.

6. Limitations

1. Interpretation remains stochastic. The same narrative may yield different entity streams across model runs.
2. Grouping errors can survive assembly. Incorrect pairing, attribution, or negation may still produce structurally valid FHIR.
3. Terminology binding is deferred. Text and display do not replace independently verified codes.
4. The entity language is flat. It cannot express every nested or backbone structure; unsupported values are refused.
5. Required defaults are policy assertions. They are reported and tagged, but they are not grounded in the narrative.
6. Suppression can lose information. Facts without a safe catalog representation may be omitted rather than misattributed.
7. Voice adds a silent failure surface. Returning the transcript enables inspection but cannot prevent transcription error.
8. Current subject assumptions are narrow. Subject wiring assumes one English narrative about one Patient.
9. External model use creates egress exposure. BYOK and allowlisting control access but do not keep PHI inside the deployment boundary.
10. Provenance is not review. Machine-origin tags explain source class, not clinical correctness.