ShipSight Intelligence

💡 Inspiration It started with a frustrating realization: 90% of global cross-border traders are SMEs, yet every serious logistics intelligence tool — Project44, FourKites, Everstream — is built exclusively for enterprise conglomerates with six-figure budgets. SMEs are left managing international shipments with static spreadsheets and gut feelings, discovering a customs hold-up or port delay only after it's already too late.

We wanted to answer one question: what if a small exporter could know their shipment was going to be delayed — before it even left the warehouse?

🔨 How We Built It We built a Hybrid AI Triad — three AI layers working in sequence:

XGBoost (trained on 10,000+ real USAID SCMS shipment records) predicts exact delay duration in days and classifies risk as High or Low

TreeSHAP computes game-theoretic Shapley values in real-time, surfacing the top risk drivers so there is zero black-box opacity

Google Gemini reads the ML outputs + SHAP drivers and generates exactly 3 actionable mitigation steps per shipment

The stack: FastAPI backend with Pydantic v2 validation, Next.js 16 frontend with Recharts visualizations, and Supabase PostgreSQL for prediction logging and ground-truth feedback.

🧱 Challenges We Faced The hardest part wasn't the ML — it was the integration layer. A few real battles from our debug log:

Feature naming mismatch: Pydantic schemas used snake_case while XGBoost models expected original training column names like "Vendor INCO Term". Solved with a FIELD_MAP dictionary in predictor.py

Docker + XGBoost on Linux: The python:3.12-slim container was missing libgomp1 — XGBoost's OpenMP dependency — causing silent crashes on Render deployment

Gemini model deprecation: Hardcoded model IDs broke mid-development. We made model selection dynamic via an optional model_name field in the request schema

Uptime monitors returning 405: Cloud probes send HEAD requests, not GET. Added explicit @app.head() routes to fix false-positive downtime alerts

The classification threshold was also tuned from the default 0.50 to 0.51 using cost-sensitive F1 optimization, pushing recall on delayed shipments to 72.5% — because missing a real delay is far more costly than a false alarm.

📚 What We Learned Explainability is not optional for domain users. Supply chain managers won't trust a risk score without knowing why. SHAP turned skepticism into confidence.

Dual-source fallback architecture matters in demos. Our Dev Mode benchmark inspector queries Supabase first, then falls back to local CSV — so the demo never fails due to network issues.

Building for SMEs means removing friction, not adding features. The entire single-shipment prediction flow — form to SHAP chart to Gemini action plan — completes in under 2 seconds.