Sentient: Bengaluru Road Risk Intelligence

Sentient is an end-to-end geospatial ML system that predicts road infrastructure risk for Bengaluru from satellite and environmental stress signals, then surfaces actionable road-level prioritization via API and dashboard.

Why this project exists

City teams need to answer:

• Which specific roads should we inspect first?
• Which zones are accumulating infrastructure stress?
• How do we turn raw satellite layers into defensible maintenance priorities?

Sentient addresses this with a reproducible data-to-decision pipeline.

Core capabilities

• Multi-source ingestion: Sentinel-1/2, Landsat, ERA5, Nightlights, Population, OSM.
• Monthly stress feature engineering on a city grid.
• Dual-model strategy:
  • CNN-temporal primary model.
  • Tabular fallback model.
• Road-level ranking and map geometry output (road_risk_ranking.json).
• FastAPI endpoints for metadata, rankings, heatmaps, and roads.
• Streamlit dashboard for decision-oriented visualization.

Project structure

sentient/
  config/                  # pipeline config
  data/
    raw/                   # raw ingested data
    processed/             # monthly processed outputs
    features/              # model datasets and stats
    results/               # rankings, evaluation, manifests
  models/                  # trained models and metrics
  scripts/                 # run scripts and smoke checks
  src/
    ingestion/             # source-specific ingestors
    preprocessing/         # validation and monthly stress
    features/              # dataset and road-risk builders
    training/              # model training entrypoints
    inference/             # scoring modules
    evaluation/            # evaluation logic
    api/                   # FastAPI service
    frontend/              # Streamlit dashboard
  docs/                    # section-wise project docs
  mkdocs.yml               # docs site config (Material UI)

Quick start

1) Install dependencies

python -m pip install -r requirements.txt

2) Run full pipeline

powershell -ExecutionPolicy Bypass -File scripts/run_pipeline.ps1 -ConfigPath "config/pipeline.bengaluru.2020_2024.json" -ModelTrack both

3) Run API

powershell -ExecutionPolicy Bypass -File scripts/run_api.ps1

4) Run frontend

powershell -ExecutionPolicy Bypass -File scripts/run_frontend.ps1

Documentation (modern UI)

Full docs are in docs/ and configured with MkDocs Material.

Install docs tooling:

python -m pip install mkdocs mkdocs-material

Run docs locally:

mkdocs serve

Open http://127.0.0.1:8000.

API endpoints

• GET /metadata
• GET /risk/latest
• GET /risk/ranking
• GET /risk/by_zone
• GET /risk/heatmap
• GET /risk/roads

Main outputs

• data/results/risk_scores.parquet
• data/results/risk_scores_cnn_temporal.parquet
• data/results/road_risk_ranking.json
• data/results/evaluation.json
• data/results/data_inventory_manifest.json

Runbook

Detailed operational commands and stage-by-stage execution:

• RUNBOOK.md