This project contains scripts for fetching FHIR resource definitions from official sources and leveraging AI (Google Gemini) to analyze and compare R4 and R6 versions.
- Bun Runtime: These scripts are written in TypeScript and designed to be run with Bun. Installation instructions: https://bun.sh/docs/installation
- Google Gemini API Key: You need an API key for Google Gemini for the
generate_resource_summaries.tsandanalyze_difference.tsscripts.- The scripts require the
GEMINI_API_KEYenvironment variable to be set. - Methods to set the API key: Bun automatically loads
.envfiles from the current working directory. The recommended way is to place a.envfile in this project root.- Using a
.envfile (Recommended): Create a file named.envin the project root directory with the content:Ensure this file is in yourGEMINI_API_KEY="YOUR_API_KEY_HERE"
.gitignore. - Directly in the shell (before running commands):
export GEMINI_API_KEY="YOUR_API_KEY_HERE"
- Prefixing the command:
GEMINI_API_KEY="YOUR_API_KEY_HERE" bun run ./script_name.ts <ResourceName>
- Using a
- The scripts require the
When run from this project root, these scripts will generate output in the following directories:
sources/r4/: Stores fetched HTML excerpts for R4 resources.sources/r6/: Stores fetched HTML excerpts for R6/build resources.summaries/: Contains the per-version resource summaries generated by Gemini.summaries/r4/<ResourceName>.mdsummaries/r6/<ResourceName>.md
analysis/: Contains the final difference analysis generated by Gemini.analysis/diff/<ResourceName>.md
Example/template files used by these scripts are located within ./examples/.
All scripts below are designed to be invoked from this project root directory.
-
generate_fhir_doc.ts:- Purpose: Fetches HTML content for a specified FHIR resource.
- Output: Saves HTML segments to
sources/r4/andsources/r6/. - Usage:
bun run ./generate_fhir_doc.ts <ResourceName>
-
generate_resource_summaries.ts:- Purpose: Generates structured markdown summaries for R4 and R6 using Gemini.
- Requires:
GEMINI_API_KEYto be set. Input HTML files fromgenerate_fhir_doc.ts(insources/). - Output: Saves markdown files to
summaries/r4/andsummaries/r6/. - Usage:
bun run ./generate_resource_summaries.ts <ResourceName>
-
analyze_difference.ts:- Purpose: Generates a markdown report comparing the R4 and R6 summaries using Gemini.
- Requires:
GEMINI_API_KEYto be set. Input markdown summaries fromgenerate_resource_summaries.ts(insummaries/). - Output: Saves a markdown difference report to
analysis/diff/. - Usage:
bun run ./analyze_difference.ts <ResourceName>
-
fetch_us_core.ts:- Purpose: Contains a hardcoded list of US Core FHIR resource names. Can be run independently to execute only the
generate_fhir_doc.tsstep for all listed US Core resources. - Usage (for generating only HTML docs for US Core):
bun run ./fetch_us_core.ts
- Purpose: Contains a hardcoded list of US Core FHIR resource names. Can be run independently to execute only the
-
analyze_us_core_migration.ts:- Purpose: Analyzes the migration impact for each US Core profile found in
../us-core-profiles/json/. For each profile, it considers its definition, its inheritance hierarchy (other US Core profiles), and the R4->R6 changes of its ultimate base FHIR resource type (e.g., Observation, Patient) fetched from../analysis/diff/. - Requires:
GEMINI_API_KEYto be set. Input JSON profile definitions in../us-core-profiles/json/. Base resource diffs in../analysis/diff/. Profile HTML in../us-core-profiles/html/(optional, for context). - Output: Saves detailed markdown analysis reports to
../analysis/us-core-migration/<profile-id>.md. - Usage:
bun run ./analyze_us_core_migration.ts
- Purpose: Analyzes the migration impact for each US Core profile found in
-
run_fhir_comparison.ts:- Purpose: Main orchestrator script. Runs the full fetch -> summarize -> diff pipeline for all resources listed in
fetch_us_core.ts. - Requires:
GEMINI_API_KEYto be set. - Usage:
bun run ./run_fhir_comparison.ts
- Purpose: Main orchestrator script. Runs the full fetch -> summarize -> diff pipeline for all resources listed in
The recommended way to process the full list of base FHIR resources (e.g., US Core base types) through the fetch/summarize/diff pipeline is by using the run_fhir_comparison.ts script:
bun run ./run_fhir_comparison.tsThis script handles dependency checks and skips already completed steps for the base resource analysis.
To generate the specific US Core profile migration analyses (after running the above), use:
bun run ./analyze_us_core_migration.tsEach primary script (generate_fhir_doc.ts, generate_resource_summaries.ts, analyze_difference.ts, analyze_us_core_migration.ts) exports an async function (e.g., ensureFhirDocHtml) that contains its core logic, or performs its analysis directly in its main/helper functions. Where applicable, functions are designed to be idempotent (skip if output exists) and handle their own dependencies. When run directly via CLI, the main function within each script calls its respective ensure... function or performs its primary task.