Confluence — Unified Environmental Intelligence API

A normalized API and platform that concurrently aggregates 50+ physical, marine, and atmospheric hyperparameters across 7 free public data sources into a single validated JSON snapshot — then connects those raw numbers into physics-informed composite signals (heat index, sea state, storm potential, coastal flood risk) and a config-driven alerting layer, backed by persisted history across a multi-location registry.

Built to ground frontier AI models and maritime decision systems in empirical, real-time physical truth — reducing weather hallucinations and enabling operational safety advisories that cite verified observations instead of training-data priors.

Current status: Full Stack Intelligence Platform. Real-time telemetry, 24h trends, multi-location registry, rules engine, Argon2id developer authentication, Model Context Protocol (MCP) server, and grounded LLM chatbot are live.

Live service
Highlights
AI Agent & MCP Integration (Claude & Cursor)
Data sources
Why this matters
Quickstart
Project structure
API reference
Phase 2: history, trends & alerting
Phase 3: grounded coastal AI chatbot
Authentication & developer API keys
Testing
Deployment
Limitations & production readiness
Documentation
License

Live service

Base URL: https://confluence-si41.onrender.com
Interactive docs (Swagger): /docs
Health probe: /health
Sample query: /environment?lat=13.08&lon=80.27&name=Chennai%20Coast
Interactive Chat: /chat

Highlights

50+ hyperparameters across 7 free APIs — atmospheric weather, sea-state hydrodynamics, dual-tier air quality, solar/nautical twilight ephemeris, topography/elevation, climate baselines, and recent seismic events.
Concurrent fan-out — all 7 upstream sources are dispatched simultaneously via ThreadPoolExecutor, bounding total latency to the single slowest source (~2.4s) rather than the sum of all seven (~10s).
Two-tier caching — a 24h station-metadata cache eliminates redundant spatial discovery, and a 5-minute response cache serves repeated queries in well under a millisecond (bypass_cache=true to force a fresh fetch).
Data-quality sentinel — every response is checked against physical boundaries (no negative wave heights, no >100% humidity, no out-of-range pressure) before it's returned.
Production-hardened — tiered rate limiting (slowapi), global exception handlers preventing stack trace leakage, structured request logging, and CI gates on every push.
Physics-informed reasoning layer — composite signals (heat index, sea state, storm potential, coastal flood risk, tsunami advisory) computed from cited meteorological/oceanographic standards, plus a config-driven alerting engine.
Pluggable, verified storage — SQLite by default, with MongoDB Atlas as the production durable backend, verified against real running clusters.
Native Model Context Protocol (MCP) — official confluence-mcp package for Claude Desktop and Cursor agent tool-use.
Developer API Key & Auth Lifecycle — Argon2id password hashing, session tokens, and developer API key lifecycle (conf_live_...) with tiered quotas.

AI Agent & MCP Integration (Claude Desktop & Cursor)

Confluence provides an official Model Context Protocol (MCP) server (packages/confluence-mcp) enabling Claude Desktop, Cursor, and enterprise AI agents to query live coastal sensor telemetry and physics derivations directly with a single configuration block:

Claude Desktop Configuration

Add to claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "confluence-mcp"],
      "env": {
        "CONFLUENCE_API_KEY": "conf_live_YOUR_API_KEY",
        "CONFLUENCE_API_URL": "https://confluence-si41.onrender.com"
      }
    }
  }
}

Cursor Configuration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "confluence-mcp"],
      "env": {
        "CONFLUENCE_API_KEY": "conf_live_YOUR_API_KEY"
      }
    }
  }
}

Exposed MCP Capabilities

Tools:
- get_coastal_snapshot: 7-in-1 real-time telemetry + NOAA Heat Index, WMO Beaufort force, small craft advisories, and storm surge.
- get_preset_locations: Validated coastal observatories (Chennai, Mumbai, Kochi, Visakhapatnam, Kolkata/Sundarbans).
- check_coastal_alerts: Threshold breaches, cyclone depressions, and hazard advisories.
- get_historical_trends: 24-hour physical deltas (temperature, pressure fall, wave height, wind).
- ask_coastal_assistant: Sensor-grounded natural language maritime guidance.
Resources: confluence://locations and confluence://methodology.
Prompts: coastal-safety-audit and cyclone-readiness-check.

Data sources

