zandy700/supply-chain-shock-map

What it does

The project studies how news-driven supply-chain shocks might propagate to S&P 500 stocks. It combines SEC filing relations, headline classification, signed shock propagation (upstream suppliers and downstream customers, decayed per hop), an OLS market-model event study with +1/+5/+20 day CARs, and an append-only hash-chained prediction ledger scored separately after outcomes mature. The audience is researchers and technically curious investors, not people looking for a live trading signal.

The repository ships two separate layers: a Python research engine and a mobile-first static UI. The UI runs on seeded sample JSON only — no live news, no verified relationships, no real forecasts. Sample confidence labels are illustrative, not calibrated probabilities.

Quick start

For the sample UI (Python 3 or any static server):

python -m http.server 8000 --directory web

Open http://localhost:8000, enter comma-separated tickers, and the watchlist is saved in this browser under watchlist-pulse. For demo content, use http://localhost:8000/?seed=demo to load AAPL, META, NVDA and TSLA. The site routes include #/briefing, #/catalysts, #/watchlist, #/company/NVDA, and #/ledger. A hosted Worker demo is also available at the live demo.

For the research engine, Python 3.11+ is needed:

pip install -e '.[dev]'
python -m scsm ingest --offline
python -m scsm propagate
python -m scsm backtest
python -m scsm ledger verify
python -m scsm score

Run from the checkout so cached data and vendored sources resolve. Outputs such as results and ledger files live in the repo; see the graph provenance document for acquisition and rebuild instructions. Broker-related setup lives in the broker setup docs.

Constraints and known limits

The shipped graph is tiny: 12 nodes and 10 reviewed edges from 14 primary 2021 SEC filings. Filings are historical snapshots, not a current S&P 500 map, and ambiguous relationships are excluded. Severity, decay and exposure weights are modeling choices, not estimated returns. Live GDELT matches are unreviewed and excluded from backtests.

The backtest covers 88 hand-selected historical scenarios (25 positive, 63 negative) from March 2021 through November 2, 2026. No overall horizon beats the always-predict-zero baseline on MAE with a CI excluding zero; upstream hit rates are consistent with a coin flip. Downstream has only 7 observations, with 2 correct signs. The authors describe the sample as a convenience cohort with selection bias, overlapping windows and no multiple-testing correction, so a tradable edge is not established. The hash chain detects tampering within the ledger but does not prove independent timestamps or prevent a complete rewrite; keep a trusted head hash.

The code is MIT, but third-party data (SEC filings, news metadata, market data) carries its own terms and is not relicensed by the project. Daily automation runs through GitHub Actions and needs Actions enabled with write permission; CI checks Ruff, offline tests, ledger chain verification and a byte-level rebuild of committed web/data.

HotRepo's take

This is a small, recent JavaScript repository that gained a few stars in the tracked November 2026 new-list window, with no GitHub daily ranking recorded. The engineering is unusually candid for a finance project: the README publishes baseline comparisons against a zero forecast, reports confidence intervals, and explicitly says the propagation model is not validated. The weak point for readers is scope rather than disclosure — a 12-node graph, 88 curated events and a sample-only UI mean the repo is better read as a methodology and research harness than as a market tool.