Aquarys

Trust-aware environmental intelligence for urban streams and river restoration governance. Uses OneAquaHealth API to get AI insights into streams!

Comment

AQUARYS

Trust-aware environmental intelligence for urban streams and river restoration governance.

Inspiration

Urban streams are degrading worldwide, yet environmental decisions about them rely on fragmented, inconsistent, and unverified observations from dozens of sources — citizen scientists, sensors, satellites, and government agencies. We kept asking: how do you know this observation is trustworthy? Which other stream went through the same thing, and what happened next? What should we observe tomorrow to learn the most?

No existing tool answered those questions. Environmental dashboards show data; they don't interrogate evidence. AQUARYS was born from the conviction that environmental intelligence must start with whether the evidence deserves to be believed — and end with what to observe next.

What It Does

AQUARYS turns uncertain environmental observations into traceable, actionable knowledge through a closed-loop evidence pipeline:

  1. Evidence Passport (X-RAY) — Evaluates each observation across seven trust dimensions (completeness, consistency, geospatial validity, temporal validity, image support, cross-observer agreement, independent corroboration). Every score is explained, never a black-box number.

  2. Stream Fingerprint — Builds an 8-axis ecological profile for each monitoring site: water quality, habitat structure, vegetation, hydromorphology, biotics, nutrients, Earth Observation signals, and citizen observations. Missing data is tracked separately from zero.

  3. Ecological Twins — Discovers comparable streams using composite similarity scoring across vector distance, structured features, temporal alignment, data coverage, and evidence confidence — not just nearest-neighbour search.

  4. Oracle Investigation — An evidence-grounded AI reasoning layer that establishes facts, finds analogues, generates hypotheses, checks counter-evidence, and identifies knowledge gaps. The Oracle never invents data; every claim traces to a source record.

  5. Skeptic Challenge — An adversarial review engine that challenges Oracle conclusions with alternative explanations, counter-evidence, and remaining uncertainties.

  6. Evidence Graph — A navigable provenance graph linking claims to observations, measurements, EO signals, and sites through typed edges (supports, contradicts, derived_from, correlates).

  7. Knowledge Gaps — Explicitly identifies what is unknown and quantifies which observation would reduce uncertainty the most using information-gain estimation.

  8. Mission Control — Optimizes volunteer data-collection assignments given an objective (e.g., reduce uncertainty), volunteer count, available time, and candidate sites. Shows expected information gain and coverage improvement.

  9. FHIR Export — Exports evidence bundles as interoperable FHIR resources for integration with health and environmental data systems.

How We Built It

We started from the product loop — Evidence → Trust → Twins → Reasoning → Uncertainty → Next Evidence — and built each engine as an independent service connected through a shared data layer.

Backend-first development: The Trust Fabric, Fingerprint Builder, Twin Engine, Oracle, Skeptic, Evidence Graph, Mission Optimizer, and FHIR Exporter were each built and integration-tested before any frontend work. Every service operates deterministically in demo mode so the product survives API outages, LLM rate limits, and cold starts during live judging.

Data ingestion pipeline: We built a resilient ingestion layer that fetches from the OneAquaHealth (OAH) API, stores raw payloads with content hashes, normalizes across heterogeneous schemas (sites, observations, measurements, EO data), and preserves full provenance (source, endpoint, retrieval timestamp, processing version).

Frontend as scientific instrument: Every screen was designed to feel like premium scientific software — clean visual hierarchy, smooth transitions, and responsive layouts — while exposing the underlying evidence chain. MapLibre renders site geography, React Flow visualizes evidence graphs, and Recharts displays fingerprint comparisons.

Oracle grounding: The AI layer synthesizes retrieved facts; it never generates them. We built a structured tool-use pipeline where the Oracle retrieves observation sets, evaluates evidence, searches stream profiles, compares trajectories, and explicitly labels each output as FACT, HYPOTHESIS, COUNTER-EVIDENCE, UNCERTAINTY, or DATA GAP.

Tech Stack

Frontend:

  • Next.js 16 (React 19, Turbopack)
  • TypeScript
  • Tailwind CSS 4
  • TanStack Query
  • MapLibre GL (geospatial visualization)
  • React Flow / XYFlow (evidence graphs)
  • Recharts (fingerprint and comparison charts)
  • Framer Motion (transitions)
  • Lucide (icons)
  • Zod (runtime validation)

Backend:

  • FastAPI (Python 3.12)
  • SQLAlchemy 2 + Alembic (async ORM and migrations)
  • Pydantic 2 (schemas and settings)
  • NumPy, Pandas, SciPy, scikit-learn (analytics and similarity scoring)
  • Shapely + GeoAlchemy2 (geospatial operations)
  • SQLite/aiosqlite for demo, PostgreSQL + PostGIS + pgvector for production
  • HTTPX + Tenacity (resilient API ingestion)

AI / Oracle:

  • Multi-provider abstraction: Gemini (free tier), Ollama (local), deterministic demo fallback
  • Structured tool-use pipeline with evidence grounding
  • No LangChain — direct provider integration

