Upload folder using huggingface_hub

README.md

@@ -26,6 +26,8 @@ Adapter status:
 
 - Public adapter repo: this repository
 - Base model: `LiquidAI/LFM2.5-VL-450M`
+- Inference engine: Hugging Face Transformers
+- Adapter loader: PEFT
 - Runtime adapter variable: `HF_ADAPTER_ID=akashreddy2103/landfill`
 - Adapter files: `adapter_config.json`, `adapter_model.safetensors`
 - Latest run id: `lora_run_20260504T181913Z`
@@ -65,9 +67,10 @@ docker compose --env-file .env.local -f docker-compose.landfillsentry.yml up --b
 Verified live smoke:
 
 - site: `LF_REAL_007`
-- scan: `scan_082`
-- incident: `inc_082`
+- scan: `scan_083`
+- incident: `inc_083`
 - inference mode: `live`
+- inference tooling: Hugging Face Transformers + PEFT
 
 ## Limitations
 

architecture_for_judges.md

@@ -0,0 +1,52 @@
+# Architecture Brief For Judges
+
+## End-to-End Flow
+
+1. Site selected from watchlist (`/watchlist`).
+2. Backend fetches imagery bundle:
+- Sentinel current at selected landfill coordinates (`/data/current/image/sentinel` via DPhi SimSat),
+- Sentinel historical (`/data/image/sentinel` via SimSat),
+- Mapbox context at selected landfill coordinates (`/data/current/image/mapbox` via DPhi SimSat).
+3. Candidate engine proposes likely methane-risk zone.
+4. Evidence panel builder assembles current, spectral, temporal, and context views.
+5. LFM2.5-VL (`LiquidAI/LFM2.5-VL-450M`) runs through Hugging Face Transformers with the PEFT LoRA adapter (`akashreddy2103/landfill`) and produces structured incident output.
+6. Output validation enforces schema and normalization.
+7. Incident + scan + evidence metadata are persisted.
+8. Operator reviews and exports evidence.
+
+## Live Reliability Controls
+
+- `REQUIRE_LIVE_RESULTS=true` blocks non-live runtime modes.
+- `INFERENCE_ALLOW_FALLBACK=false` prevents fallback from being shown as live.
+- watchlist/site detail strict selector only surfaces live-generated incidents in judge mode.
+- `scripts/live_smoke.py` verifies SimSat/API health, live scan success, previews, review persistence, and export.
+
+## Provenance Contract
+
+Every scan evidence payload stores:
+- `imagery_provenance.source_chain`,
+- per-asset timestamps and source metadata,
+- `live_fetch_status`,
+- `inference.mode`.
+
+This is exposed in:
+- `/sites/{site_id}/detail`,
+- `/scans/{scan_id}/evidence`,
+- `/incidents/{incident_id}/export`.
+
+## Dongle Corroboration Loop
+
+- API supports field methane ingestion:
+  - `POST /sites/{site_id}/dongle-readings`
+  - `GET /sites/{site_id}/dongle-readings`
+- Latest unlinked dongle reading is attached to newly generated incident as `ground_truth_hint`.
+- UI and export explicitly show `Satellite-only` vs `Satellite + Dongle corroborated`.
+
+## Deployment Notes
+
+- Backend: FastAPI + SQLite
+- Frontend: FastAPI-served ops console at `/ops` (`apps/web/ops.html`, `ops.css`, `ops.js`)
+- Live imagery: DPhi SimSat + Mapbox
+- Inference tooling: Hugging Face Transformers + PEFT
+- Model artifacts: Hugging Face base model + public PEFT adapter
+- Fine-tuning compute: Modal GPU

benchmark_summary_for_submission.md

@@ -1,6 +1,6 @@
 # Benchmark Summary For Submission
 
-Date: May 4, 2026
+Date: May 5, 2026
 
 ## Goal
 
