tsagentkit 1.0.2__py3-none-any.whl

tsagentkit/__init__.py

@@ -0,0 +1,126 @@
+"""tsagentkit - Robust execution engine for time-series forecasting agents.
+
+This library provides a strict, production-grade workflow skeleton for
+external coding agents (LLMs/AI agents) performing time-series forecasting tasks.
+
+Basic usage:
+    >>> from tsagentkit import TaskSpec, validate_contract, run_forecast
+    >>> spec = TaskSpec(h=7, freq="D")
+    >>> result = run_forecast(data, spec)
+"""
+
+__version__ = "1.0.2"
+
+# Import commonly used items from contracts
+from tsagentkit.anomaly import detect_anomalies
+from tsagentkit.backtest import (
+    BacktestReport,
+    mase,
+    rolling_backtest,
+    smape,
+    wape,
+)
+from tsagentkit.calibration import apply_calibrator, fit_calibrator
+from tsagentkit.contracts import (
+    ECovariateLeakage,
+    ESplitRandomForbidden,
+    ForecastResult,
+    ModelArtifact,
+    Provenance,
+    RunArtifact,
+    TaskSpec,
+    # Errors
+    TSAgentKitError,
+    ValidationReport,
+    validate_contract,
+)
+from tsagentkit.eval import MetricFrame, ScoreSummary, evaluate_forecasts
+from tsagentkit.qa import run_qa
+from tsagentkit.router import (
+    BucketConfig,
+    BucketProfile,
+    BucketStatistics,
+    # Bucketing (v0.2)
+    DataBucketer,
+    FallbackLadder,
+    PlanSpec,
+    SeriesBucket,
+    compute_plan_signature,
+    execute_with_fallback,
+    get_candidate_models,
+    make_plan,
+)
+from tsagentkit.series import (
+    SparsityClass,
+    SparsityProfile,
+    TSDataset,
+    build_dataset,
+)
+from tsagentkit.serving import MonitoringConfig, run_forecast
+
+# Structured logging (v1.0)
+from tsagentkit.serving.provenance import (
+    StructuredLogger,
+    format_event_json,
+    log_event,
+)
+
+# v0.2 imports (optional - use directly from submodules)
+# from tsagentkit.features import FeatureFactory, FeatureMatrix, compute_feature_hash
+# from tsagentkit.monitoring import DriftDetector, StabilityMonitor, TriggerEvaluator
+
+__all__ = [
+    "__version__",
+    # Core contracts
+    "TaskSpec",
+    "ValidationReport",
+    "ForecastResult",
+    "ModelArtifact",
+    "Provenance",
+    "RunArtifact",
+    "validate_contract",
+    # Key errors
+    "TSAgentKitError",
+    "ESplitRandomForbidden",
+    "ECovariateLeakage",
+    # Series
+    "TSDataset",
+    "SparsityProfile",
+    "SparsityClass",
+    "build_dataset",
+    # QA
+    "run_qa",
+    # Calibration + Anomaly + Eval
+    "fit_calibrator",
+    "apply_calibrator",
+    "detect_anomalies",
+    "evaluate_forecasts",
+    "MetricFrame",
+    "ScoreSummary",
+    # Router
+    "PlanSpec",
+    "compute_plan_signature",
+    "get_candidate_models",
+    "make_plan",
+    "FallbackLadder",
+    "execute_with_fallback",
+    # Router Bucketing (v0.2)
+    "DataBucketer",
+    "BucketConfig",
+    "BucketProfile",
+    "BucketStatistics",
+    "SeriesBucket",
+    # Backtest
+    "BacktestReport",
+    "rolling_backtest",
+    "wape",
+    "smape",
+    "mase",
+    # Serving
+    "run_forecast",
+    "MonitoringConfig",
+    # Structured Logging (v1.0)
+    "log_event",
+    "format_event_json",
+    "StructuredLogger",
+]

tsagentkit/anomaly/__init__.py

