Sync from GitHub (main)

src/sentinel/risk_models/base.py

@@ -2,7 +2,7 @@
 
 import re
 from abc import ABC, abstractmethod
-from typing import Any
+from typing import Any, Literal, get_args, get_origin
 
 from pydantic import TypeAdapter, ValidationError
 
@@ -13,7 +13,7 @@ from sentinel.user_input import UserInput
 class RiskModel(ABC):
     """Base class for risk models."""
 
-    REQUIRED_INPUTS: dict[str, tuple[type, bool]] = {}
+    REQUIRED_INPUTS: dict[str, tuple[Any, bool]] = {}
 
     def __init__(self, name: str):
         self.name = name
@@ -120,14 +120,54 @@ class RiskModel(ABC):
             # Validate against type and constraints if value present
             if value is not None:
                 try:
-                    adapter = TypeAdapter(field_type)
+                    adapter: TypeAdapter[Any] = TypeAdapter(field_type)
                     adapter.validate_python(value)
                 except ValidationError as e:
-                    error_msg = e.errors()[0]["msg"]
+                    # Check if this is a Literal type with enum values for better error messages
+                    if self._is_literal_enum_type(field_type):
+                        allowed_values = self._extract_literal_enum_values(field_type)
+                        if len(allowed_values) == 1:
+                            error_msg = f"must be {allowed_values[0]}"
+                        else:
+                            error_msg = f"must be one of {', '.join(allowed_values)}"
+                    else:
+                        error_msg = e.errors()[0]["msg"]
                     errors.append(f"Field '{field_path}': {error_msg}")
 
         return (len(errors) == 0, errors)
 
+    def _is_literal_enum_type(self, field_type: type) -> bool:
+        """Check if a field type is a Literal containing enum values.
+
+        Args:
+            field_type: The type to check
+
+        Returns:
+            True if the type is a Literal containing enum values
+        """
+        origin = get_origin(field_type)
+        if origin is not Literal:
+            return False
+
+        args = get_args(field_type)
+        # Check if all arguments are enum values (have a __class__ attribute and are instances of Enum)
+        return all(
+            hasattr(arg, "__class__") and hasattr(arg, "name") and hasattr(arg, "value")
+            for arg in args
+        )
+
+    def _extract_literal_enum_values(self, field_type: type) -> list[str]:
+        """Extract enum value names from a Literal type.
+
+        Args:
+            field_type: The Literal type containing enum values
+
+        Returns:
+            List of enum value names (e.g., ['FEMALE'] or ['WHITE', 'BLACK', 'ASIAN'])
+        """
+        args = get_args(field_type)
+        return [arg.name for arg in args]
+
     def run(self, user: UserInput) -> RiskScore:
         """Compute all public fields and return a `RiskScore` summary.
 

src/sentinel/risk_models/boadicea.py

@@ -7,7 +7,7 @@ The model is specifically designed for women with genetic predispositions,
 particularly BRCA1 and BRCA2 mutation carriers.
 """
 
-from typing import Annotated
+from typing import Annotated, Literal
 
 from pydantic import Field
 
