Quick start
Score scripted policies on a CPU, then build a dataset, train, and evaluate.
Execution is organized into three layers, and overrides only flow downward: cluster files
(sbatch_*.slurm) call fixed experiment wrappers (run_*.sh), which call the stable
atomic operations under entrypoints/. The entrypoints are the API the rest of the repo depends
on; all overrides are Hydra key=value.
entrypoints/.1. Check the setup on a CPU#
This needs no GPU and no model download: it builds eight maize scenarios and scores the no-action policy and
the scripted agronomic reference on them. install.sh --cpu is enough.
bash smoke_tests/wofost_gym/run_cpu_quickstart.sh
The script builds the dataset from smoke_tests/wofost_gym/config/quickstart_maize_cpu.yaml
(the first run downloads the 0.25 GB maize weather pool), rolls out both policies with the WOFOST
lnpkw-v0 action menu and the profit_max objective, and prints each mean objective.
Expected tail (about 45 seconds, including the download):
no_action: smoke_tests/wofost_gym/results/quickstart/no_action/metrics.json objective_reward_mean = 0.3341123096222971 ag_heuristic: smoke_tests/wofost_gym/results/quickstart/ag_heuristic/metrics.json objective_reward_mean = 1.5955195245941627
Eight scenarios make a smoke check; benchmark numbers come from the held-out test suite. ag_heuristic is the current code
version of the scripted agronomic reference; the paper's references are listed in
Benchmark. To print what a language model would read for one
scenario:
import pandas as pd from agrimanager.env.base import create_environment df = pd.read_parquet("smoke_tests/wofost_gym/data/quickstart_maize_cpu/val.parquet") env_config = df.iloc[0]["extra_info"]["interaction_kwargs"]["env_config"] env, _ = create_environment("wofost_gym", dict(env_config)) observation, info = env.reset() print(env.system_prompt()) print(observation)
2. Build a dataset#
A dataset config declares env_name plus the scenario parameters; environment behavior is
dataset-owned — baked into the parquet, so a split always rebuilds the same environment
(see Configuration).
bash entrypoints/dataset/build.sh \ --config entrypoints/dataset/examples/wofost/example_sample.yaml \ --num-workers 8
3. Train#
Training runs GRPO through VeRL and needs a CUDA GPU. The default config is agri_grpo; override
any parameter via Hydra key=value. With no overrides it trains on the WOFOST smoke datasets, so
build those first with bash smoke_tests/wofost_gym/run_build_datasets.sh (it uses the 20-crop
weather pool, a 17.6 GB download).
# run with the default config bash entrypoints/train/train.sh # your own dataset, model and run name bash entrypoints/train/train.sh \ data.train_files=experiments/my_exp/data/my_dataset/train.parquet \ data.val_files=experiments/my_exp/data/my_dataset/val.parquet \ actor_rollout_ref.model.path=Qwen/Qwen3-4B-Instruct-2507 \ trainer.experiment_name=my_experiment
4. Evaluate#
Evaluation is a batched rollout across the scenarios of a parquet split, with greedy decoding. Convert a
sharded training checkpoint to Transformers layout first. Scripted policies (no_action,
random, and ag_heuristic, the scripted agronomic reference) run through a separate
entrypoint on a CPU. To score on the paper's held-out test suite, follow Evaluation.
# sharded checkpoint -> Transformers layout bash entrypoints/tools/merge.sh <run_dir>/global_step_100/actor <run_dir>/global_step_100/hf # batched rollout evaluation bash entrypoints/eval/eval.sh \ data.inference_file=experiments/my_exp/data/my_dataset/test.parquet \ model.config=agrimanager/model_interface/configs/vllm_offline/default.yaml \ model.path=<run_dir>/global_step_100/hf \ output.dir=experiments/my_exp/results/my_eval # a scripted policy (no_action / random / ag_heuristic) bash entrypoints/eval/baseline_eval.sh --config-name no_action \ data.inference_file=<split.parquet> output.dir=<out_dir> wandb.enabled=false
5. Train a neural-network baseline#
A framework-native neural-network policy (Stable-Baselines3 PPO) trains as a fixed-interface baseline on a
CPU. It reads the numeric variant of a dataset, built from the same dataset config with
llm_mode: false; the WOFOST smoke build creates both variants. See
RL training.
bash entrypoints/train/nn_train.sh --config-name nn bash entrypoints/eval/nn_eval.sh --config-name nn