Domain	Service	Access	Hyperparameters
Weather & atmosphere	Open-Meteo Forecast	Free, no key	`temperature_c`, `apparent_temperature_c`, `wind_speed_kmh`, `wind_gusts_kmh`, `wind_direction_deg`, `humidity_pct`, `pressure_hpa`, `surface_pressure_hpa`, `precipitation_mm`, `cloud_cover_pct`, `uv_index`, `visibility_m`, `weather_code` (WMO), `weather_description`, `is_day`
Ocean hydrodynamics	Open-Meteo Marine	Free, no key	`sea_surface_temp_c`, `wave_height_m`, `wave_period_s`, `wave_direction_deg`, `wind_wave_height_m`, `wind_wave_period_s`, `wind_wave_direction_deg`, `swell_wave_height_m`, `swell_wave_period_s`, `swell_wave_direction_deg`, `ocean_current_velocity_kmh`, `ocean_current_direction_deg`
Air quality & chemistry	OpenAQ + Open-Meteo fallback	Free tier / free, no key	`pm25`, `pm10`, `o3`, `no2`, `so2`, `co`, `aqi_category` (EPA), `us_aqi`, `european_aqi`, `dust_ug_m3`, `aerosol_optical_depth`, `tier` (`ground_sensor` or `atmospheric_model`)
Astronomical & marine lighting	Sunrise-Sunset.org	Free, no key	`sunrise`, `sunset`, `solar_noon`, `day_length_hours`, civil/nautical/astronomical twilight begin/end
Topography & elevation	Open-Meteo Elevation	Free, no key	`elevation_m`, `coastal_risk_category` (`low-lying (<5m)` vs `elevated`)
Climate baseline	NASA POWER	Free, no key	`solar_radiation_kwh_m2`, `avg_temperature_c`, `avg_wind_speed_ms`, `observed_at`
Seismic & tsunami risk	USGS Earthquakes	Free, no key	`recent_events_7d_count`, `max_magnitude`, `max_magnitude_depth_km`, `hazard_level`, `search_radius_km`

Why this matters

Frontier LLMs asked operational coastal questions without grounding either hallucinate seasonal stereotypes or admit total blindness. A unified, verified snapshot changes that:

Scenario	Raw observations	Ungrounded response	Grounded response
Dry heat spike	35.4°C, 47% RH, 0.0mm rain, 0.76m swell	Guesses monsoon downpours and high waves from static regional priors	Safe for 2–3hr artisanal fishing; mandates hourly hydration breaks given heat index
Monsoon squall	26.2°C, 94% RH, 54mm rain, 42.5 km/h wind, 2.85m waves, 998 hPa	Gives generic advice, unaware of current wave height or squall status	"Wind (23kt) and wave height (2.85m) exceed safe limits for artisanal boats. Stay in port. Secure moorings."
Winter stagnation + pollution surge	31.0°C, calm sea (0.42m wave), PM2.5 = 168.4 µg/m³ (very unhealthy)	Fails to detect air stagnation; advises a beach stroll	Sea is safe to launch, but mandates N95 masks on deck; reschedules outdoor labor to dawn/dusk

Quickstart

1. Clone and install

git clone https://github.com/csharikrishna/Confluence.git
cd Confluence
python -m venv venv

# Windows
.\venv\Scripts\activate
# Linux / macOS
source venv/bin/activate

pip install -r requirements.txt

2. Configure environment

cp .env.example .env

At minimum, set OPENAQ_API_KEY (free from openaq.org). Optional keys include NVIDIA_API_KEY (for the grounded chatbot), MONGODB_URI (for durable Atlas storage), and ALERT_WEBHOOK_URL (for Discord/Slack alerts).

3. Run the dev server

uvicorn app:app --host 127.0.0.1 --port 8000 --reload

Interactive API Docs (Swagger): http://127.0.0.1:8000/docs
Web Interface: http://127.0.0.1:8000/

Project structure

Confluence/
├── app.py                    # Root gateway & backward-compatible uvicorn proxy
├── backend/                  # Clean backend service package
│   ├── __init__.py           # Package initialization & path resolution
│   ├── app.py                # FastAPI routes, lifespan, middleware & static mounts
│   ├── auth.py               # Argon2id password hashing, sessions & API key auth
│   ├── chat.py / chatbot.py  # Grounded LLM reasoning & safety audit prompt builder
│   ├── environmental_data.py # 7-source concurrent ingestion pipeline & normalizers
│   ├── derived_insights.py   # Physics signals (Heat Index, Beaufort, small craft)
│   ├── rules_engine.py       # Config-driven hazard evaluation engine
│   ├── alert_rules.json      # Threshold and trend condition definitions
│   ├── locations.py / .json  # 5 registered coastal stations registry
│   ├── notifications.py      # Slack/Discord webhook dispatcher
│   ├── gdrive_backup.py      # Daily disaster-recovery snapshot exporter
│   ├── db_backend.py         # Storage router (SQLite / MongoDB Atlas)
│   ├── storage.py            # SQLite local persistence & trend diffs
│   ├── mongo_storage.py      # MongoDB Atlas durable production backend
│   ├── upstream_health.py    # Upstream API latency & SLA monitor
│   └── utils.py              # Dotted-path dictionary traversal helper
├── frontend/                 # React + Vite interactive coastal UI
├── packages/
│   └── confluence-mcp/       # Official Model Context Protocol (MCP) server
├── tests/                    # Complete pytest suite (194 tests)
├── scripts/                  # Empirical RAG benchmarks, stress testing, PoCs
├── docs/                     # Design specs, walkthroughs, benchmark rubrics
├── static/                   # Benchmark results and media assets
├── render.yaml & Procfile    # Render blueprint deployment configs
└── requirements*.txt         # Base, mongo, gdrive, and benchmark dependencies

