README.md

metadata

title: Chronos 2 Forecasting
emoji: 📈
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: apache-2.0

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

   git clone <repository-url>
   cd chronos2-forecasting-app
   

2. Create a virtual environment

   python -m venv venv
   
   # On Windows
   venv\Scripts\activate
   
   # On Linux/Mac
   source venv/bin/activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Run the application

   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

   docker build -t chronos2-forecasting .
   

2. Run the container

   docker run -p 8080:8080 chronos2-forecasting
   

3. With GPU support

   docker run --gpus all -p 8080:8080 chronos2-forecasting
   

Databricks Apps Deployment

1. Upload code to DBFS

   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:

{
  "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.