Initial commit — SkinProAI dermoscopic analysis platform

Patient-level chat UI with streaming AI analysis pipeline:
- MedGemma visual examination with stage-by-stage cascade
- ConvNeXt classifier with confidence scores and differential
- MONET feature extraction and Grad-CAM attention maps
- Temporal comparison between sequential lesion images
- Persistent chat history with full cascade replay on reload
- FastAPI backend with SSE streaming + React/TypeScript frontend
- Docker build ready for Hugging Face Spaces deployment

.dockerignore

@@ -0,0 +1,28 @@
+venv/
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+.env
+
+# Frontend dev artifacts (only dist is needed)
+web/node_modules/
+web/.vite/
+
+# Local data — don't ship patient records or uploads
+data/uploads/
+data/patient_chats/
+data/lesions/
+data/patients.json
+
+# Misc
+.git/
+.gitignore
+*.md
+test*.py
+test*.jpg
+test*.png
+frontend/
+mcp_server/

.gitattributes

@@ -0,0 +1 @@
+guidelines/index/faiss.index filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+.Python
+venv/
+.venv/
+*.egg
+
+# Environment
+.env
+.env.*
+
+# Node
+web/node_modules/
+web/dist/
+web/.vite/
+
+# Patient data — never commit
+data/uploads/
+data/patient_chats/
+data/lesions/
+data/patients.json
+
+# Model weights (large binaries — store separately)
+models/*.pt
+models/*.pth
+models/*.bin
+models/*.safetensors
+
+# macOS
+.DS_Store
+
+# Test artifacts
+test*.jpg
+test*.png
+*.log
+
+# Clinical guidelines PDFs (copyrighted — obtain separately)
+guidelines/*.pdf
+
+# Temp
+/tmp/

Dockerfile

@@ -0,0 +1,40 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install Node.js for building the React frontend
+RUN apt-get update && \
+    apt-get install -y curl && \
+    curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
+    apt-get install -y nodejs && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY requirements.txt ml-requirements.txt
+COPY backend/requirements.txt api-requirements.txt
+RUN pip install --no-cache-dir -r ml-requirements.txt -r api-requirements.txt
+
+# Build React frontend
+COPY web/ web/
+WORKDIR /app/web
+RUN npm ci && npm run build
+
+WORKDIR /app
+
+# Copy application source
+COPY models/ models/
+COPY backend/ backend/
+COPY data/case_store.py data/case_store.py
+COPY guidelines/ guidelines/
+
+# Runtime directories (writable by the app)
+RUN mkdir -p data/uploads data/patient_chats data/lesions && \
+    echo '{"patients": []}' > data/patients.json
+
+# HF Spaces runs as a non-root user — ensure data dirs are writable
+RUN chmod -R 777 data/
+
+# HF Spaces uses port 7860
+EXPOSE 7860
+
+CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,44 @@
+---
+title: SkinProAI
+emoji: 🔬
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# SkinProAI
+
+AI-assisted dermoscopic lesion analysis for clinical decision support.
+
+## Features
+
+- **Patient management** — create and select patient profiles
+- **Image analysis** — upload dermoscopic images for automated assessment via MedGemma visual examination, MONET feature extraction, and ConvNeXt classification
+- **Temporal comparison** — sequential images are automatically compared to detect change over time
+- **Grad-CAM visualisation** — attention maps highlight regions driving the classification
+- **Persistent chat history** — full analysis cascade is stored and replayed on reload
+
+## Architecture
+
+| Layer | Technology |
+|-------|-----------|
+| Frontend | React 18 + TypeScript (Vite) |
+| Backend | FastAPI + uvicorn |
+| Vision-language model | MedGemma (Google) via Hugging Face |
+| Classifier | ConvNeXt fine-tuned on ISIC HAM10000 |
+| Feature extraction | MONET skin concept probes |
+| Explainability | Grad-CAM |
+
+## Usage
+
+1. Open the app and create a patient record
+2. Click the patient card to open the chat
+3. Attach a dermoscopic image and send — analysis runs automatically
+4. Upload further images for the same patient to trigger temporal comparison
+5. Ask follow-up questions in text to query the AI about the findings
+
+## Disclaimer
+
+SkinProAI is a research prototype intended for educational and investigational use only. It is **not** a certified medical device and must not be used as a substitute for professional clinical judgement.

backend/main.py

@@ -0,0 +1,63 @@
+"""
+SkinProAI FastAPI Backend
+"""
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from pathlib import Path
+import sys
+
+# Add project root to path for model imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from backend.routes import patients, lesions, analysis, chat
+
+app = FastAPI(title="SkinProAI API", version="1.0.0")
+
+# CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# API routes — analysis must be registered BEFORE patients so the literal
+# /gradcam route is not shadowed by the parameterised /{patient_id} route.
+app.include_router(analysis.router, prefix="/api/patients", tags=["analysis"])
+app.include_router(chat.router, prefix="/api/patients", tags=["chat"])
+app.include_router(patients.router, prefix="/api/patients", tags=["patients"])
+app.include_router(lesions.router, prefix="/api/patients", tags=["lesions"])
+
+# Ensure upload directories exist
+UPLOADS_DIR = Path(__file__).parent.parent / "data" / "uploads"
+UPLOADS_DIR.mkdir(parents=True, exist_ok=True)
+
+# Serve uploaded images
+if UPLOADS_DIR.exists():
+    app.mount("/uploads", StaticFiles(directory=str(UPLOADS_DIR)), name="uploads")
+
+# Serve React build (production)
+BUILD_DIR = Path(__file__).parent.parent / "web" / "dist"
+if BUILD_DIR.exists():
+    app.mount("/", StaticFiles(directory=str(BUILD_DIR), html=True), name="static")
+
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    from backend.services.analysis_service import get_analysis_service
+    svc = get_analysis_service()
+    if svc.agent.mcp_client:
+        svc.agent.mcp_client.stop()
+
+
+@app.get("/api/health")
+def health_check():
+    return {"status": "ok"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

backend/requirements.txt

@@ -0,0 +1,3 @@
+fastapi>=0.100.0
+uvicorn[standard]>=0.23.0
+python-multipart>=0.0.6

backend/routes/__init__.py

@@ -0,0 +1 @@
+from . import patients, lesions, analysis

backend/routes/analysis.py

@@ -0,0 +1,181 @@
+"""
+Analysis Routes - Image analysis with SSE streaming
+"""
+
+from fastapi import APIRouter, Query, HTTPException
+from fastapi.responses import StreamingResponse, FileResponse
+from pathlib import Path
+import json
+import tempfile
+
+from backend.services.analysis_service import get_analysis_service
+from data.case_store import get_case_store
+
+router = APIRouter()
+
+
+@router.get("/gradcam")
+def get_gradcam_by_path(path: str = Query(...)):
+    """Serve a temp visualization image (GradCAM or comparison overlay)"""
+    if not path:
+        raise HTTPException(status_code=400, detail="No path provided")
+
+    temp_dir = Path(tempfile.gettempdir()).resolve()
+    resolved_path = Path(path).resolve()
+    if not str(resolved_path).startswith(str(temp_dir)):
+        raise HTTPException(status_code=403, detail="Access denied")
+
+    allowed_suffixes = ("_gradcam.png", "_comparison.png")
+    if not any(resolved_path.name.endswith(s) for s in allowed_suffixes):
+        raise HTTPException(status_code=400, detail="Invalid image path")
+
+    if resolved_path.exists():
+        return FileResponse(str(resolved_path), media_type="image/png")
+    raise HTTPException(status_code=404, detail="Image not found")
+
+
+@router.post("/{patient_id}/lesions/{lesion_id}/images/{image_id}/analyze")
+async def analyze_image(
+    patient_id: str,
+    lesion_id: str,
+    image_id: str,
+    question: str = Query(None)
+):
+    """Analyze an image with SSE streaming"""
+    store = get_case_store()
+
+    # Verify image exists
+    img = store.get_image(patient_id, lesion_id, image_id)
+    if not img:
+        raise HTTPException(status_code=404, detail="Image not found")
+    if not img.image_path:
+        raise HTTPException(status_code=400, detail="Image has no file uploaded")
+
+    service = get_analysis_service()
+
+    async def generate():
+        try:
+            for chunk in service.analyze(patient_id, lesion_id, image_id, question):
+                yield f"data: {json.dumps(chunk)}\n\n"
+            yield "data: [DONE]\n\n"
+        except Exception as e:
+            yield f"data: {json.dumps(f'[ERROR]{str(e)}[/ERROR]')}\n\n"
+            yield "data: [DONE]\n\n"
+
+    return StreamingResponse(
+        generate(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+        }
+    )
+
+
+@router.post("/{patient_id}/lesions/{lesion_id}/images/{image_id}/confirm")
+async def confirm_diagnosis(
+    patient_id: str,
+    lesion_id: str,
+    image_id: str,
+    confirmed: bool = Query(...),
+    feedback: str = Query(None)
+):
+    """Confirm or reject diagnosis and get management guidance"""
+    service = get_analysis_service()
+
+    async def generate():
+        try:
+            for chunk in service.confirm(patient_id, lesion_id, image_id, confirmed, feedback):
+                yield f"data: {json.dumps(chunk)}\n\n"
+            yield "data: [DONE]\n\n"
+        except Exception as e:
+            yield f"data: {json.dumps(f'[ERROR]{str(e)}[/ERROR]')}\n\n"
+            yield "data: [DONE]\n\n"
+
+    return StreamingResponse(
+        generate(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+        }
+    )
+
+
+@router.post("/{patient_id}/lesions/{lesion_id}/images/{image_id}/compare")
+async def compare_to_previous(
+    patient_id: str,
+    lesion_id: str,
+    image_id: str
+):
+    """Compare this image to the previous one in the timeline"""
+    store = get_case_store()
+
+    # Get current and previous images
+    current_img = store.get_image(patient_id, lesion_id, image_id)
+    if not current_img:
+        raise HTTPException(status_code=404, detail="Image not found")
+
+    previous_img = store.get_previous_image(patient_id, lesion_id, image_id)
+    if not previous_img:
+        raise HTTPException(status_code=400, detail="No previous image to compare")
+
+    service = get_analysis_service()
+
+    async def generate():
+        try:
+            for chunk in service.compare_images(
+                patient_id, lesion_id,
+                previous_img.image_path,
+                current_img.image_path,
+                image_id
+            ):
+                yield f"data: {json.dumps(chunk)}\n\n"
+            yield "data: [DONE]\n\n"
+        except Exception as e:
+            yield f"data: {json.dumps(f'[ERROR]{str(e)}[/ERROR]')}\n\n"
+            yield "data: [DONE]\n\n"
+
+    return StreamingResponse(
+        generate(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+        }
+    )
+
+
+@router.post("/{patient_id}/lesions/{lesion_id}/chat")
+async def chat_message(
+    patient_id: str,
+    lesion_id: str,
+    message: dict
+):
+    """Send a chat message with SSE streaming response"""
+    store = get_case_store()
+
+    lesion = store.get_lesion(patient_id, lesion_id)
+    if not lesion:
+        raise HTTPException(status_code=404, detail="Lesion not found")
+
+    service = get_analysis_service()
+    content = message.get("content", "")
+
+    async def generate():
+        try:
+            for chunk in service.chat_followup(patient_id, lesion_id, content):
+                yield f"data: {json.dumps(chunk)}\n\n"
+            yield "data: [DONE]\n\n"
+        except Exception as e:
+            yield f"data: {json.dumps(f'[ERROR]{str(e)}[/ERROR]')}\n\n"
+            yield "data: [DONE]\n\n"
+
+    return StreamingResponse(
+        generate(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+        }
+    )

backend/routes/chat.py

@@ -0,0 +1,97 @@
+"""
+Chat Routes - Patient-level chat with image analysis tools
+"""
+
+import asyncio
+import json
+import threading
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, UploadFile, File, Form
+from fastapi.responses import StreamingResponse
+
+from data.case_store import get_case_store
+from backend.services.chat_service import get_chat_service
+
+router = APIRouter()
+
+
+@router.get("/{patient_id}/chat")
+def get_chat_history(patient_id: str):
+    """Get patient-level chat history"""
+    store = get_case_store()
+    if not store.get_patient(patient_id):
+        raise HTTPException(status_code=404, detail="Patient not found")
+    messages = store.get_patient_chat_history(patient_id)
+    return {"messages": messages}
+
+
+@router.delete("/{patient_id}/chat")
+def clear_chat(patient_id: str):
+    """Clear patient-level chat history"""
+    store = get_case_store()
+    if not store.get_patient(patient_id):
+        raise HTTPException(status_code=404, detail="Patient not found")
+    store.clear_patient_chat_history(patient_id)
+    return {"success": True}
+
+
+@router.post("/{patient_id}/chat")
+async def post_chat_message(
+    patient_id: str,
+    content: str = Form(""),
+    image: Optional[UploadFile] = File(None),
+):
+    """Send a chat message, optionally with an image — SSE streaming response.
+
+    The sync ML generator runs in a background thread so it never blocks the
+    event loop.  Events flow through an asyncio.Queue, so each SSE event is
+    flushed to the browser the moment it is produced (spinner shows instantly).
+    """
+    store = get_case_store()
+    if not store.get_patient(patient_id):
+        raise HTTPException(status_code=404, detail="Patient not found")
+
+    image_bytes = None
+    if image and image.filename:
+        image_bytes = await image.read()
+
+    chat_service = get_chat_service()
+
+    async def generate():
+        loop = asyncio.get_event_loop()
+        queue: asyncio.Queue = asyncio.Queue()
+
+        _SENTINEL = object()
+
+        def run_sync():
+            try:
+                for event in chat_service.stream_chat(patient_id, content, image_bytes):
+                    loop.call_soon_threadsafe(queue.put_nowait, event)
+            except Exception as e:
+                loop.call_soon_threadsafe(
+                    queue.put_nowait,
+                    {"type": "error", "message": str(e)},
+                )
+            finally:
+                loop.call_soon_threadsafe(queue.put_nowait, _SENTINEL)
+
+        thread = threading.Thread(target=run_sync, daemon=True)
+        thread.start()
+
+        while True:
+            event = await queue.get()
+            if event is _SENTINEL:
+                break
+            yield f"data: {json.dumps(event)}\n\n"
+
+        yield f"data: {json.dumps({'type': 'done'})}\n\n"
+
+    return StreamingResponse(
+        generate(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+        },
+    )

backend/routes/lesions.py

@@ -0,0 +1,241 @@
+"""
+Lesion Routes - CRUD for lesions and images
+"""
+
+from fastapi import APIRouter, HTTPException, UploadFile, File
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+from dataclasses import asdict
+from pathlib import Path
+from PIL import Image
+import io
+
+from data.case_store import get_case_store
+
+router = APIRouter()
+
+
+class CreateLesionRequest(BaseModel):
+    name: str
+    location: str = ""
+
+
+class UpdateLesionRequest(BaseModel):
+    name: str = None
+    location: str = None
+
+
+# -------------------------------------------------------------------------
+# Lesion CRUD
+# -------------------------------------------------------------------------
+
+@router.get("/{patient_id}/lesions")
+def list_lesions(patient_id: str):
+    """List all lesions for a patient"""
+    store = get_case_store()
+
+    patient = store.get_patient(patient_id)
+    if not patient:
+        raise HTTPException(status_code=404, detail="Patient not found")
+
+    lesions = store.list_lesions(patient_id)
+
+    result = []
+    for lesion in lesions:
+        images = store.list_images(patient_id, lesion.id)
+        # Get the most recent image as thumbnail
+        latest_image = images[-1] if images else None
+
+        result.append({
+            "id": lesion.id,
+            "patient_id": lesion.patient_id,
+            "name": lesion.name,
+            "location": lesion.location,
+            "created_at": lesion.created_at,
+            "image_count": len(images),
+            "latest_image": asdict(latest_image) if latest_image else None
+        })
+
+    return {"lesions": result}
+
+
+@router.post("/{patient_id}/lesions")
+def create_lesion(patient_id: str, req: CreateLesionRequest):
+    """Create a new lesion for a patient"""
+    store = get_case_store()
+
+    patient = store.get_patient(patient_id)
+    if not patient:
+        raise HTTPException(status_code=404, detail="Patient not found")
+
+    lesion = store.create_lesion(patient_id, req.name, req.location)
+    return {
+        "lesion": {
+            **asdict(lesion),
+            "image_count": 0,
+            "images": []
+        }
+    }
+
+
+@router.get("/{patient_id}/lesions/{lesion_id}")
+def get_lesion(patient_id: str, lesion_id: str):
+    """Get a lesion with all its images"""
+    store = get_case_store()
+
+    lesion = store.get_lesion(patient_id, lesion_id)
+    if not lesion:
+        raise HTTPException(status_code=404, detail="Lesion not found")
+
+    images = store.list_images(patient_id, lesion_id)
+
+    return {
+        "lesion": {
+            **asdict(lesion),
+            "image_count": len(images),
+            "images": [asdict(img) for img in images]
+        }
+    }
+
+
+@router.patch("/{patient_id}/lesions/{lesion_id}")
+def update_lesion(patient_id: str, lesion_id: str, req: UpdateLesionRequest):
+    """Update a lesion's name or location"""
+    store = get_case_store()
+
+    lesion = store.get_lesion(patient_id, lesion_id)
+    if not lesion:
+        raise HTTPException(status_code=404, detail="Lesion not found")
+
+    store.update_lesion(patient_id, lesion_id, req.name, req.location)
+
+    # Return updated lesion
+    lesion = store.get_lesion(patient_id, lesion_id)
+    images = store.list_images(patient_id, lesion_id)
+
+    return {
+        "lesion": {
+            **asdict(lesion),
+            "image_count": len(images),
+            "images": [asdict(img) for img in images]
+        }
+    }
+
+
+@router.delete("/{patient_id}/lesions/{lesion_id}")
+def delete_lesion(patient_id: str, lesion_id: str):
+    """Delete a lesion and all its images"""
+    store = get_case_store()
+
+    lesion = store.get_lesion(patient_id, lesion_id)
+    if not lesion:
+        raise HTTPException(status_code=404, detail="Lesion not found")
+
+    store.delete_lesion(patient_id, lesion_id)
+    return {"success": True}
+
+
+# -------------------------------------------------------------------------
+# Image CRUD
+# -------------------------------------------------------------------------
+
+@router.post("/{patient_id}/lesions/{lesion_id}/images")
+async def upload_image(patient_id: str, lesion_id: str, image: UploadFile = File(...)):
+    """Upload a new image to a lesion's timeline"""
+    store = get_case_store()
+
+    lesion = store.get_lesion(patient_id, lesion_id)
+    if not lesion:
+        raise HTTPException(status_code=404, detail="Lesion not found")
+
+    try:
+        # Create image record
+        img_record = store.add_image(patient_id, lesion_id)
+
+        # Save the actual image file
+        pil_image = Image.open(io.BytesIO(await image.read())).convert("RGB")
+        image_path = store.save_lesion_image(patient_id, lesion_id, img_record.id, pil_image)
+
+        # Update image record with path
+        store.update_image(patient_id, lesion_id, img_record.id, image_path=image_path)
+
+        # Return updated record
+        img_record = store.get_image(patient_id, lesion_id, img_record.id)
+        return {"image": asdict(img_record)}
+
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Failed to upload image: {e}")
+
+
+@router.get("/{patient_id}/lesions/{lesion_id}/images/{image_id}")
+def get_image_record(patient_id: str, lesion_id: str, image_id: str):
+    """Get an image record"""
+    store = get_case_store()
+
+    img = store.get_image(patient_id, lesion_id, image_id)
+    if not img:
+        raise HTTPException(status_code=404, detail="Image not found")
+
+    return {"image": asdict(img)}
+
+
+@router.get("/{patient_id}/lesions/{lesion_id}/images/{image_id}/file")
+def get_image_file(patient_id: str, lesion_id: str, image_id: str):
+    """Get the actual image file"""
+    store = get_case_store()
+
+    img = store.get_image(patient_id, lesion_id, image_id)
+    if not img or not img.image_path:
+        raise HTTPException(status_code=404, detail="Image not found")
+
+    path = Path(img.image_path)
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="Image file not found")
+
+    return FileResponse(str(path), media_type="image/png")
+
+
+@router.get("/{patient_id}/lesions/{lesion_id}/images/{image_id}/gradcam")
+def get_gradcam_file(patient_id: str, lesion_id: str, image_id: str):
+    """Get the GradCAM visualization for an image"""
+    store = get_case_store()
+
+    img = store.get_image(patient_id, lesion_id, image_id)
+    if not img or not img.gradcam_path:
+        raise HTTPException(status_code=404, detail="GradCAM not found")
+
+    path = Path(img.gradcam_path)
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="GradCAM file not found")
+
+    return FileResponse(str(path), media_type="image/png")
+
+
+# -------------------------------------------------------------------------
+# Chat
+# -------------------------------------------------------------------------
+
+@router.get("/{patient_id}/lesions/{lesion_id}/chat")
+def get_chat_history(patient_id: str, lesion_id: str):
+    """Get chat history for a lesion"""
+    store = get_case_store()
+
+    lesion = store.get_lesion(patient_id, lesion_id)
+    if not lesion:
+        raise HTTPException(status_code=404, detail="Lesion not found")
+
+    messages = store.get_chat_history(patient_id, lesion_id)
+    return {"messages": [asdict(m) for m in messages]}
+
+
+@router.delete("/{patient_id}/lesions/{lesion_id}/chat")
+def clear_chat_history(patient_id: str, lesion_id: str):
+    """Clear chat history for a lesion"""
+    store = get_case_store()
+
+    lesion = store.get_lesion(patient_id, lesion_id)
+    if not lesion:
+        raise HTTPException(status_code=404, detail="Lesion not found")
+
+    store.clear_chat_history(patient_id, lesion_id)
+    return {"success": True}

backend/routes/patients.py

@@ -0,0 +1,72 @@
+"""
+Patient Routes - CRUD for patients
+"""
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+from dataclasses import asdict
+
+from data.case_store import get_case_store
+
+router = APIRouter()
+
+
+class CreatePatientRequest(BaseModel):
+    name: str
+
+
+@router.get("")
+def list_patients():
+    """List all patients with lesion counts"""
+    store = get_case_store()
+    patients = store.list_patients()
+
+    result = []
+    for p in patients:
+        result.append({
+            **asdict(p),
+            "lesion_count": store.get_patient_lesion_count(p.id)
+        })
+
+    return {"patients": result}
+
+
+@router.post("")
+def create_patient(req: CreatePatientRequest):
+    """Create a new patient"""
+    store = get_case_store()
+    patient = store.create_patient(req.name)
+    return {
+        "patient": {
+            **asdict(patient),
+            "lesion_count": 0
+        }
+    }
+
+
+@router.get("/{patient_id}")
+def get_patient(patient_id: str):
+    """Get a patient by ID"""
+    store = get_case_store()
+    patient = store.get_patient(patient_id)
+    if not patient:
+        raise HTTPException(status_code=404, detail="Patient not found")
+
+    return {
+        "patient": {
+            **asdict(patient),
+            "lesion_count": store.get_patient_lesion_count(patient_id)
+        }
+    }
+
+
+@router.delete("/{patient_id}")
+def delete_patient(patient_id: str):
+    """Delete a patient and all their lesions"""
+    store = get_case_store()
+    patient = store.get_patient(patient_id)
+    if not patient:
+        raise HTTPException(status_code=404, detail="Patient not found")
+
+    store.delete_patient(patient_id)
+    return {"success": True}

backend/services/analysis_service.py

@@ -0,0 +1,146 @@
+"""
+Analysis Service - Wraps MedGemmaAgent for API use
+"""
+
+from pathlib import Path
+from dataclasses import asdict
+from typing import Optional, Generator
+
+from models.medgemma_agent import MedGemmaAgent
+from data.case_store import get_case_store
+
+
+class AnalysisService:
+    """Singleton service for managing analysis operations"""
+
+    _instance = None
+
+    def __init__(self):
+        self.agent = MedGemmaAgent(verbose=True)
+        self.store = get_case_store()
+        self._loaded = False
+
+    def _ensure_loaded(self):
+        """Lazy load the ML models"""
+        if not self._loaded:
+            self.agent.load_model()
+            self._loaded = True
+
+    def analyze(
+        self,
+        patient_id: str,
+        lesion_id: str,
+        image_id: str,
+        question: Optional[str] = None
+    ) -> Generator[str, None, None]:
+        """Run analysis on an image, yielding streaming chunks"""
+        self._ensure_loaded()
+
+        image = self.store.get_image(patient_id, lesion_id, image_id)
+        if not image or not image.image_path:
+            yield "[ERROR]No image uploaded[/ERROR]"
+            return
+
+        # Update stage
+        self.store.update_image(patient_id, lesion_id, image_id, stage="analyzing")
+
+        # Reset agent state for new analysis
+        self.agent.reset_state()
+
+        # Run analysis with question
+        for chunk in self.agent.analyze_image_stream(image.image_path, question=question or ""):
+            yield chunk
+
+        # Save diagnosis after analysis
+        if self.agent.last_diagnosis:
+            analysis_data = {
+                "diagnosis": self.agent.last_diagnosis["predictions"][0]["class"],
+                "full_name": self.agent.last_diagnosis["predictions"][0]["full_name"],
+                "confidence": self.agent.last_diagnosis["predictions"][0]["probability"],
+                "all_predictions": self.agent.last_diagnosis["predictions"]
+            }
+
+            # Save MONET features if available
+            if self.agent.last_monet_result:
+                analysis_data["monet_features"] = self.agent.last_monet_result.get("features", {})
+
+            self.store.update_image(
+                patient_id, lesion_id, image_id,
+                stage="awaiting_confirmation",
+                analysis=analysis_data
+            )
+
+    def confirm(
+        self,
+        patient_id: str,
+        lesion_id: str,
+        image_id: str,
+        confirmed: bool,
+        feedback: Optional[str] = None
+    ) -> Generator[str, None, None]:
+        """Confirm diagnosis and generate management guidance"""
+        for chunk in self.agent.generate_management_guidance(confirmed, feedback):
+            yield chunk
+
+        # Update stage to complete
+        self.store.update_image(patient_id, lesion_id, image_id, stage="complete")
+
+    def chat_followup(
+        self,
+        patient_id: str,
+        lesion_id: str,
+        message: str
+    ) -> Generator[str, None, None]:
+        """Handle follow-up chat messages"""
+        # Save user message
+        self.store.add_chat_message(patient_id, lesion_id, "user", message)
+
+        # Generate response
+        response = ""
+        for chunk in self.agent.chat_followup(message):
+            response += chunk
+            yield chunk
+
+        # Save assistant response
+        self.store.add_chat_message(patient_id, lesion_id, "assistant", response)
+
+    def get_chat_history(self, patient_id: str, lesion_id: str):
+        """Get chat history for a lesion"""
+        messages = self.store.get_chat_history(patient_id, lesion_id)
+        return [asdict(m) for m in messages]
+
+    def compare_images(
+        self,
+        patient_id: str,
+        lesion_id: str,
+        previous_image_path: str,
+        current_image_path: str,
+        current_image_id: str
+    ) -> Generator[str, None, None]:
+        """Compare two images and assess changes"""
+        self._ensure_loaded()
+
+        # Run comparison
+        comparison_result = None
+        for chunk in self.agent.compare_followup_images(previous_image_path, current_image_path):
+            yield chunk
+
+        # Extract comparison status from agent if available
+        # Default to STABLE if we can't determine
+        comparison_data = {
+            "status": "STABLE",
+            "summary": "Comparison complete"
+        }
+
+        # Update the current image with comparison data
+        self.store.update_image(
+            patient_id, lesion_id, current_image_id,
+            comparison=comparison_data
+        )
+
+
+def get_analysis_service() -> AnalysisService:
+    """Get or create AnalysisService singleton"""
+    if AnalysisService._instance is None:
+        AnalysisService._instance = AnalysisService()
+    return AnalysisService._instance

backend/services/chat_service.py

@@ -0,0 +1,197 @@
+"""
+Chat Service - Patient-level chat with tool dispatch and streaming
+"""
+
+import io
+import re
+import uuid
+from typing import Generator, Optional
+from pathlib import Path
+from PIL import Image as PILImage
+
+from data.case_store import get_case_store
+from backend.services.analysis_service import get_analysis_service
+
+
+def _extract_response_text(raw: str) -> str:
+    """Pull clean text out of [RESPONSE]...[/RESPONSE]; strip all other tags."""
+    # Grab the RESPONSE block first
+    match = re.search(r'\[RESPONSE\](.*?)\[/RESPONSE\]', raw, re.DOTALL)
+    if match:
+        return match.group(1).strip()
+    # Fallback: strip every known markup tag
+    clean = re.sub(
+        r'\[(STAGE:[^\]]+|THINKING|RESPONSE|/RESPONSE|/THINKING|/STAGE'
+        r'|ERROR|/ERROR|RESULT|/RESULT|CONFIRM:\d+|/CONFIRM)\]',
+        '', raw
+    )
+    return clean.strip()
+
+
+class ChatService:
+    _instance = None
+
+    def __init__(self):
+        self.store = get_case_store()
+
+    def _get_image_url(self, patient_id: str, lesion_id: str, image_id: str) -> str:
+        return f"/uploads/{patient_id}/{lesion_id}/{image_id}/image.png"
+
+    def stream_chat(
+        self,
+        patient_id: str,
+        content: str,
+        image_bytes: Optional[bytes] = None,
+    ) -> Generator[dict, None, None]:
+        """Main chat handler — yields SSE event dicts."""
+        analysis_service = get_analysis_service()
+
+        if image_bytes:
+            # ----------------------------------------------------------------
+            # Image path: analyze (and optionally compare).
+            # We do NOT stream the raw verbose analysis text to the chat bubble —
+            # the tool card IS the display artefact.  We accumulate the text
+            # internally, extract the clean [RESPONSE] block, and put it in
+            # tool_result.summary so the expanded card can show it.
+            # ----------------------------------------------------------------
+            lesion = self.store.get_or_create_chat_lesion(patient_id)
+
+            img_record = self.store.add_image(patient_id, lesion.id)
+            pil_image = PILImage.open(io.BytesIO(image_bytes)).convert("RGB")
+            abs_path = self.store.save_lesion_image(
+                patient_id, lesion.id, img_record.id, pil_image
+            )
+            self.store.update_image(patient_id, lesion.id, img_record.id, image_path=abs_path)
+
+            user_image_url = self._get_image_url(patient_id, lesion.id, img_record.id)
+            self.store.add_patient_chat_message(
+                patient_id, "user", content, image_url=user_image_url
+            )
+
+            # ---- tool: analyze_image ----------------------------------------
+            call_id = f"tc-{uuid.uuid4().hex[:6]}"
+            yield {"type": "tool_start", "tool": "analyze_image", "call_id": call_id}
+
+            analysis_text = ""
+            for chunk in analysis_service.analyze(patient_id, lesion.id, img_record.id):
+                yield {"type": "text", "content": chunk}
+                analysis_text += chunk
+
+            updated_img = self.store.get_image(patient_id, lesion.id, img_record.id)
+            analysis_result: dict = {
+                "image_url": user_image_url,
+                "summary": _extract_response_text(analysis_text),
+                "diagnosis": None,
+                "full_name": None,
+                "confidence": None,
+                "all_predictions": [],
+            }
+            if updated_img and updated_img.analysis:
+                a = updated_img.analysis
+                analysis_result.update({
+                    "diagnosis": a.get("diagnosis"),
+                    "full_name": a.get("full_name"),
+                    "confidence": a.get("confidence"),
+                    "all_predictions": a.get("all_predictions", []),
+                })
+
+            yield {
+                "type": "tool_result",
+                "tool": "analyze_image",
+                "call_id": call_id,
+                "result": analysis_result,
+            }
+
+            # ---- tool: compare_images (if a previous image exists) ----------
+            previous_img = self.store.get_previous_image(patient_id, lesion.id, img_record.id)
+            compare_call_id = None
+            compare_result = None
+            compare_text = ""
+
+            if (
+                previous_img
+                and previous_img.image_path
+                and Path(previous_img.image_path).exists()
+            ):
+                compare_call_id = f"tc-{uuid.uuid4().hex[:6]}"
+                yield {
+                    "type": "tool_start",
+                    "tool": "compare_images",
+                    "call_id": compare_call_id,
+                }
+
+                for chunk in analysis_service.compare_images(
+                    patient_id,
+                    lesion.id,
+                    previous_img.image_path,
+                    abs_path,
+                    img_record.id,
+                ):
+                    yield {"type": "text", "content": chunk}
+                    compare_text += chunk
+
+                updated_img2 = self.store.get_image(patient_id, lesion.id, img_record.id)
+                compare_result = {
+                    "prev_image_url": self._get_image_url(patient_id, lesion.id, previous_img.id),
+                    "curr_image_url": user_image_url,
+                    "status_label": "STABLE",
+                    "feature_changes": {},
+                    "summary": _extract_response_text(compare_text),
+                }
+                if updated_img2 and updated_img2.comparison:
+                    c = updated_img2.comparison
+                    compare_result.update({
+                        "status_label": c.get("status", "STABLE"),
+                        "feature_changes": c.get("feature_changes", {}),
+                    })
+                    if c.get("summary"):
+                        compare_result["summary"] = c["summary"]
+
+                yield {
+                    "type": "tool_result",
+                    "tool": "compare_images",
+                    "call_id": compare_call_id,
+                    "result": compare_result,
+                }
+
+            # Save assistant message
+            tool_calls_data = [{
+                "id": call_id,
+                "tool": "analyze_image",
+                "status": "complete",
+                "result": analysis_result,
+            }]
+            if compare_call_id and compare_result:
+                tool_calls_data.append({
+                    "id": compare_call_id,
+                    "tool": "compare_images",
+                    "status": "complete",
+                    "result": compare_result,
+                })
+
+            self.store.add_patient_chat_message(
+                patient_id, "assistant", analysis_text + compare_text,
+                tool_calls=tool_calls_data,
+            )
+
+        else:
+            # ----------------------------------------------------------------
+            # Text-only chat — stream chunks; tags are stripped on the frontend
+            # ----------------------------------------------------------------
+            self.store.add_patient_chat_message(patient_id, "user", content)
+
+            analysis_service._ensure_loaded()
+            response_text = ""
+            for chunk in analysis_service.agent.chat_followup(content):
+                yield {"type": "text", "content": chunk}
+                response_text += chunk
+
+            self.store.add_patient_chat_message(
+                patient_id, "assistant", _extract_response_text(response_text)
+            )
+
+
+def get_chat_service() -> ChatService:
+    if ChatService._instance is None:
+        ChatService._instance = ChatService()
+    return ChatService._instance

data/case_store.py

@@ -0,0 +1,507 @@
+"""
+Case Store - JSON-based persistence for patients, lesions, and images
+"""
+
+import json
+import uuid
+import shutil
+from pathlib import Path
+from datetime import datetime
+from typing import List, Dict, Optional, Any
+from dataclasses import dataclass, field, asdict
+from PIL import Image as PILImage
+
+
+@dataclass
+class ChatMessage:
+    role: str  # "user" or "assistant"
+    content: str
+    timestamp: str = field(default_factory=lambda: datetime.utcnow().isoformat())
+
+
+@dataclass
+class LesionImage:
+    """A single image capture of a lesion at a point in time"""
+    id: str
+    lesion_id: str
+    timestamp: str = field(default_factory=lambda: datetime.utcnow().isoformat())
+    image_path: Optional[str] = None
+    gradcam_path: Optional[str] = None
+    analysis: Optional[Dict[str, Any]] = None  # {diagnosis, confidence, monet_features}
+    comparison: Optional[Dict[str, Any]] = None  # {status, feature_changes, summary}
+    is_original: bool = False
+    stage: str = "pending"  # pending, analyzing, complete, error
+
+
+@dataclass
+class Lesion:
+    """A tracked lesion that can have multiple images over time"""
+    id: str
+    patient_id: str
+    name: str  # User-provided label (e.g., "Left shoulder mole")
+    location: str = ""  # Body location
+    created_at: str = field(default_factory=lambda: datetime.utcnow().isoformat())
+    chat_history: List[Dict] = field(default_factory=list)
+
+
+@dataclass
+class Patient:
+    """A patient who can have multiple lesions"""
+    id: str
+    name: str
+    created_at: str = field(default_factory=lambda: datetime.utcnow().isoformat())
+
+
+class CaseStore:
+    """JSON-based persistence for patients, lesions, and images"""
+
+    def __init__(self, data_dir: str = None):
+        if data_dir is None:
+            data_dir = Path(__file__).parent
+        self.data_dir = Path(data_dir)
+        self.patients_file = self.data_dir / "patients.json"
+        self.lesions_dir = self.data_dir / "lesions"
+        self.uploads_dir = self.data_dir / "uploads"
+
+        # Ensure directories exist
+        self.lesions_dir.mkdir(parents=True, exist_ok=True)
+        self.uploads_dir.mkdir(parents=True, exist_ok=True)
+
+        # Initialize patients file if needed
+        if not self.patients_file.exists():
+            self._init_patients_file()
+
+    def _init_patients_file(self):
+        """Initialize patients file"""
+        data = {"patients": []}
+        with open(self.patients_file, 'w') as f:
+            json.dump(data, f, indent=2)
+
+    def _load_patients_data(self) -> Dict:
+        """Load patients JSON file"""
+        with open(self.patients_file, 'r') as f:
+            return json.load(f)
+
+    def _save_patients_data(self, data: Dict):
+        """Save patients JSON file"""
+        with open(self.patients_file, 'w') as f:
+            json.dump(data, f, indent=2)
+
+    # -------------------------------------------------------------------------
+    # Patient Methods
+    # -------------------------------------------------------------------------
+
+    def list_patients(self) -> List[Patient]:
+        """List all patients"""
+        data = self._load_patients_data()
+        return [Patient(**p) for p in data.get("patients", [])]
+
+    def get_patient(self, patient_id: str) -> Optional[Patient]:
+        """Get a patient by ID"""
+        data = self._load_patients_data()
+        for p in data.get("patients", []):
+            if p["id"] == patient_id:
+                return Patient(**p)
+        return None
+
+    def create_patient(self, name: str) -> Patient:
+        """Create a new patient"""
+        patient = Patient(
+            id=f"patient-{uuid.uuid4().hex[:8]}",
+            name=name
+        )
+
+        data = self._load_patients_data()
+        data["patients"].append(asdict(patient))
+        self._save_patients_data(data)
+
+        # Create directory for this patient's lesions
+        (self.lesions_dir / patient.id).mkdir(exist_ok=True)
+
+        return patient
+
+    def delete_patient(self, patient_id: str):
+        """Delete a patient and all their lesions"""
+        data = self._load_patients_data()
+        data["patients"] = [p for p in data["patients"] if p["id"] != patient_id]
+        self._save_patients_data(data)
+
+        # Delete lesion files
+        patient_lesions_dir = self.lesions_dir / patient_id
+        if patient_lesions_dir.exists():
+            shutil.rmtree(patient_lesions_dir)
+
+        # Delete uploads
+        patient_uploads_dir = self.uploads_dir / patient_id
+        if patient_uploads_dir.exists():
+            shutil.rmtree(patient_uploads_dir)
+
+        # Delete patient chat history
+        patient_chat_file = self.data_dir / "patient_chats" / f"{patient_id}.json"
+        if patient_chat_file.exists():
+            patient_chat_file.unlink()
+
+    def get_patient_lesion_count(self, patient_id: str) -> int:
+        """Get number of lesions for a patient"""
+        return len(self.list_lesions(patient_id))
+
+    # -------------------------------------------------------------------------
+    # Lesion Methods
+    # -------------------------------------------------------------------------
+
+    def _get_lesion_path(self, patient_id: str, lesion_id: str) -> Path:
+        """Get path to lesion JSON file"""
+        return self.lesions_dir / patient_id / f"{lesion_id}.json"
+
+    def list_lesions(self, patient_id: str) -> List[Lesion]:
+        """List all lesions for a patient"""
+        patient_dir = self.lesions_dir / patient_id
+        if not patient_dir.exists():
+            return []
+
+        lesions = []
+        for f in sorted(patient_dir.glob("*.json")):
+            with open(f, 'r') as fp:
+                data = json.load(fp)
+                # Only load lesion data, not images
+                lesion_data = {k: v for k, v in data.items() if k != 'images'}
+                lesions.append(Lesion(**lesion_data))
+
+        lesions.sort(key=lambda x: x.created_at)
+        return lesions
+
+    def get_lesion(self, patient_id: str, lesion_id: str) -> Optional[Lesion]:
+        """Get a lesion by ID"""
+        path = self._get_lesion_path(patient_id, lesion_id)
+        if not path.exists():
+            return None
+
+        with open(path, 'r') as f:
+            data = json.load(f)
+            lesion_data = {k: v for k, v in data.items() if k != 'images'}
+            return Lesion(**lesion_data)
+
+    def create_lesion(self, patient_id: str, name: str, location: str = "") -> Lesion:
+        """Create a new lesion for a patient"""
+        lesion = Lesion(
+            id=f"lesion-{uuid.uuid4().hex[:8]}",
+            patient_id=patient_id,
+            name=name,
+            location=location
+        )
+
+        # Ensure patient directory exists
+        patient_dir = self.lesions_dir / patient_id
+        patient_dir.mkdir(exist_ok=True)
+
+        # Save lesion with empty images array
+        self._save_lesion_data(patient_id, lesion.id, {
+            **asdict(lesion),
+            "images": []
+        })
+
+        return lesion
+
+    def _save_lesion_data(self, patient_id: str, lesion_id: str, data: Dict):
+        """Save lesion data to JSON file"""
+        path = self._get_lesion_path(patient_id, lesion_id)
+        with open(path, 'w') as f:
+            json.dump(data, f, indent=2)
+
+    def _load_lesion_data(self, patient_id: str, lesion_id: str) -> Optional[Dict]:
+        """Load full lesion data including images"""
+        path = self._get_lesion_path(patient_id, lesion_id)
+        if not path.exists():
+            return None
+
+        with open(path, 'r') as f:
+            return json.load(f)
+
+    def delete_lesion(self, patient_id: str, lesion_id: str):
+        """Delete a lesion and all its images"""
+        path = self._get_lesion_path(patient_id, lesion_id)
+        if path.exists():
+            path.unlink()
+
+        # Delete uploads for this lesion
+        lesion_uploads_dir = self.uploads_dir / patient_id / lesion_id
+        if lesion_uploads_dir.exists():
+            shutil.rmtree(lesion_uploads_dir)
+
+    def update_lesion(self, patient_id: str, lesion_id: str, name: str = None, location: str = None):
+        """Update lesion name or location"""
+        data = self._load_lesion_data(patient_id, lesion_id)
+        if data is None:
+            return
+
+        if name is not None:
+            data["name"] = name
+        if location is not None:
+            data["location"] = location
+
+        self._save_lesion_data(patient_id, lesion_id, data)
+
+    # -------------------------------------------------------------------------
+    # LesionImage Methods
+    # -------------------------------------------------------------------------
+
+    def list_images(self, patient_id: str, lesion_id: str) -> List[LesionImage]:
+        """List all images for a lesion"""
+        data = self._load_lesion_data(patient_id, lesion_id)
+        if data is None:
+            return []
+
+        images = [LesionImage(**img) for img in data.get("images", [])]
+        images.sort(key=lambda x: x.timestamp)
+        return images
+
+    def get_image(self, patient_id: str, lesion_id: str, image_id: str) -> Optional[LesionImage]:
+        """Get an image by ID"""
+        data = self._load_lesion_data(patient_id, lesion_id)
+        if data is None:
+            return None
+
+        for img in data.get("images", []):
+            if img["id"] == image_id:
+                return LesionImage(**img)
+        return None
+
+    def add_image(self, patient_id: str, lesion_id: str) -> LesionImage:
+        """Add a new image to a lesion's timeline"""
+        data = self._load_lesion_data(patient_id, lesion_id)
+        if data is None:
+            raise ValueError(f"Lesion {lesion_id} not found")
+
+        # Check if this is the first image
+        is_first = len(data.get("images", [])) == 0
+
+        image = LesionImage(
+            id=f"img-{uuid.uuid4().hex[:8]}",
+            lesion_id=lesion_id,
+            is_original=is_first
+        )
+
+        if "images" not in data:
+            data["images"] = []
+        data["images"].append(asdict(image))
+        self._save_lesion_data(patient_id, lesion_id, data)
+
+        return image
+
+    def update_image(
+        self,
+        patient_id: str,
+        lesion_id: str,
+        image_id: str,
+        image_path: str = None,
+        gradcam_path: str = None,
+        analysis: Dict = None,
+        comparison: Dict = None,
+        stage: str = None
+    ):
+        """Update an image's data"""
+        data = self._load_lesion_data(patient_id, lesion_id)
+        if data is None:
+            return
+
+        for img in data.get("images", []):
+            if img["id"] == image_id:
+                if image_path is not None:
+                    img["image_path"] = image_path
+                if gradcam_path is not None:
+                    img["gradcam_path"] = gradcam_path
+                if analysis is not None:
+                    img["analysis"] = analysis
+                if comparison is not None:
+                    img["comparison"] = comparison
+                if stage is not None:
+                    img["stage"] = stage
+                break
+
+        self._save_lesion_data(patient_id, lesion_id, data)
+
+    def save_lesion_image(
+        self,
+        patient_id: str,
+        lesion_id: str,
+        image_id: str,
+        image: PILImage.Image,
+        filename: str = "image.png"
+    ) -> str:
+        """Save an uploaded image file, return the path"""
+        upload_dir = self.uploads_dir / patient_id / lesion_id / image_id
+        upload_dir.mkdir(parents=True, exist_ok=True)
+
+        image_path = upload_dir / filename
+        image.save(image_path)
+
+        return str(image_path)
+
+    def get_previous_image(
+        self,
+        patient_id: str,
+        lesion_id: str,
+        current_image_id: str
+    ) -> Optional[LesionImage]:
+        """Get the image before the current one (for comparison)"""
+        images = self.list_images(patient_id, lesion_id)
+
+        for i, img in enumerate(images):
+            if img.id == current_image_id and i > 0:
+                return images[i - 1]
+        return None
+
+    # -------------------------------------------------------------------------
+    # Chat Methods (scoped to lesion)
+    # -------------------------------------------------------------------------
+
+    def add_chat_message(self, patient_id: str, lesion_id: str, role: str, content: str):
+        """Add a chat message to a lesion"""
+        data = self._load_lesion_data(patient_id, lesion_id)
+        if data is None:
+            return
+
+        message = ChatMessage(role=role, content=content)
+        if "chat_history" not in data:
+            data["chat_history"] = []
+        data["chat_history"].append(asdict(message))
+        self._save_lesion_data(patient_id, lesion_id, data)
+
+    def get_chat_history(self, patient_id: str, lesion_id: str) -> List[ChatMessage]:
+        """Get chat history for a lesion"""
+        data = self._load_lesion_data(patient_id, lesion_id)
+        if data is None:
+            return []
+
+        return [ChatMessage(**m) for m in data.get("chat_history", [])]
+
+    def clear_chat_history(self, patient_id: str, lesion_id: str):
+        """Clear chat history for a lesion"""
+        data = self._load_lesion_data(patient_id, lesion_id)
+        if data is None:
+            return
+
+        data["chat_history"] = []
+        self._save_lesion_data(patient_id, lesion_id, data)
+
+    # -------------------------------------------------------------------------
+    # Patient-level Chat Methods
+    # -------------------------------------------------------------------------
+
+    def _get_patient_chat_file(self, patient_id: str) -> Path:
+        """Get path to patient-level chat JSON file"""
+        chat_dir = self.data_dir / "patient_chats"
+        chat_dir.mkdir(exist_ok=True)
+        return chat_dir / f"{patient_id}.json"
+
+    def get_patient_chat_history(self, patient_id: str) -> List[dict]:
+        """Get chat history for a patient"""
+        chat_file = self._get_patient_chat_file(patient_id)
+        if not chat_file.exists():
+            return []
+        with open(chat_file, 'r') as f:
+            data = json.load(f)
+        return data.get("messages", [])
+
+    def add_patient_chat_message(
+        self,
+        patient_id: str,
+        role: str,
+        content: str,
+        image_url: Optional[str] = None,
+        tool_calls: Optional[list] = None
+    ):
+        """Add a message to patient-level chat history"""
+        chat_file = self._get_patient_chat_file(patient_id)
+        if chat_file.exists():
+            with open(chat_file, 'r') as f:
+                data = json.load(f)
+        else:
+            data = {"messages": []}
+
+        message: Dict[str, Any] = {
+            "id": f"msg-{uuid.uuid4().hex[:8]}",
+            "role": role,
+            "content": content,
+            "timestamp": datetime.utcnow().isoformat(),
+        }
+        if image_url is not None:
+            message["image_url"] = image_url
+        if tool_calls is not None:
+            message["tool_calls"] = tool_calls
+
+        data["messages"].append(message)
+        with open(chat_file, 'w') as f:
+            json.dump(data, f, indent=2)
+
+    def clear_patient_chat_history(self, patient_id: str):
+        """Clear patient-level chat history"""
+        chat_file = self._get_patient_chat_file(patient_id)
+        with open(chat_file, 'w') as f:
+            json.dump({"messages": []}, f)
+
+    def get_or_create_chat_lesion(self, patient_id: str) -> 'Lesion':
+        """Get or create the internal chat-images lesion for a patient"""
+        for lesion in self.list_lesions(patient_id):
+            if lesion.name == "__chat_images__":
+                return lesion
+        return self.create_lesion(patient_id, "__chat_images__", "internal")
+
+    def get_latest_chat_image(self, patient_id: str) -> Optional['LesionImage']:
+        """Get the most recently analyzed chat image for a patient"""
+        lesion = self.get_or_create_chat_lesion(patient_id)
+        images = self.list_images(patient_id, lesion.id)
+        for img in reversed(images):
+            if img.analysis is not None:
+                return img
+        return None
+
+
+# Singleton instance
+_store_instance = None
+
+
+def get_case_store() -> CaseStore:
+    """Get or create CaseStore singleton"""
+    global _store_instance
+    if _store_instance is None:
+        _store_instance = CaseStore()
+    return _store_instance
+
+
+if __name__ == "__main__":
+    # Test the store
+    store = CaseStore()
+
+    print("Patients:")
+    for patient in store.list_patients():
+        print(f"  - {patient.id}: {patient.name}")
+
+    # Create a test patient
+    print("\nCreating test patient...")
+    patient = store.create_patient("Test Patient")
+    print(f"  Created: {patient.id}")
+
+    # Create a lesion
+    print("\nCreating lesion...")
+    lesion = store.create_lesion(patient.id, "Left shoulder mole", "Left shoulder")
+    print(f"  Created: {lesion.id}")
+
+    # Add an image
+    print("\nAdding image...")
+    image = store.add_image(patient.id, lesion.id)
+    print(f"  Created: {image.id} (is_original={image.is_original})")
+
+    # Add another image
+    image2 = store.add_image(patient.id, lesion.id)
+    print(f"  Created: {image2.id} (is_original={image2.is_original})")
+
+    # List images
+    print(f"\nImages for lesion {lesion.id}:")
+    for img in store.list_images(patient.id, lesion.id):
+        print(f"  - {img.id}: original={img.is_original}, stage={img.stage}")
+
+    # Cleanup
+    print("\nCleaning up test patient...")
+    store.delete_patient(patient.id)
+    print("Done!")

frontend/app.py

@@ -0,0 +1,532 @@
+"""
+SkinProAI Frontend - Modular Gradio application
+"""
+
+import gradio as gr
+from typing import Dict, Generator, Optional
+from datetime import datetime
+import sys
+import os
+import re
+import base64
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from data.case_store import get_case_store
+from frontend.components.styles import MAIN_CSS
+from frontend.components.analysis_view import format_output
+
+
+# =============================================================================
+# CONFIG
+# =============================================================================
+
+class Config:
+    APP_TITLE = "SkinProAI"
+    SERVER_PORT = int(os.environ.get("GRADIO_SERVER_PORT", "7860"))
+    HF_SPACES = os.environ.get("SPACE_ID") is not None
+
+
+# =============================================================================
+# AGENT
+# =============================================================================
+
+class AnalysisAgent:
+    """Wrapper for the MedGemma analysis agent"""
+
+    def __init__(self):
+        self.model = None
+        self.loaded = False
+
+    def load(self):
+        if self.loaded:
+            return
+        from models.medgemma_agent import MedGemmaAgent
+        self.model = MedGemmaAgent(verbose=True)
+        self.model.load_model()
+        self.loaded = True
+
+    def analyze(self, image_path: str, question: str = "") -> Generator[str, None, None]:
+        if not self.loaded:
+            yield "[STAGE:loading]Loading AI models...[/STAGE]\n"
+            self.load()
+
+        for chunk in self.model.analyze_image_stream(image_path, question=question):
+            yield chunk
+
+    def management_guidance(self, confirmed: bool, feedback: str = None) -> Generator[str, None, None]:
+        for chunk in self.model.generate_management_guidance(confirmed, feedback):
+            yield chunk
+
+    def followup(self, message: str) -> Generator[str, None, None]:
+        if not self.loaded or not self.model.last_diagnosis:
+            yield "[ERROR]No analysis context available.[/ERROR]\n"
+            return
+        for chunk in self.model.chat_followup(message):
+            yield chunk
+
+    def reset(self):
+        if self.model:
+            self.model.reset_state()
+
+
+agent = AnalysisAgent()
+case_store = get_case_store()
+
+
+# =============================================================================
+# APP
+# =============================================================================
+
+with gr.Blocks(title=Config.APP_TITLE, css=MAIN_CSS, theme=gr.themes.Soft()) as app:
+
+    # =========================================================================
+    # STATE
+    # =========================================================================
+    state = gr.State({
+        "page": "patient_select",  # patient_select | analysis
+        "case_id": None,
+        "instance_id": None,
+        "output": "",
+        "gradcam_base64": None
+    })
+
+    # =========================================================================
+    # PAGE 1: PATIENT SELECTION
+    # =========================================================================
+    with gr.Group(visible=True, elem_classes=["patient-select-container"]) as page_patient:
+        gr.Markdown("# SkinProAI", elem_classes=["patient-select-title"])
+        gr.Markdown("Select a patient to continue or create a new case", elem_classes=["patient-select-subtitle"])
+
+        with gr.Row(elem_classes=["patient-grid"]):
+            btn_demo_melanoma = gr.Button("Demo: Melanocytic Lesion", elem_classes=["patient-card"])
+            btn_demo_ak = gr.Button("Demo: Actinic Keratosis", elem_classes=["patient-card"])
+            btn_new_patient = gr.Button("+ New Patient", variant="primary", elem_classes=["new-patient-btn"])
+
+    # =========================================================================
+    # PAGE 2: ANALYSIS
+    # =========================================================================
+    with gr.Group(visible=False) as page_analysis:
+
+        # Header
+        with gr.Row(elem_classes=["app-header"]):
+            gr.Markdown(f"**{Config.APP_TITLE}**", elem_classes=["app-title"])
+            btn_back = gr.Button("< Back to Patients", elem_classes=["back-btn"])
+
+        with gr.Row(elem_classes=["analysis-container"]):
+
+            # Sidebar (previous queries)
+            with gr.Column(scale=0, min_width=260, visible=False, elem_classes=["query-sidebar"]) as sidebar:
+                gr.Markdown("### Previous Queries", elem_classes=["sidebar-header"])
+                sidebar_list = gr.Column(elem_id="sidebar-queries")
+                btn_new_query = gr.Button("+ New Query", size="sm", variant="primary")
+
+            # Main content
+            with gr.Column(scale=4, elem_classes=["main-content"]):
+
+                # Input view (greeting style)
+                with gr.Group(visible=True, elem_classes=["input-greeting"]) as view_input:
+                    gr.Markdown("What would you like to analyze?", elem_classes=["greeting-title"])
+                    gr.Markdown("Upload an image and describe what you'd like to know", elem_classes=["greeting-subtitle"])
+
+                    with gr.Column(elem_classes=["input-box-container"]):
+                        input_message = gr.Textbox(
+                            placeholder="Describe the lesion or ask a question...",
+                            show_label=False,
+                            lines=2,
+                            elem_classes=["message-input"]
+                        )
+
+                        input_image = gr.Image(
+                            type="pil",
+                            height=180,
+                            show_label=False,
+                            elem_classes=["image-preview"]
+                        )
+
+                        with gr.Row(elem_classes=["input-actions"]):
+                            gr.Markdown("*Upload a skin lesion image*")
+                            btn_analyze = gr.Button("Analyze", elem_classes=["send-btn"], interactive=False)
+
+                # Results view (shown after analysis)
+                with gr.Group(visible=False, elem_classes=["chat-view"]) as view_results:
+                    output_html = gr.HTML(
+                        value='<div class="analysis-output">Starting...</div>',
+                        elem_classes=["results-area"]
+                    )
+
+                    # Confirmation
+                    with gr.Group(visible=False, elem_classes=["confirm-buttons"]) as confirm_box:
+                        gr.Markdown("**Do you agree with this diagnosis?**")
+                        with gr.Row():
+                            btn_confirm_yes = gr.Button("Yes, continue", variant="primary", size="sm")
+                            btn_confirm_no = gr.Button("No, I disagree", variant="secondary", size="sm")
+                        input_feedback = gr.Textbox(label="Your assessment", placeholder="Enter diagnosis...", visible=False)
+                        btn_submit_feedback = gr.Button("Submit", visible=False, size="sm")
+
+                    # Follow-up
+                    with gr.Row(elem_classes=["chat-input-area"]):
+                        input_followup = gr.Textbox(placeholder="Ask a follow-up question...", show_label=False, lines=1, scale=4)
+                        btn_followup = gr.Button("Send", size="sm", scale=1)
+
+    # =========================================================================
+    # DYNAMIC SIDEBAR RENDERING
+    # =========================================================================
+    @gr.render(inputs=[state], triggers=[state.change])
+    def render_sidebar(s):
+        case_id = s.get("case_id")
+        if not case_id or s.get("page") != "analysis":
+            return
+
+        instances = case_store.list_instances(case_id)
+        current = s.get("instance_id")
+
+        for i, inst in enumerate(instances, 1):
+            diagnosis = "Pending"
+            if inst.analysis and inst.analysis.get("diagnosis"):
+                d = inst.analysis["diagnosis"]
+                diagnosis = d.get("class", "?")
+
+            label = f"#{i}: {diagnosis}"
+            variant = "primary" if inst.id == current else "secondary"
+            btn = gr.Button(label, size="sm", variant=variant, elem_classes=["query-item"])
+
+            # Attach click handler to load this instance
+            def load_instance(inst_id=inst.id, c_id=case_id):
+                def _load(current_state):
+                    current_state["instance_id"] = inst_id
+                    instance = case_store.get_instance(c_id, inst_id)
+
+                    # Load saved output if available
+                    output_html = '<div class="analysis-output"><div class="result">Previous analysis loaded</div></div>'
+                    if instance and instance.analysis:
+                        diag = instance.analysis.get("diagnosis", {})
+                        output_html = f'<div class="analysis-output"><div class="result">Diagnosis: {diag.get("full_name", diag.get("class", "Unknown"))}</div></div>'
+
+                    return (
+                        current_state,
+                        gr.update(visible=False),  # view_input
+                        gr.update(visible=True),   # view_results
+                        output_html,
+                        gr.update(visible=False)   # confirm_box
+                    )
+                return _load
+
+            btn.click(
+                load_instance(),
+                inputs=[state],
+                outputs=[state, view_input, view_results, output_html, confirm_box]
+            )
+
+    # =========================================================================
+    # EVENT HANDLERS
+    # =========================================================================
+
+    def select_patient(case_id: str, s: Dict):
+        """Handle patient selection"""
+        s["case_id"] = case_id
+        s["page"] = "analysis"
+
+        instances = case_store.list_instances(case_id)
+        has_queries = len(instances) > 0
+
+        if has_queries:
+            # Load most recent
+            inst = instances[-1]
+            s["instance_id"] = inst.id
+
+            # Load image if exists
+            img = None
+            if inst.image_path and os.path.exists(inst.image_path):
+                from PIL import Image
+                img = Image.open(inst.image_path)
+
+            return (
+                s,
+                gr.update(visible=False),  # page_patient
+                gr.update(visible=True),   # page_analysis
+                gr.update(visible=True),   # sidebar
+                gr.update(visible=False),  # view_input
+                gr.update(visible=True),   # view_results
+                '<div class="analysis-output"><div class="result">Previous analysis loaded</div></div>',
+                gr.update(visible=False)   # confirm_box
+            )
+        else:
+            # New instance
+            inst = case_store.create_instance(case_id)
+            s["instance_id"] = inst.id
+            s["output"] = ""
+
+            return (
+                s,
+                gr.update(visible=False),
+                gr.update(visible=True),
+                gr.update(visible=False),  # sidebar hidden for new patient
+                gr.update(visible=True),   # view_input
+                gr.update(visible=False),  # view_results
+                "",
+                gr.update(visible=False)
+            )
+
+    def new_patient(s: Dict):
+        """Create new patient"""
+        case = case_store.create_case(f"Patient {datetime.now().strftime('%Y-%m-%d %H:%M')}")
+        return select_patient(case.id, s)
+
+    def go_back(s: Dict):
+        """Return to patient selection"""
+        s["page"] = "patient_select"
+        s["case_id"] = None
+        s["instance_id"] = None
+        s["output"] = ""
+
+        return (
+            s,
+            gr.update(visible=True),   # page_patient
+            gr.update(visible=False),  # page_analysis
+            gr.update(visible=False),  # sidebar
+            gr.update(visible=True),   # view_input
+            gr.update(visible=False),  # view_results
+            "",
+            gr.update(visible=False)   # confirm_box
+        )
+
+    def new_query(s: Dict):
+        """Start new query for current patient"""
+        case_id = s.get("case_id")
+        if not case_id:
+            return s, gr.update(), gr.update(), gr.update(), "", gr.update()
+
+        inst = case_store.create_instance(case_id)
+        s["instance_id"] = inst.id
+        s["output"] = ""
+        s["gradcam_base64"] = None
+
+        agent.reset()
+
+        return (
+            s,
+            gr.update(visible=True),   # view_input
+            gr.update(visible=False),  # view_results
+            None,                       # clear image
+            "",                         # clear output
+            gr.update(visible=False)   # confirm_box
+        )
+
+    def enable_analyze(img):
+        """Enable analyze button when image uploaded"""
+        return gr.update(interactive=img is not None)
+
+    def run_analysis(image, message, s: Dict):
+        """Run analysis on uploaded image"""
+        if image is None:
+            yield s, gr.update(), gr.update(), gr.update(), gr.update()
+            return
+
+        case_id = s["case_id"]
+        instance_id = s["instance_id"]
+
+        # Save image
+        image_path = case_store.save_image(case_id, instance_id, image)
+        case_store.update_analysis(case_id, instance_id, stage="analyzing", image_path=image_path)
+
+        agent.reset()
+        s["output"] = ""
+        gradcam_base64 = None
+        has_confirm = False
+
+        # Switch to results view
+        yield (
+            s,
+            gr.update(visible=False),  # view_input
+            gr.update(visible=True),   # view_results
+            '<div class="analysis-output">Starting analysis...</div>',
+            gr.update(visible=False)   # confirm_box
+        )
+
+        partial = ""
+        for chunk in agent.analyze(image_path, message or ""):
+            partial += chunk
+
+            # Check for GradCAM
+            if gradcam_base64 is None:
+                match = re.search(r'\[GRADCAM_IMAGE:([^\]]+)\]', partial)
+                if match:
+                    path = match.group(1)
+                    if os.path.exists(path):
+                        try:
+                            with open(path, "rb") as f:
+                                gradcam_base64 = base64.b64encode(f.read()).decode('utf-8')
+                            s["gradcam_base64"] = gradcam_base64
+                        except:
+                            pass
+
+            if '[CONFIRM:' in partial:
+                has_confirm = True
+
+            s["output"] = partial
+
+            yield (
+                s,
+                gr.update(visible=False),
+                gr.update(visible=True),
+                format_output(partial, gradcam_base64),
+                gr.update(visible=has_confirm)
+            )
+
+        # Save analysis
+        if agent.model and agent.model.last_diagnosis:
+            diag = agent.model.last_diagnosis["predictions"][0]
+            case_store.update_analysis(
+                case_id, instance_id,
+                stage="awaiting_confirmation",
+                analysis={"diagnosis": diag}
+            )
+
+    def confirm_yes(s: Dict):
+        """User confirmed diagnosis"""
+        partial = s.get("output", "")
+        gradcam = s.get("gradcam_base64")
+
+        for chunk in agent.management_guidance(confirmed=True):
+            partial += chunk
+            s["output"] = partial
+            yield s, format_output(partial, gradcam), gr.update(visible=False)
+
+        case_store.update_analysis(s["case_id"], s["instance_id"], stage="complete")
+
+    def confirm_no():
+        """Show feedback input"""
+        return gr.update(visible=True), gr.update(visible=True)
+
+    def submit_feedback(feedback: str, s: Dict):
+        """Submit user feedback"""
+        partial = s.get("output", "")
+        gradcam = s.get("gradcam_base64")
+
+        for chunk in agent.management_guidance(confirmed=False, feedback=feedback):
+            partial += chunk
+            s["output"] = partial
+            yield (
+                s,
+                format_output(partial, gradcam),
+                gr.update(visible=False),
+                gr.update(visible=False),
+                gr.update(visible=False),
+                ""
+            )
+
+        case_store.update_analysis(s["case_id"], s["instance_id"], stage="complete")
+
+    def send_followup(message: str, s: Dict):
+        """Send follow-up question"""
+        if not message.strip():
+            return s, gr.update(), ""
+
+        case_store.add_chat_message(s["case_id"], s["instance_id"], "user", message)
+
+        partial = s.get("output", "")
+        gradcam = s.get("gradcam_base64")
+
+        partial += f'\n<div class="chat-message user">You: {message}</div>\n'
+
+        response = ""
+        for chunk in agent.followup(message):
+            response += chunk
+            s["output"] = partial + response
+            yield s, format_output(partial + response, gradcam), ""
+
+        case_store.add_chat_message(s["case_id"], s["instance_id"], "assistant", response)
+
+    # =========================================================================
+    # WIRE EVENTS
+    # =========================================================================
+
+    # Patient selection
+    btn_demo_melanoma.click(
+        lambda s: select_patient("demo-melanoma", s),
+        inputs=[state],
+        outputs=[state, page_patient, page_analysis, sidebar, view_input, view_results, output_html, confirm_box]
+    )
+
+    btn_demo_ak.click(
+        lambda s: select_patient("demo-ak", s),
+        inputs=[state],
+        outputs=[state, page_patient, page_analysis, sidebar, view_input, view_results, output_html, confirm_box]
+    )
+
+    btn_new_patient.click(
+        new_patient,
+        inputs=[state],
+        outputs=[state, page_patient, page_analysis, sidebar, view_input, view_results, output_html, confirm_box]
+    )
+
+    # Navigation
+    btn_back.click(
+        go_back,
+        inputs=[state],
+        outputs=[state, page_patient, page_analysis, sidebar, view_input, view_results, output_html, confirm_box]
+    )
+
+    btn_new_query.click(
+        new_query,
+        inputs=[state],
+        outputs=[state, view_input, view_results, input_image, output_html, confirm_box]
+    )
+
+    # Analysis
+    input_image.change(enable_analyze, inputs=[input_image], outputs=[btn_analyze])
+
+    btn_analyze.click(
+        run_analysis,
+        inputs=[input_image, input_message, state],
+        outputs=[state, view_input, view_results, output_html, confirm_box]
+    )
+
+    # Confirmation
+    btn_confirm_yes.click(
+        confirm_yes,
+        inputs=[state],
+        outputs=[state, output_html, confirm_box]
+    )
+
+    btn_confirm_no.click(
+        confirm_no,
+        outputs=[input_feedback, btn_submit_feedback]
+    )
+
+    btn_submit_feedback.click(
+        submit_feedback,
+        inputs=[input_feedback, state],
+        outputs=[state, output_html, confirm_box, input_feedback, btn_submit_feedback, input_feedback]
+    )
+
+    # Follow-up
+    btn_followup.click(
+        send_followup,
+        inputs=[input_followup, state],
+        outputs=[state, output_html, input_followup]
+    )
+
+    input_followup.submit(
+        send_followup,
+        inputs=[input_followup, state],
+        outputs=[state, output_html, input_followup]
+    )
+
+
+# =============================================================================
+# MAIN
+# =============================================================================
+
+if __name__ == "__main__":
+    print(f"\n{'='*50}")
+    print(f"  {Config.APP_TITLE}")
+    print(f"{'='*50}\n")
+
+    app.queue().launch(
+        server_name="0.0.0.0" if Config.HF_SPACES else "127.0.0.1",
+        server_port=Config.SERVER_PORT,
+        share=False,
+        show_error=True
+    )

frontend/components/analysis_view.py

@@ -0,0 +1,214 @@
+"""
+Analysis View Component - Main analysis interface with input and results
+"""
+
+import gradio as gr
+import re
+from typing import Optional
+
+
+def parse_markdown(text: str) -> str:
+    """Convert basic markdown to HTML"""
+    text = re.sub(r'\*\*(.+?)\*\*', r'<strong>\1</strong>', text)
+    text = re.sub(r'__(.+?)__', r'<strong>\1</strong>', text)
+    text = re.sub(r'\*(.+?)\*', r'<em>\1</em>', text)
+
+    # Bullet lists
+    lines = text.split('\n')
+    in_list = False
+    result = []
+    for line in lines:
+        stripped = line.strip()
+        if re.match(r'^[\*\-] ', stripped):
+            if not in_list:
+                result.append('<ul>')
+                in_list = True
+            item = re.sub(r'^[\*\-] ', '', stripped)
+            result.append(f'<li>{item}</li>')
+        else:
+            if in_list:
+                result.append('</ul>')
+                in_list = False
+            result.append(line)
+    if in_list:
+        result.append('</ul>')
+
+    return '\n'.join(result)
+
+
+# Regex patterns for output parsing
+_STAGE_RE = re.compile(r'\[STAGE:(\w+)\](.*?)\[/STAGE\]')
+_THINKING_RE = re.compile(r'\[THINKING\](.*?)\[/THINKING\]')
+_OBSERVATION_RE = re.compile(r'\[OBSERVATION\](.*?)\[/OBSERVATION\]')
+_TOOL_OUTPUT_RE = re.compile(r'\[TOOL_OUTPUT:(.*?)\]\n(.*?)\[/TOOL_OUTPUT\]', re.DOTALL)
+_RESULT_RE = re.compile(r'\[RESULT\](.*?)\[/RESULT\]')
+_ERROR_RE = re.compile(r'\[ERROR\](.*?)\[/ERROR\]')
+_GRADCAM_RE = re.compile(r'\[GRADCAM_IMAGE:[^\]]+\]\n?')
+_RESPONSE_RE = re.compile(r'\[RESPONSE\]\n(.*?)\n\[/RESPONSE\]', re.DOTALL)
+_COMPLETE_RE = re.compile(r'\[COMPLETE\](.*?)\[/COMPLETE\]')
+_CONFIRM_RE = re.compile(r'\[CONFIRM:(\w+)\](.*?)\[/CONFIRM\]')
+_REFERENCES_RE = re.compile(r'\[REFERENCES\](.*?)\[/REFERENCES\]', re.DOTALL)
+_REF_RE = re.compile(r'\[REF:([^:]+):([^:]+):([^:]+):([^:]+):([^\]]+)\]')
+
+
+def format_output(raw_text: str, gradcam_base64: Optional[str] = None) -> str:
+    """Convert tagged output to styled HTML"""
+    html = raw_text
+
+    # Stage headers
+    html = _STAGE_RE.sub(
+        r'<div class="stage"><span class="stage-indicator"></span><span class="stage-text">\2</span></div>',
+        html
+    )
+
+    # Thinking
+    html = _THINKING_RE.sub(r'<div class="thinking">\1</div>', html)
+
+    # Observations
+    html = _OBSERVATION_RE.sub(r'<div class="observation">\1</div>', html)
+
+    # Tool outputs
+    html = _TOOL_OUTPUT_RE.sub(
+        r'<div class="tool-output"><div class="tool-header">\1</div><pre class="tool-content">\2</pre></div>',
+        html
+    )
+
+    # Results
+    html = _RESULT_RE.sub(r'<div class="result">\1</div>', html)
+
+    # Errors
+    html = _ERROR_RE.sub(r'<div class="error">\1</div>', html)
+
+    # GradCAM image
+    if gradcam_base64:
+        img_html = f'<div class="gradcam-inline"><div class="gradcam-header">Attention Map</div><img src="data:image/png;base64,{gradcam_base64}" alt="Grad-CAM"></div>'
+        html = _GRADCAM_RE.sub(img_html, html)
+    else:
+        html = _GRADCAM_RE.sub('', html)
+
+    # Response section
+    def format_response(match):
+        content = match.group(1)
+        parsed = parse_markdown(content)
+        parsed = re.sub(r'\n\n+', '</p><p>', parsed)
+        parsed = parsed.replace('\n', '<br>')
+        return f'<div class="response"><p>{parsed}</p></div>'
+
+    html = _RESPONSE_RE.sub(format_response, html)
+
+    # Complete
+    html = _COMPLETE_RE.sub(r'<div class="complete">\1</div>', html)
+
+    # Confirmation
+    html = _CONFIRM_RE.sub(
+        r'<div class="confirm-box"><div class="confirm-text">\2</div></div>',
+        html
+    )
+
+    # References
+    def format_references(match):
+        ref_content = match.group(1)
+        refs_html = ['<div class="references"><div class="references-header">References</div><ul>']
+        for ref_match in _REF_RE.finditer(ref_content):
+            _, source, page, filename, superscript = ref_match.groups()
+            refs_html.append(
+                f'<li><a href="guidelines/{filename}#page={page}" target="_blank" class="ref-link">'
+                f'<sup>{superscript}</sup> {source}, p.{page}</a></li>'
+            )
+        refs_html.append('</ul></div>')
+        return '\n'.join(refs_html)
+
+    html = _REFERENCES_RE.sub(format_references, html)
+
+    # Convert newlines
+    html = html.replace('\n', '<br>')
+
+    return f'<div class="analysis-output">{html}</div>'
+
+
+def create_analysis_view():
+    """
+    Create the analysis view component.
+
+    Returns:
+        Tuple of (container, components dict)
+    """
+    with gr.Group(visible=False, elem_classes=["analysis-container"]) as container:
+
+        with gr.Row():
+            # Main content area
+            with gr.Column(elem_classes=["main-content"]):
+
+                # Input greeting (shown when no analysis yet)
+                with gr.Group(visible=True, elem_classes=["input-greeting"]) as input_greeting:
+                    gr.Markdown("What would you like to analyze?", elem_classes=["greeting-title"])
+                    gr.Markdown("Upload an image and describe what you'd like to know", elem_classes=["greeting-subtitle"])
+
+                    with gr.Column(elem_classes=["input-box-container"]):
+                        message_input = gr.Textbox(
+                            placeholder="Describe the lesion or ask a question...",
+                            show_label=False,
+                            lines=3,
+                            elem_classes=["message-input"]
+                        )
+
+                        # Image upload (compact)
+                        image_input = gr.Image(
+                            label="",
+                            type="pil",
+                            height=180,
+                            elem_classes=["image-preview"],
+                            show_label=False
+                        )
+
+                        with gr.Row(elem_classes=["input-actions"]):
+                            upload_hint = gr.Markdown("*Upload a skin lesion image above*", visible=True)
+                            send_btn = gr.Button("Analyze", elem_classes=["send-btn"], interactive=False)
+
+                # Chat/results view (shown after analysis starts)
+                with gr.Group(visible=False, elem_classes=["chat-view"]) as chat_view:
+                    results_output = gr.HTML(
+                        value='<div class="analysis-output">Starting analysis...</div>',
+                        elem_classes=["results-area"]
+                    )
+
+                    # Confirmation buttons
+                    with gr.Group(visible=False, elem_classes=["confirm-buttons"]) as confirm_group:
+                        gr.Markdown("**Do you agree with this diagnosis?**")
+                        with gr.Row():
+                            confirm_yes_btn = gr.Button("Yes, continue", variant="primary", size="sm")
+                            confirm_no_btn = gr.Button("No, I disagree", variant="secondary", size="sm")
+                        feedback_input = gr.Textbox(
+                            label="Your assessment",
+                            placeholder="Enter your diagnosis...",
+                            visible=False
+                        )
+                        submit_feedback_btn = gr.Button("Submit", visible=False, size="sm")
+
+                    # Follow-up input
+                    with gr.Row(elem_classes=["chat-input-area"]):
+                        followup_input = gr.Textbox(
+                            placeholder="Ask a follow-up question...",
+                            show_label=False,
+                            lines=1
+                        )
+                        followup_btn = gr.Button("Send", size="sm", elem_classes=["send-btn"])
+
+    components = {
+        "input_greeting": input_greeting,
+        "chat_view": chat_view,
+        "message_input": message_input,
+        "image_input": image_input,
+        "send_btn": send_btn,
+        "results_output": results_output,
+        "confirm_group": confirm_group,
+        "confirm_yes_btn": confirm_yes_btn,
+        "confirm_no_btn": confirm_no_btn,
+        "feedback_input": feedback_input,
+        "submit_feedback_btn": submit_feedback_btn,
+        "followup_input": followup_input,
+        "followup_btn": followup_btn,
+        "upload_hint": upload_hint
+    }
+
+    return container, components

frontend/components/patient_select.py

@@ -0,0 +1,48 @@
+"""
+Patient Selection Component - Landing page for selecting/creating patients
+"""
+
+import gradio as gr
+from typing import Callable, List
+from data.case_store import get_case_store, Case
+
+
+def create_patient_select(on_patient_selected: Callable[[str], None]) -> gr.Group:
+    """
+    Create the patient selection page component.
+
+    Args:
+        on_patient_selected: Callback when a patient is selected (receives case_id)
+
+    Returns:
+        gr.Group containing the patient selection UI
+    """
+    case_store = get_case_store()
+
+    with gr.Group(visible=True, elem_classes=["patient-select-container"]) as container:
+        gr.Markdown("# SkinProAI", elem_classes=["patient-select-title"])
+        gr.Markdown("Select a patient to continue or create a new case", elem_classes=["patient-select-subtitle"])
+
+        with gr.Column(elem_classes=["patient-grid"]):
+            # Demo cases
+            demo_melanoma_btn = gr.Button(
+                "Demo: Melanocytic Lesion",
+                elem_classes=["patient-card"]
+            )
+            demo_ak_btn = gr.Button(
+                "Demo: Actinic Keratosis",
+                elem_classes=["patient-card"]
+            )
+
+            # New patient button
+            new_patient_btn = gr.Button(
+                "+ New Patient",
+                elem_classes=["new-patient-btn"]
+            )
+
+    return container, demo_melanoma_btn, demo_ak_btn, new_patient_btn
+
+
+def get_patient_cases() -> List[Case]:
+    """Get list of all patient cases"""
+    return get_case_store().list_cases()

frontend/components/sidebar.py

@@ -0,0 +1,55 @@
+"""
+Sidebar Component - Shows previous queries for a patient
+"""
+
+import gradio as gr
+from datetime import datetime
+from typing import List, Optional
+from data.case_store import get_case_store, Instance
+
+
+def format_query_item(instance: Instance, index: int) -> str:
+    """Format an instance as a query item for display"""
+    diagnosis = "Pending"
+    if instance.analysis and instance.analysis.get("diagnosis"):
+        diag = instance.analysis["diagnosis"]
+        diagnosis = diag.get("full_name", diag.get("class", "Unknown"))
+
+    try:
+        dt = datetime.fromisoformat(instance.created_at.replace('Z', '+00:00'))
+        date_str = dt.strftime("%b %d, %H:%M")
+    except:
+        date_str = "Unknown"
+
+    return f"Query #{index}: {diagnosis} ({date_str})"
+
+
+def create_sidebar():
+    """
+    Create the sidebar component for showing previous queries.
+
+    Returns:
+        Tuple of (container, components dict)
+    """
+    with gr.Column(visible=False, elem_classes=["query-sidebar"]) as container:
+        gr.Markdown("### Previous Queries", elem_classes=["sidebar-header"])
+
+        # Dynamic list of query buttons
+        query_list = gr.Column(elem_id="query-list")
+
+        # New query button
+        new_query_btn = gr.Button("+ New Query", size="sm", variant="primary")
+
+    components = {
+        "query_list": query_list,
+        "new_query_btn": new_query_btn
+    }
+
+    return container, components
+
+
+def get_queries_for_case(case_id: str) -> List[Instance]:
+    """Get all instances/queries for a case"""
+    if not case_id:
+        return []
+    return get_case_store().list_instances(case_id)

frontend/components/styles.py

@@ -0,0 +1,517 @@
+"""
+CSS Styles for SkinProAI components
+"""
+
+MAIN_CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap');
+
+* {
+    font-family: 'Inter', sans-serif !important;
+}
+
+.gradio-container {
+    max-width: 1200px !important;
+    margin: 0 auto !important;
+}
+
+/* Hide Gradio footer */
+.gradio-container footer { display: none !important; }
+
+/* ============================================
+   PATIENT SELECTION PAGE
+   ============================================ */
+
+.patient-select-container {
+    min-height: 80vh;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    padding: 40px 20px;
+}
+
+.patient-select-title {
+    font-size: 32px;
+    font-weight: 600;
+    color: #111827;
+    margin-bottom: 8px;
+    text-align: center;
+}
+
+.patient-select-subtitle {
+    font-size: 16px;
+    color: #6b7280;
+    margin-bottom: 40px;
+    text-align: center;
+}
+
+.patient-grid {
+    display: flex;
+    gap: 20px;
+    flex-wrap: wrap;
+    justify-content: center;
+    max-width: 800px;
+}
+
+.patient-card {
+    background: white !important;
+    border: 2px solid #e5e7eb !important;
+    border-radius: 16px !important;
+    padding: 24px 32px !important;
+    min-width: 200px !important;
+    cursor: pointer;
+    transition: all 0.2s ease !important;
+}
+
+.patient-card:hover {
+    border-color: #6366f1 !important;
+    box-shadow: 0 8px 25px rgba(99, 102, 241, 0.15) !important;
+    transform: translateY(-2px);
+}
+
+.new-patient-btn {
+    background: #6366f1 !important;
+    color: white !important;
+    border: none !important;
+    border-radius: 12px !important;
+    padding: 16px 32px !important;
+    font-weight: 500 !important;
+    margin-top: 24px;
+}
+
+.new-patient-btn:hover {
+    background: #4f46e5 !important;
+}
+
+/* ============================================
+   ANALYSIS PAGE - MAIN LAYOUT
+   ============================================ */
+
+.analysis-container {
+    display: flex;
+    height: calc(100vh - 80px);
+    min-height: 600px;
+}
+
+/* Sidebar */
+.query-sidebar {
+    width: 280px;
+    background: #f9fafb;
+    border-right: 1px solid #e5e7eb;
+    padding: 20px;
+    overflow-y: auto;
+    flex-shrink: 0;
+}
+
+.sidebar-header {
+    font-size: 14px;
+    font-weight: 600;
+    color: #374151;
+    margin-bottom: 16px;
+    padding-bottom: 12px;
+    border-bottom: 1px solid #e5e7eb;
+}
+
+.query-item {
+    background: white;
+    border: 1px solid #e5e7eb;
+    border-radius: 8px;
+    padding: 12px;
+    margin-bottom: 8px;
+    cursor: pointer;
+    transition: all 0.15s;
+}
+
+.query-item:hover {
+    border-color: #6366f1;
+    background: #f5f3ff;
+}
+
+.query-item-title {
+    font-size: 13px;
+    font-weight: 500;
+    color: #111827;
+    margin-bottom: 4px;
+}
+
+.query-item-meta {
+    font-size: 11px;
+    color: #6b7280;
+}
+
+/* Main content area */
+.main-content {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    padding: 24px;
+    overflow: hidden;
+}
+
+/* ============================================
+   INPUT AREA (Greeting style)
+   ============================================ */
+
+.input-greeting {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    padding: 40px;
+}
+
+.greeting-title {
+    font-size: 24px;
+    font-weight: 600;
+    color: #111827;
+    margin-bottom: 8px;
+}
+
+.greeting-subtitle {
+    font-size: 14px;
+    color: #6b7280;
+    margin-bottom: 32px;
+}
+
+.input-box-container {
+    width: 100%;
+    max-width: 600px;
+    background: white;
+    border: 2px solid #e5e7eb;
+    border-radius: 16px;
+    padding: 20px;
+    transition: border-color 0.2s;
+}
+
+.input-box-container:focus-within {
+    border-color: #6366f1;
+}
+
+.message-input textarea {
+    border: none !important;
+    resize: none !important;
+    font-size: 15px !important;
+    line-height: 1.5 !important;
+    padding: 0 !important;
+}
+
+.message-input textarea:focus {
+    box-shadow: none !important;
+}
+
+.input-actions {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-top: 16px;
+    padding-top: 16px;
+    border-top: 1px solid #f3f4f6;
+}
+
+.upload-btn {
+    background: #f3f4f6 !important;
+    color: #374151 !important;
+    border: 1px solid #e5e7eb !important;
+    border-radius: 8px !important;
+    padding: 8px 16px !important;
+    font-size: 13px !important;
+}
+
+.upload-btn:hover {
+    background: #e5e7eb !important;
+}
+
+.send-btn {
+    background: #6366f1 !important;
+    color: white !important;
+    border: none !important;
+    border-radius: 8px !important;
+    padding: 10px 24px !important;
+    font-weight: 500 !important;
+}
+
+.send-btn:hover {
+    background: #4f46e5 !important;
+}
+
+.send-btn:disabled {
+    background: #d1d5db !important;
+    cursor: not-allowed;
+}
+
+/* Image preview */
+.image-preview {
+    margin-top: 16px;
+    border-radius: 12px;
+    overflow: hidden;
+    max-height: 200px;
+}
+
+.image-preview img {
+    max-height: 200px;
+    object-fit: contain;
+}
+
+/* ============================================
+   CHAT/RESULTS VIEW
+   ============================================ */
+
+.chat-view {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+}
+
+.results-area {
+    flex: 1;
+    overflow-y: auto;
+    padding: 20px;
+    background: #ffffff;
+    border: 1px solid #e5e7eb;
+    border-radius: 12px;
+    margin-bottom: 16px;
+}
+
+/* Analysis output styling */
+.analysis-output {
+    line-height: 1.6;
+    color: #333;
+}
+
+.stage {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 8px 0;
+    font-weight: 500;
+    color: #1a1a1a;
+    margin-top: 12px;
+}
+
+.stage-indicator {
+    width: 8px;
+    height: 8px;
+    background: #6366f1;
+    border-radius: 50%;
+    animation: pulse 1.5s ease-in-out infinite;
+}
+
+@keyframes pulse {
+    0%, 100% { opacity: 1; transform: scale(1); }
+    50% { opacity: 0.5; transform: scale(0.8); }
+}
+
+.thinking {
+    color: #6b7280;
+    font-style: italic;
+    font-size: 13px;
+    padding: 4px 0 4px 16px;
+    border-left: 2px solid #e5e7eb;
+    margin: 4px 0;
+}
+
+.observation {
+    color: #374151;
+    font-size: 13px;
+    padding: 4px 0 4px 16px;
+}
+
+.tool-output {
+    background: #f8fafc;
+    border-radius: 8px;
+    margin: 12px 0;
+    overflow: hidden;
+    border: 1px solid #e2e8f0;
+}
+
+.tool-header {
+    background: #f1f5f9;
+    padding: 8px 12px;
+    font-weight: 500;
+    font-size: 13px;
+    color: #475569;
+    border-bottom: 1px solid #e2e8f0;
+}
+
+.tool-content {
+    padding: 12px;
+    margin: 0;
+    font-family: 'SF Mono', Monaco, monospace !important;
+    font-size: 12px;
+    line-height: 1.5;
+    white-space: pre-wrap;
+    color: #334155;
+}
+
+.result {
+    background: #ecfdf5;
+    border: 1px solid #a7f3d0;
+    border-radius: 8px;
+    padding: 12px 16px;
+    margin: 12px 0;
+    font-weight: 500;
+    color: #065f46;
+}
+
+.error {
+    background: #fef2f2;
+    border: 1px solid #fecaca;
+    border-radius: 8px;
+    padding: 12px 16px;
+    margin: 8px 0;
+    color: #b91c1c;
+}
+
+.response {
+    background: #ffffff;
+    border: 1px solid #e5e7eb;
+    border-radius: 8px;
+    padding: 16px;
+    margin: 16px 0;
+    line-height: 1.7;
+}
+
+.response ul, .response ol {
+    margin: 8px 0;
+    padding-left: 24px;
+}
+
+.response li {
+    margin: 4px 0;
+}
+
+.complete {
+    color: #6b7280;
+    font-size: 12px;
+    padding: 8px 0;
+    text-align: center;
+}
+
+/* Confirmation */
+.confirm-box {
+    background: #eff6ff;
+    border: 1px solid #bfdbfe;
+    border-radius: 8px;
+    padding: 16px;
+    margin: 16px 0;
+    text-align: center;
+}
+
+.confirm-buttons {
+    background: #f0f9ff;
+    border: 1px solid #bae6fd;
+    border-radius: 8px;
+    padding: 12px;
+    margin-top: 12px;
+}
+
+/* References */
+.references {
+    background: #f9fafb;
+    border: 1px solid #e5e7eb;
+    border-radius: 8px;
+    margin: 16px 0;
+    overflow: hidden;
+}
+
+.references-header {
+    background: #f3f4f6;
+    padding: 8px 12px;
+    font-weight: 500;
+    font-size: 13px;
+    border-bottom: 1px solid #e5e7eb;
+}
+
+.references ul {
+    list-style: none;
+    padding: 12px;
+    margin: 0;
+}
+
+.ref-link {
+    color: #6366f1;
+    text-decoration: none;
+    font-size: 13px;
+}
+
+.ref-link:hover {
+    text-decoration: underline;
+}
+
+/* GradCAM */
+.gradcam-inline {
+    margin: 16px 0;
+    background: #f8fafc;
+    border-radius: 8px;
+    overflow: hidden;
+    border: 1px solid #e2e8f0;
+}
+
+.gradcam-header {
+    background: #f1f5f9;
+    padding: 8px 12px;
+    font-weight: 500;
+    font-size: 13px;
+    border-bottom: 1px solid #e2e8f0;
+}
+
+.gradcam-inline img {
+    max-width: 100%;
+    max-height: 300px;
+    display: block;
+    margin: 12px auto;
+}
+
+/* Chat input at bottom */
+.chat-input-area {
+    background: white;
+    border: 1px solid #e5e7eb;
+    border-radius: 12px;
+    padding: 12px 16px;
+    display: flex;
+    gap: 12px;
+    align-items: flex-end;
+}
+
+.chat-input-area textarea {
+    flex: 1;
+    border: none !important;
+    resize: none !important;
+    font-size: 14px !important;
+}
+
+/* ============================================
+   HEADER
+   ============================================ */
+
+.app-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 16px 24px;
+    border-bottom: 1px solid #e5e7eb;
+    background: white;
+}
+
+.app-title {
+    font-size: 20px;
+    font-weight: 600;
+    color: #111827;
+}
+
+.back-btn {
+    background: transparent !important;
+    color: #6b7280 !important;
+    border: 1px solid #e5e7eb !important;
+    border-radius: 8px !important;
+    padding: 8px 16px !important;
+    font-size: 13px !important;
+}
+
+.back-btn:hover {
+    background: #f9fafb !important;
+    color: #111827 !important;
+}
+"""

guidelines/index/faiss.index

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:faf9cd914f52b84a55d486a156b4756f28dbc1a92abeafc121077402e1fa53f4
+size 145965

mcp_server/server.py

@@ -0,0 +1,286 @@
+"""
+SkinProAI MCP Server - Pure JSON-RPC 2.0 stdio server (no mcp library required).
+
+Uses sys.executable (venv Python) so all ML packages (torch, transformers, etc.)
+are available. Tools are loaded lazily on first call.
+
+Run standalone: python mcp_server/server.py
+(Should start silently, waiting on stdin.)
+"""
+
+import sys
+import json
+import os
+
+# Ensure project root is on path
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from mcp_server.tool_registry import get_monet, get_convnext, get_gradcam, get_rag
+
+
+# ---------------------------------------------------------------------------
+# Tool implementations
+# ---------------------------------------------------------------------------
+
+def _monet_analyze(arguments: dict) -> dict:
+    from PIL import Image
+    image = Image.open(arguments["image_path"]).convert("RGB")
+    return get_monet().analyze(image)
+
+
+def _classify_lesion(arguments: dict) -> dict:
+    from PIL import Image
+    image = Image.open(arguments["image_path"]).convert("RGB")
+    monet_scores = arguments.get("monet_scores")
+    return get_convnext().classify(
+        clinical_image=image,
+        derm_image=None,
+        monet_scores=monet_scores,
+    )
+
+
+def _generate_gradcam(arguments: dict) -> dict:
+    from PIL import Image
+    import tempfile
+    image = Image.open(arguments["image_path"]).convert("RGB")
+    result = get_gradcam().analyze(image)
+
+    gradcam_file = tempfile.NamedTemporaryFile(suffix="_gradcam.png", delete=False)
+    gradcam_path = gradcam_file.name
+    gradcam_file.close()
+    result["overlay"].save(gradcam_path)
+
+    return {
+        "gradcam_path": gradcam_path,
+        "predicted_class": result["predicted_class"],
+        "predicted_class_full": result["predicted_class_full"],
+        "confidence": result["confidence"],
+    }
+
+
+def _search_guidelines(arguments: dict) -> dict:
+    query = arguments.get("query", "")
+    diagnosis = arguments.get("diagnosis") or ""
+    rag = get_rag()
+    context, references = rag.get_management_context(diagnosis, query)
+    references_display = rag.format_references_for_display(references)
+    return {
+        "context": context,
+        "references": references,
+        "references_display": references_display,
+    }
+
+
+def _compare_images(arguments: dict) -> dict:
+    from PIL import Image
+    import tempfile
+    image1 = Image.open(arguments["image1_path"]).convert("RGB")
+    image2 = Image.open(arguments["image2_path"]).convert("RGB")
+
+    from models.overlay_tool import get_overlay_tool
+    comparison = get_overlay_tool().generate_comparison_overlay(
+        image1, image2, label1="Previous", label2="Current"
+    )
+    comparison_path = comparison["path"]
+
+    monet = get_monet()
+    prev_result = monet.analyze(image1)
+    curr_result = monet.analyze(image2)
+
+    monet_deltas = {}
+    for name in curr_result["features"]:
+        prev_val = prev_result["features"].get(name, 0.0)
+        curr_val = curr_result["features"][name]
+        delta = curr_val - prev_val
+        if abs(delta) > 0.1:
+            monet_deltas[name] = {
+                "previous": prev_val,
+                "current": curr_val,
+                "delta": delta,
+            }
+
+    # Generate GradCAM for both images so the frontend can show a side-by-side comparison
+    prev_gradcam_path = None
+    curr_gradcam_path = None
+    try:
+        gradcam = get_gradcam()
+        prev_gc = gradcam.analyze(image1)
+        curr_gc = gradcam.analyze(image2)
+
+        f1 = tempfile.NamedTemporaryFile(suffix="_gradcam.png", delete=False)
+        prev_gradcam_path = f1.name
+        f1.close()
+        prev_gc["overlay"].save(prev_gradcam_path)
+
+        f2 = tempfile.NamedTemporaryFile(suffix="_gradcam.png", delete=False)
+        curr_gradcam_path = f2.name
+        f2.close()
+        curr_gc["overlay"].save(curr_gradcam_path)
+    except Exception:
+        pass  # GradCAM comparison is best-effort
+
+    return {
+        "comparison_path": comparison_path,
+        "monet_deltas": monet_deltas,
+        "prev_gradcam_path": prev_gradcam_path,
+        "curr_gradcam_path": curr_gradcam_path,
+    }
+
+
+TOOLS = {
+    "monet_analyze": _monet_analyze,
+    "classify_lesion": _classify_lesion,
+    "generate_gradcam": _generate_gradcam,
+    "search_guidelines": _search_guidelines,
+    "compare_images": _compare_images,
+}
+
+TOOLS_LIST = [
+    {
+        "name": "monet_analyze",
+        "description": "Extract MONET concept-presence scores from a skin lesion image.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"image_path": {"type": "string"}},
+            "required": ["image_path"],
+        },
+    },
+    {
+        "name": "classify_lesion",
+        "description": "Classify a skin lesion using ConvNeXt dual-encoder.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "image_path": {"type": "string"},
+                "monet_scores": {"type": "array"},
+            },
+            "required": ["image_path"],
+        },
+    },
+    {
+        "name": "generate_gradcam",
+        "description": "Generate a Grad-CAM attention overlay for a skin lesion image.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"image_path": {"type": "string"}},
+            "required": ["image_path"],
+        },
+    },
+    {
+        "name": "search_guidelines",
+        "description": "Search clinical guidelines RAG for management context.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string"},
+                "diagnosis": {"type": "string"},
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "compare_images",
+        "description": "Generate comparison overlay and MONET deltas for two lesion images.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "image1_path": {"type": "string"},
+                "image2_path": {"type": "string"},
+            },
+            "required": ["image1_path", "image2_path"],
+        },
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# JSON-RPC 2.0 dispatcher
+# ---------------------------------------------------------------------------
+
+def handle_request(request: dict):
+    method = request.get("method")
+    req_id = request.get("id")  # None for notifications
+    params = request.get("params", {})
+
+    if method == "initialize":
+        return {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "result": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": {"name": "SkinProAI", "version": "1.0.0"},
+            },
+        }
+
+    if method in ("notifications/initialized",):
+        return None  # notification — no response
+
+    if method == "tools/list":
+        return {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "result": {"tools": TOOLS_LIST},
+        }
+
+    if method == "tools/call":
+        name = params.get("name")
+        arguments = params.get("arguments", {})
+        if name not in TOOLS:
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "error": {"code": -32601, "message": f"Unknown tool: {name}"},
+            }
+        try:
+            result = TOOLS[name](arguments)
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {
+                    "content": [{"type": "text", "text": json.dumps(result)}],
+                    "isError": False,
+                },
+            }
+        except Exception as e:
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {
+                    "content": [{"type": "text", "text": f"Tool error: {e}"}],
+                    "isError": True,
+                },
+            }
+
+    # Unknown method with id → method not found
+    if req_id is not None:
+        return {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "error": {"code": -32601, "message": f"Method not found: {method}"},
+        }
+
+    return None  # unknown notification — ignore
+
+
+# ---------------------------------------------------------------------------
+# Main loop
+# ---------------------------------------------------------------------------
+
+def main():
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        response = handle_request(request)
+        if response is not None:
+            sys.stdout.write(json.dumps(response) + "\n")
+            sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

mcp_server/tool_registry.py

@@ -0,0 +1,55 @@
+"""
+Lazy singleton loader for all 4 ML models used by the MCP server.
+Fixes sys.path so the subprocess can import from models/.
+"""
+
+import sys
+import os
+
+# Ensure project root is on path (this file lives at project_root/mcp_server/tool_registry.py)
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+_monet = None
+_convnext = None
+_gradcam = None
+_rag = None
+
+
+def get_monet():
+    global _monet
+    if _monet is None:
+        from models.monet_tool import MonetTool
+        _monet = MonetTool()
+        _monet.load()
+    return _monet
+
+
+def get_convnext():
+    global _convnext
+    if _convnext is None:
+        from models.convnext_classifier import ConvNeXtClassifier
+        root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        _convnext = ConvNeXtClassifier(
+            checkpoint_path=os.path.join(root, "models", "seed42_fold0.pt")
+        )
+        _convnext.load()
+    return _convnext
+
+
+def get_gradcam():
+    global _gradcam
+    if _gradcam is None:
+        from models.gradcam_tool import GradCAMTool
+        _gradcam = GradCAMTool(classifier=get_convnext())
+        _gradcam.load()
+    return _gradcam
+
+
+def get_rag():
+    global _rag
+    if _rag is None:
+        from models.guidelines_rag import get_guidelines_rag
+        _rag = get_guidelines_rag()
+        if not _rag.loaded:
+            _rag.load_index()
+    return _rag

models/convnext_classifier.py

@@ -0,0 +1,383 @@
+"""
+ConvNeXt Classifier Tool - Skin lesion classification using ConvNeXt + MONET features
+Loads seed42_fold0.pt checkpoint and performs classification.
+"""
+
+import torch
+import torch.nn as nn
+import numpy as np
+from PIL import Image
+from torchvision import transforms
+from typing import Optional, Dict, List, Tuple
+import timm
+
+
+# Class names for the 11-class skin lesion classification
+CLASS_NAMES = [
+    'AKIEC', 'BCC', 'BEN_OTH', 'BKL', 'DF',
+    'INF', 'MAL_OTH', 'MEL', 'NV', 'SCCKA', 'VASC'
+]
+
+CLASS_FULL_NAMES = {
+    'AKIEC': 'Actinic Keratosis / Intraepithelial Carcinoma',
+    'BCC': 'Basal Cell Carcinoma',
+    'BEN_OTH': 'Benign Other',
+    'BKL': 'Benign Keratosis-like Lesion',
+    'DF': 'Dermatofibroma',
+    'INF': 'Inflammatory',
+    'MAL_OTH': 'Malignant Other',
+    'MEL': 'Melanoma',
+    'NV': 'Melanocytic Nevus',
+    'SCCKA': 'Squamous Cell Carcinoma / Keratoacanthoma',
+    'VASC': 'Vascular Lesion'
+}
+
+
+class ConvNeXtDualEncoder(nn.Module):
+    """
+    Dual-image ConvNeXt model matching the trained checkpoint.
+    Processes BOTH clinical and dermoscopy images through shared backbone.
+
+    Metadata input: 19 dimensions
+      - age (1): normalized age
+      - sex (4): one-hot encoded
+      - site (7): one-hot encoded (reduced from 14)
+      - MONET (7): 7 MONET feature scores
+    """
+
+    def __init__(
+        self,
+        model_name: str = 'convnext_base.fb_in22k_ft_in1k',
+        metadata_dim: int = 19,
+        num_classes: int = 11,
+        dropout: float = 0.3
+    ):
+        super().__init__()
+
+        self.backbone = timm.create_model(
+            model_name,
+            pretrained=False,
+            num_classes=0
+        )
+        backbone_dim = self.backbone.num_features  # 1024 for convnext_base
+
+        # Metadata MLP: 19 -> 64
+        self.meta_mlp = nn.Sequential(
+            nn.Linear(metadata_dim, 64),
+            nn.LayerNorm(64),
+            nn.GELU(),
+            nn.Dropout(dropout)
+        )
+
+        # Classifier: 2112 -> 512 -> 256 -> 11
+        # Input: clinical(1024) + derm(1024) + meta(64) = 2112
+        fusion_dim = backbone_dim * 2 + 64
+        self.classifier = nn.Sequential(
+            nn.Linear(fusion_dim, 512),
+            nn.LayerNorm(512),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(512, 256),
+            nn.LayerNorm(256),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(256, num_classes)
+        )
+
+        self.metadata_dim = metadata_dim
+        self.num_classes = num_classes
+        self.backbone_dim = backbone_dim
+
+    def forward(
+        self,
+        clinical_img: torch.Tensor,
+        derm_img: Optional[torch.Tensor] = None,
+        metadata: Optional[torch.Tensor] = None
+    ) -> torch.Tensor:
+        """
+        Forward pass with dual images.
+
+        Args:
+            clinical_img: [B, 3, H, W] clinical image tensor
+            derm_img: [B, 3, H, W] dermoscopy image tensor (uses clinical if None)
+            metadata: [B, 19] metadata tensor (zeros if None)
+
+        Returns:
+            logits: [B, 11]
+        """
+        # Process clinical image
+        clinical_features = self.backbone(clinical_img)
+
+        # Process dermoscopy image
+        if derm_img is not None:
+            derm_features = self.backbone(derm_img)
+        else:
+            derm_features = clinical_features
+
+        # Process metadata
+        if metadata is not None:
+            meta_features = self.meta_mlp(metadata)
+        else:
+            batch_size = clinical_features.size(0)
+            meta_features = torch.zeros(
+                batch_size, 64,
+                device=clinical_features.device
+            )
+
+        # Concatenate: [B, 1024] + [B, 1024] + [B, 64] = [B, 2112]
+        fused = torch.cat([clinical_features, derm_features, meta_features], dim=1)
+        logits = self.classifier(fused)
+
+        return logits
+
+
+class ConvNeXtClassifier:
+    """
+    ConvNeXt classifier tool for skin lesion classification.
+    Uses dual images (clinical + dermoscopy) and MONET features.
+    """
+
+    # Site mapping for metadata encoding
+    SITE_MAPPING = {
+        'head': 0, 'neck': 0, 'face': 0,  # head_neck_face
+        'trunk': 1, 'back': 1, 'chest': 1, 'abdomen': 1,
+        'upper': 2, 'arm': 2, 'hand': 2,  # upper extremity
+        'lower': 3, 'leg': 3, 'foot': 3, 'thigh': 3,  # lower extremity
+        'genital': 4, 'oral': 5, 'acral': 6,
+    }
+
+    SEX_MAPPING = {'male': 0, 'female': 1, 'other': 2, 'unknown': 3}
+
+    def __init__(
+        self,
+        checkpoint_path: str = "models/seed42_fold0.pt",
+        device: Optional[str] = None
+    ):
+        self.checkpoint_path = checkpoint_path
+        self.device = device
+        self.model = None
+        self.loaded = False
+
+        # Image preprocessing
+        self.transform = transforms.Compose([
+            transforms.Resize((384, 384)),
+            transforms.ToTensor(),
+            transforms.Normalize(
+                mean=[0.485, 0.456, 0.406],
+                std=[0.229, 0.224, 0.225]
+            )
+        ])
+
+    def load(self):
+        """Load the ConvNeXt model from checkpoint"""
+        if self.loaded:
+            return
+
+        # Determine device
+        if self.device is None:
+            if torch.cuda.is_available():
+                self.device = "cuda"
+            elif torch.backends.mps.is_available():
+                self.device = "mps"
+            else:
+                self.device = "cpu"
+
+        # Create model
+        self.model = ConvNeXtDualEncoder(
+            model_name='convnext_base.fb_in22k_ft_in1k',
+            metadata_dim=19,
+            num_classes=11,
+            dropout=0.3
+        )
+
+        # Load checkpoint
+        checkpoint = torch.load(
+            self.checkpoint_path,
+            map_location=self.device,
+            weights_only=False
+        )
+
+        if isinstance(checkpoint, dict) and 'model_state_dict' in checkpoint:
+            self.model.load_state_dict(checkpoint['model_state_dict'])
+        else:
+            self.model.load_state_dict(checkpoint)
+
+        self.model.to(self.device)
+        self.model.eval()
+        self.loaded = True
+
+    def encode_metadata(
+        self,
+        age: Optional[float] = None,
+        sex: Optional[str] = None,
+        site: Optional[str] = None,
+        monet_scores: Optional[List[float]] = None
+    ) -> torch.Tensor:
+        """
+        Encode metadata into 19-dim vector.
+
+        Layout: [age(1), sex(4), site(7), monet(7)] = 19
+
+        Args:
+            age: Patient age in years
+            sex: 'male', 'female', 'other', or None
+            site: Anatomical site string
+            monet_scores: List of 7 MONET feature scores
+
+        Returns:
+            torch.Tensor of shape [19]
+        """
+        features = []
+
+        # Age (1 dim) - normalized
+        age_norm = (age - 50) / 30 if age is not None else 0.0
+        features.append(age_norm)
+
+        # Sex (4 dim) - one-hot
+        sex_onehot = [0.0] * 4
+        if sex:
+            sex_idx = self.SEX_MAPPING.get(sex.lower(), 3)
+            sex_onehot[sex_idx] = 1.0
+        features.extend(sex_onehot)
+
+        # Site (7 dim) - one-hot
+        site_onehot = [0.0] * 7
+        if site:
+            site_lower = site.lower()
+            for key, idx in self.SITE_MAPPING.items():
+                if key in site_lower:
+                    site_onehot[idx] = 1.0
+                    break
+        features.extend(site_onehot)
+
+        # MONET (7 dim)
+        if monet_scores is not None and len(monet_scores) == 7:
+            features.extend(monet_scores)
+        else:
+            features.extend([0.0] * 7)
+
+        return torch.tensor(features, dtype=torch.float32)
+
+    def preprocess_image(self, image: Image.Image) -> torch.Tensor:
+        """Preprocess PIL image for model input"""
+        if image.mode != "RGB":
+            image = image.convert("RGB")
+        return self.transform(image).unsqueeze(0)
+
+    def classify(
+        self,
+        clinical_image: Image.Image,
+        derm_image: Optional[Image.Image] = None,
+        age: Optional[float] = None,
+        sex: Optional[str] = None,
+        site: Optional[str] = None,
+        monet_scores: Optional[List[float]] = None,
+        top_k: int = 5
+    ) -> Dict:
+        """
+        Classify a skin lesion.
+
+        Args:
+            clinical_image: Clinical (close-up) image
+            derm_image: Dermoscopy image (optional, uses clinical if None)
+            age: Patient age
+            sex: Patient sex
+            site: Anatomical site
+            monet_scores: 7 MONET feature scores
+            top_k: Number of top predictions to return
+
+        Returns:
+            dict with 'predictions', 'probabilities', 'top_class', 'confidence'
+        """
+        if not self.loaded:
+            self.load()
+
+        # Preprocess images
+        clinical_tensor = self.preprocess_image(clinical_image).to(self.device)
+
+        if derm_image is not None:
+            derm_tensor = self.preprocess_image(derm_image).to(self.device)
+        else:
+            derm_tensor = None
+
+        # Encode metadata
+        metadata = self.encode_metadata(age, sex, site, monet_scores)
+        metadata_tensor = metadata.unsqueeze(0).to(self.device)
+
+        # Run inference
+        with torch.no_grad():
+            logits = self.model(clinical_tensor, derm_tensor, metadata_tensor)
+            probs = torch.softmax(logits, dim=1)[0].cpu().numpy()
+
+        # Get top-k predictions
+        top_indices = np.argsort(probs)[::-1][:top_k]
+
+        predictions = []
+        for idx in top_indices:
+            predictions.append({
+                'class': CLASS_NAMES[idx],
+                'full_name': CLASS_FULL_NAMES[CLASS_NAMES[idx]],
+                'probability': float(probs[idx])
+            })
+
+        return {
+            'predictions': predictions,
+            'probabilities': probs.tolist(),
+            'top_class': CLASS_NAMES[top_indices[0]],
+            'confidence': float(probs[top_indices[0]]),
+            'all_classes': CLASS_NAMES,
+        }
+
+    def __call__(
+        self,
+        clinical_image: Image.Image,
+        derm_image: Optional[Image.Image] = None,
+        **kwargs
+    ) -> Dict:
+        """Shorthand for classify()"""
+        return self.classify(clinical_image, derm_image, **kwargs)
+
+
+# Singleton instance
+_convnext_instance = None
+
+
+def get_convnext_classifier(checkpoint_path: str = "models/seed42_fold0.pt") -> ConvNeXtClassifier:
+    """Get or create ConvNeXt classifier instance"""
+    global _convnext_instance
+    if _convnext_instance is None:
+        _convnext_instance = ConvNeXtClassifier(checkpoint_path)
+    return _convnext_instance
+
+
+if __name__ == "__main__":
+    import sys
+
+    print("ConvNeXt Classifier Test")
+    print("=" * 50)
+
+    classifier = ConvNeXtClassifier()
+    print("Loading model...")
+    classifier.load()
+    print("Model loaded!")
+
+    if len(sys.argv) > 1:
+        image_path = sys.argv[1]
+        print(f"\nClassifying: {image_path}")
+
+        image = Image.open(image_path).convert("RGB")
+
+        # Example with mock MONET scores
+        monet_scores = [0.2, 0.1, 0.05, 0.3, 0.7, 0.1, 0.05]
+
+        result = classifier.classify(
+            clinical_image=image,
+            age=55,
+            sex="male",
+            site="back",
+            monet_scores=monet_scores
+        )
+
+        print("\nTop Predictions:")
+        for pred in result['predictions']:
+            print(f"  {pred['probability']:.1%} - {pred['class']} ({pred['full_name']})")

models/explainability.py

@@ -0,0 +1,183 @@
+# models/explainability.py
+
+import torch
+import torch.nn.functional as F
+import numpy as np
+import cv2
+from typing import Tuple
+from PIL import Image
+
+class GradCAM:
+    """
+    Gradient-weighted Class Activation Mapping
+    Shows which regions of image are important for prediction
+    """
+    
+    def __init__(self, model: torch.nn.Module, target_layer: str = None):
+        """
+        Args:
+            model: The neural network
+            target_layer: Layer name to compute CAM on (usually last conv layer)
+        """
+        self.model = model
+        self.gradients = None
+        self.activations = None
+        
+        # Auto-detect target layer if not specified
+        if target_layer is None:
+            # Use last ConvNeXt stage
+            self.target_layer = model.convnext.stages[-1]
+        else:
+            self.target_layer = dict(model.named_modules())[target_layer]
+        
+        # Register hooks
+        self.target_layer.register_forward_hook(self._save_activation)
+        self.target_layer.register_full_backward_hook(self._save_gradient)
+    
+    def _save_activation(self, module, input, output):
+        """Save forward activations"""
+        self.activations = output.detach()
+    
+    def _save_gradient(self, module, grad_input, grad_output):
+        """Save backward gradients"""
+        self.gradients = grad_output[0].detach()
+    
+    def generate_cam(
+        self,
+        image: torch.Tensor,
+        target_class: int = None
+    ) -> np.ndarray:
+        """
+        Generate Class Activation Map
+        
+        Args:
+            image: Input image [1, 3, H, W]
+            target_class: Class to generate CAM for (None = predicted class)
+            
+        Returns:
+            cam: Activation map [H, W] normalized to 0-1
+        """
+        self.model.eval()
+        
+        # Forward pass
+        output = self.model(image)
+        
+        # Use predicted class if not specified
+        if target_class is None:
+            target_class = output.argmax(dim=1).item()
+        
+        # Zero gradients
+        self.model.zero_grad()
+        
+        # Backward pass for target class
+        output[0, target_class].backward()
+        
+        # Get gradients and activations
+        gradients = self.gradients[0]  # [C, H, W]
+        activations = self.activations[0]  # [C, H, W]
+        
+        # Global average pooling of gradients
+        weights = gradients.mean(dim=(1, 2))  # [C]
+        
+        # Weighted sum of activations
+        cam = torch.zeros(activations.shape[1:], dtype=torch.float32)
+        for i, w in enumerate(weights):
+            cam += w * activations[i]
+        
+        # ReLU
+        cam = F.relu(cam)
+        
+        # Normalize to 0-1
+        cam = cam.cpu().numpy()
+        cam = cam - cam.min()
+        if cam.max() > 0:
+            cam = cam / cam.max()
+        
+        return cam
+    
+    def overlay_cam_on_image(
+        self,
+        image: np.ndarray,  # [H, W, 3] RGB
+        cam: np.ndarray,    # [h, w]
+        alpha: float = 0.5,
+        colormap: int = cv2.COLORMAP_JET
+    ) -> np.ndarray:
+        """
+        Overlay CAM heatmap on original image
+        
+        Returns:
+            overlay: [H, W, 3] RGB image with heatmap
+        """
+        H, W = image.shape[:2]
+        
+        # Resize CAM to image size
+        cam_resized = cv2.resize(cam, (W, H))
+        
+        # Convert to heatmap
+        heatmap = cv2.applyColorMap(
+            np.uint8(255 * cam_resized),
+            colormap
+        )
+        heatmap = cv2.cvtColor(heatmap, cv2.COLOR_BGR2RGB)
+        
+        # Blend with original image
+        overlay = (alpha * heatmap + (1 - alpha) * image).astype(np.uint8)
+        
+        return overlay
+
+class AttentionVisualizer:
+    """Visualize MedSigLIP attention maps"""
+    
+    def __init__(self, model):
+        self.model = model
+    
+    def get_attention_maps(self, image: torch.Tensor) -> np.ndarray:
+        """
+        Extract attention maps from MedSigLIP
+        
+        Returns:
+            attention: [num_heads, H, W] attention weights
+        """
+        # Forward pass
+        with torch.no_grad():
+            _ = self.model(image)
+        
+        # Get last layer attention from MedSigLIP
+        # Shape: [batch, num_heads, seq_len, seq_len]
+        attention = self.model.medsiglip_features
+        
+        # Average across heads and extract spatial attention
+        # This is model-dependent - adjust based on MedSigLIP architecture
+        
+        # Placeholder implementation
+        # You'll need to adapt this to your specific MedSigLIP implementation
+        return np.random.rand(14, 14)  # Placeholder
+    
+    def overlay_attention(
+        self,
+        image: np.ndarray,
+        attention: np.ndarray,
+        alpha: float = 0.6
+    ) -> np.ndarray:
+        """Overlay attention map on image"""
+        H, W = image.shape[:2]
+        
+        # Resize attention to image size
+        attention_resized = cv2.resize(attention, (W, H))
+        
+        # Normalize
+        attention_resized = (attention_resized - attention_resized.min())
+        if attention_resized.max() > 0:
+            attention_resized = attention_resized / attention_resized.max()
+        
+        # Create colored overlay
+        heatmap = cv2.applyColorMap(
+            np.uint8(255 * attention_resized),
+            cv2.COLORMAP_VIRIDIS
+        )
+        heatmap = cv2.cvtColor(heatmap, cv2.COLOR_BGR2RGB)
+        
+        # Blend
+        overlay = (alpha * heatmap + (1 - alpha) * image).astype(np.uint8)
+        
+        return overlay

models/gradcam_tool.py

@@ -0,0 +1,285 @@
+"""
+Grad-CAM Tool - Visual explanation of ConvNeXt predictions
+Shows which regions of the image the model focuses on.
+"""
+
+import torch
+import torch.nn.functional as F
+import numpy as np
+from PIL import Image
+from torchvision import transforms
+from typing import Optional, Tuple
+import cv2
+
+
+class GradCAM:
+    """
+    Grad-CAM implementation for ConvNeXt model.
+    Generates heatmaps showing model attention.
+    """
+
+    def __init__(self, model, target_layer=None):
+        """
+        Args:
+            model: ConvNeXtDualEncoder model
+            target_layer: Layer to extract gradients from (default: last conv layer)
+        """
+        self.model = model
+        self.gradients = None
+        self.activations = None
+
+        # Hook the target layer (last stage of backbone)
+        if target_layer is None:
+            target_layer = model.backbone.stages[-1]
+
+        target_layer.register_forward_hook(self._save_activation)
+        target_layer.register_full_backward_hook(self._save_gradient)
+
+    def _save_activation(self, module, input, output):
+        """Save activations during forward pass"""
+        self.activations = output.detach()
+
+    def _save_gradient(self, module, grad_input, grad_output):
+        """Save gradients during backward pass"""
+        self.gradients = grad_output[0].detach()
+
+    def generate(
+        self,
+        image_tensor: torch.Tensor,
+        target_class: Optional[int] = None,
+        derm_tensor: Optional[torch.Tensor] = None,
+        metadata: Optional[torch.Tensor] = None
+    ) -> np.ndarray:
+        """
+        Generate Grad-CAM heatmap.
+
+        Args:
+            image_tensor: Input image tensor [1, 3, H, W]
+            target_class: Class index to visualize (default: predicted class)
+            derm_tensor: Optional dermoscopy image tensor
+            metadata: Optional metadata tensor
+
+        Returns:
+            CAM heatmap as numpy array [H, W] normalized to 0-1
+        """
+        self.model.eval()
+
+        # Forward pass
+        output = self.model(image_tensor, derm_tensor, metadata)
+
+        if target_class is None:
+            target_class = output.argmax(dim=1).item()
+
+        # Backward pass for target class
+        self.model.zero_grad()
+        output[0, target_class].backward()
+
+        # Get gradients and activations
+        gradients = self.gradients[0]  # [C, H, W]
+        activations = self.activations[0]  # [C, H, W]
+
+        # Global average pooling of gradients
+        weights = gradients.mean(dim=(1, 2))  # [C]
+
+        # Weighted combination of activation maps
+        cam = torch.zeros(activations.shape[1:], dtype=torch.float32, device=activations.device)
+        for i, w in enumerate(weights):
+            cam += w * activations[i]
+
+        # ReLU and normalize
+        cam = F.relu(cam)
+        cam = cam.cpu().numpy()
+
+        if cam.max() > 0:
+            cam = (cam - cam.min()) / (cam.max() - cam.min())
+
+        return cam
+
+    def overlay(
+        self,
+        image: np.ndarray,
+        cam: np.ndarray,
+        alpha: float = 0.5,
+        colormap: int = cv2.COLORMAP_JET
+    ) -> np.ndarray:
+        """
+        Overlay CAM heatmap on original image.
+
+        Args:
+            image: Original image [H, W, 3] RGB uint8
+            cam: CAM heatmap [H, W] float 0-1
+            alpha: Overlay transparency
+            colormap: OpenCV colormap
+
+        Returns:
+            Overlaid image [H, W, 3] RGB uint8
+        """
+        H, W = image.shape[:2]
+
+        # Resize CAM to image size
+        cam_resized = cv2.resize(cam, (W, H))
+
+        # Apply colormap
+        heatmap = cv2.applyColorMap(
+            np.uint8(255 * cam_resized),
+            colormap
+        )
+        heatmap = cv2.cvtColor(heatmap, cv2.COLOR_BGR2RGB)
+
+        # Overlay
+        overlay = (alpha * heatmap + (1 - alpha) * image).astype(np.uint8)
+
+        return overlay
+
+
+class GradCAMTool:
+    """
+    High-level Grad-CAM tool for ConvNeXt classifier.
+    """
+
+    def __init__(self, classifier=None):
+        """
+        Args:
+            classifier: ConvNeXtClassifier instance (will create one if None)
+        """
+        self.classifier = classifier
+        self.gradcam = None
+        self.loaded = False
+
+        # Preprocessing
+        self.transform = transforms.Compose([
+            transforms.Resize((384, 384)),
+            transforms.ToTensor(),
+            transforms.Normalize(
+                mean=[0.485, 0.456, 0.406],
+                std=[0.229, 0.224, 0.225]
+            )
+        ])
+
+    def load(self):
+        """Load classifier and setup Grad-CAM"""
+        if self.loaded:
+            return
+
+        if self.classifier is None:
+            from models.convnext_classifier import ConvNeXtClassifier
+            self.classifier = ConvNeXtClassifier()
+            self.classifier.load()
+
+        self.gradcam = GradCAM(self.classifier.model)
+        self.loaded = True
+
+    def generate_heatmap(
+        self,
+        image: Image.Image,
+        target_class: Optional[int] = None
+    ) -> Tuple[np.ndarray, np.ndarray, int, float]:
+        """
+        Generate Grad-CAM heatmap for an image.
+
+        Args:
+            image: PIL Image
+            target_class: Class to visualize (default: predicted)
+
+        Returns:
+            Tuple of (overlay_image, cam_heatmap, predicted_class, confidence)
+        """
+        if not self.loaded:
+            self.load()
+
+        # Ensure RGB
+        if image.mode != "RGB":
+            image = image.convert("RGB")
+
+        # Preprocess
+        image_np = np.array(image.resize((384, 384)))
+        image_tensor = self.transform(image).unsqueeze(0).to(self.classifier.device)
+
+        # Get prediction first
+        with torch.no_grad():
+            logits = self.classifier.model(image_tensor)
+            probs = torch.softmax(logits, dim=1)[0]
+            pred_class = probs.argmax().item()
+            confidence = probs[pred_class].item()
+
+        # Use predicted class if not specified
+        if target_class is None:
+            target_class = pred_class
+
+        # Generate CAM
+        cam = self.gradcam.generate(image_tensor, target_class)
+
+        # Create overlay
+        overlay = self.gradcam.overlay(image_np, cam, alpha=0.5)
+
+        return overlay, cam, pred_class, confidence
+
+    def analyze(
+        self,
+        image: Image.Image,
+        target_class: Optional[int] = None
+    ) -> dict:
+        """
+        Full analysis with Grad-CAM visualization.
+
+        Args:
+            image: PIL Image
+            target_class: Class to visualize
+
+        Returns:
+            Dict with overlay_image, cam, prediction info
+        """
+        from models.convnext_classifier import CLASS_NAMES, CLASS_FULL_NAMES
+
+        overlay, cam, pred_class, confidence = self.generate_heatmap(image, target_class)
+
+        return {
+            "overlay": Image.fromarray(overlay),
+            "cam": cam,
+            "predicted_class": CLASS_NAMES[pred_class],
+            "predicted_class_full": CLASS_FULL_NAMES[CLASS_NAMES[pred_class]],
+            "confidence": confidence,
+            "class_index": pred_class,
+        }
+
+    def __call__(self, image: Image.Image, target_class: Optional[int] = None) -> dict:
+        return self.analyze(image, target_class)
+
+
+# Singleton
+_gradcam_instance = None
+
+
+def get_gradcam_tool() -> GradCAMTool:
+    """Get or create Grad-CAM tool instance"""
+    global _gradcam_instance
+    if _gradcam_instance is None:
+        _gradcam_instance = GradCAMTool()
+    return _gradcam_instance
+
+
+if __name__ == "__main__":
+    import sys
+
+    print("Grad-CAM Tool Test")
+    print("=" * 50)
+
+    tool = GradCAMTool()
+    print("Loading model...")
+    tool.load()
+    print("Model loaded!")
+
+    if len(sys.argv) > 1:
+        image_path = sys.argv[1]
+        print(f"\nAnalyzing: {image_path}")
+
+        image = Image.open(image_path).convert("RGB")
+        result = tool.analyze(image)
+
+        print(f"\nPrediction: {result['predicted_class']} ({result['confidence']:.1%})")
+        print(f"Full name: {result['predicted_class_full']}")
+
+        # Save overlay
+        output_path = image_path.rsplit(".", 1)[0] + "_gradcam.png"
+        result["overlay"].save(output_path)
+        print(f"\nGrad-CAM overlay saved to: {output_path}")

models/guidelines_rag.py

@@ -0,0 +1,349 @@
+"""
+Guidelines RAG System - Retrieval-Augmented Generation for clinical guidelines
+Uses FAISS for vector similarity search on chunked guideline PDFs.
+"""
+
+import os
+import json
+import re
+from pathlib import Path
+from typing import List, Dict, Optional, Tuple
+
+import numpy as np
+
+# Paths
+GUIDELINES_DIR = Path(__file__).parent.parent / "guidelines"
+INDEX_DIR = GUIDELINES_DIR / "index"
+FAISS_INDEX_PATH = INDEX_DIR / "faiss.index"
+CHUNKS_PATH = INDEX_DIR / "chunks.json"
+
+# Chunking parameters
+CHUNK_SIZE = 500  # tokens (approximate)
+CHUNK_OVERLAP = 50  # tokens overlap between chunks
+
+
+class GuidelinesRAG:
+    """
+    RAG system for clinical guidelines.
+    Extracts text from PDFs, chunks it, creates embeddings, and provides search.
+    """
+
+    def __init__(self):
+        self.index = None
+        self.chunks = []
+        self.embedder = None
+        self.loaded = False
+
+    def _load_embedder(self):
+        """Load sentence transformer model for embeddings"""
+        if self.embedder is None:
+            from sentence_transformers import SentenceTransformer
+            self.embedder = SentenceTransformer('all-MiniLM-L6-v2')
+
+    def _extract_pdf_text(self, pdf_path: Path) -> str:
+        """Extract text from a PDF file"""
+        try:
+            import pdfplumber
+            text_parts = []
+            with pdfplumber.open(pdf_path) as pdf:
+                for page in pdf.pages:
+                    page_text = page.extract_text()
+                    if page_text:
+                        text_parts.append(page_text)
+            return "\n\n".join(text_parts)
+        except ImportError:
+            # Fallback to PyPDF2
+            from PyPDF2 import PdfReader
+            reader = PdfReader(pdf_path)
+            text_parts = []
+            for page in reader.pages:
+                text = page.extract_text()
+                if text:
+                    text_parts.append(text)
+            return "\n\n".join(text_parts)
+
+    def _clean_text(self, text: str) -> str:
+        """Clean extracted text"""
+        # Remove excessive whitespace
+        text = re.sub(r'\s+', ' ', text)
+        # Remove page numbers and headers
+        text = re.sub(r'\n\d+\s*\n', '\n', text)
+        # Fix broken words from line breaks
+        text = re.sub(r'(\w)-\s+(\w)', r'\1\2', text)
+        return text.strip()
+
+    def _extract_pdf_with_pages(self, pdf_path: Path) -> List[Tuple[str, int]]:
+        """Extract text from PDF with page numbers"""
+        try:
+            import pdfplumber
+            pages = []
+            with pdfplumber.open(pdf_path) as pdf:
+                for i, page in enumerate(pdf.pages, 1):
+                    page_text = page.extract_text()
+                    if page_text:
+                        pages.append((page_text, i))
+            return pages
+        except ImportError:
+            from PyPDF2 import PdfReader
+            reader = PdfReader(pdf_path)
+            pages = []
+            for i, page in enumerate(reader.pages, 1):
+                text = page.extract_text()
+                if text:
+                    pages.append((text, i))
+            return pages
+
+    def _chunk_text(self, text: str, source: str, page_num: int = 0) -> List[Dict]:
+        """
+        Chunk text into overlapping segments.
+        Returns list of dicts with 'text', 'source', 'chunk_id', 'page'.
+        """
+        # Approximate tokens by words (rough estimate: 1 token ≈ 0.75 words)
+        words = text.split()
+        chunk_words = int(CHUNK_SIZE * 0.75)
+        overlap_words = int(CHUNK_OVERLAP * 0.75)
+
+        chunks = []
+        start = 0
+        chunk_id = 0
+
+        while start < len(words):
+            end = start + chunk_words
+            chunk_text = ' '.join(words[start:end])
+
+            # Try to end at sentence boundary
+            if end < len(words):
+                last_period = chunk_text.rfind('.')
+                if last_period > len(chunk_text) * 0.7:
+                    chunk_text = chunk_text[:last_period + 1]
+
+            chunks.append({
+                'text': chunk_text,
+                'source': source,
+                'chunk_id': chunk_id,
+                'page': page_num
+            })
+
+            start = end - overlap_words
+            chunk_id += 1
+
+        return chunks
+
+    def build_index(self, force_rebuild: bool = False) -> bool:
+        """
+        Build FAISS index from guideline PDFs.
+        Returns True if index was built, False if loaded from cache.
+        """
+        # Check if index already exists
+        if not force_rebuild and FAISS_INDEX_PATH.exists() and CHUNKS_PATH.exists():
+            return self.load_index()
+
+        print("Building guidelines index...")
+        self._load_embedder()
+
+        # Create index directory
+        INDEX_DIR.mkdir(parents=True, exist_ok=True)
+
+        # Extract and chunk all PDFs with page tracking
+        all_chunks = []
+        pdf_files = list(GUIDELINES_DIR.glob("*.pdf"))
+
+        for pdf_path in pdf_files:
+            print(f"  Processing: {pdf_path.name}")
+            pages = self._extract_pdf_with_pages(pdf_path)
+            pdf_chunks = 0
+            for page_text, page_num in pages:
+                cleaned = self._clean_text(page_text)
+                chunks = self._chunk_text(cleaned, pdf_path.name, page_num)
+                all_chunks.extend(chunks)
+                pdf_chunks += len(chunks)
+            print(f"    -> {pdf_chunks} chunks from {len(pages)} pages")
+
+        if not all_chunks:
+            print("No chunks extracted from PDFs!")
+            return False
+
+        self.chunks = all_chunks
+        print(f"Total chunks: {len(self.chunks)}")
+
+        # Generate embeddings
+        print("Generating embeddings...")
+        texts = [c['text'] for c in self.chunks]
+        embeddings = self.embedder.encode(texts, show_progress_bar=True)
+        embeddings = np.array(embeddings).astype('float32')
+
+        # Build FAISS index
+        import faiss
+        dimension = embeddings.shape[1]
+        self.index = faiss.IndexFlatIP(dimension)  # Inner product (cosine with normalized vectors)
+
+        # Normalize embeddings for cosine similarity
+        faiss.normalize_L2(embeddings)
+        self.index.add(embeddings)
+
+        # Save index and chunks
+        faiss.write_index(self.index, str(FAISS_INDEX_PATH))
+        with open(CHUNKS_PATH, 'w') as f:
+            json.dump(self.chunks, f)
+
+        print(f"Index saved to {INDEX_DIR}")
+        self.loaded = True
+        return True
+
+    def load_index(self) -> bool:
+        """Load persisted FAISS index and chunks"""
+        if not FAISS_INDEX_PATH.exists() or not CHUNKS_PATH.exists():
+            return False
+
+        import faiss
+        self.index = faiss.read_index(str(FAISS_INDEX_PATH))
+
+        with open(CHUNKS_PATH, 'r') as f:
+            self.chunks = json.load(f)
+
+        self._load_embedder()
+        self.loaded = True
+        return True
+
+    def search(self, query: str, k: int = 5) -> List[Dict]:
+        """
+        Search for relevant guideline chunks.
+        Returns list of chunks with similarity scores.
+        """
+        if not self.loaded:
+            if not self.load_index():
+                self.build_index()
+
+        import faiss
+
+        # Encode query
+        query_embedding = self.embedder.encode([query])
+        query_embedding = np.array(query_embedding).astype('float32')
+        faiss.normalize_L2(query_embedding)
+
+        # Search
+        scores, indices = self.index.search(query_embedding, k)
+
+        results = []
+        for score, idx in zip(scores[0], indices[0]):
+            if idx < len(self.chunks):
+                chunk = self.chunks[idx].copy()
+                chunk['score'] = float(score)
+                results.append(chunk)
+
+        return results
+
+    def get_management_context(self, diagnosis: str, features: Optional[str] = None) -> Tuple[str, List[Dict]]:
+        """
+        Get formatted context from guidelines for management recommendations.
+        Returns tuple of (context_string, references_list).
+        References can be used for citation hyperlinks.
+        """
+        # Build search query
+        query = f"{diagnosis} management treatment recommendations"
+        if features:
+            query += f" {features}"
+
+        chunks = self.search(query, k=5)
+
+        if not chunks:
+            return "No relevant guidelines found.", []
+
+        # Build context and collect references
+        context_parts = []
+        references = []
+
+        # Unicode superscript digits
+        superscripts = ['¹', '²', '³', '⁴', '⁵', '⁶', '⁷', '⁸', '⁹']
+
+        for i, chunk in enumerate(chunks, 1):
+            source = chunk['source'].replace('.pdf', '')
+            page = chunk.get('page', 0)
+            ref_id = f"ref{i}"
+            superscript = superscripts[i-1] if i <= len(superscripts) else f"[{i}]"
+
+            # Add reference marker with superscript
+            context_parts.append(f"[Source {superscript}] {chunk['text']}")
+
+            # Collect reference info
+            references.append({
+                'id': ref_id,
+                'source': source,
+                'page': page,
+                'file': chunk['source'],
+                'score': chunk.get('score', 0)
+            })
+
+        context = "\n\n".join(context_parts)
+        return context, references
+
+    def format_references_for_prompt(self, references: List[Dict]) -> str:
+        """Format references for inclusion in LLM prompt"""
+        if not references:
+            return ""
+
+        lines = ["\n**References:**"]
+        for ref in references:
+            lines.append(f"[{ref['id']}] {ref['source']}, p.{ref['page']}")
+        return "\n".join(lines)
+
+    def format_references_for_display(self, references: List[Dict]) -> str:
+        """
+        Format references with markers that frontend can parse into hyperlinks.
+        Uses format: [REF:id:source:page:file:superscript]
+        """
+        if not references:
+            return ""
+
+        # Unicode superscript digits
+        superscripts = ['¹', '²', '³', '⁴', '⁵', '⁶', '⁷', '⁸', '⁹']
+
+        lines = ["\n[REFERENCES]"]
+        for i, ref in enumerate(references, 1):
+            superscript = superscripts[i-1] if i <= len(superscripts) else f"[{i}]"
+            # Format: [REF:ref1:Melanoma Guidelines:5:melanoma.pdf:¹]
+            lines.append(f"[REF:{ref['id']}:{ref['source']}:{ref['page']}:{ref['file']}:{superscript}]")
+        lines.append("[/REFERENCES]")
+        return "\n".join(lines)
+
+
+# Singleton instance
+_rag_instance = None
+
+
+def get_guidelines_rag() -> GuidelinesRAG:
+    """Get or create RAG instance"""
+    global _rag_instance
+    if _rag_instance is None:
+        _rag_instance = GuidelinesRAG()
+    return _rag_instance
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("  Guidelines RAG System - Index Builder")
+    print("=" * 60)
+
+    rag = GuidelinesRAG()
+
+    # Build or rebuild index
+    import sys
+    force = "--force" in sys.argv
+    rag.build_index(force_rebuild=force)
+
+    # Test search
+    print("\n" + "=" * 60)
+    print("  Testing Search")
+    print("=" * 60)
+
+    test_queries = [
+        "melanoma management",
+        "actinic keratosis treatment",
+        "surgical excision margins"
+    ]
+
+    for query in test_queries:
+        print(f"\nQuery: '{query}'")
+        results = rag.search(query, k=2)
+        for r in results:
+            print(f"  [{r['score']:.3f}] {r['source']}: {r['text'][:100]}...")

models/medgemma_agent.py

@@ -0,0 +1,927 @@
+"""
+MedGemma Agent - LLM agent with tool calling and staged thinking feedback
+
+Pipeline: MedGemma independent exam → Tools (MONET/ConvNeXt/GradCAM) → MedGemma reconciliation → Management
+"""
+
+import sys
+import time
+import random
+import json
+import os
+import subprocess
+import threading
+from typing import Optional, Generator, Dict, Any
+from PIL import Image
+
+
+class MCPClient:
+    """
+    Minimal MCP client that communicates with a FastMCP subprocess over stdio.
+
+    Uses raw newline-delimited JSON-RPC 2.0 so the main process (Python 3.9)
+    does not need the mcp library. The subprocess is launched with python3.11
+    which has mcp installed.
+    """
+
+    def __init__(self):
+        self._process = None
+        self._lock = threading.Lock()
+        self._id_counter = 0
+
+    def _next_id(self) -> int:
+        self._id_counter += 1
+        return self._id_counter
+
+    def _send(self, obj: dict):
+        line = json.dumps(obj) + "\n"
+        self._process.stdin.write(line)
+        self._process.stdin.flush()
+
+    def _recv(self) -> dict:
+        while True:
+            line = self._process.stdout.readline()
+            if not line:
+                raise RuntimeError("MCP server closed connection unexpectedly")
+            line = line.strip()
+            if not line:
+                continue
+            msg = json.loads(line)
+            # Skip server-initiated notifications (no "id" key)
+            if "id" in msg:
+                return msg
+
+    def _initialize(self):
+        """Send MCP initialize handshake."""
+        req_id = self._next_id()
+        self._send({
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "SkinProAI", "version": "1.0.0"},
+            },
+        })
+        self._recv()  # consume initialize response
+        # Confirm initialization
+        self._send({
+            "jsonrpc": "2.0",
+            "method": "notifications/initialized",
+            "params": {},
+        })
+
+    def start(self):
+        """Spawn the MCP server subprocess and complete the handshake."""
+        root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        server_script = os.path.join(root, "mcp_server", "server.py")
+        self._process = subprocess.Popen(
+            [sys.executable, server_script],  # use same venv Python (has all ML packages)
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,  # line-buffered
+        )
+        self._initialize()
+
+    def call_tool_sync(self, tool_name: str, arguments: dict) -> dict:
+        """Call a tool synchronously and return the parsed result dict."""
+        with self._lock:
+            req_id = self._next_id()
+            self._send({
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "method": "tools/call",
+                "params": {"name": tool_name, "arguments": arguments},
+            })
+            response = self._recv()
+
+        # Protocol-level error (e.g. unknown method)
+        if "error" in response:
+            raise RuntimeError(
+                f"MCP tool '{tool_name}' failed: {response['error']}"
+            )
+
+        result = response["result"]
+        content_text = result["content"][0]["text"]
+
+        # Tool-level error (isError=True means the tool itself raised an exception)
+        if result.get("isError"):
+            raise RuntimeError(f"MCP tool '{tool_name}' error: {content_text}")
+
+        return json.loads(content_text)
+
+    def stop(self):
+        """Terminate the MCP server subprocess."""
+        if self._process:
+            try:
+                self._process.stdin.close()
+                self._process.terminate()
+                self._process.wait(timeout=5)
+            except Exception:
+                pass
+            self._process = None
+
+
+# Rotating verbs for spinner effect
+ANALYSIS_VERBS = [
+    "Analyzing", "Examining", "Processing", "Inspecting", "Evaluating",
+    "Scanning", "Assessing", "Reviewing", "Studying", "Interpreting"
+]
+
+# Comprehensive visual exam prompt (combined from 4 separate stages)
+COMPREHENSIVE_EXAM_PROMPT = """Perform a systematic dermoscopic examination of this skin lesion. Assess ALL of the following in a SINGLE concise analysis:
+
+1. PATTERN: Overall architecture, symmetry (symmetric/asymmetric), organization
+2. COLORS: List all colors present (brown, black, blue, white, red, pink) and distribution
+3. BORDER: Sharp vs gradual, regular vs irregular, any disruptions
+4. STRUCTURES: Pigment network, dots/globules, streaks, blue-white veil, regression, vessels
+
+Then provide:
+- Top 3 differential diagnoses with brief reasoning
+- Concern level (1-5, where 5=urgent)
+- Single most important feature driving your assessment
+
+Be CONCISE - focus on clinically relevant findings only."""
+
+
+def get_verb():
+    """Get a random analysis verb for spinner effect"""
+    return random.choice(ANALYSIS_VERBS)
+
+
+class MedGemmaAgent:
+    """
+    Medical image analysis agent with:
+    - Staged thinking display (no emojis)
+    - Tool calling (MONET, ConvNeXt, Grad-CAM)
+    - Streaming responses
+    """
+
+    def __init__(self, verbose: bool = True):
+        self.verbose = verbose
+        self.pipe = None
+        self.model_id = "google/medgemma-4b-it"
+        self.loaded = False
+
+        # Tools (legacy direct instances, kept for fallback / non-MCP use)
+        self.monet_tool = None
+        self.convnext_tool = None
+        self.gradcam_tool = None
+        self.rag_tool = None
+        self.tools_loaded = False
+
+        # MCP client
+        self.mcp_client = None
+
+        # State for confirmation flow
+        self.last_diagnosis = None
+        self.last_monet_result = None
+        self.last_image = None
+        self.last_medgemma_exam = None  # Store independent MedGemma findings
+        self.last_reconciliation = None
+
+    def reset_state(self):
+        """Reset analysis state for new analysis (keeps models loaded)"""
+        self.last_diagnosis = None
+        self.last_monet_result = None
+        self.last_image = None
+        self.last_medgemma_exam = None
+        self.last_reconciliation = None
+
+    def _print(self, message: str):
+        """Print if verbose"""
+        if self.verbose:
+            print(message, flush=True)
+
+    def load_model(self):
+        """Load MedGemma model"""
+        if self.loaded:
+            return
+
+        self._print("Initializing MedGemma agent...")
+
+        import torch
+        from transformers import pipeline
+
+        self._print(f"Loading model: {self.model_id}")
+
+        if torch.cuda.is_available():
+            device = "cuda"
+            self._print(f"Using GPU: {torch.cuda.get_device_name(0)}")
+        elif torch.backends.mps.is_available():
+            device = "mps"
+            self._print("Using Apple Silicon (MPS)")
+        else:
+            device = "cpu"
+            self._print("Using CPU")
+
+        model_kwargs = dict(
+            torch_dtype=torch.bfloat16 if device != "cpu" else torch.float32,
+            device_map="auto",
+        )
+
+        start = time.time()
+        self.pipe = pipeline(
+            "image-text-to-text",
+            model=self.model_id,
+            model_kwargs=model_kwargs
+        )
+
+        self._print(f"Model loaded in {time.time() - start:.1f}s")
+        self.loaded = True
+
+    def load_tools(self):
+        """Load tool models (MONET + ConvNeXt + Grad-CAM + RAG)"""
+        if self.tools_loaded:
+            return
+
+        from models.monet_tool import MonetTool
+        self.monet_tool = MonetTool()
+        self.monet_tool.load()
+
+        from models.convnext_classifier import ConvNeXtClassifier
+        self.convnext_tool = ConvNeXtClassifier()
+        self.convnext_tool.load()
+
+        from models.gradcam_tool import GradCAMTool
+        self.gradcam_tool = GradCAMTool(classifier=self.convnext_tool)
+        self.gradcam_tool.load()
+
+        from models.guidelines_rag import get_guidelines_rag
+        self.rag_tool = get_guidelines_rag()
+        if not self.rag_tool.loaded:
+            self.rag_tool.load_index()
+
+        self.tools_loaded = True
+
+    def load_tools_via_mcp(self):
+        """Start the MCP server subprocess and mark tools as loaded."""
+        if self.tools_loaded:
+            return
+        self.mcp_client = MCPClient()
+        self.mcp_client.start()
+        self.tools_loaded = True
+
+    def _multi_pass_visual_exam(self, image, question: Optional[str] = None) -> Generator[str, None, Dict[str, str]]:
+        """
+        MedGemma performs comprehensive visual examination BEFORE tools run.
+        Single prompt covers pattern, colors, borders, structures, and differentials.
+        Returns findings dict after yielding all output.
+        """
+        findings = {}
+
+        yield f"\n[STAGE:medgemma_exam]MedGemma Visual Examination[/STAGE]\n"
+        yield f"[THINKING]Performing systematic dermoscopic assessment...[/THINKING]\n"
+
+        # Build prompt with optional clinical question
+        exam_prompt = COMPREHENSIVE_EXAM_PROMPT
+        if question:
+            exam_prompt += f"\n\nCLINICAL QUESTION: {question}"
+
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": image},
+                    {"type": "text", "text": exam_prompt}
+                ]
+            }
+        ]
+
+        try:
+            time.sleep(0.2)
+            output = self.pipe(messages, max_new_tokens=400)
+            result = output[0]["generated_text"][-1]["content"]
+            findings['synthesis'] = result
+
+            yield f"[RESPONSE]\n"
+            words = result.split()
+            for i, word in enumerate(words):
+                time.sleep(0.015)
+                yield word + (" " if i < len(words) - 1 else "")
+            yield f"\n[/RESPONSE]\n"
+
+        except Exception as e:
+            findings['synthesis'] = f"Analysis failed: {e}"
+            yield f"[ERROR]Visual examination failed: {e}[/ERROR]\n"
+
+        self.last_medgemma_exam = findings
+        return findings
+
+    def _reconcile_findings(
+        self,
+        image,
+        medgemma_exam: Dict[str, str],
+        monet_result: Dict[str, Any],
+        convnext_result: Dict[str, Any],
+        question: Optional[str] = None
+    ) -> Generator[str, None, None]:
+        """
+        MedGemma reconciles its independent findings with tool outputs.
+        Identifies agreements, disagreements, and provides integrated assessment.
+        """
+        yield f"\n[STAGE:reconciliation]Reconciling MedGemma Findings with Tool Results[/STAGE]\n"
+        yield f"[THINKING]Comparing independent visual assessment against AI classification tools...[/THINKING]\n"
+
+        top = convnext_result['predictions'][0]
+        runner_up = convnext_result['predictions'][1] if len(convnext_result['predictions']) > 1 else None
+
+        # Build MONET features string
+        monet_top = sorted(monet_result["features"].items(), key=lambda x: x[1], reverse=True)[:5]
+        monet_str = ", ".join([f"{k.replace('MONET_', '').replace('_', ' ')}: {v:.0%}" for k, v in monet_top])
+
+        reconciliation_prompt = f"""You performed an independent visual examination of this lesion and concluded:
+
+YOUR ASSESSMENT:
+{medgemma_exam.get('synthesis', 'Not available')[:600]}
+
+The AI classification tools produced these results:
+- ConvNeXt classifier: {top['full_name']} ({top['probability']:.1%} confidence)
+{f"- Runner-up: {runner_up['full_name']} ({runner_up['probability']:.1%})" if runner_up else ""}
+- Key MONET features: {monet_str}
+
+{f'CLINICAL QUESTION: {question}' if question else ''}
+
+Reconcile your visual findings with the AI classification:
+1. AGREEMENT/DISAGREEMENT: Do your findings support the AI diagnosis? Any conflicts?
+2. INTEGRATED ASSESSMENT: Final diagnosis considering all evidence
+3. CONFIDENCE (1-10): How certain? What would change your assessment?
+
+Be concise and specific."""
+
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": image},
+                    {"type": "text", "text": reconciliation_prompt}
+                ]
+            }
+        ]
+
+        try:
+            output = self.pipe(messages, max_new_tokens=300)
+            reconciliation = output[0]["generated_text"][-1]["content"]
+            self.last_reconciliation = reconciliation
+
+            yield f"[RESPONSE]\n"
+            words = reconciliation.split()
+            for i, word in enumerate(words):
+                time.sleep(0.015)
+                yield word + (" " if i < len(words) - 1 else "")
+            yield f"\n[/RESPONSE]\n"
+
+        except Exception as e:
+            yield f"[ERROR]Reconciliation failed: {e}[/ERROR]\n"
+
+    def analyze_image_stream(
+        self,
+        image_path: str,
+        question: Optional[str] = None,
+        max_tokens: int = 512,
+        use_tools: bool = True
+    ) -> Generator[str, None, None]:
+        """
+        Stream analysis with new pipeline:
+        1. MedGemma independent multi-pass exam
+        2. MONET + ConvNeXt + GradCAM tools
+        3. MedGemma reconciliation
+        4. Confirmation request
+        """
+        if not self.loaded:
+            yield "[STAGE:loading]Initializing MedGemma...[/STAGE]\n"
+            self.load_model()
+
+        yield f"[STAGE:image]{get_verb()} image...[/STAGE]\n"
+
+        try:
+            image = Image.open(image_path).convert("RGB")
+            self.last_image = image
+        except Exception as e:
+            yield f"[ERROR]Failed to load image: {e}[/ERROR]\n"
+            return
+
+        # Load tools early via MCP subprocess
+        if use_tools and not self.tools_loaded:
+            yield f"[STAGE:tools]Loading analysis tools...[/STAGE]\n"
+            self.load_tools_via_mcp()
+
+        # ===== PHASE 1: MedGemma Independent Visual Examination =====
+        medgemma_exam = {}
+        for chunk in self._multi_pass_visual_exam(image, question):
+            yield chunk
+            if isinstance(chunk, dict):
+                medgemma_exam = chunk
+        medgemma_exam = self.last_medgemma_exam or {}
+
+        monet_result = None
+        convnext_result = None
+
+        if use_tools:
+            # ===== PHASE 2: Run Classification Tools =====
+            yield f"\n[STAGE:tools_run]Running AI Classification Tools[/STAGE]\n"
+            yield f"[THINKING]Now running MONET and ConvNeXt to compare against visual examination...[/THINKING]\n"
+
+            # MONET Feature Extraction
+            time.sleep(0.2)
+            yield f"\n[STAGE:monet]MONET Feature Extraction[/STAGE]\n"
+
+            try:
+                monet_result = self.mcp_client.call_tool_sync(
+                    "monet_analyze", {"image_path": image_path}
+                )
+                self.last_monet_result = monet_result
+
+                yield f"[TOOL_OUTPUT:MONET Features]\n"
+                for name, score in monet_result["features"].items():
+                    short_name = name.replace("MONET_", "").replace("_", " ").title()
+                    bar_filled = int(score * 10)
+                    bar = "|" + "=" * bar_filled + "-" * (10 - bar_filled) + "|"
+                    yield f"  {short_name}: {bar} {score:.0%}\n"
+                yield f"[/TOOL_OUTPUT]\n"
+
+            except Exception as e:
+                yield f"[ERROR]MONET failed: {e}[/ERROR]\n"
+
+            # ConvNeXt Classification
+            time.sleep(0.2)
+            yield f"\n[STAGE:convnext]ConvNeXt Classification[/STAGE]\n"
+
+            try:
+                monet_scores = monet_result["vector"] if monet_result else None
+                convnext_result = self.mcp_client.call_tool_sync(
+                    "classify_lesion",
+                    {
+                        "image_path": image_path,
+                        "monet_scores": monet_scores,
+                    },
+                )
+                self.last_diagnosis = convnext_result
+
+                yield f"[TOOL_OUTPUT:Classification Results]\n"
+                for pred in convnext_result["predictions"][:5]:
+                    prob = pred['probability']
+                    bar_filled = int(prob * 20)
+                    bar = "|" + "=" * bar_filled + "-" * (20 - bar_filled) + "|"
+                    yield f"  {pred['class']}: {bar} {prob:.1%}\n"
+                    yield f"    {pred['full_name']}\n"
+                yield f"[/TOOL_OUTPUT]\n"
+
+                top = convnext_result['predictions'][0]
+                yield f"[RESULT]ConvNeXt Primary: {top['full_name']} ({top['probability']:.1%})[/RESULT]\n"
+
+            except Exception as e:
+                yield f"[ERROR]ConvNeXt failed: {e}[/ERROR]\n"
+
+            # Grad-CAM Visualization
+            time.sleep(0.2)
+            yield f"\n[STAGE:gradcam]Grad-CAM Attention Map[/STAGE]\n"
+
+            try:
+                gradcam_result = self.mcp_client.call_tool_sync(
+                    "generate_gradcam", {"image_path": image_path}
+                )
+                gradcam_path = gradcam_result["gradcam_path"]
+                yield f"[GRADCAM_IMAGE:{gradcam_path}]\n"
+            except Exception as e:
+                yield f"[ERROR]Grad-CAM failed: {e}[/ERROR]\n"
+
+            # ===== PHASE 3: MedGemma Reconciliation =====
+            if convnext_result and monet_result and medgemma_exam:
+                for chunk in self._reconcile_findings(
+                    image, medgemma_exam, monet_result, convnext_result, question
+                ):
+                    yield chunk
+
+        # Yield confirmation request
+        if convnext_result:
+            top = convnext_result['predictions'][0]
+            yield f"\n[CONFIRM:diagnosis]Do you agree with the integrated assessment?[/CONFIRM]\n"
+
+    def generate_management_guidance(
+        self,
+        user_confirmed: bool = True,
+        user_feedback: Optional[str] = None
+    ) -> Generator[str, None, None]:
+        """
+        Generate LESION-SPECIFIC management guidance using RAG + MedGemma reasoning.
+        References specific findings from this analysis, not generic textbook management.
+        """
+        if not self.last_diagnosis:
+            yield "[ERROR]No diagnosis available. Please analyze an image first.[/ERROR]\n"
+            return
+
+        top = self.last_diagnosis['predictions'][0]
+        runner_up = self.last_diagnosis['predictions'][1] if len(self.last_diagnosis['predictions']) > 1 else None
+        diagnosis = top['full_name']
+
+        if not user_confirmed and user_feedback:
+            yield f"[THINKING]Clinician provided alternative assessment: {user_feedback}[/THINKING]\n"
+            diagnosis = user_feedback
+
+        # Stage: RAG Search
+        time.sleep(0.3)
+        yield f"\n[STAGE:guidelines]Searching clinical guidelines for {diagnosis}...[/STAGE]\n"
+
+        # Get RAG context via MCP
+        features_desc = self.last_monet_result.get('description', '') if self.last_monet_result else ''
+        rag_data = self.mcp_client.call_tool_sync(
+            "search_guidelines",
+            {"query": features_desc, "diagnosis": diagnosis},
+        )
+        context = rag_data["context"]
+        references = rag_data["references"]
+
+        # Check guideline relevance
+        has_relevant_guidelines = False
+        if references:
+            diagnosis_lower = diagnosis.lower()
+            for ref in references:
+                source_lower = ref['source'].lower()
+                if any(term in diagnosis_lower for term in ['melanoma']) and 'melanoma' in source_lower:
+                    has_relevant_guidelines = True
+                    break
+                elif 'actinic' in diagnosis_lower and 'actinic' in source_lower:
+                    has_relevant_guidelines = True
+                    break
+                elif ref.get('score', 0) > 0.7:
+                    has_relevant_guidelines = True
+                    break
+
+        if not references or not has_relevant_guidelines:
+            yield f"[THINKING]No specific published guidelines for {diagnosis}. Using clinical knowledge.[/THINKING]\n"
+            context = "No specific clinical guidelines available."
+            references = []
+
+        # Build MONET features for context
+        monet_features = ""
+        if self.last_monet_result:
+            top_features = sorted(self.last_monet_result["features"].items(), key=lambda x: x[1], reverse=True)[:5]
+            monet_features = ", ".join([f"{k.replace('MONET_', '').replace('_', ' ')}: {v:.0%}" for k, v in top_features])
+
+        # Stage: Lesion-Specific Management Reasoning
+        time.sleep(0.3)
+        yield f"\n[STAGE:management]Generating Lesion-Specific Management Plan[/STAGE]\n"
+        yield f"[THINKING]Creating management plan tailored to THIS lesion's specific characteristics...[/THINKING]\n"
+
+        management_prompt = f"""Generate a CONCISE management plan for this lesion:
+
+DIAGNOSIS: {diagnosis} ({top['probability']:.1%})
+{f"Alternative: {runner_up['full_name']} ({runner_up['probability']:.1%})" if runner_up else ""}
+KEY FEATURES: {monet_features}
+
+{f"GUIDELINES: {context[:800]}" if context else ""}
+
+Provide:
+1. RECOMMENDED ACTION: Biopsy, excision, monitoring, or discharge - with specific reasoning
+2. URGENCY: Routine vs urgent vs same-day referral
+3. KEY CONCERNS: What features drive this recommendation
+
+Be specific to THIS lesion. 3-5 sentences maximum."""
+
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": self.last_image},
+                    {"type": "text", "text": management_prompt}
+                ]
+            }
+        ]
+
+        # Generate response
+        start = time.time()
+        try:
+            output = self.pipe(messages, max_new_tokens=250)
+            response = output[0]["generated_text"][-1]["content"]
+
+            yield f"[RESPONSE]\n"
+            words = response.split()
+            for i, word in enumerate(words):
+                time.sleep(0.015)
+                yield word + (" " if i < len(words) - 1 else "")
+            yield f"\n[/RESPONSE]\n"
+
+        except Exception as e:
+            yield f"[ERROR]Management generation failed: {e}[/ERROR]\n"
+
+        # Output references (pre-formatted by MCP server)
+        if references:
+            yield rag_data["references_display"]
+
+        yield f"\n[COMPLETE]Lesion-specific management plan generated in {time.time() - start:.1f}s[/COMPLETE]\n"
+
+        # Store response for recommendation extraction
+        self.last_management_response = response
+
+    def extract_recommendation(self) -> Generator[str, None, Dict[str, Any]]:
+        """
+        Extract structured recommendation from management guidance.
+        Determines: BIOPSY, EXCISION, FOLLOWUP, or DISCHARGE
+        For BIOPSY/EXCISION, gets coordinates from MedGemma.
+        """
+        if not self.last_management_response or not self.last_image:
+            yield "[ERROR]No management guidance available[/ERROR]\n"
+            return {"action": "UNKNOWN"}
+
+        yield f"\n[STAGE:recommendation]Extracting Clinical Recommendation[/STAGE]\n"
+
+        # Ask MedGemma to classify the recommendation
+        classification_prompt = f"""Based on the management plan you just provided:
+
+{self.last_management_response[:1000]}
+
+Classify the PRIMARY recommended action into exactly ONE of these categories:
+- BIOPSY: If punch biopsy, shave biopsy, or incisional biopsy is recommended
+- EXCISION: If complete surgical excision is recommended
+- FOLLOWUP: If monitoring with repeat photography/dermoscopy is recommended
+- DISCHARGE: If the lesion is clearly benign and no follow-up needed
+
+Respond with ONLY the category name (BIOPSY, EXCISION, FOLLOWUP, or DISCHARGE) on the first line.
+Then on the second line, provide a brief (1 sentence) justification."""
+
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": self.last_image},
+                    {"type": "text", "text": classification_prompt}
+                ]
+            }
+        ]
+
+        try:
+            output = self.pipe(messages, max_new_tokens=100)
+            response = output[0]["generated_text"][-1]["content"].strip()
+            lines = response.split('\n')
+            action = lines[0].strip().upper()
+            justification = lines[1].strip() if len(lines) > 1 else ""
+
+            # Validate action
+            valid_actions = ["BIOPSY", "EXCISION", "FOLLOWUP", "DISCHARGE"]
+            if action not in valid_actions:
+                # Try to extract from response
+                for valid in valid_actions:
+                    if valid in response.upper():
+                        action = valid
+                        break
+                else:
+                    action = "FOLLOWUP"  # Default to safe option
+
+            yield f"[RESULT]Recommended Action: {action}[/RESULT]\n"
+            yield f"[OBSERVATION]{justification}[/OBSERVATION]\n"
+
+            result = {
+                "action": action,
+                "justification": justification
+            }
+
+            return result
+
+        except Exception as e:
+            yield f"[ERROR]Failed to extract recommendation: {e}[/ERROR]\n"
+            return {"action": "UNKNOWN", "error": str(e)}
+
+    def compare_followup_images(
+        self,
+        previous_image_path: str,
+        current_image_path: str
+    ) -> Generator[str, None, None]:
+        """
+        Compare a follow-up image with the previous one.
+        Runs full analysis pipeline on current image, then compares findings.
+        """
+        yield f"\n[STAGE:comparison]Follow-up Comparison Analysis[/STAGE]\n"
+
+        try:
+            current_image = Image.open(current_image_path).convert("RGB")
+        except Exception as e:
+            yield f"[ERROR]Failed to load images: {e}[/ERROR]\n"
+            return
+
+        # Store previous analysis state
+        prev_exam = self.last_medgemma_exam
+
+        # Generate comparison image and MONET deltas via MCP
+        yield f"\n[STAGE:current_analysis]Analyzing Current Image[/STAGE]\n"
+
+        if self.tools_loaded:
+            try:
+                compare_data = self.mcp_client.call_tool_sync(
+                    "compare_images",
+                    {
+                        "image1_path": previous_image_path,
+                        "image2_path": current_image_path,
+                    },
+                )
+                yield f"[COMPARISON_IMAGE:{compare_data['comparison_path']}]\n"
+
+                # Side-by-side GradCAM comparison if both paths available
+                prev_gc = compare_data.get("prev_gradcam_path")
+                curr_gc = compare_data.get("curr_gradcam_path")
+                if prev_gc and curr_gc:
+                    yield f"[GRADCAM_COMPARE:{prev_gc}:{curr_gc}]\n"
+
+                # Display MONET feature deltas
+                if compare_data["monet_deltas"]:
+                    yield f"[TOOL_OUTPUT:Feature Comparison]\n"
+                    for name, delta_info in compare_data["monet_deltas"].items():
+                        prev_val = delta_info["previous"]
+                        curr_val = delta_info["current"]
+                        diff = delta_info["delta"]
+                        short_name = name.replace("MONET_", "").replace("_", " ").title()
+                        direction = "↑" if diff > 0 else "↓"
+                        yield f"  {short_name}: {prev_val:.0%} → {curr_val:.0%} ({direction}{abs(diff):.0%})\n"
+                    yield f"[/TOOL_OUTPUT]\n"
+
+            except Exception as e:
+                yield f"[ERROR]MCP comparison failed: {e}[/ERROR]\n"
+
+        # MedGemma comparison analysis
+        comparison_prompt = f"""You are comparing TWO images of the same skin lesion taken at different times.
+
+PREVIOUS ANALYSIS:
+{prev_exam.get('synthesis', 'Not available')[:500] if prev_exam else 'Not available'}
+
+Now examine the CURRENT image and compare to your memory of the previous findings.
+
+Assess for changes in:
+1. SIZE: Has the lesion grown, shrunk, or stayed the same?
+2. COLOR: Any new colors appeared? Any colors faded?
+3. SHAPE/SYMMETRY: Has the shape changed? More or less symmetric?
+4. BORDERS: Sharper, more irregular, or unchanged?
+5. STRUCTURES: New dermoscopic structures? Lost structures?
+
+Provide your assessment:
+- CHANGE_LEVEL: SIGNIFICANT_CHANGE / MINOR_CHANGE / STABLE / IMPROVED
+- Specific changes observed
+- Clinical recommendation based on changes"""
+
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": current_image},
+                    {"type": "text", "text": comparison_prompt}
+                ]
+            }
+        ]
+
+        try:
+            yield f"[THINKING]Comparing current image to previous findings...[/THINKING]\n"
+            output = self.pipe(messages, max_new_tokens=400)
+            comparison_result = output[0]["generated_text"][-1]["content"]
+
+            yield f"[RESPONSE]\n"
+            words = comparison_result.split()
+            for i, word in enumerate(words):
+                time.sleep(0.02)
+                yield word + (" " if i < len(words) - 1 else "")
+            yield f"\n[/RESPONSE]\n"
+
+            # Extract change level
+            change_level = "UNKNOWN"
+            for level in ["SIGNIFICANT_CHANGE", "MINOR_CHANGE", "STABLE", "IMPROVED"]:
+                if level in comparison_result.upper():
+                    change_level = level
+                    break
+
+            if change_level == "SIGNIFICANT_CHANGE":
+                yield f"[RESULT]⚠️ SIGNIFICANT CHANGES DETECTED - Further evaluation recommended[/RESULT]\n"
+            elif change_level == "IMPROVED":
+                yield f"[RESULT]✓ LESION IMPROVED - Continue monitoring[/RESULT]\n"
+            elif change_level == "STABLE":
+                yield f"[RESULT]✓ LESION STABLE - Continue scheduled follow-up[/RESULT]\n"
+            else:
+                yield f"[RESULT]Minor changes noted - Clinical correlation recommended[/RESULT]\n"
+
+        except Exception as e:
+            yield f"[ERROR]Comparison analysis failed: {e}[/ERROR]\n"
+
+        yield f"\n[COMPLETE]Follow-up comparison complete[/COMPLETE]\n"
+
+    def chat(self, message: str, image_path: Optional[str] = None) -> str:
+        """Simple chat interface"""
+        if not self.loaded:
+            self.load_model()
+
+        content = []
+        if image_path:
+            image = Image.open(image_path).convert("RGB")
+            content.append({"type": "image", "image": image})
+        content.append({"type": "text", "text": message})
+
+        messages = [{"role": "user", "content": content}]
+        output = self.pipe(messages, max_new_tokens=512)
+        return output[0]["generated_text"][-1]["content"]
+
+    def chat_followup(self, message: str) -> Generator[str, None, None]:
+        """
+        Handle follow-up questions using the stored analysis context.
+        Uses the last analyzed image and diagnosis to provide contextual responses.
+        """
+        if not self.loaded:
+            yield "[ERROR]Model not loaded[/ERROR]\n"
+            return
+
+        if not self.last_diagnosis or not self.last_image:
+            yield "[ERROR]No previous analysis context. Please analyze an image first.[/ERROR]\n"
+            return
+
+        # Build context from previous analysis
+        top_diagnosis = self.last_diagnosis['predictions'][0]
+        differentials = ", ".join([
+            f"{p['class']} ({p['probability']:.0%})"
+            for p in self.last_diagnosis['predictions'][:3]
+        ])
+
+        monet_desc = ""
+        if self.last_monet_result:
+            monet_desc = self.last_monet_result.get('description', '')
+
+        context_prompt = f"""You are a dermatology assistant helping with skin lesion analysis.
+
+PREVIOUS ANALYSIS CONTEXT:
+- Primary diagnosis: {top_diagnosis['full_name']} ({top_diagnosis['probability']:.1%} confidence)
+- Differential diagnoses: {differentials}
+- Visual features: {monet_desc}
+
+The user has a follow-up question about this lesion. Please provide a helpful, medically accurate response.
+
+USER QUESTION: {message}
+
+Provide a concise, informative response. If the question is outside your expertise or requires in-person examination, say so."""
+
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": self.last_image},
+                    {"type": "text", "text": context_prompt}
+                ]
+            }
+        ]
+
+        try:
+            yield f"[THINKING]Considering your question in context of the previous analysis...[/THINKING]\n"
+            time.sleep(0.2)
+
+            output = self.pipe(messages, max_new_tokens=400)
+            response = output[0]["generated_text"][-1]["content"]
+
+            yield f"[RESPONSE]\n"
+            # Stream word by word for typewriter effect
+            words = response.split()
+            for i, word in enumerate(words):
+                time.sleep(0.02)
+                yield word + (" " if i < len(words) - 1 else "")
+            yield f"\n[/RESPONSE]\n"
+
+        except Exception as e:
+            yield f"[ERROR]Failed to generate response: {e}[/ERROR]\n"
+
+
+def main():
+    """Interactive terminal interface"""
+    print("=" * 60)
+    print("  MedGemma Agent - Medical Image Analysis")
+    print("=" * 60)
+
+    agent = MedGemmaAgent(verbose=True)
+    agent.load_model()
+
+    print("\nCommands: analyze <path>, chat <message>, quit")
+
+    while True:
+        try:
+            user_input = input("\n> ").strip()
+            if not user_input:
+                continue
+
+            if user_input.lower() in ["quit", "exit", "q"]:
+                break
+
+            parts = user_input.split(maxsplit=1)
+            cmd = parts[0].lower()
+
+            if cmd == "analyze" and len(parts) > 1:
+                for chunk in agent.analyze_image_stream(parts[1].strip()):
+                    print(chunk, end="", flush=True)
+
+            elif cmd == "chat" and len(parts) > 1:
+                print(agent.chat(parts[1]))
+
+            else:
+                print("Unknown command")
+
+        except KeyboardInterrupt:
+            break
+        except Exception as e:
+            print(f"Error: {e}")
+
+
+if __name__ == "__main__":
+    main()

models/medsiglip_convnext_fusion.py

@@ -0,0 +1,224 @@
+# models/medsiglip_convnext_fusion.py
+
+import torch
+import torch.nn as nn
+from typing import Dict, List, Tuple, Optional
+import numpy as np
+import timm
+from transformers import AutoModel, AutoProcessor
+
+class MedSigLIPConvNeXtFusion(nn.Module):
+    """
+    Your trained MedSigLIP-ConvNeXt fusion model from MILK10 challenge
+    Supports 11-class skin lesion classification
+    """
+    
+    # Class names from your training
+    CLASS_NAMES = [
+        'AKIEC',      # Actinic Keratoses and Intraepithelial Carcinoma
+        'BCC',        # Basal Cell Carcinoma
+        'BEN_OTH',    # Benign Other
+        'BKL',        # Benign Keratosis-like Lesions
+        'DF',         # Dermatofibroma
+        'INF',        # Inflammatory
+        'MAL_OTH',    # Malignant Other
+        'MEL',        # Melanoma
+        'NV',         # Melanocytic Nevi
+        'SCCKA',      # Squamous Cell Carcinoma and Keratoacanthoma
+        'VASC'        # Vascular Lesions
+    ]
+    
+    def __init__(
+        self,
+        num_classes: int = 11,
+        medsiglip_model: str = "google/medsiglip-base",
+        convnext_variant: str = "convnext_base",
+        fusion_dim: int = 512,
+        dropout: float = 0.3,
+        metadata_dim: int = 20  # For metadata features
+    ):
+        super().__init__()
+        
+        self.num_classes = num_classes
+        
+        # MedSigLIP Vision Encoder
+        print(f"Loading MedSigLIP: {medsiglip_model}")
+        self.medsiglip = AutoModel.from_pretrained(medsiglip_model)
+        self.medsiglip_processor = AutoProcessor.from_pretrained(medsiglip_model)
+        
+        # ConvNeXt Backbone
+        print(f"Loading ConvNeXt: {convnext_variant}")
+        self.convnext = timm.create_model(
+            convnext_variant,
+            pretrained=True,
+            num_classes=0,
+            global_pool='avg'
+        )
+        
+        # Feature dimensions
+        self.medsiglip_dim = self.medsiglip.config.hidden_size  # 768
+        self.convnext_dim = self.convnext.num_features  # 1024
+        
+        # Optional metadata branch
+        self.use_metadata = metadata_dim > 0
+        if self.use_metadata:
+            self.metadata_encoder = nn.Sequential(
+                nn.Linear(metadata_dim, 64),
+                nn.LayerNorm(64),
+                nn.GELU(),
+                nn.Dropout(0.2),
+                nn.Linear(64, 32)
+            )
+            total_dim = self.medsiglip_dim + self.convnext_dim + 32
+        else:
+            total_dim = self.medsiglip_dim + self.convnext_dim
+        
+        # Fusion layers
+        self.fusion = nn.Sequential(
+            nn.Linear(total_dim, fusion_dim),
+            nn.LayerNorm(fusion_dim),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(fusion_dim, fusion_dim // 2),
+            nn.LayerNorm(fusion_dim // 2),
+            nn.GELU(),
+            nn.Dropout(dropout)
+        )
+        
+        # Classification head
+        self.classifier = nn.Linear(fusion_dim // 2, num_classes)
+        
+        # Store intermediate features for Grad-CAM
+        self.convnext_features = None
+        self.medsiglip_features = None
+        
+        # Register hooks
+        self.convnext.stages[-1].register_forward_hook(self._save_convnext_features)
+        
+    def _save_convnext_features(self, module, input, output):
+        """Hook to save ConvNeXt feature maps for Grad-CAM"""
+        self.convnext_features = output
+    
+    def forward(
+        self, 
+        image: torch.Tensor,
+        metadata: Optional[torch.Tensor] = None
+    ) -> torch.Tensor:
+        """
+        Forward pass
+        
+        Args:
+            image: [B, 3, H, W] tensor
+            metadata: [B, metadata_dim] optional metadata features
+            
+        Returns:
+            logits: [B, num_classes]
+        """
+        # MedSigLIP features
+        medsiglip_out = self.medsiglip.vision_model(image)
+        medsiglip_features = medsiglip_out.pooler_output  # [B, 768]
+        
+        # ConvNeXt features  
+        convnext_features = self.convnext(image)  # [B, 1024]
+        
+        # Concatenate vision features
+        fused = torch.cat([medsiglip_features, convnext_features], dim=1)
+        
+        # Add metadata if available
+        if self.use_metadata and metadata is not None:
+            metadata_features = self.metadata_encoder(metadata)
+            fused = torch.cat([fused, metadata_features], dim=1)
+        
+        # Fusion layers
+        fused = self.fusion(fused)
+        
+        # Classification
+        logits = self.classifier(fused)
+        
+        return logits
+    
+    def predict(
+        self,
+        image: torch.Tensor,
+        metadata: Optional[torch.Tensor] = None,
+        top_k: int = 5
+    ) -> Dict:
+        """
+        Get predictions with probabilities
+        
+        Args:
+            image: [B, 3, H, W] or [3, H, W]
+            metadata: Optional metadata features
+            top_k: Number of top predictions
+            
+        Returns:
+            Dictionary with predictions and features
+        """
+        if image.dim() == 3:
+            image = image.unsqueeze(0)
+        
+        self.eval()
+        with torch.no_grad():
+            logits = self.forward(image, metadata)
+            probs = torch.softmax(logits, dim=1)
+            
+            # Top-k predictions
+            top_probs, top_indices = torch.topk(
+                probs, 
+                k=min(top_k, self.num_classes), 
+                dim=1
+            )
+            
+            # Format results
+            predictions = []
+            for i in range(top_probs.size(1)):
+                predictions.append({
+                    'class': self.CLASS_NAMES[top_indices[0, i].item()],
+                    'probability': top_probs[0, i].item(),
+                    'class_idx': top_indices[0, i].item()
+                })
+        
+        return {
+            'predictions': predictions,
+            'all_probabilities': probs[0].cpu().numpy(),
+            'logits': logits[0].cpu().numpy(),
+            'convnext_features': self.convnext_features,
+            'medsiglip_features': self.medsiglip_features
+        }
+    
+    @classmethod
+    def load_from_checkpoint(
+        cls,
+        medsiglip_path: str,
+        convnext_path: Optional[str] = None,
+        ensemble_weights: tuple = (0.6, 0.4),
+        device: str = 'cpu'
+    ):
+        """
+        Load model from your training checkpoints
+        
+        Args:
+            medsiglip_path: Path to MedSigLIP model weights
+            convnext_path: Path to ConvNeXt model weights (optional)
+            ensemble_weights: (w_medsiglip, w_convnext) 
+            device: Device to load on
+        """
+        model = cls(num_classes=11)
+        
+        # Load MedSigLIP weights
+        print(f"Loading MedSigLIP from: {medsiglip_path}")
+        medsiglip_state = torch.load(medsiglip_path, map_location=device)
+        
+        # Handle different checkpoint formats
+        if 'model_state_dict' in medsiglip_state:
+            model.load_state_dict(medsiglip_state['model_state_dict'])
+        else:
+            model.load_state_dict(medsiglip_state)
+        
+        # Store ensemble weights for prediction fusion
+        model.ensemble_weights = ensemble_weights
+        
+        model.to(device)
+        model.eval()
+        
+        return model

models/monet_concepts.py

@@ -0,0 +1,332 @@
+# models/monet_concepts.py
+
+import torch
+import numpy as np
+from typing import Dict, List
+from dataclasses import dataclass
+
+@dataclass
+class ConceptScore:
+    """Single MONET concept with score and evidence"""
+    name: str
+    score: float
+    confidence: float
+    description: str
+    clinical_relevance: str  # How this affects diagnosis
+
+class MONETConceptScorer:
+    """
+    MONET concept scoring using your trained metadata patterns
+    Integrates the boosting logic from your ensemble code
+    """
+    
+    # MONET concepts used in your training
+    CONCEPT_DEFINITIONS = {
+        'MONET_ulceration_crust': {
+            'description': 'Ulceration or crusting present',
+            'high_in': ['SCCKA', 'BCC', 'MAL_OTH'],
+            'low_in': ['NV', 'BKL'],
+            'threshold_high': 0.50
+        },
+        'MONET_erythema': {
+            'description': 'Redness or inflammation',
+            'high_in': ['INF', 'BCC', 'SCCKA'],
+            'low_in': ['MEL', 'NV'],
+            'threshold_high': 0.40
+        },
+        'MONET_pigmented': {
+            'description': 'Pigmentation present',
+            'high_in': ['MEL', 'NV', 'BKL'],
+            'low_in': ['BCC', 'SCCKA', 'INF'],
+            'threshold_high': 0.55
+        },
+        'MONET_vasculature_vessels': {
+            'description': 'Vascular structures visible',
+            'high_in': ['VASC', 'BCC'],
+            'low_in': ['MEL', 'NV'],
+            'threshold_high': 0.35
+        },
+        'MONET_hair': {
+            'description': 'Hair follicles present',
+            'high_in': ['NV', 'BKL'],
+            'low_in': ['BCC', 'MEL'],
+            'threshold_high': 0.30
+        },
+        'MONET_gel_water_drop_fluid_dermoscopy_liquid': {
+            'description': 'Gel/fluid artifacts',
+            'high_in': [],
+            'low_in': [],
+            'threshold_high': 0.40
+        },
+        'MONET_skin_markings_pen_ink_purple_pen': {
+            'description': 'Pen markings present',
+            'high_in': [],
+            'low_in': [],
+            'threshold_high': 0.40
+        }
+    }
+    
+    # Class-specific patterns from your metadata boosting
+    CLASS_PATTERNS = {
+        'MAL_OTH': {
+            'sex': 'male',  # 88.9% male
+            'site_preference': 'trunk',
+            'age_range': (60, 80),
+            'key_concepts': {'MONET_ulceration_crust': 0.35}
+        },
+        'INF': {
+            'key_concepts': {
+                'MONET_erythema': 0.42,
+                'MONET_pigmented': (None, 0.30)  # Low pigmentation
+            }
+        },
+        'BEN_OTH': {
+            'site_preference': ['head', 'neck', 'face'],  # 47.7%
+            'key_concepts': {'MONET_pigmented': (0.30, 0.50)}
+        },
+        'DF': {
+            'site_preference': ['lower', 'leg', 'ankle', 'foot'],  # 65.4%
+            'age_range': (40, 65)
+        },
+        'SCCKA': {
+            'age_range': (65, None),
+            'key_concepts': {
+                'MONET_ulceration_crust': 0.50,
+                'MONET_pigmented': (None, 0.15)
+            }
+        },
+        'MEL': {
+            'age_range': (55, None),  # 61.8 years average
+            'key_concepts': {'MONET_pigmented': 0.55}
+        },
+        'NV': {
+            'age_range': (None, 45),  # 42.0 years average
+            'key_concepts': {'MONET_pigmented': 0.55}
+        }
+    }
+    
+    def __init__(self):
+        """Initialize MONET scorer with class patterns"""
+        self.class_names = [
+            'AKIEC', 'BCC', 'BEN_OTH', 'BKL', 'DF', 
+            'INF', 'MAL_OTH', 'MEL', 'NV', 'SCCKA', 'VASC'
+        ]
+    
+    def compute_concept_scores(
+        self,
+        metadata: Dict[str, float]
+    ) -> Dict[str, ConceptScore]:
+        """
+        Compute MONET concept scores from metadata
+        
+        Args:
+            metadata: Dictionary with MONET scores, age, sex, site, etc.
+            
+        Returns:
+            Dictionary of concept scores
+        """
+        concept_scores = {}
+        
+        for concept_name, definition in self.CONCEPT_DEFINITIONS.items():
+            score = metadata.get(concept_name, 0.0)
+            
+            # Determine confidence based on how extreme the score is
+            if score > definition['threshold_high']:
+                confidence = min((score - definition['threshold_high']) / 0.2, 1.0)
+                level = "HIGH"
+            elif score < 0.2:
+                confidence = min((0.2 - score) / 0.2, 1.0)
+                level = "LOW"
+            else:
+                confidence = 0.5
+                level = "MODERATE"
+            
+            # Clinical relevance
+            if level == "HIGH":
+                relevant_classes = definition['high_in']
+                clinical_relevance = f"Supports: {', '.join(relevant_classes)}"
+            elif level == "LOW":
+                excluded_classes = definition['low_in']
+                clinical_relevance = f"Against: {', '.join(excluded_classes)}"
+            else:
+                clinical_relevance = "Non-specific"
+            
+            concept_scores[concept_name] = ConceptScore(
+                name=concept_name.replace('MONET_', '').replace('_', ' ').title(),
+                score=score,
+                confidence=confidence,
+                description=f"{definition['description']} ({level})",
+                clinical_relevance=clinical_relevance
+            )
+        
+        return concept_scores
+    
+    def apply_metadata_boosting(
+        self,
+        probs: np.ndarray,
+        metadata: Dict
+    ) -> np.ndarray:
+        """
+        Apply your metadata boosting logic
+        This is directly from your ensemble optimization code
+        
+        Args:
+            probs: [11] probability array
+            metadata: Dictionary with age, sex, site, MONET scores
+            
+        Returns:
+            boosted_probs: [11] adjusted probabilities
+        """
+        boosted_probs = probs.copy()
+        
+        # 1. MAL_OTH boosting
+        if metadata.get('sex') == 'male':
+            site = str(metadata.get('site', '')).lower()
+            if 'trunk' in site:
+                age = metadata.get('age_approx', 60)
+                ulceration = metadata.get('MONET_ulceration_crust', 0)
+                
+                score = 0
+                score += 3 if metadata.get('sex') == 'male' else 0
+                score += 2 if 'trunk' in site else 0
+                score += 1 if 60 <= age <= 80 else 0
+                score += 2 if ulceration > 0.35 else 0
+                
+                confidence = score / 8.0
+                if confidence > 0.5:
+                    boosted_probs[6] *= (1.0 + confidence)  # MAL_OTH index
+        
+        # 2. INF boosting
+        erythema = metadata.get('MONET_erythema', 0)
+        pigmentation = metadata.get('MONET_pigmented', 0)
+        
+        if erythema > 0.42 and pigmentation < 0.30:
+            confidence = min((erythema - 0.42) / 0.10 + 0.5, 1.0)
+            boosted_probs[5] *= (1.0 + confidence * 0.8)  # INF index
+        
+        # 3. BEN_OTH boosting
+        site = str(metadata.get('site', '')).lower()
+        is_head_neck = any(x in site for x in ['head', 'neck', 'face'])
+        
+        if is_head_neck and 0.30 < pigmentation < 0.50:
+            ulceration = metadata.get('MONET_ulceration_crust', 0)
+            confidence = 0.7 if ulceration < 0.30 else 0.4
+            boosted_probs[2] *= (1.0 + confidence * 0.5)  # BEN_OTH index
+        
+        # 4. DF boosting
+        is_lower_ext = any(x in site for x in ['lower', 'leg', 'ankle', 'foot'])
+        
+        if is_lower_ext:
+            age = metadata.get('age_approx', 60)
+            if 40 <= age <= 65:
+                boosted_probs[4] *= 1.8  # DF index
+            elif 30 <= age <= 75:
+                boosted_probs[4] *= 1.5
+        
+        # 5. SCCKA boosting
+        ulceration = metadata.get('MONET_ulceration_crust', 0)
+        age = metadata.get('age_approx', 60)
+        
+        if ulceration > 0.50 and age >= 65 and pigmentation < 0.15:
+            boosted_probs[9] *= 1.9  # SCCKA index
+        elif ulceration > 0.45 and age >= 60 and pigmentation < 0.20:
+            boosted_probs[9] *= 1.5
+        
+        # 6. MEL vs NV age separation
+        if pigmentation > 0.55:
+            if age >= 55:
+                age_score = min((age - 55) / 20.0, 1.0)
+                boosted_probs[7] *= (1.0 + age_score * 0.5)  # MEL
+                boosted_probs[8] *= (1.0 - age_score * 0.3)  # NV
+            elif age <= 45:
+                age_score = min((45 - age) / 30.0, 1.0)
+                boosted_probs[7] *= (1.0 - age_score * 0.3)  # MEL
+                boosted_probs[8] *= (1.0 + age_score * 0.5)  # NV
+        
+        # 7. Exclusions based on pigmentation/erythema
+        if pigmentation > 0.50:
+            boosted_probs[0] *= 0.7  # AKIEC
+            boosted_probs[1] *= 0.6  # BCC
+            boosted_probs[5] *= 0.5  # INF
+            boosted_probs[9] *= 0.3  # SCCKA
+        
+        if erythema > 0.40:
+            boosted_probs[7] *= 0.7  # MEL
+            boosted_probs[8] *= 0.7  # NV
+        
+        if pigmentation < 0.20:
+            boosted_probs[7] *= 0.5  # MEL
+            boosted_probs[8] *= 0.5  # NV
+        
+        # Renormalize
+        return boosted_probs / boosted_probs.sum()
+    
+    def explain_prediction(
+        self,
+        probs: np.ndarray,
+        concept_scores: Dict[str, ConceptScore],
+        metadata: Dict
+    ) -> str:
+        """
+        Generate natural language explanation
+        
+        Args:
+            probs: Class probabilities
+            concept_scores: MONET concept scores
+            metadata: Clinical metadata
+            
+        Returns:
+            Natural language explanation
+        """
+        predicted_idx = np.argmax(probs)
+        predicted_class = self.class_names[predicted_idx]
+        confidence = probs[predicted_idx]
+        
+        explanation = f"**Primary Diagnosis: {predicted_class}**\n"
+        explanation += f"Confidence: {confidence:.1%}\n\n"
+        
+        # Key MONET features
+        explanation += "**Key Dermoscopic Features:**\n"
+        
+        sorted_concepts = sorted(
+            concept_scores.values(),
+            key=lambda x: x.score * x.confidence,
+            reverse=True
+        )
+        
+        for i, concept in enumerate(sorted_concepts[:5], 1):
+            if concept.score > 0.3 or concept.score < 0.2:
+                explanation += f"{i}. {concept.name}: {concept.score:.2f} - {concept.description}\n"
+                if concept.clinical_relevance != "Non-specific":
+                    explanation += f"   → {concept.clinical_relevance}\n"
+        
+        # Clinical context
+        explanation += "\n**Clinical Context:**\n"
+        if 'age_approx' in metadata:
+            explanation += f"• Age: {metadata['age_approx']} years\n"
+        if 'sex' in metadata:
+            explanation += f"• Sex: {metadata['sex']}\n"
+        if 'site' in metadata:
+            explanation += f"• Location: {metadata['site']}\n"
+        
+        return explanation
+    
+    def get_top_concepts(
+        self,
+        concept_scores: Dict[str, ConceptScore],
+        top_k: int = 5,
+        min_score: float = 0.3
+    ) -> List[ConceptScore]:
+        """Get top-k most important concepts"""
+        filtered = [
+            cs for cs in concept_scores.values() 
+            if cs.score >= min_score or cs.score < 0.2  # High or low
+        ]
+        
+        sorted_concepts = sorted(
+            filtered,
+            key=lambda x: x.score * x.confidence,
+            reverse=True
+        )
+        
+        return sorted_concepts[:top_k]

models/monet_tool.py

@@ -0,0 +1,354 @@
+"""
+MONET Tool - Skin lesion feature extraction using MONET model
+Correct implementation based on MONET tutorial: automatic_concept_annotation.ipynb
+"""
+
+import torch
+import torch.nn.functional as F
+import numpy as np
+import scipy.special
+from PIL import Image
+from typing import Optional, Dict, List
+import torchvision.transforms as T
+
+
+# The 7 MONET feature columns expected by ConvNeXt
+MONET_FEATURES = [
+    "MONET_ulceration_crust",
+    "MONET_hair",
+    "MONET_vasculature_vessels",
+    "MONET_erythema",
+    "MONET_pigmented",
+    "MONET_gel_water_drop_fluid_dermoscopy_liquid",
+    "MONET_skin_markings_pen_ink_purple_pen",
+]
+
+# Concept terms for each MONET feature (multiple synonyms improve detection)
+MONET_CONCEPT_TERMS = {
+    "MONET_ulceration_crust": ["ulceration", "crust", "crusting", "ulcer"],
+    "MONET_hair": ["hair", "hairy"],
+    "MONET_vasculature_vessels": ["blood vessels", "vasculature", "vessels", "telangiectasia"],
+    "MONET_erythema": ["erythema", "redness", "red"],
+    "MONET_pigmented": ["pigmented", "pigmentation", "melanin", "brown"],
+    "MONET_gel_water_drop_fluid_dermoscopy_liquid": ["dermoscopy gel", "fluid", "water drop", "immersion fluid"],
+    "MONET_skin_markings_pen_ink_purple_pen": ["pen marking", "ink", "surgical marking", "purple pen"],
+}
+
+# Prompt templates (from MONET paper)
+PROMPT_TEMPLATES = [
+    "This is skin image of {}",
+    "This is dermatology image of {}",
+    "This is image of {}",
+]
+
+# Reference prompts (baseline for contrastive scoring)
+PROMPT_REFS = [
+    ["This is skin image"],
+    ["This is dermatology image"],
+    ["This is image"],
+]
+
+
+def get_transform(n_px=224):
+    """Get MONET preprocessing transform"""
+    def convert_image_to_rgb(image):
+        return image.convert("RGB")
+
+    return T.Compose([
+        T.Resize(n_px, interpolation=T.InterpolationMode.BICUBIC),
+        T.CenterCrop(n_px),
+        convert_image_to_rgb,
+        T.ToTensor(),
+        T.Normalize((0.485, 0.456, 0.406), (0.229, 0.224, 0.225)),
+    ])
+
+
+class MonetTool:
+    """
+    MONET tool for extracting concept presence scores from skin lesion images.
+    Uses the proper contrastive scoring method from the MONET paper.
+    """
+
+    def __init__(self, device: Optional[str] = None, use_hf: bool = True):
+        """
+        Args:
+            device: Device to run on (cuda, mps, cpu)
+            use_hf: Use HuggingFace implementation (True) or original CLIP (False)
+        """
+        self.model = None
+        self.processor = None
+        self.device = device
+        self.use_hf = use_hf
+        self.loaded = False
+        self.transform = get_transform(224)
+
+        # Cache for concept embeddings
+        self._concept_embeddings = {}
+
+    def load(self):
+        """Load MONET model"""
+        if self.loaded:
+            return
+
+        # Determine device
+        if self.device is None:
+            if torch.cuda.is_available():
+                self.device = "cuda:0"
+            elif torch.backends.mps.is_available():
+                self.device = "mps"
+            else:
+                self.device = "cpu"
+
+        if self.use_hf:
+            # HuggingFace implementation
+            from transformers import AutoProcessor, AutoModelForZeroShotImageClassification
+
+            self.processor = AutoProcessor.from_pretrained("chanwkim/monet")
+            self.model = AutoModelForZeroShotImageClassification.from_pretrained("chanwkim/monet")
+            self.model.to(self.device)
+            self.model.eval()
+        else:
+            # Original CLIP implementation
+            import clip
+
+            self.model, _ = clip.load("ViT-L/14", device=self.device, jit=False)
+            self.model.load_state_dict(
+                torch.hub.load_state_dict_from_url(
+                    "https://aimslab.cs.washington.edu/MONET/weight_clip.pt"
+                )
+            )
+            self.model.eval()
+
+        self.loaded = True
+
+        # Pre-compute concept embeddings for all MONET features
+        self._precompute_concept_embeddings()
+
+    def _encode_text(self, text_list: List[str]) -> torch.Tensor:
+        """Encode text to embeddings"""
+        if self.use_hf:
+            inputs = self.processor(text=text_list, return_tensors="pt", padding=True)
+            inputs = {k: v.to(self.device) for k, v in inputs.items()}
+            with torch.no_grad():
+                embeddings = self.model.get_text_features(**inputs)
+        else:
+            import clip
+            tokens = clip.tokenize(text_list, truncate=True).to(self.device)
+            with torch.no_grad():
+                embeddings = self.model.encode_text(tokens)
+
+        return embeddings.cpu()
+
+    def _encode_image(self, image: Image.Image) -> torch.Tensor:
+        """Encode image to embedding"""
+        image_tensor = self.transform(image).unsqueeze(0).to(self.device)
+
+        if self.use_hf:
+            with torch.no_grad():
+                embedding = self.model.get_image_features(image_tensor)
+        else:
+            with torch.no_grad():
+                embedding = self.model.encode_image(image_tensor)
+
+        return embedding.cpu()
+
+    def _precompute_concept_embeddings(self):
+        """Pre-compute embeddings for all MONET concepts"""
+        for feature_name, concept_terms in MONET_CONCEPT_TERMS.items():
+            self._concept_embeddings[feature_name] = self._get_concept_embedding(concept_terms)
+
+    def _get_concept_embedding(self, concept_terms: List[str]) -> Dict:
+        """
+        Generate prompt embeddings for a concept using multiple templates.
+
+        Args:
+            concept_terms: List of synonymous terms for the concept
+
+        Returns:
+            dict with target and reference embeddings
+        """
+        # Target prompts: "This is skin image of {term}"
+        prompt_target = [
+            [template.format(term) for term in concept_terms]
+            for template in PROMPT_TEMPLATES
+        ]
+
+        # Flatten and encode
+        prompt_target_flat = [p for template_prompts in prompt_target for p in template_prompts]
+        target_embeddings = self._encode_text(prompt_target_flat)
+
+        # Reshape to [num_templates, num_terms, embed_dim]
+        num_templates = len(PROMPT_TEMPLATES)
+        num_terms = len(concept_terms)
+        embed_dim = target_embeddings.shape[-1]
+        target_embeddings = target_embeddings.view(num_templates, num_terms, embed_dim)
+
+        # Normalize
+        target_embeddings_norm = F.normalize(target_embeddings, dim=2)
+
+        # Reference prompts: "This is skin image"
+        prompt_ref_flat = [p for ref_list in PROMPT_REFS for p in ref_list]
+        ref_embeddings = self._encode_text(prompt_ref_flat)
+        ref_embeddings = ref_embeddings.view(num_templates, -1, embed_dim)
+        ref_embeddings_norm = F.normalize(ref_embeddings, dim=2)
+
+        return {
+            "target_embedding_norm": target_embeddings_norm,
+            "ref_embedding_norm": ref_embeddings_norm,
+        }
+
+    def _calculate_concept_score(
+        self,
+        image_features_norm: torch.Tensor,
+        concept_embedding: Dict,
+        temp: float = 1 / np.exp(4.5944)
+    ) -> float:
+        """
+        Calculate concept presence score using contrastive comparison.
+
+        Args:
+            image_features_norm: Normalized image embedding [1, embed_dim]
+            concept_embedding: Dict with target and reference embeddings
+            temp: Temperature for softmax
+
+        Returns:
+            Concept presence score (0-1)
+        """
+        target_emb = concept_embedding["target_embedding_norm"].float()
+        ref_emb = concept_embedding["ref_embedding_norm"].float()
+
+        # Similarity: [num_templates, num_terms] @ [embed_dim, 1] -> [num_templates, num_terms, 1]
+        target_similarity = target_emb @ image_features_norm.T.float()
+        ref_similarity = ref_emb @ image_features_norm.T.float()
+
+        # Mean over terms for each template
+        target_mean = target_similarity.mean(dim=1).squeeze()  # [num_templates]
+        ref_mean = ref_similarity.mean(dim=1).squeeze()  # [num_templates]
+
+        # Softmax between target and reference (contrastive scoring)
+        scores = scipy.special.softmax(
+            np.array([target_mean.numpy() / temp, ref_mean.numpy() / temp]),
+            axis=0
+        )
+
+        # Return mean of target scores across templates
+        return float(scores[0].mean())
+
+    def extract_features(self, image: Image.Image) -> Dict[str, float]:
+        """
+        Extract MONET feature scores from a skin lesion image.
+
+        Args:
+            image: PIL Image to analyze
+
+        Returns:
+            dict with 7 MONET feature scores (0-1 range)
+        """
+        if not self.loaded:
+            self.load()
+
+        # Ensure RGB
+        if image.mode != "RGB":
+            image = image.convert("RGB")
+
+        # Get image embedding
+        image_features = self._encode_image(image)
+        image_features_norm = F.normalize(image_features, dim=1)
+
+        # Calculate score for each MONET feature
+        features = {}
+        for feature_name in MONET_FEATURES:
+            concept_emb = self._concept_embeddings[feature_name]
+            score = self._calculate_concept_score(image_features_norm, concept_emb)
+            features[feature_name] = score
+
+        return features
+
+    def get_feature_vector(self, image: Image.Image) -> List[float]:
+        """Get MONET features as a list in the expected order."""
+        features = self.extract_features(image)
+        return [features[f] for f in MONET_FEATURES]
+
+    def get_feature_tensor(self, image: Image.Image) -> torch.Tensor:
+        """Get MONET features as a PyTorch tensor."""
+        return torch.tensor(self.get_feature_vector(image), dtype=torch.float32)
+
+    def describe_features(self, features: Dict[str, float], threshold: float = 0.6) -> str:
+        """Generate a natural language description of the MONET features."""
+        descriptions = {
+            "MONET_ulceration_crust": "ulceration or crusting",
+            "MONET_hair": "visible hair",
+            "MONET_vasculature_vessels": "visible blood vessels",
+            "MONET_erythema": "erythema (redness)",
+            "MONET_pigmented": "pigmentation",
+            "MONET_gel_water_drop_fluid_dermoscopy_liquid": "dermoscopy gel/fluid",
+            "MONET_skin_markings_pen_ink_purple_pen": "pen markings",
+        }
+
+        present = []
+        for feature, score in features.items():
+            if score >= threshold:
+                desc = descriptions.get(feature, feature)
+                present.append(f"{desc} ({score:.0%})")
+
+        if not present:
+            # Show top features even if below threshold
+            sorted_features = sorted(features.items(), key=lambda x: x[1], reverse=True)[:3]
+            present = [f"{descriptions.get(f, f)} ({s:.0%})" for f, s in sorted_features]
+
+        return "Detected features: " + ", ".join(present)
+
+    def analyze(self, image: Image.Image) -> Dict:
+        """Full analysis returning features, vector, and description."""
+        features = self.extract_features(image)
+        vector = [features[f] for f in MONET_FEATURES]
+        description = self.describe_features(features)
+
+        return {
+            "features": features,
+            "vector": vector,
+            "description": description,
+            "feature_names": MONET_FEATURES,
+        }
+
+    def __call__(self, image: Image.Image) -> Dict:
+        """Shorthand for analyze()"""
+        return self.analyze(image)
+
+
+# Singleton instance
+_monet_instance = None
+
+
+def get_monet_tool() -> MonetTool:
+    """Get or create MONET tool instance"""
+    global _monet_instance
+    if _monet_instance is None:
+        _monet_instance = MonetTool()
+    return _monet_instance
+
+
+if __name__ == "__main__":
+    import sys
+
+    print("MONET Tool Test (Correct Implementation)")
+    print("=" * 50)
+
+    tool = MonetTool(use_hf=True)
+    print("Loading model...")
+    tool.load()
+    print("Model loaded!")
+
+    if len(sys.argv) > 1:
+        image_path = sys.argv[1]
+        print(f"\nAnalyzing: {image_path}")
+        image = Image.open(image_path).convert("RGB")
+        result = tool.analyze(image)
+
+        print("\nMONET Features (Contrastive Scores):")
+        for name, score in result["features"].items():
+            bar = "█" * int(score * 20)
+            print(f"  {name}: {score:.3f} {bar}")
+
+        print(f"\nDescription: {result['description']}")
+        print(f"\nVector: {[f'{v:.3f}' for v in result['vector']]}")

models/overlay_tool.py

@@ -0,0 +1,335 @@
+"""
+Overlay Tool - Generates visual markers for biopsy sites and excision margins
+"""
+
+import io
+import tempfile
+from typing import Tuple, Optional, Dict, Any
+from PIL import Image, ImageDraw, ImageFont
+
+
+class OverlayTool:
+    """
+    Generates image overlays for clinical decision visualization:
+    - Biopsy site markers (circles)
+    - Excision margins (dashed outlines with margin indicators)
+    """
+
+    # Colors for different marker types
+    COLORS = {
+        'biopsy': (255, 69, 0, 200),      # Orange-red with alpha
+        'excision': (220, 20, 60, 200),   # Crimson with alpha
+        'margin': (255, 215, 0, 180),     # Gold for margin line
+        'text': (255, 255, 255, 255),     # White text
+        'text_bg': (0, 0, 0, 180),        # Semi-transparent black bg
+    }
+
+    def __init__(self):
+        self.loaded = True
+
+    def generate_biopsy_overlay(
+        self,
+        image: Image.Image,
+        center_x: float,
+        center_y: float,
+        radius: float = 0.05,
+        label: str = "Biopsy Site"
+    ) -> Dict[str, Any]:
+        """
+        Generate biopsy site overlay with circle marker.
+
+        Args:
+            image: PIL Image
+            center_x: X coordinate as fraction (0-1) of image width
+            center_y: Y coordinate as fraction (0-1) of image height
+            radius: Radius as fraction of image width
+            label: Text label for the marker
+
+        Returns:
+            Dict with overlay image and metadata
+        """
+        # Convert to RGBA for transparency
+        img = image.convert("RGBA")
+        width, height = img.size
+
+        # Create overlay layer
+        overlay = Image.new("RGBA", img.size, (0, 0, 0, 0))
+        draw = ImageDraw.Draw(overlay)
+
+        # Calculate pixel coordinates
+        cx = int(center_x * width)
+        cy = int(center_y * height)
+        r = int(radius * width)
+
+        # Draw outer circle (thicker)
+        for offset in range(3):
+            draw.ellipse(
+                [cx - r - offset, cy - r - offset, cx + r + offset, cy + r + offset],
+                outline=self.COLORS['biopsy'],
+                width=2
+            )
+
+        # Draw crosshairs
+        line_len = r // 2
+        draw.line([(cx - line_len, cy), (cx + line_len, cy)],
+                  fill=self.COLORS['biopsy'], width=2)
+        draw.line([(cx, cy - line_len), (cx, cy + line_len)],
+                  fill=self.COLORS['biopsy'], width=2)
+
+        # Draw label with background
+        try:
+            font = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 14)
+        except:
+            font = ImageFont.load_default()
+
+        text_bbox = draw.textbbox((0, 0), label, font=font)
+        text_width = text_bbox[2] - text_bbox[0]
+        text_height = text_bbox[3] - text_bbox[1]
+
+        text_x = cx - text_width // 2
+        text_y = cy + r + 10
+
+        # Background rectangle for text
+        padding = 4
+        draw.rectangle(
+            [text_x - padding, text_y - padding,
+             text_x + text_width + padding, text_y + text_height + padding],
+            fill=self.COLORS['text_bg']
+        )
+        draw.text((text_x, text_y), label, fill=self.COLORS['text'], font=font)
+
+        # Composite
+        result = Image.alpha_composite(img, overlay)
+
+        # Save to temp file
+        temp_file = tempfile.NamedTemporaryFile(suffix="_biopsy_overlay.png", delete=False)
+        result.save(temp_file.name, "PNG")
+        temp_file.close()
+
+        return {
+            "overlay": result,
+            "path": temp_file.name,
+            "type": "biopsy",
+            "coordinates": {
+                "center_x": center_x,
+                "center_y": center_y,
+                "radius": radius
+            },
+            "label": label
+        }
+
+    def generate_excision_overlay(
+        self,
+        image: Image.Image,
+        center_x: float,
+        center_y: float,
+        lesion_radius: float,
+        margin_mm: int = 5,
+        pixels_per_mm: float = 10.0,
+        label: str = "Excision Margin"
+    ) -> Dict[str, Any]:
+        """
+        Generate excision margin overlay with inner (lesion) and outer (margin) boundaries.
+
+        Args:
+            image: PIL Image
+            center_x: X coordinate as fraction (0-1)
+            center_y: Y coordinate as fraction (0-1)
+            lesion_radius: Lesion radius as fraction of image width
+            margin_mm: Excision margin in millimeters
+            pixels_per_mm: Estimated pixels per mm (for margin calculation)
+            label: Text label
+
+        Returns:
+            Dict with overlay image and metadata
+        """
+        img = image.convert("RGBA")
+        width, height = img.size
+
+        overlay = Image.new("RGBA", img.size, (0, 0, 0, 0))
+        draw = ImageDraw.Draw(overlay)
+
+        # Calculate coordinates
+        cx = int(center_x * width)
+        cy = int(center_y * height)
+        inner_r = int(lesion_radius * width)
+
+        # Calculate margin in pixels
+        margin_px = int(margin_mm * pixels_per_mm)
+        outer_r = inner_r + margin_px
+
+        # Draw outer margin (dashed effect using multiple arcs)
+        dash_length = 10
+        for angle in range(0, 360, dash_length * 2):
+            draw.arc(
+                [cx - outer_r, cy - outer_r, cx + outer_r, cy + outer_r],
+                start=angle,
+                end=angle + dash_length,
+                fill=self.COLORS['margin'],
+                width=3
+            )
+
+        # Draw inner lesion boundary (solid)
+        draw.ellipse(
+            [cx - inner_r, cy - inner_r, cx + inner_r, cy + inner_r],
+            outline=self.COLORS['excision'],
+            width=2
+        )
+
+        # Draw margin indicator lines (radial)
+        for angle in [0, 90, 180, 270]:
+            import math
+            rad = math.radians(angle)
+            inner_x = cx + int(inner_r * math.cos(rad))
+            inner_y = cy + int(inner_r * math.sin(rad))
+            outer_x = cx + int(outer_r * math.cos(rad))
+            outer_y = cy + int(outer_r * math.sin(rad))
+            draw.line([(inner_x, inner_y), (outer_x, outer_y)],
+                      fill=self.COLORS['margin'], width=2)
+
+        # Draw labels
+        try:
+            font = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 12)
+            font_small = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 10)
+        except:
+            font = ImageFont.load_default()
+            font_small = font
+
+        # Main label
+        text_bbox = draw.textbbox((0, 0), label, font=font)
+        text_width = text_bbox[2] - text_bbox[0]
+        text_height = text_bbox[3] - text_bbox[1]
+
+        text_x = cx - text_width // 2
+        text_y = cy + outer_r + 15
+
+        padding = 4
+        draw.rectangle(
+            [text_x - padding, text_y - padding,
+             text_x + text_width + padding, text_y + text_height + padding],
+            fill=self.COLORS['text_bg']
+        )
+        draw.text((text_x, text_y), label, fill=self.COLORS['text'], font=font)
+
+        # Margin measurement label
+        margin_label = f"{margin_mm}mm margin"
+        margin_bbox = draw.textbbox((0, 0), margin_label, font=font_small)
+        margin_width = margin_bbox[2] - margin_bbox[0]
+
+        margin_text_x = cx + outer_r + 5
+        margin_text_y = cy - 6
+
+        draw.rectangle(
+            [margin_text_x - 2, margin_text_y - 2,
+             margin_text_x + margin_width + 2, margin_text_y + 12],
+            fill=self.COLORS['text_bg']
+        )
+        draw.text((margin_text_x, margin_text_y), margin_label,
+                  fill=self.COLORS['margin'], font=font_small)
+
+        # Composite
+        result = Image.alpha_composite(img, overlay)
+
+        temp_file = tempfile.NamedTemporaryFile(suffix="_excision_overlay.png", delete=False)
+        result.save(temp_file.name, "PNG")
+        temp_file.close()
+
+        return {
+            "overlay": result,
+            "path": temp_file.name,
+            "type": "excision",
+            "coordinates": {
+                "center_x": center_x,
+                "center_y": center_y,
+                "lesion_radius": lesion_radius,
+                "margin_mm": margin_mm,
+                "total_radius": outer_r / width
+            },
+            "label": label
+        }
+
+    def generate_comparison_overlay(
+        self,
+        image1: Image.Image,
+        image2: Image.Image,
+        label1: str = "Previous",
+        label2: str = "Current"
+    ) -> Dict[str, Any]:
+        """
+        Generate side-by-side comparison of two images for follow-up.
+
+        Args:
+            image1: First (previous) image
+            image2: Second (current) image
+            label1: Label for first image
+            label2: Label for second image
+
+        Returns:
+            Dict with comparison image and metadata
+        """
+        # Resize to same height
+        max_height = 400
+
+        # Calculate sizes maintaining aspect ratio
+        w1, h1 = image1.size
+        w2, h2 = image2.size
+
+        ratio1 = max_height / h1
+        ratio2 = max_height / h2
+
+        new_w1 = int(w1 * ratio1)
+        new_w2 = int(w2 * ratio2)
+
+        img1 = image1.resize((new_w1, max_height), Image.Resampling.LANCZOS)
+        img2 = image2.resize((new_w2, max_height), Image.Resampling.LANCZOS)
+
+        # Create comparison canvas
+        gap = 20
+        total_width = new_w1 + gap + new_w2
+        header_height = 30
+        total_height = max_height + header_height
+
+        canvas = Image.new("RGB", (total_width, total_height), (255, 255, 255))
+        draw = ImageDraw.Draw(canvas)
+
+        # Draw labels
+        try:
+            font = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 14)
+        except:
+            font = ImageFont.load_default()
+
+        # Previous label
+        draw.rectangle([0, 0, new_w1, header_height], fill=(70, 130, 180))
+        bbox1 = draw.textbbox((0, 0), label1, font=font)
+        text_w1 = bbox1[2] - bbox1[0]
+        draw.text(((new_w1 - text_w1) // 2, 8), label1, fill=(255, 255, 255), font=font)
+
+        # Current label
+        draw.rectangle([new_w1 + gap, 0, total_width, header_height], fill=(60, 179, 113))
+        bbox2 = draw.textbbox((0, 0), label2, font=font)
+        text_w2 = bbox2[2] - bbox2[0]
+        draw.text((new_w1 + gap + (new_w2 - text_w2) // 2, 8), label2,
+                  fill=(255, 255, 255), font=font)
+
+        # Paste images
+        canvas.paste(img1, (0, header_height))
+        canvas.paste(img2, (new_w1 + gap, header_height))
+
+        # Draw divider
+        draw.line([(new_w1 + gap // 2, header_height), (new_w1 + gap // 2, total_height)],
+                  fill=(200, 200, 200), width=2)
+
+        temp_file = tempfile.NamedTemporaryFile(suffix="_comparison.png", delete=False)
+        canvas.save(temp_file.name, "PNG")
+        temp_file.close()
+
+        return {
+            "comparison": canvas,
+            "path": temp_file.name,
+            "type": "comparison"
+        }
+
+
+def get_overlay_tool() -> OverlayTool:
+    """Get overlay tool instance"""
+    return OverlayTool()

requirements.txt

@@ -0,0 +1,15 @@
+# requirements.txt
+
+torch>=2.0.0
+torchvision>=0.15.0
+transformers>=4.40.0
+timm>=0.9.0
+gradio==4.44.0
+gradio-client==1.3.0
+opencv-python>=4.8.0
+numpy>=1.24.0
+Pillow>=10.0.0
+sentencepiece>=0.1.99
+accelerate>=0.25.0
+protobuf>=4.0.0
+mcp>=1.0.0  # installed via python3.11 (requires Python >=3.10)

test_models.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Test script to verify model loading"""
+
+import torch
+import torch.nn as nn
+import timm
+from transformers import AutoModel, AutoProcessor
+import numpy as np
+
+DEVICE = "cpu"
+print(f"Device: {DEVICE}")
+
+# ConvNeXt model definition (matching checkpoint)
+class ConvNeXtDualEncoder(nn.Module):
+    def __init__(self, model_name="convnext_base.fb_in22k_ft_in1k",
+                 metadata_dim=19, num_classes=11, dropout=0.3):
+        super().__init__()
+        self.backbone = timm.create_model(model_name, pretrained=False, num_classes=0)
+        backbone_dim = self.backbone.num_features
+        self.meta_mlp = nn.Sequential(
+            nn.Linear(metadata_dim, 64), nn.LayerNorm(64), nn.GELU(), nn.Dropout(dropout)
+        )
+        fusion_dim = backbone_dim * 2 + 64
+        self.classifier = nn.Sequential(
+            nn.Linear(fusion_dim, 512), nn.LayerNorm(512), nn.GELU(), nn.Dropout(dropout),
+            nn.Linear(512, 256), nn.LayerNorm(256), nn.GELU(), nn.Dropout(dropout),
+            nn.Linear(256, num_classes)
+        )
+
+    def forward(self, clinical_img, derm_img=None, metadata=None):
+        clinical_features = self.backbone(clinical_img)
+        derm_features = self.backbone(derm_img) if derm_img is not None else clinical_features
+        if metadata is not None:
+            meta_features = self.meta_mlp(metadata)
+        else:
+            meta_features = torch.zeros(clinical_features.size(0), 64, device=clinical_features.device)
+        fused = torch.cat([clinical_features, derm_features, meta_features], dim=1)
+        return self.classifier(fused)
+
+
+# MedSigLIP model definition
+class MedSigLIPClassifier(nn.Module):
+    def __init__(self, num_classes=11, model_name="google/siglip-base-patch16-384"):
+        super().__init__()
+        self.siglip = AutoModel.from_pretrained(model_name)
+        self.processor = AutoProcessor.from_pretrained(model_name)
+        hidden_dim = self.siglip.config.vision_config.hidden_size
+        self.classifier = nn.Sequential(
+            nn.Linear(hidden_dim, 512), nn.LayerNorm(512), nn.GELU(), nn.Dropout(0.3),
+            nn.Linear(512, num_classes)
+        )
+        for param in self.siglip.parameters():
+            param.requires_grad = False
+
+    def forward(self, pixel_values):
+        vision_outputs = self.siglip.vision_model(pixel_values=pixel_values)
+        pooled_features = vision_outputs.pooler_output
+        return self.classifier(pooled_features)
+
+
+if __name__ == "__main__":
+    print("\n[1/2] Loading ConvNeXt...")
+    convnext_model = ConvNeXtDualEncoder()
+    ckpt = torch.load("models/seed42_fold0.pt", map_location=DEVICE, weights_only=False)
+    convnext_model.load_state_dict(ckpt)
+    convnext_model.eval()
+    print("   ConvNeXt loaded!")
+
+    print("\n[2/2] Loading MedSigLIP...")
+    medsiglip_model = MedSigLIPClassifier()
+    medsiglip_model.eval()
+    print("   MedSigLIP loaded!")
+
+    # Quick inference test
+    print("\nTesting inference...")
+    dummy_img = torch.randn(1, 3, 384, 384)
+    with torch.no_grad():
+        convnext_out = convnext_model(dummy_img)
+        print(f"   ConvNeXt output: {convnext_out.shape}")
+
+        dummy_pil = np.random.randint(0, 255, (384, 384, 3), dtype=np.uint8)
+        siglip_input = medsiglip_model.processor(images=[dummy_pil], return_tensors="pt")
+        siglip_out = medsiglip_model(siglip_input["pixel_values"])
+        print(f"   MedSigLIP output: {siglip_out.shape}")
+
+    print("\nAll tests passed!")

