UrbanLens is a hackathon-origin urban heat investigation system built by a four-person team at the WashU Google Build with AI hackathon.

Users select a satellite region in Google Maps. UrbanLens captures the map image and metadata, runs RGB-to-thermal generation through ThermalGen, proposes heat hotspot candidates, classifies visible surface types, ranks findings with deterministic scoring, and supports grounded follow-up questions over stored analysis artifacts.

UrbanLens is not production environmental measurement software. ThermalGen outputs are relative thermal evidence, not calibrated thermal camera readings. The portfolio signal is the system design: typed contracts, artifact flow, deterministic ranking, model integration, and bounded AI behavior.

• Demo video: YouTube
• Hackathon submission: Devpost
• Docs index: docs/README.md

Select map region
  -> capture satellite image and map metadata
  -> generate relative thermal evidence with ThermalGen
  -> propose candidate heat hotspots
  -> classify visible surface types from RGB crops
  -> compute anomaly, severity, confidence, and rank scores
  -> return prioritized findings and grounded follow-up answers

Select locality	Rank heat findings	Ask grounded follow-up

• Deterministic: capture handling, artifact storage, hotspot proposal, scoring, ranking, debug views, and API response contracts.
• Model-based: ThermalGen generates relative thermal evidence from RGB satellite captures.
• AI-assisted: optional crop classification, explanation wording, and follow-up planning over stored analysis results.
• Bounded: the LLM does not own ranking math, anomaly gates, or final prioritization.

Ranking is intentionally inspectable:

if anomaly_score < anomaly_threshold:
    discard

final_rank_score = severity_score * confidence_score

• Frontend: Next.js, React, TypeScript, Tailwind, and Google Maps region selection.
• Backend: FastAPI, Pydantic contracts, local artifact persistence, ThermalGen integration, scoring/ranking, and planner endpoints.
• ThermalGen: PyTorch RGB-to-thermal generation adapted for urban imagery.
• Planner layer: provider-neutral LLM adapters for grounded follow-up answers over existing analysis results.

See docs/portfolio-architecture.md for the full system diagram and tradeoff discussion.

Fast Windows setup:

copy .env.example .env
notepad .env
.\scripts\dev.ps1

The dev script syncs service env files and launches:

• Backend: http://localhost:8000
• Frontend: http://localhost:3000

Use LLM_PROVIDER=mock for a no-key local demo. For hosted portfolio deployments where AI keys and model checkpoints should not be required, set DEMO_MODE=true; the backend will keep the same API contracts but return deterministic fixture analysis instead of calling live LLMs or ThermalGen.

The live Google Maps UI still needs NEXT_PUBLIC_GOOGLE_MAPS_API_KEY. Full ThermalGen inference needs local checkpoints under:

backend/models/hybrid_thermal/checkpoints/

For setup details and troubleshooting, see docs/local-dev-setup.md.

Hosted portfolio deploys should use DEMO_MODE=true; Railway auto-installs the lightweight backend/requirements.txt. Full local ThermalGen/PyTorch dependencies live in backend/requirements-full.txt.

.\scripts\smoke.ps1

The smoke path runs deterministic backend tests and the demo fixture without Google Maps, ThermalGen checkpoints, or real LLM keys.

Example output artifact:

• docs/examples/demo-analysis-summary.json

UrbanLens was built by:

• @tioluwani-enoch: frontend UI/UX, Google Maps interaction, side panels, and analysis presentation.
• @GALGALLOR: ThermalGen adaptation, RGB/thermal preprocessing, inference integration, and thermal overlay work.
• @shuja-waraich-03: backend setup, agent loop, tool-calling behavior, prompts, and investigation flow.
• @postigodev: analysis contracts, capture/API alignment, deterministic scoring/ranking, provider paths, setup docs, CI, and repo hardening.

For a fuller team-oriented writeup, see docs/team-and-contributions.md.

• Local file storage is used for captures and generated artifacts; production would use object storage and retention/access policies.
• ThermalGen predictions are relative evidence, not calibrated measurements.
• Model checkpoints are large local artifacts and are not committed.
• The system favors a small, explainable pipeline over broad autonomous-agent behavior.
• LLM behavior is bounded to explanation and planning over stored evidence.

UrbanLens is available under the MIT License.