Sync from GitHub (main)

.codespell-ignore.txt

@@ -0,0 +1,4 @@
+Demog
+ONS
+Claus
+claus

.devcontainer/devcontainer.json

@@ -0,0 +1,23 @@
+// """Dev container Local development"""
+{
+    "name": "sentinel",
+    // "dockerFile": "Dockerfile",
+    "image": "python:3.12-slim",
+    // "initializeCommand": ". ./.env",
+    "postCreateCommand": "bash ./.devcontainer/setup.sh",
+    "build": {
+      "args": {},
+      "options": [
+        "--platform=linux/amd64"
+      ]
+    },
+      "runArgs": [
+          "--platform=linux/amd64",
+          "--add-host=host.docker.internal:host-gateway"
+      ],
+      "remoteUser": "root",
+      "containerUser": "root",
+      "mounts": [
+          "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
+      ]
+  }

.devcontainer/setup.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+set -ex
+
+# Update package lists
+apt-get update
+
+# ----- Linux Packages ----- #
+
+apt-get install -y curl wget
+
+# ----- Locales ----- #
+# Install locales and configure
+apt-get install -y locales
+echo "en_US.UTF-8 UTF-8" > /etc/locale.gen
+locale-gen en_US.UTF-8
+update-locale LANG=en_US.UTF-8
+
+# ----------------- Python -----------------
+
+# Update package lists
+apt-get update
+
+# Install necessary packages
+apt-get install -y ssh locales git
+
+# Configure locale
+echo "en_US.UTF-8 UTF-8" > /etc/locale.gen
+locale-gen
+
+# Git configuration
+git config --global --add safe.directory /workspaces/sentinel
+
+# Install Python package in editable mode
+pip install --editable .
+
+# Stash any changes before rebuilding the container
+git stash push -m "Stashed changes before (re)building the container"
+git stash apply 0
+
+
+# ----------------- Docker -----------------
+
+apt-get update && apt-get install -y docker.io && apt-get clean -y
+
+# ----------------- Google Cloud SDK -----------------
+
+# Install prerequisites for Google Cloud SDK
+apt-get install -y apt-transport-https ca-certificates gnupg curl
+
+# Import the Google Cloud public key
+curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
+
+# Add the Google Cloud SDK repository
+echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee /etc/apt/sources.list.d/google-cloud-sdk.list
+
+# Update package lists again with new repository
+apt-get update
+
+# Install Google Cloud CLI
+apt-get install -y google-cloud-cli
+
+# Authenticate Docker with Google Cloud
+gcloud auth configure-docker -q gcr.io
+
+# gcloud auth login --project <sentinel> --no-launch-browser

.dockerignore

@@ -0,0 +1,57 @@
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Git
+.git/
+.gitignore
+.github/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+*.cover
+
+# Documentation
+*.md
+!README.md
+docs/
+
+# Environment files
+.env
+.env.*
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+tmp/
+temp/
+*.log

.env.example

@@ -0,0 +1,6 @@
+# Rename this file to .env and fill in your API keys
+GOOGLE_API_KEY="your_google_api_key_here"
+OPENAI_API_KEY="your_openai_api_key_here"
+
+# Local Ollama server
+OLLAMA_BASE_URL=http://localhost:11434

.github/ISSUE_TEMPLATE/build.yaml

@@ -0,0 +1,19 @@
+name: "Build request"
+description: Changes to the build system or dependencies, such as build scripts or configuration updates.
+title: "build(): "
+labels: [build]
+projects: [instadeepai/141]
+body:
+  - type: textarea
+    id: unclear_section
+    attributes:
+      label: What dependency/dockerfile/image should be changed?
+      description: Inform what should be changed.
+      placeholder: Inform where and what should be changed.
+
+  - type: textarea
+    id: solution_description
+    attributes:
+      label: Describe the change you'd like
+      description: Inform the change requested.
+      placeholder: Bump package X from version 1.0.0 to version 1.0.1

.github/ISSUE_TEMPLATE/chore.yaml

@@ -0,0 +1,12 @@
+name: "Chore request"
+description: Routine tasks or administrative updates not directly related to code functionality.
+title: "chore(): "
+labels: [chore]
+projects: [instadeepai/141]
+body:
+  - type: textarea
+    id: solution_description
+    attributes:
+      label: Describe the solution you'd like
+      description: The solution that should be implemented.
+      placeholder: E.g. Add secrets to GitHub Secret.

.github/ISSUE_TEMPLATE/ci.yaml

@@ -0,0 +1,11 @@
+name: "CI request"
+description: Modifications related to continuous integration and deployment processes.
+title: "ci: "
+labels: [ci]
+projects: [instadeepai/141]
+body:
+  - type: textarea
+    id: unclear_section
+    attributes:
+      label: What CI modification is needed?
+      description: Provide a clear and concise description of what should be done and where.

.github/ISSUE_TEMPLATE/docs.yaml

@@ -0,0 +1,12 @@
+name: "Documentation request"
+description: Request documentation for functions, scripts, modules, etc.
+title: "docs(): "
+labels: [docs]
+projects: [instadeepai/141]
+body:
+  - type: textarea
+    id: unclear_section
+    attributes:
+      label: What is not clear for you?
+      description: Provide a clear and concise description of what is unclear. For example, mention specific parts of the code or documentation that are difficult to understand.
+      placeholder: Describe the problem you encountered.

.github/ISSUE_TEMPLATE/feat.yaml

@@ -0,0 +1,19 @@
+name: "Feature request"
+description: Request a new feature or enhancement to existing functionality.
+title: "feat(): "
+labels: [feat]
+projects: [instadeepai/141]
+body:
+  - type: textarea
+    id: tasks
+    attributes:
+      label: What are the tasks?
+      description: Provide a clear and concise description of the tasks to be completed. Include details about priority, urgency, and due dates.
+      placeholder: List and describe the tasks.
+
+  - type: textarea
+    id: deliverables
+    attributes:
+      label: What are the expected deliverables?
+      description: Provide a detailed description of the expected deliverables, including minimal deliverables, nice-to-have features, and follow-up actions.
+      placeholder: Describe the deliverables and outcomes.

.github/ISSUE_TEMPLATE/fix.yaml

@@ -0,0 +1,24 @@
+name: "Fix request"
+description: Bug fixes or patches to resolve issues in the codebase.
+title: "fix(): "
+labels: [bug, fix]
+projects: [instadeepai/141]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of what the bug is. Include the current behavior versus the expected behavior. Add any other context about the problem here as well.
+      placeholder: What brings you to realize this bug?
+
+  - type: textarea
+    id: to_reproduce
+    attributes:
+      label: To reproduce
+      description: Code snippet to reproduce the bug if possible.
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What solution do you propose to fix the bug? What are the alternatives?

.github/ISSUE_TEMPLATE/perf.yaml

@@ -0,0 +1,12 @@
+name: "Performance refactor request"
+description: Performance improvements, such as optimizations to make the code faster or more efficient.
+title: "perf(): "
+labels: [perf]
+projects: [instadeepai/141]
+body:
+  - type: textarea
+    id: challenges
+    attributes:
+      label: What should have performance improvement?
+      description: Performance improvements, such as optimizations to make the code faster or more efficient.
+      placeholder: A clear and concise description of what should have a performance improvement.

.github/ISSUE_TEMPLATE/refactor.yaml

@@ -0,0 +1,19 @@
+name: "Code refactor request"
+description: Request for code refactoring to improve code quality and structure.
+title: "refactor(): "
+labels: [refactor]
+projects: [instadeepai/141]
+body:
+  - type: textarea
+    id: challenges
+    attributes:
+      label: What should be changed?
+      description: A clear and concise description of what and where should be changed.
+      placeholder: What issues have you identified in the current code?
+
+  - type: textarea
+    id: suggestions
+    attributes:
+      label: What are the suggestions?
+      description: A description of the proposed code or file structure. Include advantages and disadvantages. Note refactoring should not break existing functionality.
+      placeholder: What changes do you propose?

.github/ISSUE_TEMPLATE/style.yaml

@@ -0,0 +1,12 @@
+name: " Style refactor request"
+description: Changes to code formatting and style, without affecting functionality.
+title: "style(): "
+labels: [style]
+projects: [instadeepai/141]
+body:
+  - type: textarea
+    id: challenges
+    attributes:
+      label: What are the style that needs to be changed?
+      description: A clear and concise description of what needs to be changed.
+      placeholder: What issues have you identified in the current code?

.github/ISSUE_TEMPLATE/test.yaml

@@ -0,0 +1,12 @@
+name: "Tests"
+description: Updates related to testing, including adding or modifying test cases.
+title: "test(): "
+labels: [test]
+projects: [instadeepai/141]
+body:
+  - type: textarea
+    id: challenges
+    attributes:
+      label: What needs to be tested?
+      description: A clear and concise description of what needs to be tested and where.
+      placeholder: What needs to be tested in the current code?

.github/actions/tools/huggingface/action.yaml

@@ -0,0 +1,68 @@
+name: 'HuggingFace Space'
+description: 'Push to a HuggingFace Space repository'
+inputs:
+  token:
+    description: 'Hugging Face API token'
+    required: true
+  space:
+    description: 'Hugging Face Space name'
+    required: true
+  branch:
+    description: 'Branch to push to'
+    required: true
+  runtime-secrets:
+    description: 'Runtime secrets to sync to HuggingFace Space'
+    required: false
+runs:
+  using: 'composite'
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v5
+      with:
+        fetch-depth: 0
+        lfs: true
+
+    - name: Check large files
+      uses: ActionsDesk/lfs-warning@v2.0
+      with:
+        filesizelimit: 10485760  # this is 10MB so we can sync to HF Spaces
+
+    - name: Install HuggingFace CLI
+      shell: bash
+      run: pip install -U "huggingface_hub[cli]"
+
+    - name: Push to HuggingFace Space
+      shell: bash
+      env:
+        HF_TOKEN: ${{ inputs.token }}
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        hf auth login --token $HF_TOKEN
+        hf upload ${{ inputs.space }} . . --repo-type=space --revision=${{ inputs.branch }} --commit-message="Sync from GitHub (${{ inputs.branch }})"
+
+    - name: Configure Space Secrets
+      if: ${{ inputs.runtime-secrets != '' }}
+      shell: bash
+      env:
+        HF_SPACE: ${{ inputs.space }}
+        HF_TOKEN: ${{ inputs.token }}
+        RUNTIME_SECRETS: ${{ inputs.runtime-secrets }}
+      run: |
+        python3 ${GITHUB_ACTION_PATH}/secrets.py
+
+    - name: Create deployment summary
+      shell: bash
+      run: |
+        if [ "${{ inputs.branch }}" = "main" ]; then
+          SPACE_URL="https://huggingface.co/spaces/${{ inputs.space }}"
+          BRANCH_TEXT="main"
+        else
+          SPACE_URL="https://huggingface.co/spaces/${{ inputs.space }}/tree/${{ inputs.branch }}"
+          BRANCH_TEXT="${{ inputs.branch }}"
+        fi
+
+        echo "## 🚀 HuggingFace Space Deployment" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "✅ Successfully deployed to **${BRANCH_TEXT}** branch" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "🔗 **App URL:** ${SPACE_URL}" >> $GITHUB_STEP_SUMMARY

