Record what was seen.
Never what should be concluded.
StreamVitals is the Field Companion submitted to the OneAquaHealth IEEE Global Hackathon 2026, Track 3. It walks a volunteer through the five official Key Indicators, keeps the observation structured, assesses it with deterministic rules you can audit line by line, and hands a reviewer clean, source-traceable data. Everything on this page can be checked against the repository or the live app.
Why it exists
The OneAquaHealth Key Indicators factsheet tells research teams what to measure. A volunteer standing at a stream on a Saturday morning rarely has it open — and the sheet is written for specialists: Latin names, lab protocols, section numbers.
When the sheet and the sighting do not line up, the free-text note fills the gap: “healthy stream.” That single word is an assessment, not an observation, and it is exactly what makes volunteer data unusable downstream. Most entries to a hackathon answer this by adding more AI on top. We made the assessment itself deterministic instead: rules score the observation, every score carries its chain of evidence, and AI stays at the edges where it explains — never where it judges.
Deterministic rules assess. AI may explain — AI never scores.
Every indicator is a health indicator
Each card quotes the factsheet's own Importance of indicator section, carried verbatim in indicators.json as why_this_matters with its source section named. Nothing was paraphrased or invented.
Benthic Macroinvertebrates
“Healthy macroinvertebrate communities indicate clean water and functioning ecological processes, which are directly linked to human and animal health by supporting safe drinking water sources, fisheries and disease-limiting environments.”
Source: Importance of indicator — II. Benthic Macroinvertebrates — OneAquaHealth Key Indicators Factsheets, doi:10.5281/zenodo.20345207
Birds
“The number of insectivorous bird species between areas differing in degree of urbanisation, and across habitat changes evaluated in long-term monitoring, will elucidate about the resilience of the ecosystem regarding pest control (disease vector mosquitoes, plant pests, etc), and the quality of cultural services that contribute to human well-being.”
Source: Importance of indicator — V. Birds — OneAquaHealth Key Indicators Factsheets, doi:10.5281/zenodo.20345207
Invasive Alien Plants of the Riparian Corridor
“In terms of health impacts, AIPs, particularly angiosperms, are frequently associated with the production of allergenic pollen and toxic compounds, which can cause wounds, skin irritation, allergic reactions and poisoning. Additionally, IAPs may act as mediators of disease vectors (e.g., dipteran vectors, ticks) and allow the occurrence and proliferation of vector-borne diseases.”
Source: Importance of indicator — XI. Invasive Alien Plants of the riparian corridor — OneAquaHealth Key Indicators Factsheets, doi:10.5281/zenodo.20345207
Fecal Coliforms
“Their presence suggests inputs from human or animal waste and therefore a potential exposure to enteric pathogens including pathogenic bacteria, and parasites. This makes them a reliable early warning signal for the potential presence of harmful pathogens such as E. coli O157, Salmonella, or viruses (e.g. norovirus causing gastroenteritis) and parasites associated with gastrointestinal diseases.”
Source: Importance of indicator — VII. Fecal Coliforms — OneAquaHealth Key Indicators Factsheets, doi:10.5281/zenodo.20345207
Diatoms and Diatom Teratology
“Certain diatom species can form harmful algal blooms (HABs) in freshwater environments. These blooms can produce toxins and/or deplete oxygen levels in the water, harm aquatic organisms, leading to fish kills and posing risks to human health through contaminated water or food consumption.”
Source: Importance of indicator — I. Diatoms and diatom teratology — OneAquaHealth Key Indicators Factsheets, doi:10.5281/zenodo.20345207
How a session runs
Name the stream and the volunteer, start a session
Session state persists in the browser (IndexedDB), so a refresh or a dropped connection on an open session does not erase what was recorded. Optionally capture the session's GPS location — it is stored on this device, in the session record and its exports, and it is used to fetch a GBIF occurrence baseline (api.gbif.org) when you reach the review page.
Choose one of the five official indicators
Three are field-observable — BMI-01 Benthic Macroinvertebrates, BIR-04 Birds, INV-11 Invasive Alien Plants. Two are laboratory-only — FCL-06 Fecal Coliforms and DIA-10 Diatoms.
Record what was observed
Each field indicator offers exactly three observation states (nine states in total), plus photo capture and a field note. Lab indicators instead show a sample ID to write on the container and the factsheet's own collection protocol — pending lab analysis stays pending.
The note check runs — deterministic, not AI
Keyword and contradiction rules in src/lib/note-quality.ts flag assessment language ('healthy', 'tier 1', 'score') and notes that contradict the selected state. It warns, never blocks. 'Keep my note anyway' writes a note_flag that travels into the JSON and CSV exports instead of being hidden. Your note stays an observation; the assessment comes from the next step.
The deterministic assessment runs — rules, not a model
streamvitals-assessment/1.0.0 maps the observation state to a band (favorable / moderate / degraded, or pending for lab indicators) and attaches the chain of evidence: the rule that fired, the factsheet passage behind it, and the honesty caveats. The same state always produces the same band. The module never touches the network, the clock, or any AI — tests read its source and fail if it ever does.
Ask the bounded Field Assistant
In-scope protocol questions are answered from the OneAquaHealth factsheet text (Groq, openai/gpt-oss-120b, factsheet injected into the prompt). Meta questions and out-of-scope questions are answered locally with no model call at all. The assistant never scores — for health judgements it points back at the deterministic card.
Review and export
The review page shows exactly what was typed — names, states, notes, sample IDs — plus the session's assessment bands and, when a GPS location was captured, a GBIF baseline of records within 50 km (context only, labelled as such). Exports (CSV, JSON, print, Lab Submission Sheet) carry the bands, the engine version, the chain rule IDs, and the GPS coordinates. A share link (URL fragment + QR) moves the session to another device with no account — photos stay on the device that captured them.
Published numbers
Countable from the repository, not marketing estimates.
The end-to-end smoke test (Playwright) walks the entire session — states, note gate, sample IDs, assistant, export, frequencies — and fails if the review page ever shows data the volunteer did not enter. Screenshots from every run are committed under tests/artifacts/. A second spec scans five routes with axe-core and fails on any critical WCAG A/AA violation (currently zero violations at every impact level); a third cuts the network to prove already-visited pages reload from the service worker while uncached pages get the designed offline screen. The ~1.9 s figure is the median of five live probes against the deployed app on 2 October 2026 (min 1.4 s, max 4.1 s); latency moves with the model provider.
Honest limits
- ×Assessment is deterministic and auditable — but citizen states are tolerance/extent proxies, not laboratory indices: BMWP, IBD and IPS all require taxon-level lab identification (factsheet §§I, II).
- ×English-only UI. The factsheets are multilingual; the interface is not yet.
- ×Offline support is deliberately modest: a service worker lets already-visited pages reload without connectivity (asserted in the end-to-end suite) and shows a designed offline screen for pages that were never visited; the assistant and a first visit to any page still require a connection.
- ×The note-check rules and their tests were written by the same author, so the suite demonstrates self-consistency, not accuracy against a labelled corpus.
- ×Real-camera, real-sunlight readability testing on physical phones is pending; the end-to-end test runs in headless Chromium.
- ×Lab indicators produce no band in the field — a sample ID is not a measurement, and the rules refuse to grade what was not measured.
Evidence you can check
- streamvitals.vercel.app — the deployed app you are reading this from
- /provenance — machine-readable track, DOI, citation, and AI-boundary statement
- doi:10.5281/zenodo.20345207 — the source factsheets (CC-BY 4.0), 14 authors
- github.com/kathir-iTech/streamvitals — run
npm testfor the 95 tests,npm run e2efor the full session walkthrough src/lib/assessment/engine.ts— the whole assessment: rules, chains, caveats. Its test suite reads the source and fails if it ever imports a model, calls the network, or reads the clock.
What comes next
Field pilot
Run the companion beside volunteers at OneAquaHealth research-city streams. The comparison we do not yet have — paper sheet versus phone on the same visit — is the validation this project still owes the framework.
Multilingual volunteer labels
The Key Indicators factsheets exist in several languages; volunteer-facing state labels currently exist in English only.
Pipeline hand-off
CSV/JSON exports already carry indicator IDs, states, notes, note flags, GPS, bands, and rule IDs in a fixed schema; the next step is ingesting them into the OneAquaHealth Citizen Science App pipeline instead of manual review.
Server-side sync
Share links cover device-to-device hand-off today (URL fragment + QR, no account). A real datastore with background replication and conflict handling is the next step — not claimed in this build.