API reference

Core Environmental Telemetry

`GET /environment`

Fetches the normalized, multi-domain environmental snapshot for any coordinates.

Parameter	Type	Required	Description
`lat`	`float`	Yes	Latitude, `-90.0` to `90.0`
`lon`	`float`	Yes	Longitude, `-180.0` to `180.0`
`name`	`string`	No	Optional human-readable label
`timeout`	`float`	No	Per-source timeout in seconds (default `10.0`)
`bypass_cache`	`bool`	No	Force fresh fetch, skipping the 5-minute cache

`GET /environment/history`

Query persisted snapshot history for a location:

GET /environment/history?lat=13.08&lon=80.27&start=2026-09-01T00:00:00Z&end=2026-09-03T00:00:00Z&field=weather.temperature_c

`GET /locations`

Lists every coastal point tracked by the platform for pre-warming and alerting.

`GET /alerts`

Evaluates the rules engine against all registered locations or a specific lat/lon.

`GET /health`

Returns service status, rate limiting, caching state, and storage backend connectivity.

`GET /api/health/upstream`

Pings all 7 upstream sources concurrently and returns live status, HTTP code, and latency in milliseconds.

Authentication & Developer Keys

Method	Endpoint	Description	Auth Required
`POST`	`/api/auth/register`	Register new user account (Argon2id)	No
`POST`	`/api/auth/login`	Login and receive bearer token	No
`GET`	`/api/auth/me`	Fetch active user profile	Yes (Bearer)
`POST`	`/api/auth/keys`	Generate new developer API key (`conf_live_...`)	Yes (Bearer)
`GET`	`/api/auth/keys`	List active developer API keys	Yes (Bearer)
`DELETE`	`/api/auth/keys/{prefix}`	Revoke an API key	Yes (Bearer)
`POST`	`/api/auth/keys/rotate`	Zero-downtime key rotation	Yes (Bearer)

Grounded Coastal AI Chatbot

`POST /ask`

Natural language coastal intelligence query. Grounded directly in live telemetry:

{
  "question": "Can artisanal fishermen launch near Chennai right now?",
  "location": "Chennai Coast"
}

`GET /chat`

Renders the dedicated coastal chatbot interface.

Phase 2 — History, Trends & Alerting

Physics-informed derived insights

Every /environment response includes meta.derived_insights — composite signals computed from the raw hyperparameters using cited, published physical standards, not a learned model:

Field	Combines	Standard
`heat_index_c` / `heat_index_category`	Temperature + humidity	NOAA/Rothfusz heat index regression, with published low/high-humidity corrections
`dew_point_c` / `fog_risk`	Temperature + humidity + wind	Magnus-Tetens approximation
`beaufort_scale`	Wind speed	WMO-adopted Beaufort scale (force 0–12)
`imd_cyclone_category`	Sustained wind speed	India Meteorological Department official classification
`small_craft_risk_level`	Wave height + wind + gusts	NWS coastal marine warning tiers (Small Craft Advisory → Hurricane Force)
`storm_potential_score` / `_level`	Pressure + gusts + cloud cover + 3h pressure trend	Engineering heuristic
`rapid_pressure_fall`	24h pressure change, latitude-normalized	Bergeron / Sanders-Gyakum rapid-cyclogenesis criterion
`air_stagnation_index`	Wind + precipitation + PM2.5	Engineering heuristic
`coastal_flood_risk`	Elevation + wave height + wind + inverse-barometer surge	Inverse barometer effect (~1cm sea-level rise per 1hPa deficit)
`tsunami_advisory`	Seismic magnitude + depth + elevation	USGS shallow-focus (<70km) criterion

Full citations and scope notes: backend/derived_insights.py.

Config-driven alerting

