feat: add phenotype to LLM query

Author: NoopDog

backend/api/services/anvil_config.py

@@ -11,6 +11,7 @@
 ANVIL_FACET_NAME_MAPPING: Dict[str, str] = {
     # Primary facets
     "Diagnosis": "diagnoses.disease",
+    "Phenotype": "diagnoses.phenotype",
     "Reported Ethnicity": "donors.reported_ethnicity",
     "File Format": "files.file_format",
     "Anatomical Site": "biosamples.anatomical_site",
@@ -24,7 +25,6 @@
     # Unmatched terms - no OpenSearch mapping
     "unmatched": "unmatched",
     # Legacy mappings (for backwards compatibility)
-    "Phenotype": "diagnoses.phenotype",
     "Data Use Permission": "datasets.data_use_permission",
     "Activity Type": "activities.activity_type",
     "Assay Type": "activities.assay_type",

backend/api/services/llm_mention_extractor.py

@@ -28,17 +28,26 @@
   independent of the technology or methods used to produce the information.
 
 - Diagnosis:
-  A disease, condition, phenotypic abnormality, or clinical finding reported in an entity.
+  A disease or individual phenotypic feature.
   This includes:
-  * Diseases (e.g., diabetes, cancer, Alzheimer's disease)
-  * Clinical conditions and phenotypes (e.g., accessory oral frenulum, cleft palate)
-  * HPO (Human Phenotype Ontology) terms describing abnormalities
+  * Named diseases (e.g., diabetes, cancer, Alzheimer's disease, autism)
   * MONDO disease terms
-  * Any medical/clinical abnormality or pathological condition
+  * Individual HPO phenotypic features (e.g., cleft palate, seizure, hypotonia)
+  * Single observable characteristics or abnormalities
 
-  IMPORTANT: Even if a term contains anatomical words (e.g., "oral", "cardiac"),
-  it should be categorized as Diagnosis if it describes an abnormality or condition,
-  not Anatomical Site.
+  IMPORTANT: Use Diagnosis for both named diseases AND individual phenotypic traits.
+  Only use Phenotype for complex phenotype syndromes.
+
+- Phenotype:
+  Complex phenotype syndromes and named phenotypic conditions.
+  This includes:
+  * Complex phenotype syndromes (e.g., Coffin-Siris syndrome, Epileptic Encephalopathy)
+  * Named phenotypic conditions (e.g., Agenesis of the Corpus Callosum)
+  * Multi-feature phenotypic presentations
+  * Specific syndrome names
+
+  IMPORTANT: Use Phenotype only for complex/named syndromes. For individual features
+  like "cleft palate" or "seizure", use Diagnosis instead.
 
 - Organism Type:
   A human-readable reference to the organism type.
@@ -73,9 +82,11 @@
 Instructions:
 - Extract exact substrings from the query.
 - Assign mentions to the most appropriate facet listed above.
-- When choosing between Diagnosis and Anatomical Site: if the term describes an abnormality,
-  condition, or disease, choose Diagnosis. Only use Anatomical Site for normal body parts
-  where samples are collected.
+- When choosing between Diagnosis and Phenotype: use Diagnosis for diseases AND individual
+  phenotypic features (like "cleft palate", "seizure"). Use Phenotype only for complex
+  syndrome names (like "Coffin-Siris syndrome", "Epileptic Encephalopathy").
+- When choosing between Diagnosis/Phenotype and Anatomical Site: use Diagnosis/Phenotype
+  for abnormalities, use Anatomical Site only for normal body parts where samples are collected.
 - If a meaningful term does not map to any facet, use facet = 'unmatched'.
 - Do not invent new facet names.
 """.strip()
@@ -86,6 +97,7 @@
     "Consent Group",
     "Data Modality",
     "Diagnosis",
+    "Phenotype",
     "Organism Type",
     "Reported Ethnicity",
     "Phenotypic Sex",

backend/api/tests/mock_llm_extractor.py

@@ -20,6 +20,14 @@ class MockLLMMentionExtractor:
         (r"\bcancer\b", "cancer", "Diagnosis"),
         (r"\bals\b", "als", "Diagnosis"),
         (r"\btype\s+2\s+diabetes\b", "type 2 diabetes", "Diagnosis"),
+        # Individual phenotypic features (go in Diagnosis)
+        (r"\bcleft\s+palate\b", "cleft palate", "Diagnosis"),
+        (r"\bseizure\b", "seizure", "Diagnosis"),
+        (r"\bhypotonia\b", "hypotonia", "Diagnosis"),
+        # Complex phenotype syndromes (go in Phenotype) - patterns are lowercase because query is lowercased
+        (r"\bcoffin-siris\s+syndrome\b", "Coffin-Siris syndrome", "Phenotype"),
+        (r"\bepileptic\s+encephalopathy\b", "Epileptic Encephalopathy", "Phenotype"),
+        (r"\bagenesis\s+of\s+(?:the\s+)?corpus\s+callosum\b", "agenesis of the corpus callosum", "Phenotype"),
         # Ethnicity
         (r"\blatino\b", "latino", "Reported Ethnicity"),
         (r"\bhispanic\b", "hispanic", "Reported Ethnicity"),

backend/api/tests/test_llm_extraction.py

@@ -2,6 +2,7 @@
 import pytest
 
 from services.normalization_service import Mention
+from services.anvil_config import get_anvil_facet_mapping
 from tests.mock_llm_extractor import MockLLMMentionExtractor
 
 
@@ -11,6 +12,12 @@ def mock_extractor() -> MockLLMMentionExtractor:
     return MockLLMMentionExtractor()
 
 
+@pytest.fixture
+def mock_extractor_with_mapping() -> MockLLMMentionExtractor:
+    """Fixture providing a mock LLM extractor with facet name mapping."""
+    return MockLLMMentionExtractor(facet_name_mapping=get_anvil_facet_mapping())
+
+
 def test_simple_query_diabetes(mock_extractor: MockLLMMentionExtractor) -> None:
     """Test extraction from simple query with one term."""
     query = "diabetes"
@@ -184,3 +191,33 @@ def test_phenotypic_sex_extraction(mock_extractor: MockLLMMentionExtractor) -> N
     mentions = mock_extractor.extract_mentions(query)
 
     assert any(m.text == "male" and m.facet == "Phenotypic Sex" for m in mentions)
+
+
+def test_individual_phenotype_feature_as_diagnosis(mock_extractor_with_mapping: MockLLMMentionExtractor) -> None:
+    """Test that individual phenotypic features are extracted as Diagnosis."""
+    query = "patients with cleft palate"
+
+    mentions = mock_extractor_with_mapping.extract_mentions(query)
+
+    assert any(m.text == "cleft palate" and m.facet == "diagnoses.disease" for m in mentions)
+
+
+def test_complex_phenotype_syndrome(mock_extractor_with_mapping: MockLLMMentionExtractor) -> None:
+    """Test that complex phenotype syndromes are extracted as Phenotype."""
+    query = "patients with Coffin-Siris syndrome"
+
+    mentions = mock_extractor_with_mapping.extract_mentions(query)
+
+    assert any(m.text == "Coffin-Siris syndrome" and m.facet == "diagnoses.phenotype" for m in mentions)
+
+
+def test_diagnosis_vs_phenotype_distinction(mock_extractor_with_mapping: MockLLMMentionExtractor) -> None:
+    """Test that the mock extractor distinguishes between Diagnosis and Phenotype."""
+    query = "patients with diabetes and Epileptic Encephalopathy"
+
+    mentions = mock_extractor_with_mapping.extract_mentions(query)
+
+    # diabetes should be Diagnosis (diagnoses.disease)
+    assert any(m.text == "diabetes" and m.facet == "diagnoses.disease" for m in mentions)
+    # Epileptic Encephalopathy should be Phenotype (diagnoses.phenotype)
+    assert any(m.text == "Epileptic Encephalopathy" and m.facet == "diagnoses.phenotype" for m in mentions)