.github/actions/tools/huggingface/secrets.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+Sync secrets from GitHub Actions to HuggingFace Space.
+
+Reads configuration from environment variables:
+    HF_SPACE: HuggingFace Space repository ID (e.g., "InstaDeepAI/sentinel")
+    HF_TOKEN: HuggingFace API token
+    RUNTIME_SECRETS: Multi-line string with secrets in format "KEY: value"
+"""
+
+import logging
+import os
+
+from huggingface_hub import HfApi
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+
+
+def extract(payload):
+    """Parse secrets from YAML-like format.
+
+    Args:
+        payload: Multi-line string with secrets in format "KEY: value"
+
+    Returns:
+        Dictionary mapping secret keys to values
+    """
+    secrets = {}
+    if not payload:
+        return secrets
+
+    for line in payload.strip().split("\n"):
+        line = line.strip()
+        if ":" in line and line:
+            key, value = line.split(":", 1)
+            key = key.strip()
+            value = value.strip()
+
+            if key and value:  # Only add if both key and value are non-empty
+                secrets[key] = value
+
+    return secrets
+
+
+def upload(repository, token, payload):
+    """Sync secrets to HuggingFace Space.
+
+    Args:
+        repository: HuggingFace Space repository ID
+        token: HuggingFace API token
+        payload: Multi-line string with secrets in format "KEY: value"
+
+    Raises:
+        RuntimeError: If any secret fails to sync
+    """
+    client = HfApi(token=token)
+    secrets = extract(payload)
+
+    if not secrets:
+        logging.info("No runtime secrets to configure")
+        return
+
+    count = 0
+    for key, value in secrets.items():
+        try:
+            client.add_space_secret(repo_id=repository, key=key, value=value)
+            logging.info("Added %s secret to HuggingFace Space", key)
+            count += 1
+        except Exception as e:
+            logging.error("Failed to add %s: %s", key, e)
+            raise RuntimeError(f"Failed to sync secret {key}") from e
+
+    logging.info("Successfully configured %d secret(s)", count)
+
+
+if __name__ == "__main__":
+    # Read configuration from environment variables
+    repository = os.getenv("HF_SPACE")
+    token = os.getenv("HF_TOKEN")
+    payload = os.getenv("RUNTIME_SECRETS", "")
+
+    # Validate required environment variables
+    if not repository:
+        raise ValueError("HF_SPACE environment variable is required")
+
+    if not token:
+        raise ValueError("HF_TOKEN environment variable is required")
+
+    # Run the sync - any exceptions will naturally exit with code 1
+    upload(repository, token, payload)

.github/actions/tools/pr-title-generator/action.yaml

@@ -0,0 +1,52 @@
+name: 'PR Title Generator'
+description: 'Updates PR title and body based on issue number from branch name'
+
+inputs:
+  github-token:
+    description: 'GitHub token for API access'
+    required: true
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Git config
+      shell: bash
+      run: |
+        git config --global --add safe.directory '*'
+
+    - name: Install GitHub CLI
+      shell: bash
+      run: |
+        (type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
+          && sudo mkdir -p -m 755 /etc/apt/keyrings \
+                && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+                && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
+          && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+          && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+          && sudo apt update \
+          && sudo apt install gh -y
+
+    - name: Update PR Title and Body
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ inputs.github-token }}
+      run: |
+        branch_name="${{ github.event.pull_request.head.ref }}"
+        issue_number=$(echo "$branch_name" | grep -o '^[0-9]\+')
+
+        if [ -z "$issue_number" ]; then
+          echo "Error: Branch name does not start with an issue number"
+          exit 1
+        fi
+
+        # Update PR title
+        issue_title=$(gh api "/repos/instadeepai/sentinel/issues/$issue_number" --jq '.title')
+        gh pr edit ${{ github.event.pull_request.number }} --title "$issue_title"
+
+        # Update PR body
+        current_body=$(gh pr view ${{ github.event.pull_request.number }} --json body --jq '.body')
+        updated_body=$(echo "$current_body" | sed "s/(issue)/#$issue_number/g")
+        gh pr edit ${{ github.event.pull_request.number }} --body "$updated_body"

.github/actions/tools/pre-commit/action.yaml

@@ -0,0 +1,74 @@
+name: 'Pre-commit'
+description: 'Pre-commit'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      shell: bash
+      run: |
+        uv sync --frozen --all-extras
+
+    - name: Install pre-commit hooks
+      shell: bash
+      run: |
+        source .venv/bin/activate
+        uv run pre-commit install-hooks
+
+    - name: Run Pre-commit
+      id: precommit
+      shell: bash
+      run: |
+        echo "##   Pre-commit Results" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+
+        if uv run pre-commit run --all-files 2>&1 | tee output.txt; then
+          echo "✅ **All pre-commit hooks passed!**" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Hook | Status |" >> $GITHUB_STEP_SUMMARY
+          echo "|------|--------|" >> $GITHUB_STEP_SUMMARY
+          grep -E "\.\.\.*Passed|\.\.\.*Skipped" output.txt | while read line; do
+            hook=$(echo "$line" | sed 's/\.\.\..*Passed.*//' | sed 's/\.\.\..*Skipped.*//' | sed 's/^[[:space:]]*//' | sed 's/[[:space:]]*$//')
+            if echo "$line" | grep -q "Passed"; then
+              echo "| $hook | ✅ Passed |" >> $GITHUB_STEP_SUMMARY
+            else
+              echo "| $hook | ⏭️ Skipped |" >> $GITHUB_STEP_SUMMARY
+            fi
+          done
+        else
+          echo "❌ **Some pre-commit hooks failed**" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Hook | Status |" >> $GITHUB_STEP_SUMMARY
+          echo "|------|--------|" >> $GITHUB_STEP_SUMMARY
+          grep -E "\.\.\.*Passed|\.\.\.*Failed|\.\.\.*Skipped" output.txt | while read line; do
+            hook=$(echo "$line" | sed 's/\.\.\..*Passed.*//' | sed 's/\.\.\..*Failed.*//' | sed 's/\.\.\..*Skipped.*//' | sed 's/^[[:space:]]*//' | sed 's/[[:space:]]*$//')
+            if echo "$line" | grep -q "Passed"; then
+              echo "| $hook | ✅ Passed |" >> $GITHUB_STEP_SUMMARY
+            elif echo "$line" | grep -q "Failed"; then
+              echo "| $hook | ❌ Failed |" >> $GITHUB_STEP_SUMMARY
+            else
+              echo "| $hook | ⏭️ Skipped |" >> $GITHUB_STEP_SUMMARY
+            fi
+          done
+
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "<details>" >> $GITHUB_STEP_SUMMARY
+          echo "<summary>📋 Click to see detailed error output</summary>" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          cat output.txt >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "</details>" >> $GITHUB_STEP_SUMMARY
+
+          exit 1
+        fi

.github/actions/tools/pytest/action.yaml

@@ -0,0 +1,104 @@
+name: 'Pytest'
+description: 'Pytest'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Checkout code
+      uses: actions/checkout@v5
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      shell: bash
+      run: |
+        uv sync --frozen
+
+    - name: Run all tests with coverage
+      id: pytest
+      shell: bash
+      run: |
+        echo "##   Pytest Results" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+
+        if uv run pytest tests/ -v --tb=short --junitxml=pytest-results.xml --cov=src --cov-report=term-missing --cov-report=xml --cov-report=html 2>&1 | tee pytest-output.txt; then
+          echo "✅ **All tests passed!**" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          # Extract test summary from pytest output
+          if grep -q "passed" pytest-output.txt; then
+            passed_count=$(grep -o '[0-9]\+ passed' pytest-output.txt | grep -o '[0-9]\+' | head -1)
+            echo "| Status | Count |" >> $GITHUB_STEP_SUMMARY
+            echo "|--------|-------|" >> $GITHUB_STEP_SUMMARY
+            echo "| ✅ Passed | $passed_count |" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          if grep -q "skipped" pytest-output.txt; then
+            skipped_count=$(grep -o '[0-9]\+ skipped' pytest-output.txt | grep -o '[0-9]\+' | head -1)
+            echo "| ⏭️ Skipped | $skipped_count |" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          if grep -q "warnings" pytest-output.txt; then
+            warnings_count=$(grep -o '[0-9]\+ warnings' pytest-output.txt | grep -o '[0-9]\+' | head -1)
+            echo "| ⚠️ Warnings | $warnings_count |" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📊 Test Summary" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          tail -10 pytest-output.txt >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+
+        else
+          echo "❌ **Some tests failed**" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          # Extract test summary from pytest output
+          if grep -q "passed" pytest-output.txt; then
+            passed_count=$(grep -o '[0-9]\+ passed' pytest-output.txt | grep -o '[0-9]\+' | head -1)
+            echo "| Status | Count |" >> $GITHUB_STEP_SUMMARY
+            echo "|--------|-------|" >> $GITHUB_STEP_SUMMARY
+            echo "| ✅ Passed | $passed_count |" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          if grep -q "failed" pytest-output.txt; then
+            failed_count=$(grep -o '[0-9]\+ failed' pytest-output.txt | grep -o '[0-9]\+' | head -1)
+            echo "| ❌ Failed | $failed_count |" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          if grep -q "skipped" pytest-output.txt; then
+            skipped_count=$(grep -o '[0-9]\+ skipped' pytest-output.txt | grep -o '[0-9]\+' | head -1)
+            echo "| ⏭️ Skipped | $skipped_count |" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          if grep -q "warnings" pytest-output.txt; then
+            warnings_count=$(grep -o '[0-9]\+ warnings' pytest-output.txt | grep -o '[0-9]\+' | head -1)
+            echo "| ⚠️ Warnings | $warnings_count |" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "<details>" >> $GITHUB_STEP_SUMMARY
+          echo "<summary>📋 Click to see detailed test output</summary>" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          cat pytest-output.txt >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "</details>" >> $GITHUB_STEP_SUMMARY
+
+          exit 1
+        fi
+
+        # Coverage report (shown for both success and failure)
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "### 📈 Coverage Report" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        # Convert coverage output to markdown table
+        python3 ${GITHUB_ACTION_PATH}/markdown.py pytest-output.txt >> $GITHUB_STEP_SUMMARY

.github/actions/tools/pytest/markdown.py

@@ -0,0 +1,89 @@
+"""
+Convert pytest coverage output to markdown table format.
+"""
+
+import re
+import sys
+
+
+def coverage_to_markdown(output_file: str) -> None:
+    """Convert pytest coverage output to markdown table.
+
+    Args:
+        output_file: Path to the pytest coverage text report.
+
+    Returns:
+        None: The function prints the markdown table to stdout.
+    """
+    try:
+        with open(output_file) as f:
+            content = f.read()
+    except FileNotFoundError:
+        print("| Error | Coverage output file not found | - | - | - |")
+        return
+
+    # Find the coverage section
+    lines = content.split("\n")
+    in_coverage_section = False
+    coverage_lines = []
+    total_line = ""
+
+    for line in lines:
+        if "Name" in line and "Stmts" in line and "Miss" in line and "Cover" in line:
+            in_coverage_section = True
+            continue
+        elif in_coverage_section:
+            if line.strip() == "" or line.startswith("="):
+                continue
+            elif line.startswith("TOTAL"):
+                total_line = line.strip()
+                break
+            elif line.strip():
+                coverage_lines.append(line.strip())
+
+    # Print markdown table header
+    print("| File | Statements | Missing | Coverage | Missing Lines |")
+    print("|------|------------|---------|----------|---------------|")
+
+    # Parse each coverage line
+    for line in coverage_lines:
+        # Match pattern: filename.py   123   45   67%   12, 34-56, 78
+        match = re.match(r"^([^\s]+\.py)\s+(\d+)\s+(\d+)\s+(\d+)%\s*(.*)$", line)
+        if match:
+            filename = match.group(1)
+            statements = int(match.group(2))
+            missing = int(match.group(3))
+            coverage_pct = int(match.group(4))
+            missing_details = match.group(5).strip()
+
+            # Clean up filename (remove src/ prefix if present)
+            clean_filename = filename.replace("src/", "")
+
+            # Format missing lines
+            if missing_details and missing_details != "-":
+                # Limit the missing details to avoid overly long tables
+                if len(missing_details) > 40:
+                    missing_details = missing_details[:37] + "..."
+                missing_cell = f"`{missing_details}`"
+            else:
+                missing_cell = "None"
+
+            print(
+                f"| {clean_filename} | {statements} | {missing} | {coverage_pct}% | {missing_cell} |"
+            )
+
+    # Add total row
+    if total_line:
+        match = re.match(r"^TOTAL\s+(\d+)\s+(\d+)\s+(\d+)%", total_line)
+        if match:
+            statements = int(match.group(1))
+            missing = int(match.group(2))
+            coverage_pct = int(match.group(3))
+            print(
+                f"| **TOTAL** | **{statements}** | **{missing}** | **{coverage_pct}%** | - |"
+            )
+
+
+if __name__ == "__main__":
+    output_file = sys.argv[1] if len(sys.argv) > 1 else "pytest-output.txt"
+    coverage_to_markdown(output_file)

.github/pull_request_template.md

@@ -0,0 +1,5 @@
+### Description
+
+
+
+Fixes (issue)

.github/workflows/chore.yaml

@@ -0,0 +1,28 @@
+name: Chore
+
+on:
+  pull_request:
+    types: [opened, edited]
+
+jobs:
+  update-pr-title:
+    if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'edited')
+    runs-on: instadeep-ci
+    container:
+      image: ghcr.io/catthehacker/ubuntu:runner-latest
+      credentials:
+        username: ${{ github.actor }}
+        password: ${{ secrets.github_token }}
+    permissions: write-all
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.head_ref }}
+          fetch-depth: 0
+
+      - name: Update PR Title and Body
+        uses: ./.github/actions/tools/pr-title-generator
+        with:
+          github-token: ${{ github.token }}

.github/workflows/main.yaml

@@ -0,0 +1,67 @@
+name: Main Workflow
+
+on:
+  push:
+
+concurrency:
+  group: ${{ github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  pre-commit:
+    runs-on:
+      group: kao-products-runners
+      labels: instadeep-ci-4
+    container:
+      image: ghcr.io/catthehacker/ubuntu:runner-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.head_ref }}
+          fetch-depth: 0
+
+      - name: Pre-commit
+        uses: ./.github/actions/tools/pre-commit
+
+  pytest:
+    runs-on:
+      group: kao-products-runners
+      labels: instadeep-ci
+    container:
+      image: ghcr.io/catthehacker/ubuntu:runner-latest
+    env:
+      CI: 1
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.head_ref }}
+          fetch-depth: 0
+
+      - name: Pytest
+        uses: ./.github/actions/tools/pytest
+
+  hugging-face:
+    if: github.ref == 'refs/heads/main'
+    runs-on:
+      group: kao-products-runners
+      labels: instadeep-ci
+    container:
+      image: ghcr.io/catthehacker/ubuntu:runner-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.head_ref || github.ref_name }}
+          fetch-depth: 0
+          lfs: true
+
+      - name: Hugging Face
+        uses: ./.github/actions/tools/huggingface
+        with:
+          token: ${{ secrets.HF_TOKEN }}
+          space: "InstaDeepAI/sentinel"
+          branch: main
+          runtime-secrets: |
+            GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}

.gitignore

@@ -0,0 +1,100 @@
+# Python general
+__pycache__/
+*.py[cod]
+*.so
+*.egg
+*.egg-info/
+*.pyd
+.DS_Store
+
+# Virtual environments
+.venv/
+
+# Byte-compiled / optimized / DLL files
+*.pyc
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+.eggs/
+.eggs-info/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# dotenv
+.env
+.env.*
+!.env.example
+
+# mypy
+.mypy_cache/
+.dmypy.json
+compiled/
+
+# Pyre type checker
+.pyre/
+
+# pyright type checker
+pyrightconfig.json
+
+# pytype
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Reports
+outputs/
+*.xlsx
+*.pdf
+
+# Cursor
+.cursor/

.pre-commit-config.yaml

@@ -0,0 +1,111 @@
+default_language_version:
+  python: python3.12
+
+default_stages: [pre-commit]
+
+repos:
+  - repo: https://github.com/hakancelikdev/unimport
+    rev: 1.3.0
+    hooks:
+      - id: unimport
+        args:
+          - --remove
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.1
+    hooks:
+      - id: ruff-format
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.8.1
+    hooks:
+      - id: nbstripout
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        name: codespell
+        description: Checks for common misspellings in text files.
+        entry: codespell --skip="*.js,*.html,*.css, *.svg" --ignore-words=.codespell-ignore.txt
+        language: python
+        types: [text]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: debug-statements
+      - id: check-ast  # Simply check whether the files parse as valid python
+      - id: check-case-conflict  # Check for files that would conflict in case-insensitive filesystems
+      - id: check-builtin-literals  # Require literal syntax when initializing empty or zero Python builtin types
+      - id: check-docstring-first  # Check a common error of defining a docstring after code
+      - id: check-merge-conflict  # Check for files that contain merge conflict strings
+      - id: check-yaml  # Check yaml files
+        args: ["--unsafe"]  # Allows special tags in mkdocs.yaml
+      - id: end-of-file-fixer  # Ensure that a file is either empty, or ends with one newline
+        exclude: end-to-end-pipeline/web/.*
+      - id: mixed-line-ending  # Replace or checks mixed line ending
+      - id: trailing-whitespace  # This hook trims trailing whitespace
+      - id: file-contents-sorter  # Sort the lines in specified files
+        files: .*requirements*\.txt$
+
+  - repo: https://github.com/google/yamlfmt
+    rev: v0.17.2
+    hooks:
+      - id: yamlfmt
+        args: ["-formatter", "retain_line_breaks_single=true,pad_line_comments=2"]
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.20.0
+    hooks:
+      - id: pyupgrade
+        args: [--py312-plus]
+
+  # The following hook sorts and formats toml files
+  - repo: https://github.com/pappasam/toml-sort
+    rev: v0.24.3
+    hooks:
+      - id: toml-sort
+        description: "Sort and format toml files."
+        args:
+          - --all
+          - --in-place
+
+  # The following hook checks for secrets in the code
+  - repo: https://github.com/zricethezav/gitleaks
+    rev: v8.28.0
+    hooks:
+      - id: gitleaks
+
+  # The following hook checks for secrets in the code
+  - repo: https://github.com/trufflesecurity/trufflehog
+    rev: v3.90.8
+    hooks:
+      - id: trufflehog
+
+  - repo: local
+    hooks:
+      - id: pylint
+        name: pylint
+        entry: pylint
+        language: python
+        additional_dependencies: ["pylint"]
+        types: [python]
+        args: ["--disable=all", "--enable=missing-docstring,unused-argument"]
+        exclude: 'test_\.py$'
+
+  # The following hook check docstrings quality
+  - repo: https://github.com/terrencepreilly/darglint
+    rev: v1.8.1
+    hooks:
+      - id: darglint
+        args: ["--docstring-style=google"]
+        exclude: 'src/sentinel/risk_models/qcancer\.py$'
+
+    # The following hook checks for docstring in functions
+  - repo: https://github.com/pycqa/pydocstyle
+    rev: 6.3.0
+    hooks:
+      - id: pydocstyle
+        args: ["--select=D103", "--match-dir=(genomics_research|projects)"]

.streamlit/config.toml

@@ -0,0 +1,6 @@
+[theme]
+backgroundColor = "#FFFFFF"
+font = "Roboto"
+primaryColor = "#007AFF"
+secondaryBackgroundColor = "#F8FBFF"
+textColor = "#0059B3"

AGENTS.md

@@ -0,0 +1,55 @@
+# Repo Guidelines
+
+This repository contains the LLM-based Cancer Risk Assessment Assistant.
+
+## Core Technologies
+- **FastAPI** for the web framework
+- **LangChain** for LLM orchestration
+- **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.
+
+## 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`.
+
+## Running commands
+- As the repository uses uv, the uv should be used to run all commands, e.g., "uv run python ..." NOT "python ...".
+
+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.
+
+## 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`
+
+## Risk Model Coverage
+
+Implemented risk calculators include:
+- **Gail** - Breast cancer risk
+- **Claus** - Breast cancer risk based on family history
+- **PLCOm2012** - Lung cancer risk
+- **CRC-PRO** - Colorectal cancer risk
+- **PCPT** - Prostate cancer risk
+- **Extended PBCG** - Prostate cancer risk (extended model)
+- **BOADICEA** - Breast and ovarian cancer risk (via CanRisk API)
+- **QCancer** - Multi-site cancer differential
+
+Additional models should follow the interfaces under `src/sentinel/risk_models`.

Dockerfile

@@ -0,0 +1,38 @@
+FROM python:3.12-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Copy dependency files first for better caching
+COPY pyproject.toml uv.lock* ./
+
+# Copy the entire project
+COPY . .
+
+# Set UV cache directory to a writable location
+ENV UV_CACHE_DIR=/tmp/uv-cache
+ENV HOME=/tmp
+
+# Install dependencies with uv
+RUN uv sync --frozen --no-dev
+
+# Create cache directory and set permissions
+RUN mkdir -p /tmp/uv-cache && chmod -R 777 /tmp/uv-cache
+
+# Make /app directory writable for non-root users (required for HuggingFace Spaces)
+RUN chmod -R 777 /app
+
+# Expose Streamlit port
+EXPOSE 8501
+
+# Set environment variables for Streamlit
+ENV STREAMLIT_SERVER_PORT=8501
+ENV STREAMLIT_SERVER_ADDRESS=0.0.0.0
+ENV STREAMLIT_SERVER_HEADLESS=true
+ENV STREAMLIT_BROWSER_GATHER_USAGE_STATS=false
+
+# Run Streamlit app
+CMD ["uv", "run", "streamlit", "run", "apps/streamlit_ui/main.py"]

GEMINI.md

@@ -0,0 +1,55 @@
+# Repo Guidelines
+
+This repository contains the LLM-based Cancer Risk Assessment Assistant.
+
+## Core Technologies
+- **FastAPI** for the web framework
+- **LangChain** for LLM orchestration
+- **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.
+
+## 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`.
+
+## Running commands
+- As the repository uses uv, the uv should be used to run all commands, e.g., "uv run python ..." NOT "python ...".
+
+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.
+
+## 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`
+
+## Risk Model Availability
+
+Risk calculators exposed to Gemini-based agents include:
+- **Gail** - Breast cancer risk
+- **Claus** - Breast cancer risk based on family history
+- **PLCOm2012** - Lung cancer risk
+- **CRC-PRO** - Colorectal cancer risk
+- **PCPT** - Prostate cancer risk
+- **Extended PBCG** - Prostate cancer risk (extended model)
+- **BOADICEA** - Breast and ovarian cancer risk (via CanRisk API)
+- **QCancer** - Multi-site cancer differential
+
+Register additional models in `src/sentinel/risk_models/__init__.py` so they are available system-wide.

README.md

@@ -1,12 +1,173 @@
 ---
-title: Sentinel
-emoji: 📚
-colorFrom: red
-colorTo: indigo
-sdk: gradio
-sdk_version: 5.49.1
-app_file: app.py
+title: Sentinel - Cancer Risk Assessment Assistant
+emoji: 🏥
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 8501
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# LLM-based Cancer Risk Assessment Assistant
+
+This project is an API service that provides preliminary cancer risk assessments based on user-provided data. It is built using FastAPI and LangChain, with a flexible architecture that supports both local and API-based LLMs.
+
+## Development Setup
+
+1. Create the virtual environment:
+
+```bash
+uv sync
+```
+
+## External API Configuration
+
+For risk models that require external APIs, such as CanRisk (BOADICEA model), fill in the following section of the `.env` file:
+
+```bash
+# .env
+CANRISK_USERNAME=your_canrisk_username
+CANRISK_PASSWORD=your_canrisk_password
+```
+
+Then source it: `source .env`
+
+For CanRisk API access , register at https://www.canrisk.org/.
+
+## Using a Local LLM (Ollama)
+
+1. Install [Ollama](https://ollama.com) for your platform.
+2. Pull the default model from the command line:
+
+```bash
+ollama pull gemma3:4b
+```
+3. Ensure the Ollama desktop app or server is running. You can check your installed models with `ollama list`.
+
+## Using API-based LLMs (Google)
+
+1. Create a `.env` file in the project root with your `GOOGLE_API_KEY`:
+
+   ```bash
+   echo "GOOGLE_API_KEY=your_key_here" > .env
+   ```
+
+   Make sure the Generative AI API is enabled for your Google Cloud project.
+
+2. Run the command line demo with the Google provider (default):
+
+   ```bash
+   uv run python apps/cli/main.py
+   ```
+
+   Switch to the local model with:
+
+   ```bash
+   uv run python apps/cli/main.py model=gemma3_4b
+   ```
+
+3. The `model` override also works with the Streamlit and FastAPI interfaces.
+
+
+## Interactive Demo
+
+Run a simple command line demo with:
+
+```bash
+uv run python apps/cli/main.py
+```
+
+Enable developer mode and load user data from a file with:
+
+```bash
+uv run python apps/cli/main.py dev_mode=true user_file=examples/user_example.yaml
+```
+
+The script collects user data, prints the structured JSON assessment, and then allows follow-up questions in a chat-like loop. Type `quit` to exit.
+
+The multi-page Streamlit interface provides an expert feedback interface located at
+`apps/streamlit_ui/main.py`.
+The first page, **User Profile**, lets you upload or manually create a profile
+before running assessments.
+The **Configuration** page allows you to choose the model and knowledge base modules and shows a live preview of the full LLM prompt.
+The **Assessment** page runs the model, shows a dashboard of results, and lets you export or chat with the assistant.
+
+### Exporting Reports
+
+After the initial assessment is displayed in the terminal, you will be prompted to export the full report to a formatted file. You can choose to generate a PDF, an Excel file, or both. The generated files (e.g., `Cancer_Risk_Report_20250626_213000.pdf`) will be saved in the root directory of the project.
+
+**Note:** This feature requires the `openpyxl` and `reportlab` libraries.
+
+You can also provide a JSON or YAML file with all user information to skip the
+interactive prompts:
+
+```bash
+uv run python apps/cli/main.py user_file=examples/user_example.yaml
+```
+
+To launch the Streamlit interface, run the following command from the root of the
+project:
+
+```bash
+uv run streamlit run apps/streamlit_ui/main.py
+```
+
+*Note* To serve the app locally you can use `ngrok`
+```bash
+ ngrok http 8501
+ ```
+
+## Important Note for Developers
+
+When making changes to the project, check if the following files should also updated to reflect the changes:
+
+- `README.md`
+- `AGENTS.md`
+- `GEMINI.md`
+
+## Available Risk Models
+
+The assistant currently includes the following built-in risk calculators:
+
+- Gail Model (Breast Cancer)
+- PLCOm2012 (Lung Cancer)
+- CRC-PRO (Colorectal Cancer)
+- PCPT (Prostate Cancer)
+- QCancer (Multi-site cancer differential)
+
+## Generating Documentation
+
+The project includes a comprehensive PDF documentation generator that creates detailed documentation of all implemented risk models and their input requirements.
+
+### Generate Risk Model Documentation
+
+To generate the PDF documentation:
+
+```bash
+uv run python scripts/generate_documentation.py
+```
+
+This will create a comprehensive PDF document (`docs/risk_model_documentation.pdf`) that includes:
+
+1. **Overview Section**:
+   - Cancer type coverage chart
+   - Statistics on implemented risk scores and cancer types covered
+
+2. **Detailed Model Information**:
+   - Description, interpretation, and references for each risk model
+   - Complete input requirements with field details, required status, units, and possible values/choices
+
+3. **Input-to-Cancer Mapping**:
+   - Reverse mapping showing which cancer types use each input field
+   - Possible values for each field
+   - Comprehensive coverage analysis
+
+The documentation is automatically regenerated based on the current codebase, ensuring it stays up-to-date as new risk models and input fields are added.
+
+### Documentation Features
+
+- **Comprehensive Coverage**: Documents all risk models and their input requirements
+- **Visual Charts**: Includes cancer type coverage visualization
+- **Detailed Tables**: Shows field specifications, constraints, and valid values
+- **Professional Layout**: Clean, readable PDF format suitable for sharing
+- **Auto-Generated**: Stays synchronized with code changes automatically

RISK_MODELS.md

@@ -0,0 +1,587 @@
+# 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`:
+
+```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
+
+### Required Imports
+
+```python
+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:
+
+```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),
+    "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:
+
+```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)}")
+
+    # Continue with model-specific logic...
+```
+
+### Model-Specific Validation
+
+Add additional validation as needed:
+
+```python
+# 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
+
+```python
+# 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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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:
+
+```python
+# ✅ 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:
+
+```python
+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:
+
+```python
+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
+
+```python
+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
+
+```python
+"""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.

