Replace llm Space with DIPAug project hub

README.md

@@ -1,63 +1,70 @@
 ---
-title: Tiny Code-Only LLM
-emoji: 🤖
-colorFrom: blue
-colorTo: green
+title: DIPAug Project Hub
+colorFrom: green
+colorTo: blue
 sdk: gradio
-sdk_version: 5.23.0
 app_file: app.py
 pinned: false
+license: mit
 ---
 
-# Tiny Code-Only LLM for Hugging Face Spaces
+# Realistic Digital Image Processing-Driven Data Augmentation for Robust Wheat Leaf Disease Classification and Severity Scoring in Field Conditions
 
-This project builds and runs a very small language model from code only.
+Short titles:
 
-- No API key
-- No OpenAI, Anthropic, Gemini, or other hosted model
-- Pure PyTorch transformer
-- Gradio UI for Hugging Face Spaces
+- `DIPAug-Net` for wheat leaf disease classification
+- `DIPAug-SeverNet` for lesion segmentation and severity scoring
 
-## What it does
+This repository is a Hugging Face-ready project scaffold built from the provided specification. It focuses on:
 
-It trains a compact character-level causal transformer on a bundled text corpus and lets you generate text from a prompt.
+- shared physics-aware DIP augmentation modules
+- phase 1 classification model and evaluation skeletons
+- phase 2 saliency, segmentation, and severity model skeletons
+- config-driven experiments for `E1-E6` and `S1-S5`
+- pytest coverage for the augmentation stack and shared utilities
 
-This is a teaching and starter project, not a production-grade large language model. It is designed to deploy cleanly on CPU in Hugging Face Spaces.
+## Repository Layout
 
-## Project structure
+- `dipauglib/`: shared augmentation, scheduling, sampling, and utility code
+- `dipaugnet/`: phase 1 model, loss, training, and evaluation skeleton
+- `dipaugsevernet/`: phase 2 saliency, multi-task model, loss, and training skeleton
+- `configs/`: YAML experiment configurations
+- `tests/`: unit tests for transforms and shared logic
+- `scripts/`: entrypoints for dataset prep, training, and evaluation
+- `figures/`, `results/`, `notebooks/`: output and analysis directories
 
-```text
-.
-├── app.py
-├── requirements.txt
-├── data/
-│   └── corpus.txt
-└── mini_llm/
-    ├── __init__.py
-    ├── config.py
-    ├── data.py
-    ├── model.py
-    ├── service.py
-    ├── tokenizer.py
-    └── trainer.py
-```
+## What Is Implemented In This Scaffold
+
+- stratified split utilities with fixed seed support
+- ImageNet preprocessing configuration
+- all 8 DIP augmentation classes as Albumentations `DualTransform` implementations
+- adaptive augmentation scheduler
+- class-imbalance-aware sampling helpers
+- DIPAug-Net architecture skeleton with CNN + Transformer fusion
+- DGSM and DIPAug-SeverNet architecture skeleton
+- YAML configurations for the requested ablations
+- a lightweight Gradio project dashboard for Hugging Face Spaces
+
+## What Still Needs Real Training Resources
 
-## Run locally
+- dataset download and checksum validation
+- baseline reproduction runs
+- full training of `E1-E6` and `S1-S5`
+- CEDB, Grad-CAM++, SAM pseudo-mask generation, and full results package
+- publication-quality result figures and final report population
+
+## Quick Start
 
 ```bash
 pip install -r requirements.txt
+python scripts/prepare_dataset.py --help
+python scripts/train_phase1.py --config configs/phase1/e6_full.yaml
+python scripts/train_phase2.py --config configs/phase2/s5_full.yaml
 python app.py
 ```
 
-## Deploy on Hugging Face Spaces
-
-1. Create a new Space.
-2. Choose `Gradio`.
-3. Upload these files.
-4. Space will install `requirements.txt`.
-5. The app will train a small model checkpoint on first use.
-
 ## Notes
 
-- The first training run is intentionally small so it can finish on CPU.
-- You can improve outputs by replacing `data/corpus.txt` with your own dataset and increasing the training steps in `mini_llm/config.py`.
+- This scaffold is intentionally config-driven and dataset-path agnostic.
+- The training code is structured for CUDA-enabled machines, but this repository itself is safe to inspect or host on Hugging Face without a GPU.
+- The Space UI is a project dashboard, not a full training runner.

app.py

@@ -1,100 +1,67 @@
 from pathlib import Path
 
 import gradio as gr
+import yaml
 
-from mini_llm.service import LocalLLMService
 
+PROJECT_ROOT = Path(__file__).resolve().parent
 
-BASE_DIR = Path(__file__).resolve().parent
-service = LocalLLMService(base_dir=BASE_DIR)
 
-
-def run_generation(prompt: str, max_new_tokens: int, temperature: float, top_k: int):
-    text, status = service.generate(
-        prompt=prompt,
-        max_new_tokens=max_new_tokens,
-        temperature=temperature,
-        top_k=top_k,
-    )
-    return text, status
+def list_configs() -> list[str]:
+    return sorted(str(path.relative_to(PROJECT_ROOT)).replace("\\", "/") for path in PROJECT_ROOT.glob("configs/**/*.yaml"))
 
 
-def run_training(epochs: int, learning_rate: float):
-    message = service.force_train(epochs=epochs, learning_rate=learning_rate)
-    return message, service.describe_model()
+def show_config(config_name: str) -> str:
+    if not config_name:
+        return "Select a config."
+    path = PROJECT_ROOT / config_name
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    return yaml.safe_dump(data, sort_keys=False)
 
 
-with gr.Blocks(title="Tiny Code-Only LLM") as demo:
+with gr.Blocks(title="DIPAug Project Hub") as demo:
     gr.Markdown(
         """
-        # Tiny Code-Only LLM
-        A small transformer language model built with PyTorch only.
+        # DIPAug Project Hub
+
+        **Project Title**
+
+        Realistic Digital Image Processing-Driven Data Augmentation for Robust Wheat Leaf Disease Classification and Severity Scoring in Field Conditions
 
-        - No API key
-        - No hosted model service
-        - Designed for Hugging Face Spaces
+        **Short Titles**
+
+        - `DIPAug-Net`
+        - `DIPAug-SeverNet`
+
+        This Hugging Face app is a lightweight dashboard for the project scaffold. It helps inspect the experiment configs and repository structure before training on a proper GPU machine.
         """
     )
 
     with gr.Row():
