Update README.md

README.md

@@ -1,71 +1,101 @@
 ---
 license: agpl-3.0
+library_name: stable-baselines3
 tags:
-- reinforcement-learning
-- stable-baselines3
-- deep-reinforcement-learning
-- agricultural-ai
-- weather-modelling
-- curriculum-learning
-- edge-ai
+  - deep-reinforcement-learning
+  - agricultural-ai
+  - weather-modelling
+  - curriculum-learning
+  - edge-ai
+pipeline_tag: reinforcement-learning
 ---
 
-# Agricultural Weather-Risk RL — Permutation-Invariant GRU Policy with Curriculum Weight Transfer
+# Agricultural Weather-Risk RL — MaskablePPO + Permutation-Invariant GRU
 
-Core RL components and training infrastructure for a budget-constrained, multi-zone weather-risk inspection task. The system includes a Gymnasium environment, a **permutation-invariant GRU features extractor** that enables weight transfer across curriculum phases with varying numbers of zones, full multi-phase curriculum training, and an export path to quantized MNN for edge deployment.
+Budget-constrained multi-zone weather-risk inspection for Indonesian rice
+zones. A Gymnasium environment tracks per-zone beliefs under a scarce
+inspection budget; a **permutation-invariant GRU** feature extractor supports
+curriculum phases with changing `n_zones`; deterministic crop-risk scoring
+grounds rewards and product alerts. Intended path includes ONNX → MNN export
+for edge inference.
+
+This card describes the training stack and architecture. It is a research
+codebase, not a production alerting service.
 
 ## What is included
 
-- `weather_forecast_env.py` — Gymnasium environment with per-zone belief tracking, action masking, soft reset, and NaN-safe wrapper.
-- `gru_weather_policy.py` — Permutation-invariant GRU features extractor (shared per-zone processing + attention-weighted aggregation + max pooling). Makes the majority of policy parameters independent of `n_zones`.
-- `train_curriculum.py` — 5-phase curriculum trainer (`normal` → `monsoon` → `drought` → `heatwave` → `humidity`) with automatic weight transfer between phases.
-- `crop_risk_scorer.py` — Deterministic, economics-calibrated risk scoring used for both training rewards and evaluation.
-- `climatology.py` + `indonesia_zones.py` — Real per-zone climatology and 14 grounded Indonesian agricultural zones with rice crop calendars.
-- `backtest_indonesia.py` — Historical replay harness with precision/recall and lead-time metrics.
-- `mnn_export.py` + `edge_wrapper.cpp` — ONNX export and C++/Vulkan edge runtime with external GRU hidden-state management.
-- `era5_data_pipeline.py` — Multi-source data pipeline (ERA5 / Open-Meteo / synthetic) with graceful degradation.
+- `weather_forecast_env.py` — Gymnasium env (belief map, action masks, triage/scarce/full budget modes, per-episode zone-order shuffle, real `EpisodeContext` injection)
+- `gru_weather_policy.py` — Permutation-invariant GRU extractor (shared per-zone processing + aggregation; most weights independent of `n_zones`)
+- `train_curriculum.py` / `train_kaggle.py` — Curriculum and standalone training (`--budget-mode triage|scarce|full`)
+- `crop_risk_scorer.py` — Deterministic, economics-calibrated risk scoring
+- `climatology.py` + `indonesia_zones.py` — Per-zone climatology and 14 grounded Indonesian agricultural zones
+- `evaluate_checkpoint_real.py` — Real-trajectory eval (L1 labels, belief Δ, zero_inspect control)
+- `mnn_export.py` + `edge_wrapper.cpp` — ONNX/MNN export and C++ edge runtime with external GRU hidden state
 
-## Key Technical Achievement
+## Key technical note
 
-The central engineering result is a **permutation-invariant, size-independent policy architecture** that solves weight transfer across curriculum phases with changing numbers of zones.
+The GRU extractor is designed so that changing `n_zones` across curriculum
+phases only requires reinitializing the action head; the bulk of the policy
+parameters transfer. That enables multi-phase runs without full restarts when
+entity count changes.
 
-Previous designs tied the GRU input dimension (and all downstream weights) to a fixed `n_zones`, causing observation space mismatches at phase transitions. The new extractor uses:
-- Shared per-zone GRU processing
-- Learned attention + max pooling across the variable zone axis
-- Separate basin-scale context (ENSO, IOD, etc.)
+**Full-tour episode length (`n_zones + 1`) is not evidence of zone-selection
+skill.** Under triage (`max_steps = max(1, n_zones - 1)`), the agent must leave
+at least one zone unvisited. Allocation claims require a triage-trained
+checkpoint evaluated under shuffle, not full-tour belief or length metrics.
 