apps/__init__.py

@@ -0,0 +1 @@
+# Apps package for the Sentinel project

apps/api/__init__.py

@@ -0,0 +1 @@
+# API package

apps/api/main.py

@@ -0,0 +1,121 @@
+"""FastAPI application exposing cancer risk assessment endpoints."""
+
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException
+
+from sentinel.config import AppConfig, ModelConfig, ResourcePaths
+from sentinel.factory import SentinelFactory
+from sentinel.models import InitialAssessment, UserInput
+
+app = FastAPI(
+    title="Cancer Risk Assessment Assistant",
+    description="API for assessing cancer risks using LLMs.",
+)
+
+# Define base paths relative to the project root
+BASE_DIR = Path(__file__).resolve().parents[2]  # Go up to project root
+CONFIGS_DIR = BASE_DIR / "configs"
+PROMPTS_DIR = BASE_DIR / "prompts"
+
+
+def create_knowledge_base_paths() -> ResourcePaths:
+    """Build resource path configuration resolved from the repository root.
+
+    Returns:
+        ResourcePaths: Paths pointing to persona, prompt, and configuration
+        assets required by the API routes.
+    """
+
+    return ResourcePaths(
+        persona=PROMPTS_DIR / "persona" / "default.md",
+        instruction_assessment=PROMPTS_DIR / "instruction" / "assessment.md",
+        instruction_conversation=PROMPTS_DIR / "instruction" / "conversation.md",
+        output_format_assessment=CONFIGS_DIR / "output_format" / "assessment.yaml",
+        output_format_conversation=CONFIGS_DIR / "output_format" / "conversation.yaml",
+        cancer_modules_dir=CONFIGS_DIR / "knowledge_base" / "cancer_modules",
+        dx_protocols_dir=CONFIGS_DIR / "knowledge_base" / "dx_protocols",
+    )
+
+
+@app.get("/")
+async def read_root() -> dict:
+    """Return a simple greeting message.
+
+    Returns:
+        dict: A dictionary containing a greeting message.
+    """
+    return {"message": "Hello, world!"}
+
+
+@app.post("/assess/{provider}", response_model=InitialAssessment)
+async def assess(
+    provider: str,
+    user_input: UserInput,
+    model: str | None = None,
+    cancer_modules: list[str] | None = None,
+    dx_protocols: list[str] | None = None,
+) -> InitialAssessment:
+    """Assess cancer risk for a user.
+
+    Args:
+        provider (str): LLM provider identifier (for example ``"openai"`` or
+            ``"anthropic"``).
+        user_input (UserInput): Structured demographics and clinical
+            information supplied by the client.
+        model (str | None): Optional model name overriding the provider
+            default.
+        cancer_modules (list[str] | None): Optional list of cancer module slugs
+            to include in the knowledge base.
+        dx_protocols (list[str] | None): Optional list of diagnostic protocol
+            slugs to include.
+
+    Returns:
+        InitialAssessment: Parsed model output describing the initial
+        assessment.
+
+    Raises:
+        HTTPException: 400 for invalid input, 500 for unexpected errors.
+    """
+    try:
+        # Create knowledge base paths
+        knowledge_base_paths = create_knowledge_base_paths()
+
+        # Set default model name if not provided
+        if model is None:
+            model_defaults = {
+                "openai": "gpt-4o-mini",
+                "anthropic": "claude-3-5-sonnet-20241022",
+                "google": "gemini-1.5-pro",
+            }
+            model = model_defaults.get(provider, "gpt-4o-mini")
+
+        # Set default modules if not provided
+        if cancer_modules is None:
+            cancer_modules_dir = knowledge_base_paths.cancer_modules_dir
+            cancer_modules = [p.stem for p in cancer_modules_dir.glob("*.yaml")]
+
+        if dx_protocols is None:
+            dx_protocols_dir = knowledge_base_paths.dx_protocols_dir
+            dx_protocols = [p.stem for p in dx_protocols_dir.glob("*.yaml")]
+
+        # Create AppConfig
+        app_config = AppConfig(
+            model=ModelConfig(provider=provider, model_name=model),
+            knowledge_base_paths=knowledge_base_paths,
+            selected_cancer_modules=cancer_modules,
+            selected_dx_protocols=dx_protocols,
+        )
+
+        # Create factory and conversation manager
+        factory = SentinelFactory(app_config)
+        conversation_manager = factory.create_conversation_manager()
+
+        # Run assessment
+        response = conversation_manager.initial_assessment(user_input)
+        return response
+
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Internal Server Error: {e!s}")

