Upload integral_ml_and_dashboard.md

integral_ml_and_dashboard.md

@@ -0,0 +1,440 @@
+# Integral — ML Verification Notebook + React GraphQL Integration + Map UI
+
+This document contains three deliverables you requested: **(A) ML verification notebook** (pothole detection & verification), **(B) React dashboard GraphQL queries & subscription wiring**, and **(C) Map UI (Leaflet)** integration. Each section includes runnable code, dependency lists, and quickstart instructions.
+
+---
+
+## A — ML Verification Notebook (Jupyter, Python)
+
+**Purpose:** Train a pothole detection model (segmentation + bbox) and produce a confidence score per detection for the verification-service. Exports inference results to the `detection-service` endpoint or writes directly to the Postgres `objects` table.
+
+**Notes:** Use labeled images from vehicle dashcams, crowd-sourced uploads, and satellite tiles. This notebook uses PyTorch + torchvision and a simple U-Net-style segmentation + simple classifier for confidence.
+
+### Dependencies
+
+```bash
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118  # or CPU wheel
+pip install jupyterlab opencv-python scikit-learn geopandas rasterio shapely matplotlib tqdm requests
+pip install albumentations
+```
+
+### Notebook (save as `ml_verification.ipynb` — here shown as linear Python cells)
+
+```python
+# cell 1: imports
+import os
+import json
+from pathlib import Path
+import random
+import numpy as np
+import cv2
+import torch
+import torch.nn as nn
+from torch.utils.data import Dataset, DataLoader
+import torchvision.transforms as T
+import albumentations as A
+from sklearn.model_selection import train_test_split
+from tqdm import tqdm
+import requests
+
+# cell 2: config
+DATA_DIR = Path('data')
+IMAGES_DIR = DATA_DIR/'images'
+MASKS_DIR = DATA_DIR/'masks'   # segmentation masks where potholes marked
+BATCH_SIZE = 8
+NUM_EPOCHS = 20
+DEVICE = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+MODEL_DIR = Path('model')
+MODEL_DIR.mkdir(parents=True, exist_ok=True)
+
+# cell 3: dataset
+class PotholeDataset(Dataset):
+    def __init__(self, image_paths, mask_paths, transforms=None):
+        self.images = image_paths
+        self.masks = mask_paths
+        self.transforms = transforms
+
+    def __len__(self):
+        return len(self.images)
+
+    def __getitem__(self, idx):
+        img = cv2.imread(str(self.images[idx]), cv2.IMREAD_COLOR)
+        img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+        mask = cv2.imread(str(self.masks[idx]), cv2.IMREAD_GRAYSCALE)
+        # normalize mask to 0/1
+        mask = (mask > 127).astype('float32')
+        if self.transforms:
+            augmented = self.transforms(image=img, mask=mask)
+            img = augmented['image']
+            mask = augmented['mask']
+        img = img.astype('float32') / 255.0
+        img = np.transpose(img, (2,0,1))
+        img_t = torch.tensor(img, dtype=torch.float32)
+        mask_t = torch.tensor(mask, dtype=torch.float32).unsqueeze(0)
+        return img_t, mask_t
+
+# cell 4: simple U-Net model
+class DoubleConv(nn.Module):
+    def __init__(self, in_c, out_c):
+        super().__init__()
+        self.net = nn.Sequential(
+            nn.Conv2d(in_c, out_c, 3, padding=1),
+            nn.ReLU(inplace=True),
+            nn.Conv2d(out_c, out_c, 3, padding=1),
+            nn.ReLU(inplace=True)
+        )
+    def forward(self,x): return self.net(x)
+
+class UNet(nn.Module):
+    def __init__(self, n_channels=3, n_classes=1):
+        super().__init__()
+        self.enc1 = DoubleConv(n_channels, 64)
+        self.pool = nn.MaxPool2d(2)
+        self.enc2 = DoubleConv(64,128)
+        self.enc3 = DoubleConv(128,256)
+        self.enc4 = DoubleConv(256,512)
+        self.up3 = nn.ConvTranspose2d(512,256,2,stride=2)
+        self.dec3 = DoubleConv(512,256)
+        self.up2 = nn.ConvTranspose2d(256,128,2,stride=2)
+        self.dec2 = DoubleConv(256,128)
+        self.up1 = nn.ConvTranspose2d(128,64,2,stride=2)
+        self.dec1 = DoubleConv(128,64)
+        self.final = nn.Conv2d(64, n_classes, 1)
+    def forward(self,x):
+        e1 = self.enc1(x)
+        e2 = self.enc2(self.pool(e1))
+        e3 = self.enc3(self.pool(e2))
+        e4 = self.enc4(self.pool(e3))
+        d3 = self.dec3(torch.cat([self.up3(e4), e3], dim=1))
+        d2 = self.dec2(torch.cat([self.up2(d3), e2], dim=1))
+        d1 = self.dec1(torch.cat([self.up1(d2), e1], dim=1))
+        out = self.final(d1)
+        return torch.sigmoid(out)
+
+# cell 5: prepare data lists (you must provide matching images & masks filenames)
+image_files = sorted(list((IMAGES_DIR).glob('*.jpg')))
+mask_files = sorted(list((MASKS_DIR).glob('*.png')))
+train_imgs, val_imgs, train_masks, val_masks = train_test_split(image_files, mask_files, test_size=0.2, random_state=42)
+
+transform = A.Compose([
+    A.Resize(256,256),
+    A.HorizontalFlip(p=0.5),
+    A.RandomBrightnessContrast(p=0.3),
+])
+
+train_ds = PotholeDataset(train_imgs, train_masks, transforms=transform)
+val_ds = PotholeDataset(val_imgs, val_masks, transforms=A.Compose([A.Resize(256,256)]))
+train_loader = DataLoader(train_ds, batch_size=BATCH_SIZE, shuffle=True)
+val_loader = DataLoader(val_ds, batch_size=BATCH_SIZE, shuffle=False)
+
+# cell 6: training loop
+model = UNet().to(DEVICE)
+optimizer = torch.optim.Adam(model.parameters(), lr=1e-4)
+criterion = nn.BCELoss()
+
+for epoch in range(NUM_EPOCHS):
+    model.train()
+    running_loss = 0.0
+    for imgs, masks in tqdm(train_loader, desc=f'train {epoch}'):
+        imgs = imgs.to(DEVICE); masks = masks.to(DEVICE)
+        preds = model(imgs)
+        loss = criterion(preds, masks)
+        optimizer.zero_grad(); loss.backward(); optimizer.step()
+        running_loss += loss.item()
+    print(f'Epoch {epoch} loss {running_loss/len(train_loader):.4f}')
+    # validation
+    model.eval()
+    val_loss = 0.0
+    with torch.no_grad():
+        for imgs, masks in val_loader:
+            imgs = imgs.to(DEVICE); masks = masks.to(DEVICE)
+            preds = model(imgs)
+            val_loss += criterion(preds, masks).item()
+    print(f'Val loss {val_loss/len(val_loader):.4f}')
+    torch.save(model.state_dict(), MODEL_DIR/f'unet_epoch_{epoch}.pt')
+
+# cell 7: inference helper -> produce detections
+import scipy.ndimage as ndi
+
+def infer_and_extract(img_path, model, threshold=0.3, min_area=50):
+    img = cv2.imread(img_path)
+    h0,w0 = img.shape[:2]
+    img_r = cv2.resize(img, (256,256))
+    x = np.transpose(img_r.astype('float32')/255.0, (2,0,1))
+    x = torch.tensor(x).unsqueeze(0).to(DEVICE)
+    with torch.no_grad():
+        pred = model(x)[0,0].cpu().numpy()
+    # resize mask back
+    mask = cv2.resize((pred>threshold).astype('uint8'), (w0,h0))
+    labeled, n = ndi.label(mask)
+    detections = []
+    for region in range(1,n+1):
+        ys, xs = np.where(labeled==region)
+        if len(xs) < min_area: continue
+        x_min, x_max = xs.min(), xs.max()
+        y_min, y_max = ys.min(), ys.max()
+        area = len(xs)
+        conf = pred[ys, xs].mean()  # approximate confidence
+        detections.append({
+            'bbox': [int(x_min), int(y_min), int(x_max), int(y_max)],
+            'area': int(area),
+            'confidence': float(conf)
+        })
+    return detections, mask
+
+# cell 8: export detections -> call detection-service
+DETECTION_API = os.getenv('DETECTION_API','http://localhost:3001/detect')
+
+def export_detection(location, image_url, detections, provenance):
+    # choose highest confidence detection
+    if not detections: return None
+    top = max(detections, key=lambda d: d['confidence'])
+    payload = {
+        'namespace':'satellite',
+        'type':'pothole-detection',
+        'timestamp':None,
+        'location': location,
+        'severity': int(min(5, max(1, int(top['area']/500)))),  # heuristic
+        'images':[image_url],
+        'provenance': provenance
+    }
+    try:
+        r = requests.post(DETECTION_API, json=payload, timeout=5)
+        return r.json()
+    except Exception as e:
+        print('export failed', e)
+        return None
+
+# usage example
+if __name__ == '__main__':
+    model.load_state_dict(torch.load(MODEL_DIR/'unet_epoch_19.pt', map_location=DEVICE))
+    test_img = 'data/ground/test1.jpg'
+    dets, mask = infer_and_extract(test_img, model)
+    print(dets)
+    # export with a dummy location/provenance
+    print(export_detection({'lat':-29.12,'lon':26.22}, 'https://example.com/test1.jpg', dets, {'source':'ml-run','license':'CC0'}))
+```
+
+---
+
+## B — React Dashboard: GraphQL queries & subscriptions (Apollo Client)
+
+**Goal:** Wire the dashboard to the Apollo Server created earlier. Provide query examples, subscription usage, and UI integration (hooks + state).
+
+### Dependencies
+
+```bash
+npm install @apollo/client graphql subscriptions-transport-ws graphql-ws
+npm install leaflet react-leaflet
+```
+
+> Note: `graphql-ws` is recommended for modern websockets; for Apollo v3 use `subscriptions-transport-ws` or adapt to your server.
+
+### Apollo client setup (src/apollo.js)
+
+```js
+import { ApolloClient, InMemoryCache, HttpLink, split } from '@apollo/client';
+import { GraphQLWsLink } from '@apollo/client/link/subscriptions';
+import { createClient } from 'graphql-ws';
+import { getMainDefinition } from '@apollo/client/utilities';
+
+const httpLink = new HttpLink({ uri: 'http://localhost:4000/graphql' });
+const wsLink = new GraphQLWsLink(createClient({ url: 'ws://localhost:4000/graphql' }));
+
+const splitLink = split(
+  ({ query }) => {
+    const def = getMainDefinition(query);
+    return def.kind === 'OperationDefinition' && def.operation === 'subscription';
+  },
+  wsLink,
+  httpLink
+);
+
+export const client = new ApolloClient({
+  link: splitLink,
+  cache: new InMemoryCache(),
+});
+```
+
+### Queries & Subscriptions (src/graphql/queries.js)
+
+```js
+import { gql } from '@apollo/client';
+
+export const LIST_FAULTS = gql`
+  query ListInfraFaults($limit:Int,$offset:Int){
+    listInfraFaults(limit:$limit,offset:$offset){
+      id namespace type timestamp severity confirmed images provenance
+    }
+  }
+`;
+
+export const FAULT_CREATED = gql`
+  subscription { faultCreated { id namespace type timestamp location severity confirmed images provenance } }
+`;
+
+export const FAULT_CONFIRMED = gql`
+  subscription { faultConfirmed { id confirmed } }
+`;
+
+export const PAYOUT_UPDATED = gql`
+  subscription { payoutUpdated { id faultId amountMinorUnits currency payeeId status txRef } }
+`;
+```
+
+### React hook usage (src/hooks/useFaults.js)
+
+```js
+import { useQuery, useSubscription } from '@apollo/client';
+import { LIST_FAULTS, FAULT_CREATED, FAULT_CONFIRMED } from '../graphql/queries';
+
+export function useFaults() {
+  const { data, loading, error, fetchMore } = useQuery(LIST_FAULTS, { variables: { limit: 50, offset: 0 } });
+
+  useSubscription(FAULT_CREATED, {
+    onSubscriptionData: ({ client, subscriptionData }) => {
+      const newFault = subscriptionData.data.faultCreated;
+      // optional: update cache or refetch
+      client.cache.modify({
+        fields: {
+          listInfraFaults(existing = []) {
+            const newRef = client.cache.writeFragment({
+              data: newFault,
+              fragment: gql`fragment NewFault on InfrastructureFault { id namespace type timestamp severity confirmed images provenance }`
+            });
+            return [newRef, ...existing];
+          }
+        }
+      });
+    }
+  });
+
+  useSubscription(FAULT_CONFIRMED, {
+    onSubscriptionData: ({ client, subscriptionData }) => {
+      const changed = subscriptionData.data.faultConfirmed;
+      // update cache entry
+      client.cache.modify({ id: client.cache.identify({ __typename: 'InfrastructureFault', id: changed.id }), fields: { confirmed() { return changed.confirmed; } } });
+    }
+  });
+
+  return { data, loading, error, fetchMore };
+}
+```
+
+### Wiring into dashboard component (snippet)
+
+```js
+import React from 'react';
+import { useFaults } from './hooks/useFaults';
+
+export default function InfraPanel(){
+  const { data, loading } = useFaults();
+  if(loading) return <div>Loading...</div>;
+  return (
+    <div>
+      {data.listInfraFaults.map(f => (
+        <div key={f.id} className="card">
+          <h4>{f.type} — severity {f.severity}</h4>
+          <p>Confirmed: {String(f.confirmed)}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## C — Map UI (Leaflet + React-Leaflet) with Satellite overlays
+
+**Goal:** Display pothole markers, heatmap, and satellite overlays (Sentinel tile layers or Mapbox). Clicking a marker opens verification panel and create/settle actions.
+
+### Dependencies
+
+```bash
+npm install leaflet react-leaflet leaflet.heat
+```
+
+Also add CSS in your app root for leaflet:
+
+```css
+/* index.css */
+.leaflet-container { height: 100%; width: 100%; }
+```
+
+### Map component (src/components/MapView.jsx)
+
+```jsx
+import React, { useEffect, useState } from 'react';
+import { MapContainer, TileLayer, Marker, Popup, Circle } from 'react-leaflet';
+import 'leaflet/dist/leaflet.css';
+import L from 'leaflet';
+
+// fix default icon issues in many bundlers
+delete L.Icon.Default.prototype._getIconUrl;
+L.Icon.Default.mergeOptions({
+  iconRetinaUrl: require('leaflet/dist/images/marker-icon-2x.png'),
+  iconUrl: require('leaflet/dist/images/marker-icon.png'),
+  shadowUrl: require('leaflet/dist/images/marker-shadow.png')
+});
+
+import { useFaults } from '../hooks/useFaults';
+
+export default function MapView(){
+  const { data } = useFaults();
+  const [center] = useState([-29.12,26.22]);
+
+  return (
+    <MapContainer center={center} zoom={13} style={{height:'600px'}}>
+      <TileLayer
+        attribution='&copy; OpenStreetMap contributors'
+        url='https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
+      />
+
+      {/* Optional Satellite overlay with Mapbox (requires token): */}
+      {/* <TileLayer url={`https://api.mapbox.com/styles/v1/mapbox/satellite-v9/tiles/{z}/{x}/{y}?access_token=${process.env.MAPBOX_TOKEN}`} /> */}
+
+      {data && data.listInfraFaults.map(f => (
+        <Marker key={f.id} position={[f.location.lat,f.location.lon]}>
+          <Popup>
+            <div>
+              <strong>{f.type}</strong>
+              <p>Severity: {f.severity}</p>
+              <p>Confirmed: {String(f.confirmed)}</p>
+              {f.images && f.images.length>0 && <img src={f.images[0]} alt="pothole" style={{width:'200px'}}/>}
+              <div>
+                <button onClick={()=>{/* call confirm mutation */}}>Confirm</button>
+              </div>
+            </div>
+          </Popup>
+        </Marker>
+      ))}
+
+    </MapContainer>
+  );
+}
+```
+
+### Heatmap (optional)
+
+Use `leaflet.heat` plugin. Convert faults into weighted points by severity.
+
+---
+
+## Deployment & Running
+
+1. Start Postgres + Redis + Apollo server (see earlier `integral-apollo-server` canvas doc). Run migrations.
+2. Start the Apollo client React app (`npm start`) with `client` configured to `http://localhost:4000/graphql` and WS `ws://localhost:4000/graphql`.
+3. Prepare training data and run `ml_verification.ipynb` to train a model and generate detection exports to the detection-service endpoint.
+4. Use the dashboard to observe faults appearing in real-time and interact with map UI to verify and settle payouts.
+
+---
+
+## Next suggestions
+
+- I can **export the ML notebook as an actual `.ipynb` file** and attach it for download.  
+- I can **generate the full React project files** (components, hooks, package.json) in the canvas and zip them.  
+- I can **produce a small sample dataset** (synthetic images + masks) so you can run training quickly.  
+
+Which of those would you like me to produce now?
+