AgriManager / Docs
Website GitHub

Adding a new environment

Drop a four-file package into agrimanager/env/ — there is no registry.

Both dataset build and training resolve your environment by folder name — importlib.import_module("agrimanager.env.<env_name>") — and discover your classes automatically. Drop a new folder in, and it works.

The four-file contract#

Create a package at agrimanager/env/<your_env>/ with four files:

FileWhat it provides
env.pysubclass of BaseEnv — reset(), step(action), system_prompt()
env_config.pysubclass of BaseEnvConfig
prompt.pyparse_action_response(text) → Optional[int]
create_dataset.pysubclass of BaseDatasetGenerator plus a module-level generate(config, output_dir)

The core interface#

python · agrimanager/env/base/env.py
class YourEnv(BaseEnv):
    def reset(self) -> Tuple[Any, Dict]:
        # return (obs, info) — obs is the first textual observation
        ...
    def step(self, action) -> Tuple[Any, float, bool, Dict]:
        # action arrives as the raw LLM string; parse it, step the simulator,
        # return (obs, reward, done, info) — a scalar reward on every turn
        ...
    def system_prompt(self) -> str:
        # the task plus the schema: observations, action menu, objective
        ...

How an environment plugs in#

Dataset build → training: how an env plugs in Two interfaces. The parquet is the seam — it carries env_name across them. framework env code (you write this) parquet (the contract) BUILD TIME dataset config YAMLenv_name + scenario parameters entrypoints/dataset/build.shthin shell wrapper · calls the Python router agrimanager.env.create_dataset.generate()reads env_name · imports the env module dynamically <Env>DatasetGeneratorsubclass of BaseDatasetGenerator interface: BaseDatasetGenerator build_split_records(split)must implement — return env_configs _build_initial_prompt(env_config)override — domain system prompt splits() parquet artifact — train.parquet · val.parquet · test.parqueteach row: extra_info.interaction_kwargs.env_config = {env_name, …} TRAINING TIME entrypoints/train/train.shlaunches agrimanager.adapter.trainer.main_ppo AgriInteraction (adapter)per row: reads env_name · calls create_environment(…) <Env> instanceadapter drives it turn-by-turn via step(action_text) interface: BaseEnv reset() → (obs, info) step(action) → (obs, reward, done, info) system_prompt() → str action arrives as text · reward is a scalar per turn
The parquet is the contract. A dataset row carries env_name; build time routes to your create_dataset.py, training time routes to your env.py — with no central registry in between.

Steps#

  1. Maintain the simulator externally under ../AgriManagerExternal/<env>; AgriManager only integrates it.
  2. Create the four-file package in agrimanager/env/<your_env>/, mirroring wofost_gym/.
  3. Export your classes in the package __init__.py's __all__ — this is how discovery finds them.
  4. Stamp env_name into every parquet row's env_config. That is the registration.
  5. Write a dataset config with env_name + dataset_id, then run entrypoints/dataset/build.sh.
  6. (Optional) add nn_adapter.py with a BaseNNEnvAdapter for the neural-network PPO baseline.
  7. Smoke-test it — copy smoke_tests/wofost_gym/, swap the env name, and run the build/train/eval scripts.
Runtime contract

Return a scalar reward every turn. If your env is trajectory-rewarded, emit 0 on early turns and the trajectory reward on the final turn. The action menu rendered in your prompt and parse_action_response() must stay mutually consistent.

Boundary rules

No if env_name == … branches anywhere — dispatch always goes through create_environment(). Never modify verl/ for an env integration. Hand-run tooling (asset generation, baselines, analyses) belongs in integrations/<env>/.