AgriManager / Docs
Website GitHub

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.

Three layers, plus a pluggable env adapter Overrides flow down only. The env adapter is swappable by dataset config. sbatch_*.slurm resources only · activate env · srun one run_*.sh srun experiments/<exp>/run_*.sh fixed wrapper · hardcodes every path and override no free-form CLI flags Hydra key=value entrypoints/*.sh stable atomic operations dataset build · LLM train · LLM eval · NN train · NN eval env_name agrimanager/env/<name>/ pluggable adapter 4 files, no registration
The three-layer execution model. Dataset build, training, and evaluation are the stable atomic operations under 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 · CPU
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):

output
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:

python
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
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).

bash
# 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.

bash
# 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
bash entrypoints/train/nn_train.sh --config-name nn
bash entrypoints/eval/nn_eval.sh  --config-name nn