aiforecastts 0.3.3
Scientific AI-powered Time Series Research Library
License: MIT
Requires Python: >=3.11

# AIForecastTS: A Scientific Framework for Time Series Resonance & Turbulence Analysis

[![PyPI version](https://badge.fury.io/py/aiforecastts.svg)](https://badge.fury.io/py/aiforecastts)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 1. Abstract
AIForecastTS is a high-performance scientific library designed to bridge the gap between classical signal processing and modern machine learning. At its core, the library introduces the **Harmonic-Gradient Resonance (HGR)** algorithm and the **Scientific Ensemble** framework. Integrated with **Gemini 3 Flash Preview**, it provides an automated AI Research Agent capable of interpreting complex temporal patterns.

## 2. Theoretical Framework

### 2.1. Harmonic-Gradient Resonance (HGR)
Traditional forecasting often fails by treating signal and noise as a monolithic entity. HGR operates on the principle of **Dual-Component Decomposition**:

#### Resonance Module (Deterministic Physics)
The Resonance module assumes that every time series contains underlying periodicities driven by systemic cycles.
- **Spectral Identification**: Uses Fast Fourier Transform (FFT) to map the series into the frequency domain.
- **Harmonic Regression**: Selects the top $K$ dominant frequencies and reconstructs the signal using a basis of sine and cosine functions:
  $$y_{res}(t) = \sum_{i=1}^{K} [a_i \sin(\omega_i t) + b_i \cos(\omega_i t)]$$

#### Turbulence Module (Stochastic Dynamics)
The residuals from the Resonance module ($y - y_{res}$) represent "Turbulence" — the chaotic, non-linear interactions of the system.

### 2.2. Scientific Ensemble (New in v0.3.3)
For maximum robustness, the library now includes a weighted ensemble architecture that combines:
- **Facebook Prophet**: For industry-standard trend and seasonality tracking.
- **HGR Algorithm**: For specialized physics-based frequency analysis.
The ensemble dynamically stabilizes predictions by averaging the deterministic physicist view (HGR) with the Bayesian probabilistic view (Prophet), and can auto-tune weights on a validation window.

## 3. Architecture & Modules

### 3.1. Advanced Analytics (`aiforecastts.analytics`)
- **DataProcessor**: Implements time-aware interpolation and rigorous stationarity testing (Augmented Dickey-Fuller).
- **FeatureEngineer**: Automated generation of high-dimensional feature spaces, including multi-scale lags and technical indicators (RSI, MACD, Bollinger Bands).

### 3.2. AI Research Agent (`aiforecastts.agents`)
Powered by **Gemini 3 Flash Preview**, the agent acts as an automated peer-reviewer. It analyzes the mathematical outputs of the HGR algorithm and generates a scientific synthesis, explaining the interaction between systemic resonance and market turbulence.

## 4. Installation & Setup

```bash
pip install aiforecastts
```

## 5. Scientific Workflow Example

```python
import pandas as pd
from aiforecastts import TimeSeriesResearch

# Load dataset (e.g., Financial or Sensor data)
df = pd.read_csv("data.csv", index_col='timestamp', parse_dates=True)

# Initialize the Research Pipeline
research = TimeSeriesResearch(df, target_col='target', model_type='ensemble')

# Execute Full Analysis with Gemini 3 Flash Agent
results = research.run_full_analysis(
    agent_query="Analyze the resonance-turbulence interaction and assess forecast stability.",
  api_key="YOUR_GEMINI_API_KEY",
  steps=7
)

# Access Scientific Report
print(results['agent_report'])

# Access Mathematical Forecast
forecast_df = results['forecast']
print(forecast_df[['resonance', 'turbulence', 'hgr_forecast']])
```

## 6. Future Research Directions
- Integration of Quantum-inspired optimization for frequency selection.
- Support for Multi-variate HGR (MV-HGR) to capture cross-series correlations.
- Real-time streaming analytics for high-frequency turbulence monitoring.

## 7. Citation
If you use this library in your research, please cite it as:
> Tuan, T. A. (2025). AIForecastTS: A Scientific Framework for Time Series Resonance & Turbulence Analysis. GitHub Repository.

---
*Developed by Tran Anh Tuan - (AI Forecast) aiconsultant.org*
```