web/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SkinProAI</title>
+    <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=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

web/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "skinproai-web",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-markdown": "^10.1.0",
+    "react-router-dom": "^6.20.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0"
+  }
+}

web/src/App.tsx

@@ -0,0 +1,14 @@
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { PatientsPage } from './pages/PatientsPage';
+import { ChatPage } from './pages/ChatPage';
+
+export function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<PatientsPage />} />
+        <Route path="/chat/:patientId" element={<ChatPage />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}

web/src/components/MessageContent.css

@@ -0,0 +1,250 @@
+/* ─── Root ───────────────────────────────────────────────────────────────── */
+.mc-root {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  font-size: 0.9375rem;
+  line-height: 1.6;
+  color: var(--gray-800);
+  width: 100%;
+}
+
+/* ─── Stage header ───────────────────────────────────────────────────────── */
+.mc-stage {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--primary);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  padding: 8px 0 2px;
+  border-top: 1px solid var(--gray-100);
+  margin-top: 4px;
+}
+
+.mc-stage:first-child {
+  border-top: none;
+  margin-top: 0;
+  padding-top: 0;
+}
+
+/* ─── Thinking text ──────────────────────────────────────────────────────── */
+.mc-thinking {
+  font-size: 0.8125rem;
+  color: var(--gray-500);
+  font-style: italic;
+}
+
+/* ─── Response block (markdown) ──────────────────────────────────────────── */
+.mc-response {
+  color: var(--gray-800);
+}
+
+.mc-response p {
+  margin: 0 0 8px;
+}
+
+.mc-response p:last-child {
+  margin-bottom: 0;
+}
+
+.mc-response strong {
+  font-weight: 600;
+  color: var(--gray-900);
+}
+
+.mc-response em {
+  font-style: italic;
+}
+
+.mc-response ul,
+.mc-response ol {
+  margin: 4px 0 8px 20px;
+  padding: 0;
+}
+
+.mc-response li {
+  margin-bottom: 2px;
+}
+
+.mc-response h1,
+.mc-response h2,
+.mc-response h3,
+.mc-response h4 {
+  font-size: 0.9375rem;
+  font-weight: 600;
+  color: var(--gray-900);
+  margin: 10px 0 4px;
+}
+
+.mc-response code {
+  font-family: monospace;
+  font-size: 0.875em;
+  background: var(--gray-100);
+  padding: 1px 5px;
+  border-radius: 4px;
+}
+
+/* ─── Tool output (monospace block) ─────────────────────────────────────── */
+.mc-tool-output {
+  background: var(--gray-900);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.mc-tool-output-label {
+  font-size: 0.6875rem;
+  font-weight: 600;
+  color: var(--gray-400);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  padding: 6px 12px 4px;
+  background: rgba(255, 255, 255, 0.05);
+  border-bottom: 1px solid rgba(255, 255, 255, 0.08);
+}
+
+.mc-tool-output pre {
+  margin: 0;
+  padding: 10px 12px;
+  font-family: 'SF Mono', 'Fira Code', monospace;
+  font-size: 0.8rem;
+  line-height: 1.5;
+  color: #e2e8f0;
+  white-space: pre;
+  overflow-x: auto;
+}
+
+/* ─── Image blocks (GradCAM, comparison) ────────────────────────────────── */
+.mc-image-block {
+  margin-top: 4px;
+}
+
+.mc-image-label {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--gray-500);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-bottom: 6px;
+}
+
+.mc-gradcam-img {
+  width: 100%;
+  max-width: 380px;
+  border-radius: 10px;
+  border: 1px solid var(--gray-200);
+  display: block;
+}
+
+.mc-comparison-img {
+  width: 100%;
+  max-width: 560px;
+  border-radius: 10px;
+  border: 1px solid var(--gray-200);
+  display: block;
+}
+
+/* ─── GradCAM side-by-side comparison ───────────────────────────────────── */
+.mc-gradcam-compare {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 10px;
+  max-width: 560px;
+}
+
+.mc-gradcam-compare-item {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.mc-gradcam-compare-title {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--gray-600);
+  text-align: center;
+}
+
+.mc-gradcam-compare-img {
+  width: 100%;
+  border-radius: 8px;
+  border: 1px solid var(--gray-200);
+  display: block;
+}
+
+/* ─── Result / error / complete / observation ───────────────────────────── */
+.mc-result {
+  background: linear-gradient(135deg, #f0fdf4, #dcfce7);
+  border: 1px solid #86efac;
+  border-radius: 8px;
+  padding: 8px 12px;
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: #15803d;
+}
+
+.mc-error {
+  background: #fef2f2;
+  border: 1px solid #fca5a5;
+  border-radius: 8px;
+  padding: 8px 12px;
+  font-size: 0.875rem;
+  color: #dc2626;
+}
+
+.mc-complete {
+  font-size: 0.8rem;
+  color: var(--gray-400);
+  text-align: right;
+}
+
+.mc-observation {
+  font-size: 0.875rem;
+  color: var(--gray-600);
+  font-style: italic;
+}
+
+/* ─── Plain streaming text ───────────────────────────────────────────────── */
+.mc-text {
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: var(--gray-700);
+  font-size: 0.875rem;
+}
+
+/* ─── References ─────────────────────────────────────────────────────────── */
+.mc-references {
+  border-top: 1px solid var(--gray-100);
+  padding-top: 8px;
+  margin-top: 4px;
+}
+
+.mc-references-title {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--gray-500);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-bottom: 4px;
+}
+
+.mc-ref-item {
+  font-size: 0.8125rem;
+  color: var(--gray-600);
+  line-height: 1.5;
+}
+
+.mc-ref-sup {
+  font-size: 0.6875rem;
+  vertical-align: super;
+  margin-right: 4px;
+  color: var(--primary);
+  font-weight: 600;
+}
+
+.mc-ref-source {
+  font-style: italic;
+}
+
+.mc-ref-page {
+  color: var(--gray-400);
+}

