feat: add consent code eligibility logic for search API (#199)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: NoopDog

backend/concept_search/EXTRACT_PROMPT.md

@@ -85,6 +85,16 @@ For these facets, extract the user's text and leave `values` empty. A resolve ag
 
 **Important:** A disease name is a **consentCode** (not focus) when the query describes what research the data is _consented for_, not what the data is _about_. Context clues: "consented for", "approved for", "data use", "research consented". Example: "diabetes datasets consented for Alzheimer's research" → focus="diabetes", consentCode="Alzheimer's". Also recognize semantic descriptions: "general research use" → consentCode, "health and medical" → consentCode, "not for profit" → consentCode.
 
+**Eligibility language** — the following cue words signal the user is asking about what data they are _allowed to use_, which means consentCode: "what can I use", "what datasets can I use", "eligible for", "consented for", "approved for", "available for my research", "for-profit", "non-profit", "commercial use". When these cues are present, emit a **consentCode** mention in addition to any focus mention. Without these cues, disease mentions stay as `focus` only.
+
+Key rule: "diabetes studies" = focus only. "What diabetes datasets can I use?" = focus + consentCode (because "can I use" signals eligibility).
+
+**Dual mentions:** When eligibility cues appear alongside a disease, emit BOTH a focus mention (what the study is about) AND a consentCode mention (what the data is permitted for). Examples:
+
+- "I'm a nonprofit studying cancer, what's available?" → focus="cancer" + consentCode="nonprofit cancer"
+- "for-profit diabetes datasets" → focus="diabetes" + consentCode="for-profit diabetes"
+- "what datasets can I use for Alzheimer's research?" → focus="Alzheimer's" + consentCode="Alzheimer's"
+
 ## Instructions
 
 1. Determine the query **intent** (`"study"`, `"variable"`, or `"auto"`) — see "Query Intent" above.

backend/concept_search/RESOLVE_PROMPT.md

@@ -74,27 +74,48 @@ If category drill-down doesn't find a match, fall back to `search_concepts`:
 - You can combine both: try category drill-down, then search if needed.
 - **Cross-category terms:** Some terms appear in multiple categories (e.g., "cholesterol" exists in Laboratory Tests, Metabolomics, Dietary & Nutrition, and Medications). When a term could fit multiple categories, try 2–3 categories and **pick the concept with the highest study count**. Set `message` to disambiguate: "Did you mean Total Cholesterol (93 studies), HDL Cholesterol (78 studies), or Dietary Cholesterol Intake (9 studies)?"
 
-## Consent Code Facet — Category Drill-Down
+## Consent Code Facet — Eligibility Resolution
 
-For **consentCode** mentions, use context-driven drill-down:
+For **consentCode** mentions, use one of two patterns:
 
-1. Call `get_consent_code_categories()` to see the base codes (GRU, HMB, DS, etc.) with descriptions, study counts, and modifier definitions.
-2. Use your understanding of the mention to pick the right base code:
-   - "general research use", "open access", "unrestricted" → GRU
-   - "health research", "biomedical only" → HMB
-   - Any disease name → DS (disease-specific)
-   - "not for profit" → look for NPU modifier on the right base
-3. If the mention refers to a disease, call `get_disease_specific_codes()` to see all DS-\* disease categories with their full names.
-4. Optionally call `get_consent_codes_for_base(base_code)` to see all variants with modifiers (e.g., all GRU-_ or DS-CVD-_ codes).
-5. Return the broadest matching code unless the user specifies modifiers.
+### Pattern A: Explicit Code
+
+When the mention text IS a consent code (e.g. "GRU", "HMB-IRB", "DS-CVD"):
+
+1. Call `compute_consent_eligibility(explicit_code=<the code>)` to get the code and all its modifier variants.
+2. Return ALL eligible codes from the result — these are combined with OR.
 
 **Examples:**
 
-- "general research use" → get categories → pick GRU
-- "breast cancer research" → get categories → see DS → get disease codes → pick DS-BRCA
-- "HMB-IRB" → direct code, return as-is
-- "cardiovascular disease, not for profit" → get disease codes → DS-CVD → get variants → DS-CVD-NPU-MDS or just DS-CVD
-- "open access no restrictions" → GRU (semantic match, "open access" = general research use)
+- "GRU" → `compute_consent_eligibility(explicit_code="GRU")` → returns GRU, GRU-IRB, GRU-NPU, etc.
+- "HMB-IRB" → `compute_consent_eligibility(explicit_code="HMB-IRB")` → returns just HMB-IRB
+- "DS-CVD" → `compute_consent_eligibility(explicit_code="DS-CVD")` → returns DS-CVD, DS-CVD-IRB, etc.
+
+### Pattern B: Eligibility / Use-Case
+
+When the mention describes a research use case or eligibility (e.g. "diabetes research", "for-profit cancer datasets", "general health research"):
+
+1. Determine **purpose**: "general" (unrestricted), "health" (health/medical/biomedical), or "disease" (specific disease).
+2. Determine **is_nonprofit**: False if mention says "for-profit" or "commercial"; True or None otherwise.
+3. Call `compute_consent_eligibility(purpose=..., disease=..., is_nonprofit=...)` — the disease parameter accepts full names ("diabetes", "cancer", "type 1 diabetes") or abbreviations ("DIAB", "CA", "T1D"). The tool resolves names automatically.
+4. Return ALL eligible codes from the result.
+
+**Examples:**
+
+- "diabetes research" → `compute_consent_eligibility(purpose="disease", disease="diabetes")` → returns GRU*, HMB*, DS-DIAB*, DS-T1D*, etc.
+- "for-profit cancer datasets" → `compute_consent_eligibility(purpose="disease", disease="cancer", is_nonprofit=False)` → returns codes without NPU modifier
+- "general health research at a university" → `compute_consent_eligibility(purpose="health")` → returns GRU* + HMB* + HMP + HR
+- "general research use" → `compute_consent_eligibility(explicit_code="GRU")`
+- "open access no restrictions" → `compute_consent_eligibility(explicit_code="GRU")`
+- "type 1 diabetes consent" → `compute_consent_eligibility(purpose="disease", disease="type 1 diabetes")`
+- "consented for diabetes only" → `compute_consent_eligibility(purpose="disease", disease="diabetes", disease_only=True)` → returns only DS-DIAB\* codes, not GRU/HMB
+- "specifically consented for cancer" → `compute_consent_eligibility(purpose="disease", disease="cancer", disease_only=True)`
+
+**disease_only flag:** Set `disease_only=True` when the user says "only", "specifically", "disease-specific", or otherwise indicates they want datasets with a disease-specific consent code — not all datasets that happen to be eligible. This excludes GRU, HMB, and other broad codes.
+
+### Exploration Tools (still available)
+
+You can still use `get_consent_code_categories()`, `get_disease_specific_codes()`, and `get_consent_codes_for_base()` to explore codes before calling `compute_consent_eligibility`.
 
 ## General Selection Rules
 

backend/concept_search/consent_codes.json

@@ -19,81 +19,31 @@
     "RD": "Research-specific restrictions or rare disease",
     "MDS-GSO": "Methods Development and Genetic Studies Only"
   },
