ts-anomaly-guard 0.1.0

# 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):

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

Uso Rápido

1. Auditoría Local (Excel / Pandas)

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

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

📄 Licencia

Este proyecto está bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

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