Tooling:

  • uv (Python package management)
  • Ruff (linting)
  • pytest + pytest-asyncio (backend testing)
  • ESLint (frontend linting)

Challenges We Ran Into

OAH API unavailability. The OneAquaHealth API was not reliably accessible during development. As a workaround, we built a comprehensive mock/demo system: a snapshot ingestion pipeline that caches real API responses as local JSON payloads, a deterministic demo Oracle provider that returns structured investigation results without requiring a live LLM, and an APP_MODE=demo flag that makes the entire application fully functional without any external API dependency. This turned out to be an architectural strength — AQUARYS survives any upstream outage during live demonstration.

Trust scoring without ground truth. There is no labeled dataset of "trustworthy" vs. "untrustworthy" stream observations. We designed a transparent, multi-dimensional scoring system where each dimension (completeness, consistency, geospatial, temporal, cross-observer, corroboration) is independently calculable from observable properties — no ML black box, every score is explainable.

Ecological twin matching beyond vector similarity. Simple embedding distance misses temporal alignment and evidence confidence. We built a composite scoring system that weights vector similarity, structured feature overlap, temporal coverage, and data quality — so a twin match means something ecologically meaningful, not just geometrically close.

Making AI claims traceable. LLMs hallucinate. We constrained the Oracle to synthesize only from retrieved evidence, built the Evidence Graph to make every claim clickable back to its source, and added the Skeptic engine to adversarially challenge conclusions before presenting them.

Balancing scientific rigor with demo polish. Environmental science demands hedged language ("evidence suggests," "associated factor," "insufficient evidence") while hackathon demos demand clear, impressive outputs. We maintained scientific language throughout while designing the UI to make the rigor visually compelling rather than dry.

Accomplishments That We're Proud Of

  • Complete closed-loop product: from raw observation to trust evaluation to twin discovery to AI investigation to skeptical challenge to knowledge gaps to optimized mission assignment — every step feeds the next.

  • Zero external dependency for demo: the entire product runs locally with APP_MODE=demo using cached data and deterministic responses. No API keys, no database server, no LLM required.

  • Evidence provenance at every layer: raw payload hashes, source endpoint tracking, processing versions, and a navigable Evidence Graph that traces any Oracle claim back to its source observation.

  • Scientific integrity preserved: no invented data, no unexplained scores, no causal claims from correlations, explicit knowledge gaps, and adversarial self-challenge built into the reasoning pipeline.

What We Learned

  • Mock systems are not shortcuts — they are architecture. Building the demo fallback forced cleaner abstractions (provider interfaces, snapshot ingestion, deterministic outputs) that made the real system more robust.

  • Trust is multi-dimensional. A single "confidence score" hides too much. Decomposing trust into independent, explainable dimensions made the system both more useful and more honest.

  • The hardest AI problem is knowing when not to generate. Constraining the Oracle to synthesize rather than generate, and building the Skeptic to challenge rather than confirm, required more engineering than the generation itself.

  • Information gain drives better fieldwork. Estimating which observation would reduce uncertainty the most transforms volunteer coordination from "go observe anywhere" to scientifically optimized resource allocation.

  • Environmental data is messy by nature. Heterogeneous schemas, missing fields, inconsistent units, spatial imprecision, and temporal gaps are not bugs to fix — they are the fundamental reality to model explicitly.

What's Next

  • Live OAH integration — Connect to the full OneAquaHealth API for real-time data ingestion across the European monitoring network once API access is stable.

  • Enhanced Oracle — Add retrieval-augmented generation with scientific literature, historical restoration case studies, and regulatory datasets to ground investigations in broader knowledge.

  • Temporal trajectory analysis — Track how stream fingerprints evolve over time and use twin trajectory comparisons to predict recovery outcomes.

  • Mobile mission app — A companion field app for volunteers executing missions, with GPS-guided task navigation and immediate observation upload.

  • Multi-language support — Localize for the European monitoring communities contributing to OAH.

Try It

Prerequisites

  • Node.js 18+
  • Python 3.12+
  • uv (Python package manager)

1. Clone and configure

git clone https://github.com/LemonDrop847/aquarys.git
cd aquarys

Create .env in the root:

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_DEMO_MODE=true

Create backend/.env:

DATABASE_URL=sqlite+aiosqlite:///aquarys.db
OAH_BASE_URL=https://api.enora-oah.eu
OAH_API_KEY=
APP_MODE=demo
LLM_PROVIDER=demo
CORS_ORIGINS=http://localhost:3000

2. Start the backend

cd backend
python -m uv sync
python -m uv run uvicorn aquarys.main:app --reload --port 8000

3. Start the frontend

# From project root
npm install
npm run dev

4. Run

Visit http://localhost:3000

The application runs fully in demo mode — no external APIs or API keys required.

Or, Visit the deployed Instance with the mock backend on https://aquarys.vercel.app/

Built With

Share this project:

Updates

Submission history