---
license: agpl-3.0
library_name: stable-baselines3
tags:
  - deep-reinforcement-learning
  - agricultural-ai
  - weather-modelling
  - curriculum-learning
  - edge-ai
pipeline_tag: reinforcement-learning
---

# Agricultural Weather-Risk RL — MaskablePPO + Permutation-Invariant GRU

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 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 note

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.

**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.

## How to use

### Train (triage default)

```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


Load and act
Pythonfrom sb3_contrib import MaskablePPO

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.

Dependencies
texttorch>=2.0
gymnasium>=0.29
stable-baselines3>=2.0
sb3-contrib>=2.0
numpy>=1.24

GPU recommended for training; CPU is viable for short runs and inference.

License
AGPL-3.0. See repository for full terms.