RISK_MODELS.md

Risk Models Specification

This document outlines the requirements and specifications for implementing risk models in the Sentinel cancer risk assessment system.

Overview

Risk models in Sentinel are designed to calculate cancer risk scores using structured user input data. All risk models must follow a consistent architecture, use the new UserInput structure, implement proper validation, and maintain comprehensive test coverage.

Core Architecture

Base Class

All risk models must inherit from RiskModel in src/sentinel/risk_models/base.py:

from sentinel.risk_models.base import RiskModel

class YourRiskModel(RiskModel):
    def __init__(self):
        super().__init__("your_model_name")

Required Methods

Every risk model must implement these abstract methods:

def compute_score(self, user: UserInput) -> str:
    """Compute the risk score for a given user profile.

    Args:
        user: The user profile containing demographics, medical history, etc.

    Returns:
        str: Risk percentage as a string or an N/A message if inapplicable.

    Raises:
        ValueError: If required inputs are missing or invalid.
    """

def cancer_type(self) -> str:
    """Return the cancer type this model assesses."""
    return "breast"  # or "lung", "prostate", etc.

def description(self) -> str:
    """Return a detailed description of the model."""

def interpretation(self) -> str:
    """Return guidance on how to interpret the results."""

def references(self) -> list[str]:
    """Return list of reference citations."""

UserInput Structure

Required Imports

from typing import Annotated
from pydantic import Field
from sentinel.risk_models.base import RiskModel
from sentinel.user_input import (
    # Import specific enums and models you need
    CancerType,
    ChronicCondition,
    Demographics,
    Ethnicity,
    FamilyMemberCancer,
    FamilyRelation,
    FamilySide,
    RelationshipDegree,
    Sex,
    SymptomEntry,
    UserInput,
    # ... other specific imports
)

UserInput Hierarchy

The UserInput class follows a hierarchical structure:

UserInput
├── demographics: Demographics
│   ├── age_years: int
│   ├── sex: Sex (enum)
│   ├── ethnicity: Ethnicity | None
│   └── anthropometrics: Anthropometrics
│       ├── height_cm: float | None
│       └── weight_kg: float | None
├── lifestyle: Lifestyle
│   ├── smoking: SmokingHistory
│   └── alcohol: AlcoholConsumption
├── personal_medical_history: PersonalMedicalHistory
│   ├── chronic_conditions: list[ChronicCondition]
│   ├── previous_cancers: list[CancerType]
│   ├── genetic_mutations: list[GeneticMutation]
│   ├── tyrer_cuzick_polygenic_risk_score: float | None
│   └── # ... other fields
├── female_specific: FemaleSpecific | None
│   ├── menstrual: MenstrualHistory
│   ├── parity: ParityHistory
│   └── breast_health: BreastHealthHistory
├── symptoms: list[SymptomEntry]
└── family_history: list[FamilyMemberCancer]

REQUIRED_INPUTS Specification

Structure

Every risk model must define a REQUIRED_INPUTS class attribute using Pydantic's Annotated types with Field constraints:

REQUIRED_INPUTS: dict[str, tuple[type, bool]] = {
    "demographics.age_years": (Annotated[int, Field(ge=18, le=100)], True),
    "demographics.sex": (Sex, True),
    "demographics.ethnicity": (Ethnicity | None, False),
    "demographics.anthropometrics.height_cm": (Annotated[float, Field(gt=0)], False),
    "demographics.anthropometrics.weight_kg": (Annotated[float, Field(gt=0)], False),
    "female_specific.menstrual.age_at_menarche": (Annotated[int, Field(ge=8, le=25)], False),
    "personal_medical_history.tyrer_cuzick_polygenic_risk_score": (Annotated[float, Field(gt=0)], False),
    "family_history": (list, False),  # list[FamilyMemberCancer]
    "symptoms": (list, False),  # list[SymptomEntry]
}

Field Constraints

Use appropriate Field constraints for validation:

• ge=X: Greater than or equal to X
• le=X: Less than or equal to X
• gt=X: Greater than X
• lt=X: Less than X

Required vs Optional

• True: Field is required for the model
• False: Field is optional but validated if present

Input Validation

Validation in compute_score

