timestral-backtest-lab / lab /validation.py
Segizu's picture
Timestral Backtest Lab (ZeroGPU)
756aa06 verified
Raw History Blame Contribute Delete
6.1 kB
"""Strict CSV and run-parameter validation for untrusted uploads."""
from __future__ import annotations
from dataclasses import dataclass
from pathlib import Path
from typing import Any
import numpy as np
import pandas as pd
MAX_FILE_BYTES = 1_000_000 # 1 MB
MAX_POINTS = 10_000
MAX_HORIZON = 256
DEFAULT_HORIZON = 24
# Patch size is 32; require enough train context after holdout for a meaningful forecast.
MIN_TRAIN_POINTS = 64
class ValidationError(ValueError):
"""User-facing validation failure (safe message, no server paths)."""
@dataclass(frozen=True)
class SeriesData:
values: np.ndarray
timestamps: pd.DatetimeIndex | None
value_column: str
date_column: str | None
n_points: int
source_label: str
@dataclass(frozen=True)
class RunParams:
holdout: int
future_horizon: int
seasonality: int
def _as_path(file_obj: Any) -> Path:
if file_obj is None:
raise ValidationError("Sube un CSV o elige un ejemplo sintético.")
if isinstance(file_obj, Path):
path = file_obj
elif isinstance(file_obj, str):
path = Path(file_obj)
elif hasattr(file_obj, "name"):
path = Path(str(file_obj.name))
else:
raise ValidationError("Entrada de archivo no válida.")
return path
def _assert_safe_csv_path(path: Path) -> Path:
try:
resolved = path.resolve(strict=True)
except (OSError, RuntimeError) as exc:
raise ValidationError("No se pudo leer el archivo CSV.") from exc
if ".." in Path(path).parts:
raise ValidationError("Ruta de archivo no permitida.")
if resolved.name.startswith("."):
raise ValidationError("Ruta de archivo no permitida.")
if resolved.suffix.lower() != ".csv":
raise ValidationError("Solo se aceptan archivos CSV (.csv).")
try:
size = resolved.stat().st_size
except OSError as exc:
raise ValidationError("No se pudo leer el archivo CSV.") from exc
if size <= 0:
raise ValidationError("El CSV está vacío.")
if size > MAX_FILE_BYTES:
raise ValidationError("El archivo supera el límite de 1 MB.")
return resolved
def parse_series_csv(
file_obj: Any,
value_column: str | None = None,
date_column: str | None = None,
source_label: str = "upload",
) -> SeriesData:
"""Parse a univariate series from CSV with hard safety limits."""
path = _assert_safe_csv_path(_as_path(file_obj))
try:
df = pd.read_csv(path)
except Exception as exc: # noqa: BLE001 — surface as validation error
raise ValidationError("CSV corrupto o ilegible.") from exc
if df.empty:
raise ValidationError("El CSV está vacío.")
if len(df) > MAX_POINTS:
raise ValidationError(f"Como máximo {MAX_POINTS} puntos (filas).")
numeric_cols = [c for c in df.columns if pd.api.types.is_numeric_dtype(df[c])]
# Also try coercing object columns that are mostly numeric.
if not numeric_cols:
for c in df.columns:
coerced = pd.to_numeric(df[c], errors="coerce")
if coerced.notna().mean() > 0.9:
df[c] = coerced
numeric_cols.append(c)
value_column = (value_column or "").strip() or None
if value_column:
if value_column not in df.columns:
raise ValidationError(
f"Columna '{value_column}' no encontrada. Disponibles: {list(df.columns)}"
)
col = value_column
else:
if not numeric_cols:
raise ValidationError("No hay columna numérica en el CSV.")
col = str(numeric_cols[-1])
values = pd.to_numeric(df[col], errors="coerce").to_numpy(dtype=np.float64)
if values.size == 0:
raise ValidationError("La columna objetivo no tiene valores.")
if values.size > MAX_POINTS:
raise ValidationError(f"Como máximo {MAX_POINTS} puntos.")
if not np.isfinite(values).all():
raise ValidationError("La serie contiene NaN o valores no finitos.")
timestamps: pd.DatetimeIndex | None = None
date_column = (date_column or "").strip() or None
if date_column:
if date_column not in df.columns:
raise ValidationError(f"Columna de fecha '{date_column}' no encontrada.")
ts = pd.to_datetime(df[date_column], errors="coerce")
if ts.isna().any():
raise ValidationError("La columna de fecha tiene valores inválidos.")
timestamps = pd.DatetimeIndex(ts)
else:
for c in df.columns:
if c == col:
continue
ts = pd.to_datetime(df[c], errors="coerce")
if ts.notna().mean() > 0.9 and not ts.isna().any():
timestamps = pd.DatetimeIndex(ts)
date_column = str(c)
break
return SeriesData(
values=values.astype(np.float64, copy=False),
timestamps=timestamps,
value_column=str(col),
date_column=date_column,
n_points=int(values.size),
source_label=source_label,
)
def validate_run_params(
n_points: int,
holdout: int,
future_horizon: int,
seasonality: int,
) -> RunParams:
holdout = int(holdout)
future_horizon = int(future_horizon)
seasonality = int(seasonality)
if holdout < 1 or future_horizon < 1:
raise ValidationError("Horizonte / holdout deben ser >= 1.")
if holdout > MAX_HORIZON or future_horizon > MAX_HORIZON:
raise ValidationError(f"Horizonte máximo: {MAX_HORIZON}.")
if seasonality < 1:
raise ValidationError("La estacionalidad debe ser >= 1.")
train_len = n_points - holdout
if train_len < MIN_TRAIN_POINTS:
raise ValidationError(
f"Se necesitan al menos {MIN_TRAIN_POINTS} puntos de contexto "
f"tras el holdout (ahora {train_len})."
)
if train_len < seasonality:
raise ValidationError(
"El contexto de entrenamiento debe cubrir al menos un periodo estacional."
)
return RunParams(holdout=holdout, future_horizon=future_horizon, seasonality=seasonality)