{"id":37419836,"url":"https://github.com/alessiosavi/demand-forecast","last_synced_at":"2026-01-16T06:05:27.346Z","repository":{"id":330382251,"uuid":"906693064","full_name":"alessiosavi/demand-forecast","owner":"alessiosavi","description":"A Torch network that leverages time series and product metadata to perform demand-forecast","archived":false,"fork":false,"pushed_at":"2025-12-25T03:42:11.000Z","size":37121,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-26T17:24:59.293Z","etag":null,"topics":["demand-forecasting","pytorch","timeseries-forecasting"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alessiosavi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-21T16:19:41.000Z","updated_at":"2025-10-10T15:14:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alessiosavi/demand-forecast","commit_stats":null,"previous_names":["alessiosavi/demand-forecast"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/alessiosavi/demand-forecast","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alessiosavi%2Fdemand-forecast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alessiosavi%2Fdemand-forecast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alessiosavi%2Fdemand-forecast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alessiosavi%2Fdemand-forecast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alessiosavi","download_url":"https://codeload.github.com/alessiosavi/demand-forecast/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alessiosavi%2Fdemand-forecast/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T03:13:13.607Z","status":"ssl_error","status_checked_at":"2026-01-16T03:11:47.863Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["demand-forecasting","pytorch","timeseries-forecasting"],"created_at":"2026-01-16T06:05:27.264Z","updated_at":"2026-01-16T06:05:27.332Z","avatar_url":"https://github.com/alessiosavi.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Demand Forecast\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg)](https://pytorch.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n\nA production-ready demand forecasting system using state-of-the-art Transformer neural networks. Predicts SKU-level demand with confidence intervals, supporting multiple time series clustering, categorical feature embeddings, and advanced architectures including TFT, PatchTST, and lightweight models for CPU deployment.\n\n## Features\n\n- **Multiple Model Architectures**:\n  - **Standard**: Transformer encoder-decoder with optional improvements (RoPE, Pre-LN, FiLM, stochastic depth)\n  - **Advanced (V2)**: Research-grade model with TFT-style variable selection, PatchTST embeddings, and quantile forecasting\n  - **Lightweight**: CPU-optimized models (TCN, MLP-Mixer) for edge deployment with ONNX export\n- **Hyperparameter Tuning**: Optuna integration for automated hyperparameter optimization\n- **Multi-Cluster Training**: Automatic time series clustering with separate models per cluster\n- **Categorical Embeddings**: Dynamic embedding layers for product attributes (color, size, category, etc.)\n- **Uncertainty Quantification**: Quantile forecasting and confidence intervals\n- **CLI Interface**: Easy-to-use command-line tools for training, evaluation, tuning, and prediction\n- **Configurable Pipeline**: YAML-based configuration for all hyperparameters\n- **Production Ready**: Proper logging, error handling, type hints, and comprehensive test suite\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/alessiosavi/demand-forecast.git\ncd demand-forecast\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# For ONNX export support (lightweight models)\npip install -e \".[deploy]\"\n```\n\n### Generate Sample Data\n\n```bash\ndemand-forecast generate-data sample_data.csv --products 50 --stores 10 --days 730\n```\n\n### Train a Model\n\n```bash\n# Copy and customize the example configuration\ncp config.example.yaml config.yaml\n\n# Train the standard model\ndemand-forecast train --config config.yaml\n\n# Train with advanced model\ndemand-forecast train --config config.yaml --model-type advanced\n\n# Train with lightweight model for CPU deployment\ndemand-forecast train --config config.yaml --model-type lightweight\n```\n\n### Hyperparameter Tuning\n\n```bash\n# Run Optuna hyperparameter tuning\ndemand-forecast tune --config config.yaml --n-trials 50 --timeout 3600\n```\n\n### Generate Predictions\n\n```bash\ndemand-forecast predict models/model.pt input_data.csv --config config.yaml --output predictions.csv\n```\n\n## Model Architectures\n\n### Standard Model (`AdvancedDemandForecastModel`)\n\nClassic Transformer encoder-decoder with optional modern improvements:\n\n| Feature | Description |\n|---------|-------------|\n| **RoPE** | Rotary Position Embeddings for better sequence modeling |\n| **Pre-LayerNorm** | Improved training stability |\n| **FiLM Conditioning** | Feature-wise Linear Modulation for static features |\n| **Stochastic Depth** | Regularization through random layer dropping |\n| **Improved Head** | GELU activation in output projection |\n\n### Advanced Model V2 (`AdvancedDemandForecastModelV2`)\n\nResearch-grade architecture combining state-of-the-art techniques:\n\n- **Variable Selection Networks (VSN)**: TFT-style feature importance learning\n- **Gated Residual Networks (GRN)**: Enhanced information flow\n- **Patch Embedding**: PatchTST-style time series tokenization\n- **Series Decomposition**: Autoformer-style trend/seasonality separation\n- **Quantile Output**: Probabilistic forecasting with uncertainty\n\n### Lightweight Models\n\nCPU-optimized architectures for edge deployment:\n\n| Model | Description | Parameters |\n|-------|-------------|------------|\n| `LightweightDemandModel` | TCN + FiLM conditioning | \u003c 1M |\n| `LightweightMixerModel` | MLP-Mixer architecture | \u003c 500K |\n\nFeatures:\n- ONNX export for optimized inference\n- TorchScript compilation\n- INT8 quantization support\n\n## Architecture Overview\n\n```text\ndemand_forecast/\n├── cli.py                 # Typer CLI commands\n├── config/settings.py     # Pydantic configuration models\n├── core/\n│   ├── pipeline.py        # Main orchestration\n│   ├── trainer.py         # Training loop with callbacks\n│   ├── evaluator.py       # Validation and metrics\n│   └── tuning.py          # Optuna hyperparameter tuning\n├── data/\n│   ├── loader.py          # Data loading with validation\n│   ├── preprocessor.py    # Scaling, filtering, resampling\n│   ├── feature_engineering.py  # Categorical encoding\n│   └── dataset.py         # PyTorch Dataset\n├── models/\n│   ├── transformer.py     # Standard model with improvements\n│   ├── transformer_v2.py  # Advanced research-grade model\n│   ├── lightweight.py     # CPU-optimized models\n│   ├── components.py      # Reusable building blocks\n│   ├── losses.py          # Loss functions (Huber, quantile, SMAPE)\n│   └── wrapper.py         # Multi-cluster ModelWrapper + factory\n├── inference/\n│   ├── predictor.py       # Prediction wrapper\n│   └── confidence.py      # Confidence interval calculation\n└── utils/                 # Utilities (clustering, metrics, etc.)\n```\n\n## Configuration\n\nThe system is configured via YAML files. See `config.example.yaml` for all options:\n\n```yaml\ndata:\n  input_path: \"sales_data.csv\"\n  resample_period: \"1W\"        # Weekly aggregation\n  max_zeros_ratio: 0.7         # Filter sparse SKUs\n\ntimeseries:\n  window: 52                   # 52-week lookback\n  n_out: 16                    # 16-week forecast horizon\n\nmodel:\n  model_type: \"standard\"       # standard, advanced, or lightweight\n  d_model: 256                 # Transformer dimension\n  nhead: 8                     # Attention heads\n  num_encoder_layers: 4\n  num_decoder_layers: 4\n  dropout: 0.3\n  # Optional improvements\n  use_rope: false              # Rotary Position Embeddings\n  use_pre_layernorm: false     # Pre-LN for stability\n  use_film_conditioning: false # FiLM for static features\n  stochastic_depth_rate: 0.0   # Stochastic depth regularization\n\ntraining:\n  num_epochs: 10\n  batch_size: 128\n  learning_rate: 0.00001\n  early_stop_patience: 3\n\ntuning:\n  enabled: false\n  n_trials: 50\n  timeout: 3600                # 1 hour timeout\n  metric: \"mse\"                # Optimize MSE\n  sampler: \"tpe\"               # TPE sampler\n```\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `train` | Train the demand forecasting model |\n| `evaluate` | Evaluate a trained model on test data |\n| `predict` | Generate predictions with confidence intervals |\n| `tune` | Run Optuna hyperparameter tuning |\n| `generate-data` | Generate synthetic sales data for testing |\n| `preprocess` | Preprocess raw data and save as Parquet |\n| `version` | Show version information |\n\n### Common Options\n\nAll commands support `--verbose` (`-v`) for debug logging.\n\n**Training with visualization:**\n```bash\ndemand-forecast train --config config.yaml --plot --plot-dir plots/training\n```\n\n**Hyperparameter tuning:**\n```bash\ndemand-forecast tune --config config.yaml --n-trials 100 --metric mae\n```\n\n**Evaluation with metrics export:**\n```bash\ndemand-forecast evaluate models/model.pt data.csv --config config.yaml \\\n    --output metrics.json --plot\n```\n\n**Prediction with confidence intervals and plots:**\n```bash\ndemand-forecast predict models/model.pt data.csv --config config.yaml \\\n    --output predictions.csv --confidence 0.95 --plot\n```\n\nRun `demand-forecast --help` for detailed usage information.\n\n## Hyperparameter Tuning\n\nThe system includes Optuna integration for automated hyperparameter optimization:\n\n```python\nfrom demand_forecast.core.tuning import HyperparameterTuner, TuningConfig, SearchSpace\n\n# Define search space\nsearch_space = SearchSpace(\n    d_model=[64, 128, 256],\n    nhead=[4, 8],\n    num_layers=(1, 6),\n    dropout=(0.1, 0.5),\n    learning_rate=(1e-5, 1e-3),\n)\n\n# Configure tuning\nconfig = TuningConfig(\n    n_trials=50,\n    timeout=3600,\n    metric=\"mse\",\n    direction=\"minimize\",\n)\n\n# Run tuning\ntuner = HyperparameterTuner(config, search_space)\nbest_params = tuner.tune(train_data, val_data)\n```\n\nOr use the convenience function:\n\n```python\nfrom demand_forecast.core.tuning import quick_tune\n\nbest_params = quick_tune(\n    train_dataloader=train_dl,\n    val_dataloader=val_dl,\n    n_trials=20,\n)\n```\n\n## Model Details\n\n### Transformer Encoder-Decoder\n\nThe model uses a Transformer architecture optimized for time series:\n\n1. **Static Embeddings**: SKU and categorical features are embedded and projected\n2. **Encoder**: Processes historical sales with positional encoding\n3. **Decoder**: Generates forecasts with causal masking and cross-attention\n4. **Multi-Cluster**: Separate model per cluster for heterogeneous demand patterns\n\n### New Components\n\n| Component | Description |\n|-----------|-------------|\n| `RotaryPositionEmbedding` | RoPE for better long-range dependencies |\n| `GatedResidualNetwork` | TFT-style gated residual connections |\n| `VariableSelectionNetwork` | Learnable feature importance |\n| `PatchEmbedding` | PatchTST-style time series tokenization |\n| `SeriesDecomposition` | Autoformer trend/seasonality separation |\n| `FiLMConditioning` | Feature-wise Linear Modulation |\n| `TemporalConvNet` | Dilated causal convolutions |\n| `InterpretableMultiHeadAttention` | TFT-style interpretable attention |\n\n### Loss Functions\n\n- **HuberLoss**: Robust to outliers (default)\n- **QuantileLoss**: For probabilistic forecasting\n- **CombinedForecastLoss**: Huber + quantile + decomposition\n- **SMAPELoss**: Symmetric MAPE for percentage errors\n- **MASELoss**: Mean Absolute Scaled Error\n\n### Clustering\n\nTime series are clustered using K-means on TSFresh meta-features. The optimal K is selected via the elbow method with Davies-Bouldin Index validation.\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\npytest\n\n# Run linting\nruff check .\nmypy demand_forecast/\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=demand_forecast\n\n# Run specific test categories\npytest tests/test_models/           # Model tests\npytest tests/test_models/test_tuning.py  # Tuning tests\n```\n\n### Project Structure\n\n```\ndemand-forecast/\n├── demand_forecast/       # Main package\n├── tests/                 # Test suite\n│   ├── test_models/       # Model and tuning tests\n│   ├── test_core/         # Core module tests\n│   └── test_utils/        # Utility tests\n├── docs/                  # Documentation\n├── config.example.yaml    # Example configuration\n├── pyproject.toml         # Project metadata\n└── Makefile              # Development commands\n```\n\n## Documentation\n\n- [Architecture Guide](docs/ARCHITECTURE.md) - System design and component details\n- [API Reference](docs/API.md) - Module and class documentation\n- [Configuration Guide](docs/CONFIGURATION.md) - All configuration options\n- [Quick Start Guide](docs/QUICKSTART.md) - Step-by-step tutorial\n- [Development Guide](docs/DEVELOPMENT.md) - Contributing and development setup\n\n## Requirements\n\n- Python 3.10+\n- PyTorch 2.0+\n- Optuna 3.0+ (for hyperparameter tuning)\n- CUDA (optional, for GPU acceleration)\n\nSee `pyproject.toml` for complete dependency list.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Citation\n\nIf you use this software in your research, please cite:\n\n```bibtex\n@software{demand_forecast,\n  title = {Demand Forecast: Transformer-based Time Series Forecasting},\n  year = {2025},\n  url = {https://github.com/alessiosavi/demand-forecast}\n}\n```\n\n## Acknowledgments\n\n- Built with [PyTorch](https://pytorch.org/)\n- Hyperparameter tuning with [Optuna](https://optuna.org/)\n- Configuration via [Pydantic](https://docs.pydantic.dev/)\n- CLI powered by [Typer](https://typer.tiangolo.com/)\n- Feature extraction with [TSFresh](https://tsfresh.readthedocs.io/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falessiosavi%2Fdemand-forecast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falessiosavi%2Fdemand-forecast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falessiosavi%2Fdemand-forecast/lists"}