@@ -62,7 +62,7 @@ Copy reviewed rows to `data/labels/manual_label_corrections.csv`, then rebuild/t
 
 5. Save the latest successful live scan artifact:
 ```bash
-python scripts/save_live_scan_artifact.py --api-base-url http://127.0.0.1:8000 --scan-id scan_082
+python scripts/save_live_scan_artifact.py --api-base-url http://127.0.0.1:8000 --scan-id scan_083
 ```
 
 6. Modal fine-tune:
@@ -84,14 +84,14 @@ Generated proof:
 Result from the latest run:
 - status: `PASS`
 - site: `LF_REAL_007`
-- scan: `scan_082`
-- incident: `inc_082`
+- scan: `scan_083`
+- incident: `inc_083`
 - inference mode: `live`
 - previews present: `current_rgb`, `spectral_composite`, `temporal_diff`, `mapbox_context`
 
 The same scan is archived at:
 - `docs/latest_live_scan_artifact.md`
-- `data/processed/judge_live_artifacts/scan_082.json`
+- `data/processed/judge_live_artifacts/scan_083.json`
 
 ## Modal LoRA Run
 

demo_script.md

@@ -0,0 +1,63 @@
+# LandfillSentry Judge Demo Script (5 Minutes)
+
+Date: May 5, 2026  
+Audience: Hackathon judges
+
+## 1) Problem Framing (30s)
+
+Landfill teams do not need another generic map. They need a clear answer to: "Where do we inspect first, and why?"  
+LandfillSentry turns satellite evidence into a reviewable incident object with operational follow-up guidance.
+
+## 2) Live Scan Walkthrough (90s)
+
+1. Open `http://127.0.0.1:8000/ops`.
+2. Select one watchlist site.
+3. Click `Scan Site` or `Scan Watchlist`.
+4. Explain:
+- `generation mode` shows `live`.
+- imagery is fetched from DPhi SimSat coordinate endpoints for Sentinel current, Sentinel historical, and Mapbox context.
+- current endpoints are `/data/current/image/sentinel` and `/data/current/image/mapbox`; historical Sentinel uses `/data/image/sentinel`.
+- scan fails fast in judge mode if live dependencies are unavailable.
+
+## 3) Evidence + Review Action (90s)
+
+1. Show `Incident Summary`.
+2. Show `Live Imagery Provenance`:
+- DPhi SimSat provider and repository,
+- `/data/current/image/sentinel`, `/data/image/sentinel`, and `/data/current/image/mapbox` endpoint usage,
+- source chain,
+- capture timestamps,
+- live fetch status.
+3. Review as operator:
+- click `Publish`, `Dismiss`, or `Needs Review`.
+4. Confirm state change in watchlist row.
+
+## 4) Export + Dongle Corroboration (60s)
+
+1. Click `Add Dongle Reading`.
+2. Run scan again.
+3. Show corroboration changing from `Satellite-only` to `Satellite + Dongle corroborated`.
+4. Load markdown export and highlight:
+- data source provenance,
+- ground truth hint,
+- recommended follow-up.
+
+## 5) Architecture + Product Story (60s)
+
+1. Satellite-first triage pipeline:
+- SimSat imagery retrieval,
+- candidate generation and evidence panel,
+- LFM2.5-VL structured reasoning,
+- operator review workflow.
+2. Why this is productizable:
+- clear workflow outcome, not just maps,
+- audit-ready export object,
+- extensible with field dongle ground truth loop.
+
+## Demo Safety Notes
+
+- Run `scripts/start_judge_mode.ps1` before demo.
+- Keep `http://127.0.0.1:9005` DPhi SimSat running.
+- If any live system fails, show deterministic error message (no fake live fallback).
+- Smoke proof: `docs/latest_live_smoke_proof.md` shows scan `scan_083` passed judge-mode checks.
+- Backup artifact: `docs/latest_live_scan_artifact.md` shows scan `scan_083` with strict-live DPhi SimSat provenance.

judge_deployment_runbook.md

@@ -4,6 +4,13 @@
 
 Use Docker for the LandfillSentry API/UI package and keep inference on the existing Hugging Face Transformers + PEFT path.
 
