v0.1.1 — Portable Demo and Reusable Contracts

v0.1.1 — Portable Demo and Reusable Contracts

MinxiongHydroCast v0.1.1 turns the Minxiong reference implementation into a lighter,
reproducible, contributor-ready official-source hydrometeorological data-quality platform. It
does not expand forecast capability or weaken any observation, model, notification, or publication
gate.

Release date: 2026-08-01

Highlights

• Adds a credential-free docker compose up --build demo with deterministic synthetic
  observations, an operator dashboard, health/readiness endpoints, Prometheus metrics, and an
  intentionally blocked forecast endpoint.
• Reduces the base wheel to NumPy, Pydantic, and Requests; scraping, reporting, and modeling use
  explicit capability extras.
• Replaces more than 30 installed executables with one grouped mhc command while retaining
  transition aliases for legacy command tokens.
• Adds strict packaged region profiles, a non-authoritative Minxiong working boundary, an example
  profile, and profile-driven regional feature coverage.
• Publishes a source-adapter Protocol and shared contract checks for stable source identity,
  adapter version, timezone-aware fetch time, provenance, and SHA-256 integrity.
• Adds contributor guidance, issue forms for bugs/features/source drift, a pull-request template,
  a clean-wheel CI smoke test, and a PyPI Trusted Publishing release workflow.

Verified release evidence

• The deterministic test suite passes for all non-network tests; loopback HTTP behavior was also
  verified through the built Compose stack.
• Ruff, Python compilation, wheel construction, Compose validation, and installed-wheel smoke
  tests pass.
• The installed wheel exposes only mhc and packages both region profiles and their GeoJSON
  boundaries.
• The Compose demo returns /healthz=200, /readyz=503, readiness metric 0, and an unavailable
  experimental forecast, as required for synthetic data.
• The 60-second dashboard walkthrough contains 30 decoder-validated GIF frames.

Install and try the demo

Install the base wheel from PyPI:

python -m pip install "minxiong-hydrocast==0.1.1"
mhc collect --region minxiong --mode demo --once
mhc serve --host 127.0.0.1 --port 8080

Or run the isolated synthetic stack from a source checkout:

docker compose up --build

Live official-source collection still requires locally protected CWA/WRA credentials and the
operational runbook. The Docker demo never contacts live sources.

Upgrade notes

Standalone minxiong-hydrocast-* executables are no longer installed. Use the grouped commands:

Previous executable	v0.1.1 command
minxiong-hydrocast-operations	mhc collect
minxiong-hydrocast-serve	mhc serve
minxiong-hydrocast-dataset-build	mhc dataset build
minxiong-hydrocast-event-discover	mhc event discover
minxiong-hydrocast-event-review	mhc event review
minxiong-hydrocast-evaluate-baselines	mhc model evaluate
minxiong-hydrocast-backup	mhc operations backup

The derived snapshot dataset is now region_features instead of minxiong_features. The generic
API route is /api/v1/features/region; /api/v1/features/minxiong remains as a read-only
compatibility route for this release.

Install optional capabilities only where needed:

python -m pip install "minxiong-hydrocast[scraper]"
python -m pip install "minxiong-hydrocast[model]"
python -m pip install "minxiong-hydrocast[report]"

Safety and research boundary

• Synthetic records remain demo_fixture and cannot satisfy readiness or forecast publication.
• Region-profile geometry states its authority; the Minxiong polygon is an operational working
  bound, not an official administrative boundary.
• Five formal radar events remain insufficient for broad weather-regime claims.
• Persistence remains the mandatory benchmark, and forecast publication remains blocked because
  Tiny U-Net does not consistently pass CSI and lead-time gates.
• This release contains no official raw data, credentials, private event notes, model checkpoint,
  or trained weights.

Next public work

• Optical-flow baseline
• Reviewed weather-regime diversity
• v0.2 dataset-building protocol and event manifest