A config-driven rules engine (backend/alert_rules.json) evaluates threshold and trend conditions over both raw and derived fields, against every registered location or a single lat/lon.

Triggered alerts are deduped per rule/location on a 60-minute cooldown and optionally dispatched to Slack/Discord via ALERT_WEBHOOK_URL.

Phase 3 — Grounded Coastal AI Chatbot

Confluence incorporates a strict grounding prompt architecture that forces frontier LLMs (such as NVIDIA Nemotron or Llama 3) to base all claims exclusively on verified observational JSON data:

Rejects hallucinated regional priors if live data is unavailable.
Injects exact sensor values (e.g. wave height, PM2.5, heat index, wind velocity).
Produces concrete, actionable safety advisories for fishermen, coastal residents, and harbor masters.

Authentication & Developer API Keys

Confluence features a dual-tier consumption model:

Anonymous Tier: Public access to /environment and /alerts, rate-limited to 30 requests/minute per IP.
Authenticated Tier: Passing an X-API-Key: conf_live_... header unlocks higher capacity (100 requests/minute per key), dedicated quotas, and access to developer endpoints.

Passwords are cryptographically secured using Argon2id, and API keys use high-entropy secrets with SHA-256 hash storage.

Testing

The project maintains a rigorous 194-test automated test suite:

Offline unit & mocked integration suite (190 tests)

Covers boundary sanity checks, ISO-UTC normalization, coordinate validation, failure degradation, physics calculations, rules engine scenarios, dual storage backends, Argon2id auth, and grounded prompt schemas.

pytest tests/ --ignore=tests/test_live_remote.py -v

Live remote deployment suite (4 tests)

Verifies the deployed service directly — connectivity, CORS, cache hits, 400 handling.

API_BASE_URL="https://confluence-si41.onrender.com" pytest tests/test_live_remote.py -v

Run All Tests

pytest tests/ -v

Deployment

This repository includes a pre-configured render.yaml and Procfile.

Fork or push this repository to GitHub.
In Render, click New → Blueprint and select this repo.
Set OPENAQ_API_KEY (and optionally NVIDIA_API_KEY, MONGODB_URI) in Render's environment settings.
Add your deployed URL to GitHub Secrets as RENDER_APP_URL to enable keep-alive and hourly ingestion cron workflows.

Limitations & production readiness

Documented honestly rather than oversold:

Tiered Quotas vs Public Access: Anonymous access is open and rate-limited to 30 req/min. Authenticated API key quotas require user registration.
Single instance, no SLA: A CI test gate runs on every push, but a dedicated monitor (UptimeRobot, Better Uptime) should be added for production alerting.
Derived signals are correctly cited, not independently certified: Most formulas are real published standards (see table above), but outputs should be treated as strong physical guidance rather than certified regulatory safety authority.
Storage Durability: SQLite on Render's free tier is ephemeral across redeploys; production uses MongoDB Atlas to ensure persistent 24h history and alert records.

Documentation

docs/PHASE2_WALKTHROUGH.md — history, trends, alerting, storage backends, and hardening
docs/phase2-plan.md — Phase 2 design specifications
docs/PHASE3.md — Phase 3 grounded LLM chatbot specifications
docs/phase1-planning-archive.md — historical Phase 1 pilot specification
scripts/run_rag_benchmark.py — empirical scientific RAG benchmark suite

License

MIT License — see LICENSE.

Name		Name	Last commit message	Last commit date
.github		.github
backend		backend
data/rag_corpus		data/rag_corpus
docs		docs
frontend		frontend
packages/confluence-mcp		packages/confluence-mcp
scripts		scripts
static		static
tests		tests
.env.example		.env.example
.gitignore		.gitignore
DESIGN.md		DESIGN.md
LICENSE		LICENSE
Procfile		Procfile
README.md		README.md
app.py		app.py
docker-compose.mongo.yml		docker-compose.mongo.yml
render.yaml		render.yaml
requirements-benchmark.txt		requirements-benchmark.txt
requirements-gdrive.txt		requirements-gdrive.txt
requirements-mongo.txt		requirements-mongo.txt
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

Confluence — Unified Environmental Intelligence API

Contents

Live service

Highlights

AI Agent & MCP Integration (Claude Desktop & Cursor)

Claude Desktop Configuration

Cursor Configuration

Exposed MCP Capabilities

Data sources

Why this matters

Quickstart

1. Clone and install

2. Configure environment

3. Run the dev server

Project structure

API reference

Core Environmental Telemetry

GET /environment

GET /environment/history

GET /locations

GET /alerts

GET /health

GET /api/health/upstream

Authentication & Developer Keys

Grounded Coastal AI Chatbot

POST /ask

GET /chat