@@ -0,0 +1,130 @@
+"""Anomaly detection based on forecast intervals/quantiles."""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import numpy as np
+import pandas as pd
+
+from tsagentkit.contracts import EAnomalyFail
+from tsagentkit.utils import parse_quantile_column
+
+AnomalyMethod = Literal["interval_breach", "conformal", "mad_residual"]
+AnomalyScore = Literal["margin", "normalized_margin", "zscore"]
+
+
+@dataclass(frozen=True)
+class AnomalyReport:
+    """Anomaly detection report."""
+
+    frame: pd.DataFrame
+    method: str
+    level: int
+    score: str
+    summary: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "method": self.method,
+            "level": self.level,
+            "score": self.score,
+            "summary": self.summary,
+            "frame": self.frame.to_dict("records"),
+        }
+
+
+def detect_anomalies(
+    forecast_with_y: pd.DataFrame,
+    method: AnomalyMethod = "interval_breach",
+    level: int = 99,
+    score: AnomalyScore = "normalized_margin",
+    calibrator: Any | None = None,
+    strict: bool = False,
+    id_col: str = "unique_id",
+    ds_col: str = "ds",
+    actual_col: str = "y",
+    pred_col: str = "yhat",
+) -> AnomalyReport:
+    """Detect anomalies using forecast uncertainty."""
+    if forecast_with_y.empty:
+        raise EAnomalyFail("Forecast frame is empty.")
+
+    if strict and calibrator is None:
+        raise EAnomalyFail(
+            "Strict mode requires calibrated intervals/quantiles for anomaly detection."
+        )
+    if not strict and calibrator is None and method != "interval_breach":
+        warnings.warn(
+            "Anomaly detection requested without calibrated intervals/quantiles. "
+            "Proceeding may increase false positives.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    df = forecast_with_y.copy()
+
+    lo_col = f"yhat_lo_{level}"
+    hi_col = f"yhat_hi_{level}"
+    if lo_col not in df.columns or hi_col not in df.columns:
+        # Try to infer from quantiles
+        lower_q = (1 - level / 100.0) / 2
+        upper_q = 1 - lower_q
+        q_cols = {parse_quantile_column(c): c for c in df.columns}
+        lo_col = q_cols.get(lower_q)
+        hi_col = q_cols.get(upper_q)
+        if lo_col is None or hi_col is None:
+            raise EAnomalyFail(
+                "No interval/quantile columns available for anomaly detection.",
+                context={"expected_level": level},
+            )
+
+    y = df[actual_col].to_numpy(dtype=float)
+    yhat = df[pred_col].to_numpy(dtype=float) if pred_col in df.columns else None
+    lo = df[lo_col].to_numpy(dtype=float)
+    hi = df[hi_col].to_numpy(dtype=float)
+
+    margin = np.zeros_like(y, dtype=float)
+    margin = np.where(y < lo, lo - y, margin)
+    margin = np.where(y > hi, y - hi, margin)
+
+    if score == "margin":
+        anomaly_score = margin
+    elif score == "normalized_margin":
+        width = np.maximum(hi - lo, 1e-8)
+        anomaly_score = margin / width
+    else:  # zscore
+        if yhat is None:
+            raise EAnomalyFail("yhat is required for zscore anomaly score.")
+        width = np.maximum(hi - lo, 1e-8)
+        anomaly_score = np.abs(y - yhat) / (0.5 * width)
+
+    anomaly_flag = margin > 0
+
+    frame = df[[id_col, ds_col, actual_col, pred_col]].copy()
+    frame["lo"] = lo
+    frame["hi"] = hi
+    frame["anomaly"] = anomaly_flag
+    frame["anomaly_score"] = anomaly_score
+    frame["threshold"] = level
+    frame["method"] = method
+    frame["score"] = score
+
+    summary = {
+        "total": int(len(frame)),
+        "anomalies": int(np.sum(anomaly_flag)),
+        "anomaly_rate": float(np.mean(anomaly_flag)) if len(frame) > 0 else 0.0,
+    }
+
+    return AnomalyReport(
+        frame=frame,
+        method=method,
+        level=level,
+        score=score,
+        summary=summary,
+    )
+
+
+__all__ = ["AnomalyReport", "detect_anomalies"]

tsagentkit/backtest/__init__.py

@@ -0,0 +1,48 @@
+"""Backtest module for tsagentkit.
+
+Provides rolling window backtesting and report structures. Legacy metric
+helpers are still exported for compatibility but are deprecated; prefer
+``tsagentkit.eval.evaluate_forecasts`` for new evaluation flows.
+"""
+
+from .engine import cross_validation_split, rolling_backtest
+from .metrics import (
+    compute_all_metrics,
+    compute_metrics_by_series,
+    mae,
+    mase,
+    pinball_loss,
+    rmse,
+    smape,
+    wape,
+    wql,
+)
+from .report import (
+    BacktestReport,
+    SegmentMetrics,
+    SeriesMetrics,
+    TemporalMetrics,
+    WindowResult,
+)
+
+__all__ = [
+    # Engine
+    "rolling_backtest",
+    "cross_validation_split",
+    # Report
+    "BacktestReport",
+    "WindowResult",
+    "SeriesMetrics",
+    "SegmentMetrics",
+    "TemporalMetrics",
+    # Metrics
+    "wape",
+    "smape",
+    "mase",
+    "mae",
+    "rmse",
+    "pinball_loss",
+    "wql",
+    "compute_all_metrics",
+    "compute_metrics_by_series",
+]