Metadata-Version: 2.4
Name: forecaster-ai
Version: 0.3.0
Summary: Enterprise-grade time series forecasting package with ARIMA, Prophet, LSTM models, and advanced decomposition
Author-email: Surya Tripathi <suryaec1099@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/surya08084/forecaster-ai
Project-URL: Documentation, https://forecasting-package.readthedocs.io
Project-URL: Repository, https://github.com/surya08084/forecaster-ai
Project-URL: Bug Tracker, https://github.com/surya08084/forecaster-ai/issues
Keywords: forecasting,time-series,machine-learning,arima,prophet,lstm,mlops
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: statsmodels>=0.14.0
Requires-Dist: prophet>=1.1.0
Requires-Dist: torch>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.23.0
Requires-Dist: mlflow>=2.5.0
Requires-Dist: optuna>=3.3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: holidays>=0.30
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: seaborn>=0.12.0
Requires-Dist: scipy>=1.11.0
Requires-Dist: prometheus-client>=0.17.0
Requires-Dist: python-multipart>=0.0.6
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: ruff>=0.0.280; extra == "dev"
Requires-Dist: mypy>=1.4.0; extra == "dev"
Requires-Dist: pre-commit>=3.3.0; extra == "dev"
Requires-Dist: ipython>=8.14.0; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"
Requires-Dist: notebook>=7.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.1.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.22.0; extra == "docs"
Provides-Extra: all
Requires-Dist: forecasting[dev,docs]; extra == "all"
Dynamic: license-file

# Forecaster-AI 🚀

**Enterprise-grade time series forecasting package with ARIMA, Prophet, LSTM models, and advanced decomposition**

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-0.3.0-green.svg)](https://pypi.org/project/forecaster-ai/)

---

## 📦 Installation

```bash
pip install forecaster-ai
```

**Requirements**: Python 3.9+

---

## ✨ What's New in v0.3.0

🎉 **All Models Now Fully Functional!**

- ✅ **LSTM Forecaster** - Complete implementation with recursive prediction
- ✅ **ARIMA & Auto-ARIMA** - Statistical time series models
- ✅ **Prophet** - Facebook's forecasting tool
- ✅ **Ensemble Methods** - Combine multiple models
- ✅ **Time Series Decomposition** - STL and Classical methods
- ✅ **Special Cases** - Intermittent demand & new product forecasting

---

## 🎯 Quick Start

### Basic Forecasting with ARIMA

```python
import pandas as pd
from forecasting.models import ARIMAForecaster
from forecasting.core.config import ForecastConfig

# Your time series data
data = pd.Series([100, 105, 110, 108, 115, 120, 118, 125, 130, 128])

# Configure forecast
config = ForecastConfig(
    horizon=5,              # Forecast 5 periods ahead
    confidence_level=0.95   # 95% confidence intervals
)

# Create and fit model
forecaster = ARIMAForecaster(config, order=(2, 1, 2))
forecaster.fit(data)

# Generate forecast
forecast, conf_int = forecaster.predict()

print("Forecast:", forecast)
print("Confidence Intervals:", conf_int)
```

---

## 📚 Complete Model Guide

### 1. ARIMA Forecaster

**Best for**: Stationary time series, short-term forecasts

```python
from forecasting.models import ARIMAForecaster
from forecasting.core.config import ForecastConfig

config = ForecastConfig(horizon=30)

# Manual parameter specification
forecaster = ARIMAForecaster(
    config=config,
    order=(2, 1, 2),              # (p, d, q)
    seasonal_order=(1, 1, 1, 7),  # (P, D, Q, s) - weekly seasonality
    trend='c'                      # constant trend
)

forecaster.fit(data)
forecast, conf_int = forecaster.predict(horizon=30)

# Get model metrics
metrics = forecaster.get_validation_metrics()
print(f"AIC: {metrics['aic']}, BIC: {metrics['bic']}")
```

### 2. Auto-ARIMA Forecaster

**Best for**: Automatic parameter selection, exploratory analysis

```python
from forecasting.models import AutoARIMAForecaster

config = ForecastConfig(horizon=30)

# Automatic parameter selection
forecaster = AutoARIMAForecaster(
    config=config,
    seasonal=True,
    m=7,                    # Seasonal period (7 for weekly)
    max_p=5,                # Max AR order
    max_q=5,                # Max MA order
    max_d=2,                # Max differencing
    information_criterion='aic',
    stepwise=True           # Faster search
)

forecaster.fit(data)
forecast, conf_int = forecaster.predict()

# See selected parameters
metrics = forecaster.get_validation_metrics()
print(f"Selected order: {metrics['order']}")
print(f"Seasonal order: {metrics['seasonal_order']}")
```

### 3. Prophet Forecaster

**Best for**: Daily/weekly data with strong seasonality, holidays

```python
from forecasting.models import ProphetForecaster

config = ForecastConfig(horizon=90)

forecaster = ProphetForecaster(
    config=config,
    growth='linear',                    # or 'logistic'
    changepoint_prior_scale=0.05,       # Trend flexibility
    seasonality_prior_scale=10.0,       # Seasonality strength
    seasonality_mode='additive',        # or 'multiplicative'
    yearly_seasonality='auto',
    weekly_seasonality='auto',
    daily_seasonality=False
)

forecaster.fit(data)
forecast, conf_int = forecaster.predict(horizon=90)

# Add custom seasonality
forecaster.add_seasonality(
    name='monthly',
    period=30.5,
    fourier_order=5
)

# Add holidays
forecaster.add_country_holidays('US')
```

### 4. LSTM Forecaster

**Best for**: Complex patterns, long sequences, multivariate data

```python
from forecasting.models import LSTMForecaster

config = ForecastConfig(horizon=30, random_seed=42)

forecaster = LSTMForecaster(
    config=config,
    lookback=30,                # Use last 30 points
    hidden_size=64,             # LSTM hidden units
    num_layers=2,               # Number of LSTM layers
    dropout=0.2,                # Dropout rate
    use_attention=True,         # Attention mechanism
    learning_rate=0.001,
    batch_size=32,
    epochs=100,
    early_stopping_patience=10
)

# Fit with validation split
forecaster.fit(data, validation_split=0.2)

# Generate forecast
forecast, conf_int = forecaster.predict(horizon=30)

# Check training metrics
metrics = forecaster.get_validation_metrics()
print(f"Final validation loss: {metrics['final_val_loss']}")
print(f"Epochs trained: {metrics['epochs_trained']}")

# Plot training history
fig = forecaster.plot_training_history()
```

### 5. Ensemble Forecaster

**Best for**: Combining multiple models for better accuracy

```python
from forecasting.models import (
    EnsembleForecaster,
    ARIMAForecaster,
    ProphetForecaster
)

config = ForecastConfig(horizon=30)

# Create individual models
arima = ARIMAForecaster(config, order=(2, 1, 2))
prophet = ProphetForecaster(config)

# Create ensemble
ensemble = EnsembleForecaster(
    config=config,
    models=[arima, prophet],
    weights=[0.6, 0.4],      # 60% ARIMA, 40% Prophet
    aggregation='weighted'    # 'mean', 'median', or 'weighted'
)

# Fit all models
ensemble.fit(data)

# Generate ensemble forecast
forecast, conf_int = ensemble.predict()

# Check model weights
weights = ensemble.get_model_weights()
print(weights)
```

---

## 🔧 Advanced Features

### Time Series Decomposition

```python
from forecasting.data.preprocessors import TimeSeriesDecomposer

# STL Decomposition
decomposer = TimeSeriesDecomposer(method='stl', period=7)
trend, seasonal, residual = decomposer.fit_transform(data)

# Classical Decomposition
decomposer = TimeSeriesDecomposer(method='classical', period=12)
components = decomposer.fit_transform(data)

# Reconstruct original series
reconstructed = decomposer.inverse_transform(trend, seasonal, residual)
```

### Data Preprocessing

```python
from forecasting.data.preprocessors import TimeSeriesPreprocessor

preprocessor = TimeSeriesPreprocessor(
    handle_missing='interpolate',
    handle_outliers=True,
    outlier_method='iqr',
    normalize=True,
    decompose=True,
    decomposition_method='stl'
)

# Preprocess data
processed_data = preprocessor.fit_transform(data)

# Inverse transform predictions
original_scale = preprocessor.inverse_transform(predictions)
```

### Intermittent Demand Forecasting

```python
from forecasting.data.special_cases import IntermittentDemandHandler

# For sparse/intermittent data (many zeros)
handler = IntermittentDemandHandler(method='sba')  # or 'croston', 'tsb'
handler.fit(sparse_data)
forecast = handler.predict(horizon=12)
```

### New Product Forecasting

```python
from forecasting.data.special_cases import NewProductHandler

# For products with little/no history
handler = NewProductHandler(method='bootstrap')
handler.fit(similar_products_data)
forecast = handler.predict(horizon=12)
```

### Data Validation

```python
from forecasting.data.validators import TimeSeriesValidator

validator = TimeSeriesValidator()

# Validate data quality
is_valid, errors = validator.validate(data)
if not is_valid:
    print("Validation errors:", errors)

# Check stationarity
is_stationary, p_value = validator.check_stationarity(data)
print(f"Stationary: {is_stationary}, p-value: {p_value}")

# Detect outliers
outliers = validator.detect_outliers(data, method='iqr')
print(f"Found {len(outliers)} outliers")

# Check seasonality
has_seasonality, period = validator.detect_seasonality(data)
print(f"Seasonality: {has_seasonality}, period: {period}")
```

---

## 📊 Model Comparison Example

```python
import numpy as np
from forecasting.models import ARIMAForecaster, ProphetForecaster, LSTMForecaster
from forecasting.core.config import ForecastConfig

# Split data
train_data = data[:-30]
test_data = data[-30:]

config = ForecastConfig(horizon=30)

# Train multiple models
models = {
    'ARIMA': ARIMAForecaster(config, order=(2, 1, 2)),
    'Prophet': ProphetForecaster(config),
    'LSTM': LSTMForecaster(config, lookback=30, epochs=50)
}

results = {}
for name, model in models.items():
    model.fit(train_data)
    forecast, _ = model.predict()
    mae = np.mean(np.abs(forecast.values - test_data.values))
    results[name] = mae
    print(f"{name} MAE: {mae:.2f}")

# Find best model
best_model = min(results, key=results.get)
print(f"\nBest model: {best_model}")
```

---

## 💾 Model Persistence

```python
# Save model
forecaster.save_model('my_model.pkl')

# Load model
from forecasting.models import ARIMAForecaster
loaded_forecaster = ARIMAForecaster.load_model('my_model.pkl')

# Use loaded model
forecast, conf_int = loaded_forecaster.predict(horizon=30)
```

---

## 🎨 Visualization

```python
import matplotlib.pyplot as plt

# Plot forecast
plt.figure(figsize=(12, 6))
plt.plot(data.index, data.values, label='Historical', color='blue')
plt.plot(forecast.index, forecast.values, label='Forecast', color='red')
plt.fill_between(
    conf_int.index,
    conf_int['lower'],
    conf_int['upper'],
    alpha=0.3,
    color='red',
    label='95% CI'
)
plt.legend()
plt.title('Time Series Forecast')
plt.xlabel('Date')
plt.ylabel('Value')
plt.grid(True)
plt.show()
```

---

## 📖 Configuration Options

```python
from forecasting.core.config import ForecastConfig, PreprocessingConfig

# Forecast configuration
config = ForecastConfig(
    horizon=30,                    # Forecast periods
    confidence_level=0.95,         # Confidence interval level
    frequency='D',                 # Data frequency
    random_seed=42,                # Reproducibility
    preprocessing=PreprocessingConfig(
        handle_missing='interpolate',
        handle_outliers=True,
        normalize=True,
        decompose=True,
        decomposition_method='stl',
        seasonal_period=7
    )
)
```

---

## 🚀 Performance Tips

### 1. **For Large Datasets**
```python
# Use Auto-ARIMA with stepwise search
forecaster = AutoARIMAForecaster(config, stepwise=True, max_p=3, max_q=3)
```

### 2. **For Fast Training**
```python
# Reduce LSTM epochs and use early stopping
forecaster = LSTMForecaster(
    config,
    epochs=50,
    early_stopping_patience=5,
    batch_size=64
)
```

### 3. **For Better Accuracy**
```python
# Use ensemble with multiple models
ensemble = EnsembleForecaster(
    config,
    models=[arima, prophet, lstm],
    aggregation='weighted'
)
```

---

## 🔍 Troubleshooting

### Issue: "Model not converging"
```python
# Solution: Adjust parameters or preprocess data
from forecasting.data.preprocessors import TimeSeriesPreprocessor

preprocessor = TimeSeriesPreprocessor(
    normalize=True,
    handle_outliers=True
)
clean_data = preprocessor.fit_transform(data)
```

### Issue: "Poor forecast accuracy"
```python
# Solution: Try ensemble or different model
ensemble = EnsembleForecaster(
    config,
    models=[model1, model2, model3],
    aggregation='mean'
)
```

### Issue: "LSTM training too slow"
```python
# Solution: Reduce complexity or use GPU
forecaster = LSTMForecaster(
    config,
    hidden_size=32,      # Reduce from 64
    num_layers=1,        # Reduce from 2
    epochs=30,           # Reduce from 100
    device='cuda'        # Use GPU if available
)
```

---

## 📦 Dependencies

Core dependencies (automatically installed):
- `numpy>=1.24.0`
- `pandas>=2.0.0`
- `scikit-learn>=1.3.0`
- `statsmodels>=0.14.0`
- `torch>=2.0.0`
- `prophet>=1.1.0`
- `pmdarima>=2.0.0`

---

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

## 📄 License

This project is licensed under the MIT License.

---

## 📧 Contact

**Author**: Surya Tripathi  
**Email**: suryaec1099@gmail.com

---

## 🙏 Acknowledgments

Built with:
- [statsmodels](https://www.statsmodels.org/) for ARIMA
- [Prophet](https://facebook.github.io/prophet/) by Facebook
- [PyTorch](https://pytorch.org/) for LSTM
- [pmdarima](http://alkaline-ml.com/pmdarima/) for Auto-ARIMA

---

## 📚 Additional Resources

- [Complete Examples](examples/complete_model_examples.py)
- [Quick Start Guide](QUICK_START_USAGE.md)
- [Migration Guide](MIGRATION_GUIDE.md)
- [Implementation Status](../IMPLEMENTATION_STATUS.md)

---

**Made with ❤️ by Bob**
