Metadata-Version: 2.4
Name: universal-forecasting-library
Version: 0.1.4
Summary: A universal forecasting library supporting linear, tree ensemble, and TSFM models.
Author-email: Alexander Simon Wong <alexanderwong30@gmail.com>
Project-URL: Homepage, https://github.com/kentalkental
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: holidays
Requires-Dist: lightgbm
Provides-Extra: tsfm
Requires-Dist: torch; extra == "tsfm"
Requires-Dist: granite-tsfm; extra == "tsfm"
Provides-Extra: stats
Requires-Dist: statsforecast; extra == "stats"

# Universal Forecasting Library

The `universal-forecasting-library` is a unified, "zero-shot" forecasting framework designed to provide a seamless interface for multiple time-series forecasting architectures. It abstracts away the complexity of data preparation, feature engineering, and hyperparameter tuning.

## Installation

You can install the package directly via pip. By default, this performs a lightweight installation (uses `scikit-learn` and `lightgbm`, avoiding heavy deep learning models or C++ compilation).

```bash
# Lightweight Install (Linear & Tree Ensemble)
pip install universal-forecasting-library

# Full Install (Includes TSFM and StatsForecast)
pip install universal-forecasting-library[tsfm,stats]
```

## Available Forecasters

The library uses an orchestration layer (`UniversalForecaster`) to dispatch work to specific forecasting engines. Here is a quick summary of what each engine does:

- **LinearForecaster (`linear`)**: Fast baseline. Uses `scikit-learn` (Ridge regression) coupled with automatic feature engineering. Installs flawlessly everywhere.
- **StatsForecaster (`stats`)**: Fast, classical statistical models. It wraps `StatsForecast` (AutoARIMA, AutoETS, AutoTheta, and SeasonalNaive). Requires the `[stats]` installation.
- **TreeEnsembleForecaster (`tree_ensemble`)**: Machine learning approach. Uses LightGBM wrapped in a multi-output RegressorChain. It automatically builds complex features (lags, rolling stats, holidays) and predicts the entire future horizon in one shot. Best for complex datasets where feature engineering shines.
- **TSFMForecaster (`tsfm`)**: Deep learning approach. Wraps Hugging Face's Time Series Foundation Models (like TinyTimeMixer). Uses massive pre-trained neural networks to perform zero-shot forecasting on your data. Best for discovering complex patterns without manual feature tuning.

## Usage Guide

### Initialization

Import the orchestrator and initialize your forecasting session:

```python
from universal_forecaster import UniversalForecaster

forecast = UniversalForecaster(
    input_windows=36,               # Lookback window (used primarily by TSFM)
    horizon=18,                     # The number of steps into the future to predict
    forecast_type='tree_ensemble',  # Choose from: 'linear', 'tree_ensemble', 'tsfm'
    test_type='model',              # (Optional) 'model' to test architectures, 'param' for hyperparameters
    tsfm_model_path="./local_ttm"   # Path to local foundation model weights (if using TSFM)
)
```

### Data Format Requirements
The input data must be a Pandas DataFrame containing at minimum:
- `ds`: The datetime column.
- `y`: The numeric target variable to forecast.
- `unique_id` *(Optional)*: An identifier for multi-series forecasting. If omitted, a dummy ID is injected automatically.

### Training & Predicting

```python
import pandas as pd

# Example Data
df_train = pd.DataFrame({
    'ds': pd.date_range('2023-01-01', periods=100),
    'y': range(100)
})

# 1. Fit the forecaster. 
# If test_type is set, this will automatically hold out 10% of data, evaluate configurations, and retrain on 100%.
forecast.fit(df_train)

# 2. Predict the horizon
# Returns a DataFrame with an 'Ensemble' column containing the predictions
predictions_df = forecast.predict()
print(predictions_df)
```

## Advanced Features

### 1. Auto-Testing & Model Selection (`test_type`)
The framework can automatically evaluate multiple configurations on a chronologically held-out 10% validation set, pick the best one using Mean Absolute Error (MAE), and seamlessly retrain on the full dataset.
- `test_type='model'`: Tests between different architectural families (e.g., `linear` vs `tree_ensemble`).
- `test_type='param'`: Tests different hyperparameter grids for a specific architecture.

### 2. Automated Feature Engineering
When using non-linear models (like `tree_ensemble`), the `UniversalForecaster` automatically generates:
- **Cyclical Calendar Features**: Sine/Cosine transformations of day-of-week, month, and hour.
- **Holiday Features**: Automatic integration with `holidays` (currently configured for Indonesia).
- **Lag Features**: Auto-scaled lag features based on the detected frequency.
- **Rolling Statistics**: Rolling mean and standard deviation (volatility) to capture recent trends.
