Metadata-Version: 2.4
Name: universal-forecasting-library
Version: 0.1.0
Summary: A universal forecasting library supporting linear, tree ensemble, and TSFM models.
Author-email: Author Name <author@example.com>
Project-URL: Homepage, https://github.com/yourusername/universal-forecasting-library
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: torch
Requires-Dist: tsfm-public

# Forecasting Library Documentation

The `forecastingLibrary` 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.

## Core Architecture

The library is built around an orchestration layer (`UniversalForecaster`) that delegates tasks to specific forecasting engines that all inherit from a common interface (`BaseForecaster`).

- **`UniversalForecaster`**: The main entry point. It handles data validation, extensive automated feature engineering, train/test splitting for evaluation, and engine dispatch.
- **`BaseForecaster`**: The abstract base class that defines the `fit()` and `predict()` contract for all engines.
- **Engines**:
  - `LinearForecaster`: Wraps Nixtla's `StatsForecast` (AutoARIMA, AutoETS, AutoTheta, SeasonalNaive). Extremely fast and parallelized.
  - `TreeEnsembleForecaster`: A multi-output tree-based model using `LightGBM` wrapped in a `RegressorChain`. Uses shifted targets to predict the entire horizon in one shot without recursive loops.
  - `TSFMForecaster`: Wraps Hugging Face's Time Series Foundation Models (e.g., TinyTimeMixer) for deep learning-based forecasting.

## Key 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 100% 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 (e.g., different `n_estimators` for `tree_ensemble`).

### 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 (Daily, Weekly, Monthly, Hourly).
- **Rolling Statistics**: Rolling mean and standard deviation (volatility) to capture recent trends.

## Usage Guide

### Initialization

```python
from lib.forecastingLibrary.UniversalForecaster 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',  # 'linear', 'tree_ensemble', 'tsfm' (or None to let test_type decide)
    test_type='model',              # 'model' to test architectures, 'param' to test 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, the `LinearForecaster` will automatically inject a dummy ID.

### Training & Predicting

```python
# 1. Fit the forecaster. 
# If test_type is set, this will automatically hold out 10% of data, test, 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()
```

## Adding New Engines

To add a new forecasting engine:
1. Create a new class inheriting from `BaseForecaster`.
2. Implement the `fit(self, df)` method. Ensure it does not modify the original `df` directly (use `.copy()`).
3. Implement the `predict(self)` method to return a DataFrame containing at least an `'Ensemble'` column.
4. Add the new engine to the `_available_forecast_types` and `_init_engine` dispatch dictionary in `UniversalForecaster`.