apps/cli/__init__.py

@@ -0,0 +1 @@
+# CLI package

apps/cli/main.py

@@ -0,0 +1,539 @@
+"""Command-line interface for running assessments and exporting reports."""
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+import hydra
+from hydra.utils import to_absolute_path
+from omegaconf import DictConfig
+
+from sentinel.config import AppConfig, ModelConfig, ResourcePaths
+from sentinel.factory import SentinelFactory
+from sentinel.models import (
+    ConversationResponse,
+    Demographics,
+    FamilyMemberCancer,
+    FemaleSpecific,
+    InitialAssessment,
+    Lifestyle,
+    PersonalMedicalHistory,
+    UserInput,
+)
+from sentinel.reporting import generate_excel_report, generate_pdf_report
+from sentinel.risk_models import RISK_MODELS
+from sentinel.utils import load_user_file
+
+
+# Color codes for terminal output
+class Colors:
+    """ANSI color codes for terminal output formatting."""
+
+    HEADER = "\033[95m"
+    OKBLUE = "\033[94m"
+    OKCYAN = "\033[96m"
+    OKGREEN = "\033[92m"
+    WARNING = "\033[93m"
+    FAIL = "\033[91m"
+    ENDC = "\033[0m"
+    BOLD = "\033[1m"
+    UNDERLINE = "\033[4m"
+
+
+def _get_input(prompt: str, optional: bool = False) -> str:
+    """Get a line of input from the user.
+
+    Args:
+        prompt: Message to display to the user.
+        optional: If True, allow empty input to be returned as an empty string.
+
+    Returns:
+        The raw string entered by the user (may be empty if optional).
+    """
+    suffix = " (optional, press Enter to skip)" if optional else ""
+    return input(f"{Colors.OKCYAN}{prompt}{suffix}:{Colors.ENDC} ")
+
+
+def _get_int_input(prompt: str, optional: bool = False) -> int | None:
+    """Get an integer from the user.
+
+    Args:
+        prompt: Message to display to the user.
+        optional: If True, allow empty input and return None.
+
+    Returns:
+        The parsed integer value, or None if optional and left empty.
+    """
+    while True:
+        val = _get_input(prompt, optional)
+        if not val and optional:
+            return None
+        try:
+            return int(val)
+        except (ValueError, TypeError):
+            print(f"{Colors.WARNING}Please enter a valid number.{Colors.ENDC}")
+
+
+def collect_user_input() -> UserInput:
+    """Collect user profile data interactively.
+
+    Returns:
+        UserInput: Structured demographics, lifestyle, and clinical data
+        assembled from CLI prompts.
+    """
+    print(
+        f"\n{Colors.HEADER}{Colors.BOLD}=== User Information Collection ==={Colors.ENDC}"
+    )
+    print("Please provide the following details for your assessment.")
+
+    # --- DEMOGRAPHICS ---
+    print(f"\n{Colors.OKBLUE}{Colors.BOLD}--- Demographics ---{Colors.ENDC}")
+    age = _get_int_input("Age")
+    sex = _get_input("Biological Sex (e.g., Male, Female)")
+    ethnicity = _get_input("Ethnicity", optional=True)
+    demographics = Demographics(age=age, sex=sex, ethnicity=ethnicity)
+
+    # --- LIFESTYLE ---
+    print(f"\n{Colors.OKBLUE}{Colors.BOLD}--- Lifestyle ---{Colors.ENDC}")
+    smoking_status = _get_input("Smoking Status (e.g., never, former, current)")
+    smoking_pack_years = (
+        _get_int_input("Smoking Pack-Years", optional=True)
+        if smoking_status in ["former", "current"]
+        else None
+    )
+    alcohol_consumption = _get_input(
+        "Alcohol Consumption (e.g., none, light, moderate, heavy)"
+    )
+    dietary_habits = _get_input("Dietary Habits", optional=True)
+    physical_activity_level = _get_input("Physical Activity Level", optional=True)
+    lifestyle = Lifestyle(
+        smoking_status=smoking_status,
+        smoking_pack_years=smoking_pack_years,
+        alcohol_consumption=alcohol_consumption,
+        dietary_habits=dietary_habits,
+        physical_activity_level=physical_activity_level,
+    )
+
+    # --- PERSONAL MEDICAL HISTORY ---
+    print(
+        f"\n{Colors.OKBLUE}{Colors.BOLD}--- Personal Medical History ---{Colors.ENDC}"
+    )
+    mutations = _get_input("Known genetic mutations (comma-separated)", optional=True)
+    cancers = _get_input("Previous cancers (comma-separated)", optional=True)
+    illnesses = _get_input(
+        "Chronic illnesses (e.g., IBD, comma-separated)", optional=True
+    )
+    personal_medical_history = PersonalMedicalHistory(
+        known_genetic_mutations=[m.strip() for m in mutations.split(",")]
+        if mutations
+        else [],
+        previous_cancers=[c.strip() for c in cancers.split(",")] if cancers else [],
+        chronic_illnesses=[i.strip() for i in illnesses.split(",")]
+        if illnesses
+        else [],
+    )
+
+    # --- CLINICAL OBSERVATIONS ---
+    print(
+        f"\n{Colors.OKBLUE}{Colors.BOLD}--- Clinical Observations / Test Results (Optional) ---{Colors.ENDC}"
+    )
+    clinical_observations = []
+    while True:
+        add_test = _get_input(
+            "Add a clinical observation or test result? (y/N)"
+        ).lower()
+        if add_test not in ["y", "yes"]:
+            break
+        test_name = _get_input("Test/Observation Name")
+        value = _get_input("Value")
+        unit = _get_input("Unit (e.g., ng/mL, or N/A)")
+        reference_range = _get_input("Reference Range", optional=True)
+        date = _get_input("Date of Test (YYYY-MM-DD)", optional=True)
+        clinical_observations.append(
+            {
+                "test_name": test_name,
+                "value": value,
+                "unit": unit,
+                "reference_range": reference_range or None,
+                "date": date or None,
+            }
+        )
+
+    # --- FAMILY HISTORY ---
+    print(
+        f"\n{Colors.OKBLUE}{Colors.BOLD}--- Family History of Cancer ---{Colors.ENDC}"
+    )
+    family_history = []
+    while True:
+        add_relative = _get_input("Add a family member with cancer? (y/N)").lower()
+        if add_relative not in ["y", "yes"]:
+            break
+        relative = _get_input("Relative (e.g., mother, sister)")
+        cancer_type = _get_input("Cancer Type")
+        age_at_diagnosis = _get_int_input("Age at Diagnosis", optional=True)
+        family_history.append(
+            FamilyMemberCancer(
+                relative=relative,
+                cancer_type=cancer_type,
+                age_at_diagnosis=age_at_diagnosis,
+            )
+        )
+
+    # --- FEMALE-SPECIFIC ---
+    female_specific = None
+    if sex.lower() == "female":
+        print(
+            f"\n{Colors.OKBLUE}{Colors.BOLD}--- Female-Specific Information ---{Colors.ENDC}"
+        )
+        age_at_first_period = _get_int_input("Age at first period", optional=True)
+        age_at_menopause = _get_int_input("Age at menopause", optional=True)
+        num_live_births = _get_int_input("Number of live births", optional=True)
+        age_at_first_live_birth = _get_int_input(
+            "Age at first live birth", optional=True
+        )
+        hormone_therapy_use = _get_input("Hormone therapy use", optional=True)
+        female_specific = FemaleSpecific(
+            age_at_first_period=age_at_first_period,
+            age_at_menopause=age_at_menopause,
+            num_live_births=num_live_births,
+            age_at_first_live_birth=age_at_first_live_birth,
+            hormone_therapy_use=hormone_therapy_use,
+        )
+
+    # --- CURRENT CONCERNS ---
+    print(f"\n{Colors.OKBLUE}{Colors.BOLD}--- Current Concerns ---{Colors.ENDC}")
+    current_concerns_or_symptoms = _get_input(
+        "Current symptoms or health concerns", optional=True
+    )
+
+    return UserInput(
+        demographics=demographics,
+        lifestyle=lifestyle,
+        family_history=family_history,
+        personal_medical_history=personal_medical_history,
+        female_specific=female_specific,
+        current_concerns_or_symptoms=current_concerns_or_symptoms,
+        clinical_observations=clinical_observations,
+    )
+
+
+def format_risk_assessment(response: InitialAssessment, dev_mode: bool = False) -> None:
+    """Pretty-print an initial risk assessment payload.
+
+    Args:
+        response (InitialAssessment): Parsed result returned by the assessment
+            chain.
+        dev_mode (bool): Flag enabling verbose debugging output.
+    """
+    # In dev mode, show everything
+    if dev_mode:
+        print(
+            f"\n{Colors.WARNING}{Colors.BOLD}--- DEV MODE: RAW MODEL OUTPUT ---{Colors.ENDC}"
+        )
+        # Use model_dump instead of model_dump_json for direct printing
+        print(json.dumps(response.model_dump(), indent=2))
+        print(
+            f"\n{Colors.WARNING}{Colors.BOLD}--- DEV MODE: PARSED & VALIDATED PYDANTIC OBJECT ---{Colors.ENDC}"
+        )
+        if response.thinking:
+            print(
+                f"{Colors.OKCYAN}{Colors.BOLD}🤔 Chain of Thought (`<think>` block):{Colors.ENDC}"
+            )
+            print(response.thinking)
+            print(f"{Colors.WARNING}{Colors.BOLD}{'-' * 30}{Colors.ENDC}")
+        if response.reasoning:
+            print(
+                f"{Colors.OKCYAN}{Colors.BOLD}🧠 Reasoning (`<reasoning>` block):{Colors.ENDC}"
+            )
+            print(response.reasoning)
+            print(f"{Colors.WARNING}{Colors.BOLD}{'-' * 30}{Colors.ENDC}")
+        print(f"{Colors.OKCYAN}{Colors.BOLD}Full Pydantic Object:{Colors.ENDC}")
+
+        # return
+        print(
+            f"\n{Colors.WARNING}{Colors.BOLD}--- DEV MODE: FORMATTED MODEL OUTPUT ---{Colors.ENDC}"
+        )
+
+    # User-friendly formatting
+    print(f"\n{Colors.HEADER}{Colors.BOLD}{'=' * 60}")
+    print("🏥 CANCER RISK ASSESSMENT REPORT")
+    print(f"{'=' * 60}{Colors.ENDC}")
+
+    # Display the primary user-facing response first
+    if response.response:
+        print(f"\n{Colors.OKCYAN}{Colors.BOLD}🤖 BiOS:{Colors.ENDC}")
+        print(response.response)
+
+    # Then display the structured summary and details
+    print(f"\n{Colors.OKBLUE}{Colors.BOLD}📋 OVERALL SUMMARY{Colors.ENDC}")
+    if response.overall_risk_score is not None:
+        print(
+            f"{Colors.OKCYAN}Overall Risk Score: {Colors.BOLD}{response.overall_risk_score}/100{Colors.ENDC}"
+        )
+    if response.overall_summary:
+        print(f"{Colors.OKCYAN}{response.overall_summary}{Colors.ENDC}")
+
+    # Risk assessments
+    risk_assessments = response.risk_assessments
+    if risk_assessments:
+        print(
+            f"\n{Colors.OKBLUE}{Colors.BOLD}🎯 DETAILED RISK ASSESSMENTS{Colors.ENDC}"
+        )
+        print(f"{Colors.OKBLUE}{'─' * 40}{Colors.ENDC}")
+
+        for i, assessment in enumerate(risk_assessments, 1):
+            cancer_type = assessment.cancer_type
+            risk_level = assessment.risk_level
+            explanation = assessment.explanation
+
+            # Color code risk levels
+            if risk_level is None:
+                risk_color = Colors.ENDC
+            elif risk_level <= 2:
+                risk_color = Colors.OKGREEN
+            elif risk_level == 3:
+                risk_color = Colors.WARNING
+            else:  # 4-5
+                risk_color = Colors.FAIL
+
+            print(f"\n{Colors.BOLD}{i}. {cancer_type.upper()}{Colors.ENDC}")
+            print(
+                f"   🎚️  Risk Level: {risk_color}{Colors.BOLD}{risk_level or 'N/A'}{Colors.ENDC}"
+            )
+            print(f"   💭 Explanation: {explanation}")
+
+            # Optional fields
+            if assessment.recommended_steps:
+                print("   📝 Recommended Steps:")
+                if isinstance(assessment.recommended_steps, list):
+                    for step in assessment.recommended_steps:
+                        print(f"      • {step}")
+                else:
+                    print(f"      • {assessment.recommended_steps}")
+
+            if assessment.lifestyle_advice:
+                print(f"   🌟 Lifestyle Advice: {assessment.lifestyle_advice}")
+
+            if i < len(risk_assessments):
+                print(f"   {Colors.OKBLUE}{'─' * 40}{Colors.ENDC}")
+
+    # Diagnostic recommendations
+    dx_recommendations = response.dx_recommendations
+    if dx_recommendations:
+        print(
+            f"\n{Colors.OKBLUE}{Colors.BOLD}🔬 DIAGNOSTIC RECOMMENDATIONS{Colors.ENDC}"
+        )
+        print(f"{Colors.OKBLUE}{'─' * 40}{Colors.ENDC}")
+
+        for i, dx_rec in enumerate(dx_recommendations, 1):
+            test_name = dx_rec.test_name
+            frequency = dx_rec.frequency
+            rationale = dx_rec.rationale
+            recommendation_level = dx_rec.recommendation_level
+
+            level_text = ""
+            if recommendation_level is not None:
+                level_map = {
+                    1: "Unsuitable",
+                    2: "Unnecessary",
+                    3: "Optional",
+                    4: "Recommended",
+                    5: "Critical - Do not skip",
+                }
+                level_text = f" ({level_map.get(recommendation_level, 'Unknown')})"
+
+            print(f"\n{Colors.BOLD}{i}. {test_name.upper()}{Colors.ENDC}")
+            if recommendation_level is not None:
+                print(
+                    f"   ⭐ Recommendation Level: {Colors.BOLD}{recommendation_level}/5{level_text}{Colors.ENDC}"
+                )
+            print(f"   📅 Frequency: {Colors.OKGREEN}{frequency}{Colors.ENDC}")
+            print(f"   💭 Rationale: {rationale}")
+
+            if dx_rec.applicable_guideline:
+                print(f"   📜 Applicable Guideline: {dx_rec.applicable_guideline}")
+
+            if i < len(dx_recommendations):
+                print(f"   {Colors.OKBLUE}{'─' * 40}{Colors.ENDC}")
+
+    print(
+        f"\n{Colors.WARNING}⚠️  IMPORTANT: This assessment does not replace professional medical advice.{Colors.ENDC}"
+    )
+    print(f"{Colors.HEADER}{'=' * 60}{Colors.ENDC}")
+
+
+def format_followup_response(
+    response: ConversationResponse, dev_mode: bool = False
+) -> None:
+    """Display follow-up conversation output.
+
+    Args:
+        response (ConversationResponse): Conversation exchange returned by the
+            LLM chain.
+        dev_mode (bool): Flag enabling verbose debugging output.
+    """
+    if dev_mode:
+        print(
+            f"\n{Colors.WARNING}{Colors.BOLD}--- DEV MODE: RAW MODEL OUTPUT ---{Colors.ENDC}"
+        )
+        # Use model_dump instead of model_dump_json for direct printing
+        print(json.dumps(response.model_dump(), indent=2))
+        print(
+            f"\n{Colors.WARNING}{Colors.BOLD}--- DEV MODE: PARSED RESPONSE ---{Colors.ENDC}"
+        )
+        if response.thinking:
+            print(f"\n{Colors.OKCYAN}{Colors.BOLD}🤔 Chain of Thought:{Colors.ENDC}")
+            print(f"{Colors.OKCYAN}{response.thinking}{Colors.ENDC}")
+
+    print(f"\n{Colors.OKCYAN}{Colors.BOLD}🤖 BiOS:{Colors.ENDC}")
+    print(f"{response.response}")
+
+
+@hydra.main(config_path="../../configs", config_name="config", version_base=None)
+def main(cfg: DictConfig) -> None:
+    """Entry point for the CLI tool invoked via Hydra.
+
+    Args:
+        cfg (DictConfig): Hydra configuration containing model, knowledge base,
+            and runtime settings.
+    """
+    print(
+        f"{Colors.HEADER}{Colors.BOLD}Welcome to the Cancer Risk Assessment Tool{Colors.ENDC}"
+    )
+    print(
+        f"{Colors.OKBLUE}This tool provides preliminary cancer risk assessments based on your input.{Colors.ENDC}\n"
+    )
+
+    dev_mode = cfg.dev_mode
+
+    if dev_mode:
+        print(
+            f"{Colors.WARNING}🔧 Running in developer mode - raw JSON output enabled{Colors.ENDC}"
+        )
+    else:
+        print(
+            f"{Colors.OKGREEN}👤 Running in user mode - formatted output enabled{Colors.ENDC}"
+        )
+
+    model = cfg.model.model_name
+    provider = cfg.model.provider
+    print(f"{Colors.OKBLUE}🤖 Using model: {model} from {provider}{Colors.ENDC}")
+
+    # Create ResourcePaths with resolved absolute paths
+    knowledge_base_paths = ResourcePaths(
+        persona=Path(to_absolute_path("prompts/persona/default.md")),
+        instruction_assessment=Path(
+            to_absolute_path("prompts/instruction/assessment.md")
+        ),
+        instruction_conversation=Path(
+            to_absolute_path("prompts/instruction/conversation.md")
+        ),
+        output_format_assessment=Path(
+            to_absolute_path("configs/output_format/assessment.yaml")
+        ),
+        output_format_conversation=Path(
+            to_absolute_path("configs/output_format/conversation.yaml")
+        ),
+        cancer_modules_dir=Path(
+            to_absolute_path("configs/knowledge_base/cancer_modules")
+        ),
+        dx_protocols_dir=Path(to_absolute_path("configs/knowledge_base/dx_protocols")),
+    )
+
+    # Create AppConfig from Hydra config
+    app_config = AppConfig(
+        model=ModelConfig(provider=cfg.model.provider, model_name=cfg.model.model_name),
+        knowledge_base_paths=knowledge_base_paths,
+        selected_cancer_modules=list(cfg.knowledge_base.cancer_modules),
+        selected_dx_protocols=list(cfg.knowledge_base.dx_protocols),
+    )
+
+    # Create factory and conversation manager
+    factory = SentinelFactory(app_config)
+    conversation = factory.create_conversation_manager()
+
+    if cfg.user_file:
+        print(f"{Colors.OKBLUE}📂 Loading user data from: {cfg.user_file}{Colors.ENDC}")
+        user = load_user_file(cfg.user_file)
+    else:
+        user = collect_user_input()
+
+    print(f"\n{Colors.OKCYAN}🔄 Running risk scoring tools...{Colors.ENDC}")
+    risks_scores = []
+    for model in RISK_MODELS:
+        risk_score = model().run(user)
+        risks_scores.append(risk_score)
+
+    user.risks_scores = risks_scores
+    for risk_score in risks_scores:
+        print(f"{Colors.OKCYAN}🔄 {risk_score.name}: {risk_score.score}{Colors.ENDC}")
+
+    print(f"\n{Colors.OKGREEN}🔄 Analyzing your information...{Colors.ENDC}")
+    response = None
+    try:
+        response = conversation.initial_assessment(user)
+        format_risk_assessment(response, dev_mode)
+    except Exception as e:
+        print(f"{Colors.FAIL}❌ Error generating assessment: {e}{Colors.ENDC}")
+        return
+
+    if response:
+        export_choice = input(
+            f"\n{Colors.OKCYAN}Export full report to a file? (pdf/excel/both/N):{Colors.ENDC} "
+        ).lower()
+        if export_choice in ["pdf", "excel", "both"]:
+            output_dir = Path("outputs")
+            output_dir.mkdir(exist_ok=True)
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            base_filename = f"Cancer_Risk_Report_{timestamp}"
+
+            if export_choice in ["pdf", "both"]:
+                pdf_filename = output_dir / f"{base_filename}.pdf"
+                try:
+                    print(f"{Colors.OKCYAN}Generating PDF report...{Colors.ENDC}")
+                    generate_pdf_report(response, user, str(pdf_filename))
+                    print(
+                        f"{Colors.OKGREEN}✅ Successfully generated {pdf_filename}{Colors.ENDC}"
+                    )
+                except Exception as e:
+                    print(
+                        f"{Colors.FAIL}❌ Error generating PDF report: {e}{Colors.ENDC}"
+                    )
+
+            if export_choice in ["excel", "both"]:
+                excel_filename = output_dir / f"{base_filename}.xlsx"
+                try:
+                    print(f"{Colors.OKCYAN}Generating Excel report...{Colors.ENDC}")
+                    generate_excel_report(response, user, str(excel_filename))
+                    print(
+                        f"{Colors.OKGREEN}✅ Successfully generated {excel_filename}{Colors.ENDC}"
+                    )
+                except Exception as e:
+                    print(
+                        f"{Colors.FAIL}❌ Error generating Excel report: {e}{Colors.ENDC}"
+                    )
+
+    # Follow-up conversation loop
+    print(
+        f"\n{Colors.OKBLUE}{Colors.BOLD}💬 You can now ask follow-up questions. Type 'quit' to exit.{Colors.ENDC}"
+    )
+    while True:
+        q = input(f"\n{Colors.BOLD}You: {Colors.ENDC}")
+        if q.lower() in {"quit", "exit", "q"}:
+            print(
+                f"{Colors.OKGREEN}👋 Thank you for using the Cancer Risk Assessment Tool!{Colors.ENDC}"
+            )
+            break
+
+        if not q.strip():
+            continue
+
+        try:
+            text = conversation.follow_up(q)
+            format_followup_response(text, dev_mode)
+        except Exception as e:
+            print(f"{Colors.FAIL}❌ Error: {e}{Colors.ENDC}")
+
+
+if __name__ == "__main__":
+    main()