web/src/components/MessageContent.tsx

@@ -0,0 +1,254 @@
+import ReactMarkdown from 'react-markdown';
+import './MessageContent.css';
+
+// Serve any temp visualization image (GradCAM, comparison) through the API
+const TEMP_IMG_URL = (path: string) =>
+  `/api/patients/gradcam?path=${encodeURIComponent(path)}`;
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+type Segment =
+  | { type: 'stage'; label: string }
+  | { type: 'thinking'; content: string }
+  | { type: 'response'; content: string }
+  | { type: 'tool_output'; label: string; content: string }
+  | { type: 'gradcam'; path: string }
+  | { type: 'comparison'; path: string }
+  | { type: 'gradcam_compare'; path1: string; path2: string }
+  | { type: 'result'; content: string }
+  | { type: 'error'; content: string }
+  | { type: 'complete'; content: string }
+  | { type: 'references'; content: string }
+  | { type: 'observation'; content: string }
+  | { type: 'text'; content: string };
+
+// ─── Parser ────────────────────────────────────────────────────────────────
+
+// Splits raw text by all known complete tag patterns (capturing group preserves them)
+const TAG_SPLIT_RE = new RegExp(
+  '(' +
+    [
+      '\\[STAGE:[^\\]]*\\][\\s\\S]*?\\[\\/STAGE\\]',
+      '\\[THINKING\\][\\s\\S]*?\\[\\/THINKING\\]',
+      '\\[RESPONSE\\][\\s\\S]*?\\[\\/RESPONSE\\]',
+      '\\[TOOL_OUTPUT:[^\\]]*\\][\\s\\S]*?\\[\\/TOOL_OUTPUT\\]',
+      '\\[GRADCAM_IMAGE:[^\\]]+\\]',
+      '\\[COMPARISON_IMAGE:[^\\]]+\\]',
+      '\\[GRADCAM_COMPARE:[^:\\]]+:[^\\]]+\\]',
+      '\\[RESULT\\][\\s\\S]*?\\[\\/RESULT\\]',
+      '\\[ERROR\\][\\s\\S]*?\\[\\/ERROR\\]',
+      '\\[COMPLETE\\][\\s\\S]*?\\[\\/COMPLETE\\]',
+      '\\[REFERENCES\\][\\s\\S]*?\\[\\/REFERENCES\\]',
+      '\\[OBSERVATION\\][\\s\\S]*?\\[\\/OBSERVATION\\]',
+      '\\[CONFIRM:[^\\]]*\\][\\s\\S]*?\\[\\/CONFIRM\\]',
+    ].join('|') +
+    ')',
+  'g',
+);
+
+// Strips known opening tags that haven't yet been closed (mid-stream partial content)
+function cleanStreamingText(text: string): string {
+  return text.replace(
+    /\[(STAGE:[^\]]*|THINKING|RESPONSE|TOOL_OUTPUT:[^\]]*|RESULT|ERROR|COMPLETE|REFERENCES|OBSERVATION|CONFIRM:[^\]]*)\]/g,
+    '',
+  );
+}
+
+function parseContent(raw: string): Segment[] {
+  const segments: Segment[] = [];
+
+  for (const part of raw.split(TAG_SPLIT_RE)) {
+    if (!part) continue;
+
+    let m: RegExpMatchArray | null;
+
+    if ((m = part.match(/^\[STAGE:([^\]]*)\]([\s\S]*)\[\/STAGE\]$/))) {
+      const label = m[2].trim();
+      if (label) segments.push({ type: 'stage', label });
+
+    } else if ((m = part.match(/^\[THINKING\]([\s\S]*)\[\/THINKING\]$/))) {
+      const c = m[1].trim();
+      if (c) segments.push({ type: 'thinking', content: c });
+
+    } else if ((m = part.match(/^\[RESPONSE\]([\s\S]*)\[\/RESPONSE\]$/))) {
+      const c = m[1].trim();
+      if (c) segments.push({ type: 'response', content: c });
+
+    } else if ((m = part.match(/^\[TOOL_OUTPUT:([^\]]*)\]([\s\S]*)\[\/TOOL_OUTPUT\]$/))) {
+      segments.push({ type: 'tool_output', label: m[1], content: m[2] });
+
+    } else if ((m = part.match(/^\[GRADCAM_IMAGE:([^\]]+)\]$/))) {
+      segments.push({ type: 'gradcam', path: m[1] });
+
+    } else if ((m = part.match(/^\[COMPARISON_IMAGE:([^\]]+)\]$/))) {
+      segments.push({ type: 'comparison', path: m[1] });
+
+    } else if ((m = part.match(/^\[GRADCAM_COMPARE:([^:\]]+):([^\]]+)\]$/))) {
+      segments.push({ type: 'gradcam_compare', path1: m[1], path2: m[2] });
+
+    } else if ((m = part.match(/^\[RESULT\]([\s\S]*)\[\/RESULT\]$/))) {
+      const c = m[1].trim();
+      if (c) segments.push({ type: 'result', content: c });
+
+    } else if ((m = part.match(/^\[ERROR\]([\s\S]*)\[\/ERROR\]$/))) {
+      const c = m[1].trim();
+      if (c) segments.push({ type: 'error', content: c });
+
+    } else if ((m = part.match(/^\[COMPLETE\]([\s\S]*)\[\/COMPLETE\]$/))) {
+      const c = m[1].trim();
+      if (c) segments.push({ type: 'complete', content: c });
+
+    } else if ((m = part.match(/^\[REFERENCES\]([\s\S]*)\[\/REFERENCES\]$/))) {
+      segments.push({ type: 'references', content: m[1].trim() });
+
+    } else if ((m = part.match(/^\[OBSERVATION\]([\s\S]*)\[\/OBSERVATION\]$/))) {
+      const c = m[1].trim();
+      if (c) segments.push({ type: 'observation', content: c });
+
+    } else if ((m = part.match(/^\[CONFIRM:[^\]]*\]([\s\S]*)\[\/CONFIRM\]$/))) {
+      const c = m[1].trim();
+      if (c) segments.push({ type: 'result', content: c });
+
+    } else {
+      // Plain text (may be mid-stream with incomplete opening tags)
+      const cleaned = cleanStreamingText(part);
+      if (cleaned.trim()) segments.push({ type: 'text', content: cleaned });
+    }
+  }
+
+  return segments;
+}
+
+// ─── References renderer ──────────────────��────────────────────────────────
+
+function References({ content }: { content: string }) {
+  const refs = content.match(/\[REF:[^\]]+\]/g) ?? [];
+  if (!refs.length) return null;
+
+  return (
+    <div className="mc-references">
+      <div className="mc-references-title">References</div>
+      {refs.map((ref, i) => {
+        // [REF:id:source:page:file:superscript]
+        const parts = ref.slice(1, -1).split(':');
+        const source = parts[2] ?? '';
+        const page = parts[3] ?? '';
+        const sup = parts[5] ?? `[${i + 1}]`;
+        return (
+          <div key={i} className="mc-ref-item">
+            <span className="mc-ref-sup">{sup}</span>
+            <span className="mc-ref-source">{source}</span>
+            {page && <span className="mc-ref-page">, p.{page}</span>}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+// ─── Main component ────────────────────────────────────────────────────────
+
+export function MessageContent({ text }: { text: string }) {
+  const segments = parseContent(text);
+
+  return (
+    <div className="mc-root">
+      {segments.map((seg, i) => {
+        switch (seg.type) {
+          case 'stage':
+            return <div key={i} className="mc-stage">{seg.label}</div>;
+
+          case 'thinking':
+            return <div key={i} className="mc-thinking">{seg.content}</div>;
+
+          case 'response':
+            return (
+              <div key={i} className="mc-response">
+                <ReactMarkdown>{seg.content}</ReactMarkdown>
+              </div>
+            );
+
+          case 'tool_output':
+            return (
+              <div key={i} className="mc-tool-output">
+                {seg.label && <div className="mc-tool-output-label">{seg.label}</div>}
+                <pre>{seg.content}</pre>
+              </div>
+            );
+
+          case 'gradcam':
+            return (
+              <div key={i} className="mc-image-block">
+                <div className="mc-image-label">Grad-CAM Attention Map</div>
+                <img
+                  src={TEMP_IMG_URL(seg.path)}
+                  className="mc-gradcam-img"
+                  alt="Grad-CAM attention map"
+                />
+              </div>
+            );
+
+          case 'comparison':
+            return (
+              <div key={i} className="mc-image-block">
+                <div className="mc-image-label">Lesion Comparison</div>
+                <img
+                  src={TEMP_IMG_URL(seg.path)}
+                  className="mc-comparison-img"
+                  alt="Side-by-side lesion comparison"
+                />
+              </div>
+            );
+
+          case 'gradcam_compare':
+            return (
+              <div key={i} className="mc-image-block">
+                <div className="mc-image-label">Grad-CAM Comparison</div>
+                <div className="mc-gradcam-compare">
+                  <div className="mc-gradcam-compare-item">
+                    <div className="mc-gradcam-compare-title">Previous</div>
+                    <img
+                      src={TEMP_IMG_URL(seg.path1)}
+                      className="mc-gradcam-compare-img"
+                      alt="Previous GradCAM"
+                    />
+                  </div>
+                  <div className="mc-gradcam-compare-item">
+                    <div className="mc-gradcam-compare-title">Current</div>
+                    <img
+                      src={TEMP_IMG_URL(seg.path2)}
+                      className="mc-gradcam-compare-img"
+                      alt="Current GradCAM"
+                    />
+                  </div>
+                </div>
+              </div>
+            );
+
+          case 'result':
+            return <div key={i} className="mc-result">{seg.content}</div>;
+
+          case 'error':
+            return <div key={i} className="mc-error">{seg.content}</div>;
+
+          case 'complete':
+            return <div key={i} className="mc-complete">{seg.content}</div>;
+
+          case 'references':
+            return <References key={i} content={seg.content} />;
+
+          case 'observation':
+            return <div key={i} className="mc-observation">{seg.content}</div>;
+
+          case 'text':
+            return seg.content.trim() ? (
+              <div key={i} className="mc-text">{seg.content}</div>
+            ) : null;
+
+          default:
+            return null;
+        }
+      })}
+    </div>
+  );
+}

web/src/components/ToolCallCard.css

@@ -0,0 +1,338 @@
+/* ─── Card container ─────────────────────────────────────────────────────── */
+.tool-card {
+  border: 1px solid var(--gray-200);
+  border-left: 3px solid var(--primary);
+  border-radius: 10px;
+  overflow: hidden;
+  background: var(--gray-50);
+  margin-top: 8px;
+}
+
+.tool-card.loading {
+  border-left-color: var(--gray-400);
+}
+
+.tool-card.error {
+  border-left-color: #ef4444;
+}
+
+/* ─── Header (collapsed row) ─────────────────────────────────────────────── */
+.tool-card-header {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 14px;
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  text-align: left;
+  transition: background 0.15s;
+}
+
+.tool-card-header:hover:not(:disabled) {
+  background: var(--gray-100);
+}
+
+.tool-card-header:disabled {
+  cursor: default;
+}
+
+.tool-icon {
+  font-size: 1rem;
+  flex-shrink: 0;
+}
+
+.tool-label {
+  flex: 1;
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--gray-700);
+  text-transform: capitalize;
+}
+
+.tool-status {
+  font-size: 0.8125rem;
+  flex-shrink: 0;
+}
+
+.tool-status.done {
+  color: var(--success, #22c55e);
+  font-weight: 600;
+}
+
+.tool-status.calling {
+  color: var(--gray-500);
+  display: flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.tool-status.error-text {
+  color: #ef4444;
+}
+
+.tool-header-summary {
+  font-size: 0.8125rem;
+  color: var(--gray-500);
+  font-weight: 400;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 200px;
+}
+
+.tool-chevron {
+  font-size: 0.625rem;
+  color: var(--gray-400);
+  margin-left: 2px;
+  flex-shrink: 0;
+}
+
+/* ─── Spinner ────────────────────────────────────────────────────────────── */
+.spinner {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border: 2px solid var(--gray-300);
+  border-top-color: var(--gray-600);
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+/* ─── Card body ──────────────────────────────────────────────────────────── */
+.tool-card-body {
+  padding: 14px;
+  border-top: 1px solid var(--gray-200);
+  background: white;
+}
+
+/* ─── analyze_image ──────────────────────────────────────────────────────── */
+.analyze-result {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.analyze-top {
+  display: flex;
+  gap: 14px;
+  align-items: flex-start;
+}
+
+.analyze-thumb {
+  width: 72px;
+  height: 72px;
+  object-fit: cover;
+  border-radius: 8px;
+  border: 1px solid var(--gray-200);
+  flex-shrink: 0;
+}
+
+.analyze-info {
+  flex: 1;
+  min-width: 0;
+}
+
+.diagnosis-name {
+  font-size: 0.9375rem;
+  font-weight: 600;
+  color: var(--gray-900);
+  margin: 0 0 4px;
+  line-height: 1.3;
+}
+
+.confidence-label {
+  font-size: 0.8125rem;
+  font-weight: 500;
+  margin: 0 0 6px;
+}
+
+.confidence-bar-track {
+  height: 6px;
+  background: var(--gray-200);
+  border-radius: 999px;
+  overflow: hidden;
+}
+
+.confidence-bar-fill {
+  height: 100%;
+  border-radius: 999px;
+  transition: width 0.3s ease;
+}
+
+.analyze-summary {
+  font-size: 0.875rem;
+  color: var(--gray-700);
+  line-height: 1.6;
+  margin: 0;
+  border-top: 1px solid var(--gray-100);
+  padding-top: 10px;
+  white-space: pre-wrap;
+}
+
+.other-predictions {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  border-top: 1px solid var(--gray-100);
+  padding-top: 10px;
+}
+
+.prediction-row {
+  display: flex;
+  justify-content: space-between;
+  font-size: 0.8125rem;
+}
+
+.pred-name {
+  color: var(--gray-600);
+}
+
+.pred-pct {
+  color: var(--gray-500);
+  font-variant-numeric: tabular-nums;
+}
+
+/* ─── compare_images ─────────────────────────────────────────────────────── */
+.compare-result {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.carousel {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+}
+
+.carousel-image-wrap {
+  position: relative;
+  display: inline-block;
+}
+
+.carousel-image {
+  width: 200px;
+  height: 160px;
+  object-fit: cover;
+  border-radius: 10px;
+  border: 1px solid var(--gray-200);
+  display: block;
+}
+
+.carousel-label {
+  position: absolute;
+  bottom: 8px;
+  left: 50%;
+  transform: translateX(-50%);
+  background: rgba(0, 0, 0, 0.55);
+  color: white;
+  font-size: 0.75rem;
+  font-weight: 600;
+  padding: 3px 10px;
+  border-radius: 999px;
+  white-space: nowrap;
+}
+
+.carousel-btn {
+  background: white;
+  border: 1px solid var(--gray-300);
+  border-radius: 6px;
+  width: 28px;
+  height: 28px;
+  cursor: pointer;
+  font-size: 0.75rem;
+  color: var(--gray-600);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.carousel-btn:hover {
+  background: var(--gray-100);
+}
+
+.carousel-dots {
+  position: absolute;
+  bottom: -18px;
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  gap: 5px;
+}
+
+.carousel-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--gray-300);
+  cursor: pointer;
+  transition: background 0.15s;
+}
+
+.carousel-dot.active {
+  background: var(--primary);
+}
+
+.compare-status {
+  font-size: 0.9375rem;
+  margin-top: 6px;
+}
+
+.feature-changes {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.feature-row {
+  display: flex;
+  justify-content: space-between;
+  font-size: 0.8125rem;
+}
+
+.feature-name {
+  color: var(--gray-600);
+  text-transform: capitalize;
+}
+
+.feature-delta {
+  font-variant-numeric: tabular-nums;
+  font-weight: 500;
+}
+
+.compare-summary {
+  font-size: 0.875rem;
+  color: var(--gray-600);
+  line-height: 1.5;
+  margin: 0;
+  border-top: 1px solid var(--gray-100);
+  padding-top: 10px;
+}
+
+/* ─── Generic fallback ───────────────────────────────────────────────────── */
+.generic-result {
+  font-size: 0.75rem;
+  background: var(--gray-50);
+  border-radius: 6px;
+  padding: 10px;
+  overflow-x: auto;
+  color: var(--gray-700);
+  margin: 0;
+  white-space: pre-wrap;
+  word-break: break-all;
+}

web/src/components/ToolCallCard.tsx

@@ -0,0 +1,207 @@
+import { useEffect, useState } from 'react';
+import { ToolCall } from '../types';
+import './ToolCallCard.css';
+
+interface ToolCallCardProps {
+  toolCall: ToolCall;
+}
+
+/** One-line summary shown in the collapsed header so results are visible at a glance */
+function CollapsedSummary({ toolCall }: { toolCall: ToolCall }) {
+  const r = toolCall.result;
+  if (!r) return null;
+
+  if (toolCall.tool === 'analyze_image') {
+    const name = r.full_name ?? r.diagnosis;
+    const pct = r.confidence != null ? `${Math.round(r.confidence * 100)}%` : null;
+    if (name) return (
+      <span className="tool-header-summary">
+        {name}{pct ? ` — ${pct}` : ''}
+      </span>
+    );
+  }
+
+  if (toolCall.tool === 'compare_images') {
+    const key = r.status_label ?? 'STABLE';
+    const cfg = STATUS_CONFIG[key] ?? { emoji: '⚪', label: key };
+    return (
+      <span className="tool-header-summary">
+        {cfg.emoji} {cfg.label}
+      </span>
+    );
+  }
+
+  return null;
+}
+
+export function ToolCallCard({ toolCall }: ToolCallCardProps) {
+  // Auto-expand when the tool completes so results are immediately visible.
+  // User can collapse manually afterwards.
+  const [expanded, setExpanded] = useState(false);
+
+  useEffect(() => {
+    if (toolCall.status === 'complete') setExpanded(true);
+  }, [toolCall.status]);
+
+  const isLoading = toolCall.status === 'calling';
+  const isError = toolCall.status === 'error';
+
+  const icon = toolCall.tool === 'compare_images' ? '🔄' : '🔬';
+  const label = toolCall.tool.replace(/_/g, ' ');
+
+  return (
+    <div className={`tool-card ${isLoading ? 'loading' : ''} ${isError ? 'error' : ''}`}>
+      <button
+        className="tool-card-header"
+        onClick={() => !isLoading && setExpanded(e => !e)}
+        disabled={isLoading}
+      >
+        <span className="tool-icon">{icon}</span>
+        <span className="tool-label">{label}</span>
+        {isLoading ? (
+          <span className="tool-status calling">
+            <span className="spinner" /> running…
+          </span>
+        ) : isError ? (
+          <span className="tool-status error-text">error</span>
+        ) : (
+          <>
+            <span className="tool-status done">✓</span>
+            {!expanded && <CollapsedSummary toolCall={toolCall} />}
+          </>
+        )}
+        {!isLoading && (
+          <span className="tool-chevron">{expanded ? '▲' : '▼'}</span>
+        )}
+      </button>
+
+      {expanded && !isLoading && toolCall.result && (
+        <div className="tool-card-body">
+          {toolCall.tool === 'analyze_image' && (
+            <AnalyzeImageResult result={toolCall.result} />
+          )}
+          {toolCall.tool === 'compare_images' && (
+            <CompareImagesResult result={toolCall.result} />
+          )}
+          {toolCall.tool !== 'analyze_image' && toolCall.tool !== 'compare_images' && (
+            <GenericResult result={toolCall.result} />
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/* ─── analyze_image renderer ─────────────────────────────────────────────── */
+
+function AnalyzeImageResult({ result }: { result: ToolCall['result'] }) {
+  if (!result) return null;
+
+  const hasClassifier = result.diagnosis != null;
+  const topPrediction = result.all_predictions?.[0];
+  const otherPredictions = result.all_predictions?.slice(1) ?? [];
+  const confidence = result.confidence ?? topPrediction?.probability ?? 0;
+  const pct = Math.round(confidence * 100);
+  const statusColor = pct >= 70 ? '#ef4444' : pct >= 40 ? '#f59e0b' : '#22c55e';
+
+  return (
+    <div className="analyze-result">
+      <div className="analyze-top">
+        {result.image_url && (
+          <img
+            src={result.image_url}
+            alt="Analyzed lesion"
+            className="analyze-thumb"
+          />
+        )}
+        <div className="analyze-info">
+          {hasClassifier ? (
+            <>
+              <p className="diagnosis-name">{result.full_name ?? result.diagnosis}</p>
+              <p className="confidence-label" style={{ color: statusColor }}>
+                Confidence: {pct}%
+              </p>
+              <div className="confidence-bar-track">
+                <div
+                  className="confidence-bar-fill"
+                  style={{ width: `${pct}%`, background: statusColor }}
+                />
+              </div>
+            </>
+          ) : (
+            <p className="diagnosis-name" style={{ color: 'var(--gray-500)', fontWeight: 400, fontSize: '0.875rem' }}>
+              Visual assessment complete — classifier unavailable
+            </p>
+          )}
+        </div>
+      </div>
+
+      {hasClassifier && otherPredictions.length > 0 && (
+        <ul className="other-predictions">
+          {otherPredictions.map(p => (
+            <li key={p.class} className="prediction-row">
+              <span className="pred-name">{p.full_name ?? p.class}</span>
+              <span className="pred-pct">{Math.round(p.probability * 100)}%</span>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+/* ─── compare_images renderer ────────────────────────────────────────────── */
+
+const STATUS_CONFIG: Record<string, { label: string; color: string; emoji: string }> = {
+  STABLE: { label: 'Stable', color: '#22c55e', emoji: '🟢' },
+  MINOR_CHANGE: { label: 'Minor Change', color: '#f59e0b', emoji: '🟡' },
+  SIGNIFICANT_CHANGE: { label: 'Significant Change', color: '#ef4444', emoji: '🔴' },
+  IMPROVED: { label: 'Improved', color: '#3b82f6', emoji: '🔵' },
+};
+
+function CompareImagesResult({ result }: { result: ToolCall['result'] }) {
+  if (!result) return null;
+
+  const statusKey = result.status_label ?? 'STABLE';
+  const status = STATUS_CONFIG[statusKey] ?? { label: statusKey, color: '#6b7280', emoji: '⚪' };
+  const featureChanges = Object.entries(result.feature_changes ?? {});
+
+  return (
+    <div className="compare-result">
+      <div className="compare-status" style={{ color: status.color }}>
+        <strong>Status: {status.label} {status.emoji}</strong>
+      </div>
+
+      {featureChanges.length > 0 && (
+        <ul className="feature-changes">
+          {featureChanges.map(([name, vals]) => {
+            const delta = vals.curr - vals.prev;
+            const sign = delta > 0 ? '+' : '';
+            return (
+              <li key={name} className="feature-row">
+                <span className="feature-name">{name}</span>
+                <span className="feature-delta" style={{ color: Math.abs(delta) > 0.1 ? '#f59e0b' : '#6b7280' }}>
+                  {sign}{(delta * 100).toFixed(1)}%
+                </span>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+
+      {result.summary && (
+        <p className="compare-summary">{result.summary}</p>
+      )}
+    </div>
+  );
+}
+
+/* ─── Generic (unknown tool) renderer ───────────────────────────────────── */
+
+function GenericResult({ result }: { result: ToolCall['result'] }) {
+  return (
+    <pre className="generic-result">
+      {JSON.stringify(result, null, 2)}
+    </pre>
+  );
+}

web/src/index.css

@@ -0,0 +1,38 @@
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  background: #f8fafc;
+  color: #1e293b;
+  line-height: 1.5;
+}
+
+button {
+  font-family: inherit;
+  cursor: pointer;
+}
+
+input {
+  font-family: inherit;
+}
+
+:root {
+  --primary: #6366f1;
+  --primary-hover: #4f46e5;
+  --success: #10b981;
+  --error: #ef4444;
+  --gray-50: #f8fafc;
+  --gray-100: #f1f5f9;
+  --gray-200: #e2e8f0;
+  --gray-300: #cbd5e1;
+  --gray-400: #94a3b8;
+  --gray-500: #64748b;
+  --gray-600: #475569;
+  --gray-700: #334155;
+  --gray-800: #1e293b;
+  --gray-900: #0f172a;
+}

web/src/main.tsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { App } from './App'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

web/src/pages/ChatPage.css

@@ -0,0 +1,340 @@
+/* ─── Layout ───────────────────────────────────────────────────────────── */
+.chat-page {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  background: var(--gray-50);
+  overflow: hidden;
+}
+
+/* ─── Header ────────────────────────────────────────────────────────────── */
+.chat-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 0 16px;
+  height: 56px;
+  background: white;
+  border-bottom: 1px solid var(--gray-200);
+  flex-shrink: 0;
+  z-index: 10;
+}
+
+.header-back-btn {
+  width: 36px;
+  height: 36px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  color: var(--gray-600);
+  border-radius: 8px;
+  transition: background 0.15s;
+  flex-shrink: 0;
+}
+
+.header-back-btn:hover {
+  background: var(--gray-100);
+}
+
+.header-back-btn svg {
+  width: 20px;
+  height: 20px;
+}
+
+.header-center {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.header-app-name {
+  font-size: 0.7rem;
+  font-weight: 600;
+  color: var(--primary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  line-height: 1;
+}
+
+.header-patient-name {
+  font-size: 1rem;
+  font-weight: 600;
+  color: var(--gray-900);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  line-height: 1.3;
+}
+
+.header-clear-btn {
+  border: 1px solid var(--gray-300);
+  background: transparent;
+  border-radius: 8px;
+  padding: 6px 14px;
+  font-size: 0.8125rem;
+  color: var(--gray-600);
+  cursor: pointer;
+  transition: all 0.15s;
+  flex-shrink: 0;
+}
+
+.header-clear-btn:hover {
+  background: var(--gray-100);
+  border-color: var(--gray-400);
+}
+
+/* ─── Messages ──────────────────────────────────────────────────────────── */
+.chat-messages {
+  flex: 1;
+  overflow-y: auto;
+  padding: 20px 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.chat-empty {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  color: var(--gray-400);
+  text-align: center;
+  gap: 12px;
+  margin: auto;
+}
+
+.chat-empty-icon svg {
+  width: 40px;
+  height: 40px;
+  color: var(--gray-300);
+}
+
+.chat-empty p {
+  font-size: 0.9375rem;
+  max-width: 280px;
+  line-height: 1.5;
+}
+
+.message-row {
+  display: flex;
+  max-width: 720px;
+  width: 100%;
+}
+
+.message-row.user {
+  align-self: flex-end;
+  justify-content: flex-end;
+}
+
+.message-row.assistant {
+  align-self: flex-start;
+  justify-content: flex-start;
+}
+
+/* ─── Bubbles ────────────────────────────────────────────────────────────── */
+.bubble {
+  max-width: 85%;
+  border-radius: 16px;
+  padding: 12px 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.user-bubble {
+  background: var(--primary);
+  color: white;
+  border-bottom-right-radius: 4px;
+}
+
+.assistant-bubble {
+  background: white;
+  border: 1px solid var(--gray-200);
+  border-bottom-left-radius: 4px;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.06);
+  max-width: 90%;
+}
+
+.bubble-text {
+  font-size: 0.9375rem;
+  line-height: 1.6;
+  white-space: pre-wrap;
+  word-break: break-word;
+  margin: 0;
+}
+
+.user-bubble .bubble-text {
+  color: white;
+}
+
+.assistant-text {
+  color: var(--gray-800);
+}
+
+/* Image in user bubble */
+.message-image {
+  width: 100%;
+  max-width: 260px;
+  border-radius: 10px;
+  display: block;
+}
+
+/* ─── Thinking indicator ─────────────────────────────────────────────────── */
+.thinking {
+  display: flex;
+  gap: 4px;
+  padding: 4px 0;
+}
+
+.dot {
+  width: 7px;
+  height: 7px;
+  background: var(--gray-400);
+  border-radius: 50%;
+  animation: bounce 1.2s infinite;
+}
+
+.dot:nth-child(2) { animation-delay: 0.2s; }
+.dot:nth-child(3) { animation-delay: 0.4s; }
+
+@keyframes bounce {
+  0%, 60%, 100% { transform: translateY(0); }
+  30% { transform: translateY(-6px); }
+}
+
+/* ─── Input bar ──────────────────────────────────────────────────────────── */
+.chat-input-bar {
+  background: white;
+  border-top: 1px solid var(--gray-200);
+  padding: 12px 16px;
+  flex-shrink: 0;
+}
+
+.image-preview-container {
+  position: relative;
+  display: inline-block;
+  margin-bottom: 10px;
+}
+
+.image-preview-thumb {
+  width: 72px;
+  height: 72px;
+  object-fit: cover;
+  border-radius: 10px;
+  border: 2px solid var(--gray-200);
+  display: block;
+}
+
+.remove-image-btn {
+  position: absolute;
+  top: -8px;
+  right: -8px;
+  width: 22px;
+  height: 22px;
+  background: var(--gray-700);
+  color: white;
+  border: none;
+  border-radius: 50%;
+  font-size: 0.875rem;
+  line-height: 1;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.input-row {
+  display: flex;
+  align-items: flex-end;
+  gap: 8px;
+}
+
+.attach-btn {
+  width: 38px;
+  height: 38px;
+  border: 1px solid var(--gray-300);
+  background: transparent;
+  border-radius: 10px;
+  cursor: pointer;
+  color: var(--gray-500);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  transition: all 0.15s;
+}
+
+.attach-btn:hover:not(:disabled) {
+  background: var(--gray-100);
+  border-color: var(--gray-400);
+  color: var(--gray-700);
+}
+
+.attach-btn:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.attach-btn svg {
+  width: 18px;
+  height: 18px;
+}
+
+.chat-input {
+  flex: 1;
+  border: 1px solid var(--gray-300);
+  border-radius: 10px;
+  padding: 9px 14px;
+  font-size: 0.9375rem;
+  font-family: inherit;
+  resize: none;
+  line-height: 1.5;
+  max-height: 160px;
+  overflow-y: auto;
+  transition: border-color 0.15s;
+}
+
+.chat-input:focus {
+  outline: none;
+  border-color: var(--primary);
+}
+
+.chat-input:disabled {
+  background: var(--gray-50);
+  color: var(--gray-400);
+}
+
+.send-btn {
+  width: 38px;
+  height: 38px;
+  background: var(--primary);
+  color: white;
+  border: none;
+  border-radius: 10px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  transition: background 0.15s;
+}
+
+.send-btn:hover:not(:disabled) {
+  background: var(--primary-hover);
+}
+
+.send-btn:disabled {
+  background: var(--gray-300);
+  cursor: not-allowed;
+}
+
+.send-btn svg {
+  width: 18px;
+  height: 18px;
+}