README.md

metadata

title: AgriPredict Analysis Service
emoji: 🌾
colorFrom: green
colorTo: blue
sdk: docker
app_file: main.py
pinned: false

AgriPredict Analysis Service

A production-ready FastAPI service for agricultural demand forecasting with multiple ML models including CatBoost ensemble methods.

Features

• Multi-Model Forecasting: SMA, WMA, Exponential Smoothing, ARIMA, and CatBoost
• RESTful API: Clean endpoints for health checks, model listing, and forecasting
• Docker Ready: Containerized for easy deployment
• Hugging Face Spaces: Configured for cloud deployment
• Comprehensive Testing: Built-in test suite for validation
• Confidence Intervals: Uncertainty quantification for predictions
• Real-time Processing: Asynchronous processing for high performance

Quick Start

1. Install Dependencies

python run.py install

2. Run the Service

python run.py run

The API will be available at:

• Local Service: http://localhost:7860
• Local Documentation: http://localhost:7860/docs
• Local Health Check: http://localhost:7860/health

Production (Hugging Face Spaces)

• Live Service: https://adsurkasur-agripredict-analysis.hf.space
• Live Documentation: https://adsurkasur-agripredict-analysis.hf.space/docs
• Live Health Check: https://adsurkasur-agripredict-analysis.hf.space/health

3. Test the Service

python run.py test

4. Train CatBoost Model (Optional)

python run.py train

API Endpoints

GET /health

Health check endpoint

{
  "status": "healthy",
  "service": "AgriPredict Analysis Service",
  "version": "1.0.0"
}

GET /models

List available forecasting models

{
  "models": ["SMA", "WMA", "ES", "ARIMA", "CatBoost"]
}

POST /forecast

Generate demand forecasts

Request Body:

{
  "historical_data": [
    {
      "date": "2023-01-01",
      "demand": 100,
      "price": 50.0,
      "weather_temp": 25.0
    }
  ],
  "forecast_horizon": 7,
  "models": ["SMA", "WMA", "ES"],
  "confidence_level": 0.95
}

Response:

{
  "forecast_horizon": 7,
  "models_used": ["SMA", "WMA", "ES"],
  "forecast_dates": ["2023-01-08", "2023-01-09", ...],
  "forecasts": {
    "SMA": [105.2, 107.8, ...],
    "WMA": [108.5, 110.2, ...],
    "ES": [106.1, 108.9, ...]
  }
}

"models": ["ensemble"], "include_confidence": true, "scenario": "realistic" }

### List Models

GET /models

Returns list of available forecasting models.

## Models Available

1. **SMA** - Simple Moving Average (basic trend analysis)
2. **WMA** - Weighted Moving Average (recent data weighted more)
3. **ES** - Exponential Smoothing (seasonal trend analysis)
4. **ARIMA** - Statistical time series model
5. **CatBoost** - Machine learning model (gradient boosting)

## Usage

### Local Development

1. Install dependencies:
```bash
python run.py install

2. Run the service:

python run.py run

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

API Documentation

Once running, visit http://localhost:7860/docs for interactive API documentation.

Testing

Test the service with the built-in test suite:

python run.py test

Deployment

This service is designed to run on Hugging Face Spaces with the following configuration:

• Runtime: Python 3.10+
• Framework: FastAPI with Uvicorn
• Container: Docker-based deployment
• Port: 7860
• GPU: Not required (CPU-only ML models)
• Memory: 2GB minimum recommended

Training the CatBoost Model

The CatBoost model includes a training script for artificial data:

python run.py train

For production use with real data:

1. Prepare your training dataset with features like:

   • Historical demand and prices
   • Date-based features (day of week, month, season)
   • Lag features (previous days' data)
   • Rolling statistics
   • Weather data

2. Modify train_catboost.py to use your real dataset

3. Train the model and update the implementation in models/forecast_models.py

Project Structure

analysis-service/
├── main.py                 # FastAPI application
├── models/
│   ├── forecast_models.py  # Forecasting algorithms
│   └── data_processor.py   # Data validation & processing
├── utils/
│   ├── config.py          # Configuration management
│   └── logger.py          # Logging setup
├── train_catboost.py      # Model training script
├── test_service.py        # API testing script
├── run.py                 # Development runner
├── requirements.txt       # Python dependencies
├── Dockerfile            # Container configuration
└── README.md             # This file

Development Commands

• python run.py install - Install dependencies
• python run.py run - Start the service
• python run.py test - Test the running service
• python run.py train - Train CatBoost model

Error Handling

The API includes comprehensive error handling:

• Input validation with Pydantic models
• Graceful error responses with appropriate HTTP status codes
• Detailed error messages for debugging
• Logging for monitoring and troubleshooting

Contributing

1. Test locally before committing: python run.py test
2. Ensure all tests pass
3. Update documentation as needed
4. Follow the existing code style and structure

License

MIT License - see LICENSE file for details.