Upload forecast.py

schemas/forecast.py

@@ -0,0 +1,329 @@
+"""Typed request/response models for the Timestral forecasting endpoints.
+
+Every series is a univariate chunk of timestamp + amounts. Timestamps are
+normalized to UTC (naive values are treated as UTC). Quantile levels must come
+from Timestral's native 21-level grid so responses map 1:1 to model output.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+Frequency = Literal["auto", "hourly", "daily", "business_daily", "weekly", "monthly"]
+ModelSize = Literal["5M", "28M", "123M", "209M", "ensemble"]
+Transform = Literal["levels", "log_returns"]
+
+DEFAULT_QUANTILES: tuple[float, ...] = (0.1, 0.5, 0.9)
+
+# Timestral heads emit 21 quantiles: fixed 0.05 steps inside 0.05..0.95 plus the
+# 0.01/0.99 tails. Levels outside this grid cannot be sliced from model output.
+NATIVE_QUANTILE_LEVELS: tuple[float, ...] = tuple(
+    sorted({round(0.05 * i, 2) for i in range(1, 20)} | {0.01, 0.99})
+)
+
+
+class SeriesPoint(BaseModel):
+    """One observed amount at one timestamp."""
+
+    timestamp: datetime = Field(
+        description="ISO-8601 timestamp. Values without timezone are treated as UTC."
+    )
+    value: float = Field(
+        description="Observed amount (price, portfolio value, ...). Must be finite.",
+    )
+
+
+class SeriesInput(BaseModel):
+    """A named univariate series of timestamp + amount pairs."""
+
+    name: str = Field(
+        min_length=1,
+        max_length=64,
+        description="Series label, echoed in the response and used in summaries.",
+    )
+    points: list[SeriesPoint] = Field(
+        min_length=2,
+        max_length=20000,
+        description="Historical observations. Duplicated timestamps are averaged; "
+        "gaps are resampled away and read as missing values by the model.",
+    )
+
+
+class ForecastRequest(BaseModel):
+    """Forecast one or more univariate series with a Timestral checkpoint."""
+
+    series: list[SeriesInput] = Field(
+        min_length=1,
+        max_length=12,
+        description="Each series is forecast independently (one variate per row).",
+    )
+    horizon: int = Field(
+        default=30,
+        ge=1,
+        le=1024,
+        description="Steps ahead to predict, in grid steps of the resolved frequency.",
+    )
+    frequency: Frequency = Field(
+        default="auto",
+        description="'auto' infers the grid from timestamp spacing. 'business_daily' "
+        "collapses to Mon-Fri steps (weekend points merge into the next business day).",
+    )
+    quantiles: list[float] = Field(
+        default_factory=lambda: list(DEFAULT_QUANTILES),
+        description="Levels to return per step, from Timestral's native 21-level grid.",
+    )
+    model_size: ModelSize = Field(
+        default="28M",
+        description="Checkpoint size; 'ensemble' averages the quantile paths of "
+        "28M/123M/209M (see TIMESTRAL_ENSEMBLE_SIZES).",
+    )
+    transform: Transform = Field(
+        default="levels",
+        description="'log_returns' forecasts log-returns and compounds each quantile "
+        "path back to amount space (requires strictly positive values).",
+    )
+    context_length: int | None = Field(
+        default=None,
+        ge=32,
+        le=32768,
+        description="Cap the history fed to the model to the most recent N grid steps.",
+    )
+    symmetric_averaging: bool = Field(
+        default=True,
+        description="Forecaster's symmetric-averaging test-time augmentation. "
+        "Disable to halve inference time at some accuracy cost.",
+    )
+    clip_nonnegative: bool = Field(
+        default=True,
+        description="Clamp forecasts at 0 for series whose history is non-negative.",
+    )
+
+    @field_validator("quantiles")
+    @classmethod
+    def _check_quantiles(cls, levels: list[float]) -> list[float]:
+        if not levels:
+            raise ValueError(
+                "quantiles must not be empty; pick from Timestral's native levels"
+            )
+        allowed = set(NATIVE_QUANTILE_LEVELS)
+        unknown = sorted(set(levels) - allowed)
+        if unknown:
+            raise ValueError(
+                f"quantiles must come from Timestral's 21 native levels, e.g. 0.1/0.5/0.9; "
+                f"got {unknown!r}. Native levels: {sorted(allowed)}"
+            )
+        return sorted(set(levels))
+
+    @model_validator(mode="after")
+    def _check_unique_names(self) -> "ForecastRequest":
+        names = [s.name for s in self.series]
+        if len(names) != len(set(names)):
+            raise ValueError("series names must be unique")
+        return self
+
+
+class ForecastStep(BaseModel):
+    """One forecast step: timestamp, median, and quantile band."""
+
+    timestamp: datetime
+    median: float
+    quantiles: dict[str, float] = Field(
+        default_factory=dict,
+        description="Requested levels keyed as '0.10' style, e.g. {'0.10': ..., '0.90': ...}",
+    )
+
+
+class ForecastSummary(BaseModel):
+    """Finance-oriented reading of one forecast at the horizon end."""
+
+    last_observed: float = Field(description="Last observed amount (series anchor).")
+    horizon_end_median: float
+    expected_change_pct: float | None = Field(
+        default=None,
+        description="Percent change of the median path at the horizon end vs the last observed amount.",
+    )
+    prob_below_start: float | None = Field(
+        default=None,
+        description="Probability the amount ends below its last observed value, "
+        "interpolated from the marginal quantiles at the horizon end.",
+    )
+    var_95_abs: float | None = Field(
+        default=None,
+        description="Value-at-risk at 95% vs the last observed amount (0 = no downside).",
+    )
+    var_95_pct: float | None = None
+    p10_horizon_end: float | None = Field(
+        default=None,
+        description="10th-percentile amount at the horizon end (band floor).",
+    )
+    p90_horizon_end: float | None = None
+
+
+class SeriesForecast(BaseModel):
+    """Forecast for one named series."""
+
+    name: str
+    context_steps: int = Field(description="Grid steps fed to the model.")
+    context_start: datetime = Field(description="First grid timestamp fed to the model.")
+    context_end: datetime = Field(
+        description="Grid timestamp of the last observed step (forecast anchor)."
+    )
+    points: list[ForecastStep]
+    summary: ForecastSummary
+
+
+class ForecastResponse(BaseModel):
+    """Probabilistic forecast for every requested series."""
+
+    model: str = Field(description="Timestral repo ids used (joined for ensembles).")
+    model_size: str = Field(description="Requested size ('5M'..'209M' or 'ensemble').")
+    frequency: str = Field(description="Frequency actually used (never 'auto').")
+    transform: str
+    horizon: int
+    context_steps: int = Field(description="Largest per-series context fed to the model.")
+    generated_at: datetime
+    warnings: list[str] = Field(default_factory=list)
+    items: list[SeriesForecast]
+
+
+class PortfolioSummary(BaseModel):
+    """The single-series finance summary for the portfolio projection."""
+
+    last_value: float
+    horizon_steps: int
+    steps_per_year: float = Field(description="Horizon steps per year of the frequency.")
+    cagr_percent: float | None = Field(
+        default=None,
+        description="Median-path growth annualized over the horizon (None for non-positive values).",
+    )
+    horizon_end_median: float
+    expected_change_pct: float | None = None
+    prob_below_start: float | None = None
+    var_95_abs: float | None = None
+    var_95_pct: float | None = None
+    p10_horizon_end: float | None = None
+    p90_horizon_end: float | None = None
+
+
+class PortfolioForecastResponse(ForecastResponse):
+    """Portfolio projection: one series forecast plus a finance summary block."""
+
+    portfolio: PortfolioSummary
+
+
+class BacktestRequest(BaseModel):
+    """Walk-forward validation request (same knobs as the forecast)."""
+
+    series: list[SeriesInput] = Field(min_length=1, max_length=12)
+    frequency: Frequency = "auto"
+    model_size: ModelSize = "28M"
+    transform: Transform = "levels"
+    context_length: int | None = Field(default=None, ge=32, le=32768)
+    symmetric_averaging: bool = True
+    clip_nonnegative: bool = True
+    folds: int = Field(
+        default=4,
+        ge=1,
+        le=12,
+        description="Number of walk-forward folds; reduced automatically when the "
+        "history cannot support them.",
+    )
+    fold_horizon: int | None = Field(
+        default=None,
+        ge=1,
+        le=365,
+        description="Validation length per fold; defaults to min(30, history/8) with a floor of 4.",
+    )
+
+    @model_validator(mode="after")
+    def _check_unique_names(self) -> "BacktestRequest":
+        names = [s.name for s in self.series]
+        if len(names) != len(set(names)):
+            raise ValueError("series names must be unique")
+        return self
+
+
+class BacktestFoldMetrics(BaseModel):
+    """Point and probabilistic quality of one fold's median/band forecast."""
+
+    origin: datetime = Field(description="First holdout step of the fold.")
+    horizon: int
+    mae: float | None = None
+    mase: float | None = Field(
+        default=None,
+        description="MAE scaled by the mean absolute 1-step naive difference of the fold's training slice.",
+    )
+    smape: float | None = None
+    crps: float | None = Field(
+        default=None,
+        description="Probabilistic error approximated as twice the mean pinball loss "
+        "over Timestral's native quantile levels.",
+    )
+    coverage_80: float | None = Field(
+        default=None,
+        description="Fraction of holdout steps inside the 10-90% band.",
+    )
+
+
+class BacktestMeanMetrics(BaseModel):
+    """Fold means (None where a metric was never computable)."""
+
+    mae: float | None = None
+    mase: float | None = None
+    smape: float | None = None
+    crps: float | None = None
+    coverage_80: float | None = None
+
+
+class BacktestSeriesResult(BaseModel):
+    """Backtest for one series: per-fold metrics plus fold means."""
+
+    name: str
+    folds: list[BacktestFoldMetrics]
+    mean: BacktestMeanMetrics
+
+
+class BacktestResponse(BaseModel):
+    """Walk-forward validation for every requested series."""
+
+    model: str
+    model_size: str
+    frequency: str
+    transform: str
+    folds: int
+    fold_horizon: int
+    generated_at: datetime
+    warnings: list[str] = Field(default_factory=list)
+    items: list[BacktestSeriesResult]
+
+
+class ModelInfo(BaseModel):
+    """One selectable Timestral checkpoint."""
+
+    size: str
+    repo_id: str
+    loaded: bool
+
+
+class ModelsResponse(BaseModel):
+    """Available checkpoints and loader configuration."""
+
+    default_size: str
+    device: str
+    max_context: int
+    ensemble_sizes: list[str]
+    models: list[ModelInfo]
+
+
+class ForecastHealth(BaseModel):
+    """Loader state of the forecasting service."""
+
+    status: str
+    device: str
+    default_size: str
+    loaded_sizes: list[str]
+    context_cap: int
+    timeout_seconds: float