README.md

metadata

title: FarmRL OpenEnv Submission
emoji: 🌾
colorFrom: green
colorTo: blue
sdk: docker
pinned: false

FarmRL OpenEnv Submission

A reinforcement learning environment and agent for optimizing farm management decisions using the OpenEnv framework.

Overview

FarmRL trains an intelligent agent to manage crop farming decisions by controlling irrigation, fertilizer application, and pesticide use. The agent learns from a real agricultural dataset and aims to maximize crop yield while maintaining sustainability.

Key Features:

• OpenEnv-compliant REST API for environment interaction
• LLM-based inference via OpenAI-compatible endpoints
• Tabular RL training with preprocessing pipeline
• Grading and evaluation framework

Quick Start

Prerequisites

• Python 3.11+
• uv package manager (recommended) or pip
• Environment variables configured (see Configuration section)

Installation

uv pip install -e .

Or with pip:

pip install -r requirements.txt

Configuration

Create a .env file in the project root with required credentials:

# API Configuration (defaults provided for base URL and model)
API_BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-4o-mini
TASK_NAME=farm-yield-optimization
BENCHMARK=farmrl
PORT=7860

# Required API Credentials (no defaults)
# Submission/Judge environments inject API_KEY.
API_KEY=your_api_key_here
# Optional local compatibility fallback:
# OPENAI_API_KEY=your_api_key_here

Environment Variables:

• API_BASE_URL: LLM endpoint URL (default: https://api.openai.com/v1)
• MODEL_NAME: Model identifier (default: gpt-4o-mini)
• TASK_NAME: Task identifier (default: farm-yield-optimization)
• BENCHMARK: Benchmark name (default: farmrl)
• PORT: Server port (default: 7860)
• API_KEY: Primary API key for submission validation (required, no default)
• OPENAI_API_KEY: Optional local compatibility fallback when API_KEY is not set

Hackathon submission note:

• Use only the injected API_BASE_URL and API_KEY values provided by the validator.
• Do not hardcode API keys, alternate providers, or alternate base URLs.
• Inference is configured to fail fast if proxy-compatible LLM settings are missing.

Running the API Server

Start the OpenEnv API server on your configured port:

uv run python -m server.app

The server will be available at http://localhost:7860

Running Inference

Execute the full inference pipeline:

uv run python inference.py

This runs the agent against the environment, logging results to stdout in the standard format:

• [START] - Episode initialization
• [STEP] - Individual step results
• [END] - Episode completion with score

Project Structure

.
├── api/              # REST API endpoints
├── env/              # FarmRL environment implementation
├── server/           # API server setup
├── tasks/            # Grading and evaluation
├── scripts/          # Data preprocessing utilities
├── reference-material/  # Documentation and examples
├── inference.py      # Main inference script
├── openenv.yaml      # Environment schema definition
├── requirements.txt  # Python dependencies
└── farmer_advisor_dataset.csv  # Agricultural training data

Environment Specification

The environment state and action spaces are defined in openenv.yaml:

Observations:

• soil_moisture: Soil water availability (0-100%)
• soil_ph: Soil acidity (4-9)
• temperature: Environmental temperature
• rainfall: Precipitation amount (mm)
• crop_stage: Current crop growth stage
• day: Days since planting

Actions:

• water: Irrigation amount (0-50 mm)
• fertilizer: Fertilizer application
• pesticide: Pesticide application

API Endpoints

• POST /reset - Reset environment (optional seed parameter)
• POST /step - Execute action and get next state
• GET /state - Get current environment state
• GET /health - Health check

Data Pipeline

The project includes a preprocessing script (scripts/add_water_variable.py) that:

1. Adds a Water_mm column representing agent-controllable irrigation
2. Adjusts Rainfall_mm to maintain water-balance invariance

Run preprocessing:

uv run python scripts/add_water_variable.py farmer_advisor_dataset.csv

Evaluation

The grading system (tasks/graders.py) evaluates agent performance based on:

• Crop yield optimization
• Sustainability metrics
• Action validity

Docker

The project includes a Dockerfile for containerized deployment:

docker build -t farmrl-openenv .
docker run -p 7860:7860 farmrl-openenv

References

• OpenEnv Framework
• FarmGym Simulation
• Dataset: Real agricultural data with crop yield observations