updated defaults

README.md

@@ -1,10 +1,160 @@
 ---
-title: Hackathon
-emoji: 🏆
-colorFrom: indigo
+title: FarmRL OpenEnv Submission
+emoji: 🌾
+colorFrom: green
 colorTo: blue
 sdk: docker
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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
+
+```bash
+uv pip install -e .
+```
+
+Or with pip:
+```bash
+pip install -r requirements.txt
+```
+
+### Configuration
+
+Create a `.env` file in the project root with required credentials:
+
+```env
+# 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)
+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`)
+- `OPENAI_API_KEY`: Your OpenAI API key (required, no default)
+
+### Running the API Server
+
+Start the OpenEnv API server on your configured port:
+
+```bash
+uv run python -m server.app
+```
+
+The server will be available at `http://localhost:7860`
+
+### Running Inference
+
+Execute the full inference pipeline:
+
+```bash
+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:
+```bash
+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:
+
+```bash
+docker build -t farmrl-openenv .
+docker run -p 7860:7860 farmrl-openenv
+```
+
+## References
+
+- [OpenEnv Framework](https://github.com/openenv-ai/openenv)
+- [FarmGym Simulation](https://github.com/farm-gym)
+- Dataset: Real agricultural data with crop yield observations

final-requirements.md

@@ -1,55 +0,0 @@
-Functional Requirements:
-
-1. Real-World Task Simulation
-The environment must represent tasks that humans actually perform in real settings—no games
-or toy problems.
-Examples include email triage, code review, data cleaning, scheduling, customer support, and
-content moderation.
-
-2. OpenEnv Specification Compliance
-The environment must fully implement the OpenEnv interface, including:
-Typed Observation, Action, and Reward models using Pydantic
-step(action) → returns (observation, reward, done, info)
-reset() → returns the initial observation
-state() → returns the current state
-An openenv.yaml file containing metadata
-The implementation must successfully pass validation via openenv validate.
-
-3. Minimum of Three Tasks with Agent Graders
-Provide at least three tasks, each with a clearly defined objective
-Tasks should span increasing difficulty: easy → medium → hard
-Each task must include a programmatic grader that assigns a score between 0.0 and
-1.0
-Grading criteria must be clear, deterministic, and reproducible
-
-4. Meaningful Reward Function
-The reward function must provide feedback throughout the task trajectory, not just at
-completion
-It should reward incremental progress toward the objective
-It must penalize undesirable behaviors such as infinite loops or destructive actions
-
-5. Baseline Inference Script
-Include an inference script that uses the OpenAI API client to evaluate a model within
-the environment
-API credentials must be read from environment variables (HF_TOKEN)
-The script should produce a reproducible baseline score across all tasks
-
-
-Non-Functional Requirements:
-1. Deployment on Hugging Face Spaces
-The environment must be deployable as a containerized Hugging Face Space
-It should be tagged with openenv
-
-2. Containerized Execution
-Provide a working Dockerfile
-The environment must build and run successfully using:
-docker build
-docker run
-
-3. Documentation
-The README must include:
-Environment overview and motivation
-Definitions of action and observation spaces
-Task descriptions with expected difficulty levels
-Setup and usage instructions
-Baseline performance scores

inference.py

@@ -27,11 +27,11 @@ def require_env(name: str) -> str:
     return value
 
 
-API_BASE_URL = require_env("API_BASE_URL")
-MODEL_NAME = require_env("MODEL_NAME")
-TASK_NAME = require_env("TASK_NAME")
-BENCHMARK = require_env("BENCHMARK")
-OPENAI_API_KEY = os.getenv("OPENAI_API_KEY", "").strip()
+API_BASE_URL = os.getenv("API_BASE_URL", "https://api.openai.com/v1").strip()
+MODEL_NAME = os.getenv("MODEL_NAME", "gpt-4o-mini").strip()
+TASK_NAME = os.getenv("TASK_NAME", "farm-yield-optimization").strip()
+BENCHMARK = os.getenv("BENCHMARK", "farmrl").strip()
+OPENAI_API_KEY = require_env("OPENAI_API_KEY")
 
 PLACEHOLDER_TOKENS = {
     "your_openai_api_key_here",

openenv.yaml

@@ -7,6 +7,13 @@ environment:
     step: POST /step
     state: GET /state
 
+defaults:
+  API_BASE_URL: https://api.openai.com/v1
+  MODEL_NAME: gpt-4o-mini
+  TASK_NAME: farm-yield-optimization
+  BENCHMARK: farmrl
+  PORT: 7860
+
 observation_schema:
   type: object
   required: