Metadata-Version: 2.4
Name: ts-anomaly-guard
Version: 0.1.0
Summary: Motor estadístico robusto para la detección ultrarrápida de anomalías en series temporales de negocios.
Author-email: Alejo Prieto <tu-email@dominio.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: sqlalchemy>=1.4.0
Provides-Extra: spark
Requires-Dist: pyspark>=3.2.0; extra == "spark"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Dynamic: license-file

```markdown
# TS-Anomaly-Guard

**TS-Anomaly-Guard** es un motor estadístico de alto rendimiento, interpretable y ultrarrápido diseñado para la detección de anomalías y cambios estructurales de régimen (*Level Shifts*) en series temporales financieras y corporativas.

Desarrollado para resolver la opacidad y los falsos positivos de los modelos tradicionales de Machine Learning, **TS-Anomaly-Guard** diferencia de forma nativa entre **outliers puntuales** (picos aislados) y **cambios de régimen duraderos** (escalamiento de negocio), permitiendo procesar desde archivos locales de Excel hasta millones de registros agrupados en **PySpark / Databricks**.

---

## Características Clave

* **100% Interpretable:** Basado en métricas robustas ($MAD$, *Modified Z-Score*, distancias cuantílicas) auditables por equipos de riesgo y auditoría.
* **Detección de Level Shift:** Distingue cuándo un negocio cambia de escala o nivel operativo de forma permanente sin generar falsos positivos en los meses posteriores.
* **Agnóstico a la Fuente de Datos:** Soporte nativo para lectura desde pandas DataFrames, archivos Excel (`.xlsx`), CSV y consultas SQL directas (`SQLAlchemy`).
* **Escalabilidad Gradual:** Ejecución en serie, multiprocesamiento paralelo local (`n_jobs`) e integración nativa con clústeres de **PySpark** (`groupBy.applyInPandas`).

---

## Instalación

Instalación estándar:
```bash
pip install ts-anomaly-guard

```

Instalación con soporte para Big Data (PySpark):

```bash
pip install "ts-anomaly-guard[spark]"

```

---

## Uso Rápido

### 1. Auditoría Local (Excel / Pandas)

```python
import pandas as pd
from ts_anomaly_guard import AnomalyGuard

# Carga de datos
df = pd.read_excel("contabilidad_fiduciaria.xlsx")

# Inicializar motor con umbrales ajustables
guard = AnomalyGuard(
    date_col="fecha",
    value_col="monto",
    group_col="id_fideicomiso",  # Opcional: para auditar múltiples negocios a la vez
    z_threshold=2.5,
    rolling_window=3
)

# Ejecutar auditoría
results = guard.detect(df)

# Filtrar hallazgos relevantes
alertas = results[results["is_anomaly"]][["id_fideicomiso", "fecha", "monto", "anomaly_type"]]
print(alertas)

```

### 2. Escalamiento Masivo en PySpark / Databricks

```python
from ts_anomaly_guard.spark import process_spark_dataset

# DataFrame de PySpark con millones de registros de transacciones
spark_df = spark.table("db_fiduciario.transacciones")

# Ejecución distribuida por nodo
audited_spark_df = process_spark_dataset(
    spark_df=spark_df,
    date_col="fecha",
    value_col="monto",
    group_col="id_negocio",
    z_threshold=2.5
)

audited_spark_df.write.mode("overwrite").saveAsTable("db_fiduciario.anomalias_detectadas")

```

---

## Clasificación de Alertas

| Tipo de Alerta | Descripción | Criterio Estadístico |
| --- | --- | --- |
| **`NORMAL`** | Variación dentro de los límites operativos esperados. | $Modified\ Z\text{-}Score < Umbral$ |
| **`PUNCTUAL_ANOMALY`** | Pico o caída abrupta aislada de un solo período. | $Z\text{-}Score\ Local \ge Umbral$ sin cambio duradero de régimen |
| **`LEVEL_SHIFT`** | Ruptura de régimen: el negocio escaló y se estabilizó en una nueva meseta. | Discrepancia respecto a la mediana histórica anterior |

---

## 📄 Licencia

Este proyecto está bajo la Licencia MIT - consulta el archivo [LICENSE](https://www.google.com/search?q=LICENSE) para más detalles.

```markdown
 English version: [README_EN.md](README_EN.md)

```
