Skip to content
AquaLens
Start monitoring

Changelog

What changed, when.

v1.0.0

2026-05-16

Initial release

Production-grade rewrite. Real Sentinel-2 retrieval via Microsoft Planetary Computer, six band-math indices over an NDWI ∧ MNDWI water mask, deterministic risk scoring, Gemini 2.5 Flash narrative grounded in the numbers, branded WeasyPrint PDF reports, and a polished Next.js 15 frontend.

Pipeline

  • Real Sentinel-2 L2A retrieval via Microsoft Planetary Computer STAC; signed COG reads with native-resolution alignment for the mixed 10 m / 20 m bands.
  • Six band-math indices (NDWI · MNDWI · NDTI · NDCI · NDVI · WRI), masked-mean aggregated over the water polygon.
  • Combined NDWI ∧ MNDWI water mask (Xu 2006) — defeats the well-known NDWI-only false positive over vegetation.
  • Deterministic weighted risk model with bounded field-evidence bonus; numeric band is auditable, unit-tested, and never moved by the LLM.
  • Gemini 2.5 Flash narrative bound to the deterministic numbers; automatic fallback to a second API key on quota / 429 errors; deterministic fallback for offline CI.
  • Land-vs-water sanity check classifies every AOI as water · mixed · land and surfaces a prominent banner + LLM disclosure when the AOI isn't a water body.

Agent layer

  • Coordinator (Gemini thinking mode) plans a workflow over four specialist agents and adapts to whether the water body has prior history.
  • Scout uses Gemini function calling + multimodal vision on the real Sentinel-2 RGB thumbnail; re-queries STAC with a tighter cloud bound when Vision flags haze over the AOI.
  • Historian combines Google Search grounding, URL Context, code execution (Mann-Kendall trend significance) and long-context history into a single briefing the Analyst quotes verbatim.
  • Analyst drafts the narrative, runs a self-critique pass against the hard rules, and rewrites once when the critique rejects the draft.
  • Reporter turns the multi-agent outputs into a structured citizen summary card (tone, guidance, limitations, and citations).
  • Full per-session execution captured in agent_traces (JSONB) and surfaced in the Agent Trace UI card and the PDF appendix.
  • AQUALENS_AGENTIC_MODE flag preserves the single-call deterministic narrative path for CI and offline runs.

Memory & adaptation

  • agent_memory table persists Historian-distilled notes per water body across sessions — the literal 'manages multi-step tasks over time' criterion.
  • text-embedding-004 vectors stored on each note (768 dims); pgvector(768) + HNSW cosine index on Postgres for fast semantic recall.
  • Soft-archives older notes past 50 active rows per water body so recall queries stay focused on recent context.
  • Same recall code path runs on SQLite (tests) and Postgres (production) — pgvector just makes it faster at scale.

Frontend

  • Next.js 15 app router, Tailwind 4, TypeScript strict mode.
  • Custom shadcn primitives hand-tuned to OKLCH design tokens, dark and light themes.
  • MapLibre map with street · satellite · terrain basemaps (collapsible switcher), Nominatim place search, decimal-coords input, click-to-pin AOI.
  • Animated hero, command palette (Ctrl K / Cmd K), motion system with `prefers-reduced-motion` support.
  • Session detail page with synced index charts, animated risk badge, evidence timeline, AOI banner, and live processing skeletons.
  • Mobile-first field-evidence companion form with EXIF-stripped photo upload and one-tap GPS capture.
  • Water-bodies library with rename + cascading delete and per-AOI session history with index trends.

Reporting

  • WeasyPrint + Jinja2 PDF reports with embedded matplotlib SVG charts.
  • Three-column risk row (pill ‖ score ‖ urgency) with page-break-safe glossary.
  • PDF re-renders on every download so template fixes ship instantly to existing sessions.
  • Banner above the risk card when the AOI is mostly land — matches the in-app warning.

Platform

  • FastAPI 0.115 backend with SQLModel, Alembic migrations, BackgroundTasks.
  • PostgreSQL 16 + PostGIS in production, SQLite for tests via the same SQLModel metadata.
  • Two Alembic migrations: 0001_initial bootstraps the schema; 0002_aoi_type adds the water-fraction / AOI-type classifier fields.
  • GitHub Actions CI running ruff, black, pytest, vitest, typecheck, eslint, stylelint, and a Playwright E2E job against the compose stack.
  • Docker Compose for local dev, Render Blueprint for the backend, vercel.json for the frontend.

Licensing & docs

  • Code and documentation licensed under MIT.
  • NOTICE.md catalogues every third-party Python and Node dependency plus the data sources.
  • COMMERCIAL_LICENSE.md clarifies that MIT already permits commercial use.
  • Methodology, risk model, API contract, user manual, and frontend design notes shipped under docs/.