Sync from GitHub (main)

AGENTS.md

@@ -1,4 +1,4 @@
-# Repo Guidelines
+# Repository Guidelines
 
 This repository contains the LLM-based Cancer Risk Assessment Assistant.
 
@@ -8,11 +8,33 @@ This repository contains the LLM-based Cancer Risk Assessment Assistant.
 - **uv** for environment and dependency management
 - **hydra:** for configuration management
 
-## Coding Philosophy
-- Prioritize clarity and reusability.
-- Favor simple replication over heavy abstraction.
-- Keep comments short and only where the code isn't self-explanatory.
-- Avoid verbose docstrings for simple functions.
+## Development Setup
+
+### Environment Setup
+- Create the virtual environment (at '.venv') with `uv sync`.
+- As the repository uses uv, the uv should be used to run all commands, e.g., "uv run python ..." NOT "python ...".
+
+### Running Commands
+- **Streamlit Interface**: `uv run streamlit run apps/streamlit_ui/main.py`
+- **CLI Demo**: `uv run python apps/cli/main.py`
+- **Tests**: `uv run pytest`
+
+The multi-page Streamlit interface for expert feedback can be launched with `uv run streamlit run apps/streamlit_ui/main.py`.
+The first page, **User Profile**, allows experts to load or create a profile stored in `st.session_state.user_profile`.
+The second page, **Configuration**, lets experts choose the model and knowledge base modules while previewing the generated prompt.
+The third page, **Assessment**, runs the AI analysis, displays a results dashboard, and provides export and chat options.
+
+## Coding Standards
+
+### Coding Philosophy
+- Write simple, explicit, modular code
+- Prioritize clarity over cleverness
+- Prefer small pure functions over large ones
+- Return early instead of nesting deeply
+- Favor functions over classes unless essential
+- Favor simple replication over heavy abstraction
+- Keep comments short and only where code isn't self-explanatory
+- Avoid premature optimization or over-engineering
 
 ### Variable Naming
 - **Avoid single-letter variable names** (x, y, i, j, e, t, f, m, c, ct) in favor of descriptive names.
@@ -45,40 +67,105 @@ This repository contains the LLM-based Cancer Risk Assessment Assistant.
 - `f in MODELS_DIR.glob` → `file_path in MODELS_DIR.glob`
 - `t in field_type.__args__` → `type_arg in field_type.__args__`
 
+### Path Handling
+- **Always use `pathlib.Path`** for all file I/O, joining, and globbing
+- Accept `Path | str` at function boundaries; normalize to `Path` internally
+- **Never use `os.path`** for path operations
+
+Example:
+```python
+from pathlib import Path
+
+def read_text(file: Path | str) -> str:
+    path = Path(file)
+    return path.read_text(encoding="utf-8")
+```
+
+### Type Hints and Modern Python
+- **Use modern type hints**: `list`, `dict`, `tuple`, `set` (not `List`, `Dict`, etc.)
+- **Use PEP 604 unions**: `A | B` (not `Union[A, B]` or `Optional[A]`)
+- Import from `typing` only when necessary (`TypedDict`, `Literal`, `Annotated`, etc.)
+- **Never use** `from __future__ import annotations`
+- Add type hints to all public functions and methods
+- Prefer precise types (`float`, `Path`, etc.) over generic ones
+- If `Any` is required, isolate and document why
+
 ### Import Management