+This is the selected inference tooling for the submission:
+
+- Inference engine: Hugging Face Transformers
+- Adapter loader: PEFT
+- Base model: `LiquidAI/LFM2.5-VL-450M`
+- Public adapter: `akashreddy2103/landfill`
+
 Why this is the safest choice for judging:
 
 - The app already supports `LiquidAI/LFM2.5-VL-450M` through Transformers.
@@ -124,3 +131,4 @@ Use `HF_LOCAL_FILES_ONLY=false` for a clean judge machine so the model can be do
 - `scripts/live_smoke.py` passes.
 - `docs/latest_live_smoke_proof.md` is regenerated after the final run.
 - `docs/benchmark_summary_for_submission.md` includes the public adapter ID, methodology, and measured base-vs-tuned delta.
+- `/runtime/status` reports `inference_tooling=Hugging Face Transformers + PEFT`.

judge_submission_brief.md

@@ -0,0 +1,88 @@
+# Judge Submission Brief
+
+Date: May 5, 2026
+
+## One-Sentence Pitch
+
+LandfillSentry turns DPhi SimSat satellite imagery and LFM2.5-VL reasoning into a live operations console for landfill methane/plume incident triage, evidence review, and export.
+
+## Chosen Inference Tooling
+
+LandfillSentry uses Hugging Face Transformers as the LFM2.5-VL inference engine and PEFT for LoRA adapter loading.
+
+- Base model: `LiquidAI/LFM2.5-VL-450M`
+- Adapter: `akashreddy2103/landfill`
+- Runtime path: `apps/api/services/inference_service.py`
+- Strict judge mode: `INFERENCE_MODE=live`, `INFERENCE_ALLOW_FALLBACK=false`
+
+llama.cpp, MLX, and ONNX are not used in this submission because the validated live path is Transformers + PEFT.
+
+## Judging Criteria Alignment
+
+| Criterion | Weight | Evidence in Project | Status |
+|---|---:|---|---|
+| Use of Satellite Imagery | 10% | DPhi SimSat is the primary live imagery provider. Runtime status, evidence metadata, and UI provenance show the provider, repo, endpoints, timestamps, and cloud cover. | Strong |
+| Innovation and Problem-Solution Fit | 35% | The workflow targets a specific operational problem: deciding which landfill site needs inspection first and why. It combines satellite evidence, model reasoning, plume polygons, triage, and exportable incident records. | Strong |
+| Technical Implementation | 35% | FastAPI backend, SQLite persistence, DPhi SimSat live imagery, Hugging Face Transformers + PEFT LFM2.5-VL inference path, strict-live failure behavior, SSE scan progress, map overlays, evidence packs, tests, and run docs. | Strong |
+| Demo and Communication | 20% | Demo script, architecture brief, live runbook, saved live artifact, and benchmark summary are included. | Strong |
+
+## What To Show In The Demo
+
+1. Open `http://127.0.0.1:8000/ops`.
+2. Show `/runtime/status` or the UI live state: `DPhi SimSat`, `strict_live`, `simsat_reachable: true`.
+3. Select `Belvedere Landfill London` or another watchlist site.
+4. Show the `Live Imagery Provenance` card:
+   - provider: DPhi SimSat,
+   - repo: `https://github.com/DPhi-Space/SimSat`,
+   - endpoints: `/data/current/image/sentinel`, `/data/image/sentinel`, `/data/current/image/mapbox`,
+   - asset timestamps and cloud cover,
+   - inference mode/model.
+5. Click `Scan Site` if live dependencies are available.
+6. Show the incident summary, plume/map overlays, evidence images, review action, and export.
+7. Open `docs/latest_live_scan_artifact.md` as the saved backup proof.
+
+## Live Proof Artifacts
+
+- Live scan artifact markdown: `docs/latest_live_scan_artifact.md`
+- Live scan artifact JSON: `data/processed/judge_live_artifacts/scan_083.json`
+- Live smoke proof: `docs/latest_live_smoke_proof.md`
+- Benchmark table: `docs/benchmark_summary_for_submission.md`
+- Architecture brief: `docs/architecture_for_judges.md`
+- Demo script: `docs/demo_script.md`
+- DPhi SimSat runbook: `docs/run_demo_dphi_simsat.md`
+
+## Run Commands
+
+Start DPhi SimSat:
+
+```powershell
+cd external\SimSat
+docker compose up --build
+```
+
+If Docker is unavailable on Windows but dependencies are installed, run the SimSat API directly:
+
+```powershell
+.\.venv\Scripts\python.exe -m uvicorn api:api --host 127.0.0.1 --port 9005
+```
+
+from `external\SimSat\src\sim`.
+
+Start LandfillSentry:
+
+```powershell
+.\.venv\Scripts\python.exe -m uvicorn apps.api.main:app --host 127.0.0.1 --port 8000
+```
+
+Verify:
+
+```powershell
+.\.venv\Scripts\python.exe scripts\live_smoke.py --api-base-url http://127.0.0.1:8000 --simsat-base-url http://127.0.0.1:9005
+.\.venv\Scripts\python.exe scripts\save_live_scan_artifact.py --api-base-url http://127.0.0.1:8000 --scan-id scan_083
+```
+
+## Honest Notes
+
+- Strict live mode is intentional: if DPhi SimSat or live inference is unavailable, the scan fails instead of showing mock output as live.
+- The public adapter path is trained, uploaded, wired, and benchmarked. The current report shows validation-loss improvement plus a measured lift on a small domain-adaptation fixture proxy; larger fully manual labels are still needed for a stronger production-quality model claim. This is documented in `docs/benchmark_summary_for_submission.md`.
+- Cached evidence remains visible for operator review, but newly triggered judge-mode scans require live dependencies.