-This design transfers **61 of 63 parameter tensors** cleanly when `n_zones` changes (only the final action head is reinitialized). Full 5-phase curriculum runs confirm that phases sharing the same `n_zones` inherit competence immediately, while phases after an entity-count change only need to relearn the action head.
+## How to use
 
-## Validation Results
+### Train (triage default)
 
-Full 5-phase curriculum (690k steps) completed successfully on GPU:
+```bash
+python train_kaggle.py \
+  --out ./run_nz2_triage \
+  --n-zones 2 \
+  --budget-mode triage \
+  --steps 100000 \
+  --clean-episode-ratio 0.90 \
+  --event-spatial-correlation 0.85 \
+  --device auto
 
-| Transition              | n_zones change | Tensors transferred | Behavior                     |
-|-------------------------|----------------|---------------------|------------------------------|
-| normal → monsoon        | 2 → 3          | 61/63               | Action head reinitialized    |
-| monsoon → drought       | 3 → 3          | 63/63               | Full transfer                |
-| drought → heatwave      | 3 → 4          | 61/63               | Action head reinitialized    |
-| heatwave → humidity     | 4 → 4          | 63/63               | Full transfer                |
 
-All phases converged to their structural performance ceiling (`n_zones + 1`). Full-transfer phases started at ceiling performance immediately. Explained variance stayed in the healthy 0.6–0.8 range. The entire curriculum finished in ~50 minutes on one T4.
+Load and act
+Pythonfrom sb3_contrib import MaskablePPO
 
-## How to Use
+model = MaskablePPO.load("run_nz2_triage/final_model.zip")
+# obs from WeatherForecastEnv; pass action_masks= for MaskablePPO
+action, _ = model.predict(obs, action_masks=masks, deterministic=True)
+
+
+Edge export (optional)
+Bashpython mnn_export.py \
+  --checkpoint run_nz2_triage/final_model.zip \
+  --output weather_rl_model.mnn \
+  --quantize int8 \
+  --n-zones 2
+Validation (what is and is not shown)
+
+ClaimStatusWeight transfer across n_zones changes (most tensors)Supported by curriculum designFull-tour training converges on length / belief movementObserved on earlier runs; not allocation skillTriage + shuffle avoids fixed physical zone lock-inObserved (slot preference can remain)Risk-conditioned zone choice under triageNot yet demonstratedProduct skill vs curated L1 impact labelsScorer/product path exists; quote only with L1 density caveats
+Synthetic triage EV under current defaults (clean≈0.90, max_steps=1) shows
+only a weak dirty-day advantage for selecting the correct zone; overall return
+still favours always-inspect. Longer training under the same reward does not
+substitute for a stronger selection signal or calibrated clean ratio.
+Limitations
+
+Research stack, not SLA. No on-call, feed uptime, or regulatory certification.
+Synthetic-heavy training. Real claims need held-out product metrics and L1 coverage honesty (unlabeled days excluded from P/R/F1).
+Full-tour ≠ triage. Do not cite full-tour belief_R or ep_len → n_zones+1 as zone-selection skill.
+Triage allocation open. A triage-trained policy under shuffle has not been shown to beat zero_inspect on L1 belief movement and choose zones by contemporaneous risk rather than a fixed action slot.
+Edge path is export-oriented. MNN/C++ wrapper is provided; not validated here as a production edge deployment.
 
-### Training
-```bash
-python train_curriculum.py --phase all --output-dir ./runs --device cuda --seed 42
-Inference (after training)
-Pythonfrom sb3_contrib import MaskablePPO
-model = MaskablePPO.load("runs/humidity/models/final_humidity.zip")
-Edge Export
-Bashpython mnn_export.py --checkpoint runs/humidity/models/final_humidity.zip \
-                     --output weather_rl_model.mnn --quantize int8 --n-zones 4
 Dependencies
+texttorch>=2.0
+gymnasium>=0.29
+stable-baselines3>=2.0
+sb3-contrib>=2.0
+numpy>=1.24
 
-torch >= 2.0
-stable-baselines3 >= 2.0
-sb3-contrib >= 2.0
-gymnasium >= 0.29
-numpy
+GPU recommended for training; CPU is viable for short runs and inference.
 
-GPU recommended for training. The edge runtime (edge_wrapper.cpp) targets Vulkan with CPU fallback.
+License
+AGPL-3.0. See repository for full terms.