Mcp Sales Forecasting

What is Mcp Sales Forecasting

mcp-sales-forecasting is a project designed to predict sales using historical sales data and weather data. It utilizes machine learning techniques to generate accurate forecasts for inventory management and sales strategies.

Use cases

Use cases include predicting sales for specific products in retail stores, optimizing inventory levels based on weather forecasts, and enhancing promotional strategies by understanding sales trends influenced by weather conditions.

How to use

To use mcp-sales-forecasting, clone the repository, set up a Python virtual environment, install the required dependencies, and configure the Visual Crossing API key. Then, prepare the sales and historical weather data in the specified format.

Key features

Key features include integration with Visual Crossing Weather API for weather data, support for historical sales data from Kaggle, and a machine learning model that predicts sales based on weather conditions and past sales trends.

Where to use

mcp-sales-forecasting can be applied in retail and e-commerce sectors where sales forecasting is crucial for inventory management, marketing strategies, and operational efficiency.

Setup and Installation

1. Clone the repository:

   git clone <your-repo-url>
   cd mcp-sales-forecasting
   

2. Create a Python virtual environment and activate it:

   python -m venv .venv
   # On Windows:
   # .\.venv\Scripts\activate
   # On macOS/Linux:
   # source .venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. API Key for Visual Crossing:

   • Sign up for a free API key at Visual Crossing Weather.
   • Open the ui.py file and replace the placeholder VC_API_KEY = "YOUR_API_KEY_HERE" with your actual Visual Crossing API key.

     # Inside ui.py (and potentially src/forecasting/model.py if you run its test block)
     VC_API_KEY = "YOUR_ACTUAL_VISUAL_CROSSING_API_KEY"
     

   • Important: Do not commit your actual API key to a public repository. For sharing, it’s better to instruct users to add their own.

5. Data Setup:

   • Sales Data: Download the train.csv file from Kaggle’s Store Item Demand Forecasting Challenge (or provide a direct link if not including it in the repo) and place it in the data/ folder. The agent is currently configured to use data for Store 1, Item 1.
   • Historical Weather Data: This project was trained using historical daily temperature data for Basel, CH, covering the period 2013-01-01 to 2017-05-31. You will need to obtain a similar CSV file. For demonstration, the src/forecasting/model.py file expects a CSV file at the path defined by HISTORICAL_WEATHER_CSV_PATH (e.g., data/Geçmiş Hava Durumu Verileri May 30 2025.csv - rename this to something like basel_weather_2013_2017.csv).
     • Ensure your CSV contains at least ‘timestamp’ (format e.g., YYYYMMDDTHHMMSS) and ‘temperature’ columns. The load_historical_weather_from_csv function in model.py will process this into daily min/mean/max temperatures.
     • Update HISTORICAL_WEATHER_CSV_PATH and HISTORICAL_WEATHER_COLUMN_MAP (if column names are different) in src/forecasting/model.py if your CSV file name or structure differs.

How to Run

1. Train the Model (if no model file exists or you want to re-train):
   The Streamlit UI will attempt to load a pre-trained model. If you need to train the model for the first time or re-train it (e.g., after changing historical data), ensure your historical weather CSV is correctly set up and then run:

   python -m src.forecasting.model
   

   This will train the model using the data in data/ and save it to models/sales_prophet_model_basel_temp.json. (The if __name__ == '__main__' block in model.py is set to delete any existing model file and retrain).

2. Run the Streamlit Web UI:

   streamlit run ui.py
   

   This will open the application in your web browser (usually at http://localhost:8501).

Project Logic Overview

• Historical Data Processing:
  • Sales data is loaded via sales_data_server.py.
  • Historical weather data (Basel temperatures) is loaded from a local CSV and processed into daily min/mean/max values by load_historical_weather_from_csv in model.py.
• Model Training (model.py):
  • Historical sales and processed historical weather are merged.
  • A Prophet model is trained with temperature metrics as external regressors.
  • The trained model is saved.
• Prediction (ui.py via model.py):
  • The user specifies the number of future days for forecasting.
  • weather_server.py fetches future weather forecasts from the Visual Crossing API for the requested period.
  • The pre-trained Prophet model is loaded.
  • make_sales_forecast in model.py uses the model and the future weather data (as regressors) to generate sales predictions.
  • Results are displayed in the Streamlit UI.

(Optional) Future Enhancements

• Implement more sophisticated methods for handling API rate limits for historical data.
• Add more diverse weather regressors (precipitation, wind, humidity, specific weather event flags).
• Incorporate holiday effects directly into the Prophet model.
• Perform rigorous model evaluation and hyperparameter tuning.
• Deploy as a more formal API (e.g., using the Flask app prototyped earlier).
• Develop a more autonomous agent that runs daily and stores/reports predictions.