CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file. Format follows Keep a Changelog; versioning follows Semantic Versioning.

---

[1.0.0] — 2026-05-11

The first complete release. Engineering-grade hardening across backend, ML pipeline, frontend, and DevOps; the rule engine is fully aligned with the D5 thesis proposal §3.7 / P4.

Added — Backend

• Request-ID middleware that stamps every response with X-Request-ID and X-Response-Time-ms. Incoming X-Request-ID headers propagate end to end, enabling cross-service tracing.
• Centralised error contract (backend/errors.py) — every non-2xx response is a typed ErrorResponse { error, detail, request_id, context } JSON document; no bare 500-HTML responses leak.
• Structured logging with per-request log records (request_id field on every line, ISO-8601 timestamps).
• Enriched /api/health reporting uptime, cache row counts (live / expired / total), DB size, and inference-log size.
• /api/version endpoint returning version + git short SHA + ML feature schema.
• Cache hygiene — prune_expired() runs on startup, sweeps inference-log rows older than 7 days, and cache_stats() is exposed via /api/health.
• Fire-and-forget cache writes with the task reference retained (asyncio.create_task lint compliance).
• Defensive ML engine — predict_rain_probability always returns float ∈ [0, 1]; NaN/Inf/wrong-type feature values gracefully degrade; model-load failures fall through to the heuristic instead of crashing.
• Improved heuristic fallback — now also responds to pressure_change_3h so the "no model yet" demo still behaves sensibly.
• Terrain edge cases — antimeridian wrap, polar clamp, ocean / no-data DEM cells handled instead of raising obscure type errors.

Added — Rule Engine (already shipped, now fully tested)

• 4 sub-hazard scorers — rainfall / fog / wind gust / thunderstorm.
• D5 §3.7.2 R1-R4 Decision Table.
• Activity-aware weighted composite (hiker | driver | construction | general).
• Dominant-hazard composite formula: 0.80·max + 0.20·mean(rest).

Added — ML pipeline

• scripts/4_evaluate_model.py generating publication-quality figures (ROC + AUC, PR + AP, calibration / Brier, threshold sweep, top-20 feature importance, confusion matrix at F2-optimal threshold).
• figures/evaluation_summary.json machine-readable evaluation blob for the thesis appendix.
• figures/threshold_sweep.csv for full reproducibility of the precision-recall trade-off table.
• models/MODEL_CARD.md — HuggingFace-style model card with intended use, training data, evaluation, limitations, and ethical considerations.

Added — Tests

• HTTP integration tests with respx-mocked external APIs (tests/test_api.py): happy path, cache hit, distinct cache slot per activity, invalid input → 422, upstream failure → 502, CORS, OpenAPI schema.
• Cache layer tests (tests/test_cache.py): TTL, expiry, prune, stats.
• Terrain edge-case tests (tests/test_terrain_edge.py): antimeridian, polar clamp, malformed DEM.
• ML engine tests (tests/test_ml_engine.py): unloaded behaviour, heuristic monotonicity, NaN/None resilience.
• Session-scoped conftest.py sets an isolated MICROCLIMATEX_DB for every test run (no clobbering the dev cache).
• Total: 70 tests; backend coverage 97 %.

Added — Frontend

• Activity selector (Hiker / Driver / Construction / General) with localStorage persistence and keyboard accessibility (aria-pressed
  • focus-visible).
• 4 mini-gauges for the per-hazard sub-scores, each with a tooltip explaining what drives it.
• D5 §3.7.2 R1-R4 indicator badges (highlight when fired).
• Demo scenarios dropdown (Genting · Cameron · Kinabalu · Everest · Singapore).
• Loading spinner during in-flight requests.
• Toast notification for errors and "no model loaded" warnings.
• Map layer switcher — Dark base + Topographic option.
• Bilingual EN/ZH UI persisted across reloads.

Added — DevOps / Reproducibility

• GitHub Actions CI (.github/workflows/ci.yml) — pytest matrix on Python 3.9 / 3.11 / 3.12, ruff lint, coverage XML artefact, plus a Docker image-build smoke test with Buildx + GHA cache.
• Multi-stage Dockerfile — builder stage for wheels, slim runtime with a non-root mcx user, baked-in HEALTHCHECK against /api/health.
• docker-compose.yml with a named data volume.
• Makefile — single-word recipes for install, test, lint, run, synth, preprocess, train, evaluate, docker, clean.
• requirements-dev.txt — split dev tooling (pytest-cov, ruff, respx, matplotlib) from runtime requirements.
• pyproject.toml — ruff configuration + pytest config.
• .pre-commit-config.yaml — trailing-whitespace, end-of-file, YAML/JSON/TOML checks, large-file guard, ruff lint + format.
• .dockerignore keeping the image lean.

Added — Documentation

• docs/architecture.md — P4.1 → P4.6 internal flow + dominant-hazard formula rationale.
• docs/thresholds.md — every threshold cited; new §8-§12 for the four hazard categories, R1-R4 table, and activity-weight matrix.
• docs/dataset.md — formal target definition (is_rain_event) and train/test split rationale.

Changed

• Rainfall sub-scorer calibration — 45 % macro probability now lands at ~ 40 (Caution band), matching the proposal's intent.
• Composite-score formula switched from naive arithmetic mean to dominant-hazard + secondary to avoid mean dilution.
• Cache key now incorporates activity — different weights → different composite → must not share a slot.

Fixed

• tenacity.RetryError from the retry decorator was not caught by the except httpx.HTTPError clause, producing a misleading 500. Now caught alongside httpx.HTTPError and ValueError, returning a clean 502.

---

[0.2.0] — 2026-05-11

Initial D5-alignment pass — see commit 55fd759.

[0.1.0] — 2026-05-11

Project scaffolding and Hybrid Engine v1 — see commits b218f5b through 4639890.