@@ -25,7 +25,7 @@ class BOADICEARiskModel(RiskModel):
 
     REQUIRED_INPUTS: dict[str, tuple[type, bool]] = {
         "demographics.age_years": (Annotated[int, Field(ge=18, le=100)], True),
-        "demographics.sex": (Sex, True),
+        "demographics.sex": (Literal[Sex.FEMALE], True),
         "demographics.ethnicity": (Ethnicity | None, False),
         "demographics.anthropometrics.height_cm": (
             Annotated[float, Field(gt=0)],

src/sentinel/risk_models/extended_pbcg.py

@@ -4,7 +4,7 @@ import json
 from functools import lru_cache
 from math import exp, log
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Literal
 
 from pydantic import Field
 
@@ -65,7 +65,7 @@ class ExtendedPBCGRiskModel(RiskModel):
 
     REQUIRED_INPUTS: dict[str, tuple[type, bool]] = {
         "demographics.age_years": (Annotated[int, Field(ge=40, le=90)], True),
-        "demographics.sex": (Sex, True),
+        "demographics.sex": (Literal[Sex.MALE], True),
         "demographics.ethnicity": (Ethnicity | None, False),
         "clinical_tests.psa": (PSATest, True),
         "clinical_tests.prostate_volume": (ProstateVolumeTest, False),

src/sentinel/risk_models/gail.py

@@ -17,7 +17,7 @@ https://dceg.cancer.gov/tools/risk-assessment/bcra.
 """
 
 from math import ceil, exp, log
-from typing import Annotated
+from typing import Annotated, Any, Literal
 
 from pydantic import Field
 
@@ -503,10 +503,20 @@ class GailRiskModel(RiskModel):
     def __init__(self):
         super().__init__("gail")
 
-    REQUIRED_INPUTS: dict[str, tuple[type, bool]] = {
+    REQUIRED_INPUTS: dict[str, tuple[Any, bool]] = {
         "demographics.age_years": (Annotated[int, Field(ge=35, le=85)], True),
-        "demographics.sex": (Sex, True),
-        "demographics.ethnicity": (Ethnicity | None, False),
+        "demographics.sex": (Literal[Sex.FEMALE], True),
+        "demographics.ethnicity": (
+            Literal[
+                Ethnicity.WHITE,
+                Ethnicity.BLACK,
+                Ethnicity.ASIAN,
+                Ethnicity.PACIFIC_ISLANDER,
+                Ethnicity.HISPANIC,
+            ]
+            | None,
+            False,
+        ),
         "female_specific.menstrual.age_at_menarche": (
             Annotated[int, Field(ge=7, le=20)],
             False,
@@ -732,10 +742,6 @@ class GailRiskModel(RiskModel):
         if not is_valid:
             raise ValueError(f"Invalid inputs for Gail: {'; '.join(errors)}")
 
-        # Check sex
-        if user.demographics.sex != Sex.FEMALE:
-            return "N/A: Gail model is only applicable to female patients."
-
         # Check female-specific data
         if user.female_specific is None:
             return "N/A: Missing female-specific information required for Gail."

src/sentinel/risk_models/prostate_mortality.py

@@ -7,7 +7,7 @@ methodology to predict mortality outcomes at specified time horizons.
 """
 
 from math import exp, log
-from typing import Annotated
+from typing import Annotated, Literal
 
 from pydantic import Field
 
@@ -29,7 +29,7 @@ class ProstateMortalityRiskModel(RiskModel):
 
     REQUIRED_INPUTS: dict[str, tuple[type, bool]] = {
         "demographics.age_years": (Annotated[int, Field(ge=35, le=95)], True),
-        "demographics.sex": (Sex, True),
+        "demographics.sex": (Literal[Sex.MALE], True),
         "clinical_tests.psa": (PSATest, True),
         "personal_medical_history.prostate_cancer_grade_group": (
             Annotated[int, Field(ge=1, le=5)],

src/sentinel/risk_models/tyrer_cuzick.py

@@ -1109,7 +1109,7 @@ class TyrerCuzickRiskModel(RiskModel):
 
     REQUIRED_INPUTS: dict[str, tuple[type, bool]] = {
         "demographics.age_years": (Annotated[int, Field(ge=18, le=100)], True),
-        "demographics.sex": (Sex, True),
+        "demographics.sex": (Literal[Sex.FEMALE], True),
         "demographics.anthropometrics.height_cm": (
             Annotated[float, Field(gt=0)],
             False,

tests/test_risk_models/test_base_model_enum_validation.py

@@ -0,0 +1,289 @@
+"""Tests for enum subset validation in REQUIRED_INPUTS.
+
+This module tests the enhanced validation logic that supports restricting
+enum fields to specific subsets using Literal types.
+"""
+
+from typing import Any, Literal
+
+from sentinel.risk_models.base import RiskModel
+from sentinel.user_input import (
+    Anthropometrics,
+    Demographics,
+    Ethnicity,
+    Lifestyle,
+    PersonalMedicalHistory,
+    Sex,
+    SmokingHistory,
+    SmokingStatus,
+    UserInput,
+)
+
+
+class EnumValidationTestModel(RiskModel):
+    """Test risk model with various enum restrictions for validation testing."""
+
+    def __init__(self):
+        super().__init__("test_enum_validation")
+
+    # Test cases for different enum restriction patterns
+    REQUIRED_INPUTS: dict[str, tuple[type | Any, bool]] = {
+        # Single enum value restriction
+        "demographics.sex": (Literal[Sex.FEMALE], True),
+        # Multiple enum value restriction (subset)
+        "demographics.ethnicity": (
+            Literal[Ethnicity.WHITE, Ethnicity.BLACK, Ethnicity.ASIAN] | None,
+            False,
+        ),
+    }
+
+    def compute_score(self, user: UserInput) -> str:
+        """Test implementation.
+
+        Args:
+            user: The user profile to score.
+
+        Returns:
+            A test score string.
+        """
+        return "test_score"
+
+    def cancer_type(self) -> str:
+        return "test"
+
+    def description(self) -> str:
+        return "Test model"
+
+    def interpretation(self) -> str:
+        return "Test interpretation"
+
+    def references(self) -> list[str]:
+        return ["Test reference"]
+
+    def time_horizon_years(self) -> float | None:
+        return None
+
+
+class TestEnumSubsetValidation:
+    """Test enum subset validation functionality."""
+
+    def setup_method(self):
+        """Set up test model."""
+        self.model = EnumValidationTestModel()
+
+    def _create_user_input(
+        self, sex: Sex, ethnicity: Ethnicity | None = None
+    ) -> UserInput:
+        """Create a valid UserInput instance for testing.
+
+        Args:
+            sex: The biological sex for the user.
+            ethnicity: The ethnicity for the user (optional).
+
+        Returns:
+            A valid UserInput instance for testing.
+        """
+        return UserInput(
+            demographics=Demographics(
+                age_years=40,
+                sex=sex,
+                ethnicity=ethnicity,
+                anthropometrics=Anthropometrics(height_cm=165.0, weight_kg=65.0),
+            ),
+            lifestyle=Lifestyle(
+                smoking=SmokingHistory(status=SmokingStatus.NEVER),
+            ),
+            personal_medical_history=PersonalMedicalHistory(),
+        )
+
+    def test_single_enum_value_restriction_valid(self):
+        """Test that valid single enum value passes validation."""
+        user = self._create_user_input(Sex.FEMALE, Ethnicity.WHITE)
+
+        is_valid, errors = self.model.validate_inputs(user)
+        assert is_valid
+        assert len(errors) == 0
+
+    def test_single_enum_value_restriction_invalid(self):
+        """Test that invalid single enum value fails validation with clear message."""
+        user = self._create_user_input(Sex.MALE, Ethnicity.WHITE)  # Should be FEMALE
+
+        is_valid, errors = self.model.validate_inputs(user)
+        assert not is_valid
+        assert len(errors) == 1
+        assert "Field 'demographics.sex': must be FEMALE" in errors[0]
+
+    def test_multiple_enum_value_restriction_valid(self):
+        """Test that valid enum values from subset pass validation."""
+        valid_ethnicities = [Ethnicity.WHITE, Ethnicity.BLACK, Ethnicity.ASIAN]
+
+        for ethnicity in valid_ethnicities:
+            user = self._create_user_input(Sex.FEMALE, ethnicity)
+
+            is_valid, errors = self.model.validate_inputs(user)
+            assert is_valid, f"Failed for ethnicity: {ethnicity}"
+            assert len(errors) == 0
+
+    def test_multiple_enum_value_restriction_invalid(self):
+        """Test that invalid enum values fail validation with clear message."""
+        invalid_ethnicities = [
+            Ethnicity.HISPANIC,
+            Ethnicity.ASHKENAZI_JEWISH,
+            Ethnicity.NATIVE_AMERICAN,
+            Ethnicity.PACIFIC_ISLANDER,
+            Ethnicity.OTHER,
+            Ethnicity.UNKNOWN,
+        ]
+
+        for ethnicity in invalid_ethnicities:
+            user = self._create_user_input(Sex.FEMALE, ethnicity)
+
+            is_valid, errors = self.model.validate_inputs(user)
+            assert not is_valid, f"Should have failed for ethnicity: {ethnicity}"
+            assert len(errors) == 1
+            assert "Field 'demographics.ethnicity': Input should be" in errors[0]
+            assert (
+                "WHITE" in errors[0] and "BLACK" in errors[0] and "ASIAN" in errors[0]
+            )
+
+    def test_optional_enum_field_with_none(self):
+        """Test that None values are handled correctly for optional enum fields."""
+        user = self._create_user_input(Sex.FEMALE, None)  # Optional field
+
+        is_valid, errors = self.model.validate_inputs(user)
+        assert is_valid
+        assert len(errors) == 0
+
+    def test_missing_required_enum_field(self):
+        """Test that missing required enum fields are caught."""
+
+        # Create a model that requires a field that's not in the user input
+        class MissingFieldModel(RiskModel):
+            """Test model for missing field validation."""
+
+            def __init__(self):
+                super().__init__("missing_field_test")
+
+            REQUIRED_INPUTS: dict[str, tuple[Any, bool]] = {
+                "demographics.sex": (Literal[Sex.FEMALE], True),
+                "demographics.ethnicity": (Ethnicity | None, False),
+                "demographics.nonexistent_field": (
+                    str,
+                    True,
+                ),  # This field doesn't exist
+            }
+
+            def compute_score(self, user: UserInput) -> str:
+                return "test"
+
+            def cancer_type(self) -> str:
+                return "test"
+
+            def description(self) -> str:
+                return "test"
+
+            def interpretation(self) -> str:
+                return "test"
+
+            def references(self) -> list[str]:
+                return ["test"]
+
+            def time_horizon_years(self) -> float | None:
+                return None
+
+        model = MissingFieldModel()
+        user = self._create_user_input(Sex.FEMALE, Ethnicity.WHITE)
+
+        is_valid, errors = model.validate_inputs(user)
+        assert not is_valid
+        assert len(errors) == 1
+        assert "Required field 'demographics.nonexistent_field' is missing" in errors[0]
+
+    def test_multiple_validation_errors(self):
+        """Test that multiple validation errors are reported."""
+        user = self._create_user_input(Sex.MALE, Ethnicity.HISPANIC)  # Both wrong
+
+        is_valid, errors = self.model.validate_inputs(user)
+        assert not is_valid
+        assert len(errors) == 2
+
+        # Check that both errors are present
+        error_messages = " ".join(errors)
+        assert "must be FEMALE" in error_messages
+        assert "Input should be" in error_messages
+        assert (
+            "WHITE" in error_messages
+            and "BLACK" in error_messages
+            and "ASIAN" in error_messages
+        )
+
+    def test_literal_enum_type_detection(self):
+        """Test the _is_literal_enum_type helper method."""
+        # Test Literal with single enum value
+        single_literal = Literal[Sex.FEMALE]
+        assert self.model._is_literal_enum_type(single_literal)
+
+        # Test Literal with multiple enum values
+        multi_literal = Literal[Ethnicity.WHITE, Ethnicity.BLACK]
+        assert self.model._is_literal_enum_type(multi_literal)
+
+        # Test non-Literal types
+        assert not self.model._is_literal_enum_type(Sex)
+        assert not self.model._is_literal_enum_type(int)
+        assert not self.model._is_literal_enum_type(str)
+
+    def test_extract_literal_enum_values(self):
+        """Test the _extract_literal_enum_values helper method."""
+        # Test single enum value
+        single_literal = Literal[Sex.FEMALE]
+        values = self.model._extract_literal_enum_values(single_literal)
+        assert values == ["FEMALE"]
+
+        # Test multiple enum values
+        multi_literal = Literal[Ethnicity.WHITE, Ethnicity.BLACK, Ethnicity.ASIAN]
+        values = self.model._extract_literal_enum_values(multi_literal)
+        assert set(values) == {"WHITE", "BLACK", "ASIAN"}
+
+    def test_backward_compatibility_unrestricted_enum(self):
+        """Test that unrestricted enum types still work (backward compatibility)."""
+
+        # Create a model with unrestricted enum
+        class UnrestrictedModel(RiskModel):
+            """Test model for backward compatibility with unrestricted enums."""
+
+            def __init__(self):
+                super().__init__("unrestricted_test")
+
+            REQUIRED_INPUTS: dict[str, tuple[type | Any, bool]] = {
+                "demographics.sex": (Sex, True),
+                "demographics.ethnicity": (Ethnicity | None, False),
+            }
+
+            def compute_score(self, user: UserInput) -> str:
+                return "test"
+
+            def cancer_type(self) -> str:
+                return "test"
+
+            def description(self) -> str:
+                return "test"
+
+            def interpretation(self) -> str:
+                return "test"
+
+            def references(self) -> list[str]:
+                return ["test"]
+
+            def time_horizon_years(self) -> float | None:
+                return None
+
+        model = UnrestrictedModel()
+
+        # Test with any valid enum values
+        user = self._create_user_input(
+            Sex.MALE, Ethnicity.HISPANIC
+        )  # Any values should work
+
+        is_valid, errors = model.validate_inputs(user)
+        assert is_valid
+        assert len(errors) == 0

tests/test_risk_models/test_boadicea_model.py

@@ -154,7 +154,14 @@ def test_model_metadata(boadicea_model: BOADICEARiskModel) -> None:
 def test_ineligible_patients_return_messages(
     boadicea_model: BOADICEARiskModel, user: UserInput, expected: str
 ) -> None:
-    assert boadicea_model.compute_score(user) == expected
+    # For male patients, validation now raises ValueError instead of returning N/A
+    if user.demographics.sex == Sex.MALE:
+        with pytest.raises(ValueError) as exc_info:
+            boadicea_model.compute_score(user)
+        assert "Invalid inputs for BOADICEA" in str(exc_info.value)
+        assert "must be FEMALE" in str(exc_info.value)
+    else:
+        assert boadicea_model.compute_score(user) == expected
 
 
 @pytest.mark.parametrize(

tests/test_risk_models/test_extended_pbcg_model.py

@@ -408,10 +408,9 @@ class TestExtendedPBCGRiskModel:
                 dre=DRETest(result=DREResult.NORMAL),
             ),
         )
-        assert (
-            self.model.compute_score(user)
-            == "N/A: Extended PBCG is validated for male patients only."
-        )
+        # Validation now returns N/A message instead of raising ValueError
+        result = self.model.compute_score(user)
+        assert result == "N/A: Invalid inputs - Field 'demographics.sex': must be MALE"
 
     def test_compute_score_invalid_age(self) -> None:
         user = UserInput(

tests/test_risk_models/test_gail_model.py

@@ -286,7 +286,7 @@ class TestGailModel:
         assert float(score) > 0
 
     def test_male_patient_handling(self):
-        """Test that male patients receive N/A response."""
+        """Test that male patients raise ValueError due to validation failure."""
         male_user = UserInput(
             demographics=Demographics(
                 age_years=45,
@@ -299,8 +299,12 @@ class TestGailModel:
             personal_medical_history=PersonalMedicalHistory(),
         )
 
-        score = self.model.compute_score(male_user)
-        assert score == "N/A: Gail model is only applicable to female patients."
+        # Male patients should now raise ValueError due to validation failure
+        with pytest.raises(ValueError) as exc_info:
+            self.model.compute_score(male_user)
+
+        assert "Invalid inputs for Gail" in str(exc_info.value)
+        assert "must be FEMALE" in str(exc_info.value)
 
     def test_age_validation(self):
         """Test age validation (35-85 range)."""
@@ -365,3 +369,97 @@ class TestGailModel:
         assert "1.67" in self.model.interpretation()
         assert isinstance(self.model.references(), list)
         assert len(self.model.references()) > 0
+
+    def test_male_patient_validation_rejection(self):
+        """Test that male patients are rejected during validation."""
+        male_user = UserInput(
+            demographics=Demographics(
+                age_years=40,
+                sex=Sex.MALE,  # Male patient should be rejected
+                ethnicity=Ethnicity.WHITE,
+                anthropometrics=Anthropometrics(height_cm=175.0, weight_kg=75.0),
+            ),
+            lifestyle=Lifestyle(
+                smoking=SmokingHistory(status=SmokingStatus.NEVER),
+            ),
+            personal_medical_history=PersonalMedicalHistory(),
+        )
+
+        # Validation should fail before compute_score is called
+        is_valid, errors = self.model.validate_inputs(male_user)
+        assert not is_valid
+        assert len(errors) == 1
+        assert "Field 'demographics.sex': must be FEMALE" in errors[0]
+
+    def test_male_patient_compute_score_raises_error(self):
+        """Test that compute_score raises ValueError for male patients."""
+        male_user = UserInput(
+            demographics=Demographics(
+                age_years=40,
+                sex=Sex.MALE,
+                ethnicity=Ethnicity.WHITE,
+                anthropometrics=Anthropometrics(height_cm=175.0, weight_kg=75.0),
+            ),
+            lifestyle=Lifestyle(
+                smoking=SmokingHistory(status=SmokingStatus.NEVER),
+            ),
+            personal_medical_history=PersonalMedicalHistory(),
+        )
+
+        # compute_score should raise ValueError due to validation failure
+        with pytest.raises(ValueError) as exc_info:
+            self.model.compute_score(male_user)
+
+        assert "Invalid inputs for Gail" in str(exc_info.value)
+        assert "must be FEMALE" in str(exc_info.value)
+
+    def test_ethnicity_restriction_validation(self):
+        """Test that unsupported ethnicities are rejected during validation."""
+        # Test with unsupported ethnicity
+        user = UserInput(
+            demographics=Demographics(
+                age_years=40,
+                sex=Sex.FEMALE,
+                ethnicity=Ethnicity.ASHKENAZI_JEWISH,  # Not in supported list
+                anthropometrics=Anthropometrics(height_cm=165.0, weight_kg=65.0),
+            ),
+            lifestyle=Lifestyle(
+                smoking=SmokingHistory(status=SmokingStatus.NEVER),
+            ),
+            personal_medical_history=PersonalMedicalHistory(),
+        )
+
+        # Validation should fail
+        is_valid, errors = self.model.validate_inputs(user)
+        assert not is_valid
+        assert len(errors) == 1
+        assert "Field 'demographics.ethnicity': Input should be" in errors[0]
+        assert "WHITE" in errors[0] and "BLACK" in errors[0] and "ASIAN" in errors[0]
+
+    def test_supported_ethnicities_pass_validation(self):
+        """Test that all supported ethnicities pass validation."""
+        supported_ethnicities = [
+            Ethnicity.WHITE,
+            Ethnicity.BLACK,
+            Ethnicity.ASIAN,
+            Ethnicity.PACIFIC_ISLANDER,
+            Ethnicity.HISPANIC,
+        ]
+
+        for ethnicity in supported_ethnicities:
+            user = UserInput(
+                demographics=Demographics(
+                    age_years=40,
+                    sex=Sex.FEMALE,
+                    ethnicity=ethnicity,
+                    anthropometrics=Anthropometrics(height_cm=165.0, weight_kg=65.0),
+                ),
+                lifestyle=Lifestyle(
+                    smoking=SmokingHistory(status=SmokingStatus.NEVER),
+                ),
+                personal_medical_history=PersonalMedicalHistory(),
+            )
+
+            is_valid, errors = self.model.validate_inputs(user)
+            assert is_valid, f"Failed for ethnicity: {ethnicity}"
+            assert len(errors) == 0