README.md

metadata

title: GreenProof Verification
emoji: 🌳
colorFrom: green
colorTo: gray
sdk: docker
app_port: 7860
pinned: false

GreenProof verification service

Scores a tree check-in and writes back a confidence, a verdict and a per-signal breakdown. The only server-side surface in the stack.

Why this exists

Everything else in GreenProof is Supabase called directly from the browser. This service exists for one reason: a client-computed verification result is forgeable. The anon key ships inside the PWA and must be assumed public, so confidence, verdict and signals are not granted to authenticated at the column level. This process holds the only key that can write them.

POST /score takes an id and nothing else. Every input is re-read from the database and from storage — a caller can ask for a check-in to be scored, but can never influence what the score is.

Endpoints

Method	Path	Purpose
GET	/health	liveness, model-loaded, config present
POST	/score	score one check-in — {"checkin_id": "..."}
POST	/advise	species + care advice — advisory, never a verdict
POST	/backfill?limit=50	score everything still pending
GET	/docs	interactive OpenAPI

/advise is the only endpoint that is not verification. It writes species_guess and advice and cannot touch confidence, verdict or signals — enforced by column grants, and by pipeline.py never importing the advisor. It is also the only endpoint that spends money (~3 cents a call), which is why it can be locked behind ADVISE_TOKEN.

How a check-in is judged

Stage 1 — gates. Disqualifying on their own, run before any scoring.

Gate	Catches
duplicate image (pHash)	resubmitted photo, gallery photo, internet photo
GPS radius	right tree, wrong place
travel speed	one account submitting from two impossible places

Stage 2 — scores. Continuous 0–1 signals, weighted into a confidence.

Score	Signal
location	distance from the registered point
liveness	excess-green vegetation fraction
scene match	DINOv2 cosine + ORB/RANSAC inliers vs previous visits
growth	canopy and trunk plausibility, not measurement

Five of the six fraud types in our attack set are caught in stage 1 by ordinary deterministic code. That is the honest reason the system works, and it is why overall accuracy is much better than the 54% rank-1 of image matching alone.

Honest limits

• Image matching is corroboration, not identity. Measured on our own 15 plants: rank-1 54% against 5% chance, AUC 0.77 — real signal, nowhere near enough to authorise a payout. It is bimodal: near-perfect on distinctive trees, near-zero inside a dense same-species stand.
• Wide-shot matching works partly off the background, not the tree.
• Young bark is smooth; BarkNet's ~94% figures are on mature bark.
• Thresholds and weights in scoring.py are provisional. They are replaced by weights fitted under leave-one-tree-out cross-validation once real rounds exist. Nothing is tuned on the data used to report performance.
• A missing signal lowers confidence and routes to a human. It never counts as zero, and it never fails closed on a genuine visit. Designed to degrade.

Configuration

Space → Settings → Variables and secrets:

Name	Kind	Value
SUPABASE_URL	variable	your project URL
SUPABASE_SERVICE_KEY	secret	the service_role key
GEMINI_API_KEY	secret	for /advise — free tier, the default provider
ANTHROPIC_API_KEY	secret	alternative provider, used only if no Gemini key
ADVISOR_PROVIDER	variable	optional: pin to gemini or anthropic
ADVISE_TOKEN	secret	any random string; required in X-Advise-Token on /advise
ALLOWED_ORIGINS	variable	your Vercel URL

The service key must never appear in the frontend. It can write any verdict for any tree, and it is the value the whole security model rests on.

Two providers, one interface. Advice runs on Gemini's free tier by default, and falls back to Anthropic if only that key is present. Free tiers have closed under this project three times mid-build, so a second provider is the cheapest insurance against a fourth — and switching is one environment variable, not a code change.

Setting neither is a supported state, not a failure: /score is unaffected and /advise returns {"written": false}. The advisory layer fails soft by design so it can never take verification down with it.

ADVISE_TOKEN matters on a public Space. Without it, anyone who finds this URL and a valid check-in id can spend your Anthropic credit three cents at a time. /score needs no such lock: it costs only our own CPU.

Local run

cd ml
pip install -r requirements.txt
export SUPABASE_URL=... SUPABASE_SERVICE_KEY=...
uvicorn app:app --reload --port 7860