Sync from GitHub (main)

AGENTS.md

@@ -14,6 +14,42 @@ This repository contains the LLM-based Cancer Risk Assessment Assistant.
 - Keep comments short and only where the code isn't self-explanatory.
 - Avoid verbose docstrings for simple functions.
 
+### Variable Naming
+- **Avoid single-letter variable names** (x, y, i, j, e, t, f, m, c, ct) in favor of descriptive names.
+- **Avoid abbreviations** (fh, ct, w, h) in favor of full descriptive names.
+- Use context-specific names for loop indices based on what you're iterating over:
+  - `item_index` for general enumeration
+  - `line_index` for text line iteration
+  - `column_index` for table/array column iteration
+  - `row_index` for table/array row iteration
+- Use descriptive names for comprehensions and iterations:
+  - `item` instead of `i` for general items
+  - `element` instead of `e` for list elements
+  - `key` instead of `k` for dictionary keys
+  - `value` instead of `v` for dictionary values
+- Use descriptive names for coordinates and positions:
+  - `x_position`, `y_position` instead of `x`, `y`
+  - `width`, `height` instead of `w`, `h`
+- Use descriptive names for data structures:
+  - `file_path` instead of `f` for file paths
+  - `model` instead of `m` for model instances
+  - `user` instead of `u` for user objects
+
+**Examples from recent refactoring:**
+- `for i, ref in enumerate(references)` → `for ref_index, ref in enumerate(references)`
+- `for e in examples` → `for example in examples`
+- `for m in models` → `for model in models`
+- `x = pdf.get_x()` → `x_position = pdf.get_x()`
+- `fh = family_history` → `family_history = family_history` (avoid abbreviations)
+- `ct for ct in cancer_types` → `cancer_type for cancer_type in cancer_types`
+- `f in MODELS_DIR.glob` → `file_path in MODELS_DIR.glob`
+- `t in field_type.__args__` → `type_arg in field_type.__args__`
+
+### 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.
+
 ## Testing
 - Write meaningful tests that verify core functionality and prevent regressions.
 - Run tests with `uv run pytest`.

scripts/generate_documentation.py

@@ -7,6 +7,7 @@ import re
 from collections import defaultdict
 from collections.abc import Iterable, Iterator
 from dataclasses import dataclass
+from enum import Enum
 from pathlib import Path
 from typing import Any, Union, get_args, get_origin
 
@@ -15,6 +16,7 @@ from annotated_types import Ge, Gt, Le, Lt
 from fpdf import FPDF
 from pydantic import BaseModel
 
+from sentinel.models import Sex
 from sentinel.risk_models.base import RiskModel
 from sentinel.risk_models.qcancer import (
     FEMALE_CANCER_TYPES as QC_FEMALE_CANCERS,
@@ -22,7 +24,7 @@ from sentinel.risk_models.qcancer import (
 from sentinel.risk_models.qcancer import (
     MALE_CANCER_TYPES as QC_MALE_CANCERS,
 )
-from sentinel.user_input import UserInput
+from sentinel.user_input import GeneticMutation, Lifestyle, UserInput
 
 # Constants
 HERE = Path(__file__).resolve().parent
@@ -50,6 +52,7 @@ class LinkManager:
     def __init__(self):
         self.model_path_to_link_id: dict[str, int] = {}
         self.next_link_id = 1
+        self.pending_links: list[tuple[str, float, float, float, float]] = []
 
     def get_or_create_link_id(self, model_path: str) -> int:
         """Get or create a link ID for a model path.
@@ -75,6 +78,35 @@ class LinkManager:
         link_id = self.get_or_create_link_id(model_path)
         pdf.set_link(link_id, y=pdf.get_y())
 
+    def store_link_info(
+        self,
+        model_path: str,
+        x_position: float,
+        y_position: float,
+        width: float,
+        height: float,
+    ) -> None:
+        """Store link information for later creation.
+
+        Args:
+            model_path: The path to the model
+            x_position: X position
+            y_position: Y position
+            width: Link width
+            height: Link height
+        """
+        self.pending_links.append((model_path, x_position, y_position, width, height))
+
+    def create_pending_links(self, pdf: FPDF) -> None:
+        """Create all pending links after destinations are created.
+
+        Args:
+            pdf: The PDF instance
+        """
+        for model_path, x_position, y_position, width, height in self.pending_links:
+            link_id = self.get_or_create_link_id(model_path)
+            pdf.link(x_position, y_position, width, height, link_id)
+
 
 # ---------------------------------------------------------------------------
 # Metadata extraction helpers
@@ -97,6 +129,688 @@ def _get_enum_choices(annotation: Any) -> list[str] | None:
     return None
 
 
+def extract_enum_info(enum_class: type[Enum]) -> dict:
+    """Extract enum values and descriptions from docstring.
+
+    Args:
+        enum_class: The enum class to extract information from
+
+    Returns:
+        dict with:
+        - name: Enum class name
+        - description: Class-level description
+        - values: List of (value_name, value, description) tuples
+    """
+    name = enum_class.__name__
+    docstring = enum_class.__doc__ or ""
+
+    # Extract class description (first paragraph before Attributes)
+    description = ""
+    if docstring:
+        # Split by "Attributes:" to get the main description
+        parts = docstring.split("Attributes:")
+        if parts:
+            description = parts[0].strip()
+            # Clean up the description
+            description = re.sub(r"\s+", " ", description)
+            description = description.replace("\n", " ").strip()
+
+    # Extract individual value descriptions from Attributes section
+    value_descriptions = {}
+    if "Attributes:" in docstring:
+        attributes_section = docstring.split("Attributes:")[1]
+        # Parse lines like "VALUE_NAME: Description text"
+        for line in attributes_section.split("\n"):
+            line = line.strip()
+            if ":" in line and not line.startswith(" "):
+                parts = line.split(":", 1)
+                if len(parts) == 2:
+                    value_name = parts[0].strip()
+                    value_desc = parts[1].strip()
+                    value_descriptions[value_name] = value_desc
+
+    # Build values list
+    values = []
+    for member_name, member_value in enum_class.__members__.items():
+        description_text = value_descriptions.get(member_name, "")
+        values.append((member_name, member_value.value, description_text))
+
+    return {"name": name, "description": description, "values": values}
+
+
+def count_genomic_mutations() -> int:
+    """Count the number of genomic mutation values available.
+
+    Returns:
+        int: Number of genetic mutation enum values available
+    """
+    return len(GeneticMutation.__members__)
+
+
+def count_lifestyle_factors() -> int:
+    """Count the number of fields in the Lifestyle model.
+
+    Returns:
+        int: Number of fields in the Lifestyle model
+    """
+    return len(Lifestyle.model_fields)
+
+
+def count_total_input_categories() -> int:
+    """Count total number of leaf field categories across UserInput.
+
+    Returns:
+        int: Total number of leaf field categories across all models
+    """
+    structure = traverse_user_input_structure(UserInput)
+    # Count only leaf fields (where model_class is None)
+    return sum(1 for _, _, model_class in structure if model_class is None)
+
+
+def count_total_discrete_choices() -> int:
+    """Count total number of enum member values across all enums.
+
+    Returns:
+        int: Total number of enum member values across all enums
+    """
+    enums_by_parent = collect_all_enums()
+    total = 0
+    for parent_enums in enums_by_parent.values():
+        for enum_info in parent_enums.values():
+            total += len(enum_info["values"])
+    return total
+
+
+def collect_all_enums() -> dict[str, dict]:
+    """Collect all enum types used in UserInput, grouped by parent model.
+
+    Returns:
+        dict: {parent_model_name: {enum_name: enum_info}}
+    """
+    enums_by_parent = defaultdict(dict)
+    seen_enums = set()
+
+    def extract_enums_from_type(field_type: Any, parent_path: str = "") -> None:
+        """Recursively extract enum types from field annotations.
+
+        Args:
+            field_type: The field type annotation to check
+            parent_path: The path to the parent model
+        """
+        # Check if it's a direct enum
+        if hasattr(field_type, "__members__"):
+            if field_type not in seen_enums:
+                seen_enums.add(field_type)
+                enum_info = extract_enum_info(field_type)
+                parent_name = parent_path.split(".")[0] if parent_path else "Root"
+                enums_by_parent[parent_name][enum_info["name"]] = enum_info
+            return
+
+        # Check Union types
+        if hasattr(field_type, "__args__"):
+            for arg in field_type.__args__:
+                extract_enums_from_type(arg, parent_path)
+
+        # Check if it's a list or other container
+        origin = get_origin(field_type)
+        if origin is list and hasattr(field_type, "__args__"):
+            args = get_args(field_type)
+            if args:
+                extract_enums_from_type(args[0], parent_path)
+
+    # Traverse UserInput structure to find all enum fields
+    structure = traverse_user_input_structure(UserInput)
+
+    for field_path, _field_name, model_class in structure:
+        if model_class is not None:
+            # This is a nested model, check its fields
+            for _field_name_inner, field_info in model_class.model_fields.items():
+                field_type = field_info.annotation
+                extract_enums_from_type(field_type, field_path)
+        else:
+            # This is a leaf field, check its type
+            if "." in field_path:
+                parent_path = ".".join(field_path.split(".")[:-1])
+            else:
+                parent_path = ""
+
+            # Get the field from UserInput
+            current_model = UserInput
+            for part in field_path.split("."):
+                if hasattr(current_model, part):
+                    field_info = current_model.model_fields.get(part)
+                    if field_info:
+                        extract_enums_from_type(field_info.annotation, parent_path)
+                    break
+
+    return dict(enums_by_parent)
+
+
+def render_enum_choices_section(
+    pdf: FPDF, enums_by_parent: dict, link_manager: LinkManager
+) -> None:
+    """Render Section 3 with enum tables grouped by parent model.
+
+    Args:
+        pdf: Active PDF instance
+        enums_by_parent: Dict of enums grouped by parent model
+        link_manager: Link manager for creating hyperlinks
+    """
+    section_counter = 1
+
+    for parent_name, enums in enums_by_parent.items():
+        if not enums:
+            continue
+
+        # Add subsection heading
+        pdf.set_font("Helvetica", "B", 12)
+        pdf.set_text_color(*THEME_PRIMARY)
+        # Capitalize first letter and remove "Enums" suffix
+        formatted_parent_name = parent_name.replace("_", " ").title()
+
+        # Create link destination for this subsection
+        subsection_link_id = f"enum_{parent_name}"
+        link_manager.create_link_destination(pdf, subsection_link_id)
+
+        pdf.write(7, f"3.{section_counter} {formatted_parent_name}")
+        pdf.ln(8)
+
+        for enum_name, enum_info in enums.items():
+            # Create link destination for the enum
+            enum_link_id = f"enum_{enum_name}"
+            link_manager.create_link_destination(pdf, enum_link_id)
+
+            # Add enum heading with name and description
+            pdf.set_font("Helvetica", "B", 11)
+            pdf.set_text_color(*THEME_PRIMARY)
+            # Format enum name: convert CamelCase to "Camel Case" and capitalize
+            formatted_enum_name = " ".join(
+                word.capitalize()
+                for word in re.findall(r"[A-Z][a-z]*|[a-z]+", enum_name)
+            )
+            pdf.write(7, f"{formatted_enum_name}")
+            pdf.ln(6)
+
+            # Add enum description if available
+            if enum_info["description"]:
+                pdf.set_font("Helvetica", "", 9)
+                pdf.set_text_color(*TEXT_DARK)
+                pdf.multi_cell(0, 4, enum_info["description"], 0, "L")
+                pdf.ln(3)
+
+            # Create table for enum values
+            table_width = pdf.w - 2 * pdf.l_margin
+            value_width = table_width * 0.25
+            description_width = table_width * 0.75
+
+            # Table header
+            pdf.set_font("Helvetica", "B", 10)
+            pdf.set_fill_color(*TABLE_HEADER_BACKGROUND)
+            pdf.set_text_color(*TEXT_LIGHT)
+            pdf.cell(value_width, 8, "Value", 0, 0, "L", True)
+            pdf.cell(description_width, 8, "Description", 0, 1, "L", True)
+
+            # Table rows with alternating colors
+            pdf.set_font("Helvetica", "", 9)
+            pdf.set_text_color(*TEXT_DARK)
+            line_height = 5.5
+
+            for idx, (_value_name, value, description) in enumerate(
+                enum_info["values"]
+            ):
+                # Check if we need a page break
+                if pdf.get_y() + 15 > pdf.h - pdf.b_margin:
+                    pdf.add_page()
+                    # Re-render table header on new page
+                    pdf.set_font("Helvetica", "B", 10)
+                    pdf.set_fill_color(*TABLE_HEADER_BACKGROUND)
+                    pdf.set_text_color(*TEXT_LIGHT)
+                    pdf.cell(value_width, 8, "Value", 0, 0, "L", True)
+                    pdf.cell(description_width, 8, "Description", 0, 1, "L", True)
+                    pdf.set_font("Helvetica", "", 9)
+                    pdf.set_text_color(*TEXT_DARK)
+
+                # Alternate row colors
+                fill_color = (
+                    ROW_BACKGROUND_LIGHT if idx % 2 == 0 else ROW_BACKGROUND_ALT
+                )
+
+                # Use the same table row rendering as Section 2
+                render_table_row(
+                    pdf,
+                    [str(value), description or "-"],
+                    [value_width, description_width],
+                    line_height,
+                    fill_color,
+                )
+
+            pdf.ln(4)
+
+        section_counter += 1
+
+
+def render_risk_models_section(
+    pdf: FPDF, models: list[RiskModel], link_manager: LinkManager
+) -> None:
+    """Render Section 4 with detailed risk model documentation.
+
+    For each model, display:
+    - Model name (as section heading)
+    - Description
+    - Reference/citation
+    - Cancer types covered
+    - Table of admissible input fields
+
+    Args:
+        pdf: Active PDF instance
+        models: List of risk model instances
+        link_manager: Link manager for creating hyperlinks
+    """
+    section_counter = 1
+
+    for model in models:
+        # Add subsection heading for each model
+        pdf.set_font("Helvetica", "B", 12)
+        pdf.set_text_color(*THEME_PRIMARY)
+
+        # Create link destination for this model
+        model_link_id = f"model_{model.__class__.__name__}"
+        link_manager.create_link_destination(pdf, model_link_id)
+
+        model_name = getattr(model, "name", model.__class__.__name__)
+        # Convert underscores to spaces and capitalize each word
+        formatted_name = model_name.replace("_", " ").title()
+        pdf.write(7, f"4.{section_counter} {formatted_name}")
+        pdf.ln(8)
+
+        # Extract model information
+        model_info = extract_model_metadata(model)
+
+        # Render model description
+        if model_info["description"]:
+            pdf.set_font("Helvetica", "", 10)
+            pdf.set_text_color(*TEXT_DARK)
+            pdf.multi_cell(0, 5, model_info["description"], 0, "L")
+            pdf.ln(3)
+
+        # Render interpretation if available
+        if model_info["interpretation"]:
+            pdf.set_font("Helvetica", "B", 10)
+            pdf.set_text_color(*THEME_PRIMARY)
+            pdf.cell(0, 5, "Interpretation:", 0, 1)
+            pdf.set_font("Helvetica", "", 9)
+            pdf.set_text_color(*TEXT_DARK)
+            pdf.multi_cell(0, 4, model_info["interpretation"], 0, "L")
+            pdf.ln(3)
+
+        # Render reference if available
+        if model_info["reference"]:
+            pdf.set_font("Helvetica", "B", 10)
+            pdf.set_text_color(*THEME_PRIMARY)
+            pdf.cell(0, 5, "Reference:", 0, 1)
+            pdf.set_font("Helvetica", "I", 9)
+            pdf.set_text_color(*THEME_MUTED)
+            pdf.multi_cell(0, 4, model_info["reference"], 0, "L")
+            pdf.ln(3)
+
+        # Render cancer types covered
+        cancer_types = cancer_types_for_model(model)
+        if cancer_types:
+            pdf.set_font("Helvetica", "B", 10)
+            pdf.set_text_color(*THEME_PRIMARY)
+            pdf.cell(0, 5, "Cancer Types Covered:", 0, 1)
+            pdf.set_font("Helvetica", "", 9)
+            pdf.set_text_color(*THEME_MUTED)
+            cancer_types_str = ", ".join(cancer_types)
+            pdf.multi_cell(0, 4, cancer_types_str, 0, "L")
+            pdf.ln(3)
+
+        # Add subheading for input requirements
+        pdf.set_font("Helvetica", "B", 11)
+        pdf.set_text_color(*THEME_PRIMARY)
+        pdf.cell(0, 6, "Input Requirements", 0, 1)
+        pdf.ln(2)
+
+        # Render input requirements table
+        render_model_input_table(pdf, model, link_manager)
+
+        # Add light horizontal separator between models (except for the last one)
+        if section_counter < len(models):
+            pdf.ln(6)
+            pdf.set_draw_color(200, 200, 200)  # Light gray color
+            # Shorter separator - about 60% of page width, centered
+            separator_width = (pdf.w - pdf.l_margin - pdf.r_margin) * 0.6
+            separator_start = (
+                pdf.l_margin
+                + (pdf.w - pdf.l_margin - pdf.r_margin - separator_width) / 2
+            )
+            pdf.line(
+                separator_start,
+                pdf.get_y(),
+                separator_start + separator_width,
+                pdf.get_y(),
+            )
+            pdf.ln(6)
+        else:
+            pdf.ln(8)
+
+        section_counter += 1
+
+
+def extract_model_metadata(model: RiskModel) -> dict:
+    """Extract metadata from a risk model.
+
+    Args:
+        model: Risk model instance
+
+    Returns:
+        Dictionary with description, reference, interpretation, and other metadata
+    """
+    # Get description from method
+    description = ""
+    if hasattr(model, "description") and callable(model.description):
+        description = model.description()
+
+    # Get interpretation from method
+    interpretation = ""
+    if hasattr(model, "interpretation") and callable(model.interpretation):
+        interpretation = model.interpretation()
+
+    # Get references from method
+    references = []
+    if hasattr(model, "references") and callable(model.references):
+        references = model.references()
+
+    # Format references as a single string
+    reference = ""
+    if references:
+        reference = "; ".join(references)
+
+    return {
+        "description": description,
+        "interpretation": interpretation,
+        "reference": reference,
+    }
+
+
+def get_field_info_from_user_input(field_path: str) -> dict:
+    """Extract description and examples from UserInput for a field path.
+
+    Args:
+        field_path: Full path like "demographics.age_years"
+
+    Returns:
+        Dict with 'description' and 'examples'
+    """
+    # Navigate the field path
+    parts = field_path.split(".")
+    current_model = UserInput
+
+    for part in parts:
+        if hasattr(current_model, "model_fields"):
+            field_info = current_model.model_fields.get(part)
+            if field_info:
+                # Get description from field metadata
+                description = field_info.description or ""
+                # Get examples from field metadata
+                examples = (
+                    field_info.json_schema_extra.get("examples", [])
+                    if field_info.json_schema_extra
+                    else []
+                )
+                examples_str = (
+                    ", ".join(str(example) for example in examples[:3])
+                    if examples
+                    else ""
+                )
+
+                # If this is the last part, return the info
+                if part == parts[-1]:
+                    return {"description": description, "examples": examples_str}
+
+                # Otherwise, navigate deeper
+                current_model = field_info.annotation
+
+    return {"description": "", "examples": ""}
+
+
+def has_different_constraints(model_field_type, _user_input_field_type) -> bool:
+    """Check if model field type has different constraints than UserInput.
+
+    Args:
+        model_field_type: Field type from model's REQUIRED_INPUTS
+        _user_input_field_type: Field type from UserInput (unused)
+
+    Returns:
+        True if constraints are different, False otherwise
+    """
+    # Check if model field type is Annotated[..., Field(...)]
+    # This indicates the model is redefining the format
+    if get_origin(model_field_type) is not None:
+        # It's an Annotated type, check if it contains Field metadata
+        args = get_args(model_field_type)
+        if args:
+            # Check if any of the metadata contains Field instances
+            for arg in args[1:]:  # Skip the first arg (the actual type)
+                if hasattr(arg, "__class__") and "Field" in str(arg.__class__):
+                    return True
+
+    return False
+
+
+def extract_constraint_text(field_type) -> str:
+    """Extract just the constraint text from a field type.
+
+    Args:
+        field_type: Field type from model's REQUIRED_INPUTS
+
+    Returns:
+        Constraint text like ">=0 to <=120" or "2 choices"
+    """
+    # Check if it's an Annotated type
+    if get_origin(field_type) is not None:
+        args = get_args(field_type)
+        if args:
+            # Look for FieldInfo metadata in the arguments
+            for arg in args[1:]:  # Skip the first arg (the actual type)
+                if hasattr(arg, "__class__") and "FieldInfo" in str(arg.__class__):
+                    # Extract constraints from FieldInfo metadata
+                    constraints = []
+                    if hasattr(arg, "metadata") and arg.metadata:
+                        for metadata_item in arg.metadata:
+                            if (
+                                hasattr(metadata_item, "ge")
+                                and metadata_item.ge is not None
+                            ):
+                                constraints.append(f">={metadata_item.ge}")
+                            if (
+                                hasattr(metadata_item, "le")
+                                and metadata_item.le is not None
+                            ):
+                                constraints.append(f"<={metadata_item.le}")
+                            if (
+                                hasattr(metadata_item, "gt")
+                                and metadata_item.gt is not None
+                            ):
+                                constraints.append(f">{metadata_item.gt}")
+                            if (
+                                hasattr(metadata_item, "lt")
+                                and metadata_item.lt is not None
+                            ):
+                                constraints.append(f"<{metadata_item.lt}")
+                            if (
+                                hasattr(metadata_item, "min_length")
+                                and metadata_item.min_length is not None
+                            ):
+                                constraints.append(
+                                    f"min_length={metadata_item.min_length}"
+                                )
+                            if (
+                                hasattr(metadata_item, "max_length")
+                                and metadata_item.max_length is not None
+                            ):
+                                constraints.append(
+                                    f"max_length={metadata_item.max_length}"
+                                )
+
+                    if constraints:
+                        return " to ".join(constraints)
+
+    # Check if it's an enum type
+    if hasattr(field_type, "__members__"):
+        return f"{len(field_type.__members__)} choices"
+
+    # Check if it's a Union type with enums
+    if get_origin(field_type) is Union:
+        args = get_args(field_type)
+        for arg in args:
+            if hasattr(arg, "__members__"):
+                return f"{len(arg.__members__)} choices"
+
+    return "any"
+
+
+def get_user_input_field_type(field_path: str):
+    """Get the field type from UserInput for a given field path.
+
+    Args:
+        field_path: Full path like "demographics.age_years"
+
+    Returns:
+        Field type from UserInput or None if not found
+    """
+    # Navigate the field path
+    parts = field_path.split(".")
+    current_model = UserInput
+
+    for part in parts:
+        if hasattr(current_model, "model_fields"):
+            field_info = current_model.model_fields.get(part)
+            if field_info:
+                # If this is the last part, return the field type
+                if part == parts[-1]:
+                    return field_info.annotation
+
+                # Otherwise, navigate deeper
+                current_model = field_info.annotation
+
+    return None
+
+
+def render_model_input_table(
+    pdf: FPDF, model: RiskModel, _link_manager: LinkManager
+) -> None:
+    """Render input requirements table with 2 columns and hyperlinks.
+
+    Columns:
+    - Field Name (with hyperlinks to Section 2)
+    - Format (model-specific or "same as user input")
+
+    Args:
+        pdf: Active PDF instance
+        model: Risk model instance
+        _link_manager: Link manager for creating hyperlinks (unused)
+    """
+    requirements = extract_model_requirements(model)
+
+    if not requirements:
+        pdf.set_font("Helvetica", "", 10)
+        pdf.cell(0, 6, "No input requirements defined for this model.", 0, 1)
+        pdf.ln(4)
+        return
+
+    # Table dimensions - only 2 columns now
+    table_width = pdf.w - 2 * pdf.l_margin
+    field_width = table_width * 0.60  # Increased since we only have 2 columns
+    format_width = table_width * 0.40
+    col_widths = [field_width, format_width]
+
+    # Table header function for reuse on page breaks
+    def render_table_header():
+        pdf.set_font("Helvetica", "B", 10)
+        pdf.set_fill_color(*TABLE_HEADER_BACKGROUND)
+        pdf.set_text_color(*TEXT_LIGHT)
+        pdf.cell(field_width, 8, "Field Name", 0, 0, "L", True)
+        pdf.cell(format_width, 8, "Format (when override)", 0, 1, "L", True)
+
+    # Add spacing before table header
+    pdf.ln(6)
+    render_table_header()
+
+    pdf.set_font("Helvetica", "", 9)
+    pdf.set_text_color(*TEXT_DARK)
+    line_height = 5.5
+
+    # Group fields by parent
+    grouped_fields = group_fields_by_requirements(requirements)
+
+    # Global index for alternating colors across all sub-fields
+    global_sub_idx = 0
+
+    for parent_name, sub_fields in grouped_fields:
+        # Check if we need a page break before the parent field
+        if pdf.get_y() + 20 > pdf.h - pdf.b_margin:
+            pdf.add_page()
+            # Add spacing after page header and before table header
+            pdf.ln(3)
+            render_table_header()
+            # Reset text color after page break to ensure readability
+            pdf.set_text_color(*TEXT_DARK)
+
+        # Render parent field name (bold) with fixed color
+        pdf.set_font("Helvetica", "B", 9)
+        pdf.set_text_color(*TEXT_DARK)
+        render_table_row(
+            pdf,
+            [parent_name, ""],
+            col_widths,
+            line_height,
+            (245, 245, 245),  # Light gray for parent rows
+        )
+
+        # Render sub-fields (normal weight, indented) with alternating colors
+        pdf.set_font("Helvetica", "", 9)
+        for field_path, field_type, _is_required in sub_fields:
+            # Format field name
+            sub_field_name = prettify_field_name(field_path.split(".")[-1])
+            indented_name = f"    {sub_field_name}"
+
+            # Determine format text based on whether model overrides UserInput
+            user_input_field_type = get_user_input_field_type(field_path)
+            if user_input_field_type and has_different_constraints(
+                field_type, user_input_field_type
+            ):
+                # Extract just the constraint part from the field type
+                format_text = extract_constraint_text(field_type)
+            else:
+                # Show "See User Input Doc" instead of "same as user input"
+                format_text = "See User Input Doc"
+
+            # Get position before rendering for hyperlink
+            x_position = pdf.get_x()
+            y_position = pdf.get_y()
+
+            # Alternate colors for sub-fields using global index
+            fill_color = (
+                ROW_BACKGROUND_LIGHT if global_sub_idx % 2 == 0 else ROW_BACKGROUND_ALT
+            )
+            render_table_row(
+                pdf,
+                [indented_name, format_text],
+                col_widths,
+                line_height,
+                fill_color,
+            )
+
+            # TODO: Add hyperlinks to field names linking to Section 2
+            # Temporarily disabled to focus on format column functionality
+
+            # Increment global index for next sub-field
+            global_sub_idx += 1
+
+    pdf.ln(4)
+
+
 def _format_type(annotation: Any) -> str:
     origin = get_origin(annotation)
     args = get_args(annotation)
@@ -158,8 +872,6 @@ def parse_annotated_type(field_type: type) -> tuple[type, dict[str, Any]]:
     Returns:
         (base_type, constraints_dict)
     """
-    from typing import get_args, get_origin
-
     origin = get_origin(field_type)
     args = get_args(field_type)
 
@@ -352,7 +1064,9 @@ def build_field_usage_map(models: list[RiskModel]) -> dict[str, list[tuple[str,
     return field_usage
 
 
-def extract_field_attributes(field_info, field_type) -> tuple[str, str, str, str]:
+def extract_field_attributes(
+    field_info, field_type
+) -> tuple[str, str, str, str, type | None]:
     """Extract field attributes directly from Field metadata.
 
     Args:
@@ -360,12 +1074,13 @@ def extract_field_attributes(field_info, field_type) -> tuple[str, str, str, str
         field_type: The field's type annotation
 
     Returns:
-        tuple of (description, examples, constraints, used_by) strings
+        tuple of (description, examples, constraints, used_by, enum_class) strings and enum class
     """
     description = "-"
     examples = "-"
     constraints = "-"
     used_by = "-"
+    enum_class = None
 
     # Extract description from Field
     if hasattr(field_info, "description") and field_info.description:
@@ -402,6 +1117,7 @@ def extract_field_attributes(field_info, field_type) -> tuple[str, str, str, str
     # Add enum count information if the field is an enum
     if hasattr(field_type, "__members__"):
         enum_count = len(field_type.__members__)
+        enum_class = field_type
         if constraints == "-":
             constraints = f"{enum_count} choices"
         else:
@@ -411,6 +1127,7 @@ def extract_field_attributes(field_info, field_type) -> tuple[str, str, str, str
         for arg in field_type.__args__:
             if hasattr(arg, "__members__"):
                 enum_count = len(arg.__members__)
+                enum_class = arg
                 if constraints == "-":
                     constraints = f"{enum_count} choices"
                 else:
@@ -427,7 +1144,7 @@ def extract_field_attributes(field_info, field_type) -> tuple[str, str, str, str
         # Check if it's a numeric type (int, float) without constraints
         elif field_type in (int, float) or (
             hasattr(field_type, "__args__")
-            and any(_type in field_type.__args__ for _type in (int, float))
+            and any(type_arg in field_type.__args__ for type_arg in (int, float))
         ):
             constraints = "any number"
         # Check if it's a Date type
@@ -440,7 +1157,7 @@ def extract_field_attributes(field_info, field_type) -> tuple[str, str, str, str
         ):
             constraints = "date"
 
-    return description, examples, constraints, used_by
+    return description, examples, constraints, used_by, enum_class
 
 
 def format_used_by(usage_list: list[tuple[str, bool]]) -> str:
@@ -471,11 +1188,10 @@ def render_user_input_hierarchy(
     Args:
         pdf: Active PDF instance
         models: List of risk model instances
-        link_manager: Link manager for creating hyperlinks between sections
+        link_manager: Link manager for creating hyperlinks
     """
-    from collections import defaultdict
-
-    from sentinel.user_input import UserInput
+    # Initialize link manager for hyperlinks
+    link_manager = LinkManager()
 
     # Build field usage mapping
     field_usage = build_field_usage_map(models)
@@ -497,6 +1213,9 @@ def render_user_input_hierarchy(
     # Render sections in order, ensuring each parent gets its leaf fields rendered
     section_counter = 1
 
+    # Global row counter for alternating colors across all tables
+    global_row_counter = [0]
+
     # Process items in the order they appear in the original structure
     processed_parents = set()
 
@@ -590,6 +1309,7 @@ def render_user_input_hierarchy(
                     link_manager,
                     nested_models_for_parent,
                     parent_info_for_current,
+                    global_row_counter,
                 )
                 section_counter += 1
 
@@ -603,6 +1323,7 @@ def render_model_fields_table(
     link_manager: LinkManager,
     nested_models_info: list[tuple[str, str, type[BaseModel]]] | None = None,
     parent_info: tuple[str, str, type[BaseModel]] | None = None,
+    global_row_counter: list[int] | None = None,
 ) -> None:
     """Render a table for a specific model's fields.
 
@@ -615,60 +1336,47 @@ def render_model_fields_table(
         link_manager: Link manager for hyperlinks
         nested_models_info: List of nested model info tuples
         parent_info: Parent model info tuple
+        global_row_counter: Mutable list containing the global row counter for alternating colors
     """
     if not model_info or not fields:
         return
 
     _model_path, model_name, model_class = model_info
 
-    # Add parent reference if this is a child model
-    if parent_info:
-        parent_path, parent_name, _ = parent_info
-        parent_link_id = link_manager.get_or_create_link_id(parent_path)
+    # Parent reference is now handled in the section title
 
-        # Add parent reference with hyperlink
-        pdf.set_font("Helvetica", "I", 9)
-        pdf.set_text_color(*THEME_MUTED)
-
-        # Get position for hyperlink
-        link_x = pdf.get_x()
-        link_y = pdf.get_y()
-
-        pdf.cell(0, 6, f"Parent: {parent_name} ^", 0, 1, "L")
-
-        # Add hyperlink to the parent reference
-        pdf.link(
-            link_x,
-            link_y,
-            pdf.get_string_width(f"Parent: {parent_name} ^"),
-            6,
-            parent_link_id,
-        )
-
-        pdf.ln(2)
+    # Add section heading with uniform rendering technique
+    pdf.set_font("Helvetica", "B", 12)
+    pdf.set_text_color(*THEME_PRIMARY)
 
-    # Add section heading with parent reference if applicable
     if parent_info:
         parent_path, parent_name, _ = parent_info
         parent_link_id = link_manager.get_or_create_link_id(parent_path)
 
-        # Create section heading with parent reference
-        section_title = f"{section_number}. {model_name} (from {parent_name})"
-        add_subheading(pdf, section_title)
+        # Render main title in primary color
+        main_title = f"{section_number}. {model_name} "
+        pdf.write(7, main_title)
 
-        # Add hyperlink to the parent reference part
-        # Get the position after the section number and model name
-        text_before_parent = f"{section_number}. {model_name} (from "
-        text_width_before_parent = pdf.get_string_width(text_before_parent)
-        parent_text_width = pdf.get_string_width(parent_name)
+        # Get current position for hyperlink
+        x_position = pdf.get_x()
+        y_position = pdf.get_y()
 
-        # Set link position (approximate, since we can't get exact position after add_subheading)
-        link_x = pdf.l_margin + text_width_before_parent
-        link_y = pdf.get_y() - 8  # Approximate position of the text line
+        # Render parenthetical part in dark gray
+        parenthetical = f"(from {parent_name})"
+        pdf.set_text_color(64, 64, 64)  # Dark gray color
+        pdf.write(7, parenthetical)
 
-        pdf.link(link_x, link_y, parent_text_width, 8, parent_link_id)
+        # Add hyperlink to the parent name within the parenthetical
+        text_width_before_parent = pdf.get_string_width(f"{main_title}(from ")
+        parent_text_width = pdf.get_string_width(parent_name)
+        pdf.link(x_position, y_position, parent_text_width, 7, parent_link_id)
     else:
-        add_subheading(pdf, f"{section_number}. {model_name}")
+        # Render single-color title
+        title = f"{section_number}. {model_name}"
+        pdf.write(7, title)
+
+    # Add proper line spacing after the title (uniform for all)
+    pdf.ln(8)
 
     # Create table for this model's fields (removed "Used By" column)
     table_width = pdf.w - 2 * pdf.l_margin
@@ -693,6 +1401,8 @@ def render_model_fields_table(
     if pdf.get_y() + 15 > pdf.h - pdf.b_margin:
         pdf.add_page()
 
+    # Add minimal spacing before table header to avoid conflicts with headings
+    pdf.ln(1)
     render_table_header()
 
     # Table rows
@@ -700,10 +1410,12 @@ def render_model_fields_table(
     pdf.set_text_color(*TEXT_DARK)
     line_height = 5.5
 
-    for idx, (field_path, field_name) in enumerate(fields):
+    for field_path, field_name in fields:
         # Check if we need a page break before this row
         if pdf.get_y() + 15 > pdf.h - pdf.b_margin:
             pdf.add_page()
+            # Add spacing after page header and before table header
+            pdf.ln(3)
             render_table_header()
             # Reset text color and font after page break to ensure readability
             pdf.set_text_color(*TEXT_DARK)
@@ -715,21 +1427,43 @@ def render_model_fields_table(
             continue
 
         # Extract field attributes
-        description, examples, constraints, _ = extract_field_attributes(
+        description, examples, constraints, _, enum_class = extract_field_attributes(
             field_info, field_info.annotation
         )
 
-        # Alternate row colors
-        fill_color = ROW_BACKGROUND_LIGHT if idx % 2 == 0 else ROW_BACKGROUND_ALT
+        # Alternate row colors using global counter
+        if global_row_counter is None:
+            # This should never happen if called correctly
+            current_row_index = 0
+        else:
+            current_row_index = global_row_counter[0]
+            # Increment global counter for next row
+            global_row_counter[0] += 1
 
-        render_table_row(
-            pdf,
-            [field_name, description, examples, constraints],
-            col_widths,
-            line_height,
-            fill_color,
+        fill_color = (
+            ROW_BACKGROUND_LIGHT if current_row_index % 2 == 0 else ROW_BACKGROUND_ALT
         )
 
+        # Check if constraints contain enum choices and make them clickable
+        if enum_class and "choices" in constraints:
+            render_table_row_with_enum_link(
+                pdf,
+                [field_name, description, examples, constraints],
+                col_widths,
+                line_height,
+                fill_color,
+                enum_class,
+                link_manager,
+            )
+        else:
+            render_table_row(
+                pdf,
+                [field_name, description, examples, constraints],
+                col_widths,
+                line_height,
+                fill_color,
+            )
+
     # Add nested model rows if any exist
     if nested_models_info:
         for nested_path, nested_name, _nested_model_class in nested_models_info:
@@ -740,7 +1474,7 @@ def render_model_fields_table(
                 continue
 
             # Extract field attributes
-            description, _, _, _ = extract_field_attributes(
+            description, _, _, _, _ = extract_field_attributes(
                 field_info, field_info.annotation
             )
 
@@ -754,17 +1488,29 @@ def render_model_fields_table(
             # Check if we need a page break before this row
             if pdf.get_y() + 15 > pdf.h - pdf.b_margin:
                 pdf.add_page()
+                # Add spacing after page header and before table header
+                pdf.ln(10)
                 render_table_header()
                 # Reset text color and font after page break
                 pdf.set_text_color(*TEXT_DARK)
                 pdf.set_font("Helvetica", "", 9)
 
-            # Use a lighter background for nested model rows
-            fill_color = (250, 250, 255)  # Very light blue
+            # Use a lighter background for nested model rows, but still alternate
+            if global_row_counter is None:
+                current_row_index = 0
+            else:
+                current_row_index = global_row_counter[0]
+                global_row_counter[0] += 1
+
+            # Use light blue for nested models, but alternate the shade
+            if current_row_index % 2 == 0:
+                fill_color = (250, 250, 255)  # Very light blue
+            else:
+                fill_color = (245, 245, 250)  # Slightly darker light blue
 
             # Create hyperlink for the nested model
-            row_x = pdf.get_x()
-            row_y = pdf.get_y()
+            x_position = pdf.get_x()
+            y_position = pdf.get_y()
 
             render_table_row(
                 pdf,
@@ -775,8 +1521,10 @@ def render_model_fields_table(
             )
 
             # Add the hyperlink to the examples cell
-            examples_x = row_x + field_width + desc_width
-            pdf.link(examples_x, row_y, examples_width, line_height, nested_link_id)
+            examples_x = x_position + field_width + desc_width
+            pdf.link(
+                examples_x, y_position, examples_width, line_height, nested_link_id
+            )
 
     pdf.ln(6)
 
@@ -924,7 +1672,7 @@ def add_subheading(pdf: FPDF, title: str) -> None:
     pdf.set_text_color(*THEME_PRIMARY)  # Changed to primary color
     pdf.set_font("Helvetica", "B", 12)  # Reduced from 13 to 12
     pdf.cell(0, 7, title, 0, 1)  # Removed .upper(), reduced height from 8 to 7
-    pdf.ln(2)
+    pdf.ln(8)  # Increased spacing significantly to prevent conflicts with table headers
 
 
 def draw_stat_card(pdf: FPDF, title: str, value: str, note: str, width: float) -> None:
@@ -937,17 +1685,17 @@ def draw_stat_card(pdf: FPDF, title: str, value: str, note: str, width: float) -
         note (str): Supporting text beneath the value.
         width (float): Width to allocate for the card (points).
     """
-    card_x = pdf.get_x()
-    card_y = pdf.get_y()
+    x_position = pdf.get_x()
+    y_position = pdf.get_y()
     height = 32
 
     pdf.set_fill_color(*CARD_BACKGROUND)
     pdf.set_draw_color(255, 255, 255)
-    pdf.rect(card_x, card_y, width, height, "F")
+    pdf.rect(x_position, y_position, width, height, "F")
 
     pdf.set_text_color(*THEME_MUTED)
     pdf.set_font("Helvetica", "B", 9)
-    pdf.set_xy(card_x + 6, card_y + 5)
+    pdf.set_xy(x_position + 6, y_position + 5)
     pdf.cell(width - 12, 4, title.upper(), 0, 2, "L")
 
     pdf.set_text_color(*THEME_PRIMARY)
@@ -958,7 +1706,7 @@ def draw_stat_card(pdf: FPDF, title: str, value: str, note: str, width: float) -
     pdf.set_font("Helvetica", "", 10)
     pdf.multi_cell(width - 12, 5, note, 0, "L")
 
-    pdf.set_xy(card_x + width + 8, card_y)
+    pdf.set_xy(x_position + width + 8, y_position)
 
 
 def render_summary_cards(pdf: FPDF, models: list[RiskModel]) -> None:
@@ -970,17 +1718,62 @@ def render_summary_cards(pdf: FPDF, models: list[RiskModel]) -> None:
     """
     stats: list[tuple[str, str, str]] = []
 
-    total_models = len(models)
-    total_cancers = len({ct for m in models for ct in cancer_types_for_model(m)})
+    # Calculate total cancer type coverage instances (sum of all bars in chart)
+    total_coverage_instances = sum(
+        len(cancer_types_for_model(model)) for model in models
+    )
+    total_cancers = len(
+        {
+            cancer_type
+            for model in models
+            for cancer_type in cancer_types_for_model(model)
+        }
+    )
     stats.append(
-        ("Risk Models", str(total_models), "Distinct risk calculators available")
+        (
+            "Risk Models",
+            str(total_coverage_instances),
+            "Total cancer type coverage instances",
+        )
     )
     stats.append(("Cancer Types", str(total_cancers), "Unique cancer sites covered"))
 
+    # New metrics
+    stats.append(
+        (
+            "Genes",
+            str(count_genomic_mutations()),
+            "Genetic mutations tracked",
+        )
+    )
+    stats.append(
+        (
+            "Lifestyle Factors",
+            str(count_lifestyle_factors()),
+            "Lifestyle fields available",
+        )
+    )
+    stats.append(
+        (
+            "Input Categories",
+            str(count_total_input_categories()),
+            "Total input fields across all categories",
+        )
+    )
+    stats.append(
+        (
+            "Discrete Choices",
+            str(count_total_discrete_choices()),
+            "Total number of categorical values available",
+        )
+    )
+
     available_width = pdf.w - 2 * pdf.l_margin
-    columns = 2
+    columns = 3  # Changed from 2 to accommodate 6 cards
     gutter = 8
-    card_width = (available_width - gutter) / columns
+    card_width = (
+        available_width - 2 * gutter
+    ) / columns  # Account for 2 gutters between 3 cards
     start_x = pdf.l_margin
     start_y = pdf.get_y()
     max_height_in_row = 0
@@ -988,9 +1781,9 @@ def render_summary_cards(pdf: FPDF, models: list[RiskModel]) -> None:
     for idx, (title, value, note) in enumerate(stats):
         col = idx % columns
         row = idx // columns
-        x = start_x + col * (card_width + gutter)
-        y = start_y + row * 38  # fixed row height
-        pdf.set_xy(x, y)
+        x_position = start_x + col * (card_width + gutter)
+        y_position = start_y + row * 38  # fixed row height
+        pdf.set_xy(x_position, y_position)
         draw_stat_card(pdf, title, value, note, card_width)
         max_height_in_row = max(max_height_in_row, 36)
 
@@ -1056,8 +1849,8 @@ def render_model_summary(pdf: FPDF, model: RiskModel, cancer_types: list[str]) -
     pdf.set_font("Helvetica", "", 8)
     pdf.set_text_color(*TEXT_DARK)
     references = model.references()
-    for i, ref in enumerate(references, 1):
-        pdf.multi_cell(0, 4, f"{i}. {ref}", 0, "L")
+    for ref_index, ref in enumerate(references, 1):
+        pdf.multi_cell(0, 4, f"{ref_index}. {ref}", 0, "L")
     pdf.ln(2)
 
 
@@ -1223,8 +2016,6 @@ def gather_spec_details(
 
         # Special handling for specific fields
         if spec and spec.path == "demographics.sex":
-            from sentinel.models import Sex
-
             sex_choices = [choice.value for choice in Sex]
             ranges.append(", ".join(sex_choices))
         elif spec and spec.path == "demographics.ethnicity":
@@ -1491,30 +2282,118 @@ def render_table_row(
         # Reset text color after page break to ensure readability
         pdf.set_text_color(*TEXT_DARK)
 
-    row_x = pdf.get_x()
-    row_y = pdf.get_y()
+    x_position = pdf.get_x()
+    y_position = pdf.get_y()
 
     # First, draw the background rectangle for the entire row
     pdf.set_fill_color(*fill_color)
-    pdf.rect(row_x, row_y, sum(widths), row_height, "F")
+    pdf.rect(x_position, y_position, sum(widths), row_height, "F")
 
     # Then draw the text in each cell with consistent height
-    current_x = row_x
+    current_x = x_position
     for width, wrapped_lines in zip(widths, wrapped_texts, strict=False):
-        pdf.set_xy(current_x, row_y)
+        pdf.set_xy(current_x, y_position)
         pdf.set_fill_color(*fill_color)
 
         # Draw each line of wrapped text
-        for i, line in enumerate(wrapped_lines):
-            pdf.set_xy(current_x, row_y + i * line_height)
+        for line_index, line in enumerate(wrapped_lines):
+            pdf.set_xy(current_x, y_position + line_index * line_height)
             pdf.cell(width, line_height, line, border=0, align="L", fill=False)
 
         current_x += width
 
     # Draw the border around the entire row
     pdf.set_draw_color(*TABLE_BORDER)
-    pdf.rect(row_x, row_y, sum(widths), row_height)
-    pdf.set_xy(row_x, row_y + row_height)
+    pdf.rect(x_position, y_position, sum(widths), row_height)
+    pdf.set_xy(x_position, y_position + row_height)
+
+
+def render_table_row_with_enum_link(
+    pdf: FPDF,
+    texts: list[str],
+    widths: list[float],
+    line_height: float,
+    fill_color: tuple[int, int, int],
+    enum_class: type,
+    link_manager: LinkManager,
+) -> None:
+    """Render a table row with clickable enum choices in the constraints column.
+
+    Args:
+        pdf: Active PDF instance
+        texts: Column texts (constraints should be in the last column)
+        widths: Column widths
+        line_height: Line height for text
+        fill_color: Background color for the row
+        enum_class: The enum class to link to
+        link_manager: Link manager for creating hyperlinks
+    """
+    # Calculate the maximum height needed for this row by wrapping text
+    max_lines = 0
+    wrapped_texts = []
+
+    for text, width in zip(texts, widths, strict=False):
+        if not text:
+            wrapped_lines = [""]
+        else:
+            # Wrap text to fit within the column width
+            wrapped_lines = pdf.multi_cell(
+                width, line_height, text, border=0, align="L", split_only=True
+            )
+        wrapped_texts.append(wrapped_lines)
+        max_lines = max(max_lines, len(wrapped_lines))
+
+    # Calculate the total row height
+    row_height = max_lines * line_height
+
+    # Check if we need a page break before rendering the row
+    if pdf.get_y() + row_height > pdf.h - pdf.b_margin:
+        pdf.add_page()
+        # Reset text color after page break to ensure readability
+        pdf.set_text_color(*TEXT_DARK)
+
+    x_position = pdf.get_x()
+    y_position = pdf.get_y()
+
+    # First, draw the background rectangle for the entire row
+    pdf.set_fill_color(*fill_color)
+    pdf.rect(x_position, y_position, sum(widths), row_height, "F")
+
+    # Then draw the text in each cell with consistent height
+    current_x = x_position
+    for column_index, (width, wrapped_lines) in enumerate(
+        zip(widths, wrapped_texts, strict=False)
+    ):
+        pdf.set_xy(current_x, y_position)
+        pdf.set_fill_color(*fill_color)
+
+        # Draw each line of wrapped text
+        for line_index, line in enumerate(wrapped_lines):
+            pdf.set_xy(current_x, y_position + line_index * line_height)
+
+            # If this is the constraints column (last column) and contains choices, make it clickable
+            if column_index == len(texts) - 1 and "choices" in line and enum_class:
+                # Store link information for later creation (after destinations are created)
+                enum_link_id = f"enum_{enum_class.__name__}"
+                link_manager.store_link_info(
+                    enum_link_id,
+                    pdf.get_x(),
+                    pdf.get_y(),
+                    pdf.get_string_width(line),
+                    line_height,
+                )
+
+                # Render the text
+                pdf.cell(width, line_height, line, border=0, align="L", fill=False)
+            else:
+                pdf.cell(width, line_height, line, border=0, align="L", fill=False)
+
+        current_x += width
+
+    # Draw the border around the entire row
+    pdf.set_draw_color(*TABLE_BORDER)
+    pdf.rect(x_position, y_position, sum(widths), row_height)
+    pdf.set_xy(x_position, y_position + row_height)
 
 
 def render_field_table(pdf: FPDF, model: RiskModel) -> None:
@@ -1552,6 +2431,8 @@ def render_field_table(pdf: FPDF, model: RiskModel) -> None:
         pdf.cell(unit_width, 8, "Unit", 0, 0, "L", True)
         pdf.cell(range_width, 8, "Choices / Range", 0, 1, "L", True)
 
+    # Add minimal spacing before table header
+    pdf.ln(1)
     render_table_header()
 
     pdf.set_font("Helvetica", "", 9)
@@ -1564,10 +2445,15 @@ def render_field_table(pdf: FPDF, model: RiskModel) -> None:
     # Define a fixed color for parent field rows (slightly darker than regular rows)
     PARENT_ROW_COLOR = (245, 245, 245)  # Light gray for parent rows
 
+    # Global index for alternating colors across all sub-fields
+    global_sub_idx = 0
+
     for parent_name, sub_fields in grouped_fields:
         # Check if we need a page break before the parent field
         if pdf.get_y() + 20 > pdf.h - pdf.b_margin:
             pdf.add_page()
+            # Add spacing after page header and before table header
+            pdf.ln(3)
             render_table_header()
             # Reset text color after page break to ensure readability
             pdf.set_text_color(*TEXT_DARK)
@@ -1585,7 +2471,7 @@ def render_field_table(pdf: FPDF, model: RiskModel) -> None:
 
         # Render sub-fields (normal weight, indented) with alternating colors
         pdf.set_font("Helvetica", "", 9)
-        for sub_idx, (field_path, field_type, is_required) in enumerate(sub_fields):
+        for field_path, field_type, is_required in sub_fields:
             # Get the spec from UserInput introspection
             spec = USER_INPUT_FIELD_SPECS.get(field_path)
 
@@ -1600,9 +2486,9 @@ def render_field_table(pdf: FPDF, model: RiskModel) -> None:
             # Indent the sub-field name
             sub_field_name = prettify_field_name(field_path.split(".")[-1])
             indented_name = f"    {sub_field_name}"
-            # Alternate colors for sub-fields only
+            # Alternate colors for sub-fields using global index
             fill_color = (
-                ROW_BACKGROUND_LIGHT if sub_idx % 2 == 0 else ROW_BACKGROUND_ALT
+                ROW_BACKGROUND_LIGHT if global_sub_idx % 2 == 0 else ROW_BACKGROUND_ALT
             )
             render_table_row(
                 pdf,
@@ -1611,6 +2497,8 @@ def render_field_table(pdf: FPDF, model: RiskModel) -> None:
                 line_height,
                 fill_color,
             )
+            # Increment global index for next sub-field
+            global_sub_idx += 1
 
     pdf.ln(4)
 
@@ -1644,6 +2532,9 @@ class PDF(FPDF):
         self.set_draw_color(*THEME_MUTED)
         self.line(self.l_margin, 16, self.w - self.r_margin, 16)
 
+        # Add spacing after header to prevent overlap with content
+        self.set_y(25)
+
     def footer(self):
         """Render the footer with page numbering."""
         self.set_y(-15)
@@ -1659,10 +2550,10 @@ def discover_risk_models() -> list[RiskModel]:
         list[RiskModel]: Instantiated models ordered by name.
     """
     models = []
-    for f in MODELS_DIR.glob("*.py"):
-        if f.stem.startswith("_"):
+    for file_path in MODELS_DIR.glob("*.py"):
+        if file_path.stem.startswith("_"):
             continue
-        module_name = f"sentinel.risk_models.{f.stem}"
+        module_name = f"sentinel.risk_models.{file_path.stem}"
         module = importlib.import_module(module_name)
         for _, obj in inspect.getmembers(module, inspect.isclass):
             if issubclass(obj, RiskModel) and obj is not RiskModel:
@@ -1687,44 +2578,46 @@ def generate_coverage_chart(models: list[RiskModel]) -> None:
     cancer_types = list(cancer_types)
     counts = list(counts)
 
-    plt.figure(figsize=(10, 8))
-    plt.barh(cancer_types, counts, color=[c / 255 for c in THEME_PRIMARY])
-    plt.xlabel("Number of Models")
-    plt.ylabel("Cancer Type")
-    plt.title("Cancer Type Coverage by Risk Models")
-    plt.gca().invert_yaxis()
+    plt.figure(figsize=(15, 6))  # Keep width, double height (15:6 ratio)
+    plt.bar(
+        cancer_types, counts, color=[color_value / 255 for color_value in THEME_PRIMARY]
+    )
+    plt.xlabel("Cancer Type", fontsize=16, fontweight="bold")
+    plt.ylabel("Number of Models", fontsize=16, fontweight="bold")
+    plt.title("Cancer Type Coverage by Risk Models", fontsize=18, fontweight="bold")
+    plt.xticks(
+        rotation=45, ha="right", fontsize=14
+    )  # Rotate x-axis labels for better readability
+    plt.yticks(fontsize=14)  # Set y-axis tick font size
     plt.tight_layout()
     plt.savefig(CHART_FILE)
     plt.close()
 
 
-def render_summary_page(
-    pdf: FPDF, _models: list[RiskModel], link_manager: "LinkManager"
-) -> None:
+def render_summary_page(pdf: FPDF, link_manager: "LinkManager") -> None:
     """Render a summary page with hyperlinks to all sections.
 
     Args:
         pdf: Active PDF document.
-        _models: List of risk models to document (unused but kept for API consistency).
         link_manager: Link manager for creating hyperlinks.
     """
     # Title
     pdf.set_text_color(*TEXT_DARK)
     pdf.set_font("Helvetica", "B", 24)
     pdf.cell(0, 15, "Sentinel Risk Model Documentation", 0, 1, "C")
-    pdf.ln(10)
+    pdf.ln(6)
 
     # Subtitle
     pdf.set_text_color(*THEME_MUTED)
     pdf.set_font("Helvetica", "", 12)
     pdf.cell(0, 8, "Comprehensive Guide to Cancer Risk Assessment Models", 0, 1, "C")
-    pdf.ln(20)
+    pdf.ln(8)
 
     # Table of Contents
     pdf.set_text_color(*TEXT_DARK)
     pdf.set_font("Helvetica", "B", 16)
-    pdf.cell(0, 10, "Table of Contents", 0, 1)
-    pdf.ln(5)
+    pdf.cell(0, 8, "Table of Contents", 0, 1)
+    pdf.ln(4)
 
     # Section 1: Overview
     pdf.set_font("Helvetica", "B", 12)
@@ -1732,15 +2625,17 @@ def render_summary_page(
 
     # Create hyperlink for Overview section
     overview_link_id = link_manager.get_or_create_link_id("overview")
-    link_x = pdf.get_x()
-    link_y = pdf.get_y()
-    pdf.cell(0, 8, "1. Overview", 0, 1)
-    pdf.link(link_x, link_y, pdf.get_string_width("1. Overview"), 8, overview_link_id)
+    x_position = pdf.get_x()
+    y_position = pdf.get_y()
+    pdf.cell(0, 7, "1. Overview", 0, 1)
+    pdf.link(
+        x_position, y_position, pdf.get_string_width("1. Overview"), 7, overview_link_id
+    )
 
     pdf.set_font("Helvetica", "", 10)
     pdf.set_text_color(*TEXT_DARK)
-    pdf.cell(0, 6, "   Key metrics, cancer coverage, and model statistics", 0, 1)
-    pdf.ln(3)
+    pdf.cell(0, 5, "   Key metrics, cancer coverage, and model statistics", 0, 1)
+    pdf.ln(2)
 
     # Section 2: User Input Structure
     pdf.set_font("Helvetica", "B", 12)
@@ -1748,29 +2643,27 @@ def render_summary_page(
 
     # Create hyperlink for User Input Structure section
     user_input_link_id = link_manager.get_or_create_link_id("user_input_structure")
-    link_x = pdf.get_x()
-    link_y = pdf.get_y()
-    pdf.cell(0, 8, "2. User Input Structure & Requirements", 0, 1)
+    x_position = pdf.get_x()
+    y_position = pdf.get_y()
+    pdf.cell(0, 7, "2. User Input Structure & Requirements", 0, 1)
     pdf.link(
-        link_x,
-        link_y,
+        x_position,
+        y_position,
         pdf.get_string_width("2. User Input Structure & Requirements"),
-        8,
+        7,
         user_input_link_id,
     )
 
     pdf.set_font("Helvetica", "", 10)
     pdf.set_text_color(*TEXT_DARK)
-    pdf.cell(0, 6, "   Complete field definitions, examples, and constraints", 0, 1)
-    pdf.ln(3)
+    pdf.cell(0, 5, "   Complete field definitions, examples, and constraints", 0, 1)
+    pdf.ln(2)
 
     # Sub-sections for User Input (simplified - no hyperlinks for now)
     pdf.set_font("Helvetica", "", 10)
     pdf.set_text_color(*THEME_MUTED)
 
     # Get all sections that will be rendered
-    from sentinel.user_input import UserInput
-
     structure = traverse_user_input_structure(UserInput)
     parent_to_items = defaultdict(list)
 
@@ -1781,7 +2674,7 @@ def render_summary_page(
             parent_path = ""
         parent_to_items[parent_path].append((field_path, field_name, model_class))
 
-    section_counter = 3
+    section_counter = 1
     processed_parents = set()
 
     for field_path, _field_name, _model_class in structure:
@@ -1807,11 +2700,84 @@ def render_summary_page(
             for field_path_check, field_name_check, model_class_check in structure:
                 if field_path_check == parent_path and model_class_check is not None:
                     model_name = field_name_check.replace("_", " ").title()
-                    pdf.cell(0, 5, f"   {section_counter}. {model_name}", 0, 1)
+                    pdf.cell(0, 4, f"   {section_counter}. {model_name}", 0, 1)
                     section_counter += 1
                     break
 
-    pdf.ln(10)
+    # Section 3: User Input Tabular Choices
+    pdf.set_font("Helvetica", "B", 12)
+    pdf.set_text_color(*THEME_PRIMARY)
+
+    # Create hyperlink for User Input Tabular Choices section
+    enum_choices_link_id = link_manager.get_or_create_link_id("user_input_enums")
+    x_position = pdf.get_x()
+    y_position = pdf.get_y()
+    pdf.cell(0, 7, "3. User Input Tabular Choices", 0, 1)
+    pdf.link(
+        x_position,
+        y_position,
+        pdf.get_string_width("3. User Input Tabular Choices"),
+        7,
+        enum_choices_link_id,
+    )
+
+    pdf.set_font("Helvetica", "", 10)
+    pdf.set_text_color(*TEXT_DARK)
+    pdf.cell(0, 5, "   Enum values and descriptions for all choice fields", 0, 1)
+    pdf.ln(2)
+
+    # Add subsections for Section 3
+    pdf.set_font("Helvetica", "", 10)
+    pdf.set_text_color(*THEME_MUTED)
+
+    # Get enum information to create subsections
+    enums_by_parent = collect_all_enums()
+    section_counter = 1
+
+    for parent_name, enums in enums_by_parent.items():
+        if not enums:
+            continue
+
+        # Format parent name
+        formatted_parent_name = parent_name.replace("_", " ").title()
+
+        # Create hyperlink for this subsection
+        subsection_link_id = f"enum_{parent_name}"
+        x_position = pdf.get_x()
+        y_position = pdf.get_y()
+        pdf.cell(0, 4, f"   {section_counter}. {formatted_parent_name}", 0, 1)
+        pdf.link(
+            x_position,
+            y_position,
+            pdf.get_string_width(f"   {section_counter}. {formatted_parent_name}"),
+            5,
+            subsection_link_id,
+        )
+        section_counter += 1
+
+    # Section 4: Risk Score Models
+    pdf.set_font("Helvetica", "B", 12)
+    pdf.set_text_color(*THEME_PRIMARY)
+
+    # Create hyperlink for Risk Score Models section
+    risk_models_link_id = link_manager.get_or_create_link_id("risk_models")
+    x_position = pdf.get_x()
+    y_position = pdf.get_y()
+    pdf.cell(0, 7, "4. Risk Score Models", 0, 1)
+    pdf.link(
+        x_position,
+        y_position,
+        pdf.get_string_width("4. Risk Score Models"),
+        7,
+        risk_models_link_id,
+    )
+
+    pdf.set_font("Helvetica", "", 10)
+    pdf.set_text_color(*TEXT_DARK)
+    pdf.cell(0, 5, "   Detailed documentation for each risk assessment model", 0, 1)
+    pdf.ln(2)
+
+    pdf.ln(5)
 
     # Footer note
     pdf.set_font("Helvetica", "I", 9)
@@ -1850,12 +2816,14 @@ def create_pdf(models: list[RiskModel], output_path: Path) -> None:
     link_manager = LinkManager()
 
     # --- Summary Section ---
-    render_summary_page(pdf, models, link_manager)
+    render_summary_page(pdf, link_manager)
 
     # --- Overview Section ---
     pdf.add_page()
     # Create link destination for Overview section
     link_manager.create_link_destination(pdf, "overview")
+    # Add spacing after page header
+    pdf.ln(3)
     add_section_heading(pdf, "1", "Overview")
     add_subheading(pdf, "Key Metrics")
     render_summary_cards(pdf, models)
@@ -1869,9 +2837,35 @@ def create_pdf(models: list[RiskModel], output_path: Path) -> None:
     pdf.add_page()
     # Create link destination for User Input Structure section
     link_manager.create_link_destination(pdf, "user_input_structure")
+    # Add spacing after page header
+    pdf.ln(3)
     add_section_heading(pdf, "2", "User Input Structure & Requirements")
     render_user_input_hierarchy(pdf, models, link_manager)
 
+    # --- User Input Tabular Choices Section ---
+    pdf.add_page()
+    # Create link destination for User Input Tabular Choices section
+    link_manager.create_link_destination(pdf, "user_input_enums")
+    # Add spacing after page header
+    pdf.ln(3)
+    add_section_heading(pdf, "3", "User Input Tabular Choices")
+
+    # Collect all enums and render the section
+    enums_by_parent = collect_all_enums()
+    render_enum_choices_section(pdf, enums_by_parent, link_manager)
+
+    # --- Risk Models Section ---
+    pdf.add_page()
+    # Create link destination for Risk Models section
+    link_manager.create_link_destination(pdf, "risk_models")
+    # Add spacing after page header
+    pdf.ln(3)
+    add_section_heading(pdf, "4", "Risk Score Models")
+    render_risk_models_section(pdf, models, link_manager)
+
+    # Create all pending links after destinations are created
+    link_manager.create_pending_links(pdf)
+
     pdf.output(output_path)
     print(f"Documentation successfully generated at: {output_path}")
 

tests/test_generate_documentation.py

@@ -287,11 +287,12 @@ class TestUserInputStructureExtraction:
         field_info = UserInput.model_fields["demographics"]
         field_type = field_info.annotation
 
-        description, examples, constraints, used_by = extract_field_attributes(
-            field_info, field_type
+        description, examples, constraints, used_by, enum_class = (
+            extract_field_attributes(field_info, field_type)
         )
 
         assert isinstance(description, str)
         assert isinstance(examples, str)
         assert isinstance(constraints, str)
         assert isinstance(used_by, str)
+        assert enum_class is None or isinstance(enum_class, type)