-- **Place all imports at the top of the file**, not inside functions.
-- This improves performance (imports loaded once) and code readability.
-- Group imports logically: standard library, third-party, local modules.
+- **Place all imports at the top of the file**, never inside functions or classes
+- Group imports in three sections with blank lines between:
+  1. Standard library imports
+  2. Third-party library imports
+  3. Local/project imports
+- This improves performance (imports loaded once) and code readability
+
+### Error Handling and Logging
+- **Use `try/except` only for I/O or external APIs**
+- Catch specific exceptions only (never broad `except:`)
+- Raise clear, actionable error messages
+- **Use `loguru`** for logging, never `print()` in production code
+
+Example:
+```python
+from loguru import logger
+
+try:
+    data = Path(file_path).read_text(encoding="utf-8")
+except FileNotFoundError as error:
+    logger.error(f"Configuration file not found: {file_path}")
+    raise ValueError(f"Missing required config: {file_path}") from error
+```
+
+### Docstring Standards
+- **Use Google-style docstrings** for all public functions and classes
+- Do NOT include type hints in docstrings (they're in the signature)
+- Describe behavior, invariants, side effects, and edge cases
+- Include examples for complex functions
+- Avoid verbose docstrings for simple, self-explanatory functions
 
 ## Testing
-- Write meaningful tests that verify core functionality and prevent regressions.
-- Run tests with `uv run pytest`.
 
-## Development Setup
-- Create the virtual environment (at '.venv') with `uv sync`.
+### Testing Philosophy
+- Write meaningful tests that verify core functionality and prevent regressions
+- Use `pytest` as the testing framework
+- Tests go under `tests/` mirroring the source layout
+- Test both valid and invalid input scenarios
 
-## Running commands
-- As the repository uses uv, the uv should be used to run all commands, e.g., "uv run python ..." NOT "python ...".
+### Test Types
+- **Unit tests**: Small, deterministic, one concept per test
+- **Integration tests**: Real workflows or reference comparisons with external systems
+- Use `pytest.mark` to tag slow or manual tests
 
-These guidelines apply to the entire repository. A multi-page Streamlit
-interface for expert feedback can be launched with `uv run streamlit run
-apps/streamlit_ui/main.py`.
-The first page, **User Profile**, allows experts to load or create a profile
-stored in `st.session_state.user_profile`.
-The second page, **Configuration**, lets experts choose the model and knowledge base modules while previewing the generated prompt.
-The third page, **Assessment**, runs the AI analysis, displays a results dashboard, and provides export and chat options.
+### Test Coverage Requirements
+- Ensure comprehensive test coverage for all risk models
+- **Ground Truth Validation**: Test against known reference values
+- **Input Validation**: Test that invalid inputs raise `ValueError`
+- **Edge Cases**: Test boundary conditions
+- **Inapplicable Cases**: Test when models should return "N/A"
 
-## Important Note for Developers
+### Running Tests
+```bash
+uv run pytest              # Run all tests
+uv run pytest -q          # Quiet mode
+uv run pytest -v          # Verbose mode
+uv run pytest tests/test_risk_models/  # Specific directory
+```
 
-When making changes to the project, ensure that the following files are updated to reflect the changes:
+### Pre-Submission Checklist
+Before committing code, verify:
+1. ✅ Run `uv run pytest -q` (all tests pass)
+2. ✅ Run `pre-commit run --all-files` (all hooks pass)
+3. ✅ No `print()` statements in production code
+4. ✅ No broad `except:` blocks
+5. ✅ All type hints present on public functions
+6. ✅ File paths use `pathlib.Path`
+7. ✅ Logging uses `loguru`
 
-- `README.md`
-- `AGENTS.md`
-- `GEMINI.md`
+## Risk Models
+
+### Implemented Models
 
-## Risk Model Coverage
+The assistant currently includes the following built-in risk calculators:
 
-Implemented risk calculators include:
 - **Gail** - Breast cancer risk
 - **Claus** - Breast cancer risk based on family history
 - **BOADICEA** - Breast and ovarian cancer risk (via CanRisk API)
@@ -91,3 +178,268 @@ Implemented risk calculators include:
 - **QCancer** - Multi-site cancer differential
 
 Additional models should follow the interfaces under `src/sentinel/risk_models`.
+
+### Risk Model Implementation Guide
+
+#### Base Architecture
+
+All risk models must inherit from `RiskModel` in `src/sentinel/risk_models/base.py`:
+
+```python
+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:
+
+```python
+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
+
+**All risk models must use the centralized `UserInput` structure** - this is the single source of truth for all data types and enums. 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
+├── female_specific: FemaleSpecific | None
+│   ├── menstrual: MenstrualHistory
+│   ├── parity: ParityHistory
+│   └── breast_health: BreastHealthHistory
+├── symptoms: list[SymptomEntry]
+└── family_history: list[FamilyMemberCancer]
+```
+
+#### REQUIRED_INPUTS Specification
+
+Every risk model must define a `REQUIRED_INPUTS` class attribute using Pydantic's `Annotated` types with `Field` constraints:
+
+```python
+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]
+    "symptoms": (list, False),  # list[SymptomEntry]
+}
+```
+
+#### Input Validation
+
+Every `compute_score` method must start with input validation:
+
+```python
+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)}")
+
+    # Model-specific validation
+    if user.demographics.sex != Sex.FEMALE:
+        return "N/A: Model is only applicable to female patients."
+
+    # Continue with model-specific logic...
+```
+
+#### Data Access Patterns
+
+```python
+# Demographics
+age = user.demographics.age_years
+sex = user.demographics.sex
+ethnicity = user.demographics.ethnicity
+
+# Female-specific data
+if user.female_specific is not None:
+    menarche_age = user.female_specific.menstrual.age_at_menarche
+    num_births = user.female_specific.parity.num_live_births
+
+# Family history
+for member in user.family_history:
+    if member.cancer_type == CancerType.BREAST:
+        relation = member.relation
+        age_at_diagnosis = member.age_at_diagnosis
+```
+
+#### Enum Usage
+
+**Always use enums from `sentinel.user_input`, never string literals or custom enums:**
+
+```python
+# ✅ Correct - using UserInput enums
+if user.demographics.sex == Sex.FEMALE:
+if member.cancer_type == CancerType.BREAST:
+if member.relation == FamilyRelation.MOTHER:
+
+# ❌ Incorrect - string literals
+if user.demographics.sex == "female":
+if member.cancer_type == "breast":
+
+# ❌ Incorrect - custom enums
+if user.demographics.sex == MyCustomSex.FEMALE:
+```
+
+**Important**: All risk models must use the same centralized enums from `UserInput`. If a required enum doesn't exist in `UserInput`, you must:
+1. **Extend UserInput** by adding the new enum to `src/sentinel/user_input.py`
+2. **Never create model-specific enums** - this prevents divergence between models
+3. **Update all models** to use the new centralized enum
+
+This ensures all risk models share the same data structure and prevents fragmentation.
+
+#### Extending UserInput
+
+When a risk model needs fields or enums that don't exist in `UserInput`:
+
+1. **Add to UserInput**: Extend `src/sentinel/user_input.py` with new fields/enums
+2. **Update all models**: Ensure all existing models can handle the new fields (use `| None` for optional fields)
+3. **Never create model-specific structures**: This prevents divergence and fragmentation
+4. **Test thoroughly**: Add tests for new fields in `tests/test_user_input.py`
+
+Example of extending UserInput:
+```python
+# In src/sentinel/user_input.py
+class ChronicCondition(str, Enum):
+    # ... existing values
+    NEW_CONDITION = "new_condition"  # Add new enum value
+
+class PersonalMedicalHistory(StrictBaseModel):
+    # ... existing fields
+    new_field: float | None = Field(None, description="New field description")
+```
+
+#### Testing Requirements
+
+Create comprehensive test files with:
+- **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"
+
+Example test structure:
+
+```python
+import pytest
+from sentinel.user_input import UserInput, Demographics, Sex
+from sentinel.risk_models import YourRiskModel
+
+GROUND_TRUTH_CASES = [
+    {
+        "name": "test_case_name",
+        "input": UserInput(
+            demographics=Demographics(
+                age_years=40,
+                sex=Sex.FEMALE,
+                # ... other fields
+            ),
+            # ... rest of input
+        ),
+        "expected": 1.5,  # Expected risk percentage
+    },
+    # ... more test cases
+]
+
+class TestYourRiskModel:
+    @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)
+        actual_risk = float(actual_risk_str)
+        assert actual_risk == pytest.approx(expected_risk, abs=0.01)
+```
+
+#### 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
+
+## LLM and Code Assistant Guidelines
+
+When generating or modifying code, AI assistants MUST:
+
+### Mandatory Rules
+- Follow ALL guidelines in this document without exception
+- Never use forbidden constructs (`os.path`, `Optional[]`, `List[]`, `print()`, broad `except:`)
+- Never add decorative comment banners or unnecessary formatting
+- Always generate clean, modular, statically typed code
+
+### Code Generation Standards
+- Prefer clarity and simplicity over cleverness
+- Use modern Python type hints exclusively
+- Include comprehensive docstrings for non-trivial functions
+- Ensure all examples compile, type-check, and pass linting
+
+### Verification
+All generated code must:
+- Pass `ruff format` and `ruff check`
+- Include proper type hints
+- Use `pathlib.Path` for all file operations
+- Use `loguru` for logging
+- Follow the Variable Naming guidelines
+
+## Important Note for Developers
+
+When making changes to the project, ensure that the following files are updated to reflect the changes:
+
+- `README.md`
+- `AGENTS.md`
+- `GEMINI.md`
+
+For additional implementation details, refer to the existing risk model implementations in `src/sentinel/risk_models/`.