Add Maritime monorepo scaffold: backend FastAPI + frontend Next.js + CI/CD workflow

Co-authored-by: Anamitra-Sarkar <202972126+Anamitra-Sarkar@users.noreply.github.com>

.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+.env
+.venv/
+venv/
+env/
+.pytest_cache/
+htmlcov/
+.coverage
+
+# Model weights (download at runtime)
+weights/
+*.pt
+*.pth
+*.onnx

Dockerfile

@@ -0,0 +1,37 @@
+# SUB-SENTINEL backend – Hugging Face Spaces Docker image
+#
+# Build:  docker build -t sub-sentinel-backend .
+# Run:    docker run -p 7860:7860 sub-sentinel-backend
+
+FROM python:3.11-slim
+
+# HF Spaces requires port 7860
+EXPOSE 7860
+
+# Install system dependencies for OpenCV
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libglib2.0-0 \
+    libgl1-mesa-glx \
+    libsm6 \
+    libxext6 \
+    libxrender-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python deps first (cache layer)
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application source
+COPY . .
+
+# Create weights directory (populated at runtime via env / volume)
+RUN mkdir -p weights
+
+# Non-root user for HF Spaces compatibility
+RUN useradd -m appuser && chown -R appuser:appuser /app
+USER appuser
+
+# Start the server on port 7860
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

main.py

@@ -0,0 +1,99 @@
+"""
+SUB-SENTINEL backend – FastAPI application.
+
+Endpoints:
+  POST /process   – accepts an image upload and returns:
+    {
+      enhanced_image_base64 : str,
+      heatmap_base64        : str,
+      detections            : [{class, mapped_label, confidence, bbox:[x1,y1,x2,y2]}],
+      sitrep_text           : str
+    }
+"""
+
+import os
+import logging
+
+from fastapi import FastAPI, File, UploadFile, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+
+from processing import enhance_image, run_detection, build_heatmap
+from sitrep import generate_sitrep
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# App setup
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="SUB-SENTINEL API",
+    description="Acoustic-Visual Forensics & Threat Relay",
+    version="1.0.0",
+)
+
+# CORS – allow Vercel production domain + localhost development
+_ORIGINS = [
+    os.getenv("FRONTEND_ORIGIN", "https://sub-sentinel.vercel.app"),
+    "http://localhost:3000",
+    "http://127.0.0.1:3000",
+]
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ---------------------------------------------------------------------------
+# Routes
+# ---------------------------------------------------------------------------
+
+
+@app.get("/health")
+async def health() -> dict:
+    """Liveness probe."""
+    return {"status": "ok"}
+
+
+@app.post("/process")
+async def process_image(file: UploadFile = File(...)) -> dict:
+    """
+    Accept an image upload and run the full forensic pipeline:
+      1. Underwater image enhancement (FUnIE-GAN fallback → CLAHE)
+      2. YOLOv8n object detection with maritime label mapping
+      3. SSIM-based forensic heatmap generation
+      4. Groq SITREP generation
+    """
+    # Validate content type
+    if not file.content_type or not file.content_type.startswith("image/"):
+        raise HTTPException(status_code=400, detail="File must be an image.")
+
+    try:
+        raw_bytes = await file.read()
+    except Exception as exc:
+        logger.error("Failed to read upload: %s", exc)
+        raise HTTPException(status_code=400, detail="Could not read uploaded file.")
+
+    if not raw_bytes:
+        raise HTTPException(status_code=400, detail="Empty file received.")
+
+    try:
+        enhanced_b64, original_array = enhance_image(raw_bytes)
+        detections = run_detection(original_array)
+        heatmap_b64 = build_heatmap(original_array)
+        sitrep = generate_sitrep(detections)
+    except Exception as exc:
+        logger.exception("Pipeline error: %s", exc)
+        raise HTTPException(status_code=500, detail=f"Processing pipeline failed: {exc}")
+
+    return {
+        "enhanced_image_base64": enhanced_b64,
+        "heatmap_base64": heatmap_b64,
+        "detections": detections,
+        "sitrep_text": sitrep,
+    }

