---
title: Grape Firmness Predictor
emoji: 🍇
colorFrom: purple
colorTo: green
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
pinned: false
license: mit
---

# 🍇 Grape Firmness Predictor

An interactive machine learning application that predicts grape firmness based on physical characteristics using a RandomForest Regressor trained with AutoML.

## 🎯 Overview

This Gradio interface provides an easy way to predict grape firmness levels (Soft, Medium, Firm) using measurements of width, length, blemish count, and color. The model was trained using automated machine learning techniques on a carefully curated grape dataset.

## 🤖 Model Information

### Architecture
- **Algorithm**: RandomForest Regressor
- **Framework**: scikit-learn 1.4.2
- **Training Method**: AutoML grid search
- **Model Repository**: [EricCRX/grape-firmness-automl](https://huggingface.co/EricCRX/grape-firmness-automl)

### Performance Metrics
- **RMSE**: 0.177
- **R² Score**: 0.943 (94.3% variance explained)
- **Training**: Grid search across RandomForest and SVR models

### Files
- `model.joblib`: Trained RandomForest model
- `preprocess.joblib`: Preprocessing pipeline (feature transforms and scaling)

## 📊 Dataset

### Source
- **Dataset**: [rlogh/grape-firmness-dataset](https://huggingface.co/datasets/rlogh/grape-firmness-dataset)
- **Original Samples**: 30 manually collected measurements
- **Augmented Samples**: 300 (using SMOTE-NC and numeric jitter)
- **Purpose**: Address class imbalance and increase training data

### Features
| Feature | Type | Range | Description |
|---------|------|-------|-------------|
| width_cm | float | 1.5-3.0 | Grape width in centimeters |
| length_cm | float | 1.5-3.0 | Grape length in centimeters |
| blemish_count | int | 0-10 | Number of visible surface blemishes |
| color | string | red/green | Grape variety color |

### Target Variable
- **firmness**: Integer scale 1-3
  - **1 = Soft**: Overripe, mushy texture
  - **2 = Medium**: Optimal ripeness for consumption
  - **3 = Firm**: Fresh, crisp texture

## 🚀 Features

### User Interface
- **Intuitive Sliders**: Adjust physical measurements easily
- **Color Selection**: Radio buttons for red or green grapes
- **Real-time Predictions**: Instant firmness classification
- **Detailed Results**: Comprehensive prediction interpretation
- **Quality Assessment**: Automatic quality evaluation based on inputs

### Example Inputs
Pre-loaded examples covering different scenarios:
- Soft red grape with blemishes
- Firm green grape without blemishes
- Large firm red grape
- Small soft red grape with multiple blemishes
- Medium green grape

### Information Panels
- Model architecture and training details
- Dataset information and feature descriptions
- Known limitations and disclaimers
- Result interpretation guidelines

## 📋 How to Use

### Basic Workflow
1. **Adjust Sliders**:
   - Set grape width (1.5-3.0 cm)
   - Set grape length (1.5-3.0 cm)
   - Set blemish count (0-10)

2. **Select Color**:
   - Choose red or green grape variety

3. **Get Prediction**:
   - Click "Predict Firmness" button
   - View firmness level (Soft/Medium/Firm)
   - Read quality assessment

4. **Try Examples**:
   - Click any example to load preset values
   - See predictions for different grape types

### Interpreting Results

The prediction includes:
- **Firmness Level**: Classification (1, 2, or 3)
- **Raw Score**: Continuous prediction value
- **Quality Assessment**: Based on blemishes and size
- **Input Summary**: Your entered characteristics

## 🔬 Technical Details

### Training Procedure
1. **Data Preparation**:
   - Load original 30-sample dataset
   - Apply SMOTE-NC for class balancing
   - Add numeric jitter for augmentation
   - Split: 70% train, 15% val, 15% test

2. **AutoML Search**:
   - Grid search across model types
   - Hyperparameter tuning for selected models
   - Cross-validation during search
   - R² score as optimization metric

3. **Model Selection**:
   - RandomForest selected as best performer
   - Tuned parameters: n_estimators, max_depth
   - Preprocessing pipeline saved separately

### Preprocessing Pipeline
- Feature scaling/normalization
- Categorical encoding (color)
- Feature engineering (if applicable)
- Consistent transform for inference

## ⚠️ Limitations

### Data Limitations
- **Small Original Dataset**: Only 30 authentic samples
- **Synthetic Augmentation**: 90% of data is algorithmically generated
- **Limited Diversity**: May not represent all grape varieties
- **Geographic Constraints**: Unknown source locations

### Model Limitations
- **Generalization**: May not work well on unseen varieties
- **Feature Coverage**: Missing important factors (temperature, harvest time)
- **Measurement Sensitivity**: Requires accurate physical measurements
- **Blemish Subjectivity**: Counting may vary between observers

### Use Case Constraints
- **Not Production-Ready**: Educational demonstration only
- **No Commercial Validation**: Not tested in real grading scenarios
- **No Regulatory Approval**: Not certified for quality control
- **Academic Purpose**: Designed for learning ML deployment

## 🎓 Educational Context

This project demonstrates:
- **Classical ML Workflow**: Feature engineering, model training, evaluation
- **AutoML Techniques**: Automated hyperparameter search
- **Model Deployment**: Gradio interface on Hugging Face Spaces
- **Documentation**: Comprehensive README and in-app guidance
- **User Experience**: Intuitive interface for non-technical users

Created as part of CMU 24-679 (Designing and Deploying AI/ML) coursework.

## 📖 Additional Resources

### Related Links
- [Model Card](https://huggingface.co/EricCRX/grape-firmness-automl)
- [Dataset Card](https://huggingface.co/datasets/rlogh/grape-firmness-dataset)
- [scikit-learn Documentation](https://scikit-learn.org/)
- [Gradio Documentation](https://gradio.app/)

### Further Reading
- RandomForest Regression theory
- SMOTE for imbalanced datasets
- Feature engineering for tabular data
- Model evaluation metrics (RMSE, R²)

## 🐛 Known Issues

- **Version Dependencies**: Specific scikit-learn version required (1.4.2)
- **Preprocessing Compatibility**: Model and preprocessor must match versions
- **Input Validation**: Limited checks for extreme outlier values
- **Color Typos**: Case-sensitive color input in backend

## 🔮 Future Improvements

Potential enhancements:
- Add confidence intervals for predictions
- Include feature importance visualization
- Support for additional grape varieties
- Image-based firmness prediction
- Integration with SHAP for explainability
- Mobile-optimized interface
- Batch prediction support

## 📄 License

MIT License - Free for educational and research use

## 🙏 Acknowledgments

- **Model Creator**: EricCRX
- **Dataset Creator**: rlogh
- **Framework**: scikit-learn team
- **Platform**: Hugging Face Spaces
- **UI**: Gradio library
- **Course**: CMU 24-679 instructors and TAs

---

**Disclaimer**: This model is for educational purposes only. Predictions should not be used for commercial grape grading or quality control without proper validation and testing on production data.