LAMDA: Supply Chain Risk Prediction System

LAMDA estimates real-time disruption risk across a small network of major shipping ports and recommends the lowest-risk route between them. It combines live signal scraping, a graph attention model for spatial risk propagation, and A* pathfinding into a single Flask API.

Overview

The system tracks five global trade hubs (Hong Kong, Singapore, Shanghai, Tokyo, Los Angeles) connected in a distance-based graph. For each node it pulls in supply chain pressure data, news, political risk, weather, and trade volume, turns that into a 6-dimensional risk vector, and propagates it across the graph with a Graph Attention Network so that risk at one port can influence its neighbors. A route optimizer then uses those scores to find the lowest-risk paths between any two ports.

This started as a way to explore graph neural networks in a real-world logistics context rather than as a production system. The node set, update interval, and data sources reflect that scope.

How it works

scrapers (gscpi, news, political, trade, weather, reporter credibility)
        |
        v
intelligence processor
  - normalizes GSCPI and trade data
  - scores news/political/weather text with Gemini, or a keyword
    heuristic if no API key is configured
  - applies reporter credibility weighting
  - outputs a 6D risk vector per node
        |
        v
graph risk engine
  - Graph Attention Network (PyTorch Geometric) propagates risk
    across the port graph based on distance-weighted edges
  - stores the last 10 snapshots per node in SQLite
        |
        v
route optimizer
  - A* search with a cost function over risk, distance, and trade volume
  - returns the k best, sufficiently distinct routes between two ports
        |
        v
Flask API
  - exposes route analysis, node status, and graph state
  - background scheduler refreshes the graph on an interval

Tech stack

• Python, Flask, Flask-CORS
• PyTorch and PyTorch Geometric (GATConv) for the graph model
• SQLite for risk history
• APScheduler for periodic graph updates
• SerpAPI, Open-Meteo, OpenWeatherMap, UN Comtrade, and the World Bank API as data sources
• Google Gemini as an optional LLM for text analysis, with a deterministic keyword-based fallback

Getting started

Prerequisites

• Python 3.10+
• pip

Installation

git clone https://github.com/Mayan10/LAMDA.git
cd LAMDA

python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate

pip install -r requirements.txt

Configuration

cp .env.example .env

All API keys are optional. Without them, the system falls back to free data sources (Open-Meteo, UN Comtrade, World Bank) and a deterministic heuristic for text scoring instead of an LLM call.

Variable	Purpose
SERPAPI_API_KEY	Live news, political, and weather search enrichment
OPENWEATHERMAP_API_KEY	Additional weather data source
GEMINI_API_KEY	Enables LLM-based text scoring instead of the keyword heuristic
SCRAPER_HTTP_ENABLED	If true, calls scrapers as separately hosted services instead of running them in-process

Running

python api_server.py

On first run this builds the graph structure, fetches live data, and starts the API on http://localhost:5001. Use PORT=8080 python api_server.py to run on a different port.

The graph refreshes automatically every 30 minutes (UPDATE_INTERVAL_MINUTES in .env), or on demand via POST /api/update_graph.

API reference

Base URL: http://localhost:5001/api

POST /api/analyze_route

Finds the best routes between two nodes.

curl -X POST http://localhost:5001/api/analyze_route \
  -H "Content-Type: application/json" \
  -d '{"source": "Hong_Kong", "destination": "Los_Angeles", "num_routes": 3}'

GET /api/node_status/<node_id>

Current risk breakdown for a single node.

curl http://localhost:5001/api/node_status/Hong_Kong

GET /api/graph_snapshot

Full graph state with nodes, edges, and aggregate risk statistics.

curl http://localhost:5001/api/graph_snapshot

GET /api/historical_trends/<node_id>?limit=10

Recent risk history for a node (up to the last 10 stored snapshots).

curl "http://localhost:5001/api/historical_trends/Hong_Kong?limit=5"

GET /api/available_nodes

Lists all supported nodes with their current overall risk.

curl http://localhost:5001/api/available_nodes

POST /api/update_graph

Manually triggers a graph update outside the scheduled interval.

curl -X POST http://localhost:5001/api/update_graph

GET /api/health

Reports whether each component initialized and which LLM provider is active.

curl http://localhost:5001/api/health

Project structure

api_server.py              Flask app, scheduler, and route handlers
intelligence_processor.py  Turns raw scraper output into risk vectors
graph_risk_engine.py       GAT model, graph state, and SQLite persistence
route_optimizer.py         A* search and route analysis
scraper_orchestrator.py    Coordinates in-process or HTTP scraper calls
node_metadata.py           Node definitions and graph edge construction
scrapers/                  One module per data source (GSCPI, news,
                            political, trade, weather, reporter credibility)
deploy/                    Example systemd unit for a single-server deployment

Design notes and limitations

• The node graph is fixed at five ports. node_metadata.py builds edges from a minimum spanning tree plus each node's two nearest neighbors, so it is not a fully connected graph.
• The GAT model propagates risk using its attention mechanism over the graph structure at inference time; it is not trained on historical disruption outcomes in this version. Extending it with a labeled dataset and a training loop is a natural next step.
• Text-based risk scoring (news, political, weather) uses Gemini when GEMINI_API_KEY is set, and otherwise falls back to a keyword-weighted heuristic so the system still runs without any LLM access.
• Risk history is capped at the last 10 snapshots per node in SQLite, intended for short-term trend display rather than long-term storage.

License

MIT, see LICENSE.