| # Chronos 2 Time Series Forecasting Application | |
| A production-ready web application for testing Amazon's **Chronos 2** time series forecasting model using the latest `Chronos2Pipeline` API. Built with Dash for enterprise scalability and designed for both local development and cloud deployment. | |
| ## Features | |
| - **Latest Chronos 2 API**: Uses `Chronos2Pipeline.predict_df()` with DataFrame-based interface | |
| - **Interactive Forecasting**: Generate forecasts up to 365 days with adjustable confidence intervals | |
| - **Dual Model Support**: Switch between Fast (Chronos-Bolt) and Accurate (Chronos-2) variants | |
| - **Multivariate Ready**: Built on Chronos 2 architecture supporting multivariate forecasting | |
| - **Flexible Data Input**: Upload CSV/Excel files or use sample datasets | |
| - **Rich Visualizations**: Interactive Plotly charts with confidence bands and zoom capabilities | |
| - **Data Quality Analysis**: Automatic preprocessing with quality reports | |
| - **GPU Acceleration**: Automatic CUDA support with CPU fallback | |
| - **Security Hardened**: Non-root Docker containers, server-side validation, filename sanitization | |
| - **Production Ready**: Designed for deployment on local machines or Databricks Apps | |
| ## Architecture | |
| Built following best practices for scalability and maintainability: | |
| - **Dash Framework**: Handles thousands of concurrent users | |
| - **Plotly Visualizations**: Smooth rendering of 100K+ data points | |
| - **Model Caching**: Chronos 2 loaded once at startup for fast inference | |
| - **Client-Side State**: Efficient state management without server sessions | |
| - **Modular Design**: Clean separation of components, services, and utilities | |
| ## Installation | |
| ### Prerequisites | |
| - Python 3.10+ | |
| - CUDA-capable GPU (optional, for faster inference) | |
| - 8GB+ RAM (4-8GB for model + overhead) | |
| ### Local Setup | |
| 1. **Clone the repository** | |
| ```bash | |
| git clone <repository-url> | |
| cd chronos2-forecasting-app | |
| ``` | |
| 2. **Create a virtual environment** | |
| ```bash | |
| python -m venv venv | |
| # On Windows | |
| venv\Scripts\activate | |
| # On Linux/Mac | |
| source venv/bin/activate | |
| ``` | |
| 3. **Install dependencies** | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| 4. **Run the application** | |
| ```bash | |
| python app.py | |
| ``` | |
| 5. **Access the app** | |
| Open your browser to `http://127.0.0.1:8050` | |
| ## Usage Guide | |
| ### Quick Start | |
| 1. **Load Sample Data** | |
| - Click one of the sample dataset buttons (Electricity, Retail, Manufacturing) | |
| - Or upload your own CSV/Excel file | |
| 2. **Configure Data** | |
| - Select the date column | |
| - Select the target variable to forecast | |
| - (Optional) Select an ID column for multivariate series | |
| 3. **Set Forecast Parameters** | |
| - Adjust the forecast horizon (1-365 days) | |
| - Select confidence levels (80%, 90%, 95%, 99%) | |
| - Choose model variant (Fast or Accurate) | |
| 4. **Generate Forecast** | |
| - Click "Generate Forecast" button | |
| - Wait for model inference (typically 1-5 seconds) | |
| - View interactive chart with confidence intervals | |
| ### Data Requirements | |
| Your data should have: | |
| - **Date column**: Any standard date format | |
| - **Target column**: Numeric values to forecast | |
| - **Minimum rows**: At least 2x the forecast horizon | |
| - **File size**: Up to 100MB | |
| - **Formats**: CSV, XLSX, XLS | |
| ### Tips for Best Results | |
| - Use at least 2x the forecast horizon in historical data | |
| - Clean your data before upload (though the app handles basic preprocessing) | |
| - Start with the Fast model variant for quick testing | |
| - Use the Accurate variant for final forecasts | |
| - Larger confidence intervals provide more conservative forecasts | |
| ## Project Structure | |
| ``` | |
| chronos2-forecasting-app/ | |
| ├── app.py # Main Dash application | |
| ├── components/ # UI components | |
| │ ├── upload.py # File upload component | |
| │ ├── chart.py # Chart generation | |
| │ └── controls.py # Parameter controls | |
| ├── services/ # Business logic | |
| │ ├── model_service.py # Chronos model wrapper | |
| │ ├── data_processor.py # Data preprocessing | |
| │ └── cache_manager.py # Caching logic | |
| ├── utils/ # Utilities | |
| │ ├── validators.py # Input validation | |
| │ └── metrics.py # Forecast metrics | |
| ├── config/ # Configuration | |
| │ ├── settings.py # Environment settings | |
| │ └── constants.py # App constants | |
| ├── datasets/ # Sample datasets | |
| ├── static/ # Static assets | |
| │ └── custom.css # Custom styles | |
| ├── requirements.txt # Python dependencies | |
| ├── Dockerfile # Container definition | |
| └── README.md # This file | |
| ``` | |
| ## Configuration | |
| ### Environment Variables | |
| - `ENVIRONMENT`: Set to `local` or `production` | |
| - `DEVICE`: Set to `auto`, `cuda`, or `cpu` | |
| - `LOG_LEVEL`: Set to `DEBUG`, `INFO`, `WARNING`, or `ERROR` | |
| - `DATABRICKS_APP_PORT`: Port for Databricks deployment (default: 8080) | |
| ### Local vs Databricks Configuration | |
| The app automatically detects the environment and adjusts settings: | |
| **Local Development:** | |
| - Host: 127.0.0.1 | |
| - Port: 8050 | |
| - Debug: Enabled | |
| - Storage: Local directories | |
| **Databricks Deployment:** | |
| - Host: 0.0.0.0 | |
| - Port: 8080 (or DATABRICKS_APP_PORT) | |
| - Debug: Disabled | |
| - Storage: /tmp and /dbfs | |
| ## Deployment | |
| ### Hugging Face Spaces (Recommended for Free Hosting) | |
| The easiest way to deploy this app for free: | |
| 1. **Create a Hugging Face account** at https://huggingface.co | |
| 2. **Create a new Space** | |
| - Go to https://huggingface.co/spaces | |
| - Click "Create new Space" | |
| - Select "Dash" as the SDK | |
| - Choose a name for your Space | |
| 3. **Upload your code** | |
| - Option A: Connect your GitHub repository (recommended) | |
| - Option B: Upload files directly through the web interface | |
| 4. **Configure the Space** | |
| - The app will automatically use `app.py` as the entry point | |
| - HuggingFace Spaces provides 16GB RAM (sufficient for Chronos-2) | |
| - Optional: Request GPU upgrade for faster inference | |
| 5. **Access your deployed app** | |
| - Your app will be live at: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME` | |
| **Note**: First startup may take 2-3 minutes as the Chronos-2 model downloads (~500MB). | |
| ### Docker Deployment | |
| 1. **Build the image** | |
| ```bash | |
| docker build -t chronos2-forecasting . | |
| ``` | |
| 2. **Run the container** | |
| ```bash | |
| docker run -p 8080:8080 chronos2-forecasting | |
| ``` | |
| 3. **With GPU support** | |
| ```bash | |
| docker run --gpus all -p 8080:8080 chronos2-forecasting | |
| ``` | |
| ### Databricks Apps Deployment | |
| 1. **Upload code to DBFS** | |
| ```bash | |
| databricks fs cp -r . dbfs:/apps/chronos2-forecasting/ | |
| ``` | |
| 2. **Create Databricks App** | |
| - Use the Databricks Apps UI | |
| - Point to the uploaded directory | |
| - Set environment variable: `ENVIRONMENT=production` | |
| 3. **Configure resources** | |
| - Minimum: 8GB RAM | |
| - Recommended: GPU instance for faster inference | |
| ### Production Considerations | |
| - **Memory**: Allocate 6-8GB for the model + overhead | |
| - **Scaling**: Use multiple workers with Gunicorn | |
| - **Monitoring**: Check `/health` endpoint for status | |
| - **Logging**: Logs to stdout for easy collection | |
| - **Timeouts**: Set to 300s+ for large forecasts | |
| ## API Reference | |
| ### Health Check Endpoint | |
| ``` | |
| GET /health | |
| ``` | |
| Returns: | |
| ```json | |
| { | |
| "status": "healthy", | |
| "model_loaded": true, | |
| "model_variant": "fast", | |
| "device": "cuda" | |
| } | |
| ``` | |
| ## Troubleshooting | |
| ### Model Loading Issues | |
| **Problem**: Model fails to load | |
| - Check available memory (need 4-8GB) | |
| - Try CPU mode: Set `DEVICE=cpu` | |
| - Check internet connection (first run downloads model) | |
| ### GPU Not Detected | |
| **Problem**: CUDA device not found | |
| - Verify CUDA installation: `python -c "import torch; print(torch.cuda.is_available())"` | |
| - Install correct PyTorch version for your CUDA | |
| - App will automatically fall back to CPU | |
| ### Upload Failures | |
| **Problem**: File upload fails | |
| - Check file size (<100MB) | |
| - Verify file format (CSV, XLSX, XLS) | |
| - Ensure file is not corrupted | |
| ### Slow Performance | |
| **Problem**: Forecasts take too long | |
| - Use Fast model variant instead of Accurate | |
| - Reduce forecast horizon | |
| - Enable GPU acceleration | |
| - Limit data points (app decimates to 10K for display) | |
| ### Memory Errors | |
| **Problem**: Out of memory during inference | |
| - Switch to Fast model variant (smaller) | |
| - Use CPU instead of GPU | |
| - Reduce batch size in model_service.py | |
| - Close other applications | |
| ## Performance Tuning | |
| ### For Development | |
| - Enable debug mode for detailed logging | |
| - Use Fast model variant | |
| - Work with smaller datasets initially | |
| ### For Production | |
| - Disable debug mode | |
| - Use GPU for inference | |
| - Enable caching (already configured) | |
| - Use Gunicorn with 4 workers | |
| - Set up monitoring and alerting | |
| ## Contributing | |
| Contributions are welcome! Please: | |
| 1. Fork the repository | |
| 2. Create a feature branch | |
| 3. Make your changes | |
| 4. Add tests if applicable | |
| 5. Submit a pull request | |
| ## License | |
| This project is provided as-is for educational and research purposes. | |
| ## Acknowledgments | |
| - **Chronos Model**: Amazon Science | |
| - **Dash Framework**: Plotly | |
| - **Sample Data**: Generated for demonstration purposes | |
| ## Support | |
| For issues, questions, or suggestions: | |
| - Open an issue in the repository | |
| - Check existing documentation | |
| - Review troubleshooting guide above | |
| ## Changelog | |
| ### Version 1.0.1 (Latest - Chronos 2 Full Implementation) | |
| - **BREAKING**: Migrated to Chronos 2 API with `Chronos2Pipeline` | |
| - Fixed deprecated pandas methods (`fillna(method=...)` → `ffill()`/`bfill()`) | |
| - Updated to `chronos-forecasting==2.0.0` package | |
| - Fixed type hints (`any` → `Any`) across all modules | |
| - Added DataFrame-based prediction interface | |
| - Security improvements: | |
| - Non-root user in Docker container | |
| - Server-side file validation | |
| - Filename sanitization | |
| - Health check timeout configuration | |
| - Updated model paths to support Chronos-2 (s3://autogluon/chronos-2) | |
| - Fixed data format compatibility (id/timestamp/target columns) | |
| - Added `requests` library for health checks | |
| ### Version 1.0.0 (Initial Release) | |
| - Chronos 2 model integration | |
| - Single-page Dash application | |
| - CSV/Excel upload support | |
| - Interactive visualizations | |
| - Confidence interval display | |
| - Sample datasets included | |
| - Docker deployment ready | |
| - Databricks Apps compatible | |
| ## Roadmap | |
| Future enhancements being considered: | |
| - Multi-series forecasting UI | |
| - Model comparison features | |
| - Export forecast results | |
| - Custom model fine-tuning | |
| - Real-time data streaming | |
| - Advanced metrics dashboard | |
| - API-only mode for programmatic access | |
| --- | |
| Built with Dash and Chronos 2 for production-ready time series forecasting. | |