apps/streamlit_ui/__init__.py

@@ -0,0 +1 @@
+# Streamlit UI package

apps/streamlit_ui/main.py

@@ -0,0 +1,71 @@
+"""Streamlit entry point for the Sentinel expert feedback UI."""
+
+import streamlit as st
+
+# --- Page Configuration ---
+st.set_page_config(
+    page_title="Sentinel | AI Cancer Risk Assessment", page_icon="⚕️", layout="wide"
+)
+
+# --- Header Section ---
+st.title("Sentinel: AI-Powered Cancer Risk Assessment")
+st.markdown("""
+Welcome to **Sentinel**, an advanced demonstration of an AI-powered assistant for evidence-based cancer risk assessment.
+This tool analyzes user-provided health data to generate a preliminary risk profile and personalized diagnostic recommendations based on a configurable knowledge base.
+""")
+
+st.divider()
+
+# --- Key Features Section ---
+st.header("How It Works", anchor=False)
+col1, col2, col3 = st.columns(3, gap="large")
+
+with col1:
+    st.subheader("👤 1. Build Your Profile")
+    st.write(
+        "Navigate to the **Profile** page to input your health information. "
+        "You can either upload a pre-filled YAML file or create a new profile from scratch using our guided form."
+    )
+
+with col2:
+    st.subheader("⚙️ 2. Configure the AI")
+    st.write(
+        "On the **Configuration** page, you can select the AI model and the specific cancer modules and diagnostic protocols "
+        "from our knowledge base that will be used for your assessment."
+    )
+
+with col3:
+    st.subheader("🔬 3. Run the Assessment")
+    st.write(
+        "Finally, visit the **Assessment** page to run the analysis. You'll receive a full dashboard of your results, "
+        "and you can interact with the AI assistant via a chat interface."
+    )
+
+# --- Call to Action / How to Get Started ---
+st.header("Get Started", anchor=False)
+st.page_link(
+    "pages/1_Profile.py", label="**Go to the Profile Page to begin →**", icon="👤"
+)
+
+st.divider()
+
+st.warning(
+    "**Disclaimer:** This is a demo application - please report any bugs or issues to Tom!"
+)
+
+
+# --- Footer / About Section ---
+with st.sidebar:
+    st.info("Created by **Tom Barrett**")
+    with st.expander("About Sentinel"):
+        st.markdown("""
+        This application uses a Large Language Model (LLM) to synthesize user data with an evidence-based knowledge base,
+        providing a nuanced, preliminary cancer risk assessment.
+
+        **Powered by:**
+        - Streamlit
+        - FastAPI
+        - LangChain
+        - ChatGPT, Google Gemini, Llama, etc.
+        - ☕ Coffee
+        """)

apps/streamlit_ui/page_versions/profile/v1.py

