Metadata-Version: 2.4
Name: forecaster-ai
Version: 0.2.1
Summary: Enterprise-grade time series forecasting package with ARIMA, Prophet, and LSTM models
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

# Forecasting Package 📈

[![CI](https://github.com/username/forecasting-package/workflows/CI/badge.svg)](https://github.com/username/forecasting-package/actions)
[![codecov](https://codecov.io/gh/username/forecasting-package/branch/main/graph/badge.svg)](https://codecov.io/gh/username/forecasting-package)
[![PyPI version](https://badge.fury.io/py/forecasting-package.svg)](https://badge.fury.io/py/forecasting-package)
[![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)
[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://docs.forecasting-package.example.com)

An enterprise-grade time series forecasting package with MLOps capabilities, supporting multiple forecasting models, automated hyperparameter tuning, and production-ready deployment.

## ✨ Features

### 🎯 Core Capabilities
- **Multiple Forecasting Models**: ARIMA, Prophet, LSTM, and Ensemble methods
- **Automated Model Selection**: AutoML with hyperparameter optimization
- **Data Validation**: Comprehensive data quality checks and preprocessing
- **Feature Engineering**: Automated temporal and Fourier feature generation
- **Evaluation Framework**: Backtesting, cross-validation, and comprehensive metrics

### 🚀 MLOps Integration
- **Experiment Tracking**: MLflow integration for experiment management
- **Model Registry**: Version control and model lifecycle management
- **Performance Monitoring**: Real-time model performance and drift detection
- **A/B Testing**: Compare multiple models in production

### 🌐 Production Ready
- **REST API**: FastAPI-based prediction and training endpoints
- **Docker Support**: Containerized deployment with docker-compose
- **CI/CD Pipeline**: Automated testing, building, and deployment
- **Monitoring**: Prometheus and Grafana integration
- **Scalability**: Horizontal scaling support

## 📦 Installation

### Using pip

```bash
pip install forecasting-package
```

### From source

```bash
git clone https://github.com/surya08084/frcst.git
cd forecasting-package
pip install -e .
```

### Using Docker

```bash
docker pull ghcr.io/username/forecasting-package:latest
docker run -p 8000:8000 ghcr.io/username/forecasting-package:latest
```

## 🚀 Quick Start

### Basic Usage

```python
import pandas as pd
from forecasting.models.arima import ARIMAForecaster
from forecasting.data.validators import TimeSeriesValidator
from forecasting.evaluation.metrics import ForecastMetrics

# Load your time series data
df = pd.read_csv('data.csv', parse_dates=['date'])

# Validate data
validator = TimeSeriesValidator()
is_valid, issues = validator.validate(df['value'])

# Create and train model
model = ARIMAForecaster(order=(1, 1, 1))
model.fit(df['value'].values)

# Make predictions
forecast = model.predict(steps=30)

# Evaluate
metrics = ForecastMetrics()
mae = metrics.mae(df['value'][-30:], forecast)
print(f"MAE: {mae}")
```

### Using Prophet

```python
from forecasting.models.prophet import ProphetForecaster

# Create Prophet model with custom seasonality
model = ProphetForecaster(
    seasonality_mode='multiplicative',
    yearly_seasonality=True,
    weekly_seasonality=True
)

# Fit with exogenous variables
model.fit(
    y=df['value'].values,
    dates=df['date'].values,
    exog=df[['temperature', 'holiday']].values
)

# Forecast with confidence intervals
forecast, lower, upper = model.predict(steps=30, return_conf_int=True)
```

### Using LSTM

```python
from forecasting.models.lstm import LSTMForecaster

# Create LSTM model
model = LSTMForecaster(
    hidden_size=64,
    num_layers=2,
    dropout=0.2,
    learning_rate=0.001
)

# Train model
model.fit(
    y=df['value'].values,
    epochs=100,
    batch_size=32,
    validation_split=0.2
)

# Predict
forecast = model.predict(steps=30)
```

### Ensemble Methods

```python
from forecasting.models.ensemble import EnsembleForecaster
from forecasting.models.arima import ARIMAForecaster
from forecasting.models.prophet import ProphetForecaster

# Create ensemble
ensemble = EnsembleForecaster(
    models=[
        ARIMAForecaster(order=(1, 1, 1)),
        ProphetForecaster()
    ],
    weights=[0.6, 0.4]  # Optional custom weights
)

# Train and predict
ensemble.fit(df['value'].values)
forecast = ensemble.predict(steps=30)
```

### AutoML

```python
from forecasting.models.tuning import AutoML

# Automated model selection and tuning
automl = AutoML(
    models=['arima', 'prophet', 'lstm'],
    metric='rmse',
    cv_folds=5
)

# Find best model
best_model = automl.fit(df['value'].values)

# Use best model
forecast = best_model.predict(steps=30)
```

## 🔧 Advanced Usage

### Data Preprocessing

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

# Preprocess data
preprocessor = TimeSeriesPreprocessor()
df_clean = preprocessor.handle_missing_values(df)
df_scaled, scaler = preprocessor.scale_data(df_clean)

# Engineer features
engineer = FeatureEngineer()
df_features = engineer.create_temporal_features(df_scaled)
df_features = engineer.create_fourier_features(df_features, n_terms=3)
```

### Backtesting

```python
from forecasting.evaluation.backtesting import RollingOriginBacktester

# Setup backtester
backtester = RollingOriginBacktester(
    initial_window=100,
    horizon=10,
    step=1
)

# Run backtest
results = backtester.run(model, df['value'].values)

# Analyze results
print(f"Average RMSE: {results['avg_rmse']}")
print(f"Average MAE: {results['avg_mae']}")
```

### MLflow Integration

```python
from forecasting.mlops.tracking import ExperimentTracker
from forecasting.mlops.registry import ModelRegistry

# Track experiments
tracker = ExperimentTracker(
    experiment_name='sales_forecasting',
    tracking_uri='http://localhost:5000'
)

with tracker.start_run():
    # Train model
    model.fit(df['value'].values)
    
    # Log parameters
    tracker.log_params({'order': (1, 1, 1)})
    
    # Log metrics
    tracker.log_metrics({'rmse': 10.5, 'mae': 8.2})
    
    # Log model
    tracker.log_model(model, 'arima_model')

# Register model
registry = ModelRegistry(tracking_uri='http://localhost:5000')
version = registry.register_model(
    model_name='sales_forecaster',
    model=model,
    metadata={'dataset': 'sales_2024'}
)
```

## 🌐 API Usage

### Start API Server

```bash
# Using uvicorn
uvicorn forecasting.api.main:app --host 0.0.0.0 --port 8000

# Using Docker
docker-compose up -d
```

### Make Predictions

```python
import requests

# Predict endpoint
response = requests.post(
    'http://localhost:8000/api/v1/predict',
    json={
        'model_name': 'sales_forecaster',
        'steps': 30,
        'confidence_level': 0.95
    }
)

forecast = response.json()
print(forecast['predictions'])
```

### Train Model via API

```python
# Training endpoint
response = requests.post(
    'http://localhost:8000/api/v1/train',
    json={
        'model_type': 'arima',
        'data': data_list,
        'config': {
            'order': [1, 1, 1],
            'seasonal_order': [0, 0, 0, 0]
        }
    }
)

result = response.json()
print(f"Model trained: {result['model_id']}")
```

## 📊 Monitoring

### Prometheus Metrics

The API exposes metrics at `/metrics`:

- `forecast_requests_total`: Total prediction requests
- `forecast_request_duration_seconds`: Request duration
- `model_prediction_errors_total`: Prediction errors
- `active_models`: Number of active models

### Grafana Dashboards

Access Grafana at `http://localhost:3000` (default credentials: admin/admin)

Pre-configured dashboards:
- Model Performance Overview
- API Request Metrics
- System Resource Usage
- Model Drift Detection

## 🧪 Testing

```bash
# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific test suite
pytest tests/unit/test_models.py -v

# Run integration tests
pytest tests/integration/ -v
```

## 📚 Documentation

Full documentation is available at [https://docs.forecasting-package.example.com](https://docs.forecasting-package.example.com)

- [User Guide](https://docs.forecasting-package.example.com/user-guide/)
- [API Reference](https://docs.forecasting-package.example.com/api/)
- [Examples](https://docs.forecasting-package.example.com/examples/)
- [Contributing Guide](https://docs.forecasting-package.example.com/contributing/)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

```bash
# Setup development environment
make install-dev

# Run pre-commit checks
make pre-commit

# Submit pull request
git checkout -b feature/your-feature
git commit -m "Add your feature"
git push origin feature/your-feature
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Prophet](https://facebook.github.io/prophet/) by Facebook
- [statsmodels](https://www.statsmodels.org/) for ARIMA implementation
- [PyTorch](https://pytorch.org/) for LSTM models
- [MLflow](https://mlflow.org/) for experiment tracking
- [FastAPI](https://fastapi.tiangolo.com/) for API framework

## 📞 Support

- 📧 Email: suryaec1099@gmail.com
- 💬 Slack: [Join our community](https://slack.forecasting-package.example.com)
- 🐛 Issues: [GitHub Issues](https://github.com/surya08084/frcst/issues)
- 📖 Docs: [Documentation](https://docs.forecasting-package.example.com)

## 🗺️ Roadmap

- [ ] Support for additional models (XGBoost, LightGBM)
- [ ] Real-time streaming predictions
- [ ] Automated anomaly detection
- [ ] Multi-variate forecasting
- [ ] Cloud deployment templates (AWS, GCP, Azure)
- [ ] Web UI for model management

## ⭐ Star History

[![Star History Chart](https://api.star-history.com/svg?repos=username/forecasting-package&type=Date)](https://star-history.com/#username/forecasting-package&Date)

---

Made with ❤️ by the Forecasting Package Team
