https://github.com/shubham001official/fmcg-demand-forecasting
Transformer-based demand forecasting system with Streamlit dashboard and KPI insights. Time-series forecasting application using Amazon Chronos and PyTorch.
https://github.com/shubham001official/fmcg-demand-forecasting
demand-forecasting machine-learning time-series-forecasting
Last synced: 13 days ago
JSON representation
Transformer-based demand forecasting system with Streamlit dashboard and KPI insights. Time-series forecasting application using Amazon Chronos and PyTorch.
- Host: GitHub
- URL: https://github.com/shubham001official/fmcg-demand-forecasting
- Owner: shubham001official
- Created: 2026-04-12T11:59:40.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T12:28:51.000Z (2 months ago)
- Last Synced: 2026-04-12T14:19:31.007Z (2 months ago)
- Topics: demand-forecasting, machine-learning, time-series-forecasting
- Language: Jupyter Notebook
- Homepage: https://fmcg-demand-forecasting.streamlit.app
- Size: 262 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# FMCG Demand Intelligence Platform
**Author:** Shubham Sharma
---
## Badges
---
## 1. Overview
This project implements a production-style **AI-driven demand forecasting system** for FMCG products using transformer-based time-series models.
The system leverages **Amazon Chronos (T5-based architecture)** to generate probabilistic forecasts and integrates a **Streamlit-based analytics layer** for visualization, decision support, and reporting.
The platform is designed to replicate real-world enterprise workflows used in:
- Demand planning
- Supply chain optimization
- Retail analytics
- Business intelligence systems
---
## 2. Key Capabilities
### Forecasting Engine
- Transformer-based forecasting using Chronos
- Multi-product batch inference
- Probabilistic outputs with uncertainty bounds
- GPU-accelerated inference support
### Data Engineering
- Columnar storage using Parquet
- High-performance processing with Polars
- Memory optimization via categorical encoding
### Analytics Layer
- Interactive filtering (Company, Category, Product)
- Time-window analysis (3M, 6M, 1Y, Full)
- Multi-product comparative visualization
### Evaluation Metrics
- Mean Absolute Percentage Error (MAPE)
- Root Mean Squared Error (RMSE)
### Reporting
- Automated PDF generation
- Business-ready executive summaries
- Embedded visualizations
---
## 3. System Architecture
```mermaid
flowchart LR
A[Raw Sales Data - Parquet] --> B[Data Processing Layer]
B --> C[Feature Extraction]
C --> D[Chronos Forecast Model]
D --> E[Forecast Samples]
E --> F[Quantile Aggregation]
F --> G[Master Dataset]
G --> H[Streamlit Application]
H --> I[Interactive Dashboard]
H --> J[AI Insight Engine]
H --> K[PDF Report Generator]
````
-----
## 4\. Detailed Pipeline Architecture
```mermaid
flowchart TD
subgraph Data_Layer [Data Layer]
A1[Historical FMCG Sales]
A2[Parquet Storage]
end
subgraph Processing_Layer [Processing Layer]
B1[Polars DataFrame]
B2[Filtering by Product Hierarchy]
B3[Sorting Time Series]
end
subgraph Model_Layer [Model Layer]
C1[Chronos T5 Model]
C2[Tensor Conversion]
C3[GPU Inference]
end
subgraph Forecast_Layer [Forecast Layer]
D1[Multiple Sample Paths]
D2[Median Forecast]
D3[Confidence Intervals]
end
subgraph Output_Layer [Output Layer]
E1[Historical + Forecast Merge]
E2[Schema Enforcement]
E3[Parquet Output]
end
subgraph Application_Layer [Application Layer]
F1[Streamlit UI]
F2[Plotly Visualizations]
F3[AI Insights]
F4[PDF Reports]
end
A1 --> A2 --> B1 --> B2 --> B3
B3 --> C2 --> C1 --> C3
C3 --> D1 --> D2 --> D3
D2 --> E1
D3 --> E1
E1 --> E2 --> E3 --> F1
F1 --> F2
F1 --> F3
F1 --> F4
```
-----
## 5\. Forecasting Methodology
### Input
- Univariate time series per product (daily demand)
### Model
- Chronos T5 small variant
- Pretrained transformer for time-series forecasting
### Inference
- Generates multiple forecast trajectories (`num_samples=20`)
### Aggregation
- Median used as final prediction
- 10th percentile → lower bound
- 90th percentile → upper bound
### Post-processing
- Negative values clipped to zero
- Forecast horizon: 30 days
-----
## 6\. Data Schema
### Input Dataset
| Column | Description |
| :--- | :--- |
| Date | Timestamp |
| Company | FMCG company |
| Category | Product category |
| Product | SKU/Product name |
| Demand | Units sold |
### Output Dataset
| Column | Description |
| :--- | :--- |
| Date | Timestamp |
| Company | Company |
| Category | Category |
| Product | Product |
| Data\_Type | Historical / Forecast |
| Demand | Predicted / Actual |
| Demand\_Lower | Lower bound |
| Demand\_Upper | Upper bound |
-----
## 7\. Application Architecture
The Streamlit application is structured into modular components:
- Data loading (cached)
- Filtering layer (sidebar controls)
- KPI computation
- Forecast evaluation
- Visualization layer
- AI insights engine
- Report generation module
-----
## 8\. Dashboard Features
### Overview Tab
- Recent demand metrics
- Growth rate computation
- Forecast totals
- Moving average trends
### AI Insights Tab
- Rule-based interpretation of:
- Trend direction
- Growth signals
- Forecast reliability
### Forecast Tab
- Actual vs predicted comparison
- Error metrics visualization
### Multi-Product Analysis
- Cross-product demand comparison
- Contribution analysis
-----
## 9\. Performance Considerations
- **Polars** significantly improves query performance over pandas.
- **GPU inference** reduces forecasting latency.
- **Columnar storage** (Parquet) minimizes I/O overhead.
- **Categorical encoding** reduces memory footprint.
-----
## 10\. Project Structure
```text
fmcg-demand-ai/
├── fmcg_sales_india_2023_2026.parquet
├── fmcg_master_forecast.parquet
├── app.py
├── training.py
├── Screenshots/
│ └── app.png
├── requirements.txt
└── README.md
```
-----
## 11\. Setup Instructions
### Install Dependencies
```bash
pip install pandas polars torch transformers tqdm streamlit plotly reportlab
pip install git+[https://github.com/amazon-science/chronos-forecasting.git](https://github.com/amazon-science/chronos-forecasting.git)
```
### Run Forecast Pipeline
```bash
python training.ipynb
```
### Launch Application
```bash
streamlit run app.py
```
-----
## 12\. Screenshot
-----
## 13\. Future Enhancements
- Real-time data ingestion pipelines
- Model fine-tuning on domain-specific data
- Hierarchical forecasting (Company → Category → SKU)
- Integration with inventory optimization systems
- Deployment on cloud infrastructure (AWS / GCP)
-----
## 14\. License
This project is licensed under the MIT License.
```text
MIT License
Copyright (c) 2026 Shubham Sharma
...
```
-----
## 15\. Author
**Shubham Sharma**
**GitHub**: [https://github.com/shubham001official](https://github.com/shubham001official)
```
```