processing.py

@@ -0,0 +1,187 @@
+"""
+Image processing pipeline for SUB-SENTINEL.
+
+Provides three functions:
+  enhance_image(raw_bytes)        → (base64_str, numpy_array)
+  run_detection(image_array)      → list[dict]
+  build_heatmap(image_array)      → base64_str
+
+All heavy-weight model paths gracefully fall back to CPU-friendly alternatives
+when model weights are absent.
+"""
+
+import base64
+import io
+import logging
+from typing import Optional
+
+import cv2
+import numpy as np
+from PIL import Image
+from skimage.metrics import structural_similarity as ssim
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Maritime label mapping for YOLOv8 COCO classes
+# ---------------------------------------------------------------------------
+_LABEL_MAP: dict[str, str] = {
+    "person": "Diver/Swimmer",
+    "boat": "Surface/Sub Threat",
+    "ship": "Surface/Sub Threat",
+    "submarine": "Surface/Sub Threat",
+    "surfboard": "Surface/Sub Threat",
+    # extend as needed
+}
+
+
+def _array_to_base64(img_array: np.ndarray, fmt: str = "JPEG") -> str:
+    """Convert a uint8 numpy array (H×W×C, RGB) to a base-64 data-URI string."""
+    pil_img = Image.fromarray(img_array.astype(np.uint8))
+    buf = io.BytesIO()
+    pil_img.save(buf, format=fmt, quality=90)
+    encoded = base64.b64encode(buf.getvalue()).decode("utf-8")
+    mime = "image/jpeg" if fmt == "JPEG" else "image/png"
+    return f"data:{mime};base64,{encoded}"
+
+
+def _bytes_to_array(raw_bytes: bytes) -> np.ndarray:
+    """Decode raw image bytes to a uint8 RGB numpy array."""
+    nparr = np.frombuffer(raw_bytes, np.uint8)
+    bgr = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+    if bgr is None:
+        raise ValueError("OpenCV could not decode the image.")
+    return cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)
+
+
+# ---------------------------------------------------------------------------
+# 1. Underwater image enhancement
+# ---------------------------------------------------------------------------
+
+
+def _clahe_enhance(rgb: np.ndarray) -> np.ndarray:
+    """
+    CPU-friendly underwater enhancement using CLAHE on LAB colour space.
+    Used when FUnIE-GAN weights are unavailable.
+    """
+    lab = cv2.cvtColor(rgb, cv2.COLOR_RGB2LAB)
+    l_channel, a_channel, b_channel = cv2.split(lab)
+    clahe = cv2.createCLAHE(clipLimit=2.5, tileGridSize=(8, 8))
+    l_channel = clahe.apply(l_channel)
+    # Slight blue-green colour correction typical for underwater footage
+    a_channel = np.clip(a_channel.astype(np.int16) - 5, 0, 255).astype(np.uint8)
+    b_channel = np.clip(b_channel.astype(np.int16) + 10, 0, 255).astype(np.uint8)
+    enhanced_lab = cv2.merge([l_channel, a_channel, b_channel])
+    return cv2.cvtColor(enhanced_lab, cv2.COLOR_LAB2RGB)
+
+
+def _funiegan_enhance(rgb: np.ndarray) -> Optional[np.ndarray]:
+    """
+    Attempt FUnIE-GAN inference via a local ONNX weight file.
+    Returns None if weights are missing so the caller can fall back.
+    """
+    weights_path = "weights/funiegan.onnx"
+    try:
+        import os
+        if not os.path.exists(weights_path):
+            return None
+        net = cv2.dnn.readNetFromONNX(weights_path)
+        h, w = rgb.shape[:2]
+        target_h, target_w = 256, 256
+        resized = cv2.resize(rgb, (target_w, target_h)).astype(np.float32) / 127.5 - 1.0
+        blob = cv2.dnn.blobFromImage(resized)
+        net.setInput(blob)
+        out = net.forward()
+        out_img = ((out[0].transpose(1, 2, 0) + 1.0) * 127.5).clip(0, 255).astype(np.uint8)
+        return cv2.resize(out_img, (w, h))
+    except Exception as exc:
+        logger.warning("FUnIE-GAN inference failed (%s); using CLAHE fallback.", exc)
+        return None
+
+
+def enhance_image(raw_bytes: bytes) -> tuple[str, np.ndarray]:
+    """
+    Enhance an underwater image.
+
+    Returns:
+        (base64_enhanced, original_rgb_array)
+    The original array is returned unchanged for use in downstream steps.
+    """
+    rgb = _bytes_to_array(raw_bytes)
+    enhanced = _funiegan_enhance(rgb)
+    if enhanced is None:
+        enhanced = _clahe_enhance(rgb)
+    return _array_to_base64(enhanced), rgb
+
+
+# ---------------------------------------------------------------------------
+# 2. Object detection (YOLOv8n)
+# ---------------------------------------------------------------------------
+
+
+def run_detection(rgb: np.ndarray) -> list[dict]:
+    """
+    Run YOLOv8n COCO detection and map labels to maritime terminology.
+
+    Returns a list of detection dicts:
+      {class, mapped_label, confidence, bbox: [x1, y1, x2, y2]}
+    """
+    try:
+        from ultralytics import YOLO  # lazy import – large package
+        model = YOLO("yolov8n.pt")    # downloads automatically on first run
+        results = model(rgb, verbose=False)
+    except Exception as exc:
+        logger.warning("YOLOv8n detection failed (%s); returning empty detections.", exc)
+        return []
+
+    detections = []
+    for result in results:
+        if result.boxes is None:
+            continue
+        for box in result.boxes:
+            cls_id = int(box.cls[0])
+            cls_name = model.names.get(cls_id, str(cls_id))
+            conf = float(box.conf[0])
+            x1, y1, x2, y2 = (float(v) for v in box.xyxy[0])
+            detections.append(
+                {
+                    "class": cls_name,
+                    "mapped_label": _LABEL_MAP.get(cls_name, cls_name),
+                    "confidence": round(conf, 4),
+                    "bbox": [round(x1), round(y1), round(x2), round(y2)],
+                }
+            )
+    return detections
+
+
+# ---------------------------------------------------------------------------
+# 3. SSIM-based forensic heatmap
+# ---------------------------------------------------------------------------
+
+
+def build_heatmap(rgb: np.ndarray) -> str:
+    """
+    Generate a forensic heatmap by comparing the original image against a
+    Gaussian-blurred reference.  High SSIM → green; low SSIM → red.
+
+    Returns a base64-encoded PNG heatmap.
+    """
+    gray = cv2.cvtColor(rgb, cv2.COLOR_RGB2GRAY)
+    # Reference: gently blurred version of the same frame
+    blurred = cv2.GaussianBlur(gray, (15, 15), 0)
+
+    # Compute SSIM score map (window-level scores)
+    _, ssim_map = ssim(gray, blurred, full=True, data_range=255)
+
+    # Normalise to [0, 255]
+    ssim_norm = ((ssim_map + 1.0) / 2.0 * 255).clip(0, 255).astype(np.uint8)
+
+    # Map to BGR: low similarity → red (forensic interest), high → green
+    heatmap_bgr = cv2.applyColorMap(ssim_norm, cv2.COLORMAP_RdYlGn if hasattr(cv2, "COLORMAP_RdYlGn") else cv2.COLORMAP_JET)
+
+    # Blend with original for context
+    rgb_bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)
+    overlay = cv2.addWeighted(rgb_bgr, 0.55, heatmap_bgr, 0.45, 0)
+    overlay_rgb = cv2.cvtColor(overlay, cv2.COLOR_BGR2RGB)
+
+    return _array_to_base64(overlay_rgb, fmt="PNG")