latest_live_scan_artifact.md

@@ -1,6 +1,6 @@
 # Live Scan Artifact
 
-Generated: 2026-05-04T18:51:58+00:00
+Generated: 2026-05-05T06:09:08+00:00
 
 ## Runtime
 
@@ -9,13 +9,13 @@ Generated: 2026-05-04T18:51:58+00:00
 - SimSat reachable: True
 - Live scan available: True
 - Scan policy: strict_live
-- SimSat base URL: http://simsat-api:8000
+- SimSat base URL: http://localhost:9005
 
 ## Scan
 
 - Site: LF_REAL_007
-- Scan ID: scan_082
-- Incident ID: inc_082
+- Scan ID: scan_083
+- Incident ID: inc_083
 - Status: live
 - Inference mode: live
 - Model: LiquidAI/LFM2.5-VL-450M@main+adapter=akashreddy2103/landfill@main
@@ -44,6 +44,6 @@ Endpoints:
 
 | Asset | Source | Captured | Cloud Cover | Local Path |
 |---|---|---|---:|---|
-| sentinel_current | dphi-simsat | 2026-05-03T10:36:59+00:00 | 0.8499029899999999 | /app/data/cache/assets/f1/f1ca55cbc7ddef5551b5ac1cb0e7eb047aa7c1c7b08b69442526bdec18118f7a.img |
-| sentinel_historical | dphi-simsat | 2026-04-26T10:46:55+00:00 | 0.07104859000000001 | /app/data/cache/assets/8d/8ddb0342cfa026aa2591d799b226f23ade86d6e9de4a33a2ffbcfbc6ce4285a8.img |
-| mapbox_context | mapbox | 2026-05-04T18:23:52+00:00 | 0.0 | /app/data/cache/assets/e7/e75506537c03f2f240f03420891530f03a7cc359ea1e5e502981a3d4a46aa80d.img |
+| sentinel_current | dphi-simsat | 2026-05-03T10:36:59+00:00 | 0.8499029899999999 | data/cache/assets/f1/f1ca55cbc7ddef5551b5ac1cb0e7eb047aa7c1c7b08b69442526bdec18118f7a.img |
+| sentinel_historical | dphi-simsat | 2026-04-26T10:46:55+00:00 | 0.07104859000000001 | data/cache/assets/8d/8ddb0342cfa026aa2591d799b226f23ade86d6e9de4a33a2ffbcfbc6ce4285a8.img |
+| mapbox_context | mapbox | 2026-05-05T06:07:47+00:00 | 0.0 | data/cache/assets/e7/e75506537c03f2f240f03420891530f03a7cc359ea1e5e502981a3d4a46aa80d.img |

