decoding…
decoding…
CitySutra AI is a neighborhood-level environmental operations prototype. It combines grid-scale air and weather data with reported incidents to produce one explainable prioritization score — the Civic Action Priority (0–100). That score is an operational triage number. It is not an official AQI, a medical-risk score, a government warning, or a scientifically validated prediction. Nothing here makes medical diagnoses or personalized health claims.
The whole model is deterministic: identical inputs always produce identical scores. There is no opaque “AI prediction” layer, and Amazon Bedrock is not required for core operation (an optional future enhancement only).
| Source | Used for | Standard / caveats | Link |
|---|---|---|---|
| Open-Meteo Air Quality API | PM2.5, PM10, US AQI, NO₂, O₃ (hourly) — no EU AQI series offered by the provider | Grid product, ≈15–25 km resolution. An hourly grid assimilation/forecast — never a street sensor. | open-meteo docs |
| Open-Meteo Forecast API | Temp, apparent temp, humidity, precipitation, probability, wind | Grid forecast. Probabilities are model probabilities, not official alerts. | open-meteo docs |
| CPCB National AQI (reference only) | Official Indian AQI definition | CitySutra does <b>not</b> compute CPCB NAQI (its pollutant sub-indices, units and averaging windows are not satisfied by grid data) and never relabels the US AQI as NAQI. | CPCB AQI PDF |
| Delhi Jal Board (reference only) | Water complaint routing | No live integration exists — the app never files complaints or claims one was filed. | Jal Board complaints |
| OpenStreetMap | Map basemap | Tile usage policy applies; attribution shown on the map. | OSM |
Open-Meteo grid products resolve at roughly 15–25 km. Values are area-scale forecasts/assimilations, not street-level sensor readings. When a provider is unreachable the UI shows an explicit “unavailable” state with the failure reason — it never substitutes a fake or relabeled value.
With past_days=1the most recent completed hour comes from the provider's analysis/assimilation and future hours from forecast. Both are labeled in the UI (“grid forecast” / “latest grid value”); neither is presented as a point measurement. The dashboard shows the observation timestamp, the fetch time, the provider and the standard for every value.
Four dimensions are normalized to 0–100 with documented, configurable transformations. Weights are applied only over dimensions that have valid data and are renormalized — missing data is never treated as zero, and if no dimension is available the UI shows “insufficient data” instead of a score.
| Dimension | Weight | Transform | Basis |
|---|---|---|---|
| A · Air | 30% | A = clamp(AQI, 0, 100) | Latest reported US AQI from Open-Meteo's air-quality product (the provider does not offer an EU AQI series). Already an index on 0–100+, so A = clamp(AQI, 0, 100). This is NOT India's CPCB National AQI. |
| H · Heat | 25% | apparent °C: ≤32→0, ≥42→100 (linear) | Linear map of apparent temperature: ≤32 °C → 0, ≥42 °C → 100. A configurable operational assumption, not an official heat alert. |
| W · Water | 20% | 0.7·(rain 6h/25 mm) + 0.3·(max probability) | Rainfall pressure for the next 6 h: 70% weight on depth (25 mm → 100) + 30% on max precipitation probability. Configurable assumption. |
| G · Ground | 25% | Σ severity × 12 over active waste incidents (cap 100) | Derived from active waste-track incidents: Σ severity × 12, capped at 100. A city-wide proxy for waste pressure, not a measured field condition. |
score = min(100, Σ (wᵢ / Σw) · valueᵢ + Σ triggered interaction bonuses)
| Rule | Bonus | Condition |
|---|---|---|
| R-01 | +10 | An active open-burning / smoke report is present while the selected AQI reads ≥ 100 (US AQI 'Unhealthy' band). |
| R-02 | +10 | An active blocked-drain, waterlogging or flooding-risk report is present and ≥ 10 mm rain (or ≥ 60 % probability) is forecast within 6 hours. |
| R-03 | +8 | Heat dimension ≥ 70 while an active water-leak / cooling-resource report is present. |
| R-04 | +5 | Waste dimension ≥ 60 with at least 2 active collection-related incidents (overflow, missed collection, accumulation). |
Bonuses are capped so the final score never exceeds 100, and a bonus only attaches to an action when allof that rule's incident evidence is part of the action's evidence set — so every +N point is traceable.
| Factor | Default | Meaning |
|---|---|---|
| CO₂e per t organic diverted | 0.0545 t CO2e/t | Simplified IPCC-style default for diversion from unmanaged disposal (CH₄ LHV-based). Illustrative. |
| CO₂e per collection-km | 0.35 kg/km | Assumed small truck, loaded + return. User-editable. |
| Biodigester yield | 100 kWh/t wet | Optional scenario only — off unless entered. |
| Water tariff | ₹65/kL | Illustrative municipal tariff for the monetary line. |
All calculator outputs are estimates / scenarios with ±25 % sensitivity bands. No measured methane reduction, energy production or CO₂ savings are claimed.
Incidents carry evidenceType (citizen / sensor / official / simulated), confidence (low / medium / high), source name, timestamps and a demo flag. All seeded records are explicitly labeled DEMO and never described as detected hotspots.
Local mode persists to a local Postgres database (clearly labeled in the header). In AWS mode the same repository contract is implemented on DynamoDB behind API Gateway + Lambda (see aws/ and the README). Provider calls use finite timeouts, response validation, a 5-minute cache, and honest error/stale states.
Every number in the UI is backed by a machine-readable methodology endpoint — GET /api/methodology — returning the exact weights, thresholds, rules and sources. Snapshot, incidents and actions are all available via the documented API (see README). If you find a wrong value or an unclear assumption, note the route, timestamp and value, and raise it in the project issue tracker referenced in the README.
| Service | Role in CitySutra AI | Where |
|---|---|---|
| Amazon S3 | Environmental datasets, weather exports and evidence files (private bucket, SSE, 90-day lifecycle for evidence/) | aws/template.yaml · POST /evidence on the Lambda API |
| AWS Lambda | Serverless processing: incident CRUD, deterministic risk analysis (POST /risk-snapshot), evidence ingestion | aws/lambda/handler.mjs |
| Amazon API Gateway | Exposes the backend APIs with basic request throttling | aws/template.yaml (HTTP API, /{proxy+}) |
| Amazon DynamoDB | Incident records, action decisions, and ALERT records holding computed risk indicators | citysutra-<env> table + statusIndex GSI |
| Amazon CloudWatch | Lambda/API logs, error & throttle metrics, and the citysutra-<env> dashboard | LoggingConfig + dashboard resource in the template |
| Amazon Bedrock (optional) | Plain-English explanations of prioritized actions. OFF by default; the deterministic template is the source of truth and every explanation is labeled by engine | BEDROCK_ENABLED flag · “AI explain” on action cards |
AWS SDK for JavaScript v3 is used server-side only; credentials come from execution roles / environment and are never placed in NEXT_PUBLIC_* variables or source. AWS SAM (not CDK) is used for infrastructure as code. In local demo mode these services are not contacted — the app clearly labels itself “Local demo DB” and disables S3-backed photo upload.
| Endpoint | What it returns | Notes |
|---|---|---|
| GET /api/health | db ok, backend mode, time | used by the header mode chip |
| GET /api/snapshot | full cross-track snapshot (dims, score, actions) | lat/lon/demoAir params |
| GET /api/incidents | list with track/status/q/limit filters | Zod-validated query |
| POST /api/incidents | creates an incident (201) | 422 on validation failure; throttled |
| PATCH /api/incidents/{id} | lifecycle transition | 409 on impossible jump; reject needs a reason |
| GET /api/actions · PATCH /api/actions/{id} | recomputed queue / operator decision | decisions persist in the action ledger |
| GET /api/providers/air · /weather | raw provider result incl. ok:false | honest failure states, 5-min cache |
| GET /api/methodology | this page's data, machine-readable | weights, thresholds, rules, sources |
| POST /api/demo/reset | reseed the labeled demo dataset | returns the seed count |
| POST /api/explain | action explanation | Amazon Bedrock if BEDROCK_ENABLED, else labeled deterministic template |
The standalone Lambda backend additionally serves POST /risk-snapshot (serverless risk analysis → DynamoDB ALERT record) and POST /evidence (S3 evidence upload) for operators scripting against the raw API.
| Term | Meaning here |
|---|---|
| Grid product | Model output on a ~15–25 km lattice; an area-scale estimate, never a street sensor reading. |
| Assimilation vs forecast | Past/current hours come from data assimilation of the model state; future hours are pure forecast. Both labeled in the UI. |
| US AQI | US EPA index (0–500) as provided by the provider. Shown as-is; not converted, not CPCB NAQI. |
| Interaction rule | A bounded, explicitly defined bonus (R-01…R-04) that fires only when both its data condition and its incident evidence are present. |
| Renormalisation | When a dimension is missing, its weight is redistributed over the available dimensions instead of being treated as zero. |
| Action ledger | Persistent store of operator decisions (accepted/dismissed) on generated actions — workspace only. |
| DEMO record | A seeded sample incident, always badged; used for reproducible demonstration, never presented as detected reality. |