requirements.txt

@@ -0,0 +1,13 @@
+fastapi>=0.111.0
+uvicorn[standard]>=0.29.0
+python-multipart>=0.0.9
+Pillow>=10.3.0
+numpy>=1.26.0
+opencv-python-headless>=4.9.0
+scikit-image>=0.23.0
+ultralytics>=8.2.0
+groq>=0.9.0
+httpx>=0.27.0
+pytest>=8.2.0
+pytest-asyncio>=0.23.0
+httpx>=0.27.0

sitrep.py

@@ -0,0 +1,78 @@
+"""
+SITREP generation using the Groq API (llama-3.1-8b-instant).
+
+Falls back to a static template when GROQ_API_KEY is not set or when
+the API call fails, so the system remains functional without credentials.
+"""
+
+import os
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _build_prompt(detections: list[dict]) -> str:
+    """Compose the SITREP prompt from detection results."""
+    if not detections:
+        det_summary = "No objects detected in the current frame."
+    else:
+        lines = []
+        for d in detections:
+            x1, y1, x2, y2 = d["bbox"]
+            lines.append(
+                f"  - {d['mapped_label']} (conf {d['confidence']:.0%}) "
+                f"at pixel coords ({x1},{y1})→({x2},{y2})"
+            )
+        det_summary = "\n".join(lines)
+
+    return (
+        "You are the AI analyst for SUB-SENTINEL, an underwater forensics system.\n"
+        "Generate a concise, military-style SITREP (≤120 words) based on these detections:\n\n"
+        f"{det_summary}\n\n"
+        "Format: SITUATION / ASSESSMENT / RECOMMENDATION. Use clear, direct language."
+    )
+
+
+def _static_sitrep(detections: list[dict]) -> str:
+    """Minimal static fallback when Groq is unavailable."""
+    if not detections:
+        return (
+            "SITUATION: Sensor sweep complete – no contacts.\n"
+            "ASSESSMENT: Area clear.\n"
+            "RECOMMENDATION: Continue routine patrol."
+        )
+    labels = ", ".join({d["mapped_label"] for d in detections})
+    count = len(detections)
+    return (
+        f"SITUATION: {count} contact(s) detected – {labels}.\n"
+        "ASSESSMENT: Requires manual review.\n"
+        "RECOMMENDATION: Dispatch response team and maintain sensor lock."
+    )
+
+
+def generate_sitrep(detections: list[dict]) -> str:
+    """
+    Call Groq llama-3.1-8b-instant to generate a SITREP.
+    Falls back to _static_sitrep if GROQ_API_KEY is absent or on any error.
+    """
+    api_key = os.getenv("GROQ_API_KEY")
+    if not api_key:
+        logger.info("GROQ_API_KEY not set; using static SITREP fallback.")
+        return _static_sitrep(detections)
+
+    try:
+        from groq import Groq  # lazy import
+
+        client = Groq(api_key=api_key)
+        response = client.chat.completions.create(
+            model="llama-3.1-8b-instant",
+            messages=[
+                {"role": "user", "content": _build_prompt(detections)},
+            ],
+            max_tokens=200,
+            temperature=0.4,
+        )
+        return response.choices[0].message.content.strip()
+    except Exception as exc:
+        logger.warning("Groq SITREP generation failed (%s); using static fallback.", exc)
+        return _static_sitrep(detections)