Every compute_score method must start with input validation:

def compute_score(self, user: UserInput) -> str:
    """Compute the risk score for a given user profile."""
    # Validate inputs first
    is_valid, errors = self.validate_inputs(user)
    if not is_valid:
        raise ValueError(f"Invalid inputs for {self.name}: {'; '.join(errors)}")

    # Continue with model-specific logic...

Model-Specific Validation

Add additional validation as needed:

# Check sex applicability
if user.demographics.sex != Sex.FEMALE:
    return "N/A: Model is only applicable to female patients."

# Check age range
if not (35 <= user.demographics.age_years <= 85):
    return "N/A: Age is outside the validated range."

# Check required data availability
if user.female_specific is None:
    return "N/A: Missing female-specific information required for model."

Extending UserInput

When to Extend

If a risk model requires fields or enums that don't exist in UserInput, do not use replacement values or hacks. Instead, propose extending UserInput:

1. Missing Enums: Add new values to existing enums (e.g., ChronicCondition, SymptomType)
2. Missing Fields: Add new fields to appropriate sections (e.g., PersonalMedicalHistory, BreastHealthHistory)
3. Missing Models: Create new Pydantic models if needed

Extension Process

1. Identify Missing Elements: Document what's needed for the model
2. Propose Extension: Suggest specific additions to UserInput
3. Implement Extension: Add the new fields/enums to src/sentinel/user_input.py
4. Update Tests: Add tests for new fields in tests/test_user_input.py
5. Update Model: Use the new fields in your risk model
6. Run Tests: Ensure all tests pass

Example Extensions

# Adding new ChronicCondition enum values
class ChronicCondition(str, Enum):
    # ... existing values
    ENDOMETRIAL_POLYPS = "endometrial_polyps"
    ANAEMIA = "anaemia"

# Adding new fields to PersonalMedicalHistory
class PersonalMedicalHistory(StrictBaseModel):
    # ... existing fields
    tyrer_cuzick_polygenic_risk_score: float | None = Field(
        None,
        gt=0,
        description="Tyrer-Cuzick polygenic risk score as relative risk multiplier",
    )

# Adding new fields to BreastHealthHistory
class BreastHealthHistory(StrictBaseModel):
    # ... existing fields
    lobular_carcinoma_in_situ: bool | None = Field(
        None,
        description="History of lobular carcinoma in situ (LCIS) diagnosis",
    )

Data Access Patterns

Demographics

age = user.demographics.age_years
sex = user.demographics.sex
ethnicity = user.demographics.ethnicity
height_cm = user.demographics.anthropometrics.height_cm
weight_kg = user.demographics.anthropometrics.weight_kg

Female-Specific Data

if user.female_specific is not None:
    fs = user.female_specific
    menarche_age = fs.menstrual.age_at_menarche
    menopause_age = fs.menstrual.age_at_menopause
    num_births = fs.parity.num_live_births
    first_birth_age = fs.parity.age_at_first_live_birth
    num_biopsies = fs.breast_health.num_biopsies
    atypical_hyperplasia = fs.breast_health.atypical_hyperplasia
    lcis = fs.breast_health.lobular_carcinoma_in_situ

Medical History

chronic_conditions = user.personal_medical_history.chronic_conditions
previous_cancers = user.personal_medical_history.previous_cancers
genetic_mutations = user.personal_medical_history.genetic_mutations
polygenic_score = user.personal_medical_history.tyrer_cuzick_polygenic_risk_score

Family History

for member in user.family_history:
    if member.cancer_type == CancerType.BREAST:
        relation = member.relation
        age_at_diagnosis = member.age_at_diagnosis
        degree = member.degree
        side = member.side

Symptoms

for symptom in user.symptoms:
    symptom_type = symptom.symptom_type
    severity = symptom.severity
    duration_days = symptom.duration_days

Enum Usage

Always Use Enums

Never use string literals. Always use the appropriate enums:

# ✅ Correct
if user.demographics.sex == Sex.FEMALE:
if member.cancer_type == CancerType.BREAST:
if member.relation == FamilyRelation.MOTHER:
if member.degree == RelationshipDegree.FIRST:
if member.side == FamilySide.MATERNAL:

# ❌ Incorrect
if user.demographics.sex == "female":
if member.cancer_type == "breast":
if member.relation == "mother":

Enum Mapping

When you need to map enums to model-specific codes:

def _race_code_from_ethnicity(ethnicity: Ethnicity | None) -> int:
    """Map ethnicity enum to model-specific race code."""
    if not ethnicity:
        return 1  # Default

    if ethnicity == Ethnicity.BLACK:
        return 2
    if ethnicity in {Ethnicity.ASIAN, Ethnicity.PACIFIC_ISLANDER}:
        return 3
    if ethnicity == Ethnicity.HISPANIC:
        return 6
    return 1  # Default to White

Testing Requirements

Test File Structure

Create comprehensive test files following this pattern:

import pytest
from sentinel.user_input import (
    # Import all needed models and enums
    Anthropometrics,
    BreastHealthHistory,
    CancerType,
    Demographics,
    Ethnicity,
    FamilyMemberCancer,
    FamilyRelation,
    FamilySide,
    FemaleSpecific,
    Lifestyle,
    MenstrualHistory,
    ParityHistory,
    PersonalMedicalHistory,
    RelationshipDegree,
    Sex,
    SmokingHistory,
    SmokingStatus,
    UserInput,
)
from sentinel.risk_models import YourRiskModel

# Ground truth test cases
GROUND_TRUTH_CASES = [
    {
        "name": "test_case_name",
        "input": UserInput(
            demographics=Demographics(
                age_years=40,
                sex=Sex.FEMALE,
                ethnicity=Ethnicity.WHITE,
                anthropometrics=Anthropometrics(height_cm=165.0, weight_kg=65.0),
            ),
            lifestyle=Lifestyle(
                smoking=SmokingHistory(status=SmokingStatus.NEVER),
            ),
            personal_medical_history=PersonalMedicalHistory(),
            female_specific=FemaleSpecific(
                menstrual=MenstrualHistory(age_at_menarche=13),
                parity=ParityHistory(num_live_births=1, age_at_first_live_birth=25),
                breast_health=BreastHealthHistory(),
            ),
            family_history=[
                FamilyMemberCancer(
                    relation=FamilyRelation.MOTHER,
                    cancer_type=CancerType.BREAST,
                    age_at_diagnosis=55,
                    degree=RelationshipDegree.FIRST,
                    side=FamilySide.MATERNAL,
                )
            ],
        ),
        "expected": 1.5,  # Expected risk percentage
    },
    # ... more test cases
]

class TestYourRiskModel:
    """Test suite for YourRiskModel."""

    def setup_method(self):
        """Initialize model instance for testing."""
        self.model = YourRiskModel()

    @pytest.mark.parametrize("case", GROUND_TRUTH_CASES, ids=lambda x: x["name"])
    def test_ground_truth_validation(self, case):
        """Test against ground truth results."""
        user_input = case["input"]
        expected_risk = case["expected"]

        actual_risk_str = self.model.compute_score(user_input)

        if "N/A" in actual_risk_str:
            pytest.fail(f"Model returned N/A: {actual_risk_str}")

        actual_risk = float(actual_risk_str)
        assert actual_risk == pytest.approx(expected_risk, abs=0.01)

    def test_validation_errors(self):
        """Test that model raises ValueError for invalid inputs."""
        # Test invalid age
        user_input = UserInput(
            demographics=Demographics(
                age_years=30,  # Below minimum
                sex=Sex.FEMALE,
                anthropometrics=Anthropometrics(height_cm=165.0, weight_kg=65.0),
            ),
            # ... rest of input
        )

        with pytest.raises(ValueError, match=r"Invalid inputs for.*:"):
            self.model.compute_score(user_input)

    def test_inapplicable_cases(self):
        """Test cases where model returns N/A."""
        # Test male patient
        user_input = UserInput(
            demographics=Demographics(
                age_years=50,
                sex=Sex.MALE,  # Wrong sex
                anthropometrics=Anthropometrics(height_cm=175.0, weight_kg=70.0),
            ),
            # ... rest of input
        )

        score = self.model.compute_score(user_input)
        assert "N/A" in score

Test Coverage Requirements