@@ -0,0 +1,20 @@
+"""Legacy v1 profile page components for Streamlit UI."""
+
+import streamlit as st
+
+
+def render():
+    """Renders the V1 view of the Profile page (JSON Viewer)."""
+
+    st.markdown("### V1: Simple JSON Viewer")
+    st.info(
+        "This view displays the raw JSON of the loaded user profile. It is not editable."
+    )
+
+    profile = st.session_state.get("user_profile")
+
+    if profile is not None:
+        # Display the profile using st.json for clarity and robustness
+        st.json(profile.model_dump_json())
+    else:
+        st.warning("No user profile loaded. Please create or upload one.")

apps/streamlit_ui/page_versions/profile/v2.py

@@ -0,0 +1,246 @@
+"""V2 profile page with editable form for Streamlit UI."""
+
+import pandas as pd
+import streamlit as st
+
+from sentinel.models import (
+    ClinicalObservation,
+    Demographics,
+    FamilyMemberCancer,
+    FemaleSpecific,
+    Lifestyle,
+    PersonalMedicalHistory,
+    UserInput,
+)
+from sentinel.risk_models import RISK_MODELS
+
+
+def render():
+    """Renders the V2 view of the Profile page (Editable Form)."""
+
+    st.markdown("### V2: Editable Profile Form")
+    st.info(
+        "This view populates an editable form with the loaded profile data, allowing you to make and save changes."
+    )
+
+    profile = st.session_state.get("user_profile")
+
+    if profile is None:
+        st.warning("No user profile loaded. Please create or upload one.")
+        return
+
+    with st.container(border=True):
+        # This selectbox stays outside the form but inside the container.
+        sex_options = ["Female", "Male", "Other"]
+        try:
+            current_sex_index = sex_options.index(profile.demographics.sex)
+        except ValueError:
+            current_sex_index = 0
+
+        sex = st.selectbox(
+            "Biological Sex",
+            options=sex_options,
+            index=current_sex_index,
+            key="edit_profile_sex",
+            help="Changing this will dynamically show or hide sex-specific fields in the form below.",
+        )
+
+        # The form starts here and should contain all the fields and the submit button.
+        with st.form(key="edit_profile_form"):
+            st.subheader("Demographics")
+            age = st.number_input(
+                "Age", min_value=0, step=1, value=profile.demographics.age
+            )
+            ethnicity = st.text_input(
+                "Ethnicity", value=profile.demographics.ethnicity or ""
+            )
+
+            st.subheader("Lifestyle")
+            smoking_options = ["never", "former", "current"]
+            try:
+                smoking_index = smoking_options.index(profile.lifestyle.smoking_status)
+            except ValueError:
+                st.warning(
+                    f"Invalid 'smoking_status' ('{profile.lifestyle.smoking_status}') in file. Defaulting to '{smoking_options[0]}'."
+                )
+                smoking_index = 0
+            smoking_status = st.selectbox(
+                "Smoking Status", smoking_options, index=smoking_index
+            )
+            smoking_pack_years = st.number_input(
+                "Pack-Years",
+                min_value=0,
+                step=1,
+                value=profile.lifestyle.smoking_pack_years or 0,
+            )
+            alcohol_options = ["none", "light", "moderate", "heavy"]
+            try:
+                alcohol_index = alcohol_options.index(
+                    profile.lifestyle.alcohol_consumption
+                )
+            except ValueError:
+                st.warning(
+                    f"Invalid 'alcohol_consumption' ('{profile.lifestyle.alcohol_consumption}') in file. Defaulting to '{alcohol_options[0]}'."
+                )
+                alcohol_index = 0
+            alcohol_consumption = st.selectbox(
+                "Alcohol Consumption", alcohol_options, index=alcohol_index
+            )
+            dietary_habits = st.text_area(
+                "Dietary Habits", value=profile.lifestyle.dietary_habits or ""
+            )
+            physical_activity_level = st.text_area(
+                "Physical Activity",
+                value=profile.lifestyle.physical_activity_level or "",
+            )
+
+            st.subheader("Personal Medical History")
+            known_genetic_mutations = st.text_input(
+                "Known Genetic Mutations (comma-separated)",
+                value=", ".join(
+                    profile.personal_medical_history.known_genetic_mutations
+                ),
+            )
+            previous_cancers = st.text_input(
+                "Previous Cancers (comma-separated)",
+                value=", ".join(profile.personal_medical_history.previous_cancers),
+            )
+            chronic_illnesses = st.text_input(
+                "Chronic Illnesses (comma-separated)",
+                value=", ".join(profile.personal_medical_history.chronic_illnesses),
+            )
+
+            st.subheader("Family History")
+            fam_cols = ["relative", "cancer_type", "age_at_diagnosis"]
+            fam_history_data = [m.model_dump() for m in profile.family_history]
+            fam_history_df = (
+                pd.DataFrame(fam_history_data, columns=fam_cols)
+                if fam_history_data
+                else pd.DataFrame(columns=fam_cols)
+            )
+            edited_fam_history = st.data_editor(
+                fam_history_df,
+                num_rows="dynamic",
+                key="edit_family_history_editor",
+                use_container_width=True,
+            )
+
+            st.subheader("Clinical Observations")
+            obs_cols = ["test_name", "value", "unit", "reference_range", "date"]
+            obs_data = [o.model_dump() for o in profile.clinical_observations]
+            obs_df = (
+                pd.DataFrame(obs_data, columns=obs_cols)
+                if obs_data
+                else pd.DataFrame(columns=obs_cols)
+            )
+            edited_obs = st.data_editor(
+                obs_df,
+                num_rows="dynamic",
+                key="edit_clinical_obs_editor",
+                use_container_width=True,
+            )
+
+            female_specific_data = {}
+            if sex == "Female":
+                st.subheader("Female-Specific")
+                fs_profile = profile.female_specific or FemaleSpecific()
+                female_specific_data["age_at_first_period"] = st.number_input(
+                    "Age at First Period",
+                    min_value=0,
+                    step=1,
+                    value=fs_profile.age_at_first_period or 0,
+                )
+                female_specific_data["age_at_menopause"] = st.number_input(
+                    "Age at Menopause",
+                    min_value=0,
+                    step=1,
+                    value=fs_profile.age_at_menopause or 0,
+                )
+                female_specific_data["num_live_births"] = st.number_input(
+                    "Number of Live Births",
+                    min_value=0,
+                    step=1,
+                    value=fs_profile.num_live_births or 0,
+                )
+                female_specific_data["age_at_first_live_birth"] = st.number_input(
+                    "Age at First Live Birth",
+                    min_value=0,
+                    step=1,
+                    value=fs_profile.age_at_first_live_birth or 0,
+                )
+                female_specific_data["hormone_therapy_use"] = st.text_input(
+                    "Hormone Therapy Use", value=fs_profile.hormone_therapy_use or ""
+                )
+
+            current_concerns = st.text_area(
+                "Current Concerns or Symptoms",
+                value=profile.current_concerns_or_symptoms or "",
+            )
+
+            # The submit button MUST be inside the 'with st.form' block.
+            submitted = st.form_submit_button("Save Changes")
+            if submitted:
+                try:
+                    demographics = Demographics(
+                        age=int(age), sex=sex, ethnicity=ethnicity or None
+                    )
+                    lifestyle = Lifestyle(
+                        smoking_status=smoking_status,
+                        smoking_pack_years=int(smoking_pack_years) or None,
+                        alcohol_consumption=alcohol_consumption,
+                        dietary_habits=dietary_habits or None,
+                        physical_activity_level=physical_activity_level or None,
+                    )
+                    pmh = PersonalMedicalHistory(
+                        known_genetic_mutations=[
+                            m.strip()
+                            for m in known_genetic_mutations.split(",")
+                            if m.strip()
+                        ],
+                        previous_cancers=[
+                            c.strip() for c in previous_cancers.split(",") if c.strip()
+                        ],
+                        chronic_illnesses=[
+                            i.strip() for i in chronic_illnesses.split(",") if i.strip()
+                        ],
+                    )
+                    family_history = [
+                        FamilyMemberCancer(**row.to_dict())
+                        for _, row in edited_fam_history.dropna(how="all").iterrows()
+                    ]
+                    observations = [
+                        ClinicalObservation(**row.to_dict())
+                        for _, row in edited_obs.dropna(how="all").iterrows()
+                    ]
+
+                    female_specific = None
+                    if sex == "Female":
+                        if any(female_specific_data.values()):
+                            female_specific = FemaleSpecific(**female_specific_data)
+
+                    updated_profile = UserInput(
+                        demographics=demographics,
+                        lifestyle=lifestyle,
+                        family_history=family_history,
+                        personal_medical_history=pmh,
+                        female_specific=female_specific,
+                        current_concerns_or_symptoms=current_concerns or None,
+                        clinical_observations=observations,
+                    )
+
+                    with st.spinner("Calculating risk scores..."):
+                        risks_scores = []
+                        for model in RISK_MODELS:
+                            risk_score = model().run(updated_profile)
+                            risks_scores.append(risk_score)
+
+                        # Attach the scores to the object before saving
+                        updated_profile.risks_scores = risks_scores
+
+                    # Now save the fully updated object to the session state
+                    st.session_state.user_profile = updated_profile
+                    st.success("Profile updated and risk scores calculated!")
+                    st.rerun()
+
+                except Exception as e:
+                    st.error(f"Error updating profile: {e}")

apps/streamlit_ui/pages/1_Profile.py