-  "disease_abbreviations": {
-    "CA": "Cancer (all types)",
-    "CVD": "Cardiovascular Disease",
-    "BRCA": "Breast Cancer",
-    "OVCA": "Ovarian Cancer",
-    "LC": "Lung Cancer",
-    "PC": "Prostate Cancer",
-    "DIAB": "Diabetes",
-    "T1D": "Type 1 Diabetes",
-    "T1DR": "Type 1 Diabetes Research",
-    "T2D": "Type 2 Diabetes",
-    "COPD": "Chronic Obstructive Pulmonary Disease",
-    "ASTHMA": "Asthma",
-    "ASD": "Autism Spectrum Disorder",
-    "ALZ": "Alzheimer's Disease",
-    "SCD": "Sickle Cell Disease",
-    "HIV": "Human Immunodeficiency Virus / AIDS",
-    "HCC": "Hepatocellular Carcinoma",
-    "SLE": "Systemic Lupus Erythematosus",
-    "IBD": "Inflammatory Bowel Disease",
-    "CF": "Cystic Fibrosis",
-    "CFD": "Craniofacial Disorders",
-    "CFR": "Cystic Fibrosis Research",
-    "CC": "Colorectal Cancer",
-    "CKD": "Chronic Kidney Disease",
-    "EP": "Epilepsy",
-    "CHD": "Congenital Heart Disease",
-    "ED": "Eating Disorders",
-    "SZRD": "Schizophrenia-Related Disorders",
-    "HEM": "Hematologic Diseases",
-    "PACA": "Pancreatic Cancer",
-    "NHL": "Non-Hodgkin Lymphoma",
-    "LEU": "Leukemia",
-    "AMD": "Age-Related Macular Degeneration",
-    "LD": "Liver Disease",
-    "LIVD": "Liver Disease",
-    "NDR": "Neurodevelopmental Research",
-    "PD": "Parkinson's Disease",
-    "STK": "Stroke",
-    "MS": "Multiple Sclerosis",
-    "RA": "Rheumatoid Arthritis",
-    "TB": "Tuberculosis",
-    "MM": "Multiple Myeloma",
-    "HNC": "Head and Neck Cancer",
-    "FDO": "Familial Dysautonomia / Dysautonomic Disorders",
-    "PEDCR": "Pediatric Cancer Research",
-    "BOED": "Bone Disease",
-    "AF": "Atrial Fibrillation",
-    "IR": "Insulin Resistance",
-    "DEM": "Dementia",
-    "HLBS": "Heart, Lung, Blood, and Sleep disorders",
-    "DRC": "Diabetes-Related Complications",
-    "LDS": "Lysosomal Storage Diseases",
-    "ESD": "Esophageal Diseases",
-    "MSC": "Musculoskeletal Conditions",
-    "MAL": "Malaria",
-    "HF": "Heart Failure",
-    "MI": "Myocardial Infarction",
-    "ADO": "Autoimmune Disorders",
-    "BLADDERCA": "Bladder Cancer",
-    "BROC": "Brain and Other Central Nervous System Cancer",
-    "BT": "Brain Tumor",
-    "CS": "Cushing's Syndrome",
-    "ALC": "Alcohol-Related Disorders",
-    "ADHD": "Attention Deficit Hyperactivity Disorder",
-    "OC": "Ovarian Cancer",
-    "HM": "Hematologic Malignancies",
-    "CLL": "Chronic Lymphocytic Leukemia",
-    "RCC": "Renal Cell Carcinoma",
-    "BPD": "Bronchopulmonary Dysplasia",
-    "PAD": "Peripheral Arterial Disease",
-    "SARC": "Sarcoidosis",
-    "OFC": "Orofacial Clefts",
-    "UC": "Ulcerative Colitis",
-    "LCTC": "Lung Cancer and Tobacco Control",
-    "TMJD": "Temporomandibular Joint Disorders"
+  "disease_hierarchy": {
+    "CA": [
+      "BRCA",
+      "OVCA",
+      "LC",
+      "PC",
+      "HCC",
+      "CC",
+      "PACA",
+      "NHL",
+      "LEU",
+      "HNC",
+      "MM",
+      "RCC",
+      "CLL",
+      "OC",
+      "BLADDERCA",
+      "BROC",
+      "BT",
+      "PEDCR",
+      "LCTC",
+      "HM"
+    ],
+    "CVD": ["AF", "HF", "MI", "PAD", "STK", "CHD"],
+    "DIAB": ["T1D", "T2D", "DRC", "T1DR", "IR"],
+    "LD": ["LIVD", "ESD"]
   }
 }