Dermatolog AI Scan

.devcontainer/devcontainer.json

@@ -0,0 +1,25 @@
+{
+	"name": "Dermatolog AI Scanner Dev",
+	"build": {
+		"context": "..",
+		"dockerfile": "../Dockerfile"
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-python.python",
+				"ms-python.black-formatter",
+				"charliermarsh.ruff",
+				"tamasfe.even-better-toml"
+			]
+		}
+	},
+	"forwardPorts": [
+		8000
+	],
+	"postCreateCommand": "pip install -r requirements-dev.txt && playwright install --with-deps chromium && npm install",
+	"runArgs": [
+		"--env-file",
+		".env"
+	]
+}

.dockerignore

@@ -0,0 +1,31 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+pip-log.txt
+pip-delete-this-directory.txt
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+.git
+.mypy_cache
+.pytest_cache
+.hypothesize
+
+# Data and Cache
+tmp/
+db/
+cache/
+model_cache/
+
+# Local Config
+.env
+.DS_Store

.env

@@ -0,0 +1,6 @@
+# GCP Project Configuration
+PROJECT_ID=your-project-id
+LOCATION=europe-central2
+
+
+

.gitignore

@@ -0,0 +1,23 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+server.log
+debug*.log
+image_stats.duckdb
+venv/
+db/
+tmp/
+coverage/coverage-final.json
+node_modules/*
+coverage/*
+app/static/js/client/git_push.sh
+app/static/js/client/mocha.opts
+*.DS_Store
+gcp_key.json
+verify*.py
+test_*.log
+*.out
+.env
+*.db
+yolov8n.pt

.nvmrc

@@ -0,0 +1 @@
+18

DEPLOY.md

@@ -0,0 +1,144 @@
+# 📦 Deployment Guide
+
+This application is fully containerized and can be deployed to Google Cloud Run, AWS, or any Kubernetes cluster.
+
+## Minimum Requirements
+
+- **RAM**: 4 GB (8 GB Recommended for MedSigLIP model)
+- **CPU**: 2 vCPU
+- **Dependencies**: Docker (for building the image)
+
+---
+
+## 🚀 Google Cloud Run
+
+We provide a helper script to deploy with the correct hardware configuration.
+
+1.  **Authenticate**:
+    ```bash
+    gcloud auth login
+    gcloud config set project YOUR_PROJECT_ID
+    ```
+
+    2.  **Export HF_TOKEN (Crucial)**:
+        For the build to succeed (downloading gated model), you must export your token:
+        ```bash
+        export HF_TOKEN=your_hf_token
+        ```
+
+    3.  **Run Deployment Script**:
+        ```bash
+        chmod +x bin/deploy.sh
+        ./bin/deploy.sh
+        ```
+
+    This script will:
+    - Build the container image.
+    - Deploy to Cloud Run with **8GB RAM** and **2 vCPUs**.
+    - Configure the fallback to public models if no gated token is provided.
+
+4.  **Access**:
+    The script will output the public URL of your application.
+
+### 🔧 Cloud Build Configuration (`cloudbuild.yaml`)
+
+The project includes a `cloudbuild.yaml` file, which is used by Google Cloud Build to execute the container build process. 
+
+**Why is it needed?**
+The standard `gcloud builds submit` command does not support passing build arguments (like `HF_TOKEN`) directly to the Dockerfile easily. The `cloudbuild.yaml` file explicitly defines the build steps to include the `--build-arg` flag, ensuring the gated MedSigLIP model can be downloaded securely during the build.
+
+**Manual Usage:**
+If you need to trigger a build manually without `bin/deploy.sh`:
+```bash
+gcloud builds submit --config cloudbuild.yaml \
+  --substitutions=_HF_TOKEN="$HF_TOKEN",_SERVICE_NAME="dermatolog-ai-scan" .
+```
+
+
+## AWS (Amazon Web Services)
+
+You can deploy using **AWS App Runner** (easiest) or **Amazon ECS**.
+
+1.  **Build and Push Image**:
+    Creating an ECR repository and pushing your image:
+    ```bash
+    aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com
+    
+    docker build -t dermatolog-ai-scan .
+    docker tag dermatolog-ai-scan:latest YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/dermatolog-ai-scan:latest
+    docker push YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/dermatolog-ai-scan:latest
+    ```
+
+2.  **Deploy via App Runner**:
+    - Select **Container Registry** in App Runner.
+    - Choose the pushed image.
+    - **Configuration**:
+        - **CPU**: 2 vCPU
+        - **Memory**: 4 GB (Minimum) or higher.
+        - **Port**: 8000
+        - **Environment Variables**: Add `HF_TOKEN` if you have one.
+
+---
+
+## ☸️ Kubernetes (K8s)
+
+Deploy to any Kubernetes formatted cluster (EKS, GKE, K3s, Minikube).
+
+**1. Create Deployment (`k8s-deployment.yaml`)**:
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: dermatolog-ai
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: dermatolog-ai
+  template:
+    metadata:
+      labels:
+        app: dermatolog-ai
+    spec:
+      containers:
+      - name: dermatolog-ai
+        image: your-registry/dermatolog-ai-scan:latest
+        resources:
+          requests:
+            memory: "4Gi"
+            cpu: "1000m"
+          limits:
+            memory: "8Gi"
+            cpu: "2000m"
+        ports:
+        - containerPort: 8000
+        env:
+        # Optional: Add HF_TOKEN secret if using gated models
+        # - name: HF_TOKEN
+        #   valueFrom:
+        #     secretKeyRef:
+        #       name: hf-secret
+        #       key: token
+```
+
+**2. Expose Service (`k8s-service.yaml`)**:
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: dermatolog-ai-service
+spec:
+  type: LoadBalancer
+  selector:
+    app: dermatolog-ai
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 8000
+```
+
+**3. Apply Configuration**:
+```bash
+kubectl apply -f k8s-deployment.yaml
+kubectl apply -f k8s-service.yaml
+```

Dockerfile

@@ -0,0 +1,43 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    wget \
+    build-essential \
+    libgl1 \
+    libglib2.0-0 \
+    && curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Pre-download the model to bake it into the image
+# This prevents downloading 4GB+ on every container start
+ARG HF_TOKEN
+ENV HF_TOKEN=${HF_TOKEN}
+
+RUN python -c "from transformers import AutoProcessor, AutoModel; \
+    import os; \
+    token = os.environ.get('HF_TOKEN'); \
+    print(f'Downloading MedSigLIP model with token present: {bool(token)}...'); \
+    AutoProcessor.from_pretrained('google/medsiglip-448', token=token); \
+    AutoModel.from_pretrained('google/medsiglip-448', token=token)"
+
+# Pre-download YOLO model
+RUN python -c "from ultralytics import YOLO; YOLO('yolov8n.pt')"
+
+# Copy application code
+COPY . .
+
+# Expose port (Cloud Run defaults to 8080, providing a fallback)
+ENV PORT=8080
+EXPOSE $PORT
+
+# Command to run (Using Shell form so it evaluates $PORT)
+CMD uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8080}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcin Stepien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,162 @@
+# Dermatolog AI Scan
+
+A privacy-first, free, and easy-to-use dermatology scan app powered by latest AI models.
+
+## Features
+
+- **Local Models**: Direct interface with MedSigLIP model locally or on Cloud Run.
+- **Lesion Detection**: Uses **YOLOv8-Nano** to automatically identify and localise skin lesions for optimized preprocessing.
+- **Session-based Photo Management**: 
+    - **Local-Only Storage**: Images are processed and stored entirely within your browser's memory using DataURLs. No image files are ever written to the server's disk, ensuring maximum patient privacy.
+    - **Drag & Drop Upload**: Upload multiple images easily.
+    - **Clipboard Paste Support**: Paste images directly from your clipboard (Ctrl+V) to preview them instantly.
+    - **Smart Timeline**: Photos are automatically grouped into "Virtual Directories" based on their creation date (extracted from EXIF).
+    - **Privacy**: All data is scoped to your browser session.
+- **Zero-Shot Dermatology Analysis**:
+    - Uses **Google Health's MedSigLIP** (`google/medsiglip-448`) model for localized analysis.
+    - Classifies images against a comprehensive set of **25+ dermatological conditions** relevant to EU medical practices.
+    - **Rationale**: The label set focuses on high-mortality cancers (Melanoma), high-prevalence conditions (Eczema, Acne), and common differential diagnoses to aid in effective triage.
+
+### 📊 Confidence & Interpretation Logic
+
+The application uses specialized logic to convert raw model scores into clinical insights:
+
+- **Cancerous Tumor Consolidation**: If the top-ranked results are malignant tumor diseases 
+    (
+        Melanoma, 
+        Basal Cell Carcinoma, 
+        Squamous Cell Carcinoma,
+        Bowen's Disease
+    )
+    the confidence margin is calculated as the **difference between the sum of these top tumor scores and the first non-tumor result**. This ensures high confidence is reported when the AI is certain of malignancy, even if it is debating the specific tumor subtype.
+- **Predictive Entropy**: The system calculates Shannon Entropy across all predictions. If entropy is high (e.g., above 2.0 bits), the result is flagged as unreliable regardless of the top score.
+- **Interpretation Margin**: For mixed cases (Tumor vs. Non-Tumor), if the margin is below the configurable threshold (default 5%), the application flags the result as "Not clear" to prompt manual review.
+
+### 🩺 Supported Dermatological Conditions
+
+The system is tuned to detect the following conditions based on EU referral guidelines and prevalence statistics:
+
+| Category | Conditions | Rationale |
+| :--- | :--- | :--- |
+| **Malignant / Pre-malignant** | Melanoma, Basal Cell Carcinoma (BCC), Squamous Cell Carcinoma (SCC), Actinic Keratosis, Bowen's Disease, Dysplastic Nevus | Priority for early detection due to mortality risk (Melanoma) or high prevalence impacting healthcare resources (BCC/SCC). |
+| **Inflammatory** | Psoriasis, Atopic Dermatitis (Eczema), Acne Vulgaris, Rosacea, Urticaria, Lichen Planus, Hidradenitis Suppurativa | Represents the highest burden of disease on quality of life in the EU population. |
+| **Infectious** | Fungal Infections (Tinea), Herpes Zoster (Shingles), Impetigo, Warts, Molluscum Contagiosum | Frequent reasons for primary care visits; contagious nature requires accurate identification. |
+| **Benign / Differential** | Melanocytic Nevus, Seborrheic Keratosis, Dermatofibroma, Haemangioma, Epidermoid Cyst, Lipoma | Crucial for distinguishing from malignant lesions to reduce unnecessary anxiety and referrals. |
+| **Other** | Vitiligo, Alopecia Areata, Melasma | Common pigmentary and hair disorders affecting psychological well-being. |
+
+## 🔒 Privacy & Security
+
+Dermatolog AI Scan is built with a **Privacy-First** architecture:
+
+1.  **Browser-Side Image Handling**: When you select an image, it is read by the `FileReader` API and converted to a Base64 DataURL.
+2.  **No Server-Side Persistence**: The backend receives the image data only for the duration of the analysis request. It process the image in-memory and returns the results. No temporary or permanent image files are created on the server's filesystem.
+3.  **Local Memory State**: Image data is pinned to the JavaScript state of your current browser tab. Refreshing the page or closing the tab clears the local image memory.
+4.  **Session Isolation**: Each user is assigned a unique, random session ID to isolate their requests and analysis cache.
+
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- **Docker** and **Docker Compose** installed.
+- **VS Code** with the **Dev Containers** extension.
+- **Node.js** (v18+) and **npm** (for frontend tests).
+
+### 🛠️ Development Setup
+
+The project is designed to be developed inside a **Dev Container**. This ensures a consistent environment with all dependencies pre-installed.
+
+1.  **Clone the Repository**:
+    ```bash
+    git clone <repository-url>
+    cd dermatolog-ai-scan
+    ```
+
+3.  **HuggingFace Configuration**:
+    Access to the MedSigLIP model is gated. You must provide a token in your `.env` file to download/load the model.
+
+
+4.  **Environment Variables (`.env`)**:
+
+    Create a `.env` file in the root directory to store configuration variables. This file is automatically loaded by:
+    - **Docker Compose**: Used to populate `environment:` variables in `docker-compose.yml`.
+    - **Development Container**: To set workspace environment variables.
+    - **Deployment Script**: `bin/deploy.sh` reads `PROJECT_ID` from this file.
+
+   
+    **Template `.env`:**
+    ```ini
+    # GCP Project Configuration (for deployment)
+    PROJECT_ID=your-gcp-project-id
+    LOCATION=us-central1
+
+    # Optional: Temporary File Cleanup (seconds) - Default 86400 (24h)
+    TMP_MAX_AGE_SECONDS=86400
+
+    # Optional: HuggingFace Token for Gated Models (Local MedSigLIP)
+    HF_TOKEN=your_hf_token
+    ```
+
+    **To obtain `HF_TOKEN` for `google/medsiglip-448`:**
+    1.  Create a [Hugging Face account](https://huggingface.co/join).
+    2.  Visit the [google/medsiglip-448 model page](https://huggingface.co/google/medsiglip-448) and check if you need to accept a license agreement (gated access).
+    3.  Go to your [Settings > Access Tokens](https://huggingface.co/settings/tokens) page.
+    4.  Create a new token with **Read** permissions.
+    5.  Copy the token and paste it into your `.env` file as `HF_TOKEN`.
+
+5.  **Start Dev Container**:
+    - Open the folder in VS Code.
+    - When prompted, click **"Reopen in Container"** (or run standard command `Dev Containers: Reopen in Container`).
+    - VS Code will build the container and install all dependencies defined in `requirements-dev.txt` and `package.json`.
+
+    Inside the integrated terminal of VS Code (running in the container):
+    ```bash
+    npm install  # If not run automatically
+    uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+    ```
+    - The API will be available at: http://localhost:8000 (docs at http://localhost:8000/docs/)
+    - Frontend: http://localhost:8000/
+    - **Debug Mode**: Append `?debug` to the URL (e.g., http://localhost:8000/?debug) to reveal detailed model logs, execution timers, saliency maps, and preprocessing calibration settings.
+
+### 🐳 Running with Docker (Manual)
+
+If you prefer to run the container manually (outside VS Code):
+
+**1. Build the Image:**
+You MUST pass your `HF_TOKEN` as a build argument to download the gated model.
+```bash
+# Load token from .env or export it matches your environment
+export HF_TOKEN=your_token_here
+docker build --build-arg HF_TOKEN=$HF_TOKEN -t dermatolog-ai-scan .
+```
+
+**2. Run the Container:**
+Pass the token as an environment variable for runtime checks (optional if baked in, but recommended).
+```bash
+docker run -p 8000:8000 -e HF_TOKEN=$HF_TOKEN dermatolog-ai-scan
+```
+
+### 🧪 Running Tests
+
+We use `pytest` for unit tests and `playwright` for end-to-end tests.
+
+- **Unit Tests**:
+    ```bash
+    pytest tests/unit
+    ```
+
+- **Integration/E2E Tests**:
+    ```bash
+    pytest tests/e2e
+    ```
+
+- **JavaScript Unit Tests**:
+    ```bash
+    npm test
+    ```
+
+### Deployment
+
+The application is containerized and can be deployed to Google Cloud Run, AWS, or Kubernetes.
+
+👉 **See [DEPLOY.md](DEPLOY.md) for full deployment instructions.**

app/config.py

@@ -0,0 +1,44 @@
+"""
+Configuration settings for the Dermatolog AI Scan application.
+Contains model parameters, clinical thresholds, and system constants.
+"""
+
+
+# --- Stage 2: Result Interpretation Parameters ---
+
+# Shannon Entropy threshold (in bits) for determining prediction reliability.
+# Entropy measures the model's "confusion" across all classes.
+# For a 10-class distribution:
+# - Max entropy (complete guessing) is ~3.32 bits.
+# - High confidence (90% in one class) approaches 0 bits.
+# Threshold of 2.5 allows for relative clarity but flags high-chaos distributions.
+INTERPRETER_ENTROPY_THRESHOLD = 2.5
+
+# Margin threshold specifically for Mixed (Tumor vs Non-Tumor) cases.
+# If the top prediction is a tumor but the second is non-tumor (or vice versa),
+# and the absolute difference in their scores is less than this value,
+# the result is annotated as "Not clear".
+INTERPRETER_MARGIN_THRESHOLD = 0.05
+
+# --- Confidence Classification (Margin Based) ---
+
+# Mapping of confidence levels based on the margin between Top-1 and Top-2 results.
+# Used to provide qualitative feedback to the end user.
+CONFIDENCE_CLASSES = [
+    {"min": 0.40, "label": "Confident", "color_hint": "green"},
+    {"min": 0.20, "label": "Plausible", "color_hint": "gray"},
+    {"min": 0.10, "label": "Low confidence", "color_hint": "yellow"},
+    {"min": 0.00, "label": "Results unclear", "color_hint": "red"},
+]
+
+
+# --- Model Configuration ---
+
+# The target image resolution for MedSigLIP. 
+# Changing this requires a compatible model checkpoint.
+MODEL_IMAGE_SIZE = (448, 448)
+
+# The default HuggingFace model path for MedSigLIP.
+MEDSIGLIP_MODEL_NAME = "google/medsiglip-448"
+
+

app/dal/database.py

@@ -0,0 +1,68 @@
+import duckdb
+import os
+import logging
+from contextlib import contextmanager
+
+logger = logging.getLogger(__name__)
+
+class DuckDBManager:
+    def __init__(self, db_path: str = "data/app.duckdb"):
+        self.db_path = db_path
+        # Initialize or migrate schema
+        self._init_schema()
+
+    def _init_schema(self):
+        """Initializes the database schema."""
+        try:
+            with self.get_connection() as con:
+                con.execute("""
+                    CREATE TABLE IF NOT EXISTS interaction_logs (
+                        id INTEGER PRIMARY KEY,
+                        timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                        prompt TEXT,
+                        response TEXT,
+                        latency_ms INTEGER
+                    );
+                    CREATE SEQUENCE IF NOT EXISTS seq_interaction_id START 1;
+                    
+                    CREATE TABLE IF NOT EXISTS photos (
+                        id UUID PRIMARY KEY,
+                        session_id VARCHAR,
+                        filename VARCHAR,
+                        content BLOB,
+                        creation_date DATE,
+                        uploaded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                        md5_hash VARCHAR,
+                        analysis_results VARCHAR,
+                        analysis_date VARCHAR
+                    );
+                    -- Migration for existing tables
+                    ALTER TABLE photos ADD COLUMN IF NOT EXISTS md5_hash VARCHAR;
+                    ALTER TABLE photos ADD COLUMN IF NOT EXISTS analysis_results VARCHAR;
+                    ALTER TABLE photos ADD COLUMN IF NOT EXISTS analysis_date VARCHAR;
+                """)
+                logger.info("Database schema initialized.")
+        except Exception as e:
+            logger.error(f"Failed to init schema: {e}")
+
+    @contextmanager
+    def get_connection(self):
+        """Yields a DuckDB connection."""
+        # DuckDB handles concurrency well, but creating a connection per request is safe for persistence
+        con = duckdb.connect(self.db_path)
+        try:
+            yield con
+        finally:
+            con.close()
+
+    def log_interaction(self, prompt: str, response: str, latency_ms: int):
+        try:
+            with self.get_connection() as con:
+                con.execute("""
+                    INSERT INTO interaction_logs (id, prompt, response, latency_ms)
+                    VALUES (nextval('seq_interaction_id'), ?, ?, ?)
+                """, [prompt, response, latency_ms])
+        except Exception as e:
+            logger.error(f"Failed to log interaction: {e}")
+
+db_manager = DuckDBManager(db_path=os.getenv("DUCKDB_PATH", "data/app.duckdb"))

app/dal/photo_repo.py

@@ -0,0 +1,89 @@
+
+import logging
+from typing import List, Optional, Tuple, Dict
+
+logger = logging.getLogger(__name__)
+
+class PhotoRepository:
+    def __init__(self):
+        # In-memory storage instead of DuckDB
+        # key: session_id, value: { photo_id: metadata_dict }
+        self._storage: Dict[str, Dict[str, dict]] = {}
+
+    def _get_session_store(self, session_id: str) -> Dict[str, dict]:
+        if session_id not in self._storage:
+            self._storage[session_id] = {}
+        return self._storage[session_id]
+
+    def find_duplicate(self, session_id: str, file_hash: str) -> Optional[str]:
+        store = self._get_session_store(session_id)
+        for photo_id, metadata in store.items():
+            if metadata.get("md5_hash") == file_hash:
+                return photo_id
+        return None
+
+    def create_photo(self, photo_id: str, session_id: str, filename: str, ext: str, creation_date: str, file_hash: str, content: bytes):
+        store = self._get_session_store(session_id)
+        store[photo_id] = {
+            "id": photo_id,
+            "filename": filename,
+            "content": content,
+            "creation_date": creation_date,
+            "uploaded_at": str(logging.Formatter().formatTime(logging.LogRecord(None, None, None, None, None, None, None), "%Y-%m-%d %H:%M:%S")),
+            "md5_hash": file_hash,
+            "analysis_results": None,
+            "analysis_date": None
+        }
+
+    def get_timeline_photos(self, session_id: str) -> List[Tuple]:
+        store = self._get_session_store(session_id)
+        results = []
+        # Convert to the tuple format expected by router
+        # (id, filename, creation_date, uploaded_at, analysis_results, analysis_date)
+        for p in store.values():
+            results.append((
+                p["id"],
+                p["filename"],
+                p["creation_date"],
+                p["uploaded_at"],
+                p["analysis_results"],
+                p["analysis_date"]
+            ))
+        # Sort by creation_date DESC, then uploaded_at DESC
+        return sorted(results, key=lambda x: (x[2], x[3]), reverse=True)
+
+    def save_analysis_results(self, photo_id: str, session_id: str, results_json: str):
+        store = self._get_session_store(session_id)
+        if photo_id in store:
+            store[photo_id]["analysis_results"] = results_json
+            store[photo_id]["analysis_date"] = str(logging.Formatter().formatTime(logging.LogRecord(None, None, None, None, None, None, None), "%H:%M:%S"))
+            
+    def get_analysis_results(self, photo_id: str, session_id: str) -> Optional[Tuple[str, str]]:
+        store = self._get_session_store(session_id)
+        p = store.get(photo_id)
+        if p and p["analysis_results"]:
+            return (p["analysis_results"], p["analysis_date"])
+        return None
+
+    def update_date(self, photo_id: str, session_id: str, new_date: str):
+        store = self._get_session_store(session_id)
+        if photo_id in store:
+            store[photo_id]["creation_date"] = new_date
+
+    def get_photo_metadata(self, photo_id: str, session_id: str) -> Optional[Tuple[str, bytes]]:
+        store = self._get_session_store(session_id)
+        p = store.get(photo_id)
+        if p:
+            return (p["filename"], p["content"])
+        return None
+
+    def delete_photo(self, photo_id: str, session_id: str):
+        store = self._get_session_store(session_id)
+        if photo_id in store:
+            del store[photo_id]
+
+    def clear_session(self, session_id: str):
+        if session_id in self._storage:
+            del self._storage[session_id]
+
+photo_repo = PhotoRepository()

app/dermatology_data.py

@@ -0,0 +1,104 @@
+# Comprehensive dermatology labels based on EU prevalence and referral guidelines
+# Rationale:
+# 1. Malignant/Pre-malignant: Detecting high-mortality (Melanoma) and high-prevalence (BCC/SCC) cancers is the priority.
+# 2. Inflammatory: Eczema, Psoriasis, and Acne are the most common burdens on quality of life in EU.
+# 3. Infectious: Fungal and viral infections are frequent reasons for primary care visits.
+# 4. Benign: Essential for differential diagnosis to reduce unnecessary anxiety or referrals.
+
+MEDSIGLIP_DERMATOLOGY_LABELS = {
+    # Malignant & Pre-malignant
+    "Melanoma": "malignant melanoma, asymmetric pigmented lesion with irregular borders and color variegation",
+    "Basal Cell Carcinoma": "basal cell carcinoma, pearly translucent papule with arborizing telangiectasia",
+    "Squamous Cell Carcinoma": "squamous cell carcinoma, indurated hyperkeratotic erythematous nodule or ulcerated plaque",
+    "Actinic Keratosis": "actinic keratosis, rough scaly erythematous macule on sun-damaged skin",
+    "Bowen's Disease": "Bowen's disease, well-demarcated erythematous scaly plaque",
+    "Dysplastic Nevus": "dysplastic nevus, atypical melanocytic lesion with irregular borders and variable pigmentation",
+    
+    # Benign Tumors (Differential Diagnosis)
+    "Melanocytic Nevus": "benign melanocytic nevus, well-circumscribed symmetrical pigmented macule",
+    "Seborrheic Keratosis": "seborrheic keratosis, sharply demarcated verrucous plaque with stuck-on appearance",
+    "Dermatofibroma": "dermatofibroma, firm hyperpigmented dermal nodule with positive dimple sign",
+    "Haemangioma": "hemangioma, benign vascular anomaly, bright red or violaceous nodule",
+    "Epidermoid Cyst": "epidermoid cyst, subcutaneous skin-colored nodule with central punctum",
+    
+    # Inflammatory Conditions
+    "Psoriasis": "psoriasis vulgaris, well-demarcated erythematous plaques with thick silvery-white scale",
+    "Atopic Dermatitis": "atopic dermatitis, pruritic erythematous scaling patches with lichenification",
+    "Acne Vulgaris": "acne vulgaris, inflammatory eruption with comedones, papules, and pustules",
+    "Rosacea": "rosacea, facial erythema and telangiectasia with inflammatory papules",
+    "Urticaria": "urticaria, transient circumscribed erythematous and edematous wheals",
+    "Lichen Planus": "lichen planus, pruritic purple polygonal planar papules with Wickham striae",
+    "Hidradenitis Suppurativa": "hidradenitis suppurativa, painful deep-seated inflammatory nodules and abscesses",
+    
+    # Infectious
+    "Fungal Infection": "tinea fungal infection, an annular, scaling, erythematous patch with raised borders and central clearing",
+    "Herpes Zoster": "herpes zoster, a unilateral, dermatomal eruption of grouped, painful vesicles on an erythematous base",
+    "Impetigo": "impetigo, superficial bacterial infection with erosions and classic honey-colored crusting",
+    "Warts": "verruca vulgaris, a viral infection presenting as a hyperkeratotic, exophytic papule",
+    "Molluscum Contagiosum": "molluscum contagiosum, presenting as firm, dome-shaped, umbilicated, pearly papules",
+    
+    # Pigmentary & Hair
+    "Vitiligo": "vitiligo, depigmented white macules and patches devoid of melanocytes",
+    "Alopecia Areata": "alopecia areata, localized patches of non-scarring hair loss on the scalp or body",
+    "Melasma": "melasma, symmetric, hyperpigmented brown macules primarily on sun-exposed facial areas",
+
+    # Miscellaneous 
+    "Insect Bites": "arthropod bite reaction, intensely pruritic, erythematous papules with a central punctum",
+    "Folliculitis": "folliculitis, inflammation of hair follicles with multiple erythematous papules and pustules",
+    "Drug Rash": "morbilliform drug eruption, a generalized, symmetric, maculopapular erythematous exanthem",
+    
+    # Baseline
+    "Normal Skin": "normal, healthy skin with intact epidermis, uniform texture, and no visible lesions"
+}
+#Inflammatory vs. Neoplastic Differentiation: The model can effectively distinguish 
+# between inflammatory skin conditions and neoplastic (cancerous) 
+## Used for triage analysis
+MEDSIGLIP_DERMATOLOGY_FIRST_CLASSES = {
+    # 1. Inflammatory 
+    "Inflammatory skin disease": "showing inflammatory lesion, or a rash or redness, or scaling",
+    # 2. Neoplastic 
+    #"Neoplastic skin tumor": "neoplastic skin tumor or suspect growth or abnormal mole",
+    "Melanoma": MEDSIGLIP_DERMATOLOGY_LABELS["Melanoma"],
+    # 3. Zero-Shot Baseline
+    "Healthly skin": "melanocytic naevus, pigmented naevus"
+}
+
+CANCEROUS_TUMOR_CLASSES = {
+    "Melanoma", 
+    "Basal Cell Carcinoma",
+    "Squamous Cell Carcinoma",
+    "Bowen's Disease"
+}
+
+BENIGN_TUMOR_CLASSES = {
+    "Melanocytic Nevus",
+    "Seborrheic Keratosis",
+    "Dermatofibroma",
+    "Haemangioma",
+    "Epidermoid Cyst"
+}
+
+# Narrow set of labels focusing on MedSigLIP's highest performance tiers
+MEDSIGLIP_DERMATOLOGY_NARROW_LABELS = {
+    # 1. High-Precision Vascular & Pigmented Lesions
+    "Melanoma": MEDSIGLIP_DERMATOLOGY_LABELS["Melanoma"],
+    "Basal Cell Carcinoma": MEDSIGLIP_DERMATOLOGY_LABELS["Basal Cell Carcinoma"],
+    "Melanocytic Nevus": MEDSIGLIP_DERMATOLOGY_LABELS["Melanocytic Nevus"],
+    "Seborrheic Keratosis": MEDSIGLIP_DERMATOLOGY_LABELS["Seborrheic Keratosis"],
+    
+    # 2. Texture-Heavy Inflammatory Conditions
+    "Psoriasis": MEDSIGLIP_DERMATOLOGY_LABELS["Psoriasis"],
+    "Atopic Dermatitis": MEDSIGLIP_DERMATOLOGY_LABELS["Atopic Dermatitis"],
+    "Acne Vulgaris": MEDSIGLIP_DERMATOLOGY_LABELS["Acne Vulgaris"],
+    "Rosacea": MEDSIGLIP_DERMATOLOGY_LABELS["Rosacea"],
+    
+    # 3. Morphologically Distinct Infections
+    "Herpes Zoster": MEDSIGLIP_DERMATOLOGY_LABELS["Herpes Zoster"],
+    "Warts": MEDSIGLIP_DERMATOLOGY_LABELS["Warts"],
+    "Molluscum Contagiosum": MEDSIGLIP_DERMATOLOGY_LABELS["Molluscum Contagiosum"],
+    
+    # 4. Zero-Shot Baseline
+    "Normal Skin": MEDSIGLIP_DERMATOLOGY_LABELS["Normal Skin"]
+}
+
+

app/main.py

@@ -0,0 +1,68 @@
+import time
+import logging
+import uuid
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from fastapi import FastAPI, HTTPException, Request, Response
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from fastapi.responses import HTMLResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
+
+from app.models import HealthCheckResponse
+from app.routers.photos import router as photos_router
+from app.routers.api import router as api_router
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+app = FastAPI(
+    title="Dermatolog AI Scan",
+    description="FastAPI application for dermatology analysis",
+    version="1.0.0"
+)
+
+# Simple Session Middleware
+class SessionMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        session_id = request.cookies.get("session_id")
+        created_new = False
+        if not session_id:
+            session_id = str(uuid.uuid4())
+            created_new = True
+            # Hack: Inject into request scope so endpoints can see it if they looked there,
+            # but usually they look at cookies. We rely on the client sending it back,
+            # but for the *first* request, we need to handle it.
+            # Ideally endpoints assume cookie exists.
+            # Let's set the cookie on the response.
+
+        # Pass session_id in request state if needed?
+        # request.state.session_id = session_id
+        
+        response = await call_next(request)
+        
+        if created_new:
+            # Set cookie for 1 day
+            response.set_cookie(key="session_id", value=session_id, max_age=86400)
+            
+        return response
+
+app.add_middleware(SessionMiddleware)
+
+app.include_router(photos_router)
+app.include_router(api_router)
+
+# Mount static files
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+app.mount("/static", StaticFiles(directory=os.path.join(BASE_DIR, "static")), name="static")
+templates = Jinja2Templates(directory=os.path.join(BASE_DIR, "templates"))
+
+@app.get("/", response_class=HTMLResponse)
+async def read_root(request: Request):
+    """Serve the main frontend page."""
+    return templates.TemplateResponse("index.html", {"request": request})

app/models.py

@@ -0,0 +1,55 @@
+from pydantic import BaseModel
+from typing import List, Optional
+class HealthCheckResponse(BaseModel):
+    status: str
+    yolo_available: bool
+
+class Photo(BaseModel):
+    id: str
+    filename: str
+    creation_date: str  # ISO date string YYYY-MM-DD
+    uploaded_at: str
+    analysis: Optional[object] = None # Can be List[dict] (legacy) or dict (new with comparison)
+    analysis_date: Optional[str] = None
+    local_content: Optional[str] = None # Base64 data for client-side storage
+
+
+# Response model for the timeline: a list of either Photo (single) or VirtualDirectory (group)
+# In Pydantic V2 we might use Union, but for simplicity/JSON serialization,
+# we can return a list of objects that have a 'type' field.
+
+class TimelineItem(BaseModel):
+    type: str # 'photo' or 'directory'
+    date: str
+    data: Optional[Photo] = None # If type is photo
+    items: Optional[List[Photo]] = None # If type is directory
+
+
+
+from app.config import INTERPRETER_MARGIN_THRESHOLD
+
+class SinglePhotoAnalysisRequest(BaseModel):
+    # Default labels for zero-shot classification from centralized config
+    candidate_labels: Optional[List[str]] = None
+    model: Optional[str] = "medsiglip" # "medsiglip" only now
+    base64_image: Optional[str] = None # Client-side image data
+    margin_threshold: Optional[float] = INTERPRETER_MARGIN_THRESHOLD
+
+class SinglePhotoAnalysisResponse(BaseModel):
+    photo_id: str
+    predictions: List[dict]
+    primary_model_name: Optional[str] = None
+    analysis_date: Optional[str] = None
+    prepared_image_base64: Optional[str] = None
+    saliency_base64: Optional[str] = None # Returning saliency as base64
+    interpretation: Optional[dict] = None
+    preprocess_strategy: Optional[dict] = None
+    execution_times: Optional[dict] = None
+
+class SaliencyRequest(BaseModel):
+    base64_image: str
+    target_label: str
+
+class SaliencyResponse(BaseModel):
+    photo_id: str
+    saliency_base64: str

app/photos.py

@@ -0,0 +1,334 @@
+import uuid
+import base64
+import logging
+import io
+import json
+import os
+from datetime import datetime, date
+from typing import List, Optional
+from fastapi import APIRouter, UploadFile, File, Form, HTTPException, Cookie, Response, Request
+from fastapi.responses import JSONResponse
+from PIL import Image, ExifTags
+
+
+from app.models import TimelineItem, Photo, VirtualDirectory, SinglePhotoAnalysisRequest, SinglePhotoAnalysisResponse
+from app.services.medsiglip_service import medsiglip_service
+from app.dal.photo_repo import photo_repo
+from app.dermatology_data import EU_DERMATOLOGY_LABELS
+
+router = APIRouter(prefix="/api/photos", tags=["photos"])
+
+logger = logging.getLogger(__name__)
+
+def get_date_from_image(image_bytes: bytes) -> str:
+    """Heuristic to find creation date from EXIF or return today."""
+    try:
+        image = Image.open(io.BytesIO(image_bytes))
+        exif = image._getexif()
+        if exif:
+            # 36867 is DateTimeOriginal, 306 is DateTime
+            for tag_id in [36867, 306]:
+                if tag_id in exif:
+                    date_str = exif[tag_id]
+                    # Format is usually "YYYY:MM:DD HH:MM:SS"
+                    try:
+                        dt = datetime.strptime(date_str, "%Y:%m:%d %H:%M:%S")
+                        return dt.date().isoformat()
+                    except ValueError:
+                        continue
+    except Exception as e:
+        logger.warning(f"Failed to extract EXIF: {e}")
+    
+    # Fallback to today
+    return date.today().isoformat()
+
+import hashlib
+
+@router.post("/upload")
+async def upload_photos(
+    request: Request,
+    files: List[UploadFile] = File(...),
+):
+    session_id = request.cookies.get("session_id")
+    if not session_id:
+        raise HTTPException(status_code=400, detail="No session found - reload page")
+
+    processed_ids = []
+    skipped_count = 0
+    
+    try:
+        for file in files:
+            content = await file.read()
+            
+            # Calculate MD5 hash
+            file_hash = hashlib.md5(content).hexdigest()
+            
+            # Check for duplicate in this session
+            existing_id = photo_repo.find_duplicate(session_id, file_hash)
+            
+            if existing_id:
+                skipped_count += 1
+                continue
+
+            # Heuristic Date Extraction
+            creation_date = get_date_from_image(content)
+            
+            photo_id = str(uuid.uuid4())
+            
+            # Save to filesystem
+            session_dir = os.path.join("img", session_id)
+            os.makedirs(session_dir, exist_ok=True)
+            
+            # Use original extension or default to .jpg
+            ext = os.path.splitext(file.filename)[1]
+            if not ext:
+                ext = ".jpg"
+            
+            file_path = os.path.join(session_dir, f"{photo_id}{ext}")
+            with open(file_path, "wb") as f:
+                f.write(content)
+
+            # Save metadata to DB via Repo
+            photo_repo.create_photo(photo_id, session_id, file.filename, ext, creation_date, file_hash)
+            
+            processed_ids.append(photo_id)
+                
+        return {
+            "uploaded": len(processed_ids), 
+            "skipped": skipped_count,
+            "ids": processed_ids,
+            "message": f"Uploaded {len(processed_ids)} photos, skipped {skipped_count} duplicates."
+        }
+        
+    except Exception as e:
+        logger.error(f"Upload failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.get("", response_model=List[TimelineItem])
+async def get_timeline(request: Request):
+    session_id = request.cookies.get("session_id")
+    if not session_id:
+        return []
+
+    try:
+        # Fetch from Repo
+        rows = photo_repo.get_timeline_photos(session_id)
+        
+        photos = []
+        for r in rows:
+            analysis_data = None
+            if len(r) > 4 and r[4]:
+                try:
+                    analysis_data = json.loads(r[4])
+                except:
+                    pass
+
+            analysis_date = None
+            if len(r) > 5 and r[5]:
+                analysis_date = r[5]
+
+            photos.append(Photo(
+                id=str(r[0]),
+                filename=r[1],
+                creation_date=r[2],
+                uploaded_at=r[3],
+                analysis=analysis_data,
+                analysis_date=analysis_date
+            ))
+                
+        # Grouping Logic: ALWAYS group by date (directory mode)
+        timeline = []
+        if not photos:
+            return timeline
+
+        current_group = []
+        current_date = None
+
+        for p in photos:
+            if p.creation_date != current_date:
+                # Flush previous group
+                if current_group:
+                    timeline.append(TimelineItem(
+                        type="directory",
+                        date=current_date,
+                        items=current_group
+                    ))
+                # Start new group
+                current_group = [p]
+                current_date = p.creation_date
+            else:
+                current_group.append(p)
+        
+        # Flush last group
+        if current_group:
+            timeline.append(TimelineItem(
+                type="directory",
+                date=current_date,
+                items=current_group
+            ))
+            
+        logger.info(f"Timeline fetched: {len(timeline)} groups for session {session_id}")
+        return timeline
+
+    except Exception as e:
+        logger.error(f"Timeline fetch failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+def _append_group(timeline: List[TimelineItem], group: List[Photo], date_str: str):
+    if len(group) == 1:
+        # Single photo item
+        timeline.append(TimelineItem(
+            type="photo",
+            date=date_str,
+            data=group[0]
+        ))
+    else:
+        # Virtual Directory
+        timeline.append(TimelineItem(
+            type="directory",
+            date=date_str,
+            items=group
+        ))
+
+@router.patch("/{photo_id}/date")
+async def patch_photo_date(photo_id: str, request: Request, payload: dict):
+    # payload: {"date": "2023-01-01"}
+    session_id = request.cookies.get("session_id")
+    new_date = payload.get("date")
+    
+    if not new_date:
+        raise HTTPException(status_code=400, detail="Date required")
+
+    try:
+        photo_repo.update_date(photo_id, session_id, new_date)
+        return {"status": "updated"}
+    except Exception as e:
+        logger.error(f"Update failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.get("/{photo_id}/content")
+async def get_photo_content(photo_id: str, request: Request):
+    session_id = request.cookies.get("session_id")
+    try:
+        result = photo_repo.get_photo_metadata(photo_id, session_id)
+        if not result:
+            raise HTTPException(status_code=404, detail="Photo not found")
+        
+        original_filename = result[0]
+        stored_content = result[1]
+        
+        try:
+            local_filename = stored_content.decode('utf-8')
+            file_path = os.path.join("img", session_id, local_filename)
+            
+            if os.path.exists(file_path):
+                with open(file_path, "rb") as f:
+                    content = f.read()
+            else:
+                content = stored_content
+        except:
+            content = stored_content
+
+        # Simple mimetype detection or default
+        media_type = "image/jpeg" 
+        if original_filename.lower().endswith(".png"):
+            media_type = "image/png"
+        
+        return Response(content=content, media_type=media_type)
+            
+    except Exception as e:
+        logger.error(f"Content fetch failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/{photo_id}/analyze", response_model=SinglePhotoAnalysisResponse)
+async def analyze_photo(photo_id: str, request: Request, payload: SinglePhotoAnalysisRequest):
+    session_id = request.cookies.get("session_id")
+    if not session_id:
+        raise HTTPException(status_code=400, detail="No session found")
+
+    try:
+        # Check cache first
+        cached = photo_repo.get_analysis_results(photo_id, session_id)
+        if cached:
+            try:
+                 # cached is (json_str, date_str)
+                 preds = json.loads(cached[0])
+                 return SinglePhotoAnalysisResponse(
+                     photo_id=photo_id, 
+                     predictions=preds,
+                     analysis_date=cached[1]
+                 )
+            except Exception:
+                 pass
+
+        # 1. Fetch Photo Content via Repo
+        result = photo_repo.get_photo_metadata(photo_id, session_id)
+        if not result:
+            raise HTTPException(status_code=404, detail="Photo not found")
+        
+        stored_content = result[1]
+        
+        try:
+            local_filename = stored_content.decode('utf-8')
+            file_path = os.path.join("img", session_id, local_filename)
+            if os.path.exists(file_path):
+                with open(file_path, "rb") as f:
+                    content = f.read()
+            else:
+                content = stored_content
+        except:
+            content = stored_content
+
+        # 2. Run Inference
+        labels = payload.candidate_labels
+        if not labels:
+            labels = EU_DERMATOLOGY_LABELS
+
+        predictions = medsiglip_service.get_embeddings(content, texts=labels)
+        
+        # Save results for future use
+        try:
+            photo_repo.save_analysis_results(photo_id, session_id, json.dumps(predictions))
+        except Exception as e:
+            logger.error(f"Failed to save analysis results: {e}")
+        
+        return SinglePhotoAnalysisResponse(
+            photo_id=photo_id,
+            predictions=predictions,
+            analysis_date=datetime.now().isoformat()
+        )
+
+    except Exception as e:
+        logger.error(f"Analysis failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.delete("/{photo_id}")
+async def delete_photo(photo_id: str, request: Request):
+    session_id = request.cookies.get("session_id")
+    if not session_id:
+        raise HTTPException(status_code=400, detail="No session found")
+
+    try:
+        photo_repo.delete_photo(photo_id, session_id)
+        # Ideally delete file too, but keeping it simple for now
+        return {"status": "deleted", "id": photo_id}
+            
+    except Exception as e:
+        logger.error(f"Delete failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.delete("")
+async def clear_session_photos(request: Request):
+    """Deletes all photos associated with the current session ID."""
+    session_id = request.cookies.get("session_id")
+    if not session_id:
+        raise HTTPException(status_code=400, detail="No session found")
+
+    try:
+        photo_repo.clear_session(session_id)
+        # Ideally clean up directory
+        return {"status": "cleared", "message": "All session photos deleted"}
+            
+    except Exception as e:
+        logger.error(f"Clear session failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))

app/routers/api.py

@@ -0,0 +1,17 @@
+from fastapi import APIRouter
+from app.models import HealthCheckResponse
+import os
+
+router = APIRouter(prefix="/api")
+
+from app.services.medsiglip_service import medsiglip_service
+from app.services.yolo_service import yolo_service
+
+@router.get("/health", response_model=HealthCheckResponse)
+async def health_check():
+    """Health check endpoint."""
+    yolo_available = yolo_service.load_model() is not None
+    return HealthCheckResponse(
+        status="OK",
+        yolo_available=yolo_available
+    )

app/routers/photos.py

@@ -0,0 +1,394 @@
+import uuid
+import base64
+import logging
+import io
+import json
+import os
+import time
+from datetime import datetime, date
+from typing import List, Optional
+from fastapi import APIRouter, UploadFile, File, HTTPException, Response, Request
+from PIL import Image
+
+
+from app.models import TimelineItem, Photo, SinglePhotoAnalysisRequest, SinglePhotoAnalysisResponse, SaliencyRequest, SaliencyResponse
+from app.services.medsiglip_service import medsiglip_service
+from app.services.medsiglip_modality_wrapper import (
+    medsiglip_wrapped_service, 
+)
+from app.services.image_preprocess_service import image_preprocess_service, PreprocessStrategy
+from app.services.result_interpreter import result_interpreter
+from app.dal.photo_repo import photo_repo
+
+router = APIRouter(prefix="/api/photos", tags=["photos"])
+
+logger = logging.getLogger(__name__)
+
+def get_date_from_image(image_bytes: bytes) -> str:
+    """Heuristic to find creation date from EXIF or return today."""
+    try:
+        image = Image.open(io.BytesIO(image_bytes))
+        exif = image._getexif()
+        if exif:
+            # 36867 is DateTimeOriginal, 306 is DateTime
+            for tag_id in [36867, 306]:
+                if tag_id in exif:
+                    date_str = exif[tag_id]
+                    # Format is usually "YYYY:MM:DD HH:MM:SS"
+                    try:
+                        dt = datetime.strptime(date_str, "%Y:%m:%d %H:%M:%S")
+                        return dt.date().isoformat()
+                    except ValueError:
+                        continue
+    except Exception as e:
+        logger.warning(f"Failed to extract EXIF: {e}")
+    
+    # Fallback to today
+    return date.today().isoformat()
+
+import hashlib
+
+@router.post("/upload")
+async def upload_photos(
+    request: Request,
+    files: List[UploadFile] = File(...),
+):
+    session_id = request.cookies.get("session_id")
+    if not session_id:
+        raise HTTPException(status_code=400, detail="No session found - reload page")
+
+    processed_ids = []
+    skipped_count = 0
+    
+    try:
+        for file in files:
+            content = await file.read()
+            
+            # Calculate MD5 hash
+            file_hash = hashlib.md5(content).hexdigest()
+            
+            # Check for duplicate in this session
+            existing_id = photo_repo.find_duplicate(session_id, file_hash)
+            
+            if existing_id:
+                skipped_count += 1
+                continue
+
+            # Heuristic Date Extraction
+            creation_date = get_date_from_image(content)
+            
+            photo_id = str(uuid.uuid4())
+            
+            # Use original extension or default to .jpg
+            ext = os.path.splitext(file.filename)[1]
+            if not ext:
+                ext = ".jpg"
+
+            # Save metadata and binary content to Repo
+            photo_repo.create_photo(photo_id, session_id, file.filename, ext, creation_date, file_hash, content)
+            
+            processed_ids.append(photo_id)
+                
+        return {
+            "uploaded": len(processed_ids), 
+            "skipped": skipped_count,
+            "ids": processed_ids,
+            "message": f"Uploaded {len(processed_ids)} photos, skipped {skipped_count} duplicates."
+        }
+        
+    except Exception as e:
+        logger.error(f"Upload failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.get("", response_model=List[TimelineItem])
+async def get_timeline(request: Request):
+    session_id = request.cookies.get("session_id")
+    if not session_id:
+        return []
+
+    try:
+        # Fetch from Repo
+        rows = photo_repo.get_timeline_photos(session_id)
+        
+        photos = []
+        for r in rows:
+            analysis_data = None
+            if len(r) > 4 and r[4]:
+                try:
+                    analysis_data = json.loads(r[4])
+                except:
+                    pass
+
+            analysis_date = None
+            if len(r) > 5 and r[5]:
+                analysis_date = r[5]
+
+            photos.append(Photo(
+                id=str(r[0]),
+                filename=r[1],
+                creation_date=r[2],
+                uploaded_at=r[3],
+                analysis=analysis_data,
+                analysis_date=analysis_date
+            ))
+                
+        # Grouping Logic: ALWAYS group by date (directory mode)
+        timeline = []
+        if not photos:
+            return timeline
+
+        current_group = []
+        current_date = None
+
+        for p in photos:
+            if p.creation_date != current_date:
+                # Flush previous group
+                if current_group:
+                    timeline.append(TimelineItem(
+                        type="directory",
+                        date=current_date,
+                        items=current_group
+                    ))
+                # Start new group
+                current_group = [p]
+                current_date = p.creation_date
+            else:
+                current_group.append(p)
+        
+        # Flush last group
+        if current_group:
+            timeline.append(TimelineItem(
+                type="directory",
+                date=current_date,
+                items=current_group
+            ))
+            
+        logger.info(f"Timeline fetched: {len(timeline)} groups for session {session_id}")
+        return timeline
+
+    except Exception as e:
+        logger.error(f"Timeline fetch failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+def _append_group(timeline: List[TimelineItem], group: List[Photo], date_str: str):
+    if len(group) == 1:
+        # Single photo item
+        timeline.append(TimelineItem(
+            type="photo",
+            date=date_str,
+            data=group[0]
+        ))
+    else:
+        # Virtual Directory
+        timeline.append(TimelineItem(
+            type="directory",
+            date=date_str,
+            items=group
+        ))
+
+@router.patch("/{photo_id}/date")
+async def patch_photo_date(photo_id: str, request: Request, payload: dict):
+    # payload: {"date": "2023-01-01"}
+    session_id = request.cookies.get("session_id")
+    new_date = payload.get("date")
+    
+    if not new_date:
+        raise HTTPException(status_code=400, detail="Date required")
+
+    try:
+        photo_repo.update_date(photo_id, session_id, new_date)
+        return {"status": "updated"}
+    except Exception as e:
+        logger.error(f"Update failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.get("/{photo_id}/content")
+async def get_photo_content(photo_id: str, request: Request):
+    session_id = request.cookies.get("session_id")
+    try:
+        result = photo_repo.get_photo_metadata(photo_id, session_id)
+        if not result:
+            raise HTTPException(status_code=404, detail="Photo not found")
+        
+        original_filename = result[0]
+        stored_content = result[1]
+        
+        content = stored_content
+
+        # Simple mimetype detection or default
+        media_type = "image/jpeg" 
+        if original_filename.lower().endswith(".png"):
+            media_type = "image/png"
+        
+        return Response(content=content, media_type=media_type)
+            
+    except Exception as e:
+        logger.error(f"Content fetch failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/{photo_id}/analyze", response_model=SinglePhotoAnalysisResponse)
+async def analyze_photo(photo_id: str, request: Request, payload: SinglePhotoAnalysisRequest):
+    session_id = request.cookies.get("session_id")
+    if not session_id:
+        raise HTTPException(status_code=400, detail="No session found")
+
+    try:
+        # 1. Get Photo Content (Prioritize payload for local-only storage)
+        if payload.base64_image:
+            # Decode base64 image
+            if "," in payload.base64_image:
+                _, encoded = payload.base64_image.split(",", 1)
+            else:
+                encoded = payload.base64_image
+            content = base64.b64decode(encoded)
+        else:
+            # Fallback to fetching from Repo (Database/Filesystem)
+            result = photo_repo.get_photo_metadata(photo_id, session_id)
+            if not result:
+                raise HTTPException(status_code=404, detail="Photo not found")
+            
+            stored_content = result[1]
+            content = stored_content
+
+        # 2. Run Inference
+        custom_labels = payload.candidate_labels
+        
+        execution_times = {}
+
+        # Determine Preprocessing Strategy and prepare image
+        start_time = time.perf_counter()
+        prep_strategy = image_preprocess_service.recommend_prep_strategy(content)
+        prepared_base64 = image_preprocess_service.prepare_image_base64(content)
+        execution_times["image_preprocess"] = f"{(time.perf_counter() - start_time):.3f}s"
+        
+        primary_results = []
+        primary_name = None
+
+        # Run Primary (MedSigLIP)
+        interpretation = None
+        try:
+            start_time = time.perf_counter()
+            primary_results = medsiglip_wrapped_service.analyze_image(content, custom_labels=custom_labels)
+            execution_times["primary_medsiglip"] = f"{(time.perf_counter() - start_time):.3f}s"
+            primary_name = medsiglip_wrapped_service.service.model_name
+            
+            # Interpret results with configurable threshold
+            interpretation = result_interpreter.interpret(
+                primary_results, 
+                margin_threshold=payload.margin_threshold
+            )
+        except Exception as e:
+            logger.error(f"Primary inference failed: {e}")
+            raise HTTPException(status_code=500, detail="Primary model failed")
+
+        if primary_results:
+            logger.info(f"Primary ({primary_name}) top result: {primary_results[0]['label']} ({primary_results[0]['score']:.2f})")
+             
+        results_dict = {
+             "primary": primary_results,
+             "interpretation": interpretation,
+             "primary_model_name": primary_name,
+             "preprocess_strategy": prep_strategy,
+             "prepared_image_base64": prepared_base64,
+             "execution_times": execution_times
+        }
+        
+        # Merge with existing cache 
+        try:
+            current_cache = photo_repo.get_analysis_results(photo_id, session_id)
+            if current_cache:
+                start_data = json.loads(current_cache[0])
+                if isinstance(start_data, dict):
+                    if not primary_results and "primary" in start_data:
+                        results_dict["primary"] = start_data["primary"]
+                        results_dict["primary_model_name"] = start_data.get("primary_model_name")
+        except:
+            pass
+
+        # Save results
+        if not payload.base64_image:
+            try:
+                photo_repo.save_analysis_results(photo_id, session_id, json.dumps(results_dict))
+            except Exception as e:
+                logger.error(f"Failed to save analysis results: {e}")
+        
+        return SinglePhotoAnalysisResponse(
+            photo_id=photo_id,
+            predictions=results_dict.get("primary") or [],
+            interpretation=results_dict.get("interpretation"),
+            primary_model_name=results_dict.get("primary_model_name"),
+            analysis_date=datetime.now().isoformat(),
+            prepared_image_base64=results_dict.get("prepared_image_base64"),
+            preprocess_strategy=results_dict.get("preprocess_strategy"),
+            execution_times=results_dict.get("execution_times")
+        )
+
+    except Exception as e:
+        logger.error(f"Analysis failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.delete("/{photo_id}")
+async def delete_photo(photo_id: str, request: Request):
+    session_id = request.cookies.get("session_id")
+    if not session_id:
+        raise HTTPException(status_code=400, detail="No session found")
+
+    try:
+        photo_repo.delete_photo(photo_id, session_id)
+        # Ideally delete file too, but keeping it simple for now
+        return {"status": "deleted", "id": photo_id}
+            
+    except Exception as e:
+        logger.error(f"Delete failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+from app.services.gradcam_service import gradcam_service
+
+@router.post("/{photo_id}/saliency", response_model=SaliencyResponse)
+async def generate_saliency_map(
+    photo_id: str,
+    payload: SaliencyRequest,
+    request: Request
+):
+    session_id = request.cookies.get("session_id")
+    if not session_id:
+        raise HTTPException(status_code=400, detail="No session found")
+
+    try:
+        # Decode base64 image
+        if "," in payload.base64_image:
+            _, encoded = payload.base64_image.split(",", 1)
+        else:
+            encoded = payload.base64_image
+        content = base64.b64decode(encoded)
+        
+        # Generate Saliency (Grad-CAM)
+        heatmap_bytes = gradcam_service.get_heatmap(content, payload.target_label)
+        saliency_base64 = base64.b64encode(heatmap_bytes).decode('utf-8')
+        
+        return SaliencyResponse(
+            photo_id=photo_id,
+            saliency_base64=saliency_base64
+        )
+            
+    except Exception as e:
+        logger.error(f"Saliency generation failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.delete("")
+async def clear_session_photos(request: Request):
+    """Deletes all photos associated with the current session ID."""
+    session_id = request.cookies.get("session_id")
+    if not session_id:
+        raise HTTPException(status_code=400, detail="No session found")
+
+    try:
+        photo_repo.clear_session(session_id)
+        
+            
+        return {"status": "cleared", "message": "All session photos deleted"}
+            
+    except Exception as e:
+        logger.error(f"Clear session failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))

app/services/detection_visualizer_service.py

@@ -0,0 +1,56 @@
+import logging
+from PIL import Image, ImageDraw
+import io
+import numpy as np
+
+from app.services.yolo_service import yolo_service
+
+logger = logging.getLogger(__name__)
+
+class DetectionVisualizerService:
+    def __init__(self):
+        pass
+
+    def get_detection_visual(self, image_content: bytes, target_label: str = None) -> bytes:
+        """
+        Detects lesions using YOLOv8-Nano and draws a bounding box.
+        Returns the image with box as bytes (JPEG).
+        """
+        try:
+            # Prepare Inputs
+            image = Image.open(io.BytesIO(image_content)).convert("RGB")
+            
+            model = yolo_service.load_model()
+            results = model.predict(image, conf=0.25, verbose=False)
+            
+            # Draw on image
+            draw = ImageDraw.Draw(image)
+            
+            found = False
+            if results and len(results[0].boxes) > 0:
+                for box in results[0].boxes:
+                    b = box.xyxy[0].cpu().numpy()
+                    conf = float(box.conf[0])
+                    
+                    # Draw red box for lesion
+                    draw.rectangle([b[0], b[1], b[2], b[3]], outline="red", width=5)
+                    # Draw label background
+                    label = f"Lesion {conf:.2f}"
+                    draw.text((b[0] + 5, b[1] + 5), label, fill="red")
+                    found = True
+            
+            if not found:
+                # Optional: draw some indicator that nothing was found?
+                # Or just return original image.
+                pass
+
+            # Return
+            buf = io.BytesIO()
+            image.save(buf, format="JPEG")
+            return buf.getvalue()
+
+        except Exception as e:
+            logger.error(f"YOLO visualizer error: {e}")
+            return image_content
+
+detection_visualizer_service = DetectionVisualizerService()

app/services/gradcam_service.py

@@ -0,0 +1,113 @@
+import logging
+import torch
+import torch.nn.functional as F
+import numpy as np
+import cv2
+from PIL import Image
+import io
+from app.services.medsiglip_service import medsiglip_service
+
+logger = logging.getLogger(__name__)
+
+class GradCAMService:
+    def __init__(self):
+        self.gradients = None
+        self.activations = None
+        self.hooks = []
+
+    def _save_gradient(self, _module, _grad_input, grad_output):
+        self.gradients = grad_output[0]
+
+    def _save_activation(self, _module, _input, output):
+        if isinstance(output, tuple):
+             self.activations = output[0]
+        else:
+             self.activations = output
+
+    def get_heatmap(self, image_content: bytes, target_label: str) -> bytes:
+        """
+        Generates a Grad-CAM heatmap for the given image and target label.
+        Returns the overlay image as bytes (JPEG).
+        """
+        # Ensure model is ready
+        medsiglip_service._load_model()
+        model = medsiglip_service.model
+        processor = medsiglip_service.processor
+        device = medsiglip_service.device
+
+        # Clean state
+        self.gradients = None
+        self.activations = None
+        for h in self.hooks: h.remove()
+        self.hooks = []
+
+        try:
+            # Prepare Inputs
+            image = Image.open(io.BytesIO(image_content)).convert("RGB")
+            inputs = processor(text=[target_label], images=image, return_tensors="pt", padding="max_length").to(device)
+            
+            # Hook Target Layer: Last Encoder Layer of Vision Model
+            target_layer = model.vision_model.encoder.layers[-1]
+            
+            h1 = target_layer.register_forward_hook(self._save_activation)
+            h2 = target_layer.register_full_backward_hook(self._save_gradient)
+            self.hooks.extend([h1, h2])
+
+            # Forward Pass
+            model.zero_grad()
+            outputs = model(**inputs)
+            
+            # Calculate Score
+            score = outputs.logits_per_image[0, 0]
+            
+            # Backward Pass
+            score.backward()
+            
+            if self.gradients is None or self.activations is None:
+                logger.error("Failed to capture gradients or activations.")
+                return image_content
+
+            # CPU processing
+            gradients = self.gradients[0].detach().cpu()
+            activations = self.activations[0].detach().cpu()
+            
+            weights = torch.mean(gradients, dim=0)
+            cam = torch.matmul(activations, weights)
+            
+            seq_len = cam.shape[0]
+            grid_size = int(seq_len**0.5)
+            
+            if grid_size * grid_size != seq_len:
+                logger.warning(f"Non-square sequence length: {seq_len}")
+                return image_content
+            
+            cam_map = cam.view(grid_size, grid_size)
+            cam_map = F.relu(cam_map)
+            
+            if cam_map.max() > 0:
+                cam_map = cam_map - cam_map.min()
+                cam_map = cam_map / cam_map.max()
+            
+            cam_map_np = cam_map.numpy()
+
+            img_np = np.array(image)
+            heatmap = cv2.resize(cam_map_np, (img_np.shape[1], img_np.shape[0]))
+            
+            heatmap = np.uint8(255 * heatmap)
+            heatmap_color = cv2.applyColorMap(heatmap, cv2.COLORMAP_JET)
+            
+            overlay = cv2.addWeighted(img_np, 0.6, heatmap_color, 0.4, 0)
+            
+            out_img = Image.fromarray(overlay)
+            buf = io.BytesIO()
+            out_img.save(buf, format="JPEG")
+            return buf.getvalue()
+
+        except Exception as e:
+            logger.error(f"Grad-CAM error: {e}")
+            return image_content
+        finally:
+            for h in self.hooks: h.remove()
+            self.hooks = []
+
+gradcam_service = GradCAMService()

app/services/image_preprocess_service.py

@@ -0,0 +1,192 @@
+import logging
+import functools
+import time
+import numpy as np
+from PIL import Image
+import io
+from app.services.yolo_service import yolo_service
+
+logger = logging.getLogger(__name__)
+
+from enum import Enum
+
+class PreprocessStrategy(str, Enum):
+    CROP = "crop"
+    PAD = "pad"
+    NONE = "none"
+
+class ImagePreprocessService:
+    def __init__(self):
+        pass
+
+
+    def get_lesion_bbox(self, image_content: bytes, threshold: float = 0.25) -> tuple:
+        """
+        Detects the lesion bounding box using YOLOv8-Nano.
+        """
+        try:
+            with Image.open(io.BytesIO(image_content)) as img:
+                if img.mode != "RGB":
+                    img = img.convert("RGB")
+                width, height = img.size
+                
+                model = yolo_service.load_model()
+                if model is None:
+                    return (0, 0, width, height)
+                    
+                # Run inference
+                results = model.predict(img, conf=threshold, verbose=False)
+                
+                if not results or len(results[0].boxes) == 0:
+                    logger.debug("YOLO detection found no boxes, falling back to full image")
+                    return (0, 0, width, height)
+                    
+                # Take the highest confidence box (YOLO sorts by confidence by default)
+                box = results[0].boxes[0].xyxy[0].cpu().numpy()
+                return (float(box[0]), float(box[1]), float(box[2]), float(box[3]))
+        except Exception as e:
+            logger.error(f"YOLO detection failed: {e}")
+            return None
+
+
+    @functools.lru_cache(maxsize=32)
+    def recommend_prep_strategy(self, image_bytes: bytes) -> dict:
+        """
+        Decides whether to 'crop' or 'pad' based on object detection.
+        """
+        start_time = time.perf_counter()
+        image = Image.open(io.BytesIO(image_bytes))
+        width, height = image.size
+        
+        if width == height:
+            return {
+                "strategy": PreprocessStrategy.NONE, 
+                "reason": "Already square",
+                "execution_time": f"{(time.perf_counter() - start_time):.3f}s"
+            }
+
+        if width <= 448 and height <= 448:
+            return {
+                "strategy": PreprocessStrategy.PAD, 
+                "reason": "Image is 448x448 or smaller; padding to square to avoid any data loss or scale-down",
+                "execution_time": f"{(time.perf_counter() - start_time):.3f}s"
+            }
+
+        bbox = self.get_lesion_bbox(image_bytes)
+        if not bbox:
+            return {
+                "strategy": PreprocessStrategy.CROP, 
+                "reason": "Detection failed, defaulting to center crop",
+                "execution_time": f"{(time.perf_counter() - start_time):.3f}s"
+            }
+
+        x1, y1, x2, y2 = bbox
+        
+        # Center square boundaries
+        new_dim = min(width, height)
+        if width > height:
+            # Landscape
+            crop_x1 = (width - new_dim) / 2
+            crop_x2 = (width + new_dim) / 2
+            
+            # Check if bbox is outside the horizontal center crop
+            is_cut = (x1 < crop_x1) or (x2 > crop_x2)
+        else:
+            # Portrait
+            crop_y1 = (height - new_dim) / 2
+            crop_y2 = (height + new_dim) / 2
+            
+            # Check if bbox is outside the vertical center crop
+            is_cut = (y1 < crop_y1) or (y2 > crop_y2)
+
+        if is_cut:
+            return {
+                "strategy": PreprocessStrategy.PAD, 
+                "reason": "Object extends beyond center crop area",
+                "bbox": bbox,
+                "execution_time": f"{(time.perf_counter() - start_time):.3f}s"
+            }
+        else:
+            return {
+                "strategy": PreprocessStrategy.CROP, 
+                "reason": "Object fully contained in center crop area",
+                "bbox": bbox,
+                "execution_time": f"{(time.perf_counter() - start_time):.3f}s"
+            }
+
+    def prepare_image(self, image: Image.Image, target_size: tuple = (448, 448)) -> Image.Image:
+        """
+        Intelligently prepares an image by either cropping or padding to a square,
+        then resizing to target_size.
+        """
+        # Convert to bytes for strategy detection
+        img_byte_arr = io.BytesIO()
+        image.save(img_byte_arr, format='JPEG')
+        image_bytes = img_byte_arr.getvalue()
+        
+        strategy_res = self.recommend_prep_strategy(image_bytes)
+        strategy = strategy_res["strategy"]
+        
+        width, height = image.size
+        
+        if strategy == PreprocessStrategy.CROP or strategy == PreprocessStrategy.NONE:
+            # Traditional center crop (or already square)
+            new_dim = min(width, height)
+            left = (width - new_dim) / 2
+            top = (height - new_dim) / 2
+            right = (width + new_dim) / 2
+            bottom = (height + new_dim) / 2
+            image = image.crop((left, top, right, bottom))
+        elif strategy == PreprocessStrategy.PAD:
+            # Pad to square
+            new_dim = max(width, height)
+            # Use black background for padding as it is common for clinical vision models
+            new_image = Image.new("RGB", (new_dim, new_dim), (0, 0, 0)) 
+            if width > height:
+                # Landscape -> Pad Top/Bottom
+                new_image.paste(image, (0, (new_dim - height) // 2))
+            else:
+                # Portrait -> Pad Left/Right
+                new_image.paste(image, ((new_dim - width) // 2, 0))
+            image = new_image
+        
+        # Finally resize
+        if image.size != target_size:
+            logger.debug(f"Resizing image to {target_size}")
+            image = image.resize(target_size, Image.Resampling.LANCZOS)
+            
+        return image
+
+    def prepare_image_base64(self, image_bytes: bytes, target_size: tuple = (448, 448)) -> str:
+        """
+        Prepares image and returns as base64 data URI for UI debugging/display.
+        """
+        import base64
+        try:
+            image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+            prepared_image = self.prepare_image(image, target_size)
+            
+            buf = io.BytesIO()
+            prepared_image.save(buf, format="JPEG")
+            img_b64 = base64.b64encode(buf.getvalue()).decode('utf-8')
+            return f"data:image/jpeg;base64,{img_b64}"
+        except Exception as e:
+            logger.error(f"Failed to prepare image base64: {e}")
+            return None
+
+    def prepare_image_bytes(self, image_bytes: bytes, target_size: tuple = (448, 448)) -> bytes:
+        """
+        Helper to prepare image directly from bytes and return bytes.
+        """
+        try:
+            image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+            prepared_image = self.prepare_image(image, target_size)
+            
+            buf = io.BytesIO()
+            prepared_image.save(buf, format="JPEG")
+            return buf.getvalue()
+        except Exception as e:
+            logger.error(f"Failed to prepare image bytes: {e}")
+            raise e
+
+image_preprocess_service = ImagePreprocessService()

app/services/medsiglip_modality_wrapper.py

@@ -0,0 +1,80 @@
+import logging
+from typing import List, Dict, Optional, Any
+from app.services.medsiglip_service import medsiglip_service
+from app.dermatology_data import MEDSIGLIP_DERMATOLOGY_NARROW_LABELS
+
+logger = logging.getLogger(__name__)
+
+class ClinicalModalityWrapper:
+    """
+    Generic wrapper for vision-language models that implements clinical modality templating
+    using the MEDSIGLIP_DERMATOLOGY_NARROW_LABELS map (Keys and Values).
+    """
+    def __init__(self, service: Any, modality: str = "macroscopic"):
+        self.service = service
+        # "macroscopic" -> "Clinical photograph showing {desc}."
+        # "dermoscopy" -> "Dermoscopy image revealing {desc}."
+        self.modality = modality
+        self.labels_map = MEDSIGLIP_DERMATOLOGY_NARROW_LABELS
+
+    def _get_template(self) -> str:
+        if self.modality == "dermoscopy":
+            return "Dermoscopy image revealing {}."
+        #return "Clinical photograph showing {}."
+        return "A patient-submitted smartphone photograph showing {}."
+
+    def analyze_image(self, image_bytes: bytes, custom_labels: Optional[List[str]] = None) -> List[Dict]:
+        """
+        Analyzes an image using clinical descriptions (values) wrapped in modality templates.
+        Returns mapped results with original short labels (keys).
+        """
+        # 1. Prepare labels and descriptions from MEDSIGLIP_DERMATOLOGY_NARROW_LABELS
+        if custom_labels:
+            descriptions = []
+            valid_labels = []
+            for label in custom_labels:
+                if label in self.labels_map:
+                    descriptions.append(self.labels_map[label])
+                    valid_labels.append(label)
+                else:
+                    # If not in our clinical map, use original label as description
+                    descriptions.append(label)
+                    valid_labels.append(label)
+        else:
+            # Use all predefined clinical labels (Keys and Values)
+            valid_labels = list(self.labels_map.keys())
+            descriptions = list(self.labels_map.values())
+
+        # 2. Apply modality template to descriptions (Values)
+        template = self._get_template()
+        prompts = [template.format(desc) for desc in descriptions]
+
+        print(f"\n[DEBUG] Prompts for {self.service.model_name}:")
+        for p in prompts:
+            print(f"  - {p}")
+
+        # 3. Call the underlying service
+        # Handle different method names between MedSigLIP and SigLIP services
+        if hasattr(self.service, "get_embeddings"):
+            raw_results = self.service.get_embeddings(image_bytes, texts=prompts)
+        elif hasattr(self.service, "get_predictions"):
+            raw_results = self.service.get_predictions(image_bytes, texts=prompts)
+        else:
+            raise AttributeError(f"Service {type(self.service)} has no supported inference method.")
+
+        # 4. Map prompts back to original short labels (Keys)
+        prompt_to_label = dict(zip(prompts, valid_labels))
+
+        mapped_results = []
+        for res in raw_results:
+            original_label = prompt_to_label.get(res["label"], res["label"])
+            mapped_results.append({
+                "label": original_label,
+                "description": res["label"], # The full prompt used
+                "score": res["score"]
+            })
+
+        return mapped_results
+
+# Global instances for easy access
+medsiglip_wrapped_service = ClinicalModalityWrapper(medsiglip_service)

app/services/medsiglip_service.py

@@ -0,0 +1,95 @@
+import logging
+import torch
+import os
+from PIL import Image
+from transformers import AutoProcessor, AutoModel
+import io
+from typing import List, Optional
+from app.services.image_preprocess_service import image_preprocess_service
+from app.config import MEDSIGLIP_MODEL_NAME, MODEL_IMAGE_SIZE
+
+logger = logging.getLogger(__name__)
+
+class MedSigLIPService:
+    def __init__(self, model_name=MEDSIGLIP_MODEL_NAME):
+        # We'll lazy load the model to avoid startup costs and potential auth issues crashing the app immediately
+        self.model_name = model_name
+        
+        self.processor = None
+        self.model = None
+        if torch.cuda.is_available():
+            self.device = "cuda"
+        elif torch.backends.mps.is_available():
+            self.device = "mps"
+        else:
+            self.device = "cpu"
+
+    def _load_model(self):
+        if self.model is None:
+            logger.info(f"Loading MedSigLIP model: {self.model_name} on {self.device}...")
+            try:
+                token = os.getenv("HF_TOKEN")
+                self.processor = AutoProcessor.from_pretrained(self.model_name, token=token)
+                self.model = AutoModel.from_pretrained(self.model_name, token=token).to(self.device)
+                logger.info("MedSigLIP model loaded successfully.")
+            except Exception as e:
+                    logger.error(f"Failed to load MedSigLIP model: {e}")
+                    raise e
+
+    def get_embeddings(self, image_bytes: bytes, texts: Optional[List[str]] = None):
+        """
+        Run inference to get embeddings or probabilities for zero-shot classification.
+        If texts is provided, performs zero-shot classification via similarity.
+        """
+        self._load_model()
+        try:
+            image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+            image = image_preprocess_service.prepare_image(image, MODEL_IMAGE_SIZE)
+            
+            if texts:
+                # 64-token limit check as per requirements
+                inputs = self.processor(
+                    text=texts,
+                    images=image,
+                    padding="max_length",
+                    max_length=64,
+                    truncation=True,
+                    return_tensors="pt"
+                ).to(self.device)
+
+                # Optional: Log warning if truncation occurred (check input_ids shape vs max_length)
+                # Note: with truncation=True, the shape will be (num_texts, 64)
+                # To detect if it *would* have exceeded, we could tokenize without truncation first,
+                # but that's expensive. Instead, we can just ensure we stay within the limit.
+                
+                with torch.no_grad():
+                    outputs = self.model(**inputs)
+                
+                # Retrieve logits
+                logits_per_image = outputs.logits_per_image
+                probs = logits_per_image.softmax(dim=1)
+                
+                # Format results
+                results = []
+                prob_values = probs[0].tolist()
+                for i, text in enumerate(texts):
+                    results.append({"label": text, "score": prob_values[i]})
+                
+                # Sort by score descending
+                results.sort(key=lambda x: x["score"], reverse=True)
+                return results
+            else:
+                # Just image embedding
+                # MedSigLIP is a CLIP-like model, so we can get features
+                inputs = self.processor(images=image, return_tensors="pt").to(self.device) # Only image
+                with torch.no_grad():
+                     image_features = self.model.get_image_features(**inputs)
+                
+                return {"embedding": image_features[0].tolist()}
+
+        except Exception as e:
+            logger.error(f"MedSigLIP inference failed: {e}")
+            raise e
+
+# Global instance
+medsiglip_service = MedSigLIPService()

app/services/result_interpreter.py

@@ -0,0 +1,159 @@
+import math
+import logging
+from typing import List, Dict, Any
+from app.dermatology_data import CANCEROUS_TUMOR_CLASSES
+from app.config import INTERPRETER_ENTROPY_THRESHOLD, INTERPRETER_MARGIN_THRESHOLD, CONFIDENCE_CLASSES
+
+logger = logging.getLogger(__name__)
+
+class ResultInterpreter:
+    """
+    Analyzes classification results from MedSigLIP models to provide clinical insights.
+    
+    Responsibilities:
+    1. Detect if top predictions indicate tumor-related diseases based on CANCEROUS_TUMOR_CLASSES.
+    2. Handle mixed cases (Tumor vs Non-Tumor) with confidence margins.
+    3. Calculate Predictive Entropy (Shannon Entropy) as a measure of model uncertainty.
+    4. Provide descriptive annotations and color hints for UI.
+    5. Classify confidence based on Top-1 vs Top-2 margin.
+    """
+
+    def interpret(self, results: List[Dict[str, Any]], 
+                  entropy_threshold: float = INTERPRETER_ENTROPY_THRESHOLD,
+                  margin_threshold: float = INTERPRETER_MARGIN_THRESHOLD) -> Dict[str, Any]:
+        """Interprets a list of classification results."""
+        if not results:
+            return self._empty_result()
+
+        scores = [r["score"] for r in results]
+        entropy = self.calculate_entropy(scores)
+        is_reliable = entropy < entropy_threshold
+
+        # Rule 1: Margin Calculation (including Tumor Consolidation)
+        margin = self._calculate_margin(results)
+        conf_info = self.get_confidence_level(margin)
+        
+        # Rule 2: Status and Annotation Logic
+        analysis = self._determine_status_and_annotation(results, margin, margin_threshold)
+        
+        # Rule 3: Format computation process for tech logs
+        comp_process = self._format_computation_process(
+            results, margin, margin_threshold, conf_info, entropy, entropy_threshold, is_reliable
+        )
+
+        return {
+            "is_high_risk": analysis["is_high_risk"],
+            "entropy": entropy,
+            "is_reliable": is_reliable,
+            "annotation": analysis["annotation"],
+            "color_hint": analysis["color_hint"],
+            "confidence_label": conf_info["label"],
+            "confidence_color": conf_info["color_hint"],
+            "status": analysis["status"],
+            "margin": margin,
+            "margin_threshold": margin_threshold,
+            "computation_process": comp_process,
+            "top_2_labels": [results[0]["label"], results[1]["label"]] if len(results) > 1 else [results[0]["label"], "None"]
+        }
+
+    def _empty_result(self) -> Dict[str, Any]:
+        return {
+            "is_high_risk": False, "entropy": 0.0, "is_reliable": False,
+            "annotation": "No results available to interpret.", "color_hint": "gray",
+            "confidence_label": "Unknown", "confidence_color": "gray",
+            "computation_process": ["No results provided."]
+        }
+
+    def _calculate_margin(self, results: List[Dict[str, Any]]) -> float:
+        """
+        Calculates margin. 
+        Tumor rule: sum(contiguous tumors) - first_non_tumor
+        Default rule: top_1 - top_2
+        """
+        top_1 = results[0]
+        if top_1["label"] in CANCEROUS_TUMOR_CLASSES:
+            tumor_sum = 0.0
+            next_non_tumor_score = 0.0
+            found_non_tumor = False
+            for r in results:
+                if not found_non_tumor and r["label"] in CANCEROUS_TUMOR_CLASSES:
+                    tumor_sum += r["score"]
+                elif not found_non_tumor:
+                    next_non_tumor_score = r["score"]
+                    found_non_tumor = True
+            return round(tumor_sum - next_non_tumor_score, 4)
+        
+        top_2_score = results[1]["score"] if len(results) > 1 else 0.0
+        return round(top_1["score"] - top_2_score, 4)
+
+    def _determine_status_and_annotation(self, results: List[Dict[str, Any]], margin: float, margin_threshold: float) -> Dict[str, Any]:
+        """Provides status, annotation, and color hint based on top results."""
+        t1 = results[0]
+        t2 = results[1] if len(results) > 1 else {"label": "None", "score": 0.0}
+        
+        is_t1_tumor = t1["label"] in CANCEROUS_TUMOR_CLASSES
+        is_t2_tumor = t2["label"] in CANCEROUS_TUMOR_CLASSES
+
+        if is_t1_tumor and is_t2_tumor:
+            return {"is_high_risk": True, "annotation": "High likeness of tumor disease", "color_hint": "red", "status": "tumor_detected"}
+        
+        if is_t1_tumor != is_t2_tumor:
+            if margin < margin_threshold:
+                return {"is_high_risk": False, "annotation": "Not clear", "color_hint": "yellow", "status": "uncertain_mixed"}
+            
+            if is_t1_tumor:
+                return {"is_high_risk": False, "annotation": f"Potential cancerous condition: {t1['label']}", "color_hint": "red", "status": "potential_tumor"}
+            return {"is_high_risk": False, "annotation": f"Likely benign: {t1['label']}", "color_hint": "green", "status": "likely_benign"}
+            
+        return {"is_high_risk": False, "annotation": "No immediate tumor likeness detected in top results", "color_hint": "green", "status": "benign"}
+
+    def _format_computation_process(self, results, margin, margin_threshold, conf_info, entropy, entropy_threshold, is_reliable) -> List[str]:
+        """Formats the detailed steps of interpretation for UI display."""
+        t1 = results[0]
+        t2 = results[1] if len(results) > 1 else {"label": "None", "score": 0.0}
+        
+        process = [
+            f"Top 1: {t1['label']} ({t1['score']:.2f}) - Tumor: {t1['label'] in CANCEROUS_TUMOR_CLASSES}",
+            f"Top 2: {t2['label']} ({t2['score']:.2f}) - Tumor: {t2['label'] in CANCEROUS_TUMOR_CLASSES}",
+            f"Margin: {margin:.4f} (Threshold: {margin_threshold})",
+            f"Confidence: {conf_info['label']}",
+            f"Mixed Case Detect: {'Yes' if (t1['label'] in CANCEROUS_TUMOR_CLASSES) != (t2['label'] in CANCEROUS_TUMOR_CLASSES) else 'No'}",
+            f"Entropy: {entropy:.2f} bits (Limit: {entropy_threshold})"
+        ]
+        process.append("Status: Prediction within reliability limits" if is_reliable else f"Status: Low confidence - High uncertainty detected (Entropy: {entropy:.2f})")
+        return process
+
+    def get_confidence_level(self, margin: float) -> Dict[str, str]:
+        """
+        Maps margin to a qualitative confidence level using thresholds from config.
+        """
+        # Round to avoid floating point precision issues (e.g. 0.4 - 0.1 = 0.30000000000000004)
+        m = round(margin, 4)
+        
+        for cls in CONFIDENCE_CLASSES:
+            if m > cls["min"]:
+                return {
+                    "label": cls["label"],
+                    "color_hint": cls.get("color_hint", "")
+                }
+        
+        # Fallback to the last class (usually 0.0) if no match found
+        last_cls = CONFIDENCE_CLASSES[-1]
+        return {
+            "label": last_cls["label"],
+            "color_hint": last_cls.get("color_hint", "")
+        }
+
+    def calculate_entropy(self, probabilities: List[float]) -> float:
+        """
+        Calculates Shannon entropy in bits.
+        H = -sum(pi * log2(pi))
+        """
+        entropy = 0.0
+        for p in probabilities:
+            if p > 1e-9: # Avoid log(0)
+                entropy -= p * math.log2(p)
+        return entropy
+
+# Global singleton instance
+result_interpreter = ResultInterpreter()

app/services/vertex_client.py

@@ -0,0 +1,77 @@
+import os
+import logging
+try:
+    from google.cloud import aiplatform
+    from google.oauth2 import service_account
+    import google.auth
+    GOOGLE_CLOUD_AVAILABLE = True
+except ImportError:
+    GOOGLE_CLOUD_AVAILABLE = False
+    aiplatform = None
+    service_account = None
+    google = None
+
+logger = logging.getLogger(__name__)
+
+class VertexClient:
+    def __init__(self):
+        self.project_id = os.environ.get("PROJECT_ID")
+        self.location = os.environ.get("LOCATION", "us-central1")
+        self.endpoint_id = os.environ.get("ENDPOINT_ID") # ID of the deployed MedGemma endpoint
+        self.credentials_path = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
+        
+        self.setup_complete = False
+        
+        if not GOOGLE_CLOUD_AVAILABLE:
+            logger.warning("google-cloud-aiplatform not installed. Vertex AI client will be mocked.")
+            return
+
+        if self.project_id:
+            try:
+                # If credentials path is set, explicit load (dev), else default (cloud run)
+                if self.credentials_path and os.path.exists(self.credentials_path):
+                    creds = service_account.Credentials.from_service_account_file(self.credentials_path)
+                else:
+                    creds, _ = google.auth.default()
+
+                aiplatform.init(
+                    project=self.project_id,
+                    location=self.location,
+                    credentials=creds
+                )
+                self.setup_complete = True
+                logger.info(f"Vertex AI initialized for project {self.project_id}")
+            except Exception as e:
+                logger.error(f"Failed to initialize Vertex AI: {e}")
+
+    async def predict(self, prompt: str, max_tokens: int = 256, temperature: float = 0.2) -> str:
+        if not self.setup_complete:
+            logger.info("Returning mock prediction because Vertex AI is not configured.")
+            return "Mock Response: Vertex AI is not configured. This is a dummy prediction."
+        
+        if not self.endpoint_id:
+            return "Endpoint ID not configured."
+
+        try:
+            # Get Endpoint
+            endpoint = aiplatform.Endpoint(self.endpoint_id)
+            
+            # Predict
+            # Structure depends on the model serving container. 
+            # MedGemma usually expects instances=[{"prompt": ...}]
+            instances = [{"prompt": prompt, "max_tokens": max_tokens, "temperature": temperature}]
+            
+            response = endpoint.predict(instances=instances)
+            
+            # Parse prediction (assuming standard format, adjust based on actual model output)
+            # Typically response.predictions is a list
+            if response.predictions:
+                 return str(response.predictions[0])
+            else:
+                 return "No prediction returned."
+
+        except Exception as e:
+            logger.error(f"Prediction failed: {e}")
+            raise e
+
+vertex_client = VertexClient()

app/services/yolo_service.py

@@ -0,0 +1,22 @@
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+class YOLOService:
+    def __init__(self):
+        self.model = None
+
+    def load_model(self):
+        if self.model is None:
+            try:
+                from ultralytics import YOLO
+                # Use YOLOv8-Nano
+                logger.info("Loading YOLOv8-Nano model...")
+                self.model = YOLO('yolov8n.pt')
+            except ImportError:
+                logger.warning("ultralytics not installed. YOLO detection will be skipped.")
+                return None
+        return self.model
+
+yolo_service = YOLOService()

app/static/app.js

@@ -0,0 +1,512 @@
+function dermatologApp() {
+    return {
+        // App State
+        activeTab: 'photos',
+        analysisResults: {},
+        showTechnicalDetails: {}, // Map of photo_id -> boolean
+
+        // Chat State
+        prompt: '',
+        temperature: 0.2,
+        loading: false,
+        response: null,
+        latency: null,
+        sessionId: null,
+
+        // Photo State
+        timeline: [],
+        dragover: false,
+        editingPhoto: null,
+        editingDate: '',
+
+        // Common
+        error: null,
+        modelName: 'Loading...',
+        yoloAvailable: false,
+        marginThreshold: 0.05,
+        currentAnalysisId: null,
+        clearPromise: null,
+        debugMode: false,
+
+        init() {
+            this.sessionId = this.getCookie('session_id');
+            const urlParams = new URLSearchParams(window.location.search);
+            this.debugMode = urlParams.has('debug');
+
+            this.loadTimeline();
+            this.fetchModelInfo();
+
+            // Global Paste Handler
+            window.addEventListener('paste', (e) => {
+                const items = (e.clipboardData || e.originalEvent.clipboardData).items;
+                const files = [];
+                for (let i = 0; i < items.length; i++) {
+                    if (items[i].type.indexOf('image') !== -1) {
+                        const file = items[i].getAsFile();
+                        if (file) files.push(file);
+                    }
+                }
+                if (files.length > 0) {
+                    this.handleFiles(files);
+                }
+            });
+
+            // Prevent accidental refresh
+            window.addEventListener('beforeunload', (e) => {
+                if (this.timeline && this.timeline.length > 0) {
+                    const msg = "On refresh the content would be cleared. Are you sure you want to leave?";
+                    e.preventDefault();
+                    e.returnValue = msg;
+                    return msg;
+                }
+            });
+        },
+
+        async fetchModelInfo() {
+            try {
+                const res = await fetch('/api/health');
+                if (res.ok) {
+                    const data = await res.json();
+                    this.yoloAvailable = data.yolo_available;
+                    if (data.status === "OK") {
+                        this.modelName = "MedSigLIP (Local)";
+                    } else if (data.status === "suspended") {
+                        this.modelName = "Service Suspended";
+                    } else {
+                        this.modelName = data.status || "Unknown Status";
+                    }
+                }
+            } catch (e) {
+                console.error("Failed to fetch model info", e);
+                this.modelName = "Error fetching health";
+            }
+        },
+
+        getCookie(name) {
+            const value = `; ${document.cookie}`;
+            const parts = value.split(`; ${name}=`);
+            if (parts.length === 2) return parts.pop().split(';').shift();
+            return null;
+        },
+
+        async loadTimeline() {
+            try {
+                const res = await fetch('/api/photos?t=' + new Date().getTime());
+                if (res.ok) {
+                    this.timeline = await res.json();
+
+                    this.timeline.forEach(item => {
+                        const processPhoto = (p) => {
+                            // Status is handled at runtime in this.analysisResults, not restored from DB
+                            // satisfy "store the state whether image was processed in the html not db"
+                        };
+
+                        if (item.type === 'directory') {
+                            item.items.forEach(processPhoto);
+                        } else if (item.type === 'photo') {
+                            processPhoto(item.data);
+                        }
+                    });
+                }
+            } catch (e) {
+                console.error("Timeline load failed", e);
+            }
+        },
+
+        async handleDrop(event) {
+            this.dragover = false;
+            const files = event.dataTransfer.files;
+            if (files.length > 0) {
+                this.handleFiles(files);
+            }
+        },
+
+        async handleFiles(files) {
+            if (files.length === 0) return;
+
+            // Ensure we wait for any ongoing session clearing to finish
+            if (this.clearPromise) {
+                await this.clearPromise;
+            }
+
+            this.loading = true;
+            try {
+                for (let i = 0; i < files.length; i++) {
+                    const file = files[i];
+                    const dataUrl = await this.readAsDataURL(file);
+
+                    // Basic duplicate check (by name and size for local)
+                    const isDuplicate = this.getAllPhotos().some(p => p.filename === file.name && p.size === file.size);
+                    if (isDuplicate) {
+                        this.showToast("Upload Notice", `Skipped ${file.name} (already in timeline)`, "warning");
+                        continue;
+                    }
+
+                    const photoId = crypto.randomUUID();
+                    const photo = {
+                        id: photoId,
+                        filename: file.name,
+                        size: file.size,
+                        creation_date: new Date(file.lastModified || Date.now()).toISOString().split('T')[0],
+                        uploaded_at: new Date().toISOString(),
+                        local_content: dataUrl,
+                        analysis: null
+                    };
+
+                    this.addPhotoToTimeline(photo);
+                }
+
+                // Brief delay to let UI render the new cards
+                setTimeout(() => {
+                    this.analyzeAllPhotos();
+                }, 300);
+
+            } catch (e) {
+                console.error("Local processing error:", e);
+                this.error = "Failed to process images: " + e.message;
+            } finally {
+                this.loading = false;
+            }
+        },
+
+        readAsDataURL(file) {
+            return new Promise((resolve, reject) => {
+                const reader = new FileReader();
+                reader.onload = () => resolve(reader.result);
+                reader.onerror = reject;
+                reader.readAsDataURL(file);
+            });
+        },
+
+        addPhotoToTimeline(photo) {
+            // Check if day exists
+            let dir = this.timeline.find(item => item.type === 'directory' && item.date === photo.creation_date);
+            if (!dir) {
+                dir = {
+                    type: 'directory',
+                    date: photo.creation_date,
+                    items: [],
+                    count: 0
+                };
+                this.timeline.push(dir);
+                // Sort timeline by date descending
+                this.timeline.sort((a, b) => b.date.localeCompare(a.date));
+            }
+
+            // Avoid duplicates in items list
+            if (!dir.items.some(p => p.id === photo.id)) {
+                dir.items.push(photo);
+                dir.items.sort((a, b) => b.uploaded_at.localeCompare(a.uploaded_at));
+                dir.count = dir.items.length;
+            }
+        },
+
+        async deletePhoto(photoId) {
+            if (!confirm("Are you sure you want to delete this photo locally?")) return;
+
+            // Remove from timeline state (purely local)
+            this.timeline.forEach(dir => {
+                if (dir.type === 'directory') {
+                    dir.items = dir.items.filter(p => p.id !== photoId);
+                    dir.count = dir.items.length;
+                }
+            });
+            // Clean up empty directories
+            this.timeline = this.timeline.filter(dir => dir.type !== 'directory' || dir.count > 0);
+
+            delete this.analysisResults[photoId];
+            return true;
+        },
+
+        async deletePhotoFromModal() {
+            if (!this.editingPhoto) return;
+            const success = await this.deletePhoto(this.editingPhoto.id);
+            if (success) {
+                document.querySelector('.edit-dialog').hide();
+                this.editingPhoto = null;
+            }
+        },
+
+        async clearSession() {
+            if (!confirm("Clear all local photos?")) return;
+            // reset all frontend reactive state variables needed for a clean run
+            this.analysisResults = {};
+            this.timeline = [];
+            this.showTechnicalDetails = {};
+            this.prompt = '';
+            this.loading = false;
+            this.response = null;
+            this.latency = null;
+            this.currentAnalysisId = null;
+            this.editingPhoto = null;
+            this.editingDate = '';
+
+            // Reset file inputs so identical files can trigger @change again
+            if (this.$refs.fileInput) this.$refs.fileInput.value = '';
+            if (this.$refs.cameraInput) this.$refs.cameraInput.value = '';
+
+            // Optional: Tell backend to clear its session context if needed
+            fetch('/api/photos', { method: 'DELETE' }).catch(console.error);
+        },
+
+
+        openEditModal(photo) {
+            this.editingPhoto = photo;
+            this.editingDate = photo.creation_date;
+            document.querySelector('.edit-dialog').show();
+        },
+
+        async saveDate() {
+            if (!this.editingPhoto) return;
+
+            // Update locally
+            const oldDate = this.editingPhoto.creation_date;
+            const newDate = this.editingDate;
+
+            if (oldDate !== newDate) {
+                // Remove from old location
+                this.timeline.forEach(dir => {
+                    if (dir.date === oldDate) {
+                        dir.items = dir.items.filter(p => p.id !== this.editingPhoto.id);
+                        dir.count = dir.items.length;
+                    }
+                });
+
+                // Add to new
+                this.editingPhoto.creation_date = newDate;
+                this.addPhotoToTimeline(this.editingPhoto);
+
+                // Cleanup empty
+                this.timeline = this.timeline.filter(dir => dir.count > 0);
+            }
+
+            document.querySelector('.edit-dialog').hide();
+            this.editingPhoto = null;
+        },
+
+        async analyzeAllPhotos() {
+            this.loading = true;
+            this.error = null;
+            this.latency = 0;
+
+            const photos = this.getAllPhotos();
+            if (photos.length === 0) {
+                this.loading = false;
+                return;
+            }
+
+            const photosToAnalyze = photos.filter(p => !this.analysisResults[p.id]);
+            if (photosToAnalyze.length === 0) {
+                this.loading = false;
+                return;
+            }
+
+            let report = (this.response || "");
+            if (report && !report.endsWith("\n\n")) report += "\n\n";
+            report += `--- Starting Local Analysis Batch [${new Date().toLocaleTimeString()}] ---\n`;
+            this.response = report;
+
+            let startTime = performance.now();
+
+            try {
+                for (const photo of photosToAnalyze) {
+                    console.log(`Starting analysis for ${photo.filename} (${photo.id})`);
+                    report += `Analyzing ${photo.filename} (Local Transfer)...\n`;
+                    this.response = report;
+                    this.currentAnalysisId = photo.id;
+
+                    try {
+                        const res = await fetch(`/api/photos/${photo.id}/analyze`, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify({
+                                model: 'medsiglip',
+                                margin_threshold: parseFloat(this.marginThreshold),
+                                base64_image: photo.local_content
+                            })
+                        });
+
+                        if (res.ok) {
+                            const data = await res.json();
+                            if (data.predictions && data.predictions.length > 0) {
+                                // Populate results for UI
+                                this.analysisResults[photo.id] = {
+                                    id: photo.id,
+                                    date: new Date().toISOString(),
+                                    prediction: data.predictions[0],
+                                    predictions: data.predictions, // For legacy if any
+                                    primary: data.predictions,
+                                    initial_classification: data.initial_classification,
+                                    primary_name: data.primary_model_name,
+                                    interpretation: data.interpretation,
+                                    preprocess_strategy: data.preprocess_strategy,
+                                    prepared_image_base64: data.prepared_image_base64,
+                                    execution_times: data.execution_times,
+                                    saliency_base64: data.saliency_base64
+                                };
+                                report += `  ➔ Primary Results (${data.primary_model_name}):\n`;
+                                data.predictions.forEach(p => {
+                                    report += `     - ${p.label}: ${(p.score * 100).toFixed(1)}%\n`;
+                                });
+                            }
+                        } else {
+                            const err = await res.text();
+                            report += `  ➔ Request Failed: ${res.status} ${err}\n`;
+                        }
+                    } catch (e) {
+                        console.error(`Analysis error for ${photo.id}:`, e);
+                        report += `  ➔ Error: ${e.message}\n`;
+                    }
+
+                    this.currentAnalysisId = null;
+                    report += "\n";
+                    this.response = report;
+                }
+
+                this.latency = Math.round(performance.now() - startTime);
+                report += "Batch Completion Success.";
+                this.response = report;
+
+            } catch (e) {
+                console.error(e);
+                this.error = "Analysis process encountered a critical error.";
+            } finally {
+                this.loading = false;
+            }
+        },
+
+        async fetchSaliency(photo) {
+            console.log("fetchSaliency triggered for", photo.id);
+            if (!this.analysisResults[photo.id]) {
+                console.warn("No analysis results for photo", photo.id);
+                return;
+            }
+            if (this.analysisResults[photo.id].saliency_base64) {
+                console.log("Saliency already exists for", photo.id);
+                return;
+            }
+            if (!this.analysisResults[photo.id].primary || this.analysisResults[photo.id].primary.length === 0) {
+                console.warn("No primary assessment predictions for", photo.id);
+                return;
+            }
+
+            const topLabel = this.analysisResults[photo.id].primary[0].label;
+            console.log("Fetching saliency for label:", topLabel);
+
+            try {
+                const res = await fetch(`/api/photos/${photo.id}/saliency`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        base64_image: photo.local_content,
+                        target_label: topLabel
+                    })
+                });
+
+                if (res.ok) {
+                    const data = await res.json();
+                    console.log("Saliency data received for", photo.id, "len:", data.saliency_base64 ? data.saliency_base64.length : 0);
+                    this.analysisResults[photo.id].saliency_base64 = data.saliency_base64;
+                    console.log("Updated analysisResults with saliency for", photo.id);
+                } else {
+                    console.error("Saliency fetch failed with status:", res.status);
+                }
+            } catch (e) {
+                console.error("Saliency fetch error:", e);
+            }
+        },
+
+        getAllPhotos() {
+            let photos = [];
+            this.timeline.forEach(item => {
+                if (item.type === 'photo') photos.push(item.data);
+                else if (item.type === 'directory') photos.push(...item.items);
+            });
+            return photos;
+        },
+
+        getInterpretationColor(hint) {
+            const colors = {
+                'red': 'var(--sl-color-danger-600)',
+                'yellow': 'var(--sl-color-warning-600)',
+                'green': 'var(--sl-color-success-600)',
+                'gray': 'var(--sl-color-neutral-600)'
+            };
+            return colors[hint] || colors['gray'];
+        },
+
+        getBadgeVariant(hint) {
+            const variants = {
+                'green': 'success',
+                'gray': 'neutral',
+                'yellow': 'warning',
+                'red': 'danger'
+            };
+            return variants[hint] || 'neutral';
+        },
+
+        getInterpretationIcon(hint) {
+            if (hint === 'green') return 'shield-check';
+            if (hint === 'red') return 'exclamation-triangle';
+            return 'activity';
+        },
+
+        copyReport(photoId) {
+            const result = this.analysisResults[photoId];
+            if (!result) return;
+
+            const annotation = result.interpretation ? result.interpretation.annotation : result.prediction.label;
+            const confidence = result.interpretation ? result.interpretation.confidence_label : 'N/A';
+            const score = Math.round(result.prediction.score * 100) + '%';
+
+            const text = `Clinical Summary\n----------------\nResult: ${annotation}\nConfidence: ${confidence} (${score})\nDate: ${new Date(result.date).toLocaleString()}\n\nNote: This is an AI-assisted analysis and should be reviewed by a professional.`;
+
+            navigator.clipboard.writeText(text).then(() => {
+                this.showToast('Copied', 'Clinical summary copied to clipboard', 'success', 'clipboard-check');
+            });
+        },
+
+        toggleDebug() {
+            this.debugMode = !this.debugMode;
+            const url = new URL(window.location.href);
+            if (this.debugMode) {
+                url.searchParams.set('debug', '1');
+            } else {
+                url.searchParams.delete('debug');
+            }
+            window.history.replaceState({}, '', url.toString());
+        },
+
+        showToast(title, message, variant = 'primary', icon = 'info-circle') {
+            const alert = Object.assign(document.createElement('sl-alert'), {
+                variant: variant,
+                closable: true,
+                duration: 5000,
+                innerHTML: `
+                    <sl-icon slot="icon" name="${icon}"></sl-icon>
+                    <strong>${title}</strong><br />
+                    ${message}
+                `
+            });
+            document.body.append(alert);
+
+            // Ensure shoelace components are defined before calling methods
+            if (typeof customElements !== 'undefined' && customElements.whenDefined) {
+                customElements.whenDefined('sl-alert').then(() => {
+                    if (typeof alert.toast === 'function') {
+                        alert.toast();
+                    }
+                });
+            } else {
+                // Fallback for environments where customElements/Shoelace might not be fully loaded
+                setTimeout(() => {
+                    if (typeof alert.toast === 'function') alert.toast();
+                }, 100);
+            }
+        }
+    }
+}
+
+if (typeof window !== 'undefined') {
+    window.dermatologApp = dermatologApp;
+}

app/static/js/modules/api.js

@@ -0,0 +1,59 @@
+/**
+ * API client for backend communication
+ */
+export class ApiClient {
+    /**
+     * @param {string} baseUrl - Base URL for API (default: current origin)
+     */
+    constructor(baseUrl = '') {
+        this.baseUrl = baseUrl;
+    }
+
+    /**
+     * Uploads an image for analysis
+     * @param {FormData} formData - Form data containing image file
+     * @returns {Promise<Object>} { task_id: string }
+     * @throws {Error} If upload fails
+     */
+    async uploadImage(formData) {
+        const response = await fetch(`${this.baseUrl}/upload`, {
+            method: 'POST',
+            body: formData
+        });
+
+        if (!response.ok) {
+            throw new Error(`Upload failed: ${response.statusText}`);
+        }
+
+        return response.json();
+    }
+
+    /**
+     * Gets progress for a task
+     * @param {string} taskId - Task ID
+     * @returns {Promise<Object|null>} Task data or null if not found
+     */
+    async getProgress(taskId) {
+        try {
+            const response = await fetch(`${this.baseUrl}/progress/${taskId}`);
+            if (!response.ok) return null;
+            return response.json();
+        } catch (error) {
+            console.error('Failed to fetch progress:', error);
+            return null;
+        }
+    }
+
+    /**
+     * Gets aggregate statistics
+     * @returns {Promise<Object>} Statistics data
+     * @throws {Error} If fetch fails
+     */
+    async getStats() {
+        const response = await fetch(`${this.baseUrl}/stats`);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch stats: ${response.statusText}`);
+        }
+        return response.json();
+    }
+}

app/templates/index.html

@@ -0,0 +1,1149 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Dermatolog AI Scan</title>
+
+    <!-- Custom JS (Must load before Alpine) -->
+    <script defer src="/static/app.js?v=22"></script>
+
+    <!-- Alpine.js -->
+    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js"></script>
+
+    <!-- Shoelace -->
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.12.0/cdn/themes/light.css" />
+    <script type="module"
+        src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.12.0/cdn/shoelace-autoloader.js"></script>
+
+
+
+    <!-- Fonts -->
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+
+    <style>
+        :root {
+            --sl-font-sans: 'Outfit', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            --brand-primary: #10b981;
+            /* Clinical Green */
+            --brand-trust: #0f172a;
+            /* Deep Navy */
+            --bg-subtle: #f8fafc;
+        }
+
+        body {
+            font-family: var(--sl-font-sans);
+            background: linear-gradient(180deg, #ffffff 0%, var(--bg-subtle) 100%);
+            min-height: 100vh;
+            color: var(--brand-trust);
+        }
+
+        .container {
+            max-width: 1000px;
+            margin: 0 auto;
+            padding: 3rem 1.5rem;
+        }
+
+        /* Glassmorphism Effect */
+        .glass-overlay {
+            background: rgba(15, 23, 42, 0.85);
+            backdrop-filter: blur(8px);
+            -webkit-backdrop-filter: blur(8px);
+        }
+
+        /* Premium Card */
+        .card-premium {
+            border: 1px solid var(--sl-color-neutral-200);
+            box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.05), 0 2px 4px -2px rgb(0 0 0 / 0.05);
+            transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+            background: white;
+            border-radius: var(--sl-border-radius-large);
+        }
+
+        .card-premium:hover {
+            transform: translateY(-2px);
+            box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.07);
+            border-color: var(--sl-color-primary-200);
+        }
+
+        .card-premium.main-upload-card {
+            box-shadow: var(--sl-shadow-large);
+        }
+
+        .card-premium.main-upload-card:hover {
+            box-shadow: var(--sl-shadow-large);
+            transform: none;
+        }
+
+        .main-upload-card::part(body) {
+            padding: 0;
+            width: 100%;
+        }
+
+        /* Enhanced Upload Zone */
+        .upload-zone {
+            background: linear-gradient(135deg, var(--sl-color-primary-50) 0%, white 100%);
+            border: 2px dashed var(--sl-color-primary-300) !important;
+            border-radius: var(--sl-border-radius-large);
+            transition: all 0.3s ease;
+        }
+
+        .upload-zone:hover {
+            border-color: var(--sl-color-primary-500) !important;
+            background: linear-gradient(135deg, var(--sl-color-primary-100) 0%, white 100%);
+        }
+
+        .timeline-container img {
+            transition: transform 0.3s ease;
+        }
+
+        .timeline-container .timeline-item:hover img {
+            transform: scale(1.02);
+        }
+
+        .analysis-card::part(base),
+        .timeline-item::part(base) {
+            box-shadow: var(--sl-shadow-large);
+            border: 2px solid var(--sl-color-neutral-200);
+            background-color: #ffffff;
+            /*transition: all 0.3s ease;*/
+        }
+
+        .interactive-result {
+            transition: all 0.3s ease;
+        }
+
+        .interactive-result:hover {
+            border-color: var(--sl-color-primary-300) !important;
+            box-shadow: var(--sl-shadow-large) !important;
+        }
+
+        .timeline-group::part(base) {
+            box-shadow: none;
+            background: transparent;
+            border: none;
+        }
+
+        .timeline-group::part(header) {
+            border-bottom: none;
+            padding: 0 0 1rem 0;
+        }
+
+        .timeline-group::part(body) {
+            padding: 0;
+        }
+
+        .timeline-container {
+            position: relative;
+            padding-left: 2.5rem;
+            padding-bottom: 2rem;
+            display: flex;
+            flex-direction: column;
+            gap: 2rem;
+        }
+
+        .timeline-container::before {
+            content: '';
+            position: absolute;
+            left: 0.5rem;
+            top: 0.75rem;
+            bottom: 2rem;
+            width: 2px;
+            background-color: var(--sl-color-primary-200);
+            z-index: 0;
+        }
+
+        .timeline-dot {
+            position: absolute;
+            left: calc(-2rem + 1px);
+            top: 50%;
+            transform: translate(-50%, -50%);
+            width: 14px;
+            height: 14px;
+            border-radius: 50%;
+            background-color: var(--sl-color-primary-600);
+            box-shadow: 0 0 0 5px var(--sl-color-primary-100), 0 0 12px rgba(13, 114, 255, 0.3);
+            z-index: 1;
+        }
+
+        [x-cloak] {
+            display: none !important;
+        }
+
+        /* Floating Action Button */
+        .fab {
+            position: fixed;
+            bottom: 2.5rem;
+            right: 2.5rem;
+            width: 60px;
+            height: 60px;
+            border-radius: 50%;
+            background-color: var(--sl-color-primary-600);
+            color: white;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            box-shadow: 0 10px 25px -5px rgba(16, 185, 129, 0.4);
+            cursor: pointer;
+            z-index: 1000;
+            transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+            border: none;
+            text-decoration: none;
+        }
+
+        .fab:hover {
+            background-color: var(--sl-color-primary-700);
+            transform: scale(1.15) rotate(10deg);
+            box-shadow: 0 15px 30px -5px rgba(16, 185, 129, 0.5);
+        }
+
+        .fab:active {
+            transform: scale(0.95);
+        }
+
+        .fab sl-icon {
+            font-size: 1.5rem;
+        }
+
+        #header {
+            margin-bottom: 3rem;
+            text-align: center;
+        }
+
+        .analysis-history-container {
+            border-top: 1px solid var(--sl-color-neutral-100);
+            padding: 0 2rem 2rem 2rem;
+        }
+
+        .analysis-image-container {
+            position: relative;
+            width: 300px;
+            height: 300px;
+            background: var(--sl-color-neutral-100);
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            border-radius: var(--sl-border-radius-medium);
+            overflow: hidden;
+            cursor: pointer;
+        }
+
+        .analysis-layout {
+            display: flex;
+            gap: 1.5rem;
+            align-items: flex-start;
+            flex-wrap: nowrap;
+        }
+
+        .analysis-details-column {
+            flex-grow: 1;
+            min-width: 0;
+        }
+
+        @media (max-width: 600px) {
+
+
+            .container {
+                padding: 1.5rem 0;
+            }
+
+            #header {
+                margin-bottom: 1.5rem;
+            }
+
+            .analysis-layout {
+                flex-direction: column;
+                align-items: stretch;
+            }
+
+            .analysis-image-container {
+                width: 100%;
+                height: auto;
+                aspect-ratio: 1;
+            }
+
+            .card-premium.main-upload-card,
+            .card-premium.main-upload-card:hover {
+                border: none;
+                box-shadow: none;
+                border-radius: 0;
+                margin-bottom: 0 !important;
+            }
+
+            sl-card.timeline-group {
+                box-shadow: none;
+                border: none;
+            }
+
+            .card-premium.main-upload-card::part(base) {
+                border: none;
+                box-shadow: none;
+                border-radius: 0;
+            }
+
+            .analysis-history-container {
+                border-top: none;
+                padding: 0;
+            }
+
+            .timeline-container {
+                border: none;
+                box-shadow: none;
+                padding-left: 0;
+            }
+
+            .timeline-container::before {
+                display: none;
+            }
+
+            .timeline-dot {
+                position: static;
+                transform: none;
+            }
+
+            .timeline-item,
+            .timeline-item::part(base) {
+                border: none;
+                box-shadow: none;
+                border-radius: 0;
+            }
+
+            .fab {
+                bottom: 1.5rem;
+                right: 1.5rem;
+                width: 54px;
+                height: 54px;
+            }
+        }
+    </style>
+</head>
+
+<body x-data="dermatologApp()">
+
+    <div class="container">
+
+        <!-- Header -->
+        <div id="header">
+            <div
+                style="display: flex; align-items: center; justify-content: center; gap: 0.75rem; margin-bottom: 0.5rem;">
+                <sl-icon name="activity" style="font-size: 2rem; color: var(--brand-primary);"></sl-icon>
+                <h1 style="margin: 0; font-weight: 700; letter-spacing: -0.025em; font-size: 1.75rem;">Dermatolog <span
+                        style="color: var(--sl-color-primary-600)">AI Scan</span></h1>
+            </div>
+            <p style="color: var(--sl-color-neutral-500); max-width: 500px; margin: 0 auto; line-height: 1.6;">
+                A privacy-first, free, and easy-to-use skin lesion scan app powered by latest AI models.
+            </p>
+        </div>
+
+        <!-- Drag & Drop Upload Zone (Clean) -->
+        <sl-card class="card-premium main-upload-card" style="margin-bottom: 1.5rem; overflow: hidden; width: 100%;">
+            <div class="upload-zone" @dragover.prevent="dragover = true" @dragleave.prevent="dragover = false"
+                @drop.prevent="handleDrop($event)" @click="$refs.fileInput.click()"
+                style="text-align: center; padding: 4rem 2rem 2rem 2rem; cursor: pointer;">
+
+                <div style="display: flex; flex-direction: column; align-items: center; gap: 1.25rem;">
+                    <div
+                        style="background: white; width: 64px; height: 64px; border-radius: 50%; display: flex; align-items: center; justify-content: center; box-shadow: var(--sl-shadow-sm);">
+                        <sl-icon name="search" style="font-size: 2rem; color: var(--sl-color-primary-600);"></sl-icon>
+                    </div>
+
+                    <div>
+                        <h3 style="margin: 0 0 0.25rem 0; font-size: 1.25rem; font-weight: 600;">Secure Image Analysis
+                        </h3>
+                        <p style="color: var(--sl-color-neutral-500); font-size: 0.95rem; margin: 0;">
+                            Drag photos here or click to browse
+                        </p>
+                    </div>
+
+                    <div style="font-size: 0.75rem; color: var(--sl-color-neutral-400);">
+                        <sl-icon name="keyboard" style="vertical-align: middle;"></sl-icon> Press Ctrl+V to paste images
+                    </div>
+
+                    <!-- Action Buttons Inside Zone -->
+                    <div style="display: flex; gap: 1rem; flex-wrap: wrap; justify-content: center; margin-top: 0.5rem;"
+                        @click.stop>
+                        <sl-button variant="primary" pill @click.stop="$refs.cameraInput.click()"
+                            style="min-width: 140px;">
+                            <sl-icon slot="prefix" name="camera"></sl-icon>
+                            Capture Image
+                        </sl-button>
+                        <sl-button pill @click.stop="$refs.fileInput.click()">
+                            <sl-icon slot="prefix" name="image"></sl-icon>
+                            Library
+                        </sl-button>
+                    </div>
+                </div>
+
+            </div>
+
+            <!-- Hidden Inputs -->
+            <input type="file" x-ref="fileInput" multiple accept="image/*" style="display: none;"
+                @change="handleFiles($event.target.files)" @click.stop>
+            <input type="file" x-ref="cameraInput" accept="image/*" capture="environment" style="display: none;"
+                @change="handleFiles($event.target.files)" @click.stop>
+
+            <!-- Analysis History Inside Card -->
+            <div class="analysis-history-container">
+                <!-- Timeline View -->
+                <div
+                    style="display: flex; justify-content: space-between; align-items: center; padding-top: 1.5rem; margin-bottom: 1rem;">
+                    <h3 x-show="timeline.length > 0" style="margin: 0; font-size: 1.1rem; font-weight: 600;">Analysis
+                        History</h3>
+                    <template x-if="timeline.length > 0">
+                        <sl-button variant="danger" outline pill size="small" @click="clearSession">
+                            <sl-icon slot="prefix" name="trash"></sl-icon>
+                            Clear History
+                        </sl-button>
+                    </template>
+                </div>
+
+                <template x-if="timeline.length === 0">
+                    <div style="text-align: center; padding: 4rem 0; color: var(--sl-color-neutral-400);">
+                        <sl-icon name="image" style="font-size: 3rem; margin-bottom: 1rem; opacity: 0.3;"></sl-icon>
+                        <div style="font-size: 1.1rem; font-weight: 500;">History Empty</div>
+                        <p style="font-size: 0.9rem; margin-top: 0.25rem;">Upload medical images to begin AI assessment.
+                        </p>
+                    </div>
+                </template>
+
+                <div class="timeline-container">
+                    <template x-for="item in timeline" :key="item.date">
+
+                        <!-- Virtual Directory (Group) -->
+                        <template x-if="item.type === 'directory'">
+                            <sl-card class="timeline-group">
+                                <div slot="header"
+                                    style="display: flex; justify-content: space-between; align-items: center;">
+                                    <div style="display: flex; align-items: center; gap: 0.75rem; position: relative;">
+                                        <div class="timeline-dot"></div>
+                                        <strong x-text="item.date"
+                                            style="font-size: 1.15rem; color: var(--sl-color-neutral-800);"></strong>
+                                    </div>
+                                    <sl-badge variant="primary" pill
+                                        x-text="item.items.length === 1 ? '1 Photo' : item.items.length + ' Photos'"></sl-badge>
+                                </div>
+
+                                <!-- View Mode: Grid (Default) -->
+                                <template x-if="Object.keys(analysisResults).length === 0">
+                                    <div
+                                        style="display: grid; grid-template-columns: repeat(auto-fill, minmax(100px, 1fr)); gap: 0.5rem;">
+                                        <template x-for="photo in item.items" :key="photo.id">
+                                            <div style="position: relative; cursor: pointer;"
+                                                :data-analyzed="!!analysisResults[photo.id]">
+                                                <img :src="photo.local_content || '/api/photos/' + photo.id + '/content'"
+                                                    style="width: 100%; aspect-ratio: 1; object-fit: cover; border-radius: var(--sl-border-radius-medium);"
+                                                    @click="openEditModal(photo)">
+
+                                                <!-- Processing Overlay -->
+                                                <template x-if="currentAnalysisId === photo.id">
+                                                    <div
+                                                        style="position: absolute; inset: 0; background: rgba(255,255,255,0.7); display: flex; align-items: center; justify-content: center; border-radius: var(--sl-border-radius-medium);">
+                                                        <sl-spinner
+                                                            style="font-size: 2rem; --track-width: 4px; color: var(--sl-color-primary-600);"></sl-spinner>
+                                                    </div>
+                                                </template>
+
+                                                <!-- Waiting Overlay -->
+                                                <template
+                                                    x-if="loading && !analysisResults[photo.id] && currentAnalysisId !== photo.id">
+                                                    <div
+                                                        style="position: absolute; inset: 0; background: rgba(0,0,0,0.5); display: flex; align-items: center; justify-content: center; color: white; border-radius: var(--sl-border-radius-medium);">
+                                                        <sl-icon name="hourglass-split"
+                                                            style="font-size: 2rem; opacity: 0.8;"></sl-icon>
+                                                    </div>
+                                                </template>
+
+                                                <!-- Primary Result Overlay -->
+                                                <template x-if="analysisResults[photo.id]">
+                                                    <div
+                                                        style="position: absolute; bottom: 0; left: 0; right: 0; background: rgba(0,0,0,0.85); color: white; padding: 2px; font-size: 0.6rem; text-align: center; border-bottom-left-radius: var(--sl-border-radius-medium); border-bottom-right-radius: var(--sl-border-radius-medium);">
+                                                        <div x-text="analysisResults[photo.id].interpretation ? analysisResults[photo.id].interpretation.annotation : analysisResults[photo.id].prediction.label"
+                                                            :style="'color: ' + (analysisResults[photo.id].interpretation ? getInterpretationColor(analysisResults[photo.id].interpretation.color_hint) : 'white')"
+                                                            style="white-space: nowrap; overflow: hidden; text-overflow: ellipsis; font-weight: bold;">
+                                                        </div>
+                                                    </div>
+                                                </template>
+
+                                            </div>
+                                        </template>
+                                    </div>
+                                </template>
+
+                                <!-- View Mode: List (Analysis Mode) -->
+                                <template x-if="Object.keys(analysisResults).length > 0">
+                                    <div style="display: flex; flex-direction: column; gap: 1rem;">
+                                        <template x-for="photo in item.items" :key="photo.id">
+                                            <sl-card class="analysis-card">
+                                                <div class="analysis-layout">
+
+                                                    <!-- Image Pair Container -->
+                                                    <div style="display: flex; gap: 1rem;">
+                                                        <!-- Original Image -->
+                                                        <div style="text-align: center;"
+                                                            :data-analyzed="!!analysisResults[photo.id]">
+                                                            <div class="analysis-image-container"
+                                                                @click="openEditModal(photo)">
+                                                                <img :src="photo.local_content || '/api/photos/' + photo.id + '/content'"
+                                                                    :alt="'Original Image: ' + photo.filename"
+                                                                    style="width: 100%; height: 100%; object-fit: contain;">
+
+                                                                <!-- Processing Overlay -->
+                                                                <template x-if="currentAnalysisId === photo.id">
+                                                                    <div
+                                                                        style="position: absolute; inset: 0; background: rgba(255,255,255,0.7); display: flex; align-items: center; justify-content: center;">
+                                                                        <sl-spinner
+                                                                            style="font-size: 3rem; --track-width: 6px; color: var(--sl-color-primary-600);"></sl-spinner>
+                                                                    </div>
+                                                                </template>
+
+                                                                <!-- Waiting Overlay -->
+                                                                <template
+                                                                    x-if="loading && !analysisResults[photo.id] && currentAnalysisId !== photo.id">
+                                                                    <div
+                                                                        style="position: absolute; inset: 0; background: rgba(0,0,0,0.5); display: flex; align-items: center; justify-content: center; color: white;">
+                                                                        <sl-icon name="hourglass-split"
+                                                                            style="font-size: 3rem; opacity: 0.8;"></sl-icon>
+                                                                    </div>
+                                                                </template>
+                                                            </div>
+                                                            <div style="margin-top: 0.5rem; color: var(--sl-color-neutral-500); font-size: 0.8rem;"
+                                                                x-text="photo.filename"></div>
+                                                        </div>
+                                                    </div>
+
+                                                    <!-- Analysis Details -->
+                                                    <div class="analysis-details-column">
+                                                        <template x-if="analysisResults[photo.id]">
+                                                            <div
+                                                                style="display: flex; flex-direction: column; gap: 1rem;">
+                                                                <div
+                                                                    style="display: flex; flex-direction: column; gap: 1rem;">
+                                                                    <!-- Simplified Main Result -->
+                                                                    <div
+                                                                        :style="'padding: 1.5rem; border-radius: var(--sl-border-radius-large); background: white; transition: all 0.4s ease; box-shadow: var(--sl-shadow-large); border: 2px solid ' + (analysisResults[photo.id] && analysisResults[photo.id].interpretation ? getInterpretationColor(analysisResults[photo.id].interpretation.color_hint) : 'var(--sl-color-primary-300)')">
+                                                                        <div
+                                                                            style="display: flex; align-items: center; gap: 1rem;">
+                                                                            <div
+                                                                                :style="'width: 48px; height: 48px; border-radius: 50%; display: flex; align-items: center; justify-content: center; background: ' + (analysisResults[photo.id] && analysisResults[photo.id].interpretation ? getInterpretationColor(analysisResults[photo.id].interpretation.color_hint) + '22' : 'var(--sl-color-primary-50)')">
+                                                                                <sl-icon
+                                                                                    :name="analysisResults[photo.id]?.interpretation ? getInterpretationIcon(analysisResults[photo.id].interpretation.color_hint) : 'activity'"
+                                                                                    :style="'font-size: 1.5rem; color: ' + (analysisResults[photo.id]?.interpretation ? getInterpretationColor(analysisResults[photo.id].interpretation.color_hint) : 'var(--sl-color-primary-600)')"></sl-icon>
+                                                                            </div>
+                                                                            <div>
+                                                                                <div
+                                                                                    style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 0.25rem;">
+                                                                                    <div
+                                                                                        style="font-size: 0.8rem; color: var(--sl-color-neutral-500); text-transform: uppercase; font-weight: 700; letter-spacing: 0.05em;">
+                                                                                        AI Scan result
+                                                                                    </div>
+                                                                                </div>
+                                                                                <h3 style="margin: 0; font-size: 1.25rem; font-weight: 600;"
+                                                                                    :style="'color: ' + (analysisResults[photo.id] && analysisResults[photo.id].interpretation ? getInterpretationColor(analysisResults[photo.id].interpretation.color_hint) : 'var(--sl-color-neutral-900)')"
+                                                                                    x-text="analysisResults[photo.id].interpretation ? analysisResults[photo.id].interpretation.annotation : analysisResults[photo.id].prediction.label">
+                                                                                </h3>
+
+                                                                                <template
+                                                                                    x-if="analysisResults[photo.id] && analysisResults[photo.id].prediction && !analysisResults[photo.id].prediction.is_healthy">
+                                                                                    <div
+                                                                                        style="display: flex; align-items: center; gap: 0.5rem; margin-top: 0.25rem;">
+                                                                                        <span
+                                                                                            style="font-size: 0.9rem; font-weight: 600; color: var(--sl-color-neutral-600);">
+                                                                                            Top Classification: <span
+                                                                                                x-text="analysisResults[photo.id].prediction.label"
+                                                                                                style="color: var(--sl-color-neutral-900);"></span>
+                                                                                        </span>
+                                                                                        <span
+                                                                                            style="color: var(--sl-color-neutral-400); font-size: 0.8rem;"
+                                                                                            x-text="'(' + Math.round(analysisResults[photo.id].prediction.score * 100) + '%)'"></span>
+
+                                                                                        <template
+                                                                                            x-if="analysisResults[photo.id] && analysisResults[photo.id].interpretation">
+                                                                                            <sl-badge
+                                                                                                :variant="getBadgeVariant(analysisResults[photo.id].interpretation.confidence_color)"
+                                                                                                pill size="small"
+                                                                                                style="margin-left: 0.5rem;">
+                                                                                                <span
+                                                                                                    x-text="analysisResults[photo.id].interpretation.confidence_label"></span>
+                                                                                            </sl-badge>
+                                                                                        </template>
+                                                                                    </div>
+                                                                                </template>
+                                                                            </div>
+                                                                        </div>
+
+                                                                    </div>
+
+                                                                    <!-- All Predictions Section (Always available if analyzed) -->
+                                                                    <sl-details class="interactive-result"
+                                                                        style="--border-width: 0; font-size: 0.8rem; margin-top: 0.5rem; border: 1px solid var(--sl-color-neutral-200); border-radius: var(--sl-border-radius-medium); overflow: hidden; background: var(--sl-color-neutral-50);">
+                                                                        <div slot="summary"
+                                                                            style="display: flex; align-items: center; gap: 0.5rem; font-weight: 600; color: var(--sl-color-neutral-700);">
+                                                                            <sl-icon name="list-stars"></sl-icon>
+                                                                            Detailed Predictions & Confidences
+                                                                        </div>
+                                                                        <div
+                                                                            style="padding: 0.75rem; display: flex; flex-direction: column; gap: 0.5rem; background: var(--sl-color-neutral-50);">
+
+                                                                            <div
+                                                                                style="font-size: 0.7rem; text-transform: uppercase; color: var(--sl-color-neutral-500); letter-spacing: 0.05em; margin-bottom: 0.25rem;">
+                                                                                <span
+                                                                                    x-text="analysisResults[photo.id].primary_name || 'Primary Prediction'"></span>
+                                                                            </div>
+                                                                            <template
+                                                                                x-for="p in (analysisResults[photo.id].primary || [])"
+                                                                                :key="p.label">
+                                                                                <div
+                                                                                    style="display: flex; justify-content: space-between; align-items: center; border-bottom: 1px solid var(--sl-color-neutral-200); padding: 0.5rem 0;">
+                                                                                    <span x-text="p.label"
+                                                                                        style="color: var(--sl-color-neutral-800); font-weight: 500;"></span>
+                                                                                    <sl-badge
+                                                                                        :variant="p.score > 0.5 ? 'primary' : 'neutral'"
+                                                                                        size="small" pill
+                                                                                        x-text="(p.score * 100).toFixed(1) + '%'"></sl-badge>
+                                                                                </div>
+                                                                            </template>
+                                                                        </div>
+                                                                    </sl-details>
+
+                                                                    <!-- Saliency Map Toggle  -->
+                                                                    <sl-details class="interactive-result"
+                                                                        summary="View Saliency Map"
+                                                                        @sl-show="fetchSaliency(photo)"
+                                                                        style="--border-width: 0; --background-color: var(--sl-color-neutral-50); font-size: 0.8rem; border: 1px solid var(--sl-color-neutral-200); border-radius: var(--sl-border-radius-medium); margin-top: 0.5rem;">
+                                                                        <div style="padding: 0.5rem 0;">
+                                                                            <template
+                                                                                x-if="!analysisResults[photo.id].saliency_base64">
+                                                                                <div
+                                                                                    style="text-align: center; padding: 1rem;">
+                                                                                    <sl-spinner
+                                                                                        style="font-size: 1.5rem;"></sl-spinner>
+                                                                                    <div
+                                                                                        style="margin-top: 0.5rem; font-size: 0.75rem; color: var(--sl-color-neutral-500);">
+                                                                                        Computing Grad-CAM Heatmap ...
+                                                                                    </div>
+                                                                                </div>
+                                                                            </template>
+                                                                            <template
+                                                                                x-if="analysisResults[photo.id].saliency_base64">
+                                                                                <div>
+                                                                                    <div
+                                                                                        style="position: relative; aspect-ratio: 1; background: var(--sl-color-neutral-100); border-radius: 4px; overflow: hidden;">
+                                                                                        <img :src="analysisResults[photo.id].saliency_base64.startsWith('data:') ? analysisResults[photo.id].saliency_base64 : 'data:image/jpeg;base64,' + analysisResults[photo.id].saliency_base64"
+                                                                                            style="width: 100%; height: 100%; object-fit: contain;"
+                                                                                            loading="lazy">
+                                                                                    </div>
+                                                                                    <p
+                                                                                        style="margin-top: 0.5rem; font-size: 0.75rem; color: var(--sl-color-neutral-500); line-height: 1.4;">
+                                                                                        Red/orange areas indicate
+                                                                                        regions
+                                                                                        that
+                                                                                        most influenced
+                                                                                        the
+                                                                                        primary model's classification.
+                                                                                    </p>
+                                                                                </div>
+                                                                            </template>
+                                                                        </div>
+                                                                    </sl-details>
+
+                                                                    <div style="color: var(--sl-color-neutral-400); font-size: 0.75rem; margin-top: 0.5rem;"
+                                                                        x-text="'Scan executed on: ' + new Date(analysisResults[photo.id].date).toLocaleString()">
+                                                                    </div>
+                                                                </div>
+                                                        </template>
+
+                                                        <template x-if="!analysisResults[photo.id]">
+                                                            <div
+                                                                style="color: var(--sl-color-neutral-400); font-style: italic;">
+                                                                Pending analysis...
+                                                            </div>
+                                                        </template>
+                                                    </div>
+                                                </div>
+                                            </sl-card>
+                                        </template>
+                                    </div>
+                                </template>
+                            </sl-card>
+                        </template>
+
+                        <!-- Single Photo -->
+                        <template x-if="item.type === 'photo'">
+                            <sl-card class="card-premium timeline-item" style="margin-bottom: 1.5rem;"
+                                :data-analyzed="!!analysisResults[item.data.id]">
+                                <div style="display: flex; gap: 1.5rem; padding: 0.5rem;">
+                                    <!-- Evidence Display (Thumbnail + optional Saliency) -->
+                                    <div style="display: flex; gap: 0.75rem;">
+                                        <!-- Thumbnail -->
+                                        <div style="width: 130px; aspect-ratio: 1; cursor: pointer; position: relative; overflow: hidden; border-radius: var(--sl-border-radius-medium); border: 1px solid var(--sl-color-neutral-200);"
+                                            @click="openEditModal(item.data)">
+                                            <img :src="item.data.local_content || '/api/photos/' + item.data.id + '/content'"
+                                                style="width: 100%; height: 100%; object-fit: cover;">
+
+                                            <!-- Result Overlay (Glassmorphism) -->
+                                            <template x-if="analysisResults[item.data.id]">
+                                                <div class="glass-overlay"
+                                                    style="position: absolute; bottom: 0; left: 0; right: 0; color: white; padding: 6px; font-size: 0.7rem; text-align: center;">
+                                                    <div x-text="analysisResults[item.data.id].interpretation ? analysisResults[item.data.id].interpretation.annotation : analysisResults[item.data.id].prediction.label"
+                                                        :style="'color: ' + (analysisResults[item.data.id].interpretation ? getInterpretationColor(analysisResults[item.data.id].interpretation.color_hint) : 'white')"
+                                                        style="font-weight: 700; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; text-transform: uppercase; letter-spacing: 0.02em;">
+                                                    </div>
+                                                </div>
+                                            </template>
+                                        </div>
+
+                                        <!-- Lazy Loaded Saliency Heatmap (Small compare view) -->
+                                        <template
+                                            x-if="analysisResults[item.data.id] && analysisResults[item.data.id].saliency_base64">
+                                            <div
+                                                style="width: 130px; aspect-ratio: 1; border-radius: var(--sl-border-radius-medium); border: 1px solid var(--sl-color-neutral-200); background: var(--sl-color-neutral-100); overflow: hidden;">
+                                                <img :src="analysisResults[item.data.id].saliency_base64.startsWith('data:') ? analysisResults[item.data.id].saliency_base64 : 'data:image/jpeg;base64,' + analysisResults[item.data.id].saliency_base64"
+                                                    style="width: 100%; height: 100%; object-fit: contain;">
+                                            </div>
+                                        </template>
+                                    </div>
+
+                                    <!-- Diagnostic Info -->
+                                    <div
+                                        style="flex-grow: 1; display: flex; flex-direction: column; justify-content: center;">
+                                        <div style="display: flex; justify-content: space-between; align-items: start;">
+                                            <div style="width: 100%;">
+                                                <div
+                                                    style="display: flex; align-items: center; justify-content: space-between; margin-bottom: 0.75rem;">
+                                                    <span
+                                                        style="font-size: 0.75rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; color: var(--sl-color-neutral-400);"
+                                                        x-text="item.date"></span>
+                                                    <sl-badge variant="neutral" pill size="small"
+                                                        x-text="item.data.filename" style="opacity: 0.7;"></sl-badge>
+                                                </div>
+
+                                                <!-- Results List -->
+                                                <template x-if="analysisResults[item.data.id]">
+                                                    <div style="display: flex; flex-direction: column; gap: 0.75rem;">
+                                                        <div
+                                                            :style="'display: flex; align-items: center; gap: 0.75rem; background: white; padding: 1rem; border-radius: var(--sl-border-radius-medium); box-shadow: var(--sl-shadow-medium); transition: all 0.4s ease; border: 2px solid ' + (analysisResults[item.data.id].interpretation ? getInterpretationColor(analysisResults[item.data.id].interpretation.color_hint) : 'var(--sl-color-primary-300)')">
+                                                            <div :style="'background: ' + (analysisResults[item.data.id].prediction.is_healthy ? 'var(--sl-color-success-100)' : 'var(--sl-color-primary-100)')"
+                                                                style="width: 40px; height: 40px; border-radius: 50%; display: flex; align-items: center; justify-content: center;">
+                                                                <sl-icon
+                                                                    :name="analysisResults[item.data.id].prediction.is_healthy ? 'check-lg' : 'activity'"
+                                                                    :style="'font-size: 1.25rem; color: ' + (analysisResults[item.data.id].prediction.is_healthy ? 'var(--sl-color-success-600)' : 'var(--sl-color-primary-600)')"></sl-icon>
+                                                            </div>
+
+                                                            <div style="flex-grow: 1;">
+                                                                <div
+                                                                    style="display: flex; align-items: center; gap: 0.5rem;">
+                                                                    <span style="font-weight: 700; font-size: 1.1rem;"
+                                                                        :style="'color: ' + (analysisResults[item.data.id].interpretation ? getInterpretationColor(analysisResults[item.data.id].interpretation.color_hint) : 'inherit')"
+                                                                        x-text="analysisResults[item.data.id].interpretation ? analysisResults[item.data.id].interpretation.annotation : analysisResults[item.data.id].prediction.label"></span>
+
+                                                                    <template
+                                                                        x-if="analysisResults[item.data.id].interpretation">
+                                                                        <sl-badge
+                                                                            :variant="analysisResults[item.data.id].interpretation.confidence_color === 'red' ? 'danger' : (analysisResults[item.data.id].interpretation.confidence_color === 'yellow' ? 'warning' : 'success')"
+                                                                            pill size="small"
+                                                                            x-text="analysisResults[item.data.id].interpretation.confidence_label"></sl-badge>
+                                                                    </template>
+                                                                </div>
+                                                                <div
+                                                                    style="font-size: 0.85rem; color: var(--sl-color-neutral-500); margin-top: 2px;">
+                                                                    <span
+                                                                        x-text="analysisResults[item.data.id].prediction.is_healthy ? 'No immediate concerns detected' : 'Inconclusive or requires review'"></span>
+                                                                    <span
+                                                                        x-text="' • Conf: ' + Math.round(analysisResults[item.data.id].prediction.score * 100) + '%'"></span>
+                                                                </div>
+                                                            </div>
+                                                        </div>
+                                                        <!-- All Predictions Section (Always available if analyzed) -->
+                                                        <sl-details class="interactive-result"
+                                                            style="--border-width: 0; font-size: 0.8rem; margin-top: 0.5rem; border: 1px solid var(--sl-color-neutral-200); border-radius: var(--sl-border-radius-medium); overflow: hidden; background: var(--sl-color-neutral-50);">
+                                                            <div slot="summary"
+                                                                style="display: flex; align-items: center; gap: 0.5rem; font-weight: 600; color: var(--sl-color-neutral-700);">
+                                                                <sl-icon name="list-stars"></sl-icon>
+                                                                Detailed Predictions & Confidences
+                                                            </div>
+                                                            <div
+                                                                style="padding: 0.75rem; display: flex; flex-direction: column; gap: 0.5rem; background: var(--sl-color-neutral-50);">
+
+                                                                <div
+                                                                    style="font-size: 0.7rem; text-transform: uppercase; color: var(--sl-color-neutral-500); letter-spacing: 0.05em; margin-bottom: 0.25rem;">
+                                                                    <span
+                                                                        x-text="analysisResults[item.data.id].primary_name || 'Primary Prediction'"></span>
+                                                                </div>
+                                                                <template
+                                                                    x-for="p in (analysisResults[item.data.id].primary || [])"
+                                                                    :key="p.label">
+                                                                    <div
+                                                                        style="display: flex; justify-content: space-between; align-items: center; border-bottom: 1px solid var(--sl-color-neutral-200); padding: 0.5rem 0;">
+                                                                        <span x-text="p.label"
+                                                                            style="color: var(--sl-color-neutral-800); font-weight: 500;"></span>
+                                                                        <sl-badge
+                                                                            :variant="p.score > 0.5 ? 'primary' : 'neutral'"
+                                                                            size="small" pill
+                                                                            x-text="(p.score * 100).toFixed(1) + '%'"></sl-badge>
+                                                                    </div>
+                                                                </template>
+                                                            </div>
+                                                        </sl-details>
+
+                                                        <!-- Saliency Map Toggle  -->
+                                                        <sl-details class="interactive-result"
+                                                            summary="View Grad-CAM Saliency Map"
+                                                            @sl-show="fetchSaliency(item.data)"
+                                                            style="--border-width: 0; --background-color: var(--sl-color-neutral-50); font-size: 0.8rem; border: 1px solid var(--sl-color-neutral-200); border-radius: var(--sl-border-radius-medium); margin-top: 0.5rem;">
+                                                            <div style="padding: 0.5rem 0;">
+                                                                <template
+                                                                    x-if="!analysisResults[item.data.id].saliency_base64">
+                                                                    <div style="text-align: center; padding: 1rem;">
+                                                                        <sl-spinner
+                                                                            style="font-size: 1.5rem;"></sl-spinner>
+                                                                        <div
+                                                                            style="margin-top: 0.5rem; font-size: 0.75rem; color: var(--sl-color-neutral-500);">
+                                                                            Computing Grad-CAM Heatmap ...
+                                                                        </div>
+                                                                    </div>
+                                                                </template>
+                                                                <template
+                                                                    x-if="analysisResults[item.data.id].saliency_base64">
+                                                                    <div>
+                                                                        <div
+                                                                            style="position: relative; aspect-ratio: 1; background: var(--sl-color-neutral-100); border-radius: 4px; overflow: hidden;">
+                                                                            <img :src="analysisResults[item.data.id].saliency_base64.startsWith('data:') ? analysisResults[item.data.id].saliency_base64 : 'data:image/jpeg;base64,' + analysisResults[item.data.id].saliency_base64"
+                                                                                style="width: 100%; height: 100%; object-fit: contain;"
+                                                                                loading="lazy">
+                                                                        </div>
+                                                                        <p
+                                                                            style="margin-top: 0.5rem; font-size: 0.75rem; color: var(--sl-color-neutral-500); line-height: 1.4;">
+                                                                            Red/orange areas indicate regions
+                                                                            that
+                                                                            most influenced
+                                                                            the
+                                                                            primary model's classification.
+                                                                        </p>
+                                                                    </div>
+                                                                </template>
+                                                            </div>
+                                                        </sl-details>
+
+                                                        <div
+                                                            style="margin-top: 0.5rem; display: flex; justify-content: flex-end;">
+                                                            <sl-button size="small" pill outline
+                                                                @click="copyReport(item.data.id)">
+                                                                <sl-icon slot="prefix" name="clipboard"></sl-icon>
+                                                                Copy Summary
+                                                            </sl-button>
+                                                        </div>
+                                                    </div>
+                                                </template>
+
+                                                <template x-if="!analysisResults[item.data.id]">
+                                                    <div
+                                                        style="display: flex; align-items: center; gap: 0.5rem; color: var(--sl-color-neutral-400); font-style: italic; padding: 1rem 0;">
+                                                        <sl-spinner style="font-size: 1rem;"></sl-spinner>
+                                                        <span>Running clinical analysis...</span>
+                                                    </div>
+                                                </template>
+                                            </div>
+                                        </div>
+                                    </div>
+                                </div>
+                            </sl-card>
+                        </template>
+
+                    </template>
+                </div>
+            </div>
+        </sl-card>
+
+        <!-- Local Privacy Information -->
+        <div
+            style="display: flex; align-items: center; justify-content: center; gap: 0.5rem; margin-bottom: 2.5rem; color: var(--sl-color-neutral-500); font-size: 0.85rem; padding: 0.5rem; background: var(--sl-color-neutral-50); border-radius: var(--sl-border-radius-medium);">
+            <sl-icon name="shield-check" style="color: var(--sl-color-success-600); font-size: 1.1rem;"></sl-icon>
+            <span>Privacy Mode: Images are stored locally on your device</span>
+        </div>
+
+
+
+
+
+        <!-- Error -->
+        <template x-if="error">
+            <sl-alert variant="danger" open style="margin-top: 1rem;">
+                <sl-icon slot="icon" name="exclamation-octagon"></sl-icon>
+                <strong x-text="error"></strong>
+            </sl-alert>
+        </template>
+
+        <!-- Edit Modal -->
+        <sl-dialog label="Edit Photo Date" class="edit-dialog">
+            <template x-if="editingPhoto">
+                <div>
+                    <img :src="editingPhoto.local_content || '/api/photos/' + editingPhoto.id + '/content'"
+                        style="width: 100%; max-height: 200px; object-fit: contain; margin-bottom: 1rem;">
+                    <sl-input type="date" label="Example Date" x-model="editingDate"></sl-input>
+                </div>
+            </template>
+            <div slot="footer" style="display: flex; justify-content: space-between;">
+                <sl-button variant="danger" outline @click="deletePhotoFromModal">
+                    <sl-icon slot="prefix" name="trash"></sl-icon> Delete
+                </sl-button>
+                <sl-button variant="primary" @click="saveDate">Save</sl-button>
+            </div>
+        </sl-dialog>
+
+        <!-- Floating Action Button -->
+        <button class="fab" @click="$refs.fileInput.click()" title="Upload Image">
+            <sl-icon name="plus-lg"></sl-icon>
+        </button>
+
+        <!-- Debug Toggle & Developer Data -->
+        <div
+            style="margin-top: 4rem; padding: 2rem 0; border-top: 1px solid var(--sl-color-neutral-200); margin-bottom: 2rem; text-align: center;">
+            <sl-switch :checked="debugMode" @sl-change="toggleDebug()">
+                <span style="font-size: 0.8rem; color: var(--sl-color-neutral-500);">Debug Mode</span>
+            </sl-switch>
+        </div>
+
+        <!-- Debug View: All Photos -->
+        <template x-if="debugMode">
+            <div style="margin-top: 1rem; padding-top: 1rem; border-top: 1px solid var(--sl-color-neutral-200);">
+                <h3
+                    style="color: var(--sl-color-neutral-500); font-size: 0.9rem; text-transform: uppercase; text-align: center; margin-bottom: 2rem;">
+                    Debug: All Images <span
+                        style="font-weight: normal; margin-left: 1rem; color: var(--sl-color-neutral-400);"
+                        x-text="'Session: ' + sessionId"></span>
+                    <span style="font-weight: normal; margin-left: 1rem; color: var(--sl-color-primary-500);"
+                        x-text="'Model: ' + modelName"></span>
+                    <span style="font-weight: normal; margin-left: 1rem;"
+                        :style="yoloAvailable ? 'color: var(--sl-color-success-600);' : 'color: var(--sl-color-danger-600);'"
+                        x-text="'YOLO: ' + (yoloAvailable ? 'Available' : 'Missing (Center Crop Fallback)')"></span>
+                </h3>
+
+                <!-- Debug Settings Section -->
+                <div
+                    style="margin-bottom: 1.5rem; display: flex; gap: 2rem; background: var(--sl-color-neutral-50); padding: 1rem; border-radius: var(--sl-border-radius-medium); border: 1px solid var(--sl-color-neutral-200);">
+                    <div style="text-align: left; max-width: 300px; flex: 1;">
+                        <div
+                            style="display: flex; justify-content: space-between; font-size: 0.75rem; color: var(--sl-color-neutral-600); margin-bottom: 0.5rem;">
+                            <strong>Interpretation Margin</strong>
+                            <span style="font-weight: 600; color: var(--sl-color-warning-600)"
+                                x-text="(marginThreshold * 100).toFixed(0) + '%'"></span>
+                        </div>
+                        <sl-range min="0.01" max="0.20" step="0.01" :value="marginThreshold"
+                            @sl-input="marginThreshold = $event.target.value"></sl-range>
+                        <div style="font-size: 0.65rem; color: var(--sl-color-neutral-400); margin-top: 0.25rem;">
+                            Threshold for "Not Clear" mixed tumor/benign results. Move this to calibrate the sensitivity
+                            of
+                            warnings.
+                        </div>
+                    </div>
+                    <div
+                        style="flex: 2; font-size: 0.75rem; color: var(--sl-color-neutral-500); display: flex; align-items: center;">
+                        <sl-icon name="info-circle" style="margin-right: 0.5rem;"></sl-icon>
+                        <span>These settings are for development and calibration. They affect how the model results are
+                            interpreted into human-readable alerts.</span>
+                    </div>
+                </div>
+
+                <div style="display: flex; gap: 1.5rem; overflow-x: auto; padding-bottom: 1rem; margin-bottom: 2rem;">
+                    <template x-for="photo in getAllPhotos()" :key="photo.id">
+                        <div
+                            style="flex: 0 0 auto; text-align: center; display: flex; flex-direction: column; align-items: center; gap: 0.5rem;">
+                            <div style="display: flex; gap: 0.5rem;">
+                                <!-- Raw Image -->
+                                <div style="text-align: center;">
+                                    <img :src="photo.local_content || '/api/photos/' + photo.id + '/content'"
+                                        style="width: 100px; height: 100px; object-fit: cover; border-radius: 4px; border: 1px solid var(--sl-color-neutral-300);">
+                                    <div
+                                        style="font-size: 0.6rem; color: var(--sl-color-neutral-400); margin-top: 2px;">
+                                        Raw
+                                    </div>
+                                </div>
+
+                                <!-- Processed Image -->
+                                <template
+                                    x-if="analysisResults[photo.id] && analysisResults[photo.id].prepared_image_base64">
+                                    <div style="text-align: center;">
+                                        <img :src="analysisResults[photo.id].prepared_image_base64.startsWith('data:') ? analysisResults[photo.id].prepared_image_base64 : 'data:image/jpeg;base64,' + analysisResults[photo.id].prepared_image_base64"
+                                            style="width: 100px; height: 100px; object-fit: contain; background: var(--sl-color-neutral-100); border-radius: 4px; border: 2px solid var(--sl-color-primary-300);">
+                                        <div
+                                            style="font-size: 0.6rem; color: var(--sl-color-primary-500); margin-top: 2px; font-weight: bold;">
+                                            Target (448x448)</div>
+                                    </div>
+                                </template>
+                            </div>
+
+                            <div style="font-size: 0.7rem; color: var(--sl-color-neutral-600); font-weight: 600;"
+                                x-text="photo.filename"></div>
+                            <div style="font-size: 0.6rem;"
+                                :style="analysisResults[photo.id] ? 'color: var(--sl-color-success-600);' : 'color: var(--sl-color-warning-600);'">
+                                <span
+                                    x-text="analysisResults[photo.id] ? 'Analysis Complete' : 'Pending Analysis'"></span>
+                            </div>
+
+                            <!-- Debug: Interpretation Logic -->
+                            <template x-if="analysisResults[photo.id] && analysisResults[photo.id].interpretation">
+                                <div
+                                    style="text-align: left; margin-top: 0.5rem; padding: 0.4rem; background: var(--sl-color-neutral-50); border-radius: 4px; border-left: 2px solid var(--sl-color-neutral-300); width: 100%;">
+                                    <div
+                                        style="font-size: 0.55rem; text-transform: uppercase; color: var(--sl-color-neutral-400); font-weight: bold; margin-bottom: 2px;">
+                                        Interp. Logic</div>
+                                    <template
+                                        x-for="step in analysisResults[photo.id].interpretation.computation_process">
+                                        <div
+                                            style="font-size: 0.55rem; color: var(--sl-color-neutral-500); font-family: var(--sl-font-mono); line-height: 1.2;">
+                                            » <span x-text="step"></span>
+                                        </div>
+                                    </template>
+                                </div>
+                            </template>
+                        </div>
+                    </template>
+                </div>
+
+                <!-- Execution Times Table -->
+                <template x-if="Object.values(analysisResults).some(r => r.execution_times)">
+                    <div style="margin-top: 1rem; margin-bottom: 2rem;">
+                        <sl-card>
+                            <div slot="header" style="font-size: 0.85rem; font-weight: 600;">System Performance (ms)
+                            </div>
+                            <table style="width: 100%; border-collapse: collapse; font-size: 0.8rem;">
+                                <thead>
+                                    <tr style="text-align: left; border-bottom: 1px solid var(--sl-color-neutral-200);">
+                                        <th style="padding: 0.5rem;">Photo</th>
+                                        <th style="padding: 0.5rem;">Preprocess</th>
+                                        <th style="padding: 0.5rem;">Primary AI</th>
+                                    </tr>
+                                </thead>
+                                <tbody>
+                                    <template x-for="photo in getAllPhotos()" :key="'time-' + photo.id">
+                                        <template
+                                            x-if="analysisResults[photo.id] && analysisResults[photo.id].execution_times">
+                                            <tr style="border-bottom: 1px solid var(--sl-color-neutral-100);">
+                                                <td style="padding: 0.5rem; color: var(--sl-color-neutral-500);"
+                                                    x-text="photo.filename"></td>
+                                                <td style="padding: 0.5rem;"
+                                                    x-text="analysisResults[photo.id].execution_times.image_preprocess || '-'">
+                                                </td>
+                                                <td style="padding: 0.5rem;"
+                                                    x-text="analysisResults[photo.id].execution_times.primary_medsiglip || '-'">
+                                                </td>
+                                            </tr>
+                                        </template>
+                                    </template>
+                                </tbody>
+                            </table>
+                        </sl-card>
+                    </div>
+                </template>
+
+                <!-- Model Log Response -->
+                <template x-if="response">
+                    <div style="margin-bottom: 2rem;">
+                        <sl-card class="card-result">
+                            <div slot="header">
+                                <strong>Model Log Response</strong>
+                                <sl-badge pill variant="neutral" x-text="latency + ' ms'"></sl-badge>
+                            </div>
+                            <div style="white-space: pre-wrap; font-family: var(--sl-font-mono); font-size: 0.85rem;"
+                                x-text="response"></div>
+                        </sl-card>
+                    </div>
+                </template>
+
+                <!-- Technical Analysis (Debug Info) Section -->
+                <div style="border-top: 1px solid var(--sl-color-neutral-200); padding-top: 2rem; text-align: left;">
+                    <sl-details style="--border-width: 0; --background-color: transparent;">
+                        <span slot="summary"
+                            style="color: var(--sl-color-neutral-500); font-size: 0.9rem; text-transform: uppercase; font-weight: 600;">
+                            Detailed Inference Reports (Technical Analysis)
+                        </span>
+
+                        <div
+                            style="display: grid; grid-template-columns: repeat(auto-fill, minmax(350px, 1fr)); gap: 1rem; margin-top: 1.5rem;">
+                            <template x-for="photo in getAllPhotos()" :key="'debug-' + photo.id">
+                                <template x-if="analysisResults[photo.id]">
+                                    <sl-card>
+                                        <div slot="header"
+                                            style="display: flex; justify-content: space-between; align-items: center;">
+                                            <strong x-text="photo.filename" style="font-size: 0.85rem;"></strong>
+                                            <sl-badge variant="neutral" pill
+                                                x-text="photo.id.substring(0,8)"></sl-badge>
+                                        </div>
+
+                                        <div style="display: flex; flex-direction: column; gap: 1rem;">
+                                            <!-- Saliency Map Toggle -->
+                                            <sl-details summary="View Grad-CAM Saliency Map"
+                                                @sl-show="fetchSaliency(photo)"
+                                                style="--border-width: 0; --background-color: var(--sl-color-neutral-50); font-size: 0.8rem;">
+                                                <div style="padding: 0.5rem 0;">
+                                                    <template x-if="!analysisResults[photo.id].saliency_base64">
+                                                        <div style="text-align: center; padding: 1rem;">
+                                                            <sl-spinner style="font-size: 1.5rem;"></sl-spinner>
+                                                            <div
+                                                                style="margin-top: 0.5rem; font-size: 0.75rem; color: var(--sl-color-neutral-500);">
+                                                                Computing Grad-CAM Heatmap (Lazy)...
+                                                            </div>
+                                                        </div>
+                                                    </template>
+                                                    <template x-if="analysisResults[photo.id].saliency_base64">
+                                                        <div>
+                                                            <div
+                                                                style="position: relative; aspect-ratio: 1; background: var(--sl-color-neutral-100); border-radius: 4px; overflow: hidden;">
+                                                                <img :src="analysisResults[photo.id].saliency_base64.startsWith('data:') ? analysisResults[photo.id].saliency_base64 : 'data:image/jpeg;base64,' + analysisResults[photo.id].saliency_base64"
+                                                                    style="width: 100%; height: 100%; object-fit: contain;"
+                                                                    loading="lazy">
+                                                            </div>
+                                                            <p
+                                                                style="margin-top: 0.5rem; font-size: 0.75rem; color: var(--sl-color-neutral-500); line-height: 1.4;">
+                                                                Red/orange areas indicate regions that most
+                                                                influenced the primary model's classification.
+                                                            </p>
+                                                        </div>
+                                                    </template>
+                                                </div>
+                                            </sl-details>
+
+                                            <div
+                                                style="font-family: var(--sl-font-mono); font-size: 0.8rem; display: flex; flex-direction: column; gap: 0.75rem;">
+                                                <!-- Primary Scores -->
+                                                <div
+                                                    style="padding: 0.75rem; border-radius: 4px; border: 1px solid var(--sl-color-primary-100); background: var(--sl-color-primary-50);">
+                                                    <div style="display: flex; flex-direction: column; gap: 0.25rem;">
+                                                        <template x-for="p in (analysisResults[photo.id].primary || [])"
+                                                            :key="p.label">
+                                                            <div
+                                                                style="display: flex; justify-content: space-between; align-items: center;">
+                                                                <span x-text="p.label"
+                                                                    style="color: var(--sl-color-neutral-700);"></span>
+                                                                <sl-badge
+                                                                    :variant="p.score > 0.5 ? 'primary' : 'neutral'"
+                                                                    size="small" pill
+                                                                    x-text="(p.score * 100).toFixed(1) + '%'"></sl-badge>
+                                                            </div>
+                                                        </template>
+                                                    </div>
+                                                </div>
+
+                                                <div style="color: var(--sl-color-neutral-500); font-size: 0.7rem;">
+                                                    Execution: <span
+                                                        x-text="analysisResults[photo.id] ? new Date(analysisResults[photo.id].date).toLocaleTimeString() : ''"></span><br>
+                                                    Strategy: <span
+                                                        x-text="analysisResults[photo.id] && analysisResults[photo.id].preprocess_strategy ? analysisResults[photo.id].preprocess_strategy.strategy : ''"></span><br>
+                                                </div>
+                                            </div>
+                                        </div>
+                                    </sl-card>
+                                </template>
+                            </template>
+                        </div>
+                    </sl-details>
+                </div>
+            </div>
+        </template>
+    </div>
+</body>
+
+</html>

bin/app_restart.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+echo "Stopping any existing uvicorn processes..."
+pkill -f uvicorn || true
+
+echo "Starting application server..."
+# Using nohup and python -m uvicorn to ensure correct python path and persistence
+nohup /Users/mstepien/Documents/dev2/py/fasts/venv/bin/python3.10 -m uvicorn app.main:app --host 0.0.0.0 --port 8000 > server.log 2>&1 &
+
+echo "Waiting for server to be ready..."
+# Simple loop to check if port 8000 is open (using curl or netcat logic via python)
+for i in {1..30}; do
+    if curl -s http://localhost:8000/api/health >/dev/null; then
+        echo "Server is UP!"
+        exit 0
+    fi
+    echo "Waiting for server... ($i/30)"
+    sleep 1
+done
+
+echo "Server failed to start. Check server.log:"
+tail -n 20 server.log
+exit 1

bin/app_stop.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+#kill <PID> && source venv/bin/activate && nohup uvicorn main:app --host 127.0.0.1 --port 8080 > server.log 2>&1 &
+
+# Find the PID of the running uvicorn process
+PID=$(ps aux | grep "uvicorn app.main:app" | grep -v grep | awk '{print $2}')
+
+if [ -n "$PID" ]; then
+    echo "Stopping existing application(s) (PIDs: $PID)..."
+    echo "$PID" | xargs kill
+    sleep 2 # Wait for it to shut down
+else
+    echo "No running application found."
+fi

bin/check_models.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# Get the directory where the script is located
+BIN_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+PROJECT_ROOT="$(dirname "$BIN_DIR")"
+
+echo "Checking and downloading models for Dermatolog AI..."
+
+# Use the same python executable as the app (or just python3)
+# Based on previous turns, /usr/local/opt/python@3.8/bin/python3.8 was used
+PYTHON_EXEC="/usr/local/opt/python@3.8/bin/python3.8"
+
+if [ ! -x "$PYTHON_EXEC" ]; then
+    PYTHON_EXEC="python3"
+fi
+
+$PYTHON_EXEC "$BIN_DIR/download_models.py"

bin/cleanup_chromium.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# Script to clear any hanging Chromium/Chrome/Playwright processes
+
+echo "🧹 Cleaning up hanging Chromium and test processes..."
+
+# List of process patterns to target (case-insensitive)
+TARGETS=(
+    #"chromium" "chrome" 
+    "playwright" "ms-playwright")
+
+for target in "${TARGETS[@]}"; do
+    # Check if any processes exist for this target (full command line match)
+    if pgrep -if "$target" > /dev/null; then
+        echo "Killing processes matching: $target"
+        pkill -9 -if "$target"
+    fi
+done
+
+# Also handle specific Playwright driver if it's hanging
+if pgrep -f "playwright-core" > /dev/null; then
+    echo "Killing playwright-core processes..."
+    pkill -9 -f "playwright-core"
+fi
+
+echo "✅ Cleanup complete."

bin/deploy.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+set -e
+
+
+# Load .env file if it exists
+if [ -f .env ]; then
+  export $(grep -v '^#' .env | xargs)
+fi
+
+# Check for PROJECT_ID
+if [ -z "$PROJECT_ID" ] || [ "$PROJECT_ID" == "your-project-id" ]; then
+  echo "Error: PROJECT_ID is not set. Please set it in .env or export it."
+  echo "Example: export PROJECT_ID=my-gcp-project-id"
+  exit 1
+fi
+
+GOOGLE_CLOUD_PROJECT=$PROJECT_ID
+SERVICE_NAME="dermatolog-ai-scan"
+REGION="us-central1"
+# We need enough memory for the model (MedSigLIP) to load.
+# 4GB is the absolute minimum, 8GB is safer.
+MEMORY="8Gi" 
+CPU="2"
+
+echo "========================================================"
+echo "   Deploying $SERVICE_NAME to Cloud Run ($REGION)"
+echo "   Mode: Self-Contained (Local Inference)"
+echo "========================================================"
+
+# 1. Build and Submit Container (Using Cloud Build to inject build args)
+echo "[1/3] Building container image..."
+gcloud builds submit --config cloudbuild.yaml --substitutions=_HF_TOKEN="$HF_TOKEN",_SERVICE_NAME="$SERVICE_NAME" .
+
+# 2. Deploy to Cloud Run
+echo "[2/3] Deploying to Cloud Run..."
+gcloud run deploy $SERVICE_NAME \
+  --image gcr.io/$GOOGLE_CLOUD_PROJECT/$SERVICE_NAME \
+  --region $REGION \
+  --platform managed \
+  --allow-unauthenticated \
+  --memory $MEMORY \
+  --cpu $CPU \
+  --timeout 300 \
+  --concurrency 10 \
+  --set-env-vars="HF_TOKEN=$HF_TOKEN" 
+  # Note: If HF_TOKEN is not set in your local shell, this will be empty.
+  # The app handles missing token by falling back to public model.
+
+echo "========================================================"
+echo "   Deployment Complete!"
+echo "========================================================"

bin/docker-test.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# Helper script to run tests inside the Docker container
+
+echo "Running tests in the 'app' container..."
+docker compose exec app pytest "$@"

bin/download_models.py

@@ -0,0 +1,58 @@
+import os
+import sys
+from huggingface_hub import snapshot_download
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+MODELS = [
+    "google/medsiglip-448"
+]
+
+YOLO_MODELS = [
+    "yolov8n.pt"
+]
+
+def check_and_download():
+    token = os.environ.get("HF_TOKEN")
+    if not token:
+        print("Warning: HF_TOKEN not found in environment. Gated models like MedSigLIP may fail to download.")
+    
+    success = True
+    for model_id in MODELS:
+        print(f"\n--- Checking {model_id} ---")
+        try:
+            # snackshot_download checks if files are already present and only downloads missing pieces
+            path = snapshot_download(
+                repo_id=model_id, 
+                token=token,
+                local_files_only=False # Set to True if we only wanted to check, but user wants to download too
+            )
+            print(f"Model {model_id} is ready at: {path}")
+        except Exception as e:
+            print(f"Error handling {model_id}: {e}")
+            success = False
+
+    # Download YOLO models
+    try:
+        from ultralytics import YOLO
+        for yolo_model in YOLO_MODELS:
+            print(f"\n--- Checking YOLO {yolo_model} ---")
+            try:
+                YOLO(yolo_model)
+                print(f"YOLO Model {yolo_model} is ready.")
+            except Exception as e:
+                print(f"Error handling YOLO {yolo_model}: {e}")
+                success = False
+    except ImportError:
+        print("\nWarning: ultralytics not installed. Skipping YOLO model download.")
+    
+    if success:
+        print("\nAll models are downloaded and verified.")
+    else:
+        print("\nSome models failed to download. Please check your HF_TOKEN and internet connection.")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    check_and_download()

bin/generate-api.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+# Exit on error
+set -e
+
+echo "Generating Python models..."
+
+# Find datamodel-codegen in path or venv
+if command -v datamodel-codegen >/dev/null 2>&1; then
+    CODEGEN_BIN="datamodel-codegen"
+elif [ -f "./venv/bin/datamodel-codegen" ]; then
+    CODEGEN_BIN="./venv/bin/datamodel-codegen"
+else
+    echo "datamodel-codegen not found. Attempting to install..."
+    pip install datamodel-code-generator || ./venv/bin/pip install datamodel-code-generator
+    CODEGEN_BIN="datamodel-codegen"
+    if ! command -v "$CODEGEN_BIN" >/dev/null 2>&1 && [ -f "./venv/bin/datamodel-codegen" ]; then
+        CODEGEN_BIN="./venv/bin/datamodel-codegen"
+    fi
+fi
+
+if ! "$CODEGEN_BIN" --input openapi.yaml --output app/models.py; then
+    echo "Error: Python model generation failed. Check openapi.yaml for syntax errors."
+    exit 1
+fi
+
+echo "API Generation for Python Complete!"

cloudbuild.yaml

@@ -0,0 +1,11 @@
+steps:
+- name: 'gcr.io/cloud-builders/docker'
+  args: 
+  - 'build'
+  - '--build-arg'
+  - 'HF_TOKEN=$_HF_TOKEN'
+  - '-t'
+  - 'europe-west1-docker.pkg.dev/$PROJECT_ID/dermatolog-scan/medgemma-app'
+  - '.'
+images:
+- 'europe-west1-docker.pkg.dev/$PROJECT_ID/dermatolog-scan/medgemma-app'

docker-compose.yml

@@ -0,0 +1,16 @@
+version: '3.8'
+
+services:
+  dermatolog-ai-scan:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    command: uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+    volumes:
+      - .:/app
+    ports:
+      - "8000:8000"
+    environment:
+
+      - PROJECT_ID=${PROJECT_ID}
+      - LOCATION=${LOCATION}

docker-test.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# Helper script to run tests inside the Docker container
+
+echo "Running tests in the 'app' container..."
+docker compose exec app pytest "$@"

generate-api.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+# Exit on error
+set -e
+
+echo "Generating Python models..."
+
+# Find datamodel-codegen in path or venv
+if command -v datamodel-codegen >/dev/null 2>&1; then
+    CODEGEN_BIN="datamodel-codegen"
+elif [ -f "./venv/bin/datamodel-codegen" ]; then
+    CODEGEN_BIN="./venv/bin/datamodel-codegen"
+else
+    echo "datamodel-codegen not found. Attempting to install..."
+    pip install datamodel-code-generator || ./venv/bin/pip install datamodel-code-generator
+    CODEGEN_BIN="datamodel-codegen"
+    if ! command -v "$CODEGEN_BIN" >/dev/null 2>&1 && [ -f "./venv/bin/datamodel-codegen" ]; then
+        CODEGEN_BIN="./venv/bin/datamodel-codegen"
+    fi
+fi
+
+if ! "$CODEGEN_BIN" --input openapi.yaml --output app/models.py; then
+    echo "Error: Python model generation failed. Check openapi.yaml for syntax errors."
+    exit 1
+fi
+
+echo "API Generation for Python Complete!"

openapi.yaml

@@ -0,0 +1,35 @@
+openapi: 3.0.3
+info:
+  title: Dermatolog AI Scan
+  description: AI application for dermatology analysis
+  version: 1.0.0
+paths:
+  /api/health:
+    get:
+      summary: Health check endpoint
+      operationId: health_check
+      responses:
+        '200':
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthCheckResponse'
+components:
+  schemas:
+    HealthCheckResponse:
+      properties:
+        status:
+          type: string
+          title: Status
+        database:
+          type: string
+          title: Database
+        gcp_project:
+          type: string
+          title: Gcp Project
+      type: object
+      required:
+        - status
+        - database
+      title: HealthCheckResponse

package.json

@@ -0,0 +1,38 @@
+{
+    "name": "dermatolog-ai-scan-frontend",
+    "version": "1.0.0",
+    "engines": {
+        "node": ">=16.0.0"
+    },
+    "description": "Frontend JavaScript modules for Dermatolog AI Scan",
+    "type": "module",
+    "scripts": {
+        "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+        "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+        "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+        "generate-api": "bash bin/generate-api.sh"
+    },
+    "devDependencies": {
+        "@jest/globals": "^29.7.0",
+        "jest": "^29.7.0",
+        "jest-environment-jsdom": "^29.7.0"
+    },
+    "jest": {
+        "testEnvironment": "jsdom",
+        "transform": {},
+        "testMatch": [
+            "**/tests/javascript/**/*.test.js"
+        ],
+        "collectCoverageFrom": [
+            "app/static/js/modules/**/*.js"
+        ],
+        "coverageThreshold": {
+            "global": {
+                "branches": 80,
+                "functions": 80,
+                "lines": 80,
+                "statements": 80
+            }
+        }
+    }
+}

pytest.ini

@@ -0,0 +1,17 @@
+[pytest]
+# Playwright configuration
+# Browser tests run in headless mode by default
+# Use --headed flag to run with visible browser when pytest-playwright is installed
+
+# Asyncio configuration
+# Using strict mode to avoid loop interference with non-async tests (like Playwright)
+asyncio_mode = strict
+asyncio_default_fixture_loop_scope = function
+asyncio_default_test_loop_scope = function
+
+# Disable anyio to avoid duplicate runner conflicts
+addopts = -p no:anyio
+
+# Markers
+markers =
+    browser: Browser integration tests using Playwright