-        with gr.Column():
-            prompt = gr.Textbox(
-                label="Prompt",
-                value="Once upon a time",
-                lines=6,
-            )
-            max_new_tokens = gr.Slider(
-                label="Max new tokens",
-                minimum=20,
-                maximum=300,
-                value=120,
-                step=10,
+        with gr.Column(scale=2):
+            config_input = gr.Dropdown(label="Experiment Config", choices=list_configs(), value="configs/phase1/e6_full.yaml")
+            config_output = gr.Code(label="YAML", language="yaml", value=show_config("configs/phase1/e6_full.yaml"))
+        with gr.Column(scale=2):
+            gr.Markdown(
+                """
+                ## Included Modules
+
+                - `dipauglib.transforms`: 8 physics-aware augmentations
+                - `dipauglib.schedulers`: adaptive augmentation scheduler
+                - `dipauglib.sampling`: class-imbalance-aware sampling
+                - `dipaugnet`: phase 1 classification pipeline
+                - `dipaugsevernet`: phase 2 segmentation and severity scaffold
+
+                ## Status
+
+                - repository scaffold: ready
+                - configs: ready
+                - tests: included
+                - full training runs: not executed in this dashboard
+                """
             )
-            temperature = gr.Slider(
-                label="Temperature",
-                minimum=0.1,
-                maximum=1.5,
-                value=0.9,
-                step=0.1,
-            )
-            top_k = gr.Slider(
-                label="Top-k",
-                minimum=1,
-                maximum=50,
-                value=20,
-                step=1,
-            )
-            generate_button = gr.Button("Generate Text", variant="primary")
 
-        with gr.Column():
-            output = gr.Textbox(label="Generated Text", lines=16)
-            status = gr.Textbox(label="Status", value=service.describe_model())
-
-    gr.Markdown("## Train or Refresh Model")
-    with gr.Row():
-        epochs = gr.Slider(label="Epochs", minimum=5, maximum=80, value=25, step=5)
-        learning_rate = gr.Slider(
-            label="Learning rate",
-            minimum=0.0001,
-            maximum=0.01,
-            value=0.003,
-            step=0.0001,
-        )
-    train_button = gr.Button("Train Model")
-    train_message = gr.Textbox(label="Training Result")
-    model_info = gr.Textbox(label="Model Info", value=service.describe_model())
-
-    generate_button.click(
-        fn=run_generation,
-        inputs=[prompt, max_new_tokens, temperature, top_k],
-        outputs=[output, status],
-    )
-
-    train_button.click(
-        fn=run_training,
-        inputs=[epochs, learning_rate],
-        outputs=[train_message, model_info],
-    )
+    config_input.change(fn=show_config, inputs=[config_input], outputs=[config_output])
 
 
 if __name__ == "__main__":

configs/baselines/paper1_baselines.yaml

@@ -0,0 +1,15 @@
+baselines:
+  - name: ResNet-50 + Generic Aug
+    family: resnet50
+  - name: EfficientNet-B3 (no aug)
+    family: efficientnet_b3
+  - name: EfficientNet-B3 + Generic Aug
+    family: efficientnet_b3
+  - name: SC-ConvNeXt
+    family: convnext
+  - name: GLNet
+    family: glnet
+  - name: ViT Multi-level Contrast
+    family: vit
+  - name: CropNet
+    family: shallow_cnn

configs/baselines/paper2_baselines.yaml

@@ -0,0 +1,13 @@
+baselines:
+  - name: U-Net
+    family: unet
+  - name: Attention U-Net
+    family: attention_unet
+  - name: DeepLabV3+
+    family: deeplabv3plus
+  - name: PDSNets
+    family: linknet_resnet18
+  - name: DIPAug-Net + Ordinal Head
+    family: dipaugnet_ordinal
+  - name: SegLearner
+    family: severity_baseline

configs/phase1/e1_baseline.yaml

@@ -0,0 +1,19 @@
+project:
+  name: DIPAug-Net
+  phase: phase1
+  experiment_id: E1
+dataset:
+  num_classes: 11
+  image_size: 384
+  split_seed: 42
+augmentation:
+  use_dipaug: false
+  use_aas: false
+  use_ciaa: false
+model:
+  use_dual_branch: false
+training:
+  batch_size: 32
+  epochs: 100
+  optimizer: adamw
+  learning_rate: 1.0e-4

configs/phase1/e2_geometric.yaml

@@ -0,0 +1,20 @@
+project:
+  name: DIPAug-Net
+  phase: phase1
+  experiment_id: E2
+dataset:
+  num_classes: 11
+  image_size: 384
+  split_seed: 42
+augmentation:
+  use_dipaug: false
+  geometric_only: true
+  use_aas: false
+  use_ciaa: false
+model:
+  use_dual_branch: false
+training:
+  batch_size: 32
+  epochs: 100
+  optimizer: adamw
+  learning_rate: 1.0e-4

configs/phase1/e3_dipaug_fixed.yaml

@@ -0,0 +1,20 @@
+project:
+  name: DIPAug-Net
+  phase: phase1
+  experiment_id: E3
+dataset:
+  num_classes: 11
+  image_size: 384
+  split_seed: 42
+augmentation:
+  use_dipaug: true
+  intensity: 0.7
+  use_aas: false
+  use_ciaa: false
+model:
+  use_dual_branch: false
+training:
+  batch_size: 32
+  epochs: 100
+  optimizer: adamw
+  learning_rate: 1.0e-4

configs/phase1/e4_dipaug_aas.yaml

@@ -0,0 +1,20 @@
+project:
+  name: DIPAug-Net
+  phase: phase1
+  experiment_id: E4
+dataset:
+  num_classes: 11
+  image_size: 384
+  split_seed: 42
+augmentation:
+  use_dipaug: true
+  intensity: 0.7
+  use_aas: true
+  use_ciaa: false
+model:
+  use_dual_branch: false
+training:
+  batch_size: 32
+  epochs: 100
+  optimizer: adamw
+  learning_rate: 1.0e-4

configs/phase1/e5_dual_branch.yaml

@@ -0,0 +1,20 @@
+project:
+  name: DIPAug-Net
+  phase: phase1
+  experiment_id: E5
+dataset:
+  num_classes: 11
+  image_size: 384
+  split_seed: 42
+augmentation:
+  use_dipaug: true
+  intensity: 0.7
+  use_aas: false
+  use_ciaa: false
+model:
+  use_dual_branch: true
+training:
+  batch_size: 32
+  epochs: 100
+  optimizer: adamw
+  learning_rate: 1.0e-4

configs/phase1/e6_full.yaml

@@ -0,0 +1,23 @@
+project:
+  name: DIPAug-Net
+  phase: phase1
+  experiment_id: E6
+dataset:
+  num_classes: 11
+  image_size: 384
+  split_seed: 42
+augmentation:
+  use_dipaug: true
+  intensity: 0.7
+  use_aas: true
+  use_ciaa: true
+model:
+  use_dual_branch: true
+loss:
+  type: focal_plus_weighted_ce
+training:
+  batch_size: 32
+  epochs: 100
+  optimizer: adamw
+  learning_rate: 1.0e-4
+  min_learning_rate: 1.0e-6

configs/phase2/s1_baseline.yaml

@@ -0,0 +1,19 @@
+project:
+  name: DIPAug-SeverNet
+  phase: phase2
+  experiment_id: S1
+dataset:
+  num_classes: 11
+  image_size: 384
+  split_seed: 42
+inputs:
+  use_dgsm_channel: false
+pretraining:
+  use_simclr: false
+model:
+  use_segmentation_decoder: false
+loss:
+  multitask: false
+training:
+  warmup_epochs: 20
+  joint_epochs: 80

configs/phase2/s2_segmentation.yaml

@@ -0,0 +1,20 @@
+project:
+  name: DIPAug-SeverNet
+  phase: phase2
+  experiment_id: S2
+dataset:
+  num_classes: 11
+  image_size: 384
+  split_seed: 42
+inputs:
+  use_dgsm_channel: false
+pretraining:
+  use_simclr: false
+model:
+  use_segmentation_decoder: true
+loss:
+  multitask: false
+  segmentation: bce_dice
+training:
+  warmup_epochs: 20
+  joint_epochs: 80

configs/phase2/s3_dgsm.yaml

@@ -0,0 +1,20 @@
+project:
+  name: DIPAug-SeverNet
+  phase: phase2
+  experiment_id: S3
+dataset:
+  num_classes: 11
+  image_size: 384
+  split_seed: 42
+inputs:
+  use_dgsm_channel: true
+pretraining:
+  use_simclr: false
+model:
+  use_segmentation_decoder: true
+loss:
+  multitask: false
+  segmentation: bce_dice
+training:
+  warmup_epochs: 20
+  joint_epochs: 80

configs/phase2/s4_simclr.yaml

@@ -0,0 +1,20 @@
+project:
+  name: DIPAug-SeverNet
+  phase: phase2
+  experiment_id: S4
+dataset:
+  num_classes: 11
+  image_size: 384
+  split_seed: 42
+inputs:
+  use_dgsm_channel: true
+pretraining:
+  use_simclr: true
+model:
+  use_segmentation_decoder: true
+loss:
+  multitask: false
+  segmentation: bce_dice
+training:
+  warmup_epochs: 20
+  joint_epochs: 80

configs/phase2/s5_full.yaml

@@ -0,0 +1,21 @@
+project:
+  name: DIPAug-SeverNet
+  phase: phase2
+  experiment_id: S5
+dataset:
+  num_classes: 11
+  image_size: 384
+  split_seed: 42
+inputs:
+  use_dgsm_channel: true
+pretraining:
+  use_simclr: true
+model:
+  use_segmentation_decoder: true
+loss:
+  multitask: true
+  segmentation: bce_dice
+  uncertainty_weighting: true
+training:
+  warmup_epochs: 20
+  joint_epochs: 80

dipauglib/__init__.py

@@ -0,0 +1 @@
+"""Shared library for DIPAug project components."""

dipauglib/sampling/__init__.py

@@ -0,0 +1,5 @@
+"""Sampling utilities."""
+
+from .class_imbalance import build_weighted_sampler, class_weights_from_counts, minority_class_names
+
+__all__ = ["class_weights_from_counts", "minority_class_names", "build_weighted_sampler"]

dipauglib/sampling/class_imbalance.py

@@ -0,0 +1,30 @@
+"""Class imbalance helpers for WeightedRandomSampler and augmentation scaling."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import torch
+
+
+def class_weights_from_counts(class_counts: dict[str, int]) -> dict[str, float]:
+    """Compute inverse-frequency class weights."""
+
+    total = float(sum(class_counts.values()))
+    num_classes = float(len(class_counts))
+    return {name: total / (num_classes * max(1, count)) for name, count in class_counts.items()}
+
+
+def minority_class_names(class_counts: dict[str, int], threshold_ratio: float = 0.15) -> set[str]:
+    """Return minority class names under the requested ratio."""
+
+    total = float(sum(class_counts.values()))
+    return {name for name, count in class_counts.items() if count / max(total, 1.0) < threshold_ratio}
+
+
+def build_weighted_sampler(labels: Sequence[str], class_counts: dict[str, int]) -> torch.utils.data.WeightedRandomSampler:
+    """Create a weighted sampler from labels."""
+
+    weights = class_weights_from_counts(class_counts)
+    sample_weights = torch.as_tensor([weights[label] for label in labels], dtype=torch.double)
+    return torch.utils.data.WeightedRandomSampler(sample_weights, num_samples=len(sample_weights), replacement=True)

dipauglib/schedulers/__init__.py

@@ -0,0 +1,5 @@
+"""Training schedulers."""
+
+from .adaptive import AdaptiveAugmentationScheduler
+
+__all__ = ["AdaptiveAugmentationScheduler"]

dipauglib/schedulers/adaptive.py

@@ -0,0 +1,27 @@
+"""Adaptive augmentation scheduler."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+
+@dataclass
+class AdaptiveAugmentationScheduler:
+    """Sigmoid curriculum for augmentation intensity."""
+
+    d_min: float = 0.1
+    d_max: float = 1.0
+    t_half: float = 50.0
+    tau: float = 10.0
+
+    def intensity_at(self, epoch: int) -> float:
+        """Return augmentation intensity for an epoch."""
+
+        value = self.d_min + (self.d_max - self.d_min) * (1.0 / (1.0 + math.exp(-(epoch - self.t_half) / self.tau)))
+        return float(value)
+
+    def log_payload(self, epoch: int) -> dict[str, float]:
+        """Return dashboard-friendly payload."""
+
+        return {"epoch": float(epoch), "augmentation_intensity": self.intensity_at(epoch)}

dipauglib/transforms/__init__.py

@@ -0,0 +1,23 @@
+"""Physics-aware image augmentation transforms."""
+
+from .physics import (
+    CastShadow,
+    ColourFade,
+    ColourTempShift,
+    DefocusBlur,
+    DustOverlay,
+    IlluminationGradient,
+    MotionBlur,
+    SensorNoise,
+)
+
+__all__ = [
+    "IlluminationGradient",
+    "CastShadow",
+    "MotionBlur",
+    "DefocusBlur",
+    "ColourTempShift",
+    "ColourFade",
+    "DustOverlay",
+    "SensorNoise",
+]

dipauglib/transforms/physics.py

@@ -0,0 +1,239 @@
+"""Physics-aware augmentation classes compatible with Albumentations.
+
+All transforms inherit from Albumentations ``DualTransform`` so image-mask
+consistency is preserved for downstream segmentation use.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import cv2
+import numpy as np
+from albumentations.core.transforms_interface import DualTransform
+
+
+def _ensure_uint8(image: np.ndarray) -> np.ndarray:
+    if image.dtype == np.uint8:
+        return image.copy()
+    clipped = np.clip(image, 0, 255)
+    return clipped.astype(np.uint8)
+
+
+def _clip_float_image(image: np.ndarray) -> np.ndarray:
+    return np.clip(image, 0, 255).astype(np.uint8)
+
+
+def _scaled_value(intensity: float, low: float, high: float) -> float:
+    return low + (high - low) * float(np.clip(intensity, 0.0, 1.0))
+
+
+def _kelvin_to_rgb(cct_kelvin: float) -> np.ndarray:
+    temperature = max(1000.0, min(40000.0, cct_kelvin)) / 100.0
+
+    if temperature <= 66:
+        red = 255
+        green = 99.4708025861 * math.log(temperature) - 161.1195681661
+        blue = 0 if temperature <= 19 else 138.5177312231 * math.log(temperature - 10) - 305.0447927307
+    else:
+        red = 329.698727446 * ((temperature - 60) ** -0.1332047592)
+        green = 288.1221695283 * ((temperature - 60) ** -0.0755148492)
+        blue = 255
+
+    return np.clip(np.array([red, green, blue], dtype=np.float32), 0, 255)
+
+
+class DIPDualTransform(DualTransform):
+    """Base transform with image-only mutation and mask passthrough."""
+
+    def __init__(self, intensity: float = 1.0, always_apply: bool = False, p: float = 0.5):
+        super().__init__(always_apply=always_apply, p=p)
+        self.intensity = float(np.clip(intensity, 0.0, 1.0))
+
+    def apply_to_mask(self, mask: np.ndarray, **params: Any) -> np.ndarray:
+        return mask
+
+    def get_transform_init_args_names(self) -> tuple[str, ...]:
+        return ("intensity",)
+
+
+class IlluminationGradient(DIPDualTransform):
+    """Apply a bidirectional illumination gradient on LAB L-channel."""
+
+    def get_params(self) -> dict[str, float]:
+        return {
+            "angle": float(np.random.uniform(0.0, 360.0)),
+            "strength": float(_scaled_value(self.intensity, 0.3, 0.8)),
+        }
+
+    def apply(self, img: np.ndarray, angle: float = 0.0, strength: float = 0.5, **params: Any) -> np.ndarray:
+        image = _ensure_uint8(img)
+        h, w = image.shape[:2]
+        yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
+        cx, cy = w / 2.0, h / 2.0
+        theta = np.deg2rad(angle)
+        projection = ((xx - cx) * np.cos(theta) + (yy - cy) * np.sin(theta))
+        projection = projection / (np.max(np.abs(projection)) + 1e-6)
+        gradient = 1.0 + projection * strength * 0.5
+
+        lab = cv2.cvtColor(image, cv2.COLOR_RGB2LAB).astype(np.float32)
+        lab[..., 0] = np.clip(lab[..., 0] * gradient, 0, 255)
+        return cv2.cvtColor(_clip_float_image(lab), cv2.COLOR_LAB2RGB)
+
+
+class CastShadow(DIPDualTransform):
+    """Apply polygonal canopy shadow with penumbra blur."""
+
+    def get_params(self) -> dict[str, float]:
+        return {
+            "area": float(_scaled_value(self.intensity, 0.1, 0.4)),
+            "blur_sigma": float(_scaled_value(self.intensity, 5.0, 20.0)),
+            "vertices": int(np.random.randint(3, 7)),
+        }
+
+    def apply(self, img: np.ndarray, area: float = 0.2, blur_sigma: float = 10.0, vertices: int = 4, **params: Any) -> np.ndarray:
+        image = _ensure_uint8(img)
+        h, w = image.shape[:2]
+        center = np.array([np.random.uniform(0, w), np.random.uniform(0, h)], dtype=np.float32)
+        radius = math.sqrt(max(1.0, area * h * w / math.pi))
+        angles = np.sort(np.random.uniform(0, 2 * math.pi, size=vertices))
+        polygon = []
+        for theta in angles:
+            scale = np.random.uniform(0.6, 1.2)
+            x = center[0] + radius * scale * math.cos(theta)
+            y = center[1] + radius * scale * math.sin(theta)
+            polygon.append([int(np.clip(x, 0, w - 1)), int(np.clip(y, 0, h - 1))])
+
+        mask = np.zeros((h, w), dtype=np.float32)
+        cv2.fillPoly(mask, [np.array(polygon, dtype=np.int32)], 1.0)
+        sigma = max(0.1, blur_sigma)
+        mask = cv2.GaussianBlur(mask, (0, 0), sigmaX=sigma, sigmaY=sigma)
+        alpha = np.expand_dims(np.clip(mask * 0.55, 0.0, 0.8), axis=-1)
+        shaded = image.astype(np.float32) * (1.0 - alpha)
+        return _clip_float_image(shaded)
+
+
+class MotionBlur(DIPDualTransform):
+    """Apply directional linear PSF motion blur."""
+
+    def get_params(self) -> dict[str, float]:
+        kernel_size = int(round(_scaled_value(self.intensity, 5.0, 25.0)))
+        if kernel_size % 2 == 0:
+            kernel_size += 1
+        return {
+            "kernel_size": float(kernel_size),
+            "angle": float(np.random.uniform(0.0, 180.0)),
+        }
+
+    def apply(self, img: np.ndarray, kernel_size: float = 9, angle: float = 0.0, **params: Any) -> np.ndarray:
+        image = _ensure_uint8(img)
+        size = int(kernel_size)
+        kernel = np.zeros((size, size), dtype=np.float32)
+        cv2.line(kernel, (0, size // 2), (size - 1, size // 2), 1, thickness=1)
+        rot_mat = cv2.getRotationMatrix2D((size / 2.0 - 0.5, size / 2.0 - 0.5), angle, 1.0)
+        kernel = cv2.warpAffine(kernel, rot_mat, (size, size))
+        kernel = kernel / (kernel.sum() + 1e-6)
+        return cv2.filter2D(image, -1, kernel)
+
+
+class DefocusBlur(DIPDualTransform):
+    """Apply circular pillbox defocus blur."""
+
+    def get_params(self) -> dict[str, float]:
+        return {"radius": float(_scaled_value(self.intensity, 3.0, 15.0))}
+
+    def apply(self, img: np.ndarray, radius: float = 5.0, **params: Any) -> np.ndarray:
+        image = _ensure_uint8(img)
+        radius_int = max(1, int(round(radius)))
+        size = radius_int * 2 + 1
+        kernel = np.zeros((size, size), dtype=np.float32)
+        cv2.circle(kernel, (radius_int, radius_int), radius_int, 1, thickness=-1)
+        kernel /= kernel.sum() + 1e-6
+        return cv2.filter2D(image, -1, kernel)
+
+
+class ColourTempShift(DIPDualTransform):
+    """Apply approximate correlated colour temperature shift."""
+
+    def get_params(self) -> dict[str, float]:
+        return {"cct_kelvin": float(_scaled_value(self.intensity, 3200.0, 8000.0))}
+
+    def apply(self, img: np.ndarray, cct_kelvin: float = 6500.0, **params: Any) -> np.ndarray:
+        image = _ensure_uint8(img).astype(np.float32)
+        rgb = _kelvin_to_rgb(cct_kelvin) / 255.0
+        neutral = _kelvin_to_rgb(6500.0) / 255.0
+        gain = rgb / np.maximum(neutral, 1e-6)
+        shifted = image * gain.reshape(1, 1, 3)
+        return _clip_float_image(shifted)
+
+
+class ColourFade(DIPDualTransform):
+    """Reduce saturation and adjust gamma on luminance."""
+
+    def get_params(self) -> dict[str, float]:
+        return {
+            "sat_factor": float(_scaled_value(self.intensity, 0.3, 0.7)),
+            "gamma": float(_scaled_value(self.intensity, 0.6, 1.4)),
+        }
+
+    def apply(self, img: np.ndarray, sat_factor: float = 0.5, gamma: float = 1.0, **params: Any) -> np.ndarray:
+        image = _ensure_uint8(img)
+        hsv = cv2.cvtColor(image, cv2.COLOR_RGB2HSV).astype(np.float32)
+        hsv[..., 1] *= 1.0 - sat_factor
+        faded = cv2.cvtColor(_clip_float_image(hsv), cv2.COLOR_HSV2RGB)
+        lab = cv2.cvtColor(faded, cv2.COLOR_RGB2LAB).astype(np.float32)
+        lab[..., 0] = 255.0 * np.power(np.clip(lab[..., 0] / 255.0, 0, 1), gamma)
+        return cv2.cvtColor(_clip_float_image(lab), cv2.COLOR_LAB2RGB)
+
+
+class DustOverlay(DIPDualTransform):
+    """Add semi-transparent dust particles using ellipses."""
+
+    def get_params(self) -> dict[str, float]:
+        return {
+            "n_particles": float(_scaled_value(self.intensity, 50.0, 300.0)),
+            "opacity": float(_scaled_value(self.intensity, 0.2, 0.6)),
+        }
+
+    def apply(self, img: np.ndarray, n_particles: float = 100, opacity: float = 0.3, **params: Any) -> np.ndarray:
+        image = _ensure_uint8(img).astype(np.float32)
+        h, w = image.shape[:2]
+        overlay = np.zeros_like(image, dtype=np.float32)
+        particle_count = int(max(1, round(n_particles)))
+        for _ in range(particle_count):
+            center = (int(np.random.randint(0, w)), int(np.random.randint(0, h)))
+            axes = (int(np.random.randint(1, 6)), int(np.random.randint(1, 6)))
+            angle = float(np.random.uniform(0, 180))
+            color = float(np.random.uniform(180, 255))
+            cv2.ellipse(overlay, center, axes, angle, 0, 360, (color, color, color), -1)
+
+        overlay = cv2.GaussianBlur(overlay, (0, 0), sigmaX=1.5, sigmaY=1.5)
+        dusted = image * (1.0 - opacity * 0.4) + overlay * opacity * 0.35
+        return _clip_float_image(dusted)
+
+
+class SensorNoise(DIPDualTransform):
+    """Apply mixed Gaussian, Poisson, and JPEG noise."""
+
+    def get_params(self) -> dict[str, float]:
+        return {
+            "sigma": float(_scaled_value(self.intensity, 5.0, 30.0)),
+            "jpeg_qf": float(_scaled_value(self.intensity, 40.0, 90.0)),
+        }
+
+    def apply(self, img: np.ndarray, sigma: float = 10.0, jpeg_qf: float = 80.0, **params: Any) -> np.ndarray:
+        image = _ensure_uint8(img).astype(np.float32)
+        gaussian = np.random.normal(0.0, sigma, size=image.shape).astype(np.float32)
+        noisy = image + gaussian
+
+        scaled = np.clip(noisy / 255.0, 0.0, 1.0)
+        poisson = np.random.poisson(scaled * 255.0).astype(np.float32) / 255.0
+        noisy = np.clip(poisson * 255.0, 0.0, 255.0).astype(np.uint8)
+
+        encode_params = [int(cv2.IMWRITE_JPEG_QUALITY), int(np.clip(jpeg_qf, 10, 100))]
+        success, encoded = cv2.imencode(".jpg", cv2.cvtColor(noisy, cv2.COLOR_RGB2BGR), encode_params)
+        if not success:
+            return noisy
+        decoded = cv2.imdecode(encoded, cv2.IMREAD_COLOR)
+        return cv2.cvtColor(decoded, cv2.COLOR_BGR2RGB)

dipauglib/transforms/pipeline.py

@@ -0,0 +1,38 @@
+"""Augmentation pipeline helpers."""
+
+from __future__ import annotations
+
+from albumentations import Compose, Normalize, Resize
+
+from .physics import (
+    CastShadow,
+    ColourFade,
+    ColourTempShift,
+    DefocusBlur,
+    DustOverlay,
+    IlluminationGradient,
+    MotionBlur,
+    SensorNoise,
+)
+
+
+IMAGENET_MEAN = (0.485, 0.456, 0.406)
+IMAGENET_STD = (0.229, 0.224, 0.225)
+
+
+def build_dipaug_pipeline(intensity: float = 1.0, image_size: int = 384) -> Compose:
+    """Build the full DIPAug pipeline."""
+
+    transforms = [
+        Resize(image_size, image_size),
+        IlluminationGradient(intensity=intensity, p=0.35),
+        CastShadow(intensity=intensity, p=0.35),
+        MotionBlur(intensity=intensity, p=0.25),
+        DefocusBlur(intensity=intensity, p=0.25),
+        ColourTempShift(intensity=intensity, p=0.35),
+        ColourFade(intensity=intensity, p=0.35),
+        DustOverlay(intensity=intensity, p=0.25),
+        SensorNoise(intensity=intensity, p=0.35),
+        Normalize(mean=IMAGENET_MEAN, std=IMAGENET_STD),
+    ]
+    return Compose(transforms)

dipauglib/utils/__init__.py

@@ -0,0 +1 @@
+"""Shared project utilities."""

dipauglib/utils/dataset.py

@@ -0,0 +1,53 @@
+"""Dataset split and manifest helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import pandas as pd
+from sklearn.model_selection import StratifiedShuffleSplit
+
+
+@dataclass
+class SplitConfig:
+    """Stratified split configuration."""
+
+    seed: int = 42
+    train_size: float = 0.70
+    val_size: float = 0.15
+    test_size: float = 0.15
+
+
+def build_split_manifest(records: pd.DataFrame, label_column: str, config: SplitConfig = SplitConfig()) -> pd.DataFrame:
+    """Build reproducible 70/15/15 stratified splits."""
+
+    if abs(config.train_size + config.val_size + config.test_size - 1.0) > 1e-6:
+        raise ValueError("Split fractions must sum to 1.0")
+
+    splitter = StratifiedShuffleSplit(n_splits=1, test_size=(1.0 - config.train_size), random_state=config.seed)
+    train_idx, temp_idx = next(splitter.split(records, records[label_column]))
+    train_df = records.iloc[train_idx].copy()
+    temp_df = records.iloc[temp_idx].copy()
+
+    val_ratio_within_temp = config.val_size / (config.val_size + config.test_size)
+    splitter_temp = StratifiedShuffleSplit(n_splits=1, test_size=(1.0 - val_ratio_within_temp), random_state=config.seed)
+    val_inner, test_inner = next(splitter_temp.split(temp_df, temp_df[label_column]))
+
+    val_df = temp_df.iloc[val_inner].copy()
+    test_df = temp_df.iloc[test_inner].copy()
+
+    train_df["split"] = "train"
+    val_df["split"] = "val"
+    test_df["split"] = "test"
+    manifest = pd.concat([train_df, val_df, test_df], ignore_index=True)
+    return manifest
+
+
+def save_manifest(manifest: pd.DataFrame, output_path: str | Path) -> Path:
+    """Save manifest CSV."""
+
+    path = Path(output_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    manifest.to_csv(path, index=False)
+    return path

dipauglib/utils/io.py

@@ -0,0 +1,14 @@
+"""Configuration and file IO utilities."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_yaml(path: str | Path) -> dict[str, Any]:
+    """Load a YAML configuration file."""
+
+    return yaml.safe_load(Path(path).read_text(encoding="utf-8"))

dipauglib/utils/repro.py

@@ -0,0 +1,19 @@
+"""Reproducibility helpers."""
+
+from __future__ import annotations
+
+import random
+
+import numpy as np
+import torch
+
+
+def seed_everything(seed: int = 42) -> None:
+    """Fix Python, NumPy, and PyTorch seeds."""
+
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed_all(seed)
+    torch.backends.cudnn.deterministic = True
+    torch.backends.cudnn.benchmark = False

dipaugnet/__init__.py

@@ -0,0 +1 @@
+"""Phase 1 DIPAug-Net package."""

dipaugnet/evaluation/__init__.py

@@ -0,0 +1 @@
+"""Phase 1 evaluation package."""

dipaugnet/evaluation/metrics.py

@@ -0,0 +1,27 @@
+"""Evaluation helpers for Paper 1."""
+
+from __future__ import annotations
+
+import numpy as np
+from sklearn.metrics import accuracy_score, cohen_kappa_score, f1_score, precision_recall_fscore_support
+
+
+def classification_summary(y_true: list[int], y_pred: list[int]) -> dict[str, float]:
+    """Compute core classification metrics."""
+
+    precision, recall, f1, _ = precision_recall_fscore_support(y_true, y_pred, average="macro", zero_division=0)
+    return {
+        "accuracy": float(accuracy_score(y_true, y_pred)),
+        "macro_precision": float(precision),
+        "macro_recall": float(recall),
+        "macro_f1": float(f1),
+        "cohen_kappa": float(cohen_kappa_score(y_true, y_pred)),
+    }
+
+
+def relative_performance_retention(clean_metric: float, distorted_metric: float) -> float:
+    """Compute relative performance retention."""
+
+    if clean_metric == 0:
+        return 0.0
+    return float(distorted_metric / clean_metric)

dipaugnet/models/__init__.py

@@ -0,0 +1,5 @@
+"""Phase 1 model definitions."""
+
+from .dipaugnet import DIPAugNet
+
+__all__ = ["DIPAugNet"]

dipaugnet/models/dipaugnet.py

@@ -0,0 +1,84 @@
+"""DIPAug-Net architecture skeleton."""
+
+from __future__ import annotations
+
+import torch
+from torch import nn
+import torch.nn.functional as F
+import timm
+
+
+class FeatureProjector(nn.Module):
+    """Project backbone feature maps into a shared embedding dimension."""
+
+    def __init__(self, in_channels: int, out_channels: int = 512):
+        super().__init__()
+        self.proj = nn.Sequential(
+            nn.Conv2d(in_channels, out_channels, kernel_size=1, bias=False),
+            nn.BatchNorm2d(out_channels),
+            nn.GELU(),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.proj(x)
+
+
+class DIPAugNet(nn.Module):
+    """Dual-branch CNN + Transformer classifier with cross-attention fusion."""
+
+    def __init__(self, num_classes: int = 11, embed_dim: int = 512, attn_heads: int = 8, dropout: float = 0.4):
+        super().__init__()
+        self.cnn = timm.create_model(
+            "efficientnet_b3.ra2_in1k",
+            pretrained=True,
+            features_only=True,
+            out_indices=(2, 3),
+        )
+        self.transformer = timm.create_model(
+            "swin_tiny_patch4_window7_224.ms_in1k",
+            pretrained=True,
+            features_only=True,
+            out_indices=(1, 2),
+        )
+
+        cnn_channels = self.cnn.feature_info.channels()
+        tr_channels = self.transformer.feature_info.channels()
+
+        self.cnn_proj_8 = FeatureProjector(cnn_channels[0], embed_dim)
+        self.cnn_proj_16 = FeatureProjector(cnn_channels[1], embed_dim)
+        self.tr_proj_8 = FeatureProjector(tr_channels[0], embed_dim)
+        self.tr_proj_16 = FeatureProjector(tr_channels[1], embed_dim)
+
+        self.cross_attn = nn.MultiheadAttention(embed_dim=embed_dim, num_heads=attn_heads, batch_first=True)
+        self.fusion_proj = nn.Linear(embed_dim, embed_dim)
+        self.head = nn.Sequential(
+            nn.Linear(embed_dim * 3, embed_dim),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(embed_dim, num_classes),
+        )
+
+    def forward(self, x: torch.Tensor) -> dict[str, torch.Tensor]:
+        cnn_8, cnn_16 = self.cnn(x)
+        tr_8, tr_16 = self.transformer(x)
+
+        cnn_8 = self.cnn_proj_8(cnn_8)
+        cnn_16 = self.cnn_proj_16(cnn_16)
+        tr_8 = self.tr_proj_8(tr_8)
+        tr_16 = self.tr_proj_16(tr_16)
+
+        tr_8 = F.interpolate(tr_8, size=cnn_8.shape[-2:], mode="bilinear", align_corners=False)
+        tr_16 = F.interpolate(tr_16, size=cnn_16.shape[-2:], mode="bilinear", align_corners=False)
+
+        queries = tr_16.flatten(2).transpose(1, 2)
+        keys = cnn_16.flatten(2).transpose(1, 2)
+        values = keys
+        fused_tokens, attn_weights = self.cross_attn(queries, keys, values)
+        fused_tokens = self.fusion_proj(fused_tokens)
+
+        pooled_fused = fused_tokens.mean(dim=1)
+        pooled_cnn = F.adaptive_avg_pool2d(cnn_8, output_size=1).flatten(1)
+        pooled_tr = F.adaptive_avg_pool2d(tr_8, output_size=1).flatten(1)
+
+        logits = self.head(torch.cat([pooled_fused, pooled_cnn, pooled_tr], dim=1))
+        return {"logits": logits, "attention_weights": attn_weights}

dipaugnet/training/__init__.py

@@ -0,0 +1 @@
+"""Phase 1 training package."""

dipaugnet/training/engine.py

@@ -0,0 +1,65 @@
+"""Phase 1 training engine skeleton."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import torch
+from torch.cuda.amp import GradScaler, autocast
+
+from dipauglib.schedulers.adaptive import AdaptiveAugmentationScheduler
+
+
+@dataclass
+class TrainState:
+    """Training state bundle."""
+
+    epoch: int = 0
+    best_val_f1: float = 0.0
+    patience_counter: int = 0
+
+
+def train_one_epoch(
+    model: torch.nn.Module,
+    loader: Any,
+    optimizer: torch.optim.Optimizer,
+    criterion: torch.nn.Module,
+    device: torch.device,
+    use_amp: bool = True,
+) -> float:
+    """Train one epoch."""
+
+    model.train()
+    scaler = GradScaler(enabled=use_amp and device.type == "cuda")
+    losses: list[float] = []
+
+    for batch in loader:
+        images = batch["image"].to(device)
+        targets = batch["target"].to(device)
+        optimizer.zero_grad(set_to_none=True)
+        with autocast(enabled=use_amp and device.type == "cuda"):
+            logits = model(images)["logits"]
+            loss = criterion(logits, targets)
+
+        scaler.scale(loss).backward()
+        scaler.unscale_(optimizer)
+        torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
+        scaler.step(optimizer)
+        scaler.update()
+        losses.append(float(loss.detach().cpu()))
+
+    return float(sum(losses) / max(1, len(losses)))
+
+
+def fit_phase1(model: torch.nn.Module, optimizer: torch.optim.Optimizer, scheduler: Any | None = None) -> dict[str, Any]:
+    """Placeholder fit entry for config-driven runners."""
+
+    aug_scheduler = AdaptiveAugmentationScheduler()
+    return {
+        "status": "scaffold_only",
+        "message": "Phase 1 training loop skeleton created.",
+        "initial_aug_intensity": aug_scheduler.intensity_at(0),
+        "mid_aug_intensity": aug_scheduler.intensity_at(50),
+        "scheduler_present": scheduler is not None,
+    }

dipaugnet/training/losses.py

@@ -0,0 +1,33 @@
+"""Classification losses for DIPAug-Net."""
+
+from __future__ import annotations
+
+import torch
+from torch import nn
+import torch.nn.functional as F
+
+
+class WeightedFocalLoss(nn.Module):
+    """Weighted focal loss."""
+
+    def __init__(self, class_weights: torch.Tensor | None = None, gamma: float = 2.0):
+        super().__init__()
+        self.class_weights = class_weights
+        self.gamma = gamma
+
+    def forward(self, logits: torch.Tensor, targets: torch.Tensor) -> torch.Tensor:
+        ce = F.cross_entropy(logits, targets, weight=self.class_weights, reduction="none")
+        pt = torch.exp(-ce)
+        return ((1.0 - pt) ** self.gamma * ce).mean()
+
+
+class DIPAugNetLoss(nn.Module):
+    """Combined focal and weighted CE loss."""
+
+    def __init__(self, class_weights: torch.Tensor | None = None):
+        super().__init__()
+        self.focal = WeightedFocalLoss(class_weights=class_weights, gamma=2.0)
+        self.ce = nn.CrossEntropyLoss(weight=class_weights)
+
+    def forward(self, logits: torch.Tensor, targets: torch.Tensor) -> torch.Tensor:
+        return 0.6 * self.focal(logits, targets) + 0.4 * self.ce(logits, targets)

dipaugsevernet/__init__.py

@@ -0,0 +1 @@
+"""Phase 2 DIPAug-SeverNet package."""

dipaugsevernet/evaluation/__init__.py

@@ -0,0 +1 @@
+"""Phase 2 evaluation package."""

dipaugsevernet/evaluation/metrics.py

@@ -0,0 +1,33 @@
+"""Evaluation metrics for segmentation and severity."""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.stats import pearsonr
+from sklearn.metrics import cohen_kappa_score, mean_absolute_error, mean_squared_error
+
+
+def segmentation_iou(pred_mask: np.ndarray, true_mask: np.ndarray, eps: float = 1e-6) -> float:
+    """Compute binary IoU."""
+
+    pred = pred_mask.astype(bool)
+    truth = true_mask.astype(bool)
+    intersection = np.logical_and(pred, truth).sum()
+    union = np.logical_or(pred, truth).sum()
+    return float((intersection + eps) / (union + eps))
+
+
+def severity_summary(y_true: np.ndarray, y_pred: np.ndarray) -> dict[str, float]:
+    """Compute severity regression metrics."""
+
+    return {
+        "pearson_r": float(pearsonr(y_true, y_pred).statistic) if len(y_true) > 1 else 0.0,
+        "mae": float(mean_absolute_error(y_true, y_pred)),
+        "rmse": float(np.sqrt(mean_squared_error(y_true, y_pred))),
+    }
+
+
+def ordinal_summary(y_true: np.ndarray, y_pred: np.ndarray) -> dict[str, float]:
+    """Compute ordinal metrics."""
+
+    return {"qwk": float(cohen_kappa_score(y_true, y_pred, weights="quadratic"))}

dipaugsevernet/models/__init__.py

@@ -0,0 +1,6 @@
+"""Phase 2 models."""
+
+from .dgsm import DGSM
+from .dipaugsevernet import DIPAugSeverNet
+
+__all__ = ["DGSM", "DIPAugSeverNet"]

dipaugsevernet/models/dgsm.py

@@ -0,0 +1,46 @@
+"""DIP-guided saliency module."""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+
+class DGSM:
+    """Non-trainable OpenCV-based saliency generator."""
+
+    def __init__(self, blur_sigma: float = 15.0, min_component_area: int = 50):
+        self.blur_sigma = blur_sigma
+        self.min_component_area = min_component_area
+
+    def __call__(self, image_rgb: np.ndarray) -> np.ndarray:
+        image = image_rgb.astype(np.uint8)
+        lab = cv2.cvtColor(image, cv2.COLOR_RGB2LAB)
+        hsv = cv2.cvtColor(image, cv2.COLOR_RGB2HSV)
+
+        a_channel = lab[..., 1]
+        s_channel = hsv[..., 1]
+
+        mask_a = cv2.adaptiveThreshold(a_channel, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 31, -2)
+        mask_s = cv2.adaptiveThreshold(s_channel, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY_INV, 31, 2)
+        mask = cv2.bitwise_or(mask_a, mask_s)
+
+        kernel = np.ones((7, 7), dtype=np.uint8)
+        mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
+
+        num_labels, labels, stats, _ = cv2.connectedComponentsWithStats(mask, connectivity=8)
+        filtered = np.zeros_like(mask)
+        for component_idx in range(1, num_labels):
+            area = stats[component_idx, cv2.CC_STAT_AREA]
+            if area >= self.min_component_area:
+                filtered[labels == component_idx] = 255
+
+        saliency = cv2.GaussianBlur(filtered.astype(np.float32) / 255.0, (0, 0), sigmaX=self.blur_sigma, sigmaY=self.blur_sigma)
+        return np.clip(saliency, 0.0, 1.0)
+
+    def concatenate_channel(self, image_rgb: np.ndarray) -> np.ndarray:
+        """Append saliency as 4th channel."""
+
+        saliency = self(image_rgb)[..., None]
+        image = image_rgb.astype(np.float32) / 255.0
+        return np.concatenate([image, saliency], axis=-1)

dipaugsevernet/models/dipaugsevernet.py

@@ -0,0 +1,96 @@
+"""DIPAug-SeverNet architecture scaffold."""
+
+from __future__ import annotations
+
+import torch
+from torch import nn
+import torch.nn.functional as F
+import timm
+
+
+class DecoderBlock(nn.Module):
+    """Simple U-Net style decoder block."""
+
+    def __init__(self, in_channels: int, skip_channels: int, out_channels: int):
+        super().__init__()
+        self.block = nn.Sequential(
+            nn.Conv2d(in_channels + skip_channels, out_channels, kernel_size=3, padding=1, bias=False),
+            nn.BatchNorm2d(out_channels),
+            nn.GELU(),
+            nn.Conv2d(out_channels, out_channels, kernel_size=3, padding=1, bias=False),
+            nn.BatchNorm2d(out_channels),
+            nn.GELU(),
+        )
+
+    def forward(self, x: torch.Tensor, skip: torch.Tensor) -> torch.Tensor:
+        x = F.interpolate(x, size=skip.shape[-2:], mode="bilinear", align_corners=False)
+        return self.block(torch.cat([x, skip], dim=1))
+
+
+class SeverityHead(nn.Module):
+    """Severity regression and ordinal head."""
+
+    def __init__(self, in_features: int):
+        super().__init__()
+        self.backbone = nn.Sequential(
+            nn.Linear(in_features, 256),
+            nn.GELU(),
+            nn.Dropout(0.2),
+            nn.Linear(256, 64),
+            nn.GELU(),
+        )
+        self.regression = nn.Linear(64, 1)
+        self.ordinal = nn.Linear(64, 5)
+
+    def forward(self, x: torch.Tensor) -> dict[str, torch.Tensor]:
+        features = self.backbone(x)
+        return {
+            "severity_score": torch.sigmoid(self.regression(features)),
+            "severity_ordinal_logits": self.ordinal(features),
+        }
+
+
+class DIPAugSeverNet(nn.Module):
+    """Shared-encoder segmentation and severity model scaffold."""
+
+    def __init__(self, num_classes: int = 11):
+        super().__init__()
+        self.encoder = timm.create_model(
+            "efficientnet_b4.ra2_in1k",
+            pretrained=True,
+            in_chans=4,
+            features_only=True,
+            out_indices=(1, 2, 3, 4),
+        )
+
+        channels = self.encoder.feature_info.channels()
+        self.decoder3 = DecoderBlock(channels[3], channels[2], 256)
+        self.decoder2 = DecoderBlock(256, channels[1], 128)
+        self.decoder1 = DecoderBlock(128, channels[0], 64)
+        self.segmentation_head = nn.Conv2d(64, 1, kernel_size=1)
+
+        encoder_out_channels = channels[-1]
+        self.classifier = nn.Linear(encoder_out_channels, num_classes)
+        self.severity_head = SeverityHead(encoder_out_channels * 2)
+        self.log_sigmas = nn.Parameter(torch.zeros(4))
+
+    def forward(self, x: torch.Tensor) -> dict[str, torch.Tensor]:
+        f1, f2, f3, f4 = self.encoder(x)
+        d3 = self.decoder3(f4, f3)
+        d2 = self.decoder2(d3, f2)
+        d1 = self.decoder1(d2, f1)
+        mask_logits = self.segmentation_head(d1)
+        mask_pred = torch.sigmoid(F.interpolate(mask_logits, size=x.shape[-2:], mode="bilinear", align_corners=False))
+
+        encoded = F.adaptive_avg_pool2d(f4, output_size=1).flatten(1)
+        lesion_weighted = F.adaptive_avg_pool2d(f4 * F.interpolate(mask_pred, size=f4.shape[-2:], mode="bilinear", align_corners=False), output_size=1).flatten(1)
+        severity_features = torch.cat([encoded, lesion_weighted], dim=1)
+
+        outputs = {
+            "mask_logits": mask_logits,
+            "mask_pred": mask_pred,
+            "class_logits": self.classifier(encoded),
+            "log_sigmas": self.log_sigmas,
+        }
+        outputs.update(self.severity_head(severity_features))
+        return outputs

dipaugsevernet/training/__init__.py

@@ -0,0 +1 @@
+"""Phase 2 training package."""

dipaugsevernet/training/engine.py

@@ -0,0 +1,15 @@
+"""Phase 2 training engine skeleton."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def fit_phase2(model: Any) -> dict[str, str]:
+    """Placeholder entry for phase 2 training."""
+
+    return {
+        "status": "scaffold_only",
+        "message": "Phase 2 multi-task training skeleton created.",
+        "model_name": type(model).__name__,
+    }

dipaugsevernet/training/losses.py

@@ -0,0 +1,39 @@
+"""Loss functions for DIPAug-SeverNet."""
+
+from __future__ import annotations
+
+import torch
+from torch import nn
+import torch.nn.functional as F
+
+
+def dice_loss(logits: torch.Tensor, targets: torch.Tensor, eps: float = 1e-6) -> torch.Tensor:
+    """Binary dice loss on logits."""
+
+    probs = torch.sigmoid(logits)
+    intersection = (probs * targets).sum(dim=(1, 2, 3))
+    union = probs.sum(dim=(1, 2, 3)) + targets.sum(dim=(1, 2, 3))
+    dice = (2 * intersection + eps) / (union + eps)
+    return 1.0 - dice.mean()
+
+
+def corn_ordinal_loss(logits: torch.Tensor, labels: torch.Tensor) -> torch.Tensor:
+    """Simple CORN-style cumulative ordinal loss approximation."""
+
+    losses = []
+    for threshold_idx in range(logits.shape[1]):
+        targets = (labels > threshold_idx).float()
+        losses.append(F.binary_cross_entropy_with_logits(logits[:, threshold_idx], targets))
+    return torch.stack(losses).mean()
+
+
+class UncertaintyWeightedMultiTaskLoss(nn.Module):
+    """Kendall uncertainty-weighted multi-task loss."""
+
+    def forward(self, losses: dict[str, torch.Tensor], log_sigmas: torch.Tensor) -> torch.Tensor:
+        ordered = [losses["segmentation"], losses["classification"], losses["severity_regression"], losses["severity_ordinal"]]
+        total = torch.zeros(1, device=log_sigmas.device, dtype=log_sigmas.dtype)
+        for idx, loss in enumerate(ordered):
+            sigma_sq = torch.exp(2.0 * log_sigmas[idx])
+            total = total + (0.5 / sigma_sq) * loss + log_sigmas[idx]
+        return total.squeeze(0)

figures/README.md

@@ -0,0 +1,9 @@
+# Figures
+
+This directory is reserved for:
+
+- QC grids
+- architecture diagrams
+- confusion matrices
+- CEDB charts
+- Grad-CAM++ overlays

notebooks/README.md

@@ -0,0 +1,8 @@
+# Notebooks
+
+Use this directory for:
+
+- augmentation QC grids
+- CEDB result analysis
+- Grad-CAM++ inspection
+- severity error analysis

requirements.txt

@@ -1,2 +1,22 @@
-gradio>=5.23.0
-torch>=2.2.0
+gradio==6.10.0
+albumentations>=1.4.18
+numpy>=1.26.0
+opencv-python>=4.10.0
+Pillow>=10.4.0
+PyYAML>=6.0.2
+scikit-image>=0.24.0
+scikit-learn>=1.5.2
+scipy>=1.14.1
+matplotlib>=3.9.2
+seaborn>=0.13.2
+pandas>=2.2.3
+pytest>=8.3.3
+pytest-cov>=5.0.0
+timm>=1.0.11
+torch>=2.4.0
+torchvision>=0.19.0
+segmentation-models-pytorch>=0.3.4
+lightly>=1.5.14
+wandb>=0.18.3
+pytorch-grad-cam>=1.5.4
+coral-pytorch>=1.4.0

results/README.md

@@ -0,0 +1,8 @@
+# Results
+
+This directory is reserved for:
+
+- CSV metrics
+- checkpoints
+- manifests
+- ablation summaries

scripts/evaluate_phase1.py

@@ -0,0 +1,5 @@
+"""Phase 1 evaluation entrypoint."""
+
+from __future__ import annotations
+
+print("Evaluation scaffold for Phase 1 is ready.")

scripts/evaluate_phase2.py

@@ -0,0 +1,5 @@
+"""Phase 2 evaluation entrypoint."""
+
+from __future__ import annotations
+
+print("Evaluation scaffold for Phase 2 is ready.")