latest_live_smoke_proof.md

@@ -1,6 +1,6 @@
 # Live Smoke Proof
 
-Generated: 2026-05-04T18:27:09+00:00
+Generated: 2026-05-05T06:09:00+00:00
 
 ## Command
 
@@ -12,8 +12,8 @@ python scripts/live_smoke.py --api-base-url http://127.0.0.1:8000 --simsat-base-
 
 - Status: PASS
 - Site: LF_REAL_007
-- Scan ID: scan_082
-- Incident ID: inc_082
+- Scan ID: scan_083
+- Incident ID: inc_083
 - Inference mode: live
 - Panel preview keys: current_rgb, spectral_composite, temporal_diff, mapbox_context
 

run_demo_dphi_simsat.md

@@ -0,0 +1,84 @@
+# DPhi SimSat Live Demo Runbook
+
+Use this path for the hackathon judging demo. It keeps the app on live DPhi SimSat imagery and live inference, with no mock/sample scan output presented as real.
+
+## 1. Start DPhi SimSat
+
+The hackathon-provided imagery backend is:
+
+`https://github.com/DPhi-Space/SimSat`
+
+This repository includes a local copy under `external/SimSat`.
+
+```powershell
+cd external\SimSat
+docker compose up --build
+```
+
+Confirm the SimSat API is available on:
+
+`http://localhost:9005`
+
+Required API paths:
+
+- `GET /data/current/image/sentinel`
+- `GET /data/image/sentinel`
+- `GET /data/current/image/mapbox`
+- `GET /data/image/mapbox`
+
+LandfillSentry scans watchlist sites through the coordinate-based DPhi SimSat endpoints, so the selected landfill coordinates are passed directly to `/data/current/image/sentinel`, `/data/image/sentinel`, and `/data/current/image/mapbox`.
+
+## 2. Configure LandfillSentry
+
+In `.env.local`, use live/strict settings:
+
+```env
+SIMSAT_MODE=live
+MAPBOX_MODE=live
+INFERENCE_MODE=live
+REQUIRE_LIVE_RESULTS=true
+INFERENCE_ALLOW_FALLBACK=false
+SIMSAT_BASE_URL=http://localhost:9005
+SIMSAT_USE_FOR_MAPBOX=true
+```
+
+Add the real tokens required by your local environment, for example `HF_TOKEN` and Mapbox credentials.
+
+## 3. Start the app
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/start_judge_mode.ps1 -RestartApi
+```
+
+Open:
+
+`http://127.0.0.1:8000/ops`
+
+## 4. Judge Verification
+
+These endpoints should all respond from the running app:
+
+- `GET /runtime/status`
+- `GET /ops/summary`
+- `GET /overlays/plumes`
+
+`/runtime/status` should show:
+
+- `imagery_provider`: `DPhi SimSat`
+- `imagery_provider_repository`: `https://github.com/DPhi-Space/SimSat`
+- `simsat_required_endpoints`: the Sentinel and Mapbox endpoint list
+- `scan_policy`: `strict_live`
+
+If DPhi SimSat or live inference is unavailable, scans fail with an actionable error instead of silently substituting mock/sample data.
+
+## 5. Saved Proof
+
+The smoke command writes:
+
+- `docs/latest_live_smoke_proof.md`
+- `data/processed/live_smoke_proof.json`
+
+The latest archived scan proof is:
+
+- `docs/latest_live_scan_artifact.md`
+- `data/processed/judge_live_artifacts/scan_083.json`