EmissionsNet Prototype (MVP)

This is a minimal, runnable prototype of an EmissionsNet-style system:

• a registry of supply-chain segment nodes
• a standard payload each node exposes (emissions intensity, allocation method, confidence interval, fidelity score, and input/output ratios)
• a traversal engine that recursively aggregates upstream emissions and returns a breakdown
• an interactive graph visualization where users can click suppliers to see how supply-chain emissions change.

Quick start

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# run the API
uvicorn emissionsnet.app:app --reload

Seed the demo + compute a result

# Seed the richer demo supply chain (extraction -> transport -> refining -> blending -> distribution -> retail)
curl -X POST http://127.0.0.1:8000/demo/seed   -H "X-API-Key: demo"

# Traverse (compute total CI for 1 unit of gasoline sold at the station)
curl -X POST http://127.0.0.1:8000/traverse   -H "Content-Type: application/json"   -H "X-API-Key: demo"   -d '{
    "target_node_id": "station_j",
    "product": "gasoline_retail",
    "quantity": 1
  }'

Interactive visualization

After starting the server, open:

• http://127.0.0.1:8000/viz

Workflow:

1. Click Seed demo (if not already seeded)
2. Click Load graph
3. Click edges (supplier → consumer) to choose a supplier for that requirement
4. Click Compute (or leave Auto enabled) to recompute total CI and see which edges were used
5. Click Optimize to generate a least-CI supplier path, then toggle 🔒/🔓 to compare optimized vs your manual picks

Tip: clicking a node shows its products + requirements in the side panel; you can also choose suppliers from dropdowns there.

Supplier overrides (manual “Tier 1 supplier” selection)

To force a supplier choice for a specific dependency edge, pass:

• supplier_overrides["consumer_node_id|output_product|requirement_id"] = "supplier_node_id"

Example (force the retail station to use pipeline distribution instead of truck distribution):

{
  "target_node_id": "station_j",
  "product": "gasoline_retail",
  "quantity": 1,
  "supplier_overrides": {
    "station_j|gasoline_retail|station_j_fuel_in": "dist_pipeline"
  }
}

Notes / limitations

• This is a toy implementation to validate the protocol + traversal mechanics.
• CI propagation uses a conservative linear sum of low/high bounds.
• “Optimization” is a greedy dynamic program that assumes independent sub-choices and an acyclic graph.
• Units are not validated beyond being strings — a production version should enforce dimensional consistency.
• Persistence is in-memory; swap NodeRegistry for a database (Postgres) when needed.
• Auth is a single header key (X-API-Key), intended only to illustrate the access-token concept.

Where to go next

• Replace placeholder EI values with actual model outputs and/or satellite-derived estimates.
• Add a “node execution” plug-in layer so node owners can run black-box calculations behind the same API contract.
• Add provenance objects (inputs, model versions, auditors) to support chain-of-custody reporting.
• Add UI features like saved scenarios, sharing links, and audit-ready reporting.