"""HuggingFace Inference Endpoint custom handler for Kronos. Kronos (https://github.com/shiyu-coder/Kronos) is a foundation model for K-line forecasting. This handler loads the pretrained tokenizer + model from the HF hub once at startup, then accepts batches of historical OHLCV data and returns probabilistic forecasts (mean path + confidence band from N stochastic samples). Expected request body (JSON): { "history": [ {"timestamp": "2024-01-01", "open": 100.0, "high": 102.1, "low": 99.4, "close": 101.5, "volume": 1234567, "amount": null}, ... ], "pred_len": 30, # number of future steps to forecast "n_samples": 30, # stochastic samples (more = tighter CI, slower) "temperature": 1.0, # sampling temperature "top_p": 0.9, # nucleus sampling "seed": 0 # optional, for reproducibility } Response shape: { "predictions": [ {"step": 1, "open_mean": ..., "high_mean": ..., "low_mean": ..., "close_mean": ..., "volume_mean": ..., "close_low": ..., "close_high": ...}, ... ], "history_len": , "samples_used": , "model": "Kronos-small" } """ from __future__ import annotations import os from datetime import datetime, timedelta from typing import Any, Dict, List import numpy as np import pandas as pd import torch # Kronos itself lives in the shiyu-coder/Kronos repo. The HF endpoint image # clones the repo so `from model import Kronos, KronosTokenizer, KronosPredictor` # works directly. If you prefer to vendor the model files, copy `model/` from # the repo into the same dir as this handler. from model import Kronos, KronosPredictor, KronosTokenizer # type: ignore MODEL_REPO = os.environ.get("KRONOS_MODEL_REPO", "NeoQuasar/Kronos-small") TOKENIZER_REPO = os.environ.get( "KRONOS_TOKENIZER_REPO", "NeoQuasar/Kronos-Tokenizer-base" ) MAX_CONTEXT = int(os.environ.get("KRONOS_MAX_CONTEXT", "512")) DEFAULT_PRED_LEN = int(os.environ.get("KRONOS_DEFAULT_PRED_LEN", "30")) CI_LOWER = float(os.environ.get("KRONOS_CI_LOWER", "0.1")) # 10th percentile CI_UPPER = float(os.environ.get("KRONOS_CI_UPPER", "0.9")) # 90th percentile class EndpointHandler: """HuggingFace Inference Endpoint entrypoint. HF instantiates this once per worker; __call__ runs per request. """ def __init__(self, path: str = "") -> None: device = "cuda" if torch.cuda.is_available() else "cpu" # `path` is the local snapshot of the repo HF pulled into the container. # We still need the *separate* tokenizer repo, so go through from_pretrained. self.tokenizer = KronosTokenizer.from_pretrained(TOKENIZER_REPO) self.model = Kronos.from_pretrained(MODEL_REPO) self.predictor = KronosPredictor( model=self.model, tokenizer=self.tokenizer, device=device, max_context=MAX_CONTEXT, ) self.device = device def __call__(self, data: Dict[str, Any]) -> Dict[str, Any]: # HF endpoints wrap the body in {"inputs": ...}. Be liberal about # accepting either form so the same code works in local tests too. inputs = data.get("inputs", data) if isinstance(data, dict) else {} if not isinstance(inputs, dict): return {"error": "inputs must be a JSON object"} history = inputs.get("history") if not isinstance(history, list) or len(history) < 32: return { "error": "history must be a list of >=32 OHLCV bars", "received_len": len(history) if isinstance(history, list) else 0, } pred_len = int(inputs.get("pred_len", DEFAULT_PRED_LEN)) pred_len = max(1, min(pred_len, 120)) # Free HF Space is CPU-only; aggressive default keeps a request under ~3 min. default_samples = int(os.environ.get("KRONOS_DEFAULT_SAMPLES", "5")) n_samples = int(inputs.get("n_samples", default_samples)) n_samples = max(1, min(n_samples, 60)) temperature = float(inputs.get("temperature", 1.0)) top_p = float(inputs.get("top_p", 0.9)) seed = inputs.get("seed") if seed is not None: torch.manual_seed(int(seed)) np.random.seed(int(seed)) df, timestamps = _history_to_dataframe(history) future_timestamps = _project_timestamps(timestamps, pred_len) # KronosPredictor.predict returns a DataFrame of OHLCV predictions. # We call it n_samples times and stack to compute CI bands. This is # how the official Kronos examples produce probabilistic forecasts. sample_frames: List[pd.DataFrame] = [] for _ in range(n_samples): pred_df = self.predictor.predict( df=df, x_timestamp=pd.Series(timestamps), y_timestamp=pd.Series(future_timestamps), pred_len=pred_len, T=temperature, top_p=top_p, sample_count=1, ) sample_frames.append(pred_df.reset_index(drop=True)) # Stack into (n_samples, pred_len) arrays per column. cols = ["open", "high", "low", "close", "volume"] stacks = {c: np.stack([f[c].to_numpy() for f in sample_frames]) for c in cols} close_stack = stacks["close"] ci_low = np.quantile(close_stack, CI_LOWER, axis=0) ci_high = np.quantile(close_stack, CI_UPPER, axis=0) predictions = [] for i in range(pred_len): row = { "step": i + 1, "timestamp": future_timestamps[i].isoformat(), "close_low": float(ci_low[i]), "close_high": float(ci_high[i]), } for c in cols: row[f"{c}_mean"] = float(stacks[c][:, i].mean()) predictions.append(row) return { "predictions": predictions, "history_len": len(history), "samples_used": n_samples, "pred_len": pred_len, "model": MODEL_REPO.split("/")[-1], "ci_lower_pct": CI_LOWER, "ci_upper_pct": CI_UPPER, } def _history_to_dataframe( history: List[Dict[str, Any]], ) -> tuple[pd.DataFrame, List[datetime]]: rows = [] timestamps: List[datetime] = [] for bar in history: ts = bar.get("timestamp") if isinstance(ts, str): timestamps.append(pd.to_datetime(ts).to_pydatetime()) elif isinstance(ts, (int, float)): timestamps.append(datetime.utcfromtimestamp(float(ts))) else: # If timestamps weren't provided, synthesize a daily index. Kronos # doesn't actually condition on absolute dates, only their spacing, # so this is safe as long as the caller's history really is daily. timestamps.append(datetime(2000, 1, 1) + timedelta(days=len(timestamps))) rows.append( { "open": float(bar.get("open") or bar.get("close") or 0.0), "high": float(bar.get("high") or bar.get("close") or 0.0), "low": float(bar.get("low") or bar.get("close") or 0.0), "close": float(bar.get("close") or 0.0), "volume": float(bar.get("volume") or 0.0), # Kronos also wants `amount` (turnover). If absent, derive from # close*volume which is a reasonable proxy for daily turnover. "amount": float( bar.get("amount") or (bar.get("close") or 0.0) * (bar.get("volume") or 0.0) ), } ) df = pd.DataFrame(rows) return df, timestamps def _project_timestamps(history_ts: List[datetime], pred_len: int) -> List[datetime]: """Estimate the spacing of the history and roll forward by pred_len steps.""" if len(history_ts) < 2: step = timedelta(days=1) else: deltas = [ (history_ts[i] - history_ts[i - 1]) for i in range(1, len(history_ts)) ] # Use the median spacing; robust to weekends/holidays in daily data. deltas_sorted = sorted(deltas) step = deltas_sorted[len(deltas_sorted) // 2] if step <= timedelta(0): step = timedelta(days=1) last = history_ts[-1] return [last + step * (i + 1) for i in range(pred_len)] if __name__ == "__main__": # Smoke test: generate a sine-wave history and forecast 10 steps. handler = EndpointHandler() n = 256 base = 100 + 5 * np.sin(np.linspace(0, 8 * np.pi, n)) fake_hist = [ { "timestamp": (datetime(2024, 1, 1) + timedelta(days=i)).isoformat(), "open": float(base[i]), "high": float(base[i] * 1.01), "low": float(base[i] * 0.99), "close": float(base[i]), "volume": 1_000_000, } for i in range(n) ] out = handler({"inputs": {"history": fake_hist, "pred_len": 10, "n_samples": 4}}) print(out)