@@ -0,0 +1,266 @@
+"""User profile management page."""
+
+import sys
+from pathlib import Path
+
+# Add the project root to the Python path
+# This is necessary for Streamlit to find modules in the 'apps' directory
+project_root = Path(__file__).resolve().parents[3]
+if str(project_root) not in sys.path:
+    sys.path.append(str(project_root))
+
+import pandas as pd
+import streamlit as st
+
+from apps.streamlit_ui.page_versions.profile import v1, v2
+from sentinel.models import (
+    ClinicalObservation,
+    Demographics,
+    FamilyMemberCancer,
+    FemaleSpecific,
+    Lifestyle,
+    PersonalMedicalHistory,
+    UserInput,
+)
+from sentinel.utils import load_user_file
+
+
+# --- Helper Functions ---
+def clear_profile_state():
+    """Callback function to reset profile-related session state."""
+    st.session_state.user_profile = None
+    if "profile_upload" in st.session_state:
+        del st.session_state["profile_upload"]
+
+
+# --- Main Page Layout ---
+st.title("👤 User Profile")
+
+# --- Sidebar for Version Selection and Upload ---
+with st.sidebar:
+    st.header("Controls")
+
+    # Version selection
+    version_options = ["V2 (Editable Form)", "V1 (JSON Viewer)"]
+    version = st.radio(
+        "Select Demo Version",
+        version_options,
+        help="Choose the version of the profile page to display.",
+    )
+
+    st.divider()
+
+    # Example Profile Selector
+    examples_dir = project_root / "examples"
+
+    # Collect all example profiles
+    profile_files = []
+    if examples_dir.exists():
+        # Get profiles from dev/
+        dev_dir = examples_dir / "dev"
+        if dev_dir.exists():
+            profile_files.extend(sorted(dev_dir.glob("*.yaml")))
+            profile_files.extend(sorted(dev_dir.glob("*.json")))
+
+        # Get profiles from synthetic/
+        synthetic_dir = examples_dir / "synthetic"
+        if synthetic_dir.exists():
+            for subdir in sorted(synthetic_dir.iterdir()):
+                if subdir.is_dir():
+                    profile_files.extend(sorted(subdir.glob("*.yaml")))
+                    profile_files.extend(sorted(subdir.glob("*.json")))
+
+    # Create display names (relative to examples/)
+    profile_options = {}
+    if profile_files:
+        for p in profile_files:
+            rel_path = p.relative_to(examples_dir)
+            profile_options[str(rel_path)] = p
+
+    # Dropdown selector
+    if profile_options:
+        selected = st.selectbox(
+            "Load Example Profile",
+            options=["-- Select a profile --", *profile_options.keys()],
+            key="profile_selector",
+        )
+
+        if selected != "-- Select a profile --":
+            try:
+                profile_path = profile_options[selected]
+                st.session_state.user_profile = load_user_file(str(profile_path))
+                st.success(f"✅ Loaded: {selected}")
+            except Exception as e:
+                st.error(f"Failed to load profile: {e}")
+
+    # Clear Profile Button
+    if st.session_state.get("user_profile"):
+        st.button(
+            "Clear Loaded Profile",
+            on_click=clear_profile_state,
+            use_container_width=True,
+        )
+
+
+# --- Page Content Dispatcher ---
+# Render the selected page version
+if version == "V1 (JSON Viewer)":
+    v1.render()
+else:  # Default to V2
+    v2.render()
+
+# The manual creation form can be a persistent feature at the bottom of the page
+with st.expander("Create New Profile Manually"):
+    # --- STEP 1: Move the sex selector OUTSIDE the form. ---
+    # This allows it to trigger a rerun and update the UI dynamically.
+    # Give it a unique key to avoid conflicts with other widgets.
+    sex = st.selectbox(
+        "Biological Sex", ["Male", "Female", "Other"], key="manual_profile_sex"
+    )
+
+    with st.form("manual_profile_form"):
+        st.subheader("Demographics")
+        age = st.number_input("Age", min_value=0, step=1)
+        # The 'sex' variable is now taken from the selector above the form.
+        ethnicity = st.text_input("Ethnicity")
+
+        st.subheader("Lifestyle")
+        smoking_status = st.selectbox("Smoking Status", ["never", "former", "current"])
+        smoking_pack_years = st.number_input("Pack-Years", min_value=0, step=1)
+        alcohol_consumption = st.selectbox(
+            "Alcohol Consumption", ["none", "light", "moderate", "heavy"]
+        )
+        dietary_habits = st.text_area("Dietary Habits")
+        physical_activity_level = st.text_area("Physical Activity")
+
+        st.subheader("Personal Medical History")
+        known_genetic_mutations = st.text_input(
+            "Known Genetic Mutations (comma-separated)"
+        )
+        previous_cancers = st.text_input("Previous Cancers (comma-separated)")
+        chronic_illnesses = st.text_input("Chronic Illnesses (comma-separated)")
+
+        st.subheader("Family History")
+        fam_cols = ["relative", "cancer_type", "age_at_diagnosis"]
+        fam_df = st.data_editor(
+            pd.DataFrame(columns=fam_cols),
+            num_rows="dynamic",
+            key="family_history_editor",
+        )
+
+        st.subheader("Clinical Observations")
+        obs_cols = ["test_name", "value", "unit", "reference_range", "date"]
+        obs_df = st.data_editor(
+            pd.DataFrame(columns=obs_cols),
+            num_rows="dynamic",
+            key="clinical_obs_editor",
+        )
+
+        female_specific_data = {}
+        # --- STEP 2: The conditional check now works correctly. ---
+        # The 'if' statement is evaluated on each rerun when the 'sex' selector changes.
+        if sex == "Female":
+            st.subheader("Female-Specific")
+            female_specific_data["age_at_first_period"] = st.number_input(
+                "Age at First Period", min_value=0, step=1
+            )
+            female_specific_data["age_at_menopause"] = st.number_input(
+                "Age at Menopause", min_value=0, step=1
+            )
+            female_specific_data["num_live_births"] = st.number_input(
+                "Number of Live Births", min_value=0, step=1
+            )
+            female_specific_data["age_at_first_live_birth"] = st.number_input(
+                "Age at First Live Birth", min_value=0, step=1
+            )
+            female_specific_data["hormone_therapy_use"] = st.text_input(
+                "Hormone Therapy Use"
+            )
+
+        current_concerns = st.text_area("Current Concerns or Symptoms")
+
+        submitted = st.form_submit_button("Save New Profile")
+        if submitted:
+            # --- STEP 3: Use the 'sex' variable from the external selector during submission. ---
+            demographics = Demographics(
+                age=int(age), sex=sex, ethnicity=ethnicity or None
+            )
+            lifestyle = Lifestyle(
+                smoking_status=smoking_status,
+                smoking_pack_years=int(smoking_pack_years) or None,
+                alcohol_consumption=alcohol_consumption,
+                dietary_habits=dietary_habits or None,
+                physical_activity_level=physical_activity_level or None,
+            )
+            pmh = PersonalMedicalHistory(
+                known_genetic_mutations=[
+                    m.strip() for m in known_genetic_mutations.split(",") if m.strip()
+                ],
+                previous_cancers=[
+                    c.strip() for c in previous_cancers.split(",") if c.strip()
+                ],
+                chronic_illnesses=[
+                    i.strip() for i in chronic_illnesses.split(",") if i.strip()
+                ],
+            )
+            family_history = []
+            for _, row in fam_df.dropna(how="all").iterrows():
+                if row.get("relative") and row.get("cancer_type"):
+                    family_history.append(
+                        FamilyMemberCancer(
+                            relative=str(row["relative"]),
+                            cancer_type=str(row["cancer_type"]),
+                            age_at_diagnosis=int(row["age_at_diagnosis"])
+                            if row["age_at_diagnosis"] not in ["", None]
+                            else None,
+                        )
+                    )
+
+            observations = []
+            for _, row in obs_df.dropna(how="all").iterrows():
+                if row.get("test_name") and row.get("value") and row.get("unit"):
+                    observations.append(
+                        ClinicalObservation(
+                            test_name=str(row["test_name"]),
+                            value=str(row["value"]),
+                            unit=str(row["unit"]),
+                            reference_range=(
+                                str(row["reference_range"])
+                                if row["reference_range"] not in ["", None]
+                                else None
+                            ),
+                            date=str(row["date"])
+                            if row["date"] not in ["", None]
+                            else None,
+                        )
+                    )
+
+            female_specific = None
+            if sex == "Female":
+                female_specific = FemaleSpecific(**female_specific_data)
+
+            new_profile = UserInput(
+                demographics=demographics,
+                lifestyle=lifestyle,
+                family_history=family_history,
+                personal_medical_history=pmh,
+                female_specific=female_specific,
+                current_concerns_or_symptoms=current_concerns or None,
+                clinical_observations=observations,
+            )
+            st.success("Profile saved")
+
+            # --- STEP 4: Compute the risk scores ---
+            with st.spinner("Calculating risk scores..."):
+                from sentinel.risk_models import RISK_MODELS
+
+                risks_scores = []
+                for model in RISK_MODELS:
+                    risk_score = model().run(new_profile)
+                    risks_scores.append(risk_score)
+
+                new_profile.risks_scores = risks_scores
+
+            st.session_state.user_profile = new_profile
+            st.success("Risk scores calculated!")
+            st.rerun()

apps/streamlit_ui/pages/2_Configuration.py

@@ -0,0 +1,131 @@
+"""Streamlit page: Configuration."""
+
+from pathlib import Path
+
+import streamlit as st
+import yaml
+from ui_utils import initialize_session_state
+
+from sentinel.config import AppConfig, ModelConfig, ResourcePaths
+from sentinel.factory import SentinelFactory
+
+initialize_session_state()
+
+st.title("⚙️ Model Configuration")
+
+# Define base paths relative to project root
+root = Path(__file__).resolve().parents[3]
+model_dir = root / "configs" / "model"
+model_options = sorted([p.stem for p in model_dir.glob("*.yaml")])
+default_model = (
+    "gemini_2.5_pro" if ("gemini_2.5_pro" in model_options) else model_options[0]
+)
+
+# Model selection
+current_model = st.session_state.config.get("model") or default_model
+selected_model = st.selectbox(
+    "Model Config",
+    model_options,
+    index=model_options.index(current_model) if current_model in model_options else 0,
+)
+st.session_state.config["model"] = selected_model
+
+# Cancer modules selection
+cancer_dir = root / "configs" / "knowledge_base" / "cancer_modules"
+cancer_options = sorted([p.stem for p in cancer_dir.glob("*.yaml")])
+selected_cancers = st.multiselect(
+    "Cancer Modules",
+    cancer_options,
+    default=st.session_state.config.get("cancer_modules", cancer_options),
+)
+st.session_state.config["cancer_modules"] = selected_cancers
+
+# Diagnostic protocols selection
+protocol_dir = root / "configs" / "knowledge_base" / "dx_protocols"
+protocol_options = sorted([p.stem for p in protocol_dir.glob("*.yaml")])
+selected_protocols = st.multiselect(
+    "Diagnostic Protocols",
+    protocol_options,
+    default=st.session_state.config.get("dx_protocols", protocol_options),
+)
+st.session_state.config["dx_protocols"] = selected_protocols
+
+
+@st.cache_data(show_spinner=False)
+def generate_prompt_preview(
+    model_config: str, cancer_modules: list, dx_protocols: list, _user_profile=None
+) -> str:
+    """Generate prompt preview using the factory system.
+
+    Args:
+        model_config (str): Name of the Hydra model configuration to load.
+        cancer_modules (list): Cancer module slugs selected by the user.
+        dx_protocols (list): Diagnostic protocol slugs to include.
+        _user_profile: Optional cached profile used when formatting prompts.
+
+    Returns:
+        str: Markdown-formatted prompt or an error message if generation fails.
+    """
+    try:
+        # Load model config to get provider and model name
+        model_config_path = root / "configs" / "model" / f"{model_config}.yaml"
+        with open(model_config_path) as f:
+            model_data = yaml.safe_load(f)
+
+        # Create knowledge base paths
+        knowledge_base_paths = ResourcePaths(
+            persona=root / "prompts" / "persona" / "default.md",
+            instruction_assessment=root / "prompts" / "instruction" / "assessment.md",
+            instruction_conversation=root
+            / "prompts"
+            / "instruction"
+            / "conversation.md",
+            output_format_assessment=root
+            / "configs"
+            / "output_format"
+            / "assessment.yaml",
+            output_format_conversation=root
+            / "configs"
+            / "output_format"
+            / "conversation.yaml",
+            cancer_modules_dir=root / "configs" / "knowledge_base" / "cancer_modules",
+            dx_protocols_dir=root / "configs" / "knowledge_base" / "dx_protocols",
+        )
+
+        # Create app config
+        app_config = AppConfig(
+            model=ModelConfig(
+                provider=model_data["provider"], model_name=model_data["model_name"]
+            ),
+            knowledge_base_paths=knowledge_base_paths,
+            selected_cancer_modules=cancer_modules,
+            selected_dx_protocols=dx_protocols,
+        )
+
+        # Create factory and get prompt builder
+        factory = SentinelFactory(app_config)
+
+        # Generate assessment prompt
+        prompt = factory.prompt_builder.build_assessment_prompt()
+
+        # Format prompt with user data if available
+        user_json = _user_profile.model_dump_json() if _user_profile is not None else ""
+        formatted_prompt = prompt.format(user_data=user_json)
+
+        return formatted_prompt
+
+    except Exception as e:
+        return f"Error generating prompt preview: {e!s}"
+
+
+# Generate prompt preview
+if selected_model:
+    prompt_text = generate_prompt_preview(
+        selected_model,
+        selected_cancers,
+        selected_protocols,
+        st.session_state.user_profile,
+    )
+
+    st.subheader("Prompt Preview")
+    st.text_area("System Prompt", value=prompt_text, height=500, disabled=True)

apps/streamlit_ui/pages/3_Assessment.py

