docs/CLI_USAGE.md

# CLI Usage Guide - Crop Yield Predictor

## 🌾 Overview

The `crop_yield_predictor.py` script provides three modes for making crop yield predictions:

1. **One-shot CLI prediction** - Enter parameters via command line flags
2. **Batch CSV prediction** - Process multiple records from a CSV file  
3. **Interactive mode** - Step-by-step input prompts

## 📋 Prerequisites

Ensure you have trained models available:
```bash
python crop_yield_ml_pipeline.py
```

## 🚀 Usage Examples

### 1. One-Shot CLI Prediction

Make a single prediction by providing all parameters as command-line arguments:

```bash
python crop_yield_predictor.py predict \
    --year 2024 \
    --state "Punjab" \
    --crop "Rice" \
    --season "Kharif" \
    --area 10.0 \
    --production 25.0 \
    --rainfall 1200 \
    --fertilizer 75 \
    --pesticide 8
```

**Output:**
```
🚀 Initializing Crop Yield Predictor...
📥 Loading trained models...
✅ All models loaded successfully

Prediction results (kg/hectare):
- Random Forest: 2017.70
- XGBoost: 1875.01
- PyTorch: 1103.98
Best model: Random Forest -> Yield 2017.70 kg/ha
Total expected production: 20.18 tons
```

### 2. Batch CSV Prediction

Process multiple records from a CSV file:

```bash
python crop_yield_predictor.py batch input_data.csv --out results.csv
```

**Input CSV Format:**
```csv
Crop_Year,State,District,Crop,Season,Area,Production,Annual_Rainfall,Fertilizer,Pesticide
2024,Punjab,Ludhiana,Rice,Kharif,10.0,25.0,1200.0,75.0,8.0
2024,Haryana,Karnal,Wheat,Rabi,15.0,30.0,800.0,60.0,5.0
```

**Output:** Creates a CSV with additional columns for each model's predictions.

### 3. Interactive Mode

Run without any arguments for step-by-step input:

```bash
python crop_yield_predictor.py
```

The system will guide you through entering each parameter interactively.

## 📝 Required Parameters

### For CLI Prediction (`predict` mode):

| Parameter | Type | Required | Description | Example |
|-----------|------|----------|-------------|---------|
| `--year` | int | ✅ | Crop year | 2024 |
| `--state` | str | ✅ | State name | "Punjab" |
| `--crop` | str | ✅ | Crop type | "Rice" |
| `--season` | str | ✅ | Growing season | "Kharif" |
| `--area` | float | ✅ | Area in hectares | 10.0 |
| `--production` | float | ✅ | Production in tons | 25.0 |
| `--rainfall` | float | ❌ | Annual rainfall (mm) | 1200 (default: 1000) |
| `--fertilizer` | float | ❌ | Fertilizer usage (kg) | 75 (default: 50) |
| `--pesticide` | float | ❌ | Pesticide usage (kg) | 8 (default: 5) |
| `--district` | str | ❌ | District name | "Ludhiana" (default: "Unknown") |

### Valid Options:

**States:** Any Indian state (e.g., Punjab, Haryana, Gujarat, Tamil Nadu, etc.)

**Crops:** Rice, Wheat, Maize, Cotton, Sugarcane, Groundnut, and 60+ others

**Seasons:**
- `Kharif` - Monsoon season (June-October)
- `Rabi` - Winter season (November-April) 
- `Summer` - Summer season (April-June)
- `Whole Year` - Year-round cultivation
- `Autumn`, `Winter`, `Total` - Other seasonal categories

## 💡 Tips

1. **Use quotes** for multi-word values:
   ```bash
   --state "Uttar Pradesh" --crop "Arhar/Tur"
   ```

2. **Check available options** by running interactive mode first to see supported states/crops

3. **Batch processing** is efficient for multiple predictions:
   ```bash
   # Process 1000 records at once
   python crop_yield_predictor.py batch large_dataset.csv --out predictions.csv
   ```

4. **Default values** are provided for optional parameters based on typical Indian agricultural practices

## 📊 Understanding Results

### Model Predictions
- **Random Forest**: Ensemble of decision trees (good baseline)
- **XGBoost**: Gradient boosting (often most accurate)
- **PyTorch**: Deep neural network (handles complex patterns)

### Yield Interpretation
- **> 3000 kg/ha**: 🟢 Excellent yield
- **2000-3000 kg/ha**: 🟡 Good yield  
- **1000-2000 kg/ha**: 🟠 Moderate yield
- **< 1000 kg/ha**: 🔴 Low yield

## 🔧 Command Reference

```bash
# Get general help
python crop_yield_predictor.py --help

# Get help for specific mode
python crop_yield_predictor.py predict --help
python crop_yield_predictor.py batch --help

# One-shot prediction (minimal)
python crop_yield_predictor.py predict --year 2024 --state Punjab --crop Rice --season Kharif --area 10 --production 25

# Batch prediction
python crop_yield_predictor.py batch data.csv --out results.csv

# Interactive mode (default)
python crop_yield_predictor.py
```

## 🎯 Quick Examples

### Rice in Punjab (Kharif season):
```bash
python crop_yield_predictor.py predict --year 2024 --state Punjab --crop Rice --season Kharif --area 5 --production 12 --rainfall 1100
```

### Wheat in Haryana (Rabi season):
```bash
python crop_yield_predictor.py predict --year 2024 --state Haryana --crop Wheat --season Rabi --area 8 --production 18 --rainfall 600
```

### Cotton in Gujarat (Kharif season):
```bash
python crop_yield_predictor.py predict --year 2024 --state Gujarat --crop Cotton --season Kharif --area 12 --production 8 --rainfall 800 --pesticide 15
```

---

**📁 Files:**
- `crop_yield_predictor.py` - Main CLI predictor
- `trained_models/` - Directory with trained models
- `sample_batch.csv` - Example input file for batch prediction

**🔗 Related:**
- `crop_yield_ml_pipeline.py` - Train the models
- `test_models.py` - Test model performance
- `results_summary.py` - View training results