vectrix 0.0.1__tar.gz

vectrix-0.0.1/.github/FUNDING.yml

@@ -0,0 +1 @@
+buy_me_a_coffee: eddmpython

vectrix-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

vectrix-0.0.1/.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/vectrix
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

vectrix-0.0.1/.gitignore

@@ -0,0 +1,62 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+env/
+venv/
+CLAUDE.md
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*
+
+# Data files
+*.xlsx
+*.xls
+*.csv
+*.tsv
+*.pkl
+*.pickle
+*.parquet
+*.feather
+*.jsonl
+
+# Output files
+*.log
+*.html
+*.pdf
+
+# Cache
+.cache/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+coverage.xml
+.coverage
+
+# Jupyter
+.ipynb_checkpoints/
+
+# uv
+uv.lock

vectrix-0.0.1/.python-version

@@ -0,0 +1 @@
+3.12

vectrix-0.0.1/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to Vectrix will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-02-27
+
+Initial public release of Vectrix -- a zero-config time series forecasting library built with pure NumPy + SciPy.
+
+### Added
+
+**Core Forecasting Engine (30+ Models)**
+- AutoETS: 30 Error x Trend x Seasonal combinations with AICc model selection (Hyndman-Khandakar stepwise algorithm)
+- AutoARIMA: Seasonal ARIMA with stepwise order selection, CSS objective function
+- Theta / Dynamic Optimized Theta (DOT): Original Theta method + M3 Competition winner methodology
+- AutoCES: Complex Exponential Smoothing (Svetunkov 2023)
+- AutoTBATS: Trigonometric seasonality for complex multi-seasonal time series
+- GARCH / EGARCH / GJR-GARCH: Conditional volatility modeling with asymmetric effects
+- Croston Classic / SBA / TSB / AutoCroston: Intermittent and lumpy demand forecasting
+- Logistic Growth: Prophet-style saturating trends with user-defined capacity constraints
+- AutoMSTL: Multi-seasonal STL decomposition with ARIMA residual forecasting
+- Baseline models: Naive, Seasonal Naive, Mean, Random Walk with Drift, Window Average
+
+**Novel Methods**
+- Lotka-Volterra Ensemble: Ecological competition dynamics for adaptive model weighting
+- Phase Transition Forecaster: Critical slowing down detection for regime shift prediction
+- Adversarial Stress Tester: 5 perturbation operators (spike, dropout, drift, noise, swap) for forecast robustness analysis
+- Hawkes Intermittent Demand: Self-exciting point process for clustered demand patterns
+- Entropic Confidence Scorer: Shannon entropy-based forecast uncertainty quantification
+
+**Adaptive Intelligence**
+- Regime Detection: Pure numpy Hidden Markov Model implementation (Baum-Welch + Viterbi)
+- Self-Healing Forecast: CUSUM + EWMA drift detection with conformal prediction correction
+- Constraint-Aware Forecasting: 8 business constraint types (non-negative, range, capacity, YoY change, sum, monotone, ratio, custom)
+- Forecast DNA: 65+ time series feature fingerprinting with meta-learning model recommendation and similarity search
+- Flat Defense: 4-level system (diagnostic, detection, correction, prevention) against flat prediction failure
+
+**Easy API**
+- `forecast()`: One-call forecasting with automatic model selection, accepts str/DataFrame/Series/ndarray/list/tuple/dict
+- `analyze()`: Time series DNA profiling, changepoint detection, anomaly identification
+- `regress()`: R-style formula regression (`y ~ x1 + x2`) with full diagnostics
+- `quick_report()`: Combined analysis + forecast report generation
+- Rich result objects with `.plot()`, `.to_csv()`, `.to_json()`, `.to_dataframe()`, `.summary()`, `.describe()`
+
+**Regression & Diagnostics**
+- 5 regression methods: OLS, Ridge, Lasso, Huber, Quantile
+- R-style formula interface: `regress(data=df, formula="sales ~ ads + price")`
+- Full diagnostics suite: Durbin-Watson, Breusch-Pagan, VIF, Jarque-Bera normality tests
+- Variable selection: Stepwise (forward/backward), regularization CV, best subset
+- Time series regression: Newey-West HAC, Cochrane-Orcutt, Prais-Winsten, Granger causality
+
+**Business Intelligence**
+- Anomaly detection with automated outlier identification and natural language explanation
+- What-if analysis: Scenario-based forecast simulation with parameter perturbation
+- Backtesting: Rolling origin cross-validation with MAE, RMSE, MAPE, SMAPE metrics
+- Hierarchy reconciliation: Bottom-up, Top-down, MinTrace optimal (Wickramasuriya 2019)
+- Prediction intervals: Conformal prediction + Bootstrap methods
+
+**Infrastructure**
+- Batch forecasting API with ThreadPoolExecutor parallelization
+- Model persistence: `.fxm` binary format with save/load/info utilities
+- TSFrame: Time series DataFrame wrapper with frequency detection
+- Global model: Cross-series learning for related time series
+- Numba JIT acceleration for core computations (optional dependency)
+- 275 tests covering all models, edge cases, and integration scenarios
+- GitHub Actions CI: Matrix testing (Python 3.10-3.13, Ubuntu + Windows)
+- PyPI trusted publisher deployment via GitHub Actions
+
+[0.0.1]: https://github.com/eddmpython/vectrix/releases/tag/v0.0.1

vectrix-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vectrix Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vectrix-0.0.1/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: vectrix
+Version: 0.0.1
+Summary: Zero-config time series forecasting & analysis library. Pure numpy + scipy implementation with 30+ models, regression, and adaptive intelligence.
+Project-URL: Homepage, https://github.com/eddmpython/vectrix
+Project-URL: Repository, https://github.com/eddmpython/vectrix
+Project-URL: Issues, https://github.com/eddmpython/vectrix/issues
+Project-URL: Buy Me a Coffee, https://buymeacoffee.com/eddmpython
+Author: eddmpython
+License: MIT
+License-File: LICENSE
+Keywords: arima,auto-forecast,ets,exponential-smoothing,forecasting,mstl,numpy,prediction,regression,theta,time-series
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: scipy>=1.10.0
+Provides-Extra: all
+Requires-Dist: lightgbm>=3.0; extra == 'all'
+Requires-Dist: numba>=0.58.0; extra == 'all'
+Requires-Dist: pytest-cov>=4.0; extra == 'all'
+Requires-Dist: pytest>=7.0; extra == 'all'
+Requires-Dist: ruff>=0.1.0; extra == 'all'
+Requires-Dist: scikit-learn>=1.0; extra == 'all'
+Requires-Dist: xgboost>=1.7; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: ml
+Requires-Dist: lightgbm>=3.0; extra == 'ml'
+Requires-Dist: scikit-learn>=1.0; extra == 'ml'
+Requires-Dist: xgboost>=1.7; extra == 'ml'
+Provides-Extra: numba
+Requires-Dist: numba>=0.58.0; extra == 'numba'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<br>
+
+# Vectrix
+
+**Feed data. Get forecasts. Zero config.**
+
+Pure Python time series forecasting -- 30+ models, zero heavy dependencies.
+
+<br>
+
+[![PyPI](https://img.shields.io/pypi/v/vectrix?style=flat-square&color=6366f1&label=PyPI)](https://pypi.org/project/vectrix/)
+[![Python](https://img.shields.io/pypi/pyversions/vectrix?style=flat-square&label=Python)](https://pypi.org/project/vectrix/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+[![Tests](https://img.shields.io/badge/Tests-275%20passed-brightgreen?style=flat-square)]()
+[![Sponsor](https://img.shields.io/badge/Sponsor-Buy%20Me%20a%20Coffee-orange?style=flat-square&logo=buy-me-a-coffee&logoColor=white)](https://buymeacoffee.com/eddmpython)
+
+---
+
+[Installation](#installation) · [Quick Start](#quick-start) · [Features](#features) · [API](#api-reference) · [한국어](README_KR.md)
+
+</div>
+
+<br>
+
+```
+  3 dependencies    30+ models    1 line of code
+  ─────────────     ──────────    ──────────────
+  numpy             AutoETS       from vectrix import forecast
+  scipy             AutoARIMA     result = forecast(data, steps=12)
+  pandas            Theta/DOT     print(result)
+                    TBATS
+                    GARCH
+                    ...
+```
+
+<br>
+
+## Quick Start
+
+```bash
+pip install vectrix
+```
+
+```python
+from vectrix import forecast
+
+result = forecast("sales.csv", steps=12)
+print(result)
+result.plot()
+result.to_csv("output.csv")
+```
+
+One call. Auto model selection, flat-line prevention, confidence intervals, and a plot.
+
+<br>
+
+## Why Vectrix?
+
+| | Vectrix | statsforecast | Prophet | Darts |
+|:--|:-:|:-:|:-:|:-:|
+| **Zero-config auto-forecast** | **Yes** | Yes | -- | -- |
+| **Pure Python (no heavy deps)** | **Yes** | -- | -- | -- |
+| **30+ models built-in** | **Yes** | Yes | -- | Yes |
+| **Flat prediction defense** | **Yes** | -- | -- | -- |
+| **Adversarial stress testing** | **Yes** | -- | -- | -- |
+| **Forecast DNA fingerprinting** | **Yes** | -- | -- | -- |
+| **Business constraints (8 types)** | **Yes** | -- | -- | -- |
+| **R-style regression** | **Yes** | -- | -- | -- |
+
+> `numpy` + `scipy` + `pandas` -- that's the entire install.
+
+<br>
+
+## Features
+
+<details open>
+<summary><b>Core Models</b></summary>
+
+| Model | Description |
+|-------|-------------|
+| AutoETS | 30 Error x Trend x Seasonal combinations, AICc selection |
+| AutoARIMA | Seasonal ARIMA, stepwise order selection |
+| Theta / DOT | Original Theta + Dynamic Optimized Theta |
+| AutoCES | Complex Exponential Smoothing (Svetunkov 2023) |
+| AutoTBATS | Trigonometric multi-seasonal decomposition |
+| GARCH | GARCH, EGARCH, GJR-GARCH volatility models |
+| Croston | Classic, SBA, TSB for intermittent demand |
+| Logistic Growth | Saturating trends with capacity constraints |
+| AutoMSTL | Multi-seasonal decomposition + ARIMA residuals |
+| Baselines | Naive, Seasonal Naive, Mean, Drift, Window Average |
+
+</details>
+
+<details>
+<summary><b>Novel Methods</b></summary>
+
+| Method | Description |
+|--------|-------------|
+| Lotka-Volterra Ensemble | Ecological competition dynamics for model weighting |
+| Phase Transition | Critical slowing down for regime shift prediction |
+| Adversarial Stress | 5 perturbation operators for robustness analysis |
+| Hawkes Demand | Self-exciting point process for clustered demand |
+| Entropic Confidence | Shannon entropy uncertainty quantification |
+
+</details>
+
+<details>
+<summary><b>Adaptive Intelligence</b></summary>
+
+| Feature | Description |
+|---------|-------------|
+| Regime Detection | Pure numpy HMM (Baum-Welch + Viterbi) |
+| Self-Healing | CUSUM + EWMA drift detection, conformal correction |
+| Constraints | 8 types: non-negative, range, capacity, YoY, sum, monotone, ratio, custom |
+| Forecast DNA | 65+ feature fingerprinting, meta-learning recommendation |
+| Flat Defense | 4-level prevention system |
+
+</details>
+
+<details>
+<summary><b>Regression & Diagnostics</b></summary>
+
+| Feature | Description |
+|---------|-------------|
+| Methods | OLS, Ridge, Lasso, Huber, Quantile |
+| Formula | R-style `regress(data=df, formula="y ~ x1 + x2")` |
+| Diagnostics | Durbin-Watson, Breusch-Pagan, VIF, normality |
+| Variable Selection | Stepwise, regularization CV, best subset |
+| Time Series | Newey-West, Cochrane-Orcutt, Granger causality |
+
+</details>
+
+<details>
+<summary><b>Business Intelligence</b></summary>
+
+| Feature | Description |
+|---------|-------------|
+| Anomaly Detection | Automated outlier identification and explanation |
+| What-if Analysis | Scenario-based forecast simulation |
+| Backtesting | Rolling origin cross-validation |
+| Hierarchy | Bottom-up, top-down, MinTrace reconciliation |
+| Intervals | Conformal + bootstrap prediction intervals |
+
+</details>
+
+<br>
+
+## Installation
+
+```bash
+pip install vectrix                # Core (numpy + scipy + pandas)
+pip install "vectrix[numba]"       # + Numba JIT (2-5x speedup)
+pip install "vectrix[ml]"          # + LightGBM, XGBoost, scikit-learn
+pip install "vectrix[all]"         # Everything
+```
+
+**Requirements:** Python 3.10+
+
+<br>
+
+## Usage Examples
+
+### Easy API
+
+```python
+from vectrix import forecast, analyze, regress
+
+result = forecast([100, 120, 115, 130, 125, 140], steps=5)
+
+report = analyze(df, date="date", value="sales")
+print(f"Difficulty: {report.dna.difficulty}")
+
+model = regress(data=df, formula="sales ~ temperature + promotion")
+print(model.summary())
+```
+
+### DataFrame Workflow
+
+```python
+from vectrix import forecast, analyze
+import pandas as pd
+
+df = pd.read_csv("data.csv")
+
+report = analyze(df, date="date", value="sales")
+print(report.summary())
+
+result = forecast(df, date="date", value="sales", steps=30)
+result.plot()
+result.to_csv("forecast.csv")
+```
+
+### Direct Engine Access
+
+```python
+from vectrix.engine import AutoETS, AutoARIMA
+from vectrix.adaptive import ForecastDNA
+
+ets = AutoETS(period=7)
+ets.fit(data)
+pred, lower, upper = ets.predict(30)
+
+dna = ForecastDNA()
+profile = dna.analyze(data, period=7)
+print(f"Difficulty: {profile.difficulty}")
+print(f"Recommended: {profile.recommendedModels}")
+```
+
+### Business Constraints
+
+```python
+from vectrix.adaptive import ConstraintAwareForecaster, Constraint
+
+caf = ConstraintAwareForecaster()
+result = caf.apply(predictions, lower95, upper95, constraints=[
+    Constraint('non_negative', {}),
+    Constraint('range', {'min': 100, 'max': 5000}),
+    Constraint('capacity', {'capacity': 10000}),
+    Constraint('yoy_change', {'maxPct': 30, 'historicalData': past_year}),
+])
+```
+
+### Classic API
+
+```python
+from vectrix import Vectrix
+
+fx = Vectrix(verbose=True)
+result = fx.forecast(df, dateCol="date", valueCol="sales", steps=30)
+
+if result.success:
+    print(f"Model: {result.bestModelName}")
+    print(f"Predictions: {result.predictions}")
+```
+
+<br>
+
+## API Reference
+
+### Easy API (Recommended)
+
+| Function | Description |
+|----------|-------------|
+| `forecast(data, steps=30)` | Auto model selection forecasting |
+| `analyze(data)` | DNA profiling, changepoints, anomalies |
+| `regress(y, X)` / `regress(data=df, formula="y ~ x")` | Regression with diagnostics |
+| `quick_report(data, steps=30)` | Combined analysis + forecast |
+
+### Classic API
+
+| Method | Description |
+|--------|-------------|
+| `Vectrix().forecast(df, dateCol, valueCol, steps)` | Full pipeline |
+| `Vectrix().analyze(df, dateCol, valueCol)` | Data analysis |
+
+### Return Objects
+
+| Object | Key Attributes |
+|--------|---------------|
+| `EasyForecastResult` | `.predictions` `.dates` `.lower` `.upper` `.model` `.plot()` `.to_csv()` `.to_json()` |
+| `EasyAnalysisResult` | `.dna` `.changepoints` `.anomalies` `.features` `.summary()` |
+| `EasyRegressionResult` | `.coefficients` `.pvalues` `.r_squared` `.f_stat` `.summary()` `.diagnose()` |
+
+<br>
+
+## Architecture
+
+```
+vectrix/
+├── easy.py               forecast(), analyze(), regress()
+├── vectrix.py             Vectrix class (full pipeline)
+├── types.py               ForecastResult, DataCharacteristics
+├── engine/                30+ statistical models
+│   ├── ets.py               AutoETS (30 combinations)
+│   ├── arima.py             AutoARIMA (AICc stepwise)
+│   ├── theta.py             Theta method
+│   ├── dot.py               Dynamic Optimized Theta
+│   ├── ces.py               Complex Exponential Smoothing
+│   ├── tbats.py             TBATS / AutoTBATS
+│   ├── mstl.py              Multi-Seasonal Decomposition
+│   ├── garch.py             GARCH / EGARCH / GJR-GARCH
+│   ├── croston.py           Croston Classic / SBA / TSB
+│   ├── logistic.py          Logistic Growth
+│   ├── hawkes.py            Hawkes Intermittent Demand
+│   ├── lotkaVolterra.py     Lotka-Volterra Ensemble
+│   ├── phaseTransition.py   Phase Transition Forecaster
+│   ├── adversarial.py       Adversarial Stress Tester
+│   ├── entropic.py          Entropic Confidence Scorer
+│   └── turbo.py             Numba JIT acceleration
+├── adaptive/              Regime, self-healing, constraints, DNA
+├── regression/            OLS, Ridge, Lasso, Huber, Quantile
+├── business/              Anomaly, backtest, what-if, metrics
+├── flat_defense/          4-level flat prediction prevention
+├── hierarchy/             Bottom-up, top-down, MinTrace
+├── intervals/             Conformal + bootstrap intervals
+├── ml/                    LightGBM, XGBoost wrappers
+└── global_model/          Cross-series forecasting
+```
+
+<br>
+
+## Contributing
+
+```bash
+git clone https://github.com/eddmpython/vectrix.git
+cd vectrix
+uv sync --extra dev
+uv run pytest
+```
+
+<br>
+
+## Support
+
+If you find Vectrix useful, consider supporting the project:
+
+<a href="https://buymeacoffee.com/eddmpython">
+  <img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support%20Vectrix-orange?style=for-the-badge&logo=buy-me-a-coffee&logoColor=white" alt="Buy Me a Coffee">
+</a>
+
+<br>
+
+## License
+
+[MIT](LICENSE) -- Use freely in personal and commercial projects.