• Ground Truth Validation: Test against known reference values
• Input Validation: Test that invalid inputs raise ValueError
• Edge Cases: Test boundary conditions and edge cases
• Inapplicable Cases: Test cases where model should return "N/A"
• Enum Usage: Test that all enums are used correctly
• Family History: Test various family relationship combinations
• Error Handling: Test error conditions and exception handling

Code Quality Requirements

Pre-commit Hooks

All code must pass these pre-commit hooks:

• unimport: Remove unused imports
• ruff format: Code formatting
• ruff check: Linting and style checks
• pylint: Code quality analysis
• darglint: Docstring validation
• pydocstyle: Docstring style checks
• codespell: Spell checking

Code Style

• Use type hints throughout
• Write clear, concise docstrings
• Follow PEP 8 style guidelines
• Use meaningful variable names
• Add comments for complex logic
• Handle edge cases gracefully

Error Handling

def compute_score(self, user: UserInput) -> str:
    """Compute the risk score for a given user profile."""
    try:
        # Validate inputs
        is_valid, errors = self.validate_inputs(user)
        if not is_valid:
            raise ValueError(f"Invalid inputs for {self.name}: {'; '.join(errors)}")

        # Model-specific validation
        if user.demographics.sex != Sex.FEMALE:
            return "N/A: Model is only applicable to female patients."

        # Calculate risk
        risk = self._calculate_risk(user)
        return f"{risk:.2f}"

    except Exception as e:
        return f"N/A: Error calculating risk - {e!s}"

Migration Checklist

When adapting an existing risk model to the new structure:

• Update imports to use new user_input module
• Add REQUIRED_INPUTS with Pydantic validation
• Refactor compute_score to use new UserInput structure
• Replace string literals with enums
• Update parameter extraction logic
• Add input validation at start of compute_score
• Update all test cases to use new UserInput structure
• Run full test suite to ensure 100% pass rate
• Run pre-commit hooks to ensure code quality
• Document any UserInput extensions needed
• Update model documentation and references

Examples

Complete Risk Model Template

"""Your cancer risk model implementation."""

from typing import Annotated
from pydantic import Field
from sentinel.risk_models.base import RiskModel
from sentinel.user_input import (
    CancerType,
    Demographics,
    Ethnicity,
    FamilyMemberCancer,
    FamilyRelation,
    RelationshipDegree,
    Sex,
    UserInput,
)

class YourRiskModel(RiskModel):
    """Compute cancer risk using the Your model."""

    def __init__(self):
        super().__init__("your_model")

    REQUIRED_INPUTS: dict[str, tuple[type, bool]] = {
        "demographics.age_years": (Annotated[int, Field(ge=18, le=100)], True),
        "demographics.sex": (Sex, True),
        "demographics.ethnicity": (Ethnicity | None, False),
        "family_history": (list, False),  # list[FamilyMemberCancer]
    }

    def compute_score(self, user: UserInput) -> str:
        """Compute the risk score for a given user profile."""
        # Validate inputs first
        is_valid, errors = self.validate_inputs(user)
        if not is_valid:
            raise ValueError(f"Invalid inputs for Your: {'; '.join(errors)}")

        # Model-specific validation
        if user.demographics.sex != Sex.FEMALE:
            return "N/A: Model is only applicable to female patients."

        # Extract parameters
        age = user.demographics.age_years
        ethnicity = user.demographics.ethnicity

        # Count family history
        family_count = sum(
            1 for member in user.family_history
            if member.cancer_type == CancerType.BREAST
            and member.degree == RelationshipDegree.FIRST
        )

        # Calculate risk (example)
        risk = self._calculate_risk(age, family_count, ethnicity)
        return f"{risk:.2f}"

    def _calculate_risk(self, age: int, family_count: int, ethnicity: Ethnicity | None) -> float:
        """Calculate the actual risk value."""
        # Implementation here
        return 1.5  # Example

    def cancer_type(self) -> str:
        return "breast"

    def description(self) -> str:
        return "Your model description here."

    def interpretation(self) -> str:
        return "Interpretation guidance here."

    def references(self) -> list[str]:
        return ["Your reference here."]

This specification ensures consistency, maintainability, and quality across all risk models in the Sentinel system.