adelelsayed1991 commited on
Commit
3434a32
·
verified ·
1 Parent(s): 143f318

Add app.py, requirements.txt, schema.sql, README.md to serve the fhirsql model via ZeroGPU

Browse files
Files changed (4) hide show
  1. README.md +16 -8
  2. app.py +91 -0
  3. requirements.txt +5 -0
  4. schema.sql +245 -0
README.md CHANGED
@@ -1,15 +1,23 @@
1
  ---
2
- title: Fhirsql Reasoning Sql Adapters
3
- emoji: 📈
4
- colorFrom: pink
5
  colorTo: green
6
  sdk: gradio
7
- sdk_version: 6.28.0
8
- python_version: '3.12'
9
  app_file: app.py
10
  pinned: false
11
- license: cc-by-4.0
12
- short_description: fhirsql-reasoning-sql-adapters
13
  ---
14
 
15
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
+ title: fhirsql-reasoning-sql-adapters
3
+ emoji: 🏥
4
+ colorFrom: blue
5
  colorTo: green
6
  sdk: gradio
 
 
7
  app_file: app.py
8
  pinned: false
 
 
9
  ---
10
 
11
+ # fhirsql-reasoning-sql
12
+
13
+ Translates a natural-language hospital question into a single DuckDB SQL
14
+ statement, using a DoRA/LoRA fine-tune of Qwen2.5-Coder-14B-Instruct
15
+ (adapters: `adelelsayed1991/fhirsql-reasoning-sql-adapters`) against the
16
+ fhirsql project's FHIR-derived schema.
17
+
18
+ Runs on ZeroGPU. Returns the literal string `UNANSWERABLE` when the
19
+ question cannot be answered from the schema shown to the model.
20
+
21
+ Reproduces the exact system prompt and chat-template format used during
22
+ training (see the `fhirsql` project's `sft_train.ipynb`) so generations
23
+ here match the fine-tuning distribution.
app.py ADDED
@@ -0,0 +1,91 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Gradio ZeroGPU Space serving the fhirsql-reasoning-sql-adapters model.
2
+
3
+ Reproduces the exact prompt format used during fine-tuning (see
4
+ C:\\dev\\fhirsql\\sft_train.ipynb, SYSTEM_PROMPT_TEMPLATE / build_messages /
5
+ load_schema_ddl): a system message containing the abstention token and the
6
+ DuckDB schema DDL, a user message containing the raw question, and greedy
7
+ decoding for a single SQL statement (or the literal string UNANSWERABLE).
8
+ """
9
+
10
+ import spaces
11
+ import gradio as gr
12
+ from transformers import AutoModelForCausalLM, AutoTokenizer
13
+ from peft import PeftModel
14
+
15
+ BASE_MODEL = "Qwen/Qwen2.5-Coder-14B-Instruct"
16
+ ADAPTER = "adelelsayed1991/fhirsql-reasoning-sql-adapters"
17
+ ABSTENTION_TOKEN = "UNANSWERABLE"
18
+ MAX_NEW_TOKENS = 512
19
+
20
+ SYSTEM_PROMPT_TEMPLATE = """You are a clinical data analyst who translates natural-language hospital \
21
+ questions into a single DuckDB SQL statement, run against the schema below.
22
+
23
+ Rules:
24
+ - Output ONLY the SQL statement. No markdown fences, no explanation, no leading/trailing text.
25
+ - If the question cannot be answered from this schema -- the data it needs genuinely doesn't \
26
+ exist here -- output exactly the single word: {abstention_token}
27
+ - Do not guess or approximate an answer using unrelated columns when the real field is absent.
28
+
29
+ Schema:
30
+ {schema_ddl}"""
31
+
32
+
33
+ def load_schema_ddl(schema_path: str) -> str:
34
+ """Load the DuckDB schema DDL, dropping the changelog header above the first CREATE TABLE."""
35
+ text = open(schema_path, encoding="utf-8").read()
36
+ idx = text.index("CREATE TABLE")
37
+ return text[idx:].strip()
38
+
39
+
40
+ SCHEMA_DDL = load_schema_ddl("schema.sql")
41
+ SYSTEM_PROMPT = SYSTEM_PROMPT_TEMPLATE.format(
42
+ abstention_token=ABSTENTION_TOKEN, schema_ddl=SCHEMA_DDL
43
+ )
44
+
45
+ tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL)
46
+ base_model = AutoModelForCausalLM.from_pretrained(BASE_MODEL, torch_dtype="auto")
47
+ model = PeftModel.from_pretrained(base_model, ADAPTER)
48
+ model.to("cuda")
49
+ model.eval()
50
+
51
+
52
+ @spaces.GPU(duration=30)
53
+ def generate_sql(question: str) -> str:
54
+ """Generate a single DuckDB SQL statement for a natural-language question.
55
+
56
+ Returns the literal string "UNANSWERABLE" if the model determines the
57
+ question cannot be answered from the schema it was shown.
58
+ """
59
+ messages = [
60
+ {"role": "system", "content": SYSTEM_PROMPT},
61
+ {"role": "user", "content": question},
62
+ ]
63
+ prompt_text = tokenizer.apply_chat_template(
64
+ messages, tokenize=False, add_generation_prompt=True
65
+ )
66
+ inputs = tokenizer(prompt_text, return_tensors="pt", add_special_tokens=False).to("cuda")
67
+ prompt_len = inputs["input_ids"].shape[1]
68
+
69
+ output_ids = model.generate(
70
+ **inputs,
71
+ max_new_tokens=MAX_NEW_TOKENS,
72
+ do_sample=False,
73
+ pad_token_id=tokenizer.eos_token_id,
74
+ )
75
+ return tokenizer.decode(output_ids[0][prompt_len:], skip_special_tokens=True).strip()
76
+
77
+
78
+ demo = gr.Interface(
79
+ fn=generate_sql,
80
+ inputs=gr.Text(label="Clinical question", lines=2),
81
+ outputs=gr.Text(label="Generated SQL"),
82
+ title="fhirsql-reasoning-sql",
83
+ description=(
84
+ "Translates a natural-language hospital question into DuckDB SQL "
85
+ "against the fhirsql schema. Returns UNANSWERABLE if the question "
86
+ "cannot be answered from that schema."
87
+ ),
88
+ )
89
+
90
+ if __name__ == "__main__":
91
+ demo.launch()
requirements.txt ADDED
@@ -0,0 +1,5 @@
 
 
 
 
 
 
1
+ gradio>=4.0
2
+ transformers>=4.45
3
+ peft>=0.13
4
+ torch>=2.8
5
+ accelerate>=0.34
schema.sql ADDED
@@ -0,0 +1,245 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ -- FHIR-SQL fine-tuning study: frozen core clinical schema (Phase 0.3)
2
+ --
3
+ -- This is the benchmark-facing schema shown to models in every prompt (Phase 1
4
+ -- benchmark authoring, Phase 4 SFT prompt format, Phase 5 RL reward execution).
5
+ -- It is a deliberately curated subset of the full flattened data -- see
6
+ -- METHODOLOGY_LOG.md for the two-layer rationale (full fidelity in the
7
+ -- database, curated scope in what models see) and the token-cost/scope reasoning.
8
+ --
9
+ -- Generated from the actual column types DuckDB inferred when loading
10
+ -- data/train.duckdb, not hand-assumed -- see scripts/flatten_to_duckdb.py for
11
+ -- the extraction logic that produces this shape.
12
+ --
13
+ -- Version stamp:
14
+ -- Date frozen: 2026-08-02
15
+ -- Synthea build: v3.4.0-18-ga07a65555 (git-describe string embedded in
16
+ -- generated Patient resources; downloaded from the
17
+ -- GitHub v4.0.0 release page -- see methodology log)
18
+ -- Train population: 18,999 patients (target was ~15,000; see log for
19
+ -- per-batch seed/state/age-bracket design)
20
+ -- Held-out population: 6,383 patients (target was ~5,000)
21
+ -- Populations verified disjoint: 0 patient_id overlap between train and held-out
22
+ --
23
+ -- Every number produced downstream (benchmark accuracy, cost tables, etc.) is
24
+ -- relative to this artifact. Do not modify this file without a new version
25
+ -- stamp and a note on what changed and why.
26
+ --
27
+ -- Revision 2026-08-02b: added practitioner_npi/practitioner_name to encounter
28
+ -- and medication_request (superseded by the rename in 2026-08-03, see below).
29
+ -- Root cause: Synthea DOES generate provider attribution
30
+ -- (Encounter.participant, MedicationRequest.requester), it was simply not
31
+ -- extracted in the initial flatten pass -- confirmed by inspecting raw NDJSON
32
+ -- directly, not assumed. Note: Synthea always generates exactly one
33
+ -- participant per encounter, typed "primary performer" only -- it does not
34
+ -- distinguish admitting/attending/consulting roles, so those remain
35
+ -- unanswerable regardless of schema design. Procedure.performer is never
36
+ -- populated by this Synthea version (confirmed: 0/29,947 in a full batch) --
37
+ -- procedure-level provider attribution is not available at all.
38
+ --
39
+ -- Revision 2026-08-03: FULL COLUMN RENAME to align with FHIR element names,
40
+ -- per explicit user request ("ensure llms have an easier task" mapping
41
+ -- clinical-language understanding to schema). Every core table's gold SQL
42
+ -- (2,514 unique statements) and all 10,056 training rows were regenerated
43
+ -- from scratch to match -- this was a deliberate, acknowledged-cost decision,
44
+ -- not an incremental patch. Naming convention adopted:
45
+ -- - Primary key: `id` (matches every FHIR resource's own `id` element).
46
+ -- - Foreign keys: `patient_id`, `encounter_id` (SQL join-key convention;
47
+ -- not itself a literal FHIR field name, since FHIR expresses this via
48
+ -- subject/patient/encounter *reference* elements, but resolving those
49
+ -- references to a flat join key needs a name, and `<type>_id` is the
50
+ -- clearest SQL-side compromise).
51
+ -- - Primary coding triple on each table: `code`, `system`, `display`
52
+ -- (matches FHIR Coding.code/.system/.display exactly).
53
+ -- - Where a resource's own field name differs from the generic "code"
54
+ -- (Encounter.type, Encounter.class, Immunization.vaccineCode,
55
+ -- CarePlan.category), the coding triple is prefixed with that field name
56
+ -- instead: `type_code/type_system/type_display`, `class_code`,
57
+ -- `vaccineCode/vaccineCode_system/vaccineCode_display`,
58
+ -- `category_code/category_system/category_display`.
59
+ -- - Status/descriptive fields: exact camelCase FHIR element names
60
+ -- (clinicalStatus, verificationStatus, intent, criticality).
61
+ -- - Dates: exact FHIR element names (birthDate, deceasedDateTime,
62
+ -- onsetDateTime, abatementDateTime, recordedDate, effectiveDateTime,
63
+ -- authoredOn, performedDateTime, occurrenceDateTime); Period-typed
64
+ -- start/end kept as `period_start`/`period_end` (Period.start/.end).
65
+ -- - value[x]: `valueQuantity`, `unit` (Quantity.unit), `valueCodeableConcept`
66
+ -- (+ `valueCodeableConcept_system`), `valueString`.
67
+ -- - Provider-reference columns renamed to match the FHIR field they were
68
+ -- extracted from: `requester_npi`/`requester_name` on medication_request
69
+ -- (from MedicationRequest.requester), `participant_npi`/`participant_name`
70
+ -- on encounter (from Encounter.participant).
71
+ -- - New: `race`/`ethnicity` on patient (US-Core extensions, previously
72
+ -- deferred as "untested SQL," now implemented and tested -- see
73
+ -- scripts/flatten_to_duckdb.py's us_core_ext_text macro).
74
+ -- - New table: `imaging_study` (ImagingStudy resource), promoted from the
75
+ -- non-benchmark-facing extra_ tables per explicit user request, to make
76
+ -- radiology-volume questions answerable (department-level radiology
77
+ -- questions remain unanswerable -- no department/service-line concept
78
+ -- exists anywhere in Synthea's FHIR output).
79
+ --
80
+ -- Revision 2026-08-05: secondary (ART) indexes added directly to train.duckdb and
81
+ -- heldout.duckdb (not a change to this file -- no column/table/logical change, only a
82
+ -- physical one) on the coding-triple columns (condition.code, observation.code,
83
+ -- medication_request.code, encounter.class_code, encounter.type_code, procedure.code,
84
+ -- immunization.vaccineCode, allergy.code, careplan.category_code, diagnostic_report.code,
85
+ -- imaging_study.procedureCode, imaging_study.modality), to support Phase 5's execution-
86
+ -- efficiency reward term. patient_id/encounter_id deliberately NOT indexed -- DuckDB's ART
87
+ -- index isn't used by the optimizer to accelerate joins, only point/highly-selective
88
+ -- (<0.1% of rows) filters, confirmed before deciding what to index. Re-verified all 2,707
89
+ -- unique gold SQL statements return identical results before/after on train.duckdb (24
90
+ -- structural smoke-tests on heldout.duckdb, which has no gold SQL of its own) -- see
91
+ -- METHODOLOGY_LOG.md, "Reinforcement learning setup" for the two real issues that
92
+ -- re-verification surfaced (a latent NULL-sort bug in the eval/reward comparison helper,
93
+ -- now fixed; non-deterministic tie-breaking in 7 archetype templates, not yet fixed).
94
+
95
+ CREATE TABLE patient (
96
+ id VARCHAR PRIMARY KEY,
97
+ gender VARCHAR,
98
+ birthDate DATE,
99
+ deceasedDateTime TIMESTAMP,
100
+ maritalStatus VARCHAR,
101
+ state VARCHAR, -- address[0].state
102
+ city VARCHAR, -- address[0].city
103
+ postalCode VARCHAR, -- address[0].postalCode
104
+ race VARCHAR, -- US-Core race extension, ombCategory text
105
+ ethnicity VARCHAR -- US-Core ethnicity extension, ombCategory text
106
+ );
107
+
108
+ CREATE TABLE condition (
109
+ id VARCHAR PRIMARY KEY,
110
+ patient_id VARCHAR, -- join key -> patient.id
111
+ encounter_id VARCHAR, -- join key -> encounter.id
112
+ code VARCHAR,
113
+ system VARCHAR, -- kept alongside code deliberately: code-system confusion (SNOMED vs ICD-10 vs LOINC) is a failure mode to observe
114
+ display VARCHAR,
115
+ clinicalStatus VARCHAR,
116
+ verificationStatus VARCHAR,
117
+ onsetDateTime TIMESTAMP,
118
+ abatementDateTime TIMESTAMP,
119
+ recordedDate TIMESTAMP
120
+ );
121
+
122
+ CREATE TABLE observation (
123
+ id VARCHAR PRIMARY KEY,
124
+ patient_id VARCHAR, -- join key -> patient.id
125
+ encounter_id VARCHAR, -- join key -> encounter.id
126
+ code VARCHAR,
127
+ system VARCHAR,
128
+ display VARCHAR,
129
+ category VARCHAR,
130
+ status VARCHAR,
131
+ effectiveDateTime TIMESTAMP,
132
+ valueQuantity DOUBLE, -- value[x] flattened per plan design rule
133
+ unit VARCHAR,
134
+ valueCodeableConcept VARCHAR,
135
+ valueCodeableConcept_system VARCHAR, -- code-system pairing for the value itself, when value[x] is coded
136
+ valueString VARCHAR
137
+ );
138
+
139
+ CREATE TABLE medication_request (
140
+ id VARCHAR PRIMARY KEY,
141
+ patient_id VARCHAR, -- join key -> patient.id
142
+ encounter_id VARCHAR, -- join key -> encounter.id
143
+ code VARCHAR,
144
+ system VARCHAR,
145
+ display VARCHAR,
146
+ status VARCHAR,
147
+ intent VARCHAR,
148
+ authoredOn TIMESTAMP,
149
+ requester_npi VARCHAR, -- prescribing physician's NPI (from MedicationRequest.requester)
150
+ requester_name VARCHAR
151
+ );
152
+
153
+ CREATE TABLE encounter (
154
+ id VARCHAR PRIMARY KEY,
155
+ patient_id VARCHAR, -- join key -> patient.id
156
+ class_code VARCHAR, -- Encounter.class.code (AMB/EMER/IMP/HH/VR)
157
+ type_code VARCHAR, -- Encounter.type[0].coding[0]
158
+ type_system VARCHAR,
159
+ type_display VARCHAR,
160
+ status VARCHAR,
161
+ period_start TIMESTAMP,
162
+ period_end TIMESTAMP,
163
+ reasonCode VARCHAR,
164
+ participant_npi VARCHAR, -- primary-performer physician's NPI (Synthea models only one role per encounter, not admitting/attending/etc separately)
165
+ participant_name VARCHAR
166
+ );
167
+
168
+ CREATE TABLE procedure (
169
+ id VARCHAR PRIMARY KEY,
170
+ patient_id VARCHAR, -- join key -> patient.id
171
+ encounter_id VARCHAR, -- join key -> encounter.id
172
+ code VARCHAR,
173
+ system VARCHAR,
174
+ display VARCHAR,
175
+ status VARCHAR,
176
+ performedDateTime TIMESTAMP
177
+ -- Note: Procedure.performer (physician who performed it) is never populated
178
+ -- by this Synthea version (confirmed 0/29,947) -- not available at all.
179
+ );
180
+
181
+ CREATE TABLE immunization (
182
+ id VARCHAR PRIMARY KEY,
183
+ patient_id VARCHAR, -- join key -> patient.id
184
+ encounter_id VARCHAR, -- join key -> encounter.id
185
+ vaccineCode VARCHAR,
186
+ vaccineCode_system VARCHAR,
187
+ vaccineCode_display VARCHAR,
188
+ status VARCHAR,
189
+ occurrenceDateTime TIMESTAMP
190
+ );
191
+
192
+ CREATE TABLE allergy (
193
+ id VARCHAR PRIMARY KEY,
194
+ patient_id VARCHAR, -- join key -> patient.id
195
+ code VARCHAR,
196
+ system VARCHAR,
197
+ display VARCHAR,
198
+ clinicalStatus VARCHAR,
199
+ verificationStatus VARCHAR,
200
+ category VARCHAR,
201
+ criticality VARCHAR,
202
+ recordedDate TIMESTAMP
203
+ );
204
+
205
+ CREATE TABLE careplan (
206
+ id VARCHAR PRIMARY KEY,
207
+ patient_id VARCHAR, -- join key -> patient.id
208
+ encounter_id VARCHAR, -- join key -> encounter.id
209
+ category_code VARCHAR, -- CarePlan.category[0].coding[0]
210
+ category_system VARCHAR,
211
+ category_display VARCHAR,
212
+ status VARCHAR,
213
+ period_start TIMESTAMP,
214
+ period_end TIMESTAMP
215
+ );
216
+
217
+ CREATE TABLE diagnostic_report (
218
+ id VARCHAR PRIMARY KEY,
219
+ patient_id VARCHAR, -- join key -> patient.id
220
+ encounter_id VARCHAR, -- join key -> encounter.id
221
+ code VARCHAR,
222
+ system VARCHAR,
223
+ display VARCHAR,
224
+ category VARCHAR,
225
+ status VARCHAR,
226
+ effectiveDateTime TIMESTAMP
227
+ );
228
+
229
+ CREATE TABLE imaging_study (
230
+ id VARCHAR PRIMARY KEY,
231
+ patient_id VARCHAR, -- join key -> patient.id
232
+ encounter_id VARCHAR, -- join key -> encounter.id
233
+ status VARCHAR,
234
+ started TIMESTAMP,
235
+ numberOfSeries INTEGER,
236
+ numberOfInstances INTEGER,
237
+ procedureCode VARCHAR, -- the imaging procedure performed, e.g. "Plain X-ray of ankle region"
238
+ procedureCode_system VARCHAR,
239
+ procedureCode_display VARCHAR,
240
+ modality VARCHAR, -- DICOM modality code, e.g. "DX" = Digital Radiography (from series[0])
241
+ modality_system VARCHAR,
242
+ modality_display VARCHAR,
243
+ bodySite VARCHAR, -- from series[0]
244
+ bodySite_display VARCHAR
245
+ );