RefQA Gemma-3-27B LoRA adapter (v0.7) — clean release

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,69 @@
+---
+license: gemma
+base_model: google/gemma-3-27b-it
+library_name: peft
+pipeline_tag: text-generation
+tags:
+- lora
+- peft
+- sft
+- medical
+- clinical-nlp
+- citation
+- refqa
+---
+
+# RefQA — Gemma-3-27B mixed adapter (v0.7)
+
+A LoRA adapter that fine-tunes **google/gemma-3-27b-it** on a mix of medical instruction data and the [RefQA](https://doi.org/10.5281/zenodo.20805692) CitationQA data. It learns the RefQA CitationQA task while retaining general medical question-answering ability.
+
+## Task
+
+Two capabilities from one adapter:
+1. Structured **CitationQA** generation on the RefQA schema (given the RefQA system prompt and a citation context), and
+2. Retained general medical question answering.
+
+## Results
+
+- Final `eval_loss` 0.215, token accuracy 92.6% (2 epochs / 50,224 steps)
+- Out-of-domain evaluation: **PubMedQA 74.10%**, **MedQA 24.59%**
+
+These numbers are reported as measured, not as a claim of state of the art.
+
+## Limitations
+
+- Research artifact. No clinical validation; not for clinical decision-making.
+- The CitationQA behavior requires the RefQA system prompt and chat format (below); without them the structured output is not reproduced.
+
+## Training
+
+- Base: `google/gemma-3-27b-it` (snapshot `005ad340`)
+- Data: medical instruction mix + RefQA
+- LoRA: r=64, alpha=128, dropout=0.05; language-model attention and MLP projections
+- 2 epochs / 50,224 steps
+- Stack: torch 2.11 (cu130), transformers 5.7, peft 0.19, trl 1.3
+
+## How to use
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+adapter = "taejoon89/refqa"
+base = "google/gemma-3-27b-it"   # gated: accept the Gemma license first
+
+tok = AutoTokenizer.from_pretrained(adapter)
+model = AutoModelForCausalLM.from_pretrained(base, torch_dtype="auto", device_map="auto")
+model = PeftModel.from_pretrained(model, adapter)
+```
+
+For CitationQA generation, the system prompt and input builder are in `extract_qa_glm_v03.py` at https://github.com/jin-0311/refqa. The training chat template is included here as `chat_template.jinja`.
+
+## Dataset and code
+
+- Dataset: RefQA — https://doi.org/10.5281/zenodo.20805692
+- Pipeline code: https://github.com/jin-0311/refqa
+
+## License
+
+Use is governed by the base model's license (Gemma Terms of Use). You must accept the Gemma license to download and use the base model.

adapter_config.json

@@ -0,0 +1,40 @@
+{
+  "alora_invocation_tokens": null,
+  "alpha_pattern": {},
+  "arrow_config": null,
+  "auto_mapping": null,
+  "base_model_name_or_path": "google/gemma-3-27b-it",
+  "bias": "none",
+  "corda_config": null,
+  "ensure_weight_tying": false,
+  "eva_config": null,
+  "exclude_modules": null,
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": true,
+  "layer_replication": null,
+  "layers_pattern": null,
+  "layers_to_transform": null,
+  "loftq_config": {},
+  "lora_alpha": 128,
+  "lora_bias": false,
+  "lora_dropout": 0.05,
+  "lora_ga_config": null,
+  "megatron_config": null,
+  "megatron_core": "megatron.core",
+  "modules_to_save": null,
+  "peft_type": "LORA",
+  "peft_version": "0.19.1",
+  "qalora_group_size": 16,
+  "r": 64,
+  "rank_pattern": {},
+  "revision": null,
+  "target_modules": ".*language_model\\.layers\\.\\d+\\.(?:self_attn|mlp)\\.(?:q_proj|k_proj|v_proj|o_proj|up_proj|down_proj|gate_proj)$",
+  "target_parameters": null,
+  "task_type": "CAUSAL_LM",
+  "trainable_token_indices": null,
+  "use_bdlora": null,
+  "use_dora": false,
+  "use_qalora": false,
+  "use_rslora": false
+}

adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4c0666d4cccbae4147f6ef46e1ebc4b00e209ecb127f02b8068006da55e59e69
+size 1816396048

chat_template.jinja

@@ -0,0 +1 @@
+{{ bos_token }}{%- if messages[0]['role'] == 'system' -%}  {%- set first_user_prefix = messages[0]['content'] + '\n\n' -%}  {%- set loop_messages = messages[1:] -%}{%- else -%}  {%- set first_user_prefix = '' -%}  {%- set loop_messages = messages -%}{%- endif -%}{%- for message in loop_messages -%}  {%- if (message['role'] == 'user') != (loop.index0 % 2 == 0) -%}    {{ raise_exception('Conversation roles must alternate user/assistant/user/assistant/...') }}  {%- endif -%}  {%- if message['role'] == 'assistant' -%}    {{ '<start_of_turn>model\n' }}    {% generation %}{{ message['content'] | trim }}{{ '<end_of_turn>\n' }}    {% endgeneration %}  {%- else -%}    {{ '<start_of_turn>' + message['role'] + '\n' + (first_user_prefix if loop.first else '') + (message['content'] | trim) + '<end_of_turn>\n' }}  {%- endif -%}{%- endfor -%}{%- if add_generation_prompt -%}  {{ '<start_of_turn>model\n' }}{%- endif -%}

demo_refqa_gemma3_v07.ipynb

@@ -0,0 +1,207 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7093007e",
+   "metadata": {},
+   "source": [
+    "# RefQA Gemma-3-27B (v0.7) adapter — usage demo\n",
+    "\n",
+    "This notebook shows how to load and use the **`refqa-gemma3-27b-mixed-v07`** LoRA adapter:\n",
+    "inspect the adapter, load the tokenizer, build a CitationQA prompt, and (optionally) run generation.\n",
+    "\n",
+    "**Requirements**\n",
+    "- Adapter files (this repo): `adapter_model.safetensors`, `adapter_config.json`, tokenizer, `chat_template.jinja`, `v03_system_prompt.txt`.\n",
+    "- For **generation only**: the gated base model `google/gemma-3-27b-it` (accept its license and log in with a HF token) and a GPU (~16 GB in 4-bit, or ~54 GB in bf16).\n",
+    "\n",
+    "The input/config/prompt cells run without the base model. The generation cell is guarded by `RUN_GENERATION`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cc715efe",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json, os\n",
+    "\n",
+    "ADAPTER = \".\"                       # this repo/folder holds the adapter\n",
+    "BASE    = \"google/gemma-3-27b-it\"   # gated base; needed only for generation\n",
+    "RUN_GENERATION = True               # set False to skip actual generation\n",
+    "\n",
+    "import transformers\n",
+    "print(\"transformers\", transformers.__version__)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "904ac805",
+   "metadata": {},
+   "source": [
+    "## 1. Inspect the adapter"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "91ee8ec8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cfg = json.load(open(os.path.join(ADAPTER, \"adapter_config.json\")))\n",
+    "print(\"base_model :\", cfg[\"base_model_name_or_path\"])\n",
+    "print(\"peft_type  :\", cfg[\"peft_type\"], \"| task:\", cfg[\"task_type\"])\n",
+    "print(\"LoRA r     :\", cfg[\"r\"], \"| alpha:\", cfg[\"lora_alpha\"], \"| dropout:\", cfg[\"lora_dropout\"])\n",
+    "print(\"targets    :\", cfg[\"target_modules\"])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a88ff894",
+   "metadata": {},
+   "source": [
+    "## 2. Load the tokenizer (no base model needed)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f3ad3bed",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from transformers import AutoTokenizer\n",
+    "tok = AutoTokenizer.from_pretrained(ADAPTER)\n",
+    "print(type(tok).__name__, \"| vocab size:\", tok.vocab_size)\n",
+    "print(\"has chat template:\", tok.chat_template is not None)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ee2838ec",
+   "metadata": {},
+   "source": [
+    "## 3. Build a CitationQA prompt\n",
+    "\n",
+    "The model was trained as `system` (the RefQA v0.3 system prompt) + `user` (one citation context)\n",
+    "→ `assistant` (a strict-JSON CitationQA object). The exact input builder is `build_user_prompt`\n",
+    "in `extract_qa_glm_v03.py` (https://github.com/jin-0311/refqa). Below is a compact illustrative\n",
+    "rendering; the system prompt bundled here (`v03_system_prompt.txt`) is the real one."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "70530163",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "SYSTEM = open(os.path.join(ADAPTER, \"v03_system_prompt.txt\")).read()\n",
+    "\n",
+    "# One illustrative citation context (citing paper A cites cited paper B).\n",
+    "record = {\n",
+    "    \"citing\": {\"pmcid\": \"PMC0000000\", \"title\": \"Example citing clinical study\"},\n",
+    "    \"context\": {\n",
+    "        \"imrad\": \"Introduction\",\n",
+    "        \"evidence_sentence\": \"Prior work reported that drug X reduced 30-day mortality in sepsis patients [12].\",\n",
+    "    },\n",
+    "    \"cited\": {\n",
+    "        \"pmid\": \"11111111\",\n",
+    "        \"title\": \"Randomized trial of drug X in sepsis\",\n",
+    "        \"abstract\": \"In a randomized controlled trial of 480 adults with sepsis, drug X reduced \"\n",
+    "                    \"30-day mortality from 28% to 19% compared with placebo (p=0.01).\",\n",
+    "    },\n",
+    "}\n",
+    "\n",
+    "def build_user_prompt(rec):\n",
+    "    c, ctx, cd = rec[\"citing\"], rec[\"context\"], rec[\"cited\"]\n",
+    "    return (\n",
+    "        f\"CITING PAPER: {c['title']} ({c['pmcid']})\\n\"\n",
+    "        f\"SECTION: {ctx['imrad']}\\n\"\n",
+    "        f\"EVIDENCE SENTENCE: {ctx['evidence_sentence']}\\n\\n\"\n",
+    "        f\"CITED PAPER: {cd['title']} (PMID {cd['pmid']})\\n\"\n",
+    "        f\"CITED ABSTRACT: {cd['abstract']}\\n\"\n",
+    "    )\n",
+    "\n",
+    "messages = [\n",
+    "    {\"role\": \"system\", \"content\": SYSTEM},\n",
+    "    {\"role\": \"user\",   \"content\": build_user_prompt(record)},\n",
+    "]\n",
+    "\n",
+    "prompt = tok.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)\n",
+    "n_tok = len(tok(prompt).input_ids)\n",
+    "print(f\"system prompt: {len(SYSTEM)} chars | full prompt: {n_tok} tokens\\n\")\n",
+    "print(prompt[:700], \"\\n...[truncated]...\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1c25b212",
+   "metadata": {},
+   "source": [
+    "## 4. Generate (requires the base model + a HF token)\n",
+    "\n",
+    "Set `RUN_GENERATION = True` in cell 1, accept the `google/gemma-3-27b-it` license, and\n",
+    "`huggingface-cli login`. This loads the base in 4-bit (bitsandbytes) and applies the adapter."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a53030a4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if RUN_GENERATION:\n",
+    "    import torch\n",
+    "    from transformers import AutoModelForCausalLM, BitsAndBytesConfig\n",
+    "    from peft import PeftModel\n",
+    "\n",
+    "    bnb = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type=\"nf4\",\n",
+    "                             bnb_4bit_compute_dtype=torch.bfloat16)\n",
+    "    model = AutoModelForCausalLM.from_pretrained(BASE, quantization_config=bnb, device_map=\"auto\")\n",
+    "    model = PeftModel.from_pretrained(model, ADAPTER)\n",
+    "    model.eval()\n",
+    "\n",
+    "    dev = next(model.parameters()).device\n",
+    "    inputs = tok(prompt, return_tensors=\"pt\").to(dev)\n",
+    "    with torch.no_grad():\n",
+    "        out = model.generate(**inputs, max_new_tokens=768, do_sample=False)\n",
+    "    text = tok.decode(out[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)\n",
+    "    print(text)\n",
+    "    try:\n",
+    "        print(\"\\nparsed JSON keys:\", list(json.loads(text).keys()))\n",
+    "    except Exception as e:\n",
+    "        print(\"\\n(could not parse as JSON:\", e, \")\")\n",
+    "else:\n",
+    "    print(\"RUN_GENERATION = False -> skipped. Set it True with the base model + HF token to generate.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d41be1bd",
+   "metadata": {},
+   "source": [
+    "## Notes\n",
+    "\n",
+    "- This adapter only works with its exact base, `google/gemma-3-27b-it`.\n",
+    "- For faithful CitationQA output, keep the bundled `v03_system_prompt.txt` as the system message and\n",
+    "  the training chat template (`chat_template.jinja`, applied above via `apply_chat_template`).\n",
+    "- Research artifact; not for clinical use. Dataset: https://doi.org/10.5281/zenodo.20805692 · code: https://github.com/jin-0311/refqa"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "venv_RefQA",
+   "language": "python",
+   "name": "venv_refqa"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:daab2354f8a74e70d70b4d1f804939b68a8c9624dd06cb7858e52dd8970e9726
+size 33384567

tokenizer_config.json

@@ -0,0 +1,25 @@
+{
+  "backend": "tokenizers",
+  "boi_token": "<start_of_image>",
+  "bos_token": "<bos>",
+  "clean_up_tokenization_spaces": false,
+  "eoi_token": "<end_of_image>",
+  "eos_token": "<eos>",
+  "image_token": "<image_soft_token>",
+  "is_local": true,
+  "local_files_only": false,
+  "mask_token": "<mask>",
+  "model_max_length": 1000000000000000019884624838656,
+  "model_specific_special_tokens": {
+    "boi_token": "<start_of_image>",
+    "eoi_token": "<end_of_image>",
+    "image_token": "<image_soft_token>"
+  },
+  "pad_token": "<pad>",
+  "processor_class": "Gemma3Processor",
+  "sp_model_kwargs": null,
+  "spaces_between_special_tokens": false,
+  "tokenizer_class": "GemmaTokenizer",
+  "unk_token": "<unk>",
+  "use_default_system_prompt": false
+}

v03_system_prompt.txt

@@ -0,0 +1,251 @@
+PROMPT_VERSION=v0.3
+
+You are a careful biomedical/clinical research assistant. You read ONE citation context from paper A (the citing paper) where it cites paper B, and you output a strict JSON record describing what A is asserting by citing B.
+
+Critical distinctions:
+- 'attributed_claim' is what paper A asserts BY CITING B in this specific sentence. It is NOT a summary of paper B itself.
+- The cited paper's abstract is given so you can SANITY-CHECK plausibility. If B's abstract is unrelated to the citing context, set relevance_check='mismatch', support_strength='insufficient-context', explain in mismatch_reason, and write empty strings for attributed_claim / question / answer / evidence_quote_from_cited.
+- For multi-citation sentences (n_co_cited_refs > 1), focus only on what B specifically supports; do not attribute the other refs' contributions to B.
+
+WHAT vs WHY — do not confuse these two enums:
+- 'citation_purpose' is WHY A cites B. Allowed values: background / method / result-support / comparison / contrast / negative / other.
+- 'evidence_type'    is HOW the citation is presented. Allowed values: direct-quote / paraphrase / statistic / method-citation / generic-background / other.
+NEVER use a citation_purpose value (e.g. 'result-support', 'contrast', 'background') inside evidence_type. They are different slots.
+
+Hard requirements for v0.3:
+1. evidence_quote_from_cited MUST be a verbatim substring of the cited abstract (we will programmatically verify). Pick the single most relevant sentence or fragment (up to ~50 words). When evidence_type='generic-background' or relevance_check is not 'match', leave it empty.
+2. cited_study_design reflects the design of paper B inferred from its abstract. Prefer the most specific label: rct / non-randomized-trial / prospective-cohort / retrospective-cohort / case-control / cross-sectional / case-series / case-report / systematic-review / meta-analysis / guideline / preclinical. Use 'observational' ONLY as a residual bucket when the abstract makes it clear the study is observational but does NOT specify prospective vs retrospective ascertainment AND the design is not clearly cohort/case-control/cross-sectional. If the abstract clearly says 'prospective cohort' or 'retrospective review', USE THE SPECIFIC LABEL — do not default to 'observational'. Use 'preclinical' for animal/in-vitro/translational mechanism papers. Use 'other' only if truly unidentifiable.
+3. When evidence_type='statistic', fill statistic_extraction with the metric, value, CI/range, p-value, and n_subjects exactly as written. Do not infer or compute. Otherwise statistic_extraction must be null.
+
+Output requirements:
+- Return ONE JSON object — no prose, no code fences, no extra fields.
+- Field names and enum values MUST match the schema exactly.
+- Cite the cited paper as [PMID:<pmid>] inside the answer.
+- Do not invent facts that are not in evidence_sentence or cited abstract.
+
+Schema (output must validate against this):
+{
+  "$defs": {
+    "StatisticExtraction": {
+      "properties": {
+        "metric": {
+          "description": "Name of the statistic, e.g. 'median LOS', 'OR for stroke', 'sensitivity', 'in-hospital mortality'.",
+          "title": "Metric",
+          "type": "string"
+        },
+        "value": {
+          "description": "Raw value as written, including units. e.g. '2.53 days', '93 kcal/kg', '0.42'.",
+          "title": "Value",
+          "type": "string"
+        },
+        "ci_or_range": {
+          "default": "",
+          "description": "Confidence interval or range, e.g. '95% CI 1.78-2.98' or 'range 43-142'. Empty string if none reported.",
+          "title": "Ci Or Range",
+          "type": "string"
+        },
+        "p_value": {
+          "default": "",
+          "description": "p-value as written, e.g. '0.04', '<0.001'. Empty if not reported.",
+          "title": "P Value",
+          "type": "string"
+        },
+        "n_subjects": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Sample size if explicitly mentioned, otherwise null.",
+          "title": "N Subjects"
+        }
+      },
+      "required": [
+        "metric",
+        "value"
+      ],
+      "title": "StatisticExtraction",
+      "type": "object"
+    }
+  },
+  "description": "v0.3 — clinical-grade citation-evidence Q&A record.\n\nDiffers from v0.2 only in:\n  - StudyDesign adds 'observational' (residual observational bucket)\n  - field/prompt wording clarifies it is a fallback, not a default\n  - prompt adds WHAT-vs-WHY contrast for evidence_type vs citation_purpose",
+  "properties": {
+    "relevance_check": {
+      "description": "Does the cited paper's title/abstract topically match what the evidence_sentence is citing it for? 'match'=clearly the right ref; 'ambiguous'=hard to tell; 'mismatch'=cited paper is unrelated to the claim. If 'mismatch', set support_strength='insufficient-context', leave question/answer/evidence_quote_from_cited empty, and explain in mismatch_reason.",
+      "enum": [
+        "match",
+        "ambiguous",
+        "mismatch"
+      ],
+      "title": "Relevance Check",
+      "type": "string"
+    },
+    "mismatch_reason": {
+      "default": "",
+      "description": "If relevance_check='mismatch' or 'ambiguous', a 1-sentence explanation of WHY the cited paper does not (or may not) ground the claim — e.g., 'cited paper is about X, but citing context discusses Y'. Empty string when relevance_check='match'.",
+      "title": "Mismatch Reason",
+      "type": "string"
+    },
+    "attributed_claim": {
+      "description": "What does paper A claim, by virtue of citing paper B at this sentence? This is the proposition A presents as supported by B — NOT a summary of B itself. Be specific. 1-3 sentences. Empty when mismatch.",
+      "title": "Attributed Claim",
+      "type": "string"
+    },
+    "citation_purpose": {
+      "description": "WHY paper A cites paper B. background=general motivating fact; method=A is using B's technique; result-support=B's finding directly supports A's claim/result; comparison=A compares to B; contrast=A's findings differ from B's; negative=A claims B is wrong/limited.",
+      "enum": [
+        "background",
+        "method",
+        "result-support",
+        "comparison",
+        "contrast",
+        "negative",
+        "other"
+      ],
+      "title": "Citation Purpose",
+      "type": "string"
+    },
+    "evidence_type": {
+      "description": "HOW the cited content is presented. direct-quote=A quotes B verbatim; paraphrase=A summarizes B's claim; statistic=A cites a number from B (if so, fill statistic_extraction); method-citation=A invokes B's protocol/instrument; generic-background=B is one of several refs supporting a generic statement. NEVER use a citation_purpose value (background/result-support/comparison/contrast/negative) here — those describe WHY, not HOW.",
+      "enum": [
+        "direct-quote",
+        "paraphrase",
+        "statistic",
+        "method-citation",
+        "generic-background",
+        "other"
+      ],
+      "title": "Evidence Type",
+      "type": "string"
+    },
+    "support_strength": {
+      "description": "How well does B's abstract actually support A's attributed_claim? strong=abstract clearly states the claim; moderate=consistent but not the main result; weak=tangential; insufficient-context=cannot tell from inputs alone (use whenever relevance_check != 'match').",
+      "enum": [
+        "strong",
+        "moderate",
+        "weak",
+        "insufficient-context"
+      ],
+      "title": "Support Strength",
+      "type": "string"
+    },
+    "cited_study_design": {
+      "description": "The study design of the CITED paper, inferred from its abstract. Prefer the most specific applicable label: 'rct' / 'non-randomized-trial' / 'prospective-cohort' / 'retrospective-cohort' / 'case-control' / 'cross-sectional' / 'case-series' / 'case-report' / 'systematic-review' / 'meta-analysis' / 'guideline' / 'preclinical'. Use 'observational' ONLY when the cited paper is clearly an observational design (not RCT, not preclinical) AND the abstract does not provide enough information to disambiguate prospective-cohort vs retrospective-cohort vs case-control vs cross-sectional. If the abstract clearly indicates prospective or retrospective ascertainment, USE THE SPECIFIC LABEL — do not default to 'observational'. Use 'preclinical' for animal/in-vitro/translational mechanism studies. Use 'other' only if truly unidentifiable.",
+      "enum": [
+        "rct",
+        "non-randomized-trial",
+        "prospective-cohort",
+        "retrospective-cohort",
+        "case-control",
+        "cross-sectional",
+        "observational",
+        "case-series",
+        "case-report",
+        "systematic-review",
+        "meta-analysis",
+        "guideline",
+        "preclinical",
+        "other"
+      ],
+      "title": "Cited Study Design",
+      "type": "string"
+    },
+    "question": {
+      "description": "An open-ended biomedical question that A's citing context implicitly answers using B as evidence. NOT yes/no. Empty when mismatch.",
+      "title": "Question",
+      "type": "string"
+    },
+    "answer": {
+      "description": "2-4 sentence factual answer grounded in evidence_sentence and/or cited abstract. Cite as [PMID:<pmid>] when stating B's contribution. Empty when mismatch.",
+      "title": "Answer",
+      "type": "string"
+    },
+    "answer_grounded_in": {
+      "description": "Which input(s) the answer is grounded in. Empty when mismatch.",
+      "items": {
+        "enum": [
+          "evidence_sentence",
+          "cited_abstract",
+          "both"
+        ],
+        "type": "string"
+      },
+      "title": "Answer Grounded In",
+      "type": "array"
+    },
+    "evidence_quote_from_cited": {
+      "default": "",
+      "description": "VERBATIM span copied from the CITED paper's abstract that grounds the answer. MUST be an exact substring of the abstract (we will verify). Pick the single most relevant sentence (or contiguous fragment up to ~50 words). Empty string if relevance_check != 'match' or if evidence_type='generic-background' (no specific quote).",
+      "title": "Evidence Quote From Cited",
+      "type": "string"
+    },
+    "statistic_extraction": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/StatisticExtraction"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Required when evidence_type='statistic'. Otherwise null. Extract only what is actually stated in evidence_sentence or cited abstract; do not infer."
+    }
+  },
+  "required": [
+    "relevance_check",
+    "attributed_claim",
+    "citation_purpose",
+    "evidence_type",
+    "support_strength",
+    "cited_study_design",
+    "question",
+    "answer"
+  ],
+  "title": "CitationQA",
+  "type": "object"
+}
+
+Example #1 — well-formed MATCH (template only, do NOT copy contents):
+{
+  "relevance_check": "match",
+  "mismatch_reason": "",
+  "attributed_claim": "Standardized caloric requirements for infants with congenital heart disease have not been established, and prior reports show actual enteral intake often falls short of postoperative goals.",
+  "citation_purpose": "background",
+  "evidence_type": "statistic",
+  "support_strength": "strong",
+  "cited_study_design": "retrospective-cohort",
+  "question": "Why did the authors adopt the Indian RDA caloric target instead of a CHD-specific standard for postoperative infants?",
+  "answer": "Because no consensus standard for caloric intake exists for infants with congenital heart disease (CHD); a retrospective cohort of 100 neonates after cardiac surgery [PMID:19116405] found median enteral intake of 93 kcal/kg, with the 100 kcal/kg goal met for only 48.4% of patient-days, indicating that enteral feeding alone is often suboptimal in this population. The authors therefore defaulted to the 2010 Indian RDA target of 92 kcal/kg/day.",
+  "answer_grounded_in": [
+    "both"
+  ],
+  "evidence_quote_from_cited": "The median caloric intake per day was 93 kcal/kg (range, 43-142). A goal of 100 kcal/kg was achieved for 48.4% of patient days",
+  "statistic_extraction": {
+    "metric": "median caloric intake per day",
+    "value": "93 kcal/kg",
+    "ci_or_range": "range 43-142",
+    "p_value": "",
+    "n_subjects": 100
+  }
+}
+
+Example #2 — well-formed MISMATCH (template only):
+{
+  "relevance_check": "mismatch",
+  "mismatch_reason": "Cited paper reports global plastic production and waste statistics, but the citing context discusses interfacial bonding mechanics between microplastics and cement hydration products — topically unrelated.",
+  "attributed_claim": "",
+  "citation_purpose": "background",
+  "evidence_type": "generic-background",
+  "support_strength": "insufficient-context",
+  "cited_study_design": "other",
+  "question": "",
+  "answer": "",
+  "answer_grounded_in": [],
+  "evidence_quote_from_cited": "",
+  "statistic_extraction": null
+}