Narrative in
Clinical notes arrive as free text, with the abbreviations and variation found in real care.
Deterministic Narrative to FHIR using LLMs
FHIR at Will is the bridge.
An open-source, AI-powered interoperability layer that turns your Unstructured narrative clinical data into FHIR R4 resources—while your infrastructure evolves.
</> open source
⎈ self-hostable
↯ byok / byom
☷ implementation-guide aware
FHIR at Will implements an 8-layer validation cascade so you can trust what you interoperate.
› Verification-first by design
L1StructuralIs it valid FHIR R4?
L2ProfileDoes it conform to required profiles?
L3TerminologyAre codes valid and in their ValueSets?
L4InvariantsDo FHIRPath invariants hold?
L5PlausibilityIs the value clinically possible?
L6FidelityIs each element supported by source data?
L7CoverageWhat clinical information was omitted?
L8RoutingAuto-accept, review, or reject?
› AI-powered. Deterministic by design.
AI interprets.
Deterministic code decides.
FHIR at Will uses an LLM where clinical language is ambiguous: extracting grounded facts from unstructured narrative. From there, explicit schemas, profiles, terminology rules, and validation logic control the result.
Grounded extraction
The LLM identifies clinical facts and ties them back to the source narrative.
FHIR assembly
Typed mappings turn extracted facts into predictable FHIR R4 resources and Bundles.
Deterministic verdict
The same facts, configuration, and rules produce the same validation outcome every time.
The boundary is explicit:
the model proposes meaning;
the platform enforces structure;
nothing is trusted without verification.
› Research
A semi-deterministic method for narrative-to-FHIR
The method asks a model only for the judgment that code cannot make: which facts a narrative states and which facts describe the same real-world thing. Once that compact entity stream exists, deterministic code owns validation, FHIR datatypes, references, identifiers, required defaults, provenance, and reporting.
Scope of this overview
This section explains the method and its design rationale. It makes no claim about
clinical accuracy and intentionally omits evaluation scores, validation results,
benchmarks, and comparisons with published systems.
[ the organizing question ]
Does this step have more than one defensible answer given its input?
Language interpretation and grouping may have more than one defensible answer, so the model handles them. Datatype selection, entry ordering, identifier minting, reference wiring, and policy-defined defaults do not, so ordinary code handles them.
stochastic · model calls
Entity stream
(resourceType, instance, keyword, value)
trust boundary · no model call below this line
deterministic · no model call
01 / Input
Verbatim transcription keeps the source inspectable
Typed narratives enter directly. Dictated audio first passes through a separate speech-to-text call using a caller-supplied key. Its hash-pinned instruction is deliberately narrow: transcribe only—no translation, summarization, speaker labeling, clinical interpretation, or silent repair.
Negation words and quantities must be preserved exactly. Unclear audio is marked unintelligible rather than completed by guesswork, and the transcript is returned with the Bundle so a reviewer can inspect what the downstream stages actually saw.
02 / Extraction
A small, closed entity language
One constrained JSON-mode call emits a flat list. Every entity has exactly four non-empty strings; the model never emits a FHIR object.
- resourceType
- A target resource chosen from the reviewed catalog.
- instance
- A bounded lowercase slug shared by facts about one real-world thing.
- keyword
- An allowed element for that resource type.
- value
- The source wording, preserved rather than elaborated.
The catalog closes the output space and is versioned with the prompt. FHIR datatypes
are intentionally absent from the prompt: the model supplies source meaning, while
typed FHIR models resolve representation later. The explicit instance
field makes the model’s highest-risk decision—grouping—visible and reviewable instead
of hiding it in array order.
[ reviewed rule pack ]
Six rules prevent predictable shape errors
Rules may name only elements the assembler can build, and they may never ask the model to invent a value.
- 01An age is not a birth date
Keep a stated age as an Age Observation; do not calculate a plausible date of birth.
- 02One measurement per value
Represent compound readings as distinct measurements instead of forcing two numbers into one Quantity.
- 03Anchor relative dates
Resolve an offset only against a date stated in the narrative and only to supported precision.
- 04Preserve attribution and denial
Do not turn a negation or a relative’s history into an active diagnosis for the patient.
- 05Split medication phrases
Separate the medication identity from dose, route, frequency, and timing so each lands in its proper element.
- 06One instance per real-world thing
Give each measurement, condition, encounter, and medication its own explicit grouping key.
03 / Gate
Malformed extraction fails closed
Entity validation is deterministic and all-or-nothing. Each record must contain only the four declared fields; every value must be a non-empty string; resource and element names must belong to the catalog; the instance must match its bounded slug pattern; and the complete stream must remain under the configured ceiling.
One malformed entity rejects the stream. Silently retaining the rest would create an apparently complete Bundle from a partial account of the narrative.
04 / Assembly
Nine deterministic operations build the Bundle
- 1Group
Bucket records by resource type and instance; each group becomes one entry.
- 2Order
Apply a reviewed resource rank so model output order cannot control Bundle order.
- 3Mint identifiers
Use UUIDv5 over a fixed namespace, conversion seed, type, and instance.
- 4Resolve types
Read datatype and cardinality from typed FHIR R4 models, not from model output or a handwritten guess.
- 5Coerce or refuse
Place values only when their declared datatype accepts them; otherwise drop and report.
- 6Wire references
Create a reference only when its target type has exactly one unambiguous instance.
- 7Inject the subject
Point required subject fields at the sole Patient; leave ambiguity unresolved.
- 8Apply reviewed defaults
Fill only required 1..1 elements with a defensible policy constant; optional fields stay absent.
- 9Tag provenance
Mark every entry as AI-derived and identify entries containing policy-inferred defaults.
No terminology is fabricated.
Coded concepts receive text or display only. Quantities may carry a stated unit, but no terminology system or code is asserted without a separate deterministic terminology check.
[ explainability ]
Every non-plain placement leaves a reason
droppedThe source value could not be represented.
inferredA required field came from reviewed policy.
wiredA reference was resolved structurally.
unresolvedA reference target remained ambiguous.
conflictTwo values competed for one scalar field.
Report notes contain only an entry index, resource type, element, action, and reason. They never contain the clinical value or model-authored instance slug, making the report safe to aggregate without treating the Bundle itself as loggable.
[ why this improves on older generation patterns ]
Less authority for the model, more evidence for the reviewer
Narrower model responsibility
The model interprets language and grouping; it does not invent resource structure, datatypes, references, identifiers, or codes.
Refusal over approximation
A value that does not fit is reported instead of silently reshaped into something plausible.
Specification-owned structure
FHIR’s typed models—not prompt memory—determine representation and cardinality.
Visible provenance
Grounded, structurally wired, and policy-inferred content remain distinguishable downstream.
Replayable decisions
Versioned prompts, rule packs, catalogs, typed models, and deterministic assembly make a verdict explainable.
Bounded failure surface
The remaining model judgment is explicit in the entity stream rather than distributed across an opaque generated Bundle.
[ privacy & boundaries ]
The method makes risk visible; it does not remove it
Operational constraints
- Provider credentials arrive per request and are never logged or serialized.
- External clinical-data egress requires an allowlisted host and explicit acknowledgement.
- Prompts, completions, transcripts, resource bodies, and provider responses stay out of logs.
- The Bundle and transcript remain sensitive response data; only the value-free report is log-safe.
Honest boundaries
- A wrong grouping or missed negation can still produce structurally valid FHIR.
- Ambiguous references remain unresolved rather than guessed.
- Unsupported nested structures are refused, not approximated.
- Required defaults are policy assertions, not facts grounded in the narrative.
- Machine provenance never implies human review.
[ developers welcome ]
Built in the open.
Better with you.
Help shape practical, trustworthy healthcare interoperability. Contribute code, improve the docs, report issues, or bring a new idea.
- 01 Build features
- 02 Improve documentation
- 03 Report and fix issues
- 04 Share implementation ideas
[ one project · four services ]
Your own FHIR bridge.
One Railway deploy.
Launch the API, private HL7 validator, PostgreSQL, and Redis together. Generated secrets and database bootstrap are configured for you.
Deploy on Railway
- 01FHIR at Will APIPublic HTTPS endpoint
- 02HL7 ValidatorPrivate, pinned sidecar
- 03PostgreSQLRLS-enforced application role
- 04RedisPrivate cache and coordination