tests/__init__.py

@@ -0,0 +1 @@
+# backend/tests/__init__.py

tests/test_api.py

@@ -0,0 +1,163 @@
+"""
+pytest tests for the SUB-SENTINEL FastAPI backend.
+
+Run:
+    cd backend
+    pytest tests/ -v
+"""
+
+import base64
+import io
+import os
+
+import pytest
+from fastapi.testclient import TestClient
+from PIL import Image
+
+# Ensure we do NOT need a real GROQ_API_KEY for tests
+os.environ.setdefault("GROQ_API_KEY", "")
+
+from main import app  # noqa: E402 – import after env setup
+
+client = TestClient(app)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_png_bytes(width: int = 64, height: int = 64, color=(30, 80, 120)) -> bytes:
+    """Create a small solid-colour PNG in memory."""
+    img = Image.new("RGB", (width, height), color)
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# /health
+# ---------------------------------------------------------------------------
+
+
+def test_health_ok():
+    response = client.get("/health")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+
+# ---------------------------------------------------------------------------
+# /process – happy path
+# ---------------------------------------------------------------------------
+
+
+def test_process_returns_required_keys():
+    png = _make_png_bytes()
+    response = client.post(
+        "/process",
+        files={"file": ("test.png", png, "image/png")},
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert "enhanced_image_base64" in data
+    assert "heatmap_base64" in data
+    assert "detections" in data
+    assert "sitrep_text" in data
+
+
+def test_process_enhanced_image_is_valid_base64():
+    png = _make_png_bytes()
+    response = client.post(
+        "/process",
+        files={"file": ("test.png", png, "image/png")},
+    )
+    assert response.status_code == 200
+    b64_str = response.json()["enhanced_image_base64"]
+    # Should be a data-URI
+    assert b64_str.startswith("data:image/")
+    # Extract the raw base64 portion and verify it decodes
+    raw = b64_str.split(",", 1)[1]
+    decoded = base64.b64decode(raw)
+    img = Image.open(io.BytesIO(decoded))
+    assert img.size[0] > 0
+    assert img.size[1] > 0
+
+
+def test_process_heatmap_is_valid_base64():
+    png = _make_png_bytes()
+    response = client.post(
+        "/process",
+        files={"file": ("test.png", png, "image/png")},
+    )
+    assert response.status_code == 200
+    b64_str = response.json()["heatmap_base64"]
+    assert b64_str.startswith("data:image/")
+    raw = b64_str.split(",", 1)[1]
+    decoded = base64.b64decode(raw)
+    img = Image.open(io.BytesIO(decoded))
+    assert img.size[0] > 0
+
+
+def test_process_detections_structure():
+    """Each detection must have the required keys with correct types."""
+    png = _make_png_bytes()
+    response = client.post(
+        "/process",
+        files={"file": ("test.png", png, "image/png")},
+    )
+    assert response.status_code == 200
+    detections = response.json()["detections"]
+    assert isinstance(detections, list)
+    for det in detections:
+        assert "class" in det
+        assert "mapped_label" in det
+        assert "confidence" in det
+        assert "bbox" in det
+        assert isinstance(det["confidence"], float)
+        assert len(det["bbox"]) == 4
+
+
+def test_process_sitrep_is_string():
+    png = _make_png_bytes()
+    response = client.post(
+        "/process",
+        files={"file": ("test.png", png, "image/png")},
+    )
+    assert response.status_code == 200
+    sitrep = response.json()["sitrep_text"]
+    assert isinstance(sitrep, str)
+    assert len(sitrep) > 0
+
+
+# ---------------------------------------------------------------------------
+# /process – error cases
+# ---------------------------------------------------------------------------
+
+
+def test_process_rejects_non_image():
+    response = client.post(
+        "/process",
+        files={"file": ("data.txt", b"hello world", "text/plain")},
+    )
+    assert response.status_code == 400
+
+
+def test_process_rejects_empty_file():
+    response = client.post(
+        "/process",
+        files={"file": ("empty.png", b"", "image/png")},
+    )
+    assert response.status_code == 400
+
+
+def test_process_jpeg_image():
+    """Pipeline should work with JPEG input."""
+    img = Image.new("RGB", (80, 80), (50, 100, 150))
+    buf = io.BytesIO()
+    img.save(buf, format="JPEG")
+    response = client.post(
+        "/process",
+        files={"file": ("test.jpg", buf.getvalue(), "image/jpeg")},
+    )
+    assert response.status_code == 200
+    assert "enhanced_image_base64" in response.json()