tsagentkit 1.0.2__py3-none-any.whl

tsagentkit/calibration/__init__.py

@@ -0,0 +1,136 @@
+"""Calibration utilities for forecast intervals and quantiles."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import numpy as np
+import pandas as pd
+
+from tsagentkit.contracts import ECalibrationFail
+from tsagentkit.utils import extract_quantiles, quantile_col_name
+
+CalibrationMethod = Literal["none", "conformal"]
+
+
+@dataclass(frozen=True)
+class CalibratorArtifact:
+    """Serializable calibration artifact.
+
+    Attributes:
+        method: Calibration method
+        level: Target coverage level (percent)
+        by: Calibration scope ("unique_id" or "global")
+        deltas: Mapping from unique_id to calibration delta
+        metadata: Additional metadata
+    """
+
+    method: CalibrationMethod
+    level: int
+    by: Literal["unique_id", "global"] = "unique_id"
+    deltas: dict[str, float] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def get_delta(self, unique_id: str | None = None) -> float:
+        if self.by == "global":
+            return float(self.deltas.get("global", 0.0))
+        if unique_id is None:
+            return float(self.deltas.get("global", 0.0))
+        return float(self.deltas.get(unique_id, 0.0))
+
+
+def fit_calibrator(
+    cv: pd.DataFrame,
+    method: CalibrationMethod = "conformal",
+    level: int = 99,
+    by: Literal["unique_id", "global"] = "unique_id",
+    id_col: str = "unique_id",
+    actual_col: str = "y",
+    pred_col: str = "yhat",
+) -> CalibratorArtifact:
+    """Fit calibration artifact using out-of-sample residuals."""
+    if method == "none":
+        return CalibratorArtifact(method=method, level=level, by=by, deltas={"global": 0.0})
+
+    if cv.empty:
+        raise ECalibrationFail("CV frame is empty.", context={"method": method})
+
+    if pred_col not in cv.columns or actual_col not in cv.columns:
+        raise ECalibrationFail(
+            "CV frame must include prediction and actual columns.",
+            context={"pred_col": pred_col, "actual_col": actual_col},
+        )
+
+    residuals = np.abs(cv[actual_col].to_numpy(dtype=float) - cv[pred_col].to_numpy(dtype=float))
+    if residuals.size == 0:
+        raise ECalibrationFail("No residuals available for calibration.")
+
+    alpha = level / 100.0
+    deltas: dict[str, float] = {}
+
+    if by == "global":
+        deltas["global"] = float(np.quantile(residuals, alpha))
+    else:
+        for uid, group in cv.groupby(id_col):
+            group_resid = np.abs(group[actual_col].to_numpy(dtype=float) - group[pred_col].to_numpy(dtype=float))
+            if group_resid.size == 0:
+                continue
+            deltas[str(uid)] = float(np.quantile(group_resid, alpha))
+
+        if not deltas:
+            deltas["global"] = float(np.quantile(residuals, alpha))
+
+    return CalibratorArtifact(
+        method=method,
+        level=level,
+        by=by,
+        deltas=deltas,
+        metadata={
+            "n_residuals": int(residuals.size),
+            "alpha": alpha,
+        },
+    )
+
+
+def apply_calibrator(
+    forecast: pd.DataFrame,
+    calibrator: CalibratorArtifact,
+    id_col: str = "unique_id",
+    pred_col: str = "yhat",
+) -> pd.DataFrame:
+    """Apply calibration artifact to a forecast frame."""
+    if calibrator.method == "none":
+        return forecast
+
+    if forecast.empty:
+        return forecast
+
+    df = forecast.copy()
+    level = calibrator.level
+    lo_col = f"yhat_lo_{level}"
+    hi_col = f"yhat_hi_{level}"
+
+    if id_col not in df.columns or pred_col not in df.columns:
+        raise ECalibrationFail(
+            "Forecast frame must include unique_id and yhat for calibration.",
+            context={"id_col": id_col, "pred_col": pred_col},
+        )
+
+    deltas = df[id_col].map(lambda uid: calibrator.get_delta(str(uid))).to_numpy(dtype=float)
+    yhat = df[pred_col].to_numpy(dtype=float)
+    df[lo_col] = yhat - deltas
+    df[hi_col] = yhat + deltas
+
+    # If quantile columns exist, adjust symmetrically around yhat.
+    quantiles = extract_quantiles(df.columns)
+    if quantiles:
+        for q in quantiles:
+            col = quantile_col_name(q)
+            direction = -1.0 if q < 0.5 else 1.0
+            df[col] = yhat + direction * deltas
+
+    return df
+
+
+__all__ = ["CalibratorArtifact", "fit_calibrator", "apply_calibrator"]

tsagentkit/contracts/__init__.py

@@ -0,0 +1,133 @@
+"""Contracts module for tsagentkit."""
+
+from .errors import (
+    EOOM,
+    EAdapterNotAvailable,
+    EAnomalyFail,
+    EBacktestFail,
+    EBacktestInsufficientData,
+    EBacktestInvalidWindow,
+    ECalibrationFail,
+    EContractDuplicateKey,
+    EContractInvalid,
+    EContractInvalidType,
+    EContractMissingColumn,
+    EContractUnsorted,
+    ECovariateIncompleteKnown,
+    ECovariateLeakage,
+    ECovariateStaticInvalid,
+    EDSNotMonotonic,
+    EFallbackExhausted,
+    EFreqInferFail,
+    EModelFitFailed,
+    EModelLoadFailed,
+    EModelPredictFailed,
+    EQACriticalIssue,
+    EQALeakageDetected,
+    EQAMinHistory,
+    EQARepairPeeksFuture,
+    ESplitRandomForbidden,
+    ETaskSpecIncompatible,
+    ETaskSpecInvalid,
+    TSAgentKitError,
+    get_error_class,
+)
+from .results import (
+    CVFrame,
+    ForecastFrame,
+    ForecastResult,
+    ModelArtifact,
+    Provenance,
+    RepairReport,
+    RunArtifact,
+    ValidationReport,
+)
+from .schema import validate_contract
+from .task_spec import (
+    AggregationMode,
+    AnomalyMethod,
+    AnomalySpec,
+    BacktestSpec,
+    BaseSpec,
+    CalibratorSpec,
+    CovariatePolicy,
+    CovariateRole,
+    CovariateSpec,
+    ForecastContract,
+    IntervalMode,
+    MissingPolicy,
+    PanelContract,
+    PlanSpec,
+    RouteDecision,
+    RouterConfig,
+    RouterThresholds,
+    RunArtifactSpec,
+    SeasonalityMethod,
+    TaskSpec,
+)
+
+__all__ = [
+    # Errors
+    "TSAgentKitError",
+    "EContractInvalid",
+    "EContractMissingColumn",
+    "EContractInvalidType",
+    "EContractDuplicateKey",
+    "EContractUnsorted",
+    "EFreqInferFail",
+    "EDSNotMonotonic",
+    "ESplitRandomForbidden",
+    "EQAMinHistory",
+    "EQARepairPeeksFuture",
+    "EQACriticalIssue",
+    "EQALeakageDetected",
+    "ECovariateLeakage",
+    "ECovariateIncompleteKnown",
+    "ECovariateStaticInvalid",
+    "EModelFitFailed",
+    "EModelPredictFailed",
+    "EModelLoadFailed",
+    "EAdapterNotAvailable",
+    "EFallbackExhausted",
+    "EOOM",
+    "ETaskSpecInvalid",
+    "ETaskSpecIncompatible",
+    "EBacktestFail",
+    "EBacktestInsufficientData",
+    "EBacktestInvalidWindow",
+    "ECalibrationFail",
+    "EAnomalyFail",
+    "get_error_class",
+    # Results
+    "CVFrame",
+    "ForecastFrame",
+    "ForecastResult",
+    "ModelArtifact",
+    "Provenance",
+    "RepairReport",
+    "RunArtifact",
+    "ValidationReport",
+    # Schema
+    "validate_contract",
+    # Specs
+    "AggregationMode",
+    "AnomalyMethod",
+    "AnomalySpec",
+    "BacktestSpec",
+    "BaseSpec",
+    "CalibratorSpec",
+    "CovariatePolicy",
+    "CovariateRole",
+    "CovariateSpec",
+    "ForecastContract",
+    "IntervalMode",
+    "MissingPolicy",
+    "PanelContract",
+    "PlanSpec",
+    "RouteDecision",
+    "RouterConfig",
+    "RouterThresholds",
+    "RunArtifactSpec",
+    "SeasonalityMethod",
+    "TaskSpec",
+]

tsagentkit/contracts/errors.py

@@ -0,0 +1,275 @@
+"""Error codes and exceptions for tsagentkit.
+
+Defines structured error codes used throughout the pipeline.
+Aligned to docs/PRD.md Section 6.1 with compatibility aliases.
+"""
+
+# ruff: noqa: N818
+
+from typing import Any
+
+
+class TSAgentKitError(Exception):
+    """Base exception for all tsagentkit errors.
+
+    Attributes:
+        error_code: Unique error code string for programmatic handling
+        message: Human-readable error message
+        context: Additional context data for debugging
+    """
+
+    error_code: str = "E_UNKNOWN"
+
+    def __init__(
+        self,
+        message: str,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.context = context or {}
+
+    def __str__(self) -> str:
+        if self.context:
+            return f"[{self.error_code}] {self.message} (context: {self.context})"
+        return f"[{self.error_code}] {self.message}"
+
+
+# ---------------------------
+# Contract Errors
+# ---------------------------
+
+class EContractInvalid(TSAgentKitError):
+    """Input schema/contract invalid."""
+    error_code = "E_CONTRACT_INVALID"
+
+
+class EContractMissingColumn(TSAgentKitError):
+    """Input data is missing required columns."""
+    error_code = "E_CONTRACT_MISSING_COLUMN"
+
+
+class EContractInvalidType(TSAgentKitError):
+    """Column has invalid data type."""
+    error_code = "E_CONTRACT_INVALID_TYPE"
+
+
+class EContractDuplicateKey(TSAgentKitError):
+    """Duplicate (unique_id, ds) pairs found in data."""
+    error_code = "E_CONTRACT_DUPLICATE_KEY"
+
+
+class EFreqInferFail(TSAgentKitError):
+    """Frequency cannot be inferred/validated."""
+    error_code = "E_FREQ_INFER_FAIL"
+
+
+class EDSNotMonotonic(TSAgentKitError):
+    """Time index not monotonic per series."""
+    error_code = "E_DS_NOT_MONOTONIC"
+
+
+class ESplitRandomForbidden(TSAgentKitError):
+    """Random train/test splits are strictly forbidden."""
+    error_code = "E_SPLIT_RANDOM_FORBIDDEN"
+
+
+class EContractUnsorted(EDSNotMonotonic):
+    """Data is not sorted by (unique_id, ds)."""
+    error_code = "E_DS_NOT_MONOTONIC"
+
+
+# ---------------------------
+# QA Errors
+# ---------------------------
+
+class EQAMinHistory(TSAgentKitError):
+    """Series history too short."""
+    error_code = "E_QA_MIN_HISTORY"
+
+
+class EQARepairPeeksFuture(TSAgentKitError):
+    """Repair strategy violates PIT safety."""
+    error_code = "E_QA_REPAIR_PEEKS_FUTURE"
+
+
+class EQACriticalIssue(TSAgentKitError):
+    """Critical data quality issue detected in strict mode."""
+    error_code = "E_QA_CRITICAL_ISSUE"
+
+
+class EQALeakageDetected(TSAgentKitError):
+    """Data leakage detected in strict mode."""
+    error_code = "E_QA_LEAKAGE_DETECTED"
+
+
+# ---------------------------
+# Covariate Errors
+# ---------------------------
+
+class ECovariateLeakage(TSAgentKitError):
+    """Past/observed covariate leaks into future."""
+    error_code = "E_COVARIATE_LEAKAGE"
+
+
+class ECovariateIncompleteKnown(TSAgentKitError):
+    """Future-known covariate missing in horizon."""
+    error_code = "E_COVARIATE_INCOMPLETE_KNOWN"
+
+
+class ECovariateStaticInvalid(TSAgentKitError):
+    """Static covariate invalid cardinality."""
+    error_code = "E_COVARIATE_STATIC_INVALID"
+
+
+# ---------------------------
+# Model Errors
+# ---------------------------
+
+class EModelFitFailed(TSAgentKitError):
+    """Model fitting failed."""
+    error_code = "E_MODEL_FIT_FAIL"
+
+
+class EModelPredictFailed(TSAgentKitError):
+    """Model prediction failed."""
+    error_code = "E_MODEL_PREDICT_FAIL"
+
+
+class EModelLoadFailed(TSAgentKitError):
+    """Model loading failed."""
+    error_code = "E_MODEL_LOAD_FAILED"
+
+
+class EAdapterNotAvailable(TSAgentKitError):
+    """TSFM adapter not available."""
+    error_code = "E_ADAPTER_NOT_AVAILABLE"
+
+
+class EFallbackExhausted(TSAgentKitError):
+    """All models in the fallback ladder failed."""
+    error_code = "E_FALLBACK_EXHAUSTED"
+
+
+class EOOM(TSAgentKitError):
+    """Out-of-memory during fit/predict."""
+    error_code = "E_OOM"
+
+
+# ---------------------------
+# Task Spec Errors
+# ---------------------------
+
+class ETaskSpecInvalid(TSAgentKitError):
+    """Task specification is invalid or incomplete."""
+    error_code = "E_TASK_SPEC_INVALID"
+
+
+class ETaskSpecIncompatible(TSAgentKitError):
+    """Task spec is incompatible with data."""
+    error_code = "E_TASK_SPEC_INCOMPATIBLE"
+
+
+# ---------------------------
+# Backtest Errors
+# ---------------------------
+
+class EBacktestFail(TSAgentKitError):
+    """Backtest execution failed."""
+    error_code = "E_BACKTEST_FAIL"
+
+
+class EBacktestInsufficientData(TSAgentKitError):
+    """Not enough data for requested backtest windows."""
+    error_code = "E_BACKTEST_INSUFFICIENT_DATA"
+
+
+class EBacktestInvalidWindow(TSAgentKitError):
+    """Invalid backtest window configuration."""
+    error_code = "E_BACKTEST_INVALID_WINDOW"
+
+
+# ---------------------------
+# Calibration / Anomaly Errors
+# ---------------------------
+
+class ECalibrationFail(TSAgentKitError):
+    """Calibration failed."""
+    error_code = "E_CALIBRATION_FAIL"
+
+
+class EAnomalyFail(TSAgentKitError):
+    """Anomaly detection failed."""
+    error_code = "E_ANOMALY_FAIL"
+
+
+# Registry for lookup
+ERROR_REGISTRY: dict[str, type[TSAgentKitError]] = {
+    "E_CONTRACT_INVALID": EContractInvalid,
+    "E_CONTRACT_MISSING_COLUMN": EContractMissingColumn,
+    "E_CONTRACT_INVALID_TYPE": EContractInvalidType,
+    "E_CONTRACT_DUPLICATE_KEY": EContractDuplicateKey,
+    "E_FREQ_INFER_FAIL": EFreqInferFail,
+    "E_DS_NOT_MONOTONIC": EDSNotMonotonic,
+    "E_SPLIT_RANDOM_FORBIDDEN": ESplitRandomForbidden,
+    "E_CONTRACT_UNSORTED": EContractUnsorted,
+    "E_QA_MIN_HISTORY": EQAMinHistory,
+    "E_QA_REPAIR_PEEKS_FUTURE": EQARepairPeeksFuture,
+    "E_QA_CRITICAL_ISSUE": EQACriticalIssue,
+    "E_QA_LEAKAGE_DETECTED": EQALeakageDetected,
+    "E_COVARIATE_LEAKAGE": ECovariateLeakage,
+    "E_COVARIATE_INCOMPLETE_KNOWN": ECovariateIncompleteKnown,
+    "E_COVARIATE_STATIC_INVALID": ECovariateStaticInvalid,
+    "E_MODEL_FIT_FAIL": EModelFitFailed,
+    "E_MODEL_PREDICT_FAIL": EModelPredictFailed,
+    "E_MODEL_LOAD_FAILED": EModelLoadFailed,
+    "E_ADAPTER_NOT_AVAILABLE": EAdapterNotAvailable,
+    "E_FALLBACK_EXHAUSTED": EFallbackExhausted,
+    "E_OOM": EOOM,
+    "E_TASK_SPEC_INVALID": ETaskSpecInvalid,
+    "E_TASK_SPEC_INCOMPATIBLE": ETaskSpecIncompatible,
+    "E_BACKTEST_FAIL": EBacktestFail,
+    "E_BACKTEST_INSUFFICIENT_DATA": EBacktestInsufficientData,
+    "E_BACKTEST_INVALID_WINDOW": EBacktestInvalidWindow,
+    "E_CALIBRATION_FAIL": ECalibrationFail,
+    "E_ANOMALY_FAIL": EAnomalyFail,
+}
+
+
+def get_error_class(error_code: str) -> type[TSAgentKitError]:
+    """Get error class by error code."""
+    return ERROR_REGISTRY.get(error_code, TSAgentKitError)
+
+
+__all__ = [
+    "TSAgentKitError",
+    "EContractInvalid",
+    "EContractMissingColumn",
+    "EContractInvalidType",
+    "EContractDuplicateKey",
+    "EFreqInferFail",
+    "EDSNotMonotonic",
+    "ESplitRandomForbidden",
+    "EContractUnsorted",
+    "EQAMinHistory",
+    "EQARepairPeeksFuture",
+    "EQACriticalIssue",
+    "EQALeakageDetected",
+    "ECovariateLeakage",
+    "ECovariateIncompleteKnown",
+    "ECovariateStaticInvalid",
+    "EModelFitFailed",
+    "EModelPredictFailed",
+    "EModelLoadFailed",
+    "EAdapterNotAvailable",
+    "EFallbackExhausted",
+    "EOOM",
+    "ETaskSpecInvalid",
+    "ETaskSpecIncompatible",
+    "EBacktestFail",
+    "EBacktestInsufficientData",
+    "EBacktestInvalidWindow",
+    "ECalibrationFail",
+    "EAnomalyFail",
+    "get_error_class",
+]