measure-evaluate: drive the demo from the installed FHIR package

[aleksandrkislitsyn]

The sample hardcoded a 12-measure registry and rebuilt its SQL layer from files in this repo. Both are now read from whatever package Aidbox has installed, so the same app serves a 12-measure package or a larger private one with no code change.

Measure catalog from Aidbox

app/catalog.py discovers measures from their SQLQuery Library resources (<measure>-summary / -per-patient / -evidence) and resolves each one's ViewDefinition dependencies transitively through relatedArtifact, dispatching on the canonical url (/ViewDefinition/ vs /Library/). Measure resources are optional metadata rather than a gate — a package shipping Libraries alone still yields a full catalog.

Measure/$evaluate-measure no longer rejects measures missing from service/measures-registry.json. Previously any measure outside those 12 returned:

Unknown measure: cms1017. Available: cms1154, cms124, … cms75

The registry now only supplies optional extras (exc_type, supported_version).

Materialization from the UI

POST /api/materialize builds the runtime state, per measure or for all of them:

1. $materialize the needed ViewDefinitions into sof.* tables
2. run the package's setup-NN-* scripts (terminology scaffolding, indexes)
3. flatten far.valueset into sof.concept — the one step no package resource can express, since Aidbox keeps ValueSets in a registry the SoF engine cannot see

Views already present are skipped, so measures sharing views cost nothing on a second run. Buttons: Materialize all in the sidebar and overview, Rematerialize <MEASURE> in the measure detail header. Setup scripts run statement-by-statement so an index for a table this pass did not create cannot roll back the rest.

No wrapper views are created. Aidbox inlines the package's sql-view Libraries as CTEs when running a SQLQuery, so the measure SQL's bare patient_flat resolves without any database view — verified by dropping all 22 and re-running measures to identical numbers, while raw $sql on the same name still errors.

Demo app

• Served at http://localhost:8090 by the app container; no separate python3 -m http.server step.
• All local SQL removed — summary, per-patient and evidence come from the Libraries via $sqlquery-run. demo/measure-sql.json is deleted.
• Sidebar filter (id substring + All / Open gaps / Needs setup) for navigating a large measure list; the overview grid follows it.

Setup

setup.py is replaced by load-demo-data.py, which only loads the sample bundles. Its other five steps either duplicated the package or actively conflicted with it — recreating the superseded wrapper layer, wiping sof.concept — and it only knew the 12 registry measures.

The init bundle now inlines data/*-clinical-data.json, so a fresh box comes up with patients loaded and needs no data step. It is a batch, so one rejected resource cannot sink the load; pass --no-demo-data for an Aidbox holding real data. init.json is generated and gitignored (multi-megabyte once the data is inlined) and README step 1 builds it alongside the package .tgz.

sql/01-wrapper-views.sql and sql/02-shared-exclusions.sql are dropped — the package ships both layers now.

Sample-data fixes

Two resources failed validation on load, and the Organization took two Coverage resources with it:

Resource	Defect
Condition.clinicalStatus (cms143)	display 'InActive', should be 'Inactive'
Organization/example (cms165)	neither name nor identifier, violates org-1

A fresh boot now logs zero batch errors; Coverage goes 31 → 33.

Verification

Full teardown (docker compose down -v), rebuilt both artifacts from the README, fresh boot:

batch errors: 0
patients: 485   coverage: 33   organization: 16

materialize: 22 tables, 2 setup scripts, 115,201 concepts, 0 failures
cms130  ip=204 exc=80 num=8  open=116
cms131  ip=57  exc=26 num=11 open=20
cms165  ip=75  exc=42 num=2  open=31

Demo driven in a headless browser: measures listed, live gap counts, filter and materialize buttons working, no JS errors.

🤖 Generated with Claude Code