@@ -0,0 +1,249 @@
+"""Streamlit page: Assessment."""
+
+import os
+import tempfile
+from pathlib import Path
+
+import streamlit as st
+import yaml
+
+# Configure page layout to be wider
+st.set_page_config(layout="wide")
+from collections import Counter
+
+import pandas as pd
+import plotly.graph_objects as go
+from ui_utils import initialize_session_state
+
+from sentinel.config import AppConfig, ModelConfig, ResourcePaths
+from sentinel.conversation import ConversationManager
+from sentinel.factory import SentinelFactory
+from sentinel.reporting import generate_excel_report, generate_pdf_report
+
+initialize_session_state()
+
+if st.session_state.user_profile is None:
+    st.warning(
+        "Please complete your profile on the Profile page before running an assessment."
+    )
+    st.stop()
+
+
+def create_conversation_manager(config: dict) -> ConversationManager:
+    """Create a conversation manager from the current configuration.
+
+    Args:
+        config: A dictionary containing the current configuration.
+
+    Returns:
+        ConversationManager: A conversation manager instance.
+    """
+    # Define base paths relative to project root
+    root = Path(__file__).resolve().parents[3]
+
+    # Load model config to get provider and model name
+    model_config_path = root / "configs" / "model" / f"{config['model']}.yaml"
+    with open(model_config_path) as f:
+        model_data = yaml.safe_load(f)
+
+    # Create knowledge base paths
+    knowledge_base_paths = ResourcePaths(
+        persona=root / "prompts" / "persona" / "default.md",
+        instruction_assessment=root / "prompts" / "instruction" / "assessment.md",
+        instruction_conversation=root / "prompts" / "instruction" / "conversation.md",
+        output_format_assessment=root / "configs" / "output_format" / "assessment.yaml",
+        output_format_conversation=root
+        / "configs"
+        / "output_format"
+        / "conversation.yaml",
+        cancer_modules_dir=root / "configs" / "knowledge_base" / "cancer_modules",
+        dx_protocols_dir=root / "configs" / "knowledge_base" / "dx_protocols",
+    )
+
+    # Create app config
+    app_config = AppConfig(
+        model=ModelConfig(
+            provider=model_data["provider"], model_name=model_data["model_name"]
+        ),
+        knowledge_base_paths=knowledge_base_paths,
+        selected_cancer_modules=config.get("cancer_modules", []),
+        selected_dx_protocols=config.get("dx_protocols", []),
+    )
+
+    # Create factory and conversation manager
+    factory = SentinelFactory(app_config)
+    return factory.create_conversation_manager()
+
+
+manager = create_conversation_manager(st.session_state.config)
+st.session_state.conversation_manager = manager
+
+st.title("🔬 Assessment")
+
+if st.button("Run Assessment", type="primary"):
+    with st.spinner("Running..."):
+        result = manager.initial_assessment(st.session_state.user_profile)
+        st.session_state.assessment = result
+
+assessment = st.session_state.get("assessment")
+
+if assessment:
+    # --- 1. PRE-SORT DATA ---
+    sorted_risk_assessments = sorted(
+        assessment.risk_assessments, key=lambda x: x.risk_level or 0, reverse=True
+    )
+    sorted_dx_recommendations = sorted(
+        assessment.dx_recommendations,
+        key=lambda x: x.recommendation_level or 0,
+        reverse=True,
+    )
+
+    # --- 2. ROW 1: OVERALL RISK SCORE ---
+    st.subheader("Overall Risk Score")
+    if assessment.overall_risk_score is not None:
+        fig = go.Figure(
+            go.Indicator(
+                mode="gauge+number",
+                value=assessment.overall_risk_score,
+                title={"text": "Overall Score"},
+                gauge={"axis": {"range": [0, 100]}},
+            )
+        )
+        fig.update_layout(height=300, margin=dict(t=50, b=40, l=40, r=40))
+        st.plotly_chart(fig, use_container_width=True)
+    st.divider()
+
+    # --- 3. ROW 2: RISK & RECOMMENDATION CHARTS ---
+    col1, col2 = st.columns(2)
+    with col1:
+        st.subheader("Cancer Risk Levels")
+        if sorted_risk_assessments:
+            cancers = [ra.cancer_type for ra in sorted_risk_assessments]
+            levels = [ra.risk_level or 0 for ra in sorted_risk_assessments]
+            short_cancers = [c[:28] + "..." if len(c) > 28 else c for c in cancers]
+            fig = go.Figure(
+                go.Bar(
+                    x=levels,
+                    y=short_cancers,
+                    orientation="h",
+                    hovertext=cancers,
+                    hovertemplate="<b>%{hovertext}</b><br>Risk Level: %{x}<extra></extra>",
+                )
+            )
+            fig.update_layout(
+                xaxis=dict(range=[0, 5], title="Risk Level"),
+                yaxis=dict(autorange="reversed"),
+                margin=dict(t=20, b=40, l=40, r=40),
+            )
+            st.plotly_chart(fig, use_container_width=True)
+
+    with col2:
+        st.subheader("Dx Recommendations")
+        if sorted_dx_recommendations:
+            tests = [dx.test_name for dx in sorted_dx_recommendations]
+            recs = [dx.recommendation_level or 0 for dx in sorted_dx_recommendations]
+            short_tests = [t[:28] + "..." if len(t) > 28 else t for t in tests]
+            fig = go.Figure(
+                go.Bar(
+                    x=recs,
+                    y=short_tests,
+                    orientation="h",
+                    hovertext=tests,
+                    hovertemplate="<b>%{hovertext}</b><br>Recommendation: %{x}<extra></extra>",
+                )
+            )
+            fig.update_layout(
+                xaxis=dict(range=[0, 5], title="Recommendation"),
+                yaxis=dict(autorange="reversed"),
+                margin=dict(t=20, b=40, l=40, r=40),
+            )
+            st.plotly_chart(fig, use_container_width=True)
+    st.divider()
+
+    # --- 4. ROW 3: RISK FACTOR VISUALIZATIONS ---
+    if assessment.identified_risk_factors:
+        col3, col4 = st.columns(2)
+        with col3:
+            st.subheader("Risk Factor Summary")
+            categories = [
+                rf.category.value for rf in assessment.identified_risk_factors
+            ]
+            category_counts = Counter(categories)
+            pie_fig = go.Figure(
+                go.Pie(
+                    labels=list(category_counts.keys()),
+                    values=list(category_counts.values()),
+                    hole=0.3,
+                )
+            )
+            pie_fig.update_layout(
+                height=400,
+                margin=dict(t=20, b=40, l=40, r=40),
+                legend=dict(
+                    orientation="v", yanchor="middle", y=0.5, xanchor="left", x=1.05
+                ),
+            )
+            st.plotly_chart(pie_fig, use_container_width=True)
+
+        with col4:
+            st.subheader("Identified Risk Factors")
+            risk_factor_data = [
+                {"Category": rf.category.value, "Description": rf.description}
+                for rf in assessment.identified_risk_factors
+            ]
+            rf_df = pd.DataFrame(risk_factor_data)
+            st.dataframe(rf_df, use_container_width=True, height=400, hide_index=True)
+
+    # --- 5. EXPANDERS (using sorted data) ---
+    with st.expander("Overall Summary"):
+        st.markdown(assessment.overall_summary, unsafe_allow_html=True)
+
+    with st.expander("Risk Assessments"):
+        for ra in sorted_risk_assessments:
+            st.markdown(f"**{ra.cancer_type}** - {ra.risk_level or 'N/A'}/5")
+            st.write(ra.explanation)
+            if ra.recommended_steps:
+                st.write("**Recommended Steps:**")
+                steps = ra.recommended_steps
+                if isinstance(steps, list):
+                    for step in steps:
+                        st.write(f"- {step}")
+                else:
+                    st.write(f"- {steps}")
+            if ra.lifestyle_advice:
+                st.write(f"*{ra.lifestyle_advice}*")
+            st.divider()
+
+    with st.expander("Dx Recommendations"):
+        for dx in sorted_dx_recommendations:
+            st.markdown(f"**{dx.test_name}** - {dx.recommendation_level or 'N/A'}/5")
+            if dx.frequency:
+                st.write(f"Frequency: {dx.frequency}")
+            st.write(dx.rationale)
+            if dx.applicable_guideline:
+                st.write(f"Guideline: {dx.applicable_guideline}")
+            st.divider()
+
+    # --- 6. EXISTING DOWNLOAD AND CHAT LOGIC ---
+    with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as f:
+        generate_pdf_report(assessment, st.session_state.user_profile, f.name)
+        f.seek(0)
+        pdf_data = f.read()
+    st.download_button("Download PDF", pdf_data, file_name="assessment.pdf")
+    os.unlink(f.name)
+
+    with tempfile.NamedTemporaryFile(suffix=".xlsx", delete=False) as f:
+        generate_excel_report(assessment, st.session_state.user_profile, f.name)
+        f.seek(0)
+        xls_data = f.read()
+    st.download_button("Download Excel", xls_data, file_name="assessment.xlsx")
+
+    # for q, a in manager.history:
+    #     st.chat_message("user").write(q)
+    #     st.chat_message("assistant").write(a)
+
+    if question := st.chat_input("Ask a follow-up question"):
+        with st.spinner("Thinking..."):
+            resp = manager.follow_up(question)
+        st.chat_message("user").write(question)
+        st.chat_message("assistant").write(resp.response)

apps/streamlit_ui/pages/4_Risk_Scores.py

@@ -0,0 +1,62 @@
+"""Streamlit page: Risk Scores."""
+
+import streamlit as st
+
+st.set_page_config(page_title="Risk Scores", page_icon="🧮")
+
+st.title("🧮 Calculated Risk Scores")
+
+profile = st.session_state.get("user_profile")
+
+if profile is None:
+    st.info(
+        "⬅️ Please load or create a user profile on the 'Profile' page to view the calculated scores."
+    )
+    st.stop()
+
+if not profile.risks_scores:
+    st.warning("Risk scores have not been calculated for the current profile yet.")
+    st.info(
+        "⬅️ Please go to the 'Profile' page and click the 'Save' button to trigger the calculation."
+    )
+    st.stop()
+
+st.header("Applicable Risk Scores")
+st.caption(
+    "The following risk scores were applicable to the provided user profile. Models that were not applicable are not shown."
+)
+
+# Filter out scores where the score string contains "N/A".
+applicable_scores = [
+    s for s in profile.risks_scores if s is not None and "N/A" not in s.score
+]
+
+if not applicable_scores:
+    st.success("✅ No major risk models were applicable or triggered for this profile.")
+    st.stop()
+
+# Loop through and display only the applicable scores
+for score in applicable_scores:
+    model_name = score.name.replace("_", " ").title()
+    if score.cancer_type:
+        cancer_type = score.cancer_type.replace("_", " ").title()
+        title = f"{model_name} ({cancer_type} Risk)"
+    else:
+        title = model_name
+
+    with st.expander(title, expanded=True):
+        col1, col2 = st.columns(2)
+        with col1:
+            st.metric(label="Risk Score", value=f"{score.score}")
+
+        if score.interpretation:
+            st.markdown("**Interpretation:**")
+            st.info(score.interpretation)
+
+        if score.description:
+            st.markdown(f"**Model Description:** {score.description}")
+
+        if score.references:
+            st.markdown("**References:**")
+            for ref in score.references:
+                st.write(f"- {ref}")

apps/streamlit_ui/ui_utils.py

@@ -0,0 +1,41 @@
+"""Utilities for Streamlit UI components and helpers."""
+
+from pathlib import Path
+
+import streamlit as st
+
+
+def initialize_session_state() -> None:
+    """Initialize Streamlit session state with default values."""
+    if "user_profile" not in st.session_state:
+        st.session_state.user_profile = None
+    if "config" not in st.session_state:
+        # Load all available options as defaults
+        root = Path(__file__).resolve().parents[2]  # Go up to project root
+
+        cancer_dir = root / "configs" / "knowledge_base" / "cancer_modules"
+        all_cancer_modules = sorted([p.stem for p in cancer_dir.glob("*.yaml")])
+
+        protocol_dir = root / "configs" / "knowledge_base" / "dx_protocols"
+        all_dx_protocols = sorted([p.stem for p in protocol_dir.glob("*.yaml")])
+
+        model_dir = root / "configs" / "model"
+        model_options = sorted([p.stem for p in model_dir.glob("*.yaml")])
+        if model_options:
+            default_model = (
+                "gemini_2.5_pro"
+                if ("gemini_2.5_pro" in model_options)
+                else model_options[0]
+            )
+        else:
+            default_model = None
+
+        st.session_state.config = {
+            "model": default_model,
+            "cancer_modules": all_cancer_modules,
+            "dx_protocols": all_dx_protocols,
+        }
+    if "assessment" not in st.session_state:
+        st.session_state.assessment = None
+    if "conversation_manager" not in st.session_state:
+        st.session_state.conversation_manager = None

configs/config.yaml

@@ -0,0 +1,14 @@
+defaults:
+  - model: gemma3_4b
+  - _self_
+
+user_file: null
+dev_mode: false
+
+knowledge_base:
+  # Cancer modules removed - risk models handle this logic directly
+  cancer_modules: []
+
+  dx_protocols:
+    # Keep one protocol as reference template for future additions
+    - mammography_screening

configs/knowledge_base/dx_protocols/mammography_screening.yaml

@@ -0,0 +1,46 @@
+key: mammography_screening
+name: "Mammogram for Breast Cancer Screening"
+description: "A mammogram is a low-dose X-ray of the breast used to find early signs of cancer, often before they can be seen or felt as a lump. Finding breast cancer early greatly increases the chances of successful treatment."
+typical_frequency: "Every 1 to 2 years for women of screening age, depending on specific guidelines and risk factors."
+additional_information: |
+  #### CORE GUIDANCE FOR AVERAGE-RISK INDIVIDUALS
+  This information is for individuals at average risk of breast cancer. You are generally considered average risk if you do not have a personal history of breast cancer, a known high-risk genetic mutation like BRCA1/2, or a history of radiation therapy to the chest at a young age.
+
+  ##### Guideline Nuances:
+  It's important to know that different expert groups have slightly different recommendations. This can be confusing, but it reflects that they weigh the benefits and harms of screening differently.
+  - **U.S. Preventive Services Task Force (USPSTF):** Recommends a mammogram every 2 years for women ages 40 to 74.
+  - **American Cancer Society (ACS):** Recommends women ages 40-44 have the option to start yearly mammograms. It recommends yearly mammograms for women 45-54. At age 55, women can switch to every 2 years or continue yearly screening.
+  - **NHS (UK):** Invites women for a mammogram every 3 years between the ages of 50 and 71.
+  This assistant's primary logic is based on the USPSTF guidelines, which recommend starting at age 40. You should discuss with your doctor which schedule is best for you, considering your personal health, values, and local practices.
+
+  #### RISK STRATIFICATION: IDENTIFYING HIGH-RISK INDIVIDUALS
+  Certain factors place you at a significantly higher risk for breast cancer and mean you need a different, more intensive screening plan. If any of the following apply to you, the standard recommendations are NOT sufficient. You should speak with your doctor about a referral to a high-risk breast clinic or genetic counselor.
+
+  ##### High-Risk Triggers:
+  - **Known Genetic Mutation:** You or a first-degree relative (parent, sibling, child) have a known mutation in a gene like *BRCA1*, *BRCA2*, *TP53*, *PALB2*, etc..
+  - **Strong Family History:** Even without genetic testing, a strong family history may qualify you for high-risk screening. This can be complex, but often includes having multiple first-degree relatives with breast cancer, or relatives diagnosed at a young age (e.g., before 50).
+  - **Calculated Lifetime Risk:** Risk assessment tools (like the Tyrer-Cuzick or Gail models) estimate your lifetime risk of breast cancer to be 20% or higher.
+  - **History of Chest Radiation:** You received radiation therapy to the chest between the ages of 10 and 30 (e.g., for Hodgkin lymphoma).
+  - **Personal History:** You have a personal history of lobular carcinoma in situ (LCIS), atypical ductal hyperplasia (ADH), or atypical lobular hyperplasia (ALH).
+
+  **If you meet high-risk criteria, guidelines often recommend annual screening with both a breast MRI and a mammogram, typically starting at age 30.**
+
+  #### KEY CONSIDERATIONS & ALTERNATIVE OPTIONS
+
+  ##### Breast Density:
+  Breast density refers to the amount of fibrous and glandular tissue in a breast compared to fatty tissue. Nearly half of all women have dense breasts.
+  - **What it means:** Having dense breasts is common and is a risk factor for breast cancer. It can also make it harder for mammograms to detect cancer, as both dense tissue and tumors can appear white on an X-ray.
+  - **Supplemental Screening:** Because of this, there is ongoing research into whether additional tests, like a breast ultrasound or MRI, could help find cancers missed by mammography in women with dense breasts. Currently, the USPSTF states there is not enough evidence to make a recommendation for or against these extra tests for women at average risk. This is an important topic to discuss with your doctor.
+
+  ##### Alternative Mammography Technology:
+  - **3D Mammography (Digital Breast Tomosynthesis or DBT):** This is an advanced type of mammogram that takes pictures of the breast from multiple angles to create a 3D-like image. Studies show it can find slightly more cancers and reduce the number of "false alarms" (when you are called back for more testing for something that isn't cancer), especially in women with dense breasts. Both 2D and 3D mammography are considered effective screening methods.
+
+  ##### Benefits and Harms of Screening:
+  - **Benefit:** The main benefit of screening is finding cancer early, when it is most treatable and curable.
+  - **Harms:** Screening is not perfect. It can lead to:
+    - **False Positives:** A result that looks like cancer but is not. This leads to anxiety and the need for more tests (like biopsies).
+    - **Overdiagnosis:** Finding and treating cancers that are so slow-growing they would never have caused a problem in a person's lifetime.
+    - **Radiation Exposure:** Mammograms use a very low dose of radiation. The benefit of finding cancer early is widely believed to outweigh this small risk.
+
+  ##### Breast Awareness:
+  Screening tests are important, but they don't find every cancer. It's crucial to be familiar with how your breasts normally look and feel. If you notice any changes—such as a new lump, skin dimpling, nipple changes, or persistent pain—see a doctor right away, even if your last mammogram was normal.

configs/model/chatgpt_o1.yaml

@@ -0,0 +1,2 @@
+provider: openai
+model_name: o1