aiforecastts 0.3.3

Scientific AI-powered Time Series Research Library

AIForecastTS: A Scientific Framework for Time Series Resonance & Turbulence Analysis

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

pip install aiforecastts

5. Scientific Workflow Example

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