scope3-calculation

Agentic Scope 3 Stage 2: Quantification (LCA) module.

Current MVP supports:

• CSV ingestion → normalized storage (activity_rows)
• LCA compute → factor mapping + deterministic emissions + DQS (inventory_items)
• Hotspots + gap detection (emissions-based)
• Finance-grade primitives: append-only run history + item versions + adjustment restatements + factor overrides w/ approvals

Docs:

• docs/DEVELOPMENT.md
• docs/API.md
• docs/DATA_MODEL.md
• docs/TESTING.md
• docs/MATURITY_GAP_ANALYSIS.md
• docs/CALCULATOR_TEST_MATRIX.md
• docs/TRACEABILITY.md
• docs/SWARM_ORCHESTRATION.md

Backend (FastAPI + MongoDB)

Env

Create backend/.env (or export env vars):

• MONGO_URL (required)
• DB_NAME (required)
• CORS_ORIGINS (optional, comma-separated; default *)
• MAX_UPLOAD_MB (optional; default 20)
• MONGO_INSERT_CHUNK_SIZE (optional; default 1000)
• LCA_FACTORS_PREFETCH_LIMIT (optional; default 5000)
• LCA_FACTOR_CANDIDATES_K (optional; default 3)
• LCA_VECTOR_STORE (optional; mongo default; chroma optional)
• PINECONE_API_KEY, PINECONE_INDEX (optional; required only when LCA_VECTOR_STORE=pinecone)
• LCA_HASH_DIMS (optional; default 512; must be integer in [64, 4096])

Vector-store fallback semantics:

• If vector_store is explicitly provided in request payload (/api/lca/factors/index or /api/lca/factors/search), the backend is strict and returns an error when that store is unavailable/misconfigured.
• If vector_store is omitted and defaulted from env (LCA_VECTOR_STORE), optional-store availability/config errors (501/502) automatically fall back to mongo for reliability.

Run

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn server:app --reload --port 8000

API

• GET /api/ health-ish ping
• POST /api/ingestion-jobs/upload (multipart file; optional column_map JSON form field)
• GET /api/ingestion-jobs list recent jobs
• GET /api/ingestion-jobs/{job_id} job detail/status
• GET /api/ingestion-jobs/{job_id}/preview?limit=25&offset=0 paged preview
• POST /api/lca/ingest PRD-aligned alias of upload
• POST /api/lca/compute create inventory_items (maps to mock factors + deterministic emissions + DQS)
• GET /api/lca/inventory?job_id=... paged inventory ledger
• GET /api/lca/hotspots?job_id=... vendor pareto (by emissions by default)
• GET /api/lca/gaps?job_id=... high-impact, low-DQS items (emissions by default)
• GET /api/lca/summary?job_id=... last run summary
• GET /api/lca/runs?job_id=... list run history (append-only)
• GET /api/lca/summary/as-of?job_id=...&run_id=... immutable replay totals for a run
• POST /api/lca/period/close close a period (blocks recompute unless force=true)
• GET /api/lca/inventory/versions?job_id=...&ledger_key=... version history for a ledger row
• GET /api/lca/overrides?job_id=... list factor override requests
• POST /api/lca/overrides/create create a pending factor override request
• POST /api/lca/overrides/review approve/reject an override (applies to current view)
• POST /api/lca/adjustments/create create an adjustment restatement for a ledger row
• GET /api/lca/adjustments?job_id=... list adjustments
• POST /api/lca/factors/search factor search (regex/semantic)
• POST /api/lca/factors/seed seed a small mock EF library (only if empty)
• POST /api/lca/factors/import import a packaged EF catalog
• POST /api/lca/factors/index build local semantic index
• POST /api/lca/primary-data/upsert add supplier-specific PCF (upgrades methodology)
• POST /api/material-iros/upsert upsert material IRO
• GET /api/material-iros?job_id=... list material IROs
• POST /api/fx-rates/upsert upsert FX rate
• GET /api/fx-rates?... get FX rate

Frontend (React 19 + shadcn/ui)

Env

Create frontend/.env:

REACT_APP_BACKEND_URL=http://localhost:8000

Run

cd frontend
yarn
yarn start

Flow

1. Open http://localhost:3000/ingest
2. Upload a CSV or XLSX with required headers: vendor, description, spend, currency
3. You’ll be routed to /jobs/:jobId for preview; click Compute LCA to populate emissions + DQS + hotspots/gaps