Update branding to SuperAI Forecast

README.md

@@ -1,59 +1,38 @@
 ---
-title: Kronos AI
-emoji: 🚀
+title: SuperAI Forecast
+emoji: "📈"
 colorFrom: blue
-colorTo: red
+colorTo: cyan
 sdk: docker
 app_port: 7860
 pinned: false
 ---
-# Kronos AI Analysis
+# SuperAI Forecast
 
-Kronos AI Analysis is a FastAPI + Lightweight Charts application for:
+SuperAI Forecast is a FastAPI + Lightweight Charts application for live market analysis with a multi-model AI forecast stack: Kronos, Google TimesFM, and Amazon Chronos.
 
-- loading market data from multiple providers with automatic fallback
-- calculating technical indicators
-- generating AI forecasts with Kronos
-- serving the web UI directly from the backend
+## Core Features
 
-## Runtime Requirements
-
-- Windows with Python 3.11 installed
-- Internet access for live market data
-- Internet access on first Kronos model load if the model is not already cached locally
-
-## Project Layout
+- multi-source OHLCV data with automatic fallback
+- technical indicator calculation
+- independent Kronos / TimesFM / Chronos forecasting
+- unified OHLC4 forecast contract across all AI models
+- real-time WebSocket price streaming
+- single-origin frontend served directly from the backend
 
-```text
-Kronos_AI_Analysis/
-|-- backend/
-|   |-- main.py
-|   `-- launcher.py
-|-- frontend/
-|   `-- index.html
-|-- Kronos-master/
-|   `-- model/
-|-- dist/
-|   `-- SuperAI_Analysis.exe
-|-- requirements.txt
-`-- run_server.bat
-```
+## Runtime Requirements
 
-## Recommended Start
+- Windows with Python 3.11
+- Internet access for market data
+- Internet access on the first TimesFM model load if the checkpoint is not cached locally
 
-Run:
+## Quick Start
 
 ```bat
-run_server.bat
+run.bat
 ```
 
-The startup script now:
-
-1. checks Python 3.11
-2. repairs a broken virtual environment if needed
-3. installs the full runtime dependency set
-4. verifies Kronos can be imported
-5. starts the FastAPI server on a random free local port and opens the browser automatically
+The launcher validates the virtual environment, ensures the local AI model dependencies are ready, applies the TimesFM compatibility patch, starts the backend, and opens the dashboard automatically.
 
 ## Manual Start
 
@@ -63,15 +42,30 @@ venv\Scripts\python.exe -m pip install -r requirements.txt
 venv\Scripts\python.exe -m backend.launcher
 ```
 
-## Important Notes
+## Project Layout
 
-- This project uses Kronos, not TimesFM.
-- Hugging Face Docker Spaces are pinned to port `7860`, while the local Windows launcher uses a random free port.
-- Kronos source code is loaded from `Kronos-master`.
-- Kronos weights are loaded from Hugging Face via:
-  - `NeoQuasar/Kronos-base`
-  - `NeoQuasar/Kronos-Tokenizer-base`
-- The first AI forecast can take longer because the model may warm up or download into cache.
+```text
+SuperAI Forecast/
+|-- backend/
+|   |-- main.py
+|   |-- frontend_assets.py
+|   |-- launcher.py
+|   |-- server_runtime.py
+|   |-- forecasting/
+|   `-- startup_utils.py
+|-- frontend/
+|   |-- app.js
+|   |-- forecast-models.js
+|   |-- index.html
+|   |-- workspace.js
+|   `-- workspace.css
+|-- libs/
+|   `-- chronos-forecasting/
+|-- scripts/
+|   `-- patch_timesfm.py
+|-- requirements.txt
+`-- run.bat
+```
 
 ## Key Endpoints
 
@@ -84,18 +78,29 @@ venv\Scripts\python.exe -m backend.launcher
 - `GET /api/crypto/market`
 - `WS /ws/price/{symbol}`
 
+## SuperAI Forecast Contract
+
+- Input to every AI model is a single `OHLC4` series built as `(open + high + low + close) / 4`.
+- The recommended context length is `512`, with model-specific fallback windows when the source history is shorter.
+- The default horizon is `10`, so each enabled AI model predicts `T+1 ... T+10`.
+- Output from each AI model is an independent future `OHLC4` line with quantiles `p10`, `p50`, `p90`.
+- API responses expose both `last_close` (market close) and `last_ohlc4` (forecast baseline) so downstream analysis stays explicit and stable.
+- Frontend rendering uses one forecast line per model, a shared horizon/timeframe contract, and a versioned asset registry for consistent model/UI alignment.
+
 ## Health Expectations
 
 When the system is healthy:
 
 - `/api/health` returns `status: online`
+- `timesfm.available` is `true`
+- `chronos.available` is `true`
 - `kronos.available` is `true`
-- `kronos.loaded` becomes `true` after warmup or after the first forecast
+- each model reports its own readiness state after warmup or after the first forecast
 - the frontend loads from the same backend origin
 
 ## Troubleshooting
 
-- If Python 3.11 is missing, install it first.
-- If a previous `venv` was copied from another machine, `run_server.bat` rebuilds it.
-- If forecasts fail, check `/api/health` and confirm Kronos reports as available and loaded.
-- If market data fails, check network reachability to Binance, Bybit, CoinGecko, Twelve Data, Finnhub, and Yahoo Finance.
+- Install Python 3.11 if it is missing.
+- Rebuild `venv` if it was copied from another machine.
+- If forecasts fail, check `/api/health` and confirm the target model is available and loaded.
+- If market data fails, verify connectivity to Binance, Bybit, CoinGecko, Twelve Data, Finnhub, and Yahoo Finance.

_ai_refactor.py

@@ -1,166 +0,0 @@
-import re
-path = r'd:\Python\Kronos_Platform_V1\frontend\index.html'
-with open(path, 'r', encoding='utf-8') as f:
-    content = f.read()
-
-# 1. Add fetchPaneAI function (or modify fetchAIAnalysis)
-# Actually, let's just append fetchPaneAI function before fetchAIAnalysis
-# and update the UI binding.
-
-new_fetch_code = """
-    // --- MULTI-PANE AI FETCH ---
-    async function fetchPaneAI(pane, options = {}) {
-      const symbol = pane.symbol;
-      const interval = pane.interval;
-      const horizon = pane.horizon || 24;
-      const requestKey = `${symbol}|${interval}|${horizon}`;
-
-      if (!options.force && pane.analysisRequestPromise && pane.analysisRequestKey === requestKey) {
-        return pane.analysisRequestPromise;
-      }
-
-      if (pane.analysisRetryTimer) {
-        clearTimeout(pane.analysisRetryTimer);
-        pane.analysisRetryTimer = null;
-      }
-      if (pane.analysisFetchController) {
-        pane.analysisFetchController.abort();
-      }
-
-      const controller = new AbortController();
-      pane.analysisFetchController = controller;
-      pane.analysisRequestKey = requestKey;
-
-      if (pane.paneId === Workspace.activePaneId && !pane.lastAnalysis?.payload) {
-         const panel = document.getElementById('analysisPanel');
-         panel.innerHTML = `<div class="dash-loading"><div class="loader-ring"></div><p>AI dang tinh toan...</p></div>`;
-      }
-
-      const requestPromise = (async () => {
-        try {
-          const fData = await DataCoordinator.fetchForecast(symbol, interval, horizon, controller.signal);
-          if (pane.symbol !== symbol || pane.interval !== interval) return null;
-
-          pane.lastAnalysis = { payload: fData, symbol, interval };
-          const hasForecast = Array.isArray(fData.forecast) && fData.forecast.length > 0;
-
-          if (hasForecast && pane.lastCandleData) {
-            const forecastPoints = fData.forecast;
-            const anchorPoint = { time: pane.lastCandleData.time, value: pane.lastCandleData.close };
-            const futurePoints = forecastPoints.filter(d => d && d.time !== undefined && d.p50 !== undefined && d.time !== pane.lastCandleData.time).map(d => ({ time: d.time, value: d.p50 }));
-            const p50 = [anchorPoint, ...futurePoints];
-            const p10 = [anchorPoint, ...forecastPoints.filter(d => d && d.time !== undefined && d.p10 !== undefined && d.time !== pane.lastCandleData.time).map(d => ({ time: d.time, value: d.p10 }))];
-            const p90 = [anchorPoint, ...forecastPoints.filter(d => d && d.time !== undefined && d.p90 !== undefined && d.time !== pane.lastCandleData.time).map(d => ({ time: d.time, value: d.p90 }))];
-
-            if (pane.forecastSeries) {
-               pane.forecastSeries.p50.setData([]);
-               pane.forecastSeries.p10.setData(p10);
-               pane.forecastSeries.p90.setData(p90);
-               
-               // For segments we need a helper since it's complex, or just ignore segments per-pane to keep it fast
-               // Actually we can reuse buildForecastSegmentSeries but pass the pane
-               buildPaneForecastSegments(pane, p50);
-            }
-          }
-
-          if (pane.paneId === Workspace.activePaneId) {
-             renderAnalysisPanel(symbol, interval, fData);
-             renderCompactGauges(symbol, interval, fData);
-             updateDashboardScale();
-          } else {
-             // For non-active panes, render gauges into their mini container
-             renderPaneGauges(pane, fData);
-          }
-
-          return fData;
-        } catch (e) {
-          if (e.name === 'AbortError') return null;
-          console.error(`[Pane ${pane.paneId}] AI Error:`, e);
-          return null;
-        } finally {
-          if (pane.analysisFetchController === controller) pane.analysisFetchController = null;
-        }
-      })();
-
-      pane.analysisRequestPromise = requestPromise;
-      try {
-         return await requestPromise;
-      } finally {
-         if (pane.analysisRequestPromise === requestPromise) {
-            pane.analysisRequestPromise = null;
-            pane.analysisRequestKey = null;
-         }
-      }
-    }
-
-    function buildPaneForecastSegments(pane, p50) {
-       if (!pane.forecastSeries || !pane.forecastSeries.segments) return;
-       const sGroup = pane.forecastSeries.segments;
-       sGroup.forEach(s => s.setData([]));
-       if (p50.length < 2) return;
-       for (let i = 0; i < p50.length - 1; i++) {
-          if (i >= sGroup.length) {
-             const ns = pane.chartInstance.addLineSeries({
-               color: 'rgba(34,211,238,0.8)', lineWidth: 2, lineStyle: 0,
-               crosshairMarkerVisible: false, lastValueVisible: false, priceLineVisible: false
-             });
-             sGroup.push(ns);
-          }
-          const pA = p50[i], pB = p50[i+1];
-          const clr = pB.value >= pA.value ? 'rgba(34,211,238,0.8)' : 'rgba(251,113,133,0.8)';
-          sGroup[i].applyOptions({ color: clr });
-          sGroup[i].setData([pA, pB]);
-       }
-    }
-
-    function renderPaneGauges(pane, payload) {
-       if (!pane.gaugesEl) return;
-       if (!payload || !payload.analysis) {
-          pane.gaugesEl.innerHTML = '';
-          return;
-       }
-       // Build mini gauges
-       const a = payload.analysis;
-       const tScore = typeof a.trend_score === 'number' ? a.trend_score : 50;
-       const sScore = typeof a.strength_score === 'number' ? a.strength_score : 50;
-       const vScore = typeof a.volatility_score === 'number' ? a.volatility_score : 50;
-       
-       const cT = tScore > 60 ? '#22d3ee' : (tScore < 40 ? '#fb7185' : '#94a3b8');
-       const cS = sScore > 60 ? '#818cf8' : (sScore < 40 ? '#fb7185' : '#94a3b8');
-       const cV = vScore > 60 ? '#fb923c' : (vScore < 40 ? '#2dd4bf' : '#94a3b8');
-
-       pane.gaugesEl.innerHTML = `
-          <div style="width:20px;height:20px;border-radius:50%;border:2px solid ${cT};display:flex;align-items:center;justify-content:center;background:var(--bg-depth);">
-             <span style="font-size:8px;font-weight:bold;color:${cT}">${tScore > 50 ? '↑' : '↓'}</span>
-          </div>
-       `;
-    }
-
-    // Replace the active pane listener
-    Workspace._onActivePaneChange = (newPaneId) => {
-       const pane = Workspace.getPane(newPaneId);
-       if (!pane) return;
-       // Sync toolbar
-       if (currentSymbol !== pane.symbol || timeframeSelect.value !== pane.interval) {
-          currentSymbol = pane.symbol;
-          searchInput.value = pane.symbol;
-          timeframeSelect.value = pane.interval;
-          if (window.initSymbolDetails) initSymbolDetails();
-       }
-       // Update AI Panel
-       if (pane.lastAnalysis?.payload) {
-          renderAnalysisPanel(pane.symbol, pane.interval, pane.lastAnalysis.payload);
-          renderCompactGauges(pane.symbol, pane.interval, pane.lastAnalysis.payload);
-          updateDashboardScale();
-       } else {
-          document.getElementById('analysisPanel').innerHTML = '';
-          document.getElementById('chartGauges').innerHTML = '';
-          fetchPaneAI(pane);
-       }
-    };
-
-    // Hook into loadPaneData
-"""
-
-with open('_ai_refactor.txt', 'w') as f:
-    f.write(new_fetch_code)

app.py

@@ -1,27 +1,9 @@
 from __future__ import annotations
 
-import os
-import socket
-
 import uvicorn
+from backend.server_runtime import bootstrap_runtime_port, resolve_server_port
 
-def find_free_port(host: str = "127.0.0.1") -> int:
-    """Ask the OS for a currently available local TCP port."""
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server_socket:
-        server_socket.bind((host, 0))
-        server_socket.listen(1)
-        return int(server_socket.getsockname()[1])
-
-
-def is_huggingface_space() -> bool:
-    """Return True when running inside a Hugging Face Space runtime."""
-    return bool(os.getenv("SPACE_ID") or os.getenv("SPACE_HOST"))
-
-
-def bootstrap_runtime_port() -> None:
-    """Seed PORT early so backend imports cannot override the Hugging Face runtime port."""
-    if is_huggingface_space() and not os.getenv("PORT", "").strip():
-        os.environ["PORT"] = "7860"
+DEFAULT_HOST = "0.0.0.0"
 
 
 bootstrap_runtime_port()
@@ -29,19 +11,5 @@ bootstrap_runtime_port()
 from backend.main import app
 
 
-def resolve_server_port() -> int:
-    """Use the runtime PORT when defined, keep Hugging Face on 7860, else pick a free local port."""
-    raw_port = os.getenv("PORT", "").strip()
-    if raw_port:
-        return int(raw_port)
-    if is_huggingface_space():
-        os.environ["PORT"] = "7860"
-        return 7860
-
-    port = find_free_port()
-    os.environ["PORT"] = str(port)
-    return port
-
-
 if __name__ == "__main__":
-    uvicorn.run(app, host="0.0.0.0", port=resolve_server_port())
+    uvicorn.run(app, host=DEFAULT_HOST, port=resolve_server_port(DEFAULT_HOST))

backend/forecasting/AI_MODEL_RULES.md

@@ -0,0 +1,79 @@
+# Quy tắc vận hành cho AI Forecast Models
+
+## 1. Chuẩn đầu vào
+
+- Dữ liệu đầu vào của mọi model AI là một chuỗi lịch sử `OHLC4` đúng `timeframe`.
+- `OHLC4 = (open + high + low + close) / 4`.
+- Chuỗi phải tăng dần theo thời gian, không đảo thứ tự, không chứa `NaN`, `inf`, giá trị rỗng hoặc timestamp lỗi.
+- Chuỗi phải đồng nhất timeframe trong toàn bộ context.
+- Mỗi lần inference phải được cắt context riêng cho từng model, không tái sử dụng hidden state, sample path, scaler hay tokenizer state của model khác.
+- `context length` tối thiểu cho inference là `32`.
+- `context length` khuyến nghị mặc định là `512` khi đủ dữ liệu.
+- `horizon` và `timeframe` là hai tham số dùng chung giữa các model; mọi tham số nội bộ khác phải độc lập theo từng model.
+
+## 2. Chuẩn đầu ra
+
+- Với `horizon = 10` mặc định, mỗi model AI phải dự báo đúng `10` giá trị `OHLC4` tương lai:
+  - `T+1`, `T+2`, `T+3`, `T+4`, `T+5`, `T+6`, `T+7`, `T+8`, `T+9`, `T+10`.
+- Chuẩn output thống nhất cho mọi model:
+  - `p10`
+  - `p50`
+  - `p90`
+- `p50` là đường dự báo chính để hiển thị "Dự báo AI".
+- Backend phải tạo dãy timestamp tương lai khớp chính xác với `timeframe` đầu vào.
+- Frontend phải nối tuần tự các điểm `p50` thành một line duy nhất cho từng model.
+- Điểm neo đầu tiên luôn là giá trị `OHLC4` hiện tại tại `T0`.
+
+## 3. Tính độc lập giữa các model
+
+- `Kronos`, `TimesFM`, `Chronos` phải chạy độc lập hoàn toàn.
+- Một model lỗi không được làm hỏng kết quả của model khác.
+- Cache phải phân biệt theo:
+  - `symbol`
+  - `timeframe`
+  - `horizon`
+  - `model selection`
+  - `rules version`
+- Log, warmup state, import error và device state phải theo từng model riêng.
+
+## 4. Quy tắc backend chuyên nghiệp
+
+- Mỗi model phải có adapter/provider riêng, không nhét logic model trực tiếp vào route.
+- Mọi adapter phải cùng tuân thủ một contract forecast thống nhất.
+- Validation chỉ bắt buộc ở biên hệ thống:
+  - dữ liệu lịch sử đầu vào
+  - output quantile
+  - timestamp tương lai
+- Sampling model phải có seed ổn định để tái lập kết quả khi cùng input.
+- Warmup model là lazy-load an toàn bằng lock async.
+- Inference phải có lock riêng theo model để tránh race condition khi cùng tải local GPU/CPU.
+- Response schema phải luôn giữ ổn định kể cả khi một model bị skip hoặc unavailable.
+- Mỗi model phải trả về metadata tối thiểu:
+  - tên model
+  - context length đã dùng
+  - horizon đầu ra
+  - input semantics
+  - output semantics
+  - output validation
+  - ai runtime
+
+## 5. Quy tắc hiển thị
+
+- Mỗi model có line forecast riêng.
+- Độ dày mặc định của các đường dự báo AI là: `1`.
+- Đường tổng hợp chỉ được tạo từ các model đang enabled và success.
+- Màu line phải phản ánh hướng đi của chính line forecast đó, không dùng trạng thái của model khác.
+- Khi người dùng rê chuột vào một đường forecast, giao diện phải hiển thị rõ đó là đường của model nào.
+- Chronos dùng palette riêng:
+  - tăng: xanh lá đậm
+  - sideway: xám vàng
+  - giảm: hồng đậm
+
+## 6. Quy tắc bảo trì
+
+- Thêm model mới phải chỉ cần:
+  - thêm provider
+  - đăng ký vào config
+  - nối vào frontend toggle/series
+- Không sửa contract chung chỉ để phục vụ một model đơn lẻ.
+- Mọi thay đổi lớn ở forecast subsystem phải có test regression cho payload và selection logic.

backend/forecasting/ARCHITECTURE.md

@@ -0,0 +1,90 @@
+# Forecasting Backend Architecture
+
+## Mục tiêu
+
+- Tách riêng forecasting subsystem khỏi route monolith.
+- Chuẩn hóa contract dùng chung cho `Kronos`, `TimesFM`, `Chronos`.
+- Bảo đảm mỗi model inference độc lập, có warmup/state/cache/log riêng.
+
+## Cấu trúc hiện tại
+
+- `config.py`
+  - Danh sách model chuẩn.
+  - Default selection.
+  - Hàm chuẩn hóa `model_selection`.
+- `rules.py`
+  - Load file `AI_MODEL_RULES.md`.
+  - Sinh `rules version` để dùng cho cache key và response metadata.
+- `AI_MODEL_RULES.md`
+  - Nguồn quy tắc vận hành chính thức cho forecast subsystem.
+- `providers/timesfm_provider.py`
+  - Provider TimesFM theo contract OHLC4 chuẩn.
+- `providers/chronos_provider.py`
+  - Provider Chronos theo contract OHLC4 chuẩn.
+- `backend/kronos_adapter.py`
+  - Provider Kronos hiện hữu, tiếp tục được dùng như provider độc lập.
+
+## Contract provider
+
+Mỗi provider phải đảm bảo:
+
+- Input là chuỗi lịch sử OHLC4 cùng timeframe.
+- Output thống nhất:
+  - `p10`
+  - `p50`
+  - `p90`
+  - `model_name`
+  - `context_length`
+  - `output_horizon`
+  - `input_semantics`
+  - `input_validation`
+  - `output_semantics`
+  - `output_validation`
+- Lazy-load an toàn bằng async lock.
+- Predict lock riêng để tránh race condition trên CPU/GPU cục bộ.
+
+## Runtime state
+
+Mỗi model có startup state độc lập:
+
+- `available`
+- `preload_enabled`
+- `warming`
+- `loaded`
+- `device`
+- `last_error`
+- `model`
+
+## Cache rules
+
+Forecast cache key phải phân biệt theo:
+
+- `symbol`
+- `interval`
+- `horizon`
+- `model selection`
+- `rules version`
+
+## Response rules
+
+`/api/forecast/{symbol}` luôn trả:
+
+- `forecast`
+- `forecast_models`
+- `model_selection`
+- `forecast_contract`
+- `rules`
+
+Nhờ vậy frontend và test regression có thể bám vào một schema ổn định khi thêm model mới.
+
+## Frontend integration
+
+Frontend đồng bộ cùng contract này qua:
+
+- `frontend/forecast-models.js`
+  - Nguồn cấu hình dùng chung cho thứ tự model, label, palette và `defaultLineWidth`.
+- `frontend/workspace.js`
+  - Đồng bộ selection/signature/cache theo cùng model order.
+- `frontend/app.js`
+  - Render line riêng theo từng model.
+  - Hover vào line phải hiện đúng tên model đang được trỏ tới.

backend/forecasting/__init__.py

@@ -0,0 +1,22 @@
+from backend.forecasting.config import (
+    DEFAULT_FORECAST_MODEL_SELECTION,
+    FORECAST_MODEL_LABELS,
+    FORECAST_MODEL_ORDER,
+    build_query_model_selection,
+    enabled_model_keys,
+    forecast_model_signature,
+    normalize_forecast_model_selection,
+)
+from backend.forecasting.rules import FORECAST_RULE_DOCUMENT, ForecastRuleDocument
+
+__all__ = [
+    "DEFAULT_FORECAST_MODEL_SELECTION",
+    "FORECAST_MODEL_LABELS",
+    "FORECAST_MODEL_ORDER",
+    "FORECAST_RULE_DOCUMENT",
+    "ForecastRuleDocument",
+    "build_query_model_selection",
+    "enabled_model_keys",
+    "forecast_model_signature",
+    "normalize_forecast_model_selection",
+]

backend/forecasting/config.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import Dict, Mapping, Tuple
+
+
+FORECAST_MODEL_ORDER: Tuple[str, ...] = ("kronos", "timesfm", "chronos")
+
+FORECAST_MODEL_LABELS: Dict[str, str] = {
+    "kronos": "Kronos",
+    "timesfm": "TimesFM",
+    "chronos": "Chronos",
+}
+
+DEFAULT_FORECAST_MODEL_SELECTION: Dict[str, bool] = {
+    model_key: True
+    for model_key in FORECAST_MODEL_ORDER
+}
+
+
+def normalize_forecast_model_selection(
+    selection: Mapping[str, bool] | None = None,
+) -> Dict[str, bool]:
+    normalized = {
+        model_key: bool(
+            DEFAULT_FORECAST_MODEL_SELECTION[model_key]
+            if selection is None
+            else selection.get(model_key, DEFAULT_FORECAST_MODEL_SELECTION[model_key])
+        )
+        for model_key in FORECAST_MODEL_ORDER
+    }
+    if not any(normalized.values()):
+        normalized[FORECAST_MODEL_ORDER[0]] = True
+    return normalized
+
+
+def build_query_model_selection(
+    *,
+    use_kronos: bool,
+    use_timesfm: bool,
+    use_chronos: bool,
+) -> Dict[str, bool]:
+    return normalize_forecast_model_selection(
+        {
+            "kronos": use_kronos,
+            "timesfm": use_timesfm,
+            "chronos": use_chronos,
+        }
+    )
+
+
+def forecast_model_signature(model_selection: Mapping[str, bool]) -> str:
+    normalized = normalize_forecast_model_selection(model_selection)
+    return "".join(
+        f"{model_key[0]}{int(normalized[model_key])}"
+        for model_key in FORECAST_MODEL_ORDER
+    )
+
+
+def enabled_model_keys(model_selection: Mapping[str, bool]) -> list[str]:
+    normalized = normalize_forecast_model_selection(model_selection)
+    return [
+        model_key
+        for model_key in FORECAST_MODEL_ORDER
+        if normalized[model_key]
+    ]

backend/forecasting/providers/__init__.py

@@ -0,0 +1,19 @@
+from backend.forecasting.providers.chronos_provider import (
+    CHRONOS_AVAILABLE,
+    CHRONOS_IMPORT_ERROR,
+    ChronosForecaster,
+)
+from backend.forecasting.providers.timesfm_provider import (
+    TIMESFM_AVAILABLE,
+    TIMESFM_IMPORT_ERROR,
+    TimesFMForecaster,
+)
+
+__all__ = [
+    "CHRONOS_AVAILABLE",
+    "CHRONOS_IMPORT_ERROR",
+    "ChronosForecaster",
+    "TIMESFM_AVAILABLE",
+    "TIMESFM_IMPORT_ERROR",
+    "TimesFMForecaster",
+]

backend/forecasting/providers/chronos_provider.py

@@ -0,0 +1,328 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import os
+import random
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+from fastapi import HTTPException
+
+try:
+    import torch
+    TORCH_IMPORT_ERROR: Optional[str] = None
+except Exception as exc:  # pragma: no cover - environment dependent
+    torch = None  # type: ignore[assignment]
+    TORCH_IMPORT_ERROR = str(exc)
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+CHRONOS_VENDOR_SRC = PROJECT_ROOT / "libs" / "chronos-forecasting" / "src"
+
+CHRONOS_AVAILABLE = False
+CHRONOS_IMPORT_ERROR: Optional[str] = None
+ChronosPipeline = None
+
+if TORCH_IMPORT_ERROR:
+    CHRONOS_IMPORT_ERROR = TORCH_IMPORT_ERROR
+else:
+    try:
+        if CHRONOS_VENDOR_SRC.exists() and str(CHRONOS_VENDOR_SRC) not in sys.path:
+            sys.path.insert(0, str(CHRONOS_VENDOR_SRC))
+        from chronos import ChronosPipeline as _ChronosPipeline  # type: ignore[import-not-found]
+
+        ChronosPipeline = _ChronosPipeline
+        CHRONOS_AVAILABLE = True
+    except Exception as exc:  # pragma: no cover - import environment dependent
+        CHRONOS_IMPORT_ERROR = str(exc)
+
+
+class ChronosForecaster:
+    key = "chronos"
+    label = "Chronos"
+
+    MODEL_HF_ID = os.getenv("CHRONOS_MODEL_HF_ID", "amazon/chronos-t5-tiny")
+    MIN_CONTEXT = 32
+    MAX_CONTEXT = 512
+    DEFAULT_SAMPLE_COUNT = 32
+    DEFAULT_TEMPERATURE = 1.0
+    DEFAULT_TOP_K = 50
+    DEFAULT_TOP_P = 1.0
+
+    def __init__(self, logger: logging.Logger | None = None) -> None:
+        self._logger = logger or logging.getLogger("ai-forecast.chronos")
+        self._pipeline: Optional[Any] = None
+        self._loaded = False
+        self._load_lock: Optional[asyncio.Lock] = None
+        self._predict_lock: Optional[asyncio.Lock] = None
+
+    @property
+    def available(self) -> bool:
+        return CHRONOS_AVAILABLE
+
+    @property
+    def import_error(self) -> Optional[str]:
+        return CHRONOS_IMPORT_ERROR
+
+    async def _get_load_lock(self) -> asyncio.Lock:
+        if self._load_lock is None:
+            self._load_lock = asyncio.Lock()
+        return self._load_lock
+
+    async def _get_predict_lock(self) -> asyncio.Lock:
+        if self._predict_lock is None:
+            self._predict_lock = asyncio.Lock()
+        return self._predict_lock
+
+    @property
+    def is_ready(self) -> bool:
+        return self._loaded
+
+    @property
+    def device(self) -> str:
+        if self._pipeline is None:
+            return "not_loaded"
+        try:
+            return str(self._pipeline.model.device)
+        except Exception:
+            return "cpu"
+
+    @staticmethod
+    def _extract_timestamps(df: pd.DataFrame) -> pd.Series:
+        if "timestamps" in df.columns:
+            timestamps = pd.to_datetime(df["timestamps"], utc=True)
+        elif "time" in df.columns:
+            timestamps = pd.to_datetime(df["time"], unit="s", utc=True)
+        else:
+            raise HTTPException(status_code=422, detail="Chronos requires timestamps or time column")
+        if timestamps.isna().any():
+            raise HTTPException(status_code=422, detail="Chronos input timestamps contain NaT")
+        return timestamps.reset_index(drop=True)
+
+    @classmethod
+    def _extract_ohlc4_series(cls, df: pd.DataFrame) -> np.ndarray:
+        required_columns = {"open", "high", "low", "close"}
+        missing_columns = sorted(required_columns - set(df.columns))
+        if missing_columns:
+            raise HTTPException(
+                status_code=422,
+                detail=f"Chronos input is missing OHLC columns: {', '.join(missing_columns)}",
+            )
+
+        ohlc4 = (
+            df[["open", "high", "low", "close"]]
+            .mean(axis=1)
+            .to_numpy(dtype=np.float32, copy=False)
+        )
+        if ohlc4.ndim != 1:
+            raise HTTPException(status_code=422, detail="Chronos input series must be 1-D")
+        if len(ohlc4) < cls.MIN_CONTEXT:
+            raise HTTPException(
+                status_code=422,
+                detail=f"Chronos requires at least {cls.MIN_CONTEXT} OHLC4 points",
+            )
+        if not np.isfinite(ohlc4).all():
+            raise HTTPException(status_code=422, detail="Chronos input contains non-finite OHLC4 values")
+        return ohlc4
+
+    @staticmethod
+    def _stable_seed(
+        symbol: str,
+        interval: str,
+        horizon: int,
+        context_length: int,
+        last_timestamp: pd.Timestamp,
+    ) -> int:
+        payload = "|".join(
+            [
+                symbol,
+                interval,
+                str(horizon),
+                str(context_length),
+                str(int(last_timestamp.timestamp())),
+            ]
+        )
+        return int(hashlib.sha256(payload.encode("utf-8")).hexdigest()[:8], 16)
+
+    @staticmethod
+    def _validate_output(
+        quantiles: np.ndarray,
+        mean_forecast: np.ndarray,
+        horizon: int,
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, Dict[str, Any]]:
+        quantile_array = np.asarray(quantiles, dtype=float)
+        mean_array = np.asarray(mean_forecast, dtype=float)
+
+        if quantile_array.ndim != 3 or quantile_array.shape[0] != 1 or quantile_array.shape[1] < horizon or quantile_array.shape[2] < 3:
+            raise HTTPException(
+                status_code=500,
+                detail=f"Chronos quantile forecast has invalid shape: {list(quantile_array.shape)}",
+            )
+        if mean_array.ndim != 2 or mean_array.shape[0] != 1 or mean_array.shape[1] < horizon:
+            raise HTTPException(
+                status_code=500,
+                detail=f"Chronos mean forecast has invalid shape: {list(mean_array.shape)}",
+            )
+
+        p10 = quantile_array[0, :horizon, 0].astype(float)
+        p50 = quantile_array[0, :horizon, 1].astype(float)
+        p90 = quantile_array[0, :horizon, 2].astype(float)
+        mean_values = mean_array[0, :horizon].astype(float)
+
+        if not (np.isfinite(p10).all() and np.isfinite(p50).all() and np.isfinite(p90).all()):
+            raise HTTPException(status_code=500, detail="Chronos output contains non-finite values")
+
+        quantiles_monotonic = bool(
+            np.all(p10 <= (p50 + 1e-6))
+            and np.all(p50 <= (p90 + 1e-6))
+        )
+        if not quantiles_monotonic:
+            raise HTTPException(status_code=500, detail="Chronos returned non-monotonic quantiles")
+
+        return p10, p50, p90, {
+            "quantile_shape": [int(dim) for dim in quantile_array.shape],
+            "mean_shape": [int(dim) for dim in mean_array.shape],
+            "quantiles_monotonic": quantiles_monotonic,
+            "median_close_to_mean": bool(np.allclose(p50, mean_values, atol=1e-3, rtol=1e-3)),
+        }
+
+    async def _lazy_load(self) -> None:
+        if self._loaded:
+            return
+        load_lock = await self._get_load_lock()
+        async with load_lock:
+            if self._loaded:
+                return
+            if not CHRONOS_AVAILABLE or ChronosPipeline is None:
+                raise HTTPException(
+                    status_code=503,
+                    detail=(
+                        "Chronos is unavailable. Ensure libs/chronos-forecasting is present "
+                        "and its dependencies are installed."
+                    ),
+                )
+            try:
+                self._logger.info("[Chronos] Loading %s ...", self.MODEL_HF_ID)
+                device_map = "cuda" if torch is not None and torch.cuda.is_available() else "cpu"
+                model_dtype = torch.bfloat16 if torch is not None and torch.cuda.is_available() else torch.float32
+                pipeline = await asyncio.to_thread(
+                    ChronosPipeline.from_pretrained,
+                    self.MODEL_HF_ID,
+                    device_map=device_map,
+                    dtype=model_dtype,
+                )
+                self._pipeline = pipeline
+                self._loaded = True
+                self._logger.info("[Chronos] Ready on %s", self.device)
+            except Exception as exc:
+                self._logger.error("[Chronos] Init failed: %s", exc, exc_info=True)
+                raise HTTPException(status_code=500, detail=f"Chronos init failed: {exc}")
+
+    async def forecast(
+        self,
+        df: pd.DataFrame,
+        horizon: int,
+        interval: str,
+        step_seconds: int,
+        symbol: str = "",
+    ) -> Dict[str, Any]:
+        del step_seconds
+        await self._lazy_load()
+        if self._pipeline is None:
+            raise HTTPException(status_code=500, detail="Chronos pipeline is not initialized")
+
+        timestamps = self._extract_timestamps(df)
+        ohlc4_series = self._extract_ohlc4_series(df)
+        context_length = min(len(ohlc4_series), self.MAX_CONTEXT, int(self._pipeline.model_context_length))
+        context = ohlc4_series[-context_length:]
+        seed = self._stable_seed(
+            symbol=symbol or "UNKNOWN",
+            interval=interval,
+            horizon=horizon,
+            context_length=context_length,
+            last_timestamp=pd.Timestamp(timestamps.iloc[-1]).tz_convert("UTC"),
+        )
+
+        predict_lock = await self._get_predict_lock()
+        async with predict_lock:
+            try:
+                random.seed(seed)
+                np.random.seed(seed % (2**32 - 1))
+                if torch is not None:
+                    torch.manual_seed(seed)
+                    if torch.cuda.is_available():
+                        torch.cuda.manual_seed_all(seed)
+
+                started_at = time.time()
+                context_tensor = torch.tensor(context, dtype=torch.float32)
+                quantiles, mean_forecast = await asyncio.to_thread(
+                    self._pipeline.predict_quantiles,
+                    context_tensor,
+                    prediction_length=horizon,
+                    quantile_levels=[0.1, 0.5, 0.9],
+                    num_samples=self.DEFAULT_SAMPLE_COUNT,
+                    temperature=self.DEFAULT_TEMPERATURE,
+                    top_k=self.DEFAULT_TOP_K,
+                    top_p=self.DEFAULT_TOP_P,
+                    limit_prediction_length=False,
+                )
+                elapsed = time.time() - started_at
+                self._logger.info(
+                    "[Chronos] %.2fs | horizon=%d ctx=%d samples=%d device=%s",
+                    elapsed,
+                    horizon,
+                    context_length,
+                    self.DEFAULT_SAMPLE_COUNT,
+                    self.device,
+                )
+            except Exception as exc:
+                self._logger.error("[Chronos] Forecast failed: %s", exc, exc_info=True)
+                raise HTTPException(status_code=500, detail=f"Chronos prediction failed: {exc}")
+
+        p10, p50, p90, output_validation = self._validate_output(
+            quantiles=quantiles.numpy() if hasattr(quantiles, "numpy") else np.asarray(quantiles),
+            mean_forecast=mean_forecast.numpy() if hasattr(mean_forecast, "numpy") else np.asarray(mean_forecast),
+            horizon=horizon,
+        )
+
+        return {
+            "p10": p10,
+            "p50": p50,
+            "p90": p90,
+            "model_name": self.MODEL_HF_ID,
+            "context_length": context_length,
+            "output_horizon": horizon,
+            "sample_count": self.DEFAULT_SAMPLE_COUNT,
+            "seed": seed,
+            "input_semantics": {
+                "feature_channels": ["ohlc4"],
+                "active_forecast_channels": ["ohlc4"],
+                "ignored_channels": ["volume", "amount"],
+                "price_mode": "ohlc4_single_channel",
+                "base_signal": "ohlc4",
+                "volume_mode": "omitted",
+                "amount_mode": "omitted",
+                "adapter_mode": "chronos_univariate",
+            },
+            "input_validation": {
+                "series_field": "ohlc4",
+                "dtype": "float32",
+                "context_length": context_length,
+                "finite": True,
+            },
+            "output_semantics": {
+                "forecast_channel": "ohlc4",
+                "forecast_mode": "single_future_ohlc4_line",
+                "quantile_fields": ["p10", "p50", "p90"],
+                "quantile_source": "chronos_sampling",
+                "candle_projection": "omitted",
+                "reference_baseline": "last_ohlc4",
+            },
+            "output_validation": output_validation,
+        }

backend/forecasting/providers/timesfm_provider.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import asyncio
+import importlib
+import logging
+import os
+import time
+from typing import Any, Dict, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+from fastapi import HTTPException
+
+try:
+    import torch
+    TORCH_IMPORT_ERROR: Optional[str] = None
+except Exception as exc:  # pragma: no cover - environment dependent
+    torch = None  # type: ignore[assignment]
+    TORCH_IMPORT_ERROR = str(exc)
+
+
+TIMESFM_AVAILABLE = False
+TIMESFM_IMPORT_ERROR: Optional[str] = None
+timesfm = None
+
+if TORCH_IMPORT_ERROR:
+    TIMESFM_IMPORT_ERROR = TORCH_IMPORT_ERROR
+else:
+    try:
+        import timesfm as _timesfm  # type: ignore[import-not-found]
+
+        timesfm = _timesfm
+        TIMESFM_AVAILABLE = True
+    except Exception as exc:  # pragma: no cover - import environment dependent
+        TIMESFM_IMPORT_ERROR = str(exc)
+
+
+_TIMESFM_RUNTIME_PATCHED = False
+
+
+def _patch_timesfm_runtime_compatibility(logger: logging.Logger) -> None:
+    global _TIMESFM_RUNTIME_PATCHED
+    if _TIMESFM_RUNTIME_PATCHED or timesfm is None:
+        return
+
+    try:
+        internal_module = importlib.import_module("timesfm.timesfm_2p5.timesfm_2p5_torch")
+        model_module_cls = getattr(internal_module, "TimesFM_2p5_200M_torch_module", None)
+        if model_module_cls is None or getattr(model_module_cls, "_aiforecast_meta_patch", False):
+            _TIMESFM_RUNTIME_PATCHED = True
+            return
+
+        def _patched_load_checkpoint(self: Any, path: str, **kwargs: Any) -> None:
+            tensors = internal_module.load_file(path)
+            has_meta_parameters = any(
+                getattr(parameter, "is_meta", False)
+                for parameter in self.parameters()
+            )
+            try:
+                if has_meta_parameters:
+                    self.load_state_dict(tensors, strict=True, assign=True)
+                else:
+                    self.load_state_dict(tensors, strict=True)
+            except TypeError:
+                if has_meta_parameters:
+                    self.to_empty(device=self.device)
+                self.load_state_dict(tensors, strict=True)
+
+            self.to(self.device)
+            torch_compile = kwargs.get("torch_compile", True)
+            if torch_compile:
+                internal_module.logging.info("Compiling model...")
+                self = torch.compile(self)
+            self.eval()
+
+        model_module_cls.load_checkpoint = _patched_load_checkpoint
+        model_module_cls._aiforecast_meta_patch = True
+        _TIMESFM_RUNTIME_PATCHED = True
+    except Exception as exc:  # pragma: no cover - defensive guard
+        logger.warning("[TimesFM] Runtime compatibility patch skipped: %s", exc)
+
+
+class TimesFMForecaster:
+    key = "timesfm"
+    label = "TimesFM"
+
+    MODEL_HF_ID = os.getenv("TIMESFM_MODEL_HF_ID", "google/timesfm-2.5-200m-pytorch")
+    MAX_CONTEXT = 8_192
+    MAX_HORIZON = 300
+    _Q10 = 1
+    _Q50 = 5
+    _Q90 = 9
+
+    def __init__(self, logger: logging.Logger | None = None) -> None:
+        self._logger = logger or logging.getLogger("ai-forecast.timesfm")
+        self._model: Optional[Any] = None
+        self._loaded = False
+        self._lock: Optional[asyncio.Lock] = None
+        self._predict_lock: Optional[asyncio.Lock] = None
+        self._compiled_horizon: Optional[int] = None
+
+    @property
+    def available(self) -> bool:
+        return TIMESFM_AVAILABLE
+
+    @property
+    def import_error(self) -> Optional[str]:
+        return TIMESFM_IMPORT_ERROR
+
+    @staticmethod
+    def _prepare_feature_frame(df: pd.DataFrame) -> pd.DataFrame:
+        ohlc4 = (
+            df[["open", "high", "low", "close"]]
+            .mean(axis=1)
+            .astype(np.float32)
+        )
+        return pd.DataFrame({"ohlc4": ohlc4})
+
+    @classmethod
+    def _extract_ohlc4_series(cls, df: pd.DataFrame) -> np.ndarray:
+        feature_frame = cls._prepare_feature_frame(df)
+        ohlc4_series = feature_frame["ohlc4"].to_numpy(dtype=np.float32, copy=False)
+        cls._validate_input_series(ohlc4_series)
+        return ohlc4_series
+
+    @staticmethod
+    def _validate_input_series(series: np.ndarray) -> None:
+        if series.ndim != 1:
+            raise HTTPException(status_code=422, detail="TimesFM input series must be 1-D")
+        if len(series) < 32:
+            raise HTTPException(status_code=422, detail="TimesFM requires at least 32 OHLC4 points")
+        if not np.isfinite(series).all():
+            raise HTTPException(status_code=422, detail="TimesFM input contains non-finite OHLC4 values")
+
+    @classmethod
+    def _validate_output_tensors(
+        cls,
+        point_forecast: np.ndarray,
+        quantile_forecast: np.ndarray,
+        horizon: int,
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, Dict[str, Any]]:
+        point_arr = np.asarray(point_forecast)
+        quant_arr = np.asarray(quantile_forecast)
+
+        if point_arr.ndim != 2 or point_arr.shape[0] != 1 or point_arr.shape[1] < horizon:
+            raise HTTPException(
+                status_code=500,
+                detail=f"TimesFM point forecast has invalid shape: {list(point_arr.shape)}",
+            )
+        if (
+            quant_arr.ndim != 3
+            or quant_arr.shape[0] != 1
+            or quant_arr.shape[1] < horizon
+            or quant_arr.shape[2] <= cls._Q90
+        ):
+            raise HTTPException(
+                status_code=500,
+                detail=f"TimesFM quantile forecast has invalid shape: {list(quant_arr.shape)}",
+            )
+
+        p10 = quant_arr[0, :horizon, cls._Q10].astype(float)
+        p50 = point_arr[0, :horizon].astype(float)
+        p50_from_quantiles = quant_arr[0, :horizon, cls._Q50].astype(float)
+        p90 = quant_arr[0, :horizon, cls._Q90].astype(float)
+
+        if not (np.isfinite(p10).all() and np.isfinite(p50).all() and np.isfinite(p90).all()):
+            raise HTTPException(status_code=500, detail="TimesFM output contains non-finite values")
+
+        quantiles_monotonic = bool(
+            np.all(p10 <= (p50 + 1e-6))
+            and np.all(p50 <= (p90 + 1e-6))
+        )
+        if not quantiles_monotonic:
+            raise HTTPException(status_code=500, detail="TimesFM returned non-monotonic quantiles")
+
+        median_matches_point_forecast = bool(
+            np.allclose(p50, p50_from_quantiles, atol=1e-4, rtol=1e-4)
+        )
+        if not median_matches_point_forecast:
+            logging.getLogger("ai-forecast").warning(
+                "[TimesFM] point_forecast differs from q50 quantile output"
+            )
+
+        output_validation = {
+            "point_shape": [int(dim) for dim in point_arr.shape],
+            "quantile_shape": [int(dim) for dim in quant_arr.shape],
+            "median_matches_point_forecast": median_matches_point_forecast,
+            "quantiles_monotonic": quantiles_monotonic,
+        }
+        return p10, p50, p90, output_validation
+
+    async def _get_lock(self) -> asyncio.Lock:
+        if self._lock is None:
+            self._lock = asyncio.Lock()
+        return self._lock
+
+    async def _get_predict_lock(self) -> asyncio.Lock:
+        if self._predict_lock is None:
+            self._predict_lock = asyncio.Lock()
+        return self._predict_lock
+
+    @property
+    def is_ready(self) -> bool:
+        return self._loaded
+
+    @property
+    def device(self) -> str:
+        if self._model is None:
+            return "not_loaded"
+        try:
+            return str(self._model.model.device)
+        except Exception:
+            return "cpu"
+
+    def _compile(self, horizon: int) -> None:
+        output_patch = 128
+        max_horizon = int(np.ceil(horizon / output_patch) * output_patch)
+        max_horizon = max(max_horizon, output_patch)
+        max_horizon = min(max_horizon, self.MAX_HORIZON)
+        context_len = self.MAX_CONTEXT
+        assert timesfm is not None
+        self._model.compile(
+            timesfm.ForecastConfig(
+                max_context=context_len,
+                max_horizon=max_horizon,
+                normalize_inputs=True,
+                use_continuous_quantile_head=True,
+                force_flip_invariance=True,
+                infer_is_positive=True,
+                fix_quantile_crossing=True,
+            )
+        )
+        compiled_config = getattr(self._model, "forecast_config", None)
+        actual_ctx = int(getattr(compiled_config, "max_context", context_len))
+        actual_max_horizon = int(getattr(compiled_config, "max_horizon", max_horizon))
+        self._compiled_horizon = actual_max_horizon
+        self._logger.info("[TimesFM] Compiled: ctx=%d max_horizon=%d", actual_ctx, actual_max_horizon)
+
+    async def _lazy_load(self) -> None:
+        if self._loaded:
+            return
+        lock = await self._get_lock()
+        async with lock:
+            if self._loaded:
+                return
+            if not TIMESFM_AVAILABLE or timesfm is None:
+                raise HTTPException(
+                    status_code=503,
+                    detail="TimesFM not installed. Run: pip install timesfm[torch]",
+                )
+            try:
+                _patch_timesfm_runtime_compatibility(self._logger)
+                self._logger.info("[TimesFM] Loading %s ...", self.MODEL_HF_ID)
+                model = await asyncio.to_thread(
+                    timesfm.TimesFM_2p5_200M_torch.from_pretrained,
+                    self.MODEL_HF_ID,
+                    torch_compile=False,
+                )
+                self._model = model
+                self._compile(self.MAX_HORIZON)
+                self._loaded = True
+                self._logger.info("[TimesFM] Ready on %s", self.device)
+            except Exception as exc:
+                self._logger.error("[TimesFM] Init failed: %s", exc, exc_info=True)
+                raise HTTPException(status_code=500, detail=f"TimesFM init failed: {exc}")
+
+    async def forecast(
+        self,
+        df: pd.DataFrame,
+        horizon: int,
+        interval: str = "",
+        step_seconds: int = 0,
+        symbol: str = "",
+    ) -> Dict[str, Any]:
+        del interval, step_seconds, symbol
+        await self._lazy_load()
+        if self._model is None:
+            raise HTTPException(status_code=500, detail="TimesFM model is not initialized")
+
+        try:
+            ohlc4_series = self._extract_ohlc4_series(df)
+            context_len = min(len(ohlc4_series), self.MAX_CONTEXT)
+            ohlc4_context = ohlc4_series[-context_len:]
+
+            if self._compiled_horizon is None or horizon > self._compiled_horizon:
+                self._compile(horizon)
+
+            started_at = time.time()
+            predict_lock = await self._get_predict_lock()
+            async with predict_lock:
+                point_forecast, quantile_forecast = await asyncio.to_thread(
+                    self._model.forecast,
+                    horizon,
+                    [ohlc4_context],
+                )
+            elapsed = time.time() - started_at
+            self._logger.info(
+                "[TimesFM] %.2fs | horizon=%d ctx=%d device=%s",
+                elapsed,
+                horizon,
+                context_len,
+                self.device,
+            )
+
+            if torch is not None and torch.cuda.is_available():
+                torch.cuda.empty_cache()
+
+            p10, p50, p90, output_validation = self._validate_output_tensors(
+                point_forecast=point_forecast,
+                quantile_forecast=quantile_forecast,
+                horizon=horizon,
+            )
+
+            return {
+                "p10": p10,
+                "p50": p50,
+                "p90": p90,
+                "model_name": self.MODEL_HF_ID,
+                "context_length": context_len,
+                "output_horizon": horizon,
+                "input_semantics": {
+                    "feature_channels": ["ohlc4"],
+                    "active_forecast_channels": ["ohlc4"],
+                    "ignored_channels": ["volume"],
+                    "price_mode": "ohlc4_single_channel",
+                    "base_signal": "ohlc4",
+                    "volume_mode": "omitted",
+                    "amount_mode": "omitted",
+                    "adapter_mode": "timesfm_native",
+                    "normalization": "timesfm_internal_revin",
+                },
+                "input_validation": {
+                    "series_field": "ohlc4",
+                    "dtype": str(ohlc4_context.dtype),
+                    "is_1d": True,
+                    "finite": True,
+                },
+                "output_semantics": {
+                    "forecast_channel": "ohlc4",
+                    "forecast_mode": "single_future_ohlc4_line",
+                    "quantile_fields": ["p10", "p50", "p90"],
+                    "candle_projection": "omitted",
+                    "reference_baseline": "last_ohlc4",
+                },
+                "output_validation": output_validation,
+            }
+        except HTTPException:
+            raise
+        except Exception as exc:
+            self._logger.error("[TimesFM] Forecast failed: %s", exc, exc_info=True)
+            raise HTTPException(status_code=500, detail=f"TimesFM prediction failed: {exc}")

backend/forecasting/rules.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict
+
+
+RULES_PATH = Path(__file__).with_name("AI_MODEL_RULES.md")
+
+
+@dataclass(frozen=True)
+class ForecastRuleDocument:
+    path: str
+    version: str
+    content: str
+    default_horizon: int
+    recommended_context_length: int
+    default_line_width: int
+
+    def to_metadata(self) -> Dict[str, Any]:
+        return {
+            "path": self.path,
+            "version": self.version,
+            "default_horizon": self.default_horizon,
+            "recommended_context_length": self.recommended_context_length,
+            "default_line_width": self.default_line_width,
+        }
+
+
+def load_forecast_rule_document(path: Path | None = None) -> ForecastRuleDocument:
+    rules_path = path or RULES_PATH
+    content = rules_path.read_text(encoding="utf-8").strip()
+    version = hashlib.sha256(content.encode("utf-8")).hexdigest()[:12]
+    return ForecastRuleDocument(
+        path=str(rules_path),
+        version=version,
+        content=content,
+        default_horizon=10,
+        recommended_context_length=512,
+        default_line_width=1,
+    )
+
+
+FORECAST_RULE_DOCUMENT = load_forecast_rule_document()

backend/frontend_assets.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Iterable
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse, HTMLResponse
+from fastapi.staticfiles import StaticFiles
+
+
+@dataclass(frozen=True)
+class FrontendAssets:
+    root: Path
+    index_html: Path
+    app_js: Path
+    forecast_models_js: Path
+    workspace_js: Path
+    workspace_css: Path
+    background_image: Path
+    favicon_svg: Path
+
+    @property
+    def exists(self) -> bool:
+        return self.root.exists()
+
+    def versioned_assets(self) -> tuple[Path, ...]:
+        return (
+            self.index_html,
+            self.app_js,
+            self.forecast_models_js,
+            self.workspace_js,
+            self.workspace_css,
+        )
+
+
+def resolve_frontend_assets(project_root: str | Path) -> FrontendAssets:
+    root = Path(project_root) / "frontend"
+    return FrontendAssets(
+        root=root,
+        index_html=root / "index.html",
+        app_js=root / "app.js",
+        forecast_models_js=root / "forecast-models.js",
+        workspace_js=root / "workspace.js",
+        workspace_css=root / "workspace.css",
+        background_image=root / "AIBG.png",
+        favicon_svg=root / "favicon.svg",
+    )
+
+
+def frontend_asset_headers() -> Dict[str, str]:
+    return {
+        "Cache-Control": "no-store, no-cache, must-revalidate, max-age=0",
+        "Pragma": "no-cache",
+        "Expires": "0",
+    }
+
+
+def build_frontend_asset_version(
+    *,
+    assets: FrontendAssets,
+    app_version: str,
+    cache_version: str,
+) -> str:
+    version_parts: list[str] = [app_version, cache_version]
+    for asset_path in assets.versioned_assets():
+        if asset_path.exists():
+            version_parts.append(str(int(asset_path.stat().st_mtime)))
+    return "-".join(version_parts)
+
+
+def _serve_asset_file(
+    asset_path: Path,
+    *,
+    media_type: str,
+    not_found_detail: str,
+) -> FileResponse:
+    if not asset_path.exists():
+        raise HTTPException(status_code=404, detail=not_found_detail)
+    return FileResponse(
+        str(asset_path),
+        media_type=media_type,
+        headers=frontend_asset_headers(),
+    )
+
+
+def _register_file_routes(
+    app: FastAPI,
+    *,
+    assets: FrontendAssets,
+) -> None:
+    def add_file_route(
+        route_path: str,
+        asset_path: Path,
+        *,
+        media_type: str,
+        not_found_detail: str,
+        route_name: str,
+    ) -> None:
+        async def serve_file() -> FileResponse:
+            return _serve_asset_file(
+                asset_path,
+                media_type=media_type,
+                not_found_detail=not_found_detail,
+            )
+
+        serve_file.__name__ = route_name
+        app.add_api_route(route_path, serve_file, include_in_schema=False, methods=["GET"])
+
+    file_specs: Iterable[tuple[str, Path, str, str, str]] = (
+        (
+            "/workspace.js",
+            assets.workspace_js,
+            "application/javascript",
+            "Workspace JS asset not found",
+            "serve_workspace_js",
+        ),
+        (
+            "/app.js",
+            assets.app_js,
+            "application/javascript",
+            "App JS asset not found",
+            "serve_app_js",
+        ),
+        (
+            "/forecast-models.js",
+            assets.forecast_models_js,
+            "application/javascript",
+            "Forecast model registry asset not found",
+            "serve_forecast_models_js",
+        ),
+        (
+            "/workspace.css",
+            assets.workspace_css,
+            "text/css",
+            "Workspace CSS asset not found",
+            "serve_workspace_css",
+        ),
+        (
+            "/AIBG.png",
+            assets.background_image,
+            "image/png",
+            "AIBG asset not found",
+            "serve_aibg",
+        ),
+        (
+            "/favicon.svg",
+            assets.favicon_svg,
+            "image/svg+xml",
+            "Favicon not found",
+            "serve_favicon_svg",
+        ),
+        (
+            "/favicon.ico",
+            assets.favicon_svg,
+            "image/svg+xml",
+            "Favicon not found",
+            "serve_favicon_ico",
+        ),
+    )
+    for route_path, asset_path, media_type, not_found_detail, route_name in file_specs:
+        add_file_route(
+            route_path,
+            asset_path,
+            media_type=media_type,
+            not_found_detail=not_found_detail,
+            route_name=route_name,
+        )
+
+
+def register_frontend_assets(
+    app: FastAPI,
+    *,
+    project_root: str | Path,
+    app_version: str,
+    cache_version: str,
+    logger: logging.Logger,
+) -> None:
+    assets = resolve_frontend_assets(project_root)
+    if not assets.exists:
+        logger.warning("Frontend path not found: %s", assets.root)
+        return
+
+    async def serve_frontend_index() -> HTMLResponse:
+        if not assets.index_html.exists():
+            raise HTTPException(status_code=404, detail="Frontend index not found")
+
+        html = assets.index_html.read_text(encoding="utf-8")
+        html = html.replace(
+            "__FRONTEND_ASSET_VERSION__",
+            build_frontend_asset_version(
+                assets=assets,
+                app_version=app_version,
+                cache_version=cache_version,
+            ),
+        )
+        return HTMLResponse(content=html, headers=frontend_asset_headers())
+
+    app.add_api_route("/", serve_frontend_index, include_in_schema=False, methods=["GET"])
+    app.add_api_route("/index.html", serve_frontend_index, include_in_schema=False, methods=["GET"])
+    _register_file_routes(app, assets=assets)
+    app.mount("/", StaticFiles(directory=str(assets.root), html=True), name="frontend")
+    logger.info("Mounted frontend: %s", assets.root)

backend/kronos_adapter.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import os
+import random
+import time
+from typing import Any, Dict, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+from fastapi import HTTPException
+
+try:
+    import torch
+    TORCH_IMPORT_ERROR: Optional[str] = None
+except Exception as exc:  # pragma: no cover - environment dependent
+    torch = None  # type: ignore[assignment]
+    TORCH_IMPORT_ERROR = str(exc)
+
+KRONOS_AVAILABLE = False
+KRONOS_IMPORT_ERROR: Optional[str] = None
+Kronos = None
+KronosTokenizer = None
+KronosPredictor = None
+
+if TORCH_IMPORT_ERROR:
+    KRONOS_IMPORT_ERROR = TORCH_IMPORT_ERROR
+else:
+    try:
+        from backend.kronos_core.model import (  # type: ignore[assignment]
+            Kronos,
+            KronosPredictor,
+            KronosTokenizer,
+        )
+
+        KRONOS_AVAILABLE = True
+    except Exception as exc:  # pragma: no cover - import environment dependent
+        KRONOS_IMPORT_ERROR = str(exc)
+
+
+class KronosForecaster:
+    """Async OHLC4-only wrapper around the vendored Kronos model."""
+
+    MODEL_HF_ID = os.getenv("KRONOS_MODEL_HF_ID", "NeoQuasar/Kronos-base")
+    TOKENIZER_HF_ID = "NeoQuasar/Kronos-Tokenizer-base"
+    MAX_CONTEXT = 512
+    MIN_CONTEXT = 32
+    DEFAULT_SAMPLE_COUNT = 5
+    DEFAULT_TEMPERATURE = 0.9
+    DEFAULT_TOP_P = 0.9
+    DEFAULT_TOP_K = 0
+
+    def __init__(self, logger: logging.Logger) -> None:
+        self._logger = logger
+        self._model: Optional[Any] = None
+        self._tokenizer: Optional[Any] = None
+        self._predictor: Optional[Any] = None
+        self._loaded = False
+        self._load_lock: Optional[asyncio.Lock] = None
+        self._predict_lock: Optional[asyncio.Lock] = None
+
+    async def _get_load_lock(self) -> asyncio.Lock:
+        if self._load_lock is None:
+            self._load_lock = asyncio.Lock()
+        return self._load_lock
+
+    async def _get_predict_lock(self) -> asyncio.Lock:
+        if self._predict_lock is None:
+            self._predict_lock = asyncio.Lock()
+        return self._predict_lock
+
+    @property
+    def is_ready(self) -> bool:
+        return self._loaded
+
+    @property
+    def device(self) -> str:
+        if self._predictor is None:
+            return "not_loaded"
+        try:
+            return str(self._predictor.device)
+        except Exception:  # pragma: no cover - defensive
+            return "cpu"
+
+    @staticmethod
+    def _extract_timestamps(df: pd.DataFrame) -> pd.Series:
+        if "timestamps" in df.columns:
+            ts = pd.to_datetime(df["timestamps"], utc=True)
+        elif "time" in df.columns:
+            ts = pd.to_datetime(df["time"], unit="s", utc=True)
+        else:
+            raise HTTPException(status_code=422, detail="Kronos requires timestamps or time column")
+        if ts.isna().any():
+            raise HTTPException(status_code=422, detail="Kronos input timestamps contain NaT")
+        return ts.reset_index(drop=True)
+
+    @classmethod
+    def _build_ohlc4_proxy_frame(cls, df: pd.DataFrame) -> Tuple[pd.DataFrame, np.ndarray]:
+        required_cols = {"open", "high", "low", "close"}
+        missing_cols = sorted(required_cols - set(df.columns))
+        if missing_cols:
+            raise HTTPException(
+                status_code=422,
+                detail=f"Kronos input is missing OHLC columns: {', '.join(missing_cols)}",
+            )
+
+        ohlc4 = (
+            df[["open", "high", "low", "close"]]
+            .mean(axis=1)
+            .to_numpy(dtype=np.float32, copy=False)
+        )
+        if ohlc4.ndim != 1 or len(ohlc4) < cls.MIN_CONTEXT:
+            raise HTTPException(
+                status_code=422,
+                detail=f"Kronos requires at least {cls.MIN_CONTEXT} OHLC4 points",
+            )
+        if not np.isfinite(ohlc4).all():
+            raise HTTPException(status_code=422, detail="Kronos input contains non-finite OHLC4 values")
+
+        proxy = pd.DataFrame(
+            {
+                "open": ohlc4,
+                "high": ohlc4,
+                "low": ohlc4,
+                "close": ohlc4,
+                "volume": np.zeros(len(ohlc4), dtype=np.float32),
+                "amount": np.zeros(len(ohlc4), dtype=np.float32),
+            }
+        )
+        return proxy, ohlc4.astype(float)
+
+    @staticmethod
+    def _build_future_timestamps(
+        history_timestamps: pd.Series,
+        horizon: int,
+        step_seconds: int,
+    ) -> pd.Series:
+        last_ts = pd.Timestamp(history_timestamps.iloc[-1])
+        last_ts = last_ts.tz_convert("UTC") if last_ts.tzinfo is not None else last_ts.tz_localize("UTC")
+        delta = pd.to_timedelta(step_seconds, unit="s")
+        future_index = [last_ts + (delta * (step + 1)) for step in range(horizon)]
+        return pd.Series(pd.DatetimeIndex(future_index), copy=False)
+
+    @staticmethod
+    def _stable_seed(
+        symbol: str,
+        interval: str,
+        horizon: int,
+        context_length: int,
+        last_timestamp: pd.Timestamp,
+    ) -> int:
+        payload = "|".join(
+            [
+                symbol,
+                interval,
+                str(horizon),
+                str(context_length),
+                str(int(last_timestamp.timestamp())),
+            ]
+        )
+        return int(hashlib.sha256(payload.encode("utf-8")).hexdigest()[:8], 16)
+
+    @staticmethod
+    def _build_output_validation(
+        p10: np.ndarray,
+        p50: np.ndarray,
+        p90: np.ndarray,
+        samples: np.ndarray,
+    ) -> Dict[str, Any]:
+        quantiles_monotonic = bool(
+            np.all(p10 <= (p50 + 1e-6))
+            and np.all(p50 <= (p90 + 1e-6))
+        )
+        if not quantiles_monotonic:
+            raise HTTPException(status_code=500, detail="Kronos returned non-monotonic sample quantiles")
+        if not (np.isfinite(p10).all() and np.isfinite(p50).all() and np.isfinite(p90).all()):
+            raise HTTPException(status_code=500, detail="Kronos output contains non-finite values")
+
+        return {
+            "sample_shape": [int(dim) for dim in samples.shape],
+            "quantile_shape": [1, int(p50.shape[0]), 3],
+            "quantiles_monotonic": quantiles_monotonic,
+            "quantile_source": "sample_paths",
+        }
+
+    async def _lazy_load(self) -> None:
+        if self._loaded:
+            return
+        load_lock = await self._get_load_lock()
+        async with load_lock:
+            if self._loaded:
+                return
+            if not KRONOS_AVAILABLE or Kronos is None or KronosTokenizer is None or KronosPredictor is None:
+                raise HTTPException(
+                    status_code=503,
+                    detail=(
+                        "Kronos is unavailable. Ensure backend/kronos_core is present and "
+                        "dependencies from its requirements are installed."
+                    ),
+                )
+            try:
+                self._logger.info("[Kronos] Loading %s ...", self.MODEL_HF_ID)
+                tokenizer = await asyncio.to_thread(
+                    KronosTokenizer.from_pretrained,
+                    self.TOKENIZER_HF_ID,
+                )
+                model = await asyncio.to_thread(
+                    Kronos.from_pretrained,
+                    self.MODEL_HF_ID,
+                )
+                predictor = KronosPredictor(
+                    model,
+                    tokenizer,
+                    device="cuda:0" if torch is not None and torch.cuda.is_available() else "cpu",
+                    max_context=self.MAX_CONTEXT,
+                )
+                self._tokenizer = tokenizer
+                self._model = model
+                self._predictor = predictor
+                self._loaded = True
+                self._logger.info("[Kronos] Ready on %s", self.device)
+            except Exception as exc:
+                self._logger.error("[Kronos] Init failed: %s", exc, exc_info=True)
+                raise HTTPException(status_code=500, detail=f"Kronos init failed: {exc}")
+
+    async def forecast(
+        self,
+        df: pd.DataFrame,
+        horizon: int,
+        interval: str,
+        step_seconds: int,
+        symbol: str = "",
+    ) -> Dict[str, Any]:
+        await self._lazy_load()
+        if self._predictor is None:
+            raise HTTPException(status_code=500, detail="Kronos predictor is not initialized")
+
+        history_timestamps = self._extract_timestamps(df)
+        proxy_df, _ = self._build_ohlc4_proxy_frame(df)
+        context_length = min(len(proxy_df), self.MAX_CONTEXT)
+        proxy_context = proxy_df.tail(context_length).reset_index(drop=True)
+        x_timestamp = history_timestamps.tail(context_length).reset_index(drop=True)
+        y_timestamp = self._build_future_timestamps(
+            history_timestamps=x_timestamp,
+            horizon=horizon,
+            step_seconds=step_seconds,
+        )
+
+        sample_count = self.DEFAULT_SAMPLE_COUNT
+        seed = self._stable_seed(
+            symbol=symbol or "UNKNOWN",
+            interval=interval,
+            horizon=horizon,
+            context_length=context_length,
+            last_timestamp=(
+                pd.Timestamp(x_timestamp.iloc[-1]).tz_convert("UTC")
+                if pd.Timestamp(x_timestamp.iloc[-1]).tzinfo is not None
+                else pd.Timestamp(x_timestamp.iloc[-1]).tz_localize("UTC")
+            ),
+        )
+
+        predict_lock = await self._get_predict_lock()
+        async with predict_lock:
+            try:
+                random.seed(seed)
+                np.random.seed(seed % (2**32 - 1))
+                if torch is not None:
+                    torch.manual_seed(seed)
+                    if torch.cuda.is_available():
+                        torch.cuda.manual_seed_all(seed)
+
+                t0 = time.time()
+                sample_tensor = await asyncio.to_thread(
+                    self._predictor.predict_samples,
+                    proxy_context,
+                    x_timestamp,
+                    y_timestamp,
+                    horizon,
+                    self.DEFAULT_TEMPERATURE,
+                    self.DEFAULT_TOP_K,
+                    self.DEFAULT_TOP_P,
+                    sample_count,
+                    False,
+                )
+                elapsed = time.time() - t0
+                self._logger.info(
+                    "[Kronos] %.2fs | horizon=%d ctx=%d samples=%d device=%s",
+                    elapsed,
+                    horizon,
+                    context_length,
+                    sample_count,
+                    self.device,
+                )
+            except Exception as exc:
+                self._logger.error("[Kronos] Forecast failed: %s", exc, exc_info=True)
+                raise HTTPException(status_code=500, detail=f"Kronos prediction failed: {exc}")
+
+        samples = np.asarray(sample_tensor, dtype=float)
+        if samples.ndim != 3 or samples.shape[0] != sample_count or samples.shape[1] != horizon or samples.shape[2] < 4:
+            raise HTTPException(
+                status_code=500,
+                detail=f"Kronos sample tensor has invalid shape: {list(samples.shape)}",
+            )
+
+        ohlc4_samples = samples[:, :, :4].mean(axis=2)
+        p10 = np.quantile(ohlc4_samples, 0.1, axis=0).astype(float)
+        p50 = np.quantile(ohlc4_samples, 0.5, axis=0).astype(float)
+        p90 = np.quantile(ohlc4_samples, 0.9, axis=0).astype(float)
+        output_validation = self._build_output_validation(p10, p50, p90, samples)
+
+        return {
+            "p10": p10,
+            "p50": p50,
+            "p90": p90,
+            "model_name": self.MODEL_HF_ID,
+            "tokenizer_name": self.TOKENIZER_HF_ID,
+            "context_length": context_length,
+            "output_horizon": horizon,
+            "sample_count": sample_count,
+            "seed": seed,
+            "input_semantics": {
+                "feature_channels": ["ohlc4"],
+                "active_forecast_channels": ["ohlc4"],
+                "proxy_channels": ["open", "high", "low", "close"],
+                "ignored_channels": ["volume", "amount"],
+                "price_mode": "ohlc4_single_channel",
+                "base_signal": "ohlc4",
+                "volume_mode": "synthetic_zero",
+                "amount_mode": "synthetic_zero",
+                "adapter_mode": "kronos_ohlc4_proxy",
+            },
+            "input_validation": {
+                "series_field": "ohlc4",
+                "dtype": "float32",
+                "context_length": context_length,
+                "finite": True,
+            },
+            "output_semantics": {
+                "forecast_channel": "ohlc4",
+                "forecast_mode": "single_future_ohlc4_line",
+                "quantile_fields": ["p10", "p50", "p90"],
+                "quantile_source": "sample_paths",
+                "candle_projection": "omitted",
+                "reference_baseline": "last_ohlc4",
+            },
+            "output_validation": output_validation,
+        }

backend/kronos_core/__init__.py

@@ -0,0 +1 @@
+"""Vendored Kronos model package."""

backend/kronos_core/model/kronos.py

@@ -2,12 +2,41 @@ import numpy as np
 import pandas as pd
 import torch
 from huggingface_hub import PyTorchModelHubMixin
-import sys
 
 from tqdm import trange
 
-sys.path.append("../")
-from model.module import *
+from .module import *
+
+
+def _module_has_meta_tensors(module: nn.Module) -> bool:
+    return any(getattr(param, "is_meta", False) for param in module.parameters()) or any(
+        getattr(buffer, "is_meta", False) for buffer in module.buffers()
+    )
+
+
+def _compat_load_state_dict(
+    module: nn.Module,
+    state_dict,
+    *,
+    strict: bool = True,
+    assign: bool = False,
+):
+    use_assign = assign or _module_has_meta_tensors(module)
+    if use_assign:
+        try:
+            return nn.Module.load_state_dict(module, state_dict, strict=strict, assign=True)
+        except TypeError:
+            pass
+    return nn.Module.load_state_dict(module, state_dict, strict=strict)
+
+
+def _move_module_to_device(module: nn.Module, device: str):
+    if _module_has_meta_tensors(module):
+        try:
+            return module.to_empty(device=device)
+        except TypeError:
+            return module.to_empty(device=torch.device(device))
+    return module.to(device)
 
 
 class KronosTokenizer(nn.Module, PyTorchModelHubMixin):
@@ -176,6 +205,9 @@ class KronosTokenizer(nn.Module, PyTorchModelHubMixin):
         z = self.head(z)
         return z
 
+    def load_state_dict(self, state_dict, strict=True, assign=False):
+        return _compat_load_state_dict(self, state_dict, strict=strict, assign=assign)
+
 
 class Kronos(nn.Module, PyTorchModelHubMixin):
     """
@@ -327,6 +359,9 @@ class Kronos(nn.Module, PyTorchModelHubMixin):
         x2 = self.dep_layer(context, sibling_embed, key_padding_mask=padding_mask)
         return self.head.cond_forward(x2)
 
+    def load_state_dict(self, state_dict, strict=True, assign=False):
+        return _compat_load_state_dict(self, state_dict, strict=strict, assign=assign)
+
 
 def top_k_top_p_filtering(
         logits,
@@ -386,7 +421,22 @@ def sample_from_logits(logits, temperature=1.0, top_k=None, top_p=None, sample_l
     return x
 
 
-def auto_regressive_inference(tokenizer, model, x, x_stamp, y_stamp, max_context, pred_len, clip=5, T=1.0, top_k=0, top_p=0.99, sample_count=5, verbose=False, return_samples=False):
+def auto_regressive_inference(
+    tokenizer,
+    model,
+    x,
+    x_stamp,
+    y_stamp,
+    max_context,
+    pred_len,
+    clip=5,
+    T=1.0,
+    top_k=0,
+    top_p=0.99,
+    sample_count=5,
+    verbose=False,
+    return_samples=False,
+):
     with torch.no_grad():
         x = torch.clip(x, -clip, clip)
 
@@ -464,7 +514,6 @@ def auto_regressive_inference(tokenizer, model, x, x_stamp, y_stamp, max_context
         z = tokenizer.decode(input_tokens, half=True)
         z = z.reshape(-1, sample_count, z.size(1), z.size(2))
         preds = z.cpu().numpy()
-        
         if not return_samples:
             preds = np.mean(preds, axis=1)
 
@@ -504,18 +553,108 @@ class KronosPredictor:
         
         self.device = device
 
-        self.tokenizer = self.tokenizer.to(self.device)
-        self.model = self.model.to(self.device)
-
-    def generate(self, x, x_stamp, y_stamp, pred_len, T, top_k, top_p, sample_count, verbose, return_samples=False):
+        self.tokenizer = _move_module_to_device(self.tokenizer, self.device)
+        self.model = _move_module_to_device(self.model, self.device)
+
+    def generate(
+        self,
+        x,
+        x_stamp,
+        y_stamp,
+        pred_len,
+        T,
+        top_k,
+        top_p,
+        sample_count,
+        verbose,
+        return_samples=False,
+    ):
 
         x_tensor = torch.from_numpy(np.array(x).astype(np.float32)).to(self.device)
         x_stamp_tensor = torch.from_numpy(np.array(x_stamp).astype(np.float32)).to(self.device)
         y_stamp_tensor = torch.from_numpy(np.array(y_stamp).astype(np.float32)).to(self.device)
 
-        preds = auto_regressive_inference(self.tokenizer, self.model, x_tensor, x_stamp_tensor, y_stamp_tensor, self.max_context, pred_len,
-                                          self.clip, T, top_k, top_p, sample_count, verbose, return_samples=return_samples)
-        preds = preds[:, -pred_len:, :]
+        preds = auto_regressive_inference(
+            self.tokenizer,
+            self.model,
+            x_tensor,
+            x_stamp_tensor,
+            y_stamp_tensor,
+            self.max_context,
+            pred_len,
+            self.clip,
+            T,
+            top_k,
+            top_p,
+            sample_count,
+            verbose,
+            return_samples=return_samples,
+        )
+        if return_samples:
+            preds = preds[:, :, -pred_len:, :]
+        else:
+            preds = preds[:, -pred_len:, :]
+        return preds
+
+    def predict_samples(
+        self,
+        df,
+        x_timestamp,
+        y_timestamp,
+        pred_len,
+        T=1.0,
+        top_k=0,
+        top_p=0.9,
+        sample_count=5,
+        verbose=False,
+    ):
+        if not isinstance(df, pd.DataFrame):
+            raise ValueError("Input must be a pandas DataFrame.")
+
+        if not all(col in df.columns for col in self.price_cols):
+            raise ValueError(f"Price columns {self.price_cols} not found in DataFrame.")
+
+        df = df.copy()
+        if self.vol_col not in df.columns:
+            df[self.vol_col] = 0.0
+            df[self.amt_vol] = 0.0
+        if self.amt_vol not in df.columns and self.vol_col in df.columns:
+            df[self.amt_vol] = df[self.vol_col] * df[self.price_cols].mean(axis=1)
+
+        if df[self.price_cols + [self.vol_col, self.amt_vol]].isnull().values.any():
+            raise ValueError("Input DataFrame contains NaN values in price or volume columns.")
+
+        x_time_df = calc_time_stamps(x_timestamp)
+        y_time_df = calc_time_stamps(y_timestamp)
+
+        x = df[self.price_cols + [self.vol_col, self.amt_vol]].values.astype(np.float32)
+        x_stamp = x_time_df.values.astype(np.float32)
+        y_stamp = y_time_df.values.astype(np.float32)
+
+        x_mean, x_std = np.mean(x, axis=0), np.std(x, axis=0)
+
+        x = (x - x_mean) / (x_std + 1e-5)
+        x = np.clip(x, -self.clip, self.clip)
+
+        x = x[np.newaxis, :]
+        x_stamp = x_stamp[np.newaxis, :]
+        y_stamp = y_stamp[np.newaxis, :]
+
+        preds = self.generate(
+            x,
+            x_stamp,
+            y_stamp,
+            pred_len,
+            T,
+            top_k,
+            top_p,
+            sample_count,
+            verbose,
+            return_samples=True,
+        )
+
+        preds = preds.squeeze(0)
+        preds = preds * (x_std + 1e-5) + x_mean
         return preds
 
     def predict(self, df, x_timestamp, y_timestamp, pred_len, T=1.0, top_k=0, top_p=0.9, sample_count=1, verbose=True):

backend/launcher.py

@@ -2,8 +2,6 @@ from __future__ import annotations
 
 import logging
 import os
-import socket
-import sys
 import threading
 import time
 import webbrowser
@@ -11,6 +9,7 @@ from pathlib import Path
 from typing import Any
 
 import uvicorn
+from backend import server_runtime
 
 logging.basicConfig(
     level=logging.INFO,
@@ -19,8 +18,19 @@ logging.basicConfig(
 logger = logging.getLogger("aiforecast-launcher")
 
 DEFAULT_HOST: str = "127.0.0.1"
-SERVER_BOOT_DELAY_SECONDS: float = 2.5
+SERVER_READY_TIMEOUT_SECONDS: float = 15.0
+SERVER_READY_POLL_INTERVAL_SECONDS: float = 0.25
 PROJECT_ROOT: Path = Path(__file__).resolve().parent.parent
+ENV_FILE: Path = PROJECT_ROOT / ".env"
+CONSOLE_MODE_ENV: str = "AIFORECAST_CONSOLE_MODE"
+
+
+def load_runtime_env() -> None:
+    """Load local runtime settings before resolving the server port."""
+    server_runtime.load_runtime_env(ENV_FILE, override=False)
+
+
+load_runtime_env()
 
 BANNER = r"""
    _    _____   _____                           _   
@@ -35,65 +45,94 @@ def print_banner() -> None:
     """Render a clean startup banner in the local console."""
     os.system("cls" if os.name == "nt" else "clear")
     print("\033[96m" + BANNER + "\033[0m")
-    print(" [*] Dang khoi dong he thong phan tich AI...")
-    print(" [*] Dang nap du lieu thi truong...")
+    print(" [*] Dang khoi dong SuperAI Forecast...")
+    print(" [*] Dang khoi tao he thong du bao Kronos / TimesFM / Chronos...")
     print(" [*] Trinh duyet se tu dong mo khi server san sang.")
     print()
 
 
-def load_app() -> Any:
-    """Import the FastAPI app after runtime settings are in place."""
-    project_root = str(PROJECT_ROOT)
-    if project_root not in sys.path:
-        sys.path.insert(0, project_root)
-    from backend.main import app as fastapi_app
-    return fastapi_app
+def apply_console_window_mode() -> None:
+    """Minimize or hide this console window on Windows without affecting logs."""
+    if os.name != "nt":
+        return
+
+    mode = os.getenv(CONSOLE_MODE_ENV, "minimize").strip().lower()
+    if mode in {"", "show", "visible", "keep"}:
+        return
 
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        user32 = ctypes.windll.user32
+        console_window = kernel32.GetConsoleWindow()
+        if not console_window:
+            return
+
+        show_code = 0 if mode == "hide" else 6
+        user32.ShowWindow(console_window, show_code)
+    except Exception as exc:
+        logger.debug("Khong the doi che do cua so console: %s", exc)
 
-def find_free_port(host: str = DEFAULT_HOST) -> int:
-    """Ask the OS for a currently available local TCP port."""
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server_socket:
-        server_socket.bind((host, 0))
-        server_socket.listen(1)
-        return int(server_socket.getsockname()[1])
+
+def load_app() -> Any:
+    """Import the FastAPI app after runtime settings are in place."""
+    return server_runtime.load_fastapi_app(PROJECT_ROOT)
 
 
 def resolve_server_port() -> int:
-    """Use PORT when defined, otherwise choose a random free local port."""
-    raw_port = os.getenv("PORT", "").strip()
-    if raw_port:
-        try:
-            return int(raw_port)
-        except ValueError as exc:
-            raise ValueError(f"Invalid PORT value: {raw_port}") from exc
-
-    port = find_free_port()
-    os.environ["PORT"] = str(port)
-    return port
-
-
-def open_browser(url: str) -> None:
-    """Wait briefly for the server to start, then open the dashboard."""
-    time.sleep(SERVER_BOOT_DELAY_SECONDS)
+    """Use PORT when available and free, otherwise choose a free local port."""
+    return server_runtime.resolve_server_port(DEFAULT_HOST, logger=logger)
+
+
+def wait_for_server_start(server: uvicorn.Server, startup_finished: threading.Event) -> bool:
+    """Wait until this Uvicorn instance reports a successful startup."""
+    deadline = time.monotonic() + SERVER_READY_TIMEOUT_SECONDS
+    while time.monotonic() < deadline:
+        if server.started:
+            return True
+        if startup_finished.is_set():
+            return False
+        time.sleep(SERVER_READY_POLL_INTERVAL_SECONDS)
+    return False
+
+
+def open_browser(url: str, server: uvicorn.Server, startup_finished: threading.Event) -> None:
+    """Open the dashboard only after this backend instance is ready."""
+    if not wait_for_server_start(server, startup_finished):
+        logger.warning("Bo qua mo trinh duyet vi backend khong san sang tai %s", url)
+        return
     logger.info("Dang mo bang dieu khien tai %s", url)
     webbrowser.open(url)
 
 
 if __name__ == "__main__":
     print_banner()
+    apply_console_window_mode()
 
     host = DEFAULT_HOST
     port = resolve_server_port()
     url = f"http://{host}:{port}"
     app = load_app()
+    config = uvicorn.Config(app, host=host, port=port, log_level="warning")
+    server = uvicorn.Server(config)
+    startup_finished = threading.Event()
 
-    logger.info("Khoi dong Backend Core tren %s", url)
-    threading.Thread(target=open_browser, args=(url,), daemon=True).start()
+    logger.info("Khoi dong SuperAI Forecast Backend tren %s", url)
+    threading.Thread(
+        target=open_browser,
+        args=(url, server, startup_finished),
+        daemon=True,
+    ).start()
 
     try:
-        uvicorn.run(app, host=host, port=port, log_level="warning")
+        server.run()
+    except SystemExit as exc:
+        if exc.code not in (0, None):
+            logger.error("Loi khoi dong he thong tren %s (exit=%s)", url, exc.code)
+        raise
     except Exception as exc:
         logger.exception("Loi khoi dong he thong: %s", exc)
-        print("\n [!] Co loi xay ra trong qua trinh khoi dong.")
-        print(" [!] Nhan Enter de thoat...")
-        input()
+        raise
+    finally:
+        startup_finished.set()

backend/runtime_utils.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import socket
 from copy import deepcopy
 from dataclasses import dataclass
 from typing import Any, List
@@ -15,6 +16,22 @@ class RuntimePaths:
     project_root: str
 
 
+def can_bind_tcp_port(host: str, port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server_socket:
+        try:
+            server_socket.bind((host, port))
+        except OSError:
+            return False
+    return True
+
+
+def find_free_tcp_port(host: str = "127.0.0.1") -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server_socket:
+        server_socket.bind((host, 0))
+        server_socket.listen(1)
+        return int(server_socket.getsockname()[1])
+
+
 def parse_cors_origins(raw_origins: str) -> List[str]:
     origins = [origin.strip() for origin in raw_origins.split(",") if origin.strip()]
     return origins or ["*"]

backend/server_runtime.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, Callable, Mapping, MutableMapping, Protocol
+
+from dotenv import load_dotenv
+
+from backend.runtime_utils import can_bind_tcp_port, find_free_tcp_port
+
+DEFAULT_HUGGINGFACE_PORT = 7860
+
+
+class LoggerLike(Protocol):
+    def warning(self, msg: str, *args: Any, **kwargs: Any) -> None: ...
+
+
+def is_huggingface_space(env: Mapping[str, str] | None = None) -> bool:
+    runtime_env = env or os.environ
+    return bool(runtime_env.get("SPACE_ID") or runtime_env.get("SPACE_HOST"))
+
+
+def bootstrap_runtime_port(
+    env: MutableMapping[str, str] | None = None,
+    *,
+    huggingface_port: int = DEFAULT_HUGGINGFACE_PORT,
+) -> None:
+    runtime_env = env or os.environ
+    if is_huggingface_space(runtime_env) and not runtime_env.get("PORT", "").strip():
+        runtime_env["PORT"] = str(huggingface_port)
+
+
+def load_runtime_env(
+    env_file: Path,
+    *,
+    override: bool = False,
+) -> bool:
+    if not env_file.exists():
+        return False
+    load_dotenv(env_file, override=override)
+    return True
+
+
+def load_fastapi_app(
+    project_root: Path,
+    *,
+    module_name: str = "backend.main",
+    attr_name: str = "app",
+) -> Any:
+    project_root_str = str(project_root)
+    if project_root_str not in sys.path:
+        sys.path.insert(0, project_root_str)
+
+    module = __import__(module_name, fromlist=[attr_name])
+    return getattr(module, attr_name)
+
+
+def resolve_server_port(
+    host: str,
+    *,
+    env: MutableMapping[str, str] | None = None,
+    logger: LoggerLike | None = None,
+    huggingface_port: int = DEFAULT_HUGGINGFACE_PORT,
+    port_checker: Callable[[str, int], bool] = can_bind_tcp_port,
+    free_port_finder: Callable[[str], int] = find_free_tcp_port,
+) -> int:
+    runtime_env = env or os.environ
+    raw_port = runtime_env.get("PORT", "").strip()
+
+    if raw_port:
+        try:
+            configured_port = int(raw_port)
+        except ValueError as exc:
+            raise ValueError(f"Invalid PORT value: {raw_port}") from exc
+
+        if is_huggingface_space(runtime_env) or port_checker(host, configured_port):
+            return configured_port
+
+        fallback_port = free_port_finder(host)
+        runtime_env["PORT"] = str(fallback_port)
+        if logger is not None:
+            logger.warning(
+                "PORT %s dang ban tren %s, tu dong chuyen sang cong %s",
+                configured_port,
+                host,
+                fallback_port,
+            )
+        return fallback_port
+
+    if is_huggingface_space(runtime_env):
+        runtime_env["PORT"] = str(huggingface_port)
+        return huggingface_port
+
+    fallback_port = free_port_finder(host)
+    runtime_env["PORT"] = str(fallback_port)
+    return fallback_port

backend/startup_utils.py

@@ -83,17 +83,32 @@ async def warmup_timesfm(
     startup_timesfm_state: MutableMapping[str, Any],
     logger: LoggerLike,
 ) -> None:
-    startup_timesfm_state["warming"] = True
-    startup_timesfm_state["last_error"] = None
+    await warmup_forecaster(
+        forecaster=forecaster,
+        startup_state=startup_timesfm_state,
+        logger=logger,
+        label="TimesFM",
+    )
+
+
+async def warmup_forecaster(
+    *,
+    forecaster: ForecasterLike,
+    startup_state: MutableMapping[str, Any],
+    logger: LoggerLike,
+    label: str,
+) -> None:
+    startup_state["warming"] = True
+    startup_state["last_error"] = None
     try:
         await forecaster._lazy_load()
-        startup_timesfm_state["loaded"] = forecaster.is_ready
-        startup_timesfm_state["device"] = forecaster.device
-        logger.info("[startup] TimesFM warmup finished on %s", forecaster.device)
+        startup_state["loaded"] = forecaster.is_ready
+        startup_state["device"] = forecaster.device
+        logger.info("[startup] %s warmup finished on %s", label, forecaster.device)
     except Exception as ex:
-        startup_timesfm_state["loaded"] = False
-        startup_timesfm_state["device"] = forecaster.device
-        startup_timesfm_state["last_error"] = str(ex)
-        logger.warning("[startup] TimesFM warmup failed: %s", ex)
+        startup_state["loaded"] = False
+        startup_state["device"] = forecaster.device
+        startup_state["last_error"] = str(ex)
+        logger.warning("[startup] %s warmup failed: %s", label, ex)
     finally:
-        startup_timesfm_state["warming"] = False
+        startup_state["warming"] = False

backend/test_api_regressions.py

@@ -18,6 +18,117 @@ class ApiRegressionTests(unittest.TestCase):
         cls.client = TestClient(main.app)
         cls.symbol_a, cls.symbol_b = list(main.SYMBOLS.keys())[:2]
 
+    def _build_current_forecast_payload(
+        self,
+        requested: dict[str, bool] | None = None,
+    ) -> dict[str, object]:
+        requested_models = dict(main.DEFAULT_FORECAST_MODEL_SELECTION)
+        if requested:
+            requested_models.update(requested)
+        if not any(requested_models.values()):
+            requested_models["kronos"] = True
+
+        def build_model_meta(model_key: str) -> dict[str, object]:
+            adapter_mode = {
+                "kronos": "kronos_ohlc4_proxy",
+                "timesfm": "timesfm_native",
+                "chronos": "chronos_native",
+            }[model_key]
+            is_kronos = model_key == "kronos"
+            return {
+                "model_key": model_key,
+                "name": model_key,
+                "context_length": 64,
+                "available_history": 500,
+                "input_semantics": {
+                    "feature_channels": ["ohlc4"],
+                    "price_mode": "ohlc4_single_channel",
+                    "base_signal": "ohlc4",
+                    "volume_mode": "synthetic_zero" if is_kronos else "omitted",
+                    "amount_mode": "synthetic_zero" if is_kronos else "omitted",
+                    "active_forecast_channels": ["ohlc4"],
+                    "adapter_mode": adapter_mode,
+                },
+                "output_semantics": {
+                    "forecast_channel": "ohlc4",
+                    "forecast_mode": "single_future_ohlc4_line",
+                    "candle_projection": "omitted",
+                    "reference_baseline": "last_ohlc4",
+                },
+            }
+
+        forecast_rows = [
+            {"time": 1, "p10": 1.0, "p50": 1.1, "p90": 1.2},
+            {"time": 2, "p10": 1.1, "p50": 1.2, "p90": 1.3},
+        ]
+        forecast_models: dict[str, object] = {}
+        components: dict[str, object] = {}
+        active_models: list[str] = []
+        for model_key in main.FORECAST_MODEL_ORDER:
+            enabled = bool(requested_models.get(model_key, False))
+            if enabled:
+                model_meta = build_model_meta(model_key)
+                forecast_models[model_key] = {
+                    "enabled": True,
+                    "available": True,
+                    "success": True,
+                    "skipped": False,
+                    "error": None,
+                    "forecast": forecast_rows,
+                    "model": model_meta,
+                    "ensemble": {"confidence": 61.0},
+                    "model_diagnostics": {},
+                }
+                components[model_key] = model_meta
+                active_models.append(model_key)
+            else:
+                forecast_models[model_key] = {
+                    "enabled": False,
+                    "available": True,
+                    "success": False,
+                    "skipped": True,
+                    "error": None,
+                    "forecast": [],
+                    "model": {},
+                    "ensemble": {},
+                    "model_diagnostics": {},
+                }
+
+        return {
+            "forecast": forecast_rows,
+            "display": {
+                "mode": (
+                    "raw_kronos_ohlc4_line"
+                    if active_models == ["kronos"]
+                    else "raw_timesfm_ohlc4_line"
+                    if active_models == ["timesfm"]
+                    else "raw_chronos_ohlc4_line"
+                    if active_models == ["chronos"]
+                    else "multi_model_ohlc4_line"
+                ),
+                "channels": ["ohlc4"],
+                "output_mode": "single_future_ohlc4_line",
+                "reference_series": "ohlc4",
+                "market_price_field": "last_close",
+                "forecast_reference_field": "last_ohlc4",
+                "visual_anchor_field": "last_close",
+                "combination_mode": "mean_of_enabled_models",
+            },
+            "forecast_models": forecast_models,
+            "model_selection": {
+                "requested": requested_models,
+                "active": active_models,
+                "defaults": dict(main.DEFAULT_FORECAST_MODEL_SELECTION),
+                "combination_mode": "mean_of_enabled_models",
+            },
+            "model": {
+                "name": active_models[0] if len(active_models) == 1 else "mean_of_enabled_models",
+                "active_models": active_models,
+                "components": components,
+                "cache_version": main.CACHE_VERSION,
+            },
+        }
+
     def test_cache_stats_requires_runtime_admin_token(self) -> None:
         with patch.object(main, "ADMIN_TOKEN", "test-admin-token"):
             unauthorized = self.client.get("/api/cache/stats")
@@ -35,6 +146,36 @@ class ApiRegressionTests(unittest.TestCase):
             )
             self.assertEqual(authorized.status_code, 200)
 
+    def test_forecast_rules_endpoint_exposes_versioned_contract(self) -> None:
+        response = self.client.get("/api/forecasting/rules")
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(body["rules"]["version"], main.FORECAST_RULE_DOCUMENT.version)
+        self.assertEqual(body["rules"]["default_horizon"], 10)
+        self.assertEqual(body["rules"]["recommended_context_length"], 512)
+        self.assertEqual(body["rules"]["default_line_width"], 1)
+        self.assertIn("chronos", body["models"])
+
+    def test_frontend_forecast_model_registry_has_dedicated_no_cache_route(self) -> None:
+        response = self.client.get("/forecast-models.js")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("Cache-Control", response.headers)
+        self.assertEqual(
+            response.headers["Cache-Control"],
+            "no-store, no-cache, must-revalidate, max-age=0",
+        )
+
+    def test_forecast_model_selection_supports_chronos(self) -> None:
+        selection = main._normalize_forecast_model_selection(
+            use_kronos=False,
+            use_timesfm=False,
+            use_chronos=True,
+        )
+        self.assertEqual(
+            selection,
+            {"kronos": False, "timesfm": False, "chronos": True},
+        )
+
     def test_watchlist_tickers_deduplicates_and_reports_invalid_symbols(self) -> None:
         async def fake_fetch_ticker(symbol: str) -> dict[str, object]:
             return {"symbol": symbol, "price": 123.45}
@@ -95,6 +236,116 @@ class ApiRegressionTests(unittest.TestCase):
         self.assertNotIn("binance", main._get_source_priority("EURUSD"))
         self.assertEqual(main._get_source_priority("DXY"), ["yfinance", "twelvedata"])
 
+    def test_xauusd_priority_prefers_binance_paxg_proxy_first(self) -> None:
+        self.assertEqual(
+            main._get_source_priority("XAUUSD", "1d"),
+            ["binance", "twelvedata", "yfinance"],
+        )
+
+    def test_forecast_context_window_prefers_recent_tail(self) -> None:
+        self.assertEqual(main._resolve_forecast_context_window("1h", 1000), 256)
+        self.assertEqual(main._resolve_forecast_context_window("1d", 180), 180)
+        self.assertEqual(main._resolve_forecast_context_window("1w", 400), 192)
+
+    def test_forecast_context_candidates_include_shorter_windows_for_responsiveness(self) -> None:
+        self.assertEqual(main._resolve_forecast_context_candidates("1d", 400), [48, 64, 128, 256])
+        self.assertEqual(main._resolve_forecast_context_candidates("4h", 300), [64, 96, 128, 256])
+        self.assertEqual(main._resolve_forecast_context_candidates("1d", 60), [48, 60])
+
+    def test_kronos_context_candidates_cap_direct_model_window_for_latency(self) -> None:
+        self.assertEqual(main._resolve_kronos_context_candidates("1d", 1000), [64, 128, 256])
+        self.assertEqual(main._resolve_model_context_cap("kronos", "1d", 1000), 256)
+
+    def test_forecast_context_candidate_score_penalizes_near_flat_paths(self) -> None:
+        responsive = main._score_forecast_context_candidate(
+            analysis_bundle={
+                "p50": main.np.array([100.0, 99.4, 98.8, 98.1], dtype=float),
+                "confidence": 58.0,
+            },
+            last_ohlc4=100.0,
+            recent_abs_step_pct=1.0,
+        )
+        flat = main._score_forecast_context_candidate(
+            analysis_bundle={
+                "p50": main.np.array([100.0, 99.98, 100.01, 100.0], dtype=float),
+                "confidence": 58.0,
+            },
+            last_ohlc4=100.0,
+            recent_abs_step_pct=1.0,
+        )
+
+        self.assertGreater(responsive["score"], flat["score"])
+        self.assertGreater(responsive["step_abs_mean_pct"], flat["step_abs_mean_pct"])
+
+    def test_forecast_amplitude_calibration_scales_flat_path_toward_historical_targets(self) -> None:
+        raw_bundle = main._build_raw_ohlc4_bundle(
+            {
+                "p10": main.np.array([99.98, 99.96, 99.94], dtype=float),
+                "p50": main.np.array([100.0, 99.99, 99.98], dtype=float),
+                "p90": main.np.array([100.02, 100.01, 100.0], dtype=float),
+            },
+            100.0,
+        )
+        calibrated_bundle, calibration_meta = main._apply_forecast_amplitude_calibration(
+            raw_bundle=raw_bundle,
+            last_ohlc4=100.0,
+            target_profile={
+                "target_step_abs_mean_pct": 0.45,
+                "target_range_pct": 1.2,
+                "recent_abs_step_pct": 0.8,
+                "rolling_targets": None,
+                "regime_targets": None,
+            },
+        )
+
+        self.assertGreater(calibration_meta["scale"], 1.0)
+        self.assertGreater(
+            calibrated_bundle["path_metrics"]["final_return_pct"],
+            raw_bundle["path_metrics"]["final_return_pct"] * 3,
+        )
+        self.assertGreater(
+            calibration_meta["calibrated_path"]["step_abs_mean_pct"],
+            calibration_meta["raw_path"]["step_abs_mean_pct"],
+        )
+
+    def test_forecast_path_texture_adds_stepwise_zigzag_to_future_points(self) -> None:
+        base_bundle = main._build_raw_ohlc4_bundle(
+            {
+                "p10": main.np.array([99.6, 99.4, 99.2, 99.0], dtype=float),
+                "p50": main.np.array([99.9, 99.8, 99.7, 99.6], dtype=float),
+                "p90": main.np.array([100.2, 100.1, 100.0, 99.9], dtype=float),
+            },
+            100.0,
+        )
+        textured_bundle, texture_meta = main._apply_forecast_path_texture(
+            base_bundle=base_bundle,
+            last_ohlc4=100.0,
+            target_profile={
+                "target_step_abs_mean_pct": 0.45,
+                "target_range_pct": 1.4,
+                "recent_abs_step_pct": 0.8,
+            },
+            texture_template={
+                "step_returns_pct": main.np.array([0.22, -0.35, 0.28, -0.12], dtype=float),
+                "step_abs_mean_pct": 0.3133,
+                "range_pct": 0.40,
+                "match_count": 6,
+                "signature_len": 48,
+            },
+        )
+
+        self.assertTrue(texture_meta["applied"])
+        self.assertGreater(texture_meta["blend_alpha"], 0.0)
+        self.assertGreater(
+            texture_meta["textured_path"]["step_abs_mean_pct"],
+            texture_meta["base_path"]["step_abs_mean_pct"],
+        )
+        self.assertNotAlmostEqual(
+            textured_bundle["path_metrics"]["final_return_pct"],
+            base_bundle["path_metrics"]["final_return_pct"],
+            delta=0.02,
+        )
+
     def test_crypto_dynamic_source_mappings_are_derived_for_hf_safe_fallbacks(self) -> None:
         self.assertEqual(main._get_symbol_mapping("BTCUSD", "twelvedata"), "BTC/USD")
         self.assertEqual(main._get_symbol_mapping("BTCUSD", "yfinance"), "BTC-USD")
@@ -466,7 +717,7 @@ class ApiRegressionTests(unittest.TestCase):
         self.assertEqual({item[0] for item in calls}, {"twelvedata"})
         self.assertEqual({item[2] for item in calls}, {"4h"})
 
-    def test_kronos_feature_prep_collapses_prices_to_ohlc4_and_zeroes_volume_channels(self) -> None:
+    def test_timesfm_feature_prep_collapses_prices_to_ohlc4(self) -> None:
         df = main.pd.DataFrame(
             [
                 {"open": 1.0, "high": 1.1, "low": 0.9, "close": 1.05, "volume": 0.0, "amount": 0.0},
@@ -474,13 +725,13 @@ class ApiRegressionTests(unittest.TestCase):
             ]
         )
 
-        prepared = main.KronosForecaster._prepare_feature_frame(df)
+        prepared = main.TimesFMForecaster._prepare_feature_frame(df)
         expected_ohlc4 = df[["open", "high", "low", "close"]].mean(axis=1).astype(main.np.float32)
 
         self.assertEqual(list(prepared.columns), ["ohlc4"])
         self.assertTrue(main.np.allclose(prepared["ohlc4"].values, expected_ohlc4.values))
 
-    def test_kronos_feature_prep_ignores_upstream_volume_and_amount_noise(self) -> None:
+    def test_timesfm_feature_prep_ignores_upstream_volume_and_amount_noise(self) -> None:
         df = main.pd.DataFrame(
             [
                 {"open": 10.0, "high": 11.0, "low": 9.0, "close": 10.5, "volume": 100.0, "amount": 1050.0},
@@ -488,36 +739,90 @@ class ApiRegressionTests(unittest.TestCase):
             ]
         )
 
-        prepared = main.KronosForecaster._prepare_feature_frame(df)
+        prepared = main.TimesFMForecaster._prepare_feature_frame(df)
         expected_ohlc4 = df[["open", "high", "low", "close"]].mean(axis=1).astype(main.np.float32)
 
         self.assertEqual(list(prepared.columns), ["ohlc4"])
         self.assertTrue(main.np.allclose(prepared["ohlc4"].values, expected_ohlc4.values))
 
-    def test_kronos_normalization_uses_std_plus_epsilon_contract(self) -> None:
-        x = main.np.array(
+    def test_timesfm_input_series_uses_float32_ohlc4_contract(self) -> None:
+        df = main.pd.DataFrame(
+            [
+                {"open": 1.0, "high": 1.1, "low": 0.9, "close": 1.0, "volume": 0.0},
+                {"open": 1.1, "high": 1.2, "low": 1.0, "close": 1.1, "volume": 0.0},
+                {"open": 1.2, "high": 1.3, "low": 1.1, "close": 1.2, "volume": 0.0},
+                {"open": 1.3, "high": 1.4, "low": 1.2, "close": 1.3, "volume": 0.0},
+                {"open": 1.4, "high": 1.5, "low": 1.3, "close": 1.4, "volume": 0.0},
+                {"open": 1.5, "high": 1.6, "low": 1.4, "close": 1.5, "volume": 0.0},
+                {"open": 1.6, "high": 1.7, "low": 1.5, "close": 1.6, "volume": 0.0},
+                {"open": 1.7, "high": 1.8, "low": 1.6, "close": 1.7, "volume": 0.0},
+                {"open": 1.8, "high": 1.9, "low": 1.7, "close": 1.8, "volume": 0.0},
+                {"open": 1.9, "high": 2.0, "low": 1.8, "close": 1.9, "volume": 0.0},
+                {"open": 2.0, "high": 2.1, "low": 1.9, "close": 2.0, "volume": 0.0},
+                {"open": 2.1, "high": 2.2, "low": 2.0, "close": 2.1, "volume": 0.0},
+                {"open": 2.2, "high": 2.3, "low": 2.1, "close": 2.2, "volume": 0.0},
+                {"open": 2.3, "high": 2.4, "low": 2.2, "close": 2.3, "volume": 0.0},
+                {"open": 2.4, "high": 2.5, "low": 2.3, "close": 2.4, "volume": 0.0},
+                {"open": 2.5, "high": 2.6, "low": 2.4, "close": 2.5, "volume": 0.0},
+                {"open": 2.6, "high": 2.7, "low": 2.5, "close": 2.6, "volume": 0.0},
+                {"open": 2.7, "high": 2.8, "low": 2.6, "close": 2.7, "volume": 0.0},
+                {"open": 2.8, "high": 2.9, "low": 2.7, "close": 2.8, "volume": 0.0},
+                {"open": 2.9, "high": 3.0, "low": 2.8, "close": 2.9, "volume": 0.0},
+                {"open": 3.0, "high": 3.1, "low": 2.9, "close": 3.0, "volume": 0.0},
+                {"open": 3.1, "high": 3.2, "low": 3.0, "close": 3.1, "volume": 0.0},
+                {"open": 3.2, "high": 3.3, "low": 3.1, "close": 3.2, "volume": 0.0},
+                {"open": 3.3, "high": 3.4, "low": 3.2, "close": 3.3, "volume": 0.0},
+                {"open": 3.4, "high": 3.5, "low": 3.3, "close": 3.4, "volume": 0.0},
+                {"open": 3.5, "high": 3.6, "low": 3.4, "close": 3.5, "volume": 0.0},
+                {"open": 3.6, "high": 3.7, "low": 3.5, "close": 3.6, "volume": 0.0},
+                {"open": 3.7, "high": 3.8, "low": 3.6, "close": 3.7, "volume": 0.0},
+                {"open": 3.8, "high": 3.9, "low": 3.7, "close": 3.8, "volume": 0.0},
+                {"open": 3.9, "high": 4.0, "low": 3.8, "close": 3.9, "volume": 0.0},
+                {"open": 4.0, "high": 4.1, "low": 3.9, "close": 4.0, "volume": 0.0},
+                {"open": 4.1, "high": 4.2, "low": 4.0, "close": 4.1, "volume": 0.0},
+                {"open": 4.2, "high": 4.3, "low": 4.1, "close": 4.2, "volume": 0.0},
+                {"open": 4.3, "high": 4.4, "low": 4.2, "close": 4.3, "volume": 0.0},
+            ]
+        )
+
+        ohlc4_series = main.TimesFMForecaster._extract_ohlc4_series(df)
+        expected_ohlc4 = df[["open", "high", "low", "close"]].mean(axis=1).astype(main.np.float32)
+
+        self.assertEqual(ohlc4_series.dtype, main.np.float32)
+        self.assertTrue(main.np.allclose(ohlc4_series, expected_ohlc4.values))
+
+    def test_timesfm_output_validation_prefers_point_forecast_median(self) -> None:
+        point = main.np.array([[101.0, 102.0]], dtype=main.np.float32)
+        quantiles = main.np.array(
             [
-                [1.0, 1.1, 0.9, 1.0, 0.0, 0.0],
-                [1.1, 1.2, 1.0, 1.1, 0.0, 0.0],
-                [1.2, 1.3, 1.1, 1.2, 0.0, 0.0],
+                [
+                    [100.5, 99.0, 99.5, 100.0, 100.5, 101.0, 101.5, 102.0, 102.5, 103.0],
+                    [101.5, 100.0, 100.5, 101.0, 101.5, 102.0, 102.5, 103.0, 103.5, 104.0],
+                ]
             ],
             dtype=main.np.float32,
         )
 
-        x_norm, x_mean, x_scale = main.KronosForecaster._normalize_feature_matrix(x, clip=5.0)
-
-        expected_scale = main.np.std(x, axis=0).astype(main.np.float32) + 1e-5
-        expected_norm = main.np.clip((x - x_mean) / expected_scale, -5.0, 5.0)
+        p10, p50, p90, diagnostics = main.TimesFMForecaster._validate_output_tensors(
+            point_forecast=point,
+            quantile_forecast=quantiles,
+            horizon=2,
+        )
 
-        self.assertTrue(main.np.allclose(x_scale, expected_scale))
-        self.assertTrue(main.np.allclose(x_norm, expected_norm))
+        self.assertTrue(main.np.allclose(p10, [99.0, 100.0]))
+        self.assertTrue(main.np.allclose(p50, point[0]))
+        self.assertTrue(main.np.allclose(p90, [103.0, 104.0]))
+        self.assertEqual(diagnostics["point_shape"], [1, 2])
+        self.assertEqual(diagnostics["quantile_shape"], [1, 2, 10])
+        self.assertTrue(diagnostics["median_matches_point_forecast"])
+        self.assertTrue(diagnostics["quantiles_monotonic"])
 
     def test_forecast_payload_schema_guard_rejects_legacy_blended_payload(self) -> None:
         legacy_payload = {
             "forecast": [{"time": 1, "p10": 1.0, "p50": 1.1, "p90": 1.2}],
             "forecast_candles": [],
-            "display": {"mode": "raw_kronos_ohlc_p50"},
-            "ensemble": {"mode": "kronos_plus_anchor", "confidence": 55.0},
+            "display": {"mode": "raw_legacy_ohlc_p50"},
+            "ensemble": {"mode": "legacy_plus_anchor", "confidence": 55.0},
             "model": {
                 "input_semantics": {
                     "feature_channels": ["open", "high", "low", "close", "volume", "amount"],
@@ -531,60 +836,13 @@ class ApiRegressionTests(unittest.TestCase):
         }
         self.assertFalse(main._forecast_payload_is_current(legacy_payload))
 
-    def test_forecast_payload_schema_guard_accepts_current_ohlc4_input_mode(self) -> None:
-        current_payload = {
-            "forecast": [{"time": 1, "p10": 1.0, "p50": 1.1, "p90": 1.2}],
-            "display": {
-                "mode": "raw_kronos_ohlc4_line",
-                "channels": ["ohlc4"],
-                "output_mode": "single_future_ohlc4_line",
-            },
-            "model": {
-                "input_semantics": {
-                    "feature_channels": ["ohlc4"],
-                    "price_mode": "ohlc4_single_channel",
-                    "base_signal": "ohlc4",
-                    "volume_mode": "omitted",
-                    "amount_mode": "omitted",
-                    "active_forecast_channels": ["ohlc4"],
-                    "adapter_mode": "tokenizer_6ch_to_1ch_ohlc4",
-                },
-                "output_semantics": {
-                    "forecast_channel": "ohlc4",
-                    "forecast_mode": "single_future_ohlc4_line",
-                    "candle_projection": "omitted",
-                }
-            },
-        }
+    def test_forecast_payload_schema_guard_accepts_current_multi_model_payload(self) -> None:
+        current_payload = self._build_current_forecast_payload()
         self.assertTrue(main._forecast_payload_is_current(current_payload))
 
     def test_forecast_payload_schema_guard_rejects_legacy_forecast_candles_field(self) -> None:
-        stale_payload = {
-            "forecast": [{"time": 1, "p10": 1.0, "p50": 1.1, "p90": 1.2}],
-            "forecast_candles": [],
-            "display": {
-                "mode": "raw_kronos_ohlc4_line",
-                "channels": ["ohlc4"],
-                "output_mode": "single_future_ohlc4_line",
-            },
-            "model": {
-                "input_semantics": {
-                    "feature_channels": ["ohlc4"],
-                    "price_mode": "ohlc4_single_channel",
-                    "base_signal": "ohlc4",
-                    "volume_mode": "omitted",
-                    "amount_mode": "omitted",
-                    "active_forecast_channels": ["ohlc4"],
-                    "adapter_mode": "tokenizer_6ch_to_1ch_ohlc4",
-                },
-                "output_semantics": {
-                    "forecast_channel": "ohlc4",
-                    "forecast_mode": "single_future_ohlc4_line",
-                    "candle_projection": "omitted",
-                },
-            },
-        }
-
+        stale_payload = self._build_current_forecast_payload()
+        stale_payload["forecast_candles"] = []
         self.assertFalse(main._forecast_payload_is_current(stale_payload))
 
     def test_finalize_forecast_error_payload_omits_legacy_forecast_candles_field(self) -> None:
@@ -601,6 +859,60 @@ class ApiRegressionTests(unittest.TestCase):
 
         self.assertNotIn("forecast_candles", response)
         self.assertEqual(response["display"]["output_mode"], "single_future_ohlc4_line")
+        self.assertEqual(response["display"]["forecast_reference_field"], "last_ohlc4")
+        self.assertEqual(response["display"]["visual_anchor_field"], "last_close")
+
+    def test_forecast_payload_schema_guard_rejects_missing_reference_fields(self) -> None:
+        stale_payload = self._build_current_forecast_payload()
+        stale_payload["display"] = {
+            "mode": "multi_model_ohlc4_line",
+            "channels": ["ohlc4"],
+            "output_mode": "single_future_ohlc4_line",
+        }
+        self.assertFalse(main._forecast_payload_is_current(stale_payload))
+
+    def test_forecast_payload_schema_guard_rejects_missing_model_selection(self) -> None:
+        stale_payload = self._build_current_forecast_payload()
+        stale_payload.pop("model_selection", None)
+        self.assertFalse(main._forecast_payload_is_current(stale_payload))
+
+    def test_forecast_payload_schema_guard_rejects_missing_forecast_models(self) -> None:
+        stale_payload = self._build_current_forecast_payload()
+        stale_payload.pop("forecast_models", None)
+        self.assertFalse(main._forecast_payload_is_current(stale_payload))
+
+    def test_forecast_payload_schema_guard_rejects_missing_combination_mode(self) -> None:
+        stale_payload = self._build_current_forecast_payload()
+        stale_payload["display"].pop("combination_mode", None)
+        self.assertFalse(main._forecast_payload_is_current(stale_payload))
+
+    def test_forecast_payload_schema_guard_rejects_enabled_model_without_success(self) -> None:
+        stale_payload = self._build_current_forecast_payload()
+        stale_payload["forecast_models"]["kronos"]["success"] = False
+        self.assertFalse(main._forecast_payload_is_current(stale_payload))
+
+    def test_calc_ai_forecast_score_keeps_market_return_and_tracks_model_reference_return(self) -> None:
+        score = main._calc_ai_forecast_score(
+            blended={
+                "p10": [100.0, 101.0],
+                "p50": [101.0, 102.0],
+                "p90": [102.0, 103.0],
+                "confidence": 60.0,
+                "scale": 1.0,
+            },
+            forecast_rows=[],
+            last_close=100.0,
+            indicators={"trend": {}, "atr": {"pct": 1.0}, "rsi": {"value": 50.0}},
+            horizon=2,
+            interval="1h",
+            model_reference_price=101.0,
+        )
+
+        self.assertEqual(score["forecast_return_pct"], 2.0)
+        self.assertAlmostEqual(
+            score["model_reference_return_pct"],
+            round(((102.0 - 101.0) / 101.0) * 100.0, 2),
+        )
 
     def test_synthetic_component_history_reuses_source_cache(self) -> None:
         calls: list[tuple[str, str, str, int]] = []

backend/test_frontend_assets.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+import unittest
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from backend.frontend_assets import (
+    build_frontend_asset_version,
+    register_frontend_assets,
+    resolve_frontend_assets,
+)
+
+
+class FrontendAssetsTests(unittest.TestCase):
+    def _build_frontend_fixture(self, project_root: Path) -> None:
+        frontend_root = project_root / "frontend"
+        frontend_root.mkdir(parents=True, exist_ok=True)
+
+        files: dict[str, str] = {
+            "index.html": "<html><head></head><body>v=__FRONTEND_ASSET_VERSION__</body></html>",
+            "app.js": "console.log('app');",
+            "forecast-models.js": "console.log('forecast-models');",
+            "workspace.js": "console.log('workspace');",
+            "workspace.css": "body { color: #fff; }",
+            "favicon.svg": "<svg xmlns='http://www.w3.org/2000/svg'></svg>",
+        }
+        for file_name, content in files.items():
+            (frontend_root / file_name).write_text(content, encoding="utf-8")
+
+        (frontend_root / "AIBG.png").write_bytes(b"\x89PNG\r\n\x1a\n")
+
+    def test_asset_version_changes_when_forecast_model_registry_changes(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project_root = Path(temp_dir)
+            self._build_frontend_fixture(project_root)
+            assets = resolve_frontend_assets(project_root)
+
+            initial_version = build_frontend_asset_version(
+                assets=assets,
+                app_version="1.0.0",
+                cache_version="v1",
+            )
+
+            assets.forecast_models_js.write_text("console.log('updated');", encoding="utf-8")
+            new_mtime = assets.forecast_models_js.stat().st_mtime + 5
+            os.utime(assets.forecast_models_js, (new_mtime, new_mtime))
+
+            updated_version = build_frontend_asset_version(
+                assets=assets,
+                app_version="1.0.0",
+                cache_version="v1",
+            )
+
+            self.assertNotEqual(initial_version, updated_version)
+
+    def test_register_frontend_assets_serves_forecast_registry_with_no_cache_headers(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project_root = Path(temp_dir)
+            self._build_frontend_fixture(project_root)
+            app = FastAPI()
+            register_frontend_assets(
+                app,
+                project_root=project_root,
+                app_version="1.0.0",
+                cache_version="v1",
+                logger=logging.getLogger("test-frontend-assets"),
+            )
+            client = TestClient(app)
+
+            response = client.get("/forecast-models.js")
+
+            self.assertEqual(response.status_code, 200)
+            self.assertIn("forecast-models", response.text)
+            self.assertEqual(
+                response.headers["Cache-Control"],
+                "no-store, no-cache, must-revalidate, max-age=0",
+            )
+
+    def test_register_frontend_assets_replaces_version_placeholder_in_index(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project_root = Path(temp_dir)
+            self._build_frontend_fixture(project_root)
+            app = FastAPI()
+            register_frontend_assets(
+                app,
+                project_root=project_root,
+                app_version="2.0.0",
+                cache_version="v9",
+                logger=logging.getLogger("test-frontend-assets"),
+            )
+            client = TestClient(app)
+
+            response = client.get("/")
+
+            self.assertEqual(response.status_code, 200)
+            self.assertNotIn("__FRONTEND_ASSET_VERSION__", response.text)
+            self.assertIn("2.0.0-v9-", response.text)
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/test_frontend_static_contract.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+
+class FrontendStaticContractTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.app_js = (Path(__file__).resolve().parent.parent / "frontend" / "app.js").read_text(
+            encoding="utf-8",
+        )
+        cls.index_html = (Path(__file__).resolve().parent.parent / "frontend" / "index.html").read_text(
+            encoding="utf-8",
+        )
+        cls.workspace_js = (Path(__file__).resolve().parent.parent / "frontend" / "workspace.js").read_text(
+            encoding="utf-8",
+        )
+
+    def test_app_js_does_not_use_inline_onclick_handlers(self) -> None:
+        self.assertNotIn('onclick="', self.app_js)
+
+    def test_explorer_interactions_use_data_attributes_and_global_compat_exports(self) -> None:
+        self.assertIn('data-explorer-cat="', self.app_js)
+        self.assertIn('data-symbol="${escapeHtml(s.symbol)}"', self.app_js)
+        self.assertIn("window.selectExplorerCat = selectExplorerCat;", self.app_js)
+        self.assertIn("window.explorerSelectSymbol = explorerSelectSymbol;", self.app_js)
+
+    def test_market_toggle_dom_ref_is_explicit(self) -> None:
+        self.assertIn("const toggleMarketBtn = document.getElementById('toggleMarketBtn');", self.app_js)
+
+    def test_layout_switcher_reconciles_actual_workspace_state_before_noop(self) -> None:
+        self.assertIn("function inferWorkspaceLayoutPreset()", self.app_js)
+        self.assertIn("const currentPreset = syncWorkspaceLayoutPreset();", self.app_js)
+        self.assertIn("const isPresetFullyApplied = (", self.app_js)
+
+    def test_progressive_ai_forecast_contract_is_exposed(self) -> None:
+        self.assertIn(
+            "window.buildCombinedForecastPayloadForPane = buildCombinedForecastPayloadForPane;",
+            self.app_js,
+        )
+        self.assertIn("async fetchForecastModel(symbol, interval, horizon, modelKey, signal)", self.workspace_js)
+        self.assertIn("complete: false", self.workspace_js)
+
+    def test_shared_chart_viewport_contract_is_centralized(self) -> None:
+        self.assertIn("const CHART_RIGHT_OFFSET = 50;", self.app_js)
+        self.assertIn("function buildSharedTimeScaleOptions(overrides = {})", self.app_js)
+        self.assertIn("function getAllOpenChartInstances()", self.app_js)
+        self.assertIn("function zoomAllCharts(direction)", self.app_js)
+        self.assertIn("function panAllCharts(direction)", self.app_js)
+        self.assertIn("function restoreOrFitChartViewport(chartKey, chartInstance, context)", self.app_js)
+        self.assertIn("function registerChartViewportTracking(chartInstance, chartKey, getContext)", self.app_js)
+        self.assertIn("function alignChartViewportToReservedSpace(chartKey, chartInstance, context, options = {})", self.app_js)
+        self.assertIn("function resolveChartRightEdgeAnchor(chartKey)", self.app_js)
+        self.assertIn("const zoomOutBtn = document.getElementById('zoomOutBtn');", self.app_js)
+        self.assertIn("const zoomInBtn = document.getElementById('zoomInBtn');", self.app_js)
+        self.assertIn("const panLeftBtn = document.getElementById('panLeftBtn');", self.app_js)
+        self.assertIn("const panRightBtn = document.getElementById('panRightBtn');", self.app_js)
+        self.assertIn("function setupChartNavigationCluster()", self.app_js)
+        self.assertIn('id="zoomOutBtn"', self.index_html)
+        self.assertIn('id="zoomInBtn"', self.index_html)
+        self.assertIn('id="panLeftBtn"', self.index_html)
+        self.assertIn('id="panRightBtn"', self.index_html)
+        self.assertIn('.chart-nav-cluster', self.index_html)
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/test_kronos_meta_compat.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import unittest
+
+import torch
+
+from backend.kronos_core.model.kronos import (
+    _compat_load_state_dict,
+    _module_has_meta_tensors,
+    _move_module_to_device,
+)
+
+
+class KronosMetaCompatibilityTests(unittest.TestCase):
+    def test_meta_module_detection(self) -> None:
+        meta_linear = torch.nn.Linear(2, 2, device="meta")
+        self.assertTrue(_module_has_meta_tensors(meta_linear))
+
+    def test_compat_load_state_dict_assigns_into_meta_parameters(self) -> None:
+        source = torch.nn.Linear(2, 2)
+        meta_linear = torch.nn.Linear(2, 2, device="meta")
+
+        _compat_load_state_dict(meta_linear, source.state_dict(), strict=True)
+
+        self.assertFalse(_module_has_meta_tensors(meta_linear))
+        self.assertTrue(torch.allclose(meta_linear.weight.detach(), source.weight.detach()))
+        self.assertTrue(torch.allclose(meta_linear.bias.detach(), source.bias.detach()))
+
+    def test_move_module_to_device_handles_meta_modules(self) -> None:
+        meta_linear = torch.nn.Linear(2, 2, device="meta")
+
+        moved = _move_module_to_device(meta_linear, "cpu")
+
+        self.assertFalse(_module_has_meta_tensors(moved))
+        self.assertEqual(str(next(moved.parameters()).device), "cpu")
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/test_launcher.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import threading
+import unittest
+from unittest.mock import Mock, patch
+
+from backend import launcher
+
+
+class _FakeServer:
+    def __init__(self, *, started: bool = False) -> None:
+        self.started = started
+
+
+class LauncherTests(unittest.TestCase):
+    def test_wait_for_server_start_returns_true_when_uvicorn_started(self) -> None:
+        server = _FakeServer(started=True)
+        finished = threading.Event()
+        self.assertTrue(launcher.wait_for_server_start(server, finished))
+
+    def test_wait_for_server_start_returns_false_when_startup_finishes_early(self) -> None:
+        server = _FakeServer(started=False)
+        finished = threading.Event()
+        finished.set()
+        with patch.object(launcher, "SERVER_READY_TIMEOUT_SECONDS", 0.3):
+            with patch.object(launcher, "SERVER_READY_POLL_INTERVAL_SECONDS", 0.05):
+                self.assertFalse(launcher.wait_for_server_start(server, finished))
+
+    def test_open_browser_skips_when_backend_never_starts(self) -> None:
+        browser_open = Mock()
+        server = _FakeServer(started=False)
+        finished = threading.Event()
+
+        with patch.object(launcher, "wait_for_server_start", return_value=False):
+            with patch.object(launcher.webbrowser, "open", browser_open):
+                launcher.open_browser("http://127.0.0.1:8000", server, finished)
+
+        browser_open.assert_not_called()
+
+    def test_resolve_server_port_delegates_to_shared_runtime(self) -> None:
+        with patch.object(launcher.server_runtime, "resolve_server_port", return_value=8123) as resolver:
+            self.assertEqual(launcher.resolve_server_port(), 8123)
+        resolver.assert_called_once_with(launcher.DEFAULT_HOST, logger=launcher.logger)
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/test_runtime_utils.py

@@ -1,11 +1,15 @@
 from __future__ import annotations
 
 import unittest
+from pathlib import Path
 
 import numpy as np
+import socket
 
 from backend.runtime_utils import (
+    can_bind_tcp_port,
     clone_cache_payload,
+    find_free_tcp_port,
     make_json_compatible,
     parse_cors_origins,
     resolve_runtime_paths,
@@ -13,6 +17,10 @@ from backend.runtime_utils import (
 
 
 class RuntimeUtilsTests(unittest.TestCase):
+    @staticmethod
+    def _module_file() -> str:
+        return str(Path(__file__).resolve().with_name("main.py"))
+
     def test_parse_cors_origins_splits_and_trims(self) -> None:
         result = parse_cors_origins(" https://a.com,https://b.com , , ")
         self.assertEqual(result, ["https://a.com", "https://b.com"])
@@ -20,6 +28,20 @@ class RuntimeUtilsTests(unittest.TestCase):
     def test_parse_cors_origins_defaults_to_wildcard(self) -> None:
         self.assertEqual(parse_cors_origins("   "), ["*"])
 
+    def test_can_bind_tcp_port_detects_busy_listener(self) -> None:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server_socket:
+            server_socket.bind(("127.0.0.1", 0))
+            server_socket.listen(1)
+            busy_port = int(server_socket.getsockname()[1])
+            self.assertFalse(can_bind_tcp_port("127.0.0.1", busy_port))
+
+        self.assertTrue(can_bind_tcp_port("127.0.0.1", busy_port))
+
+    def test_find_free_tcp_port_returns_bindable_port(self) -> None:
+        port = find_free_tcp_port("127.0.0.1")
+        self.assertGreater(port, 0)
+        self.assertTrue(can_bind_tcp_port("127.0.0.1", port))
+
     def test_clone_cache_payload_returns_independent_copy(self) -> None:
         original = {"nested": {"value": 1}, "items": [1, 2, 3]}
         cloned = clone_cache_payload(original)
@@ -45,17 +67,20 @@ class RuntimeUtilsTests(unittest.TestCase):
         self.assertEqual(result["series"], [1.0, 2.0])
 
     def test_resolve_runtime_paths_for_dev_mode(self) -> None:
+        module_file = self._module_file()
+        expected_current_dir = str(Path(module_file).resolve().parent)
+        expected_project_root = str(Path(module_file).resolve().parent.parent)
         paths = resolve_runtime_paths(
-            module_file=r"D:\Python\Kronos_Platform_V1\backend\main.py",
+            module_file=module_file,
             is_frozen=False,
             bundle_dir=r"D:\Bundle",
         )
-        self.assertEqual(paths.current_dir, r"D:\Python\Kronos_Platform_V1\backend")
-        self.assertEqual(paths.project_root, r"D:\Python\Kronos_Platform_V1")
+        self.assertEqual(paths.current_dir, expected_current_dir)
+        self.assertEqual(paths.project_root, expected_project_root)
 
     def test_resolve_runtime_paths_for_frozen_mode(self) -> None:
         paths = resolve_runtime_paths(
-            module_file=r"D:\Python\Kronos_Platform_V1\backend\main.py",
+            module_file=self._module_file(),
             is_frozen=True,
             bundle_dir=r"D:\Bundle",
         )

backend/test_server_runtime.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import sys
+import tempfile
+import textwrap
+import unittest
+from pathlib import Path
+
+from backend import server_runtime
+
+
+class _FakeLogger:
+    def __init__(self) -> None:
+        self.warnings: list[tuple[str, tuple[object, ...]]] = []
+
+    def warning(self, msg: str, *args: object, **kwargs: object) -> None:
+        self.warnings.append((msg, args))
+
+
+class ServerRuntimeTests(unittest.TestCase):
+    def test_bootstrap_runtime_port_sets_huggingface_default(self) -> None:
+        env = {"SPACE_ID": "demo-space"}
+
+        server_runtime.bootstrap_runtime_port(env, huggingface_port=7860)
+
+        self.assertEqual(env["PORT"], "7860")
+
+    def test_bootstrap_runtime_port_keeps_existing_port(self) -> None:
+        env = {"SPACE_HOST": "space.example", "PORT": "9000"}
+
+        server_runtime.bootstrap_runtime_port(env, huggingface_port=7860)
+
+        self.assertEqual(env["PORT"], "9000")
+
+    def test_resolve_server_port_keeps_configured_port_when_available(self) -> None:
+        env = {"PORT": "8000"}
+        port = server_runtime.resolve_server_port(
+            "127.0.0.1",
+            env=env,
+            port_checker=lambda host, value: host == "127.0.0.1" and value == 8000,
+            free_port_finder=lambda host: 8123,
+        )
+        self.assertEqual(port, 8000)
+        self.assertEqual(env["PORT"], "8000")
+
+    def test_resolve_server_port_falls_back_when_configured_port_is_busy(self) -> None:
+        env = {"PORT": "8000"}
+        logger = _FakeLogger()
+
+        port = server_runtime.resolve_server_port(
+            "127.0.0.1",
+            env=env,
+            logger=logger,
+            port_checker=lambda host, value: False,
+            free_port_finder=lambda host: 8123,
+        )
+
+        self.assertEqual(port, 8123)
+        self.assertEqual(env["PORT"], "8123")
+        self.assertEqual(len(logger.warnings), 1)
+
+    def test_resolve_server_port_uses_huggingface_default_when_missing(self) -> None:
+        env = {"SPACE_ID": "demo-space"}
+
+        port = server_runtime.resolve_server_port(
+            "0.0.0.0",
+            env=env,
+            port_checker=lambda host, value: False,
+            free_port_finder=lambda host: 8123,
+        )
+
+        self.assertEqual(port, 7860)
+        self.assertEqual(env["PORT"], "7860")
+
+    def test_load_runtime_env_returns_false_for_missing_file(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            env_file = Path(temp_dir) / "missing-aiforecast.env"
+            self.assertFalse(server_runtime.load_runtime_env(env_file))
+
+    def test_load_fastapi_app_imports_requested_module_attribute(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project_root = Path(temp_dir)
+            module_name = "temp_runtime_app_module"
+            module_path = project_root / f"{module_name}.py"
+            module_path.write_text(
+                textwrap.dedent(
+                    """
+                    app = {"name": "demo-app"}
+                    """
+                ).strip(),
+                encoding="utf-8",
+            )
+
+            try:
+                app = server_runtime.load_fastapi_app(
+                    project_root,
+                    module_name=module_name,
+                    attr_name="app",
+                )
+                self.assertEqual(app, {"name": "demo-app"})
+                self.assertIn(str(project_root), sys.path)
+            finally:
+                sys.modules.pop(module_name, None)
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/test_startup_utils.py

@@ -7,7 +7,7 @@ from backend.startup_utils import (
     build_source_selftest_urls,
     clear_stale_ip_limits,
     run_source_selftest,
-    warmup_kronos,
+    warmup_timesfm,
 )
 
 
@@ -92,14 +92,14 @@ class StartupUtilsTests(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(startup_sources["broken"]["error"], "network down")
         self.assertEqual(startup_sources["binance"]["checked_at"], "2026-04-26T00:00:00+00:00")
 
-    async def test_warmup_kronos_updates_success_state(self) -> None:
+    async def test_warmup_timesfm_updates_success_state(self) -> None:
         logger = _FakeLogger()
         state = {"warming": False, "last_error": "old", "loaded": False, "device": "not_loaded"}
         forecaster = _FakeForecaster()
 
-        await warmup_kronos(
+        await warmup_timesfm(
             forecaster=forecaster,
-            startup_kronos_state=state,
+            startup_timesfm_state=state,
             logger=logger,
         )
 
@@ -108,14 +108,14 @@ class StartupUtilsTests(unittest.IsolatedAsyncioTestCase):
         self.assertTrue(state["loaded"])
         self.assertEqual(state["device"], "cpu")
 
-    async def test_warmup_kronos_tracks_failure_state(self) -> None:
+    async def test_warmup_timesfm_tracks_failure_state(self) -> None:
         logger = _FakeLogger()
         state = {"warming": False, "last_error": None, "loaded": True, "device": "not_loaded"}
         forecaster = _FakeForecaster(should_fail=True)
 
-        await warmup_kronos(
+        await warmup_timesfm(
             forecaster=forecaster,
-            startup_kronos_state=state,
+            startup_timesfm_state=state,
             logger=logger,
         )
 

backend/test_timesfm_provider.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import logging
+import types
+import unittest
+from unittest.mock import patch
+
+from backend.forecasting.providers import timesfm_provider
+
+
+class _FakeParameter:
+    def __init__(self, *, is_meta: bool) -> None:
+        self.is_meta = is_meta
+
+
+class _FakeTimesfmModel:
+    def __init__(self, *, is_meta: bool) -> None:
+        self.device = "cpu"
+        self._parameters = [_FakeParameter(is_meta=is_meta)]
+        self.calls: list[tuple[object, ...]] = []
+
+    def parameters(self):  # type: ignore[no-untyped-def]
+        return iter(self._parameters)
+
+    def load_state_dict(self, tensors, strict: bool = True, assign: bool = False) -> None:
+        self.calls.append(("load_state_dict", tensors, strict, assign))
+
+    def to_empty(self, *, device: str) -> None:
+        self.calls.append(("to_empty", device))
+
+    def to(self, device: str) -> None:
+        self.calls.append(("to", device))
+
+    def eval(self) -> None:
+        self.calls.append(("eval",))
+
+
+class TimesfmProviderCompatibilityTests(unittest.TestCase):
+    def setUp(self) -> None:
+        timesfm_provider._TIMESFM_RUNTIME_PATCHED = False
+
+    def test_runtime_patch_enables_assign_for_meta_models(self) -> None:
+        fake_internal_module = types.SimpleNamespace(
+            load_file=lambda path: {"path": path},
+            logging=logging,
+            TimesFM_2p5_200M_torch_module=type("FakeModelModule", (), {}),
+        )
+
+        with patch.object(timesfm_provider, "timesfm", object()), patch.object(
+            timesfm_provider.importlib,
+            "import_module",
+            return_value=fake_internal_module,
+        ):
+            timesfm_provider._patch_timesfm_runtime_compatibility(logging.getLogger("test"))
+
+        patched_cls = fake_internal_module.TimesFM_2p5_200M_torch_module
+        fake_model = _FakeTimesfmModel(is_meta=True)
+        patched_cls.load_checkpoint(fake_model, "checkpoint.safetensors", torch_compile=False)
+
+        self.assertIn(("load_state_dict", {"path": "checkpoint.safetensors"}, True, True), fake_model.calls)
+        self.assertIn(("to", "cpu"), fake_model.calls)
+        self.assertIn(("eval",), fake_model.calls)
+        self.assertTrue(getattr(patched_cls, "_aiforecast_meta_patch"))
+
+    def test_runtime_patch_keeps_standard_loading_for_non_meta_models(self) -> None:
+        fake_internal_module = types.SimpleNamespace(
+            load_file=lambda path: {"path": path},
+            logging=logging,
+            TimesFM_2p5_200M_torch_module=type("FakeModelModule", (), {}),
+        )
+
+        with patch.object(timesfm_provider, "timesfm", object()), patch.object(
+            timesfm_provider.importlib,
+            "import_module",
+            return_value=fake_internal_module,
+        ):
+            timesfm_provider._patch_timesfm_runtime_compatibility(logging.getLogger("test"))
+
+        patched_cls = fake_internal_module.TimesFM_2p5_200M_torch_module
+        fake_model = _FakeTimesfmModel(is_meta=False)
+        patched_cls.load_checkpoint(fake_model, "checkpoint.safetensors", torch_compile=False)
+
+        self.assertIn(("load_state_dict", {"path": "checkpoint.safetensors"}, True, False), fake_model.calls)
+        self.assertNotIn(("to_empty", "cpu"), fake_model.calls)
+
+
+if __name__ == "__main__":
+    unittest.main()

frontend/forecast-models.js

@@ -0,0 +1,82 @@
+(() => {
+  const lineStyleSolid = window.LightweightCharts?.LineStyle?.Solid ?? 0;
+  const modelOrder = Object.freeze(['kronos', 'timesfm', 'chronos']);
+  const defaultLineWidth = 1;
+  const modelLabels = Object.freeze({
+    kronos: 'Kronos',
+    timesfm: 'TimesFM',
+    chronos: 'Chronos',
+  });
+  const defaultSelection = Object.freeze(
+    Object.fromEntries(modelOrder.map((modelKey) => [modelKey, true]))
+  );
+  const modelTonePalette = Object.freeze({
+    kronos: Object.freeze({
+      up: '#2563eb',
+      flat: '#c2410c',
+      down: '#b91c1c',
+    }),
+    timesfm: Object.freeze({
+      up: '#16a34a',
+      flat: '#eab308',
+      down: '#ef4444',
+    }),
+    chronos: Object.freeze({
+      up: '#166534',
+      flat: '#a39b6b',
+      down: '#be185d',
+    }),
+  });
+  const modelSeriesStyle = Object.freeze(
+    Object.fromEntries(
+      modelOrder.map((modelKey) => [
+        modelKey,
+        Object.freeze({
+          lineWidth: defaultLineWidth,
+          lineStyle: lineStyleSolid,
+        }),
+      ])
+    )
+  );
+
+  function normalizeSelection(selection = null) {
+    const requested = selection && typeof selection === 'object' ? selection : defaultSelection;
+    const normalized = Object.fromEntries(
+      modelOrder.map((modelKey) => [
+        modelKey,
+        Boolean(
+          Object.prototype.hasOwnProperty.call(requested, modelKey)
+            ? requested[modelKey]
+            : defaultSelection[modelKey]
+        ),
+      ])
+    );
+    if (!Object.values(normalized).some(Boolean)) {
+      normalized[modelOrder[0]] = true;
+    }
+    return normalized;
+  }
+
+  function signature(selection = null) {
+    const normalized = normalizeSelection(selection);
+    return modelOrder
+      .map((modelKey) => `${modelKey[0]}${normalized[modelKey] ? 1 : 0}`)
+      .join('');
+  }
+
+  function createEmptyLines() {
+    return Object.fromEntries(modelOrder.map((modelKey) => [modelKey, []]));
+  }
+
+  window.AIFORECAST_MODEL_CONFIG = Object.freeze({
+    modelOrder,
+    modelLabels,
+    defaultSelection,
+    defaultLineWidth,
+    modelTonePalette,
+    modelSeriesStyle,
+    normalizeSelection,
+    signature,
+    createEmptyLines,
+  });
+})();

frontend/workspace.css

@@ -1,5 +1,5 @@
 /* ═══════════════════════════════════════════════════════
-   KRONOS MULTI-CHART WORKSPACE — CSS
+   AI FORECAST MULTI-CHART WORKSPACE — CSS
    ═══════════════════════════════════════════════════════ */
 
 /* ── Layout Switcher (ultra-compact pill) ──────────── */
@@ -225,6 +225,48 @@
   bottom: 0;
 }
 
+.pane-forecast-hover {
+  position: absolute;
+  top: 34px;
+  right: 8px;
+  z-index: 11;
+  min-height: 22px;
+  padding: 0 9px;
+  border-radius: 999px;
+  border: 1px solid rgba(102, 163, 255, 0.28);
+  background: rgba(7, 18, 38, 0.84);
+  color: rgba(235, 244, 255, 0.94);
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  font-family: var(--ff-display);
+  font-size: 0.56rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  box-shadow: 0 10px 28px rgba(2, 8, 23, 0.26);
+  backdrop-filter: blur(10px);
+  -webkit-backdrop-filter: blur(10px);
+  pointer-events: none;
+  opacity: 1;
+  transform: translateY(0);
+  transition: opacity 0.16s ease, transform 0.16s ease, border-color 0.16s ease;
+}
+
+.pane-forecast-hover.hidden {
+  opacity: 0;
+  transform: translateY(-4px);
+}
+
+.pane-forecast-hover::before {
+  content: '';
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: currentColor;
+  box-shadow: 0 0 0 3px rgba(102, 163, 255, 0.18);
+}
+
 /* ── Pane Loader ───────────────────────────────────── */
 .pane-loader {
   position: absolute;

frontend/workspace.js

@@ -1,6 +1,6 @@
 /**
  * ═══════════════════════════════════════════════════════
- *  KRONOS MULTI-CHART WORKSPACE ENGINE (V1)
+ *  AI FORECAST MULTI-CHART WORKSPACE ENGINE (V1)
  *  Provides: PaneState, ChartPaneController, StreamManager,
  *            DataCoordinator, WorkspaceController
  * ═══════════════════════════════════════════════════════
@@ -12,12 +12,36 @@ const CHART_HISTORY_LIMIT_WS = 500;
 const MAX_CONCURRENT_FETCHES = 4;
 const WS_RECONNECT_DELAY = 5000;
 const LAYOUT_PRESETS = [1, 2, 4, 8];
+const MODEL_CONFIG = window.AIFORECAST_MODEL_CONFIG;
+if (!MODEL_CONFIG) {
+  throw new Error('AIFORECAST_MODEL_CONFIG is missing');
+}
 const LAYOUT_GRID_MAP = {
   1: { cols: 1, rows: 1 },
   2: { cols: 2, rows: 1 },
   4: { cols: 2, rows: 2 },
   8: { cols: 4, rows: 2 },
 };
+const FORECAST_MODEL_ORDER = MODEL_CONFIG.modelOrder;
+const DEFAULT_AI_MODEL_SELECTION = MODEL_CONFIG.defaultSelection;
+
+function normalizeAiModelSelection(selection = null) {
+  return MODEL_CONFIG.normalizeSelection(selection);
+}
+
+function getAiModelSignature(selection = null) {
+  return MODEL_CONFIG.signature(selection);
+}
+
+function buildWebSocketUrl(apiBase, path) {
+  const fallbackOrigin = (
+    window.location.origin &&
+    window.location.origin !== 'null'
+  ) ? window.location.origin : 'http://127.0.0.1';
+  const resolvedUrl = new URL(path, apiBase || fallbackOrigin);
+  resolvedUrl.protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  return resolvedUrl.toString();
+}
 
 /* ══════════════════════════════════════════════════════
    PaneState — Per-pane data container
@@ -29,12 +53,22 @@ class PaneState {
     this.interval = interval;
     this.indicatorMode = 'none';
     this.horizon = 10;
+    this.aiModels = normalizeAiModelSelection();
 
     // Chart instances (set by ChartPaneController)
     this.chartInstance = null;
     this.candleSeries = null;
-    this.forecastSeries = { candles: null, p50: null, p10: null, p90: null, segments: [] };
+    this.forecastSeries = {
+      candles: null,
+      reserve: null,
+      p50: null,
+      p10: null,
+      p90: null,
+      segments: [],
+      models: Object.fromEntries(FORECAST_MODEL_ORDER.map((modelKey) => [modelKey, null])),
+    };
     this.indicatorSeries = { bbUpper: null, bbMid: null, bbLower: null, rsi: null };
+    this.forecastHoverEl = null;
 
     // Network
     this.fetchController = null;
@@ -45,10 +79,23 @@ class PaneState {
 
     // Data
     this.lastCandleData = null;
-    this.lastAnalysis = { payload: null, symbol: null, interval: null };
+    this.lastAnalysis = {
+      payload: null,
+      symbol: null,
+      interval: null,
+      horizon: null,
+      modelSignature: null,
+      complete: false,
+    };
+    this.analysisPayloadCache = {};
+    this.partialModelPayloads = {};
+    this.analysisProgress = { requested: [], ready: [], pending: [], failed: [] };
+    this.cachedForecastModelLines = MODEL_CONFIG.createEmptyLines();
     this.chartContext = { symbol: null, interval: null };
-    this.forecastContext = { symbol: null, interval: null, ready: false };
+    this.forecastContext = { symbol: null, interval: null, horizon: null, modelSignature: null, ready: false };
     this.priceFormat = { precision: 2, minMove: 0.01 };
+    this.historicalBarCount = 0;
+    this.loadedFutureBars = 0;
 
     // UI
     this.loading = false;
@@ -70,8 +117,11 @@ class PaneState {
     return Boolean(
       this.lastAnalysis &&
       this.lastAnalysis.payload &&
+      this.lastAnalysis.complete === true &&
       this.lastAnalysis.symbol === this.symbol &&
-      this.lastAnalysis.interval === this.interval
+      this.lastAnalysis.interval === this.interval &&
+      this.lastAnalysis.horizon === this.horizon &&
+      this.lastAnalysis.modelSignature === this.getAiModelSignature()
     );
   }
 
@@ -80,17 +130,34 @@ class PaneState {
       this.forecastContext &&
       this.forecastContext.ready &&
       this.forecastContext.symbol === this.symbol &&
-      this.forecastContext.interval === this.interval
+      this.forecastContext.interval === this.interval &&
+      this.forecastContext.horizon === this.horizon &&
+      this.forecastContext.modelSignature === this.getAiModelSignature()
     );
   }
 
+  getAiModelSelection() {
+    return normalizeAiModelSelection(this.aiModels);
+  }
+
+  getAiModelSignature() {
+    return getAiModelSignature(this.aiModels);
+  }
+
   
   async fetchAI(options = {}) {
     const horizon = this.horizon || 24;
     const requestSymbol = this.symbol;
     const requestInterval = this.interval;
     const requestHorizon = horizon;
-    const requestKey = `${requestSymbol}|${requestInterval}|${requestHorizon}`;
+    const requestModels = this.getAiModelSelection();
+    const requestModelSignature = getAiModelSignature(requestModels);
+    const requestKey = `${requestSymbol}|${requestInterval}|${requestHorizon}|${requestModelSignature}`;
+    const enabledModelKeys = FORECAST_MODEL_ORDER.filter((modelKey) => requestModels[modelKey]);
+
+    if (!options.force && this.hasMatchingAnalysis()) {
+      return this.lastAnalysis.payload;
+    }
 
     if (!options.force && this.analysisRequestPromise && this.analysisRequestKey === requestKey) {
       return this.analysisRequestPromise;
@@ -104,121 +171,165 @@ class PaneState {
       this.analysisFetchController.abort();
     }
 
-    if (typeof window.clearPaneForecastCandlesOnly === 'function') {
-      window.clearPaneForecastCandlesOnly(this);
-    } else if (this.forecastSeries?.candles?.setData) {
-      this.forecastSeries.candles.setData([]);
-      if (this.forecastSeries.candles.applyOptions) {
-        this.forecastSeries.candles.applyOptions({ visible: false });
+    if (!options.preserveForecastVisuals) {
+      if (typeof window.clearPaneForecastCandlesOnly === 'function') {
+        window.clearPaneForecastCandlesOnly(this);
+      } else if (this.forecastSeries?.candles?.setData) {
+        this.forecastSeries.candles.setData([]);
+        if (this.forecastSeries.candles.applyOptions) {
+          this.forecastSeries.candles.applyOptions({ visible: false });
+        }
       }
     }
 
     const controller = new AbortController();
     this.analysisFetchController = controller;
     this.analysisRequestKey = requestKey;
+    this.error = null;
+    this.partialModelPayloads = {};
+    this.analysisProgress = {
+      requested: [...enabledModelKeys],
+      ready: [],
+      pending: [...enabledModelKeys],
+      failed: [],
+    };
+    this.lastAnalysis = {
+      payload: null,
+      symbol: requestSymbol,
+      interval: requestInterval,
+      horizon: requestHorizon,
+      modelSignature: requestModelSignature,
+      complete: false,
+    };
+    if (typeof window.renderPaneAnalysisUI === 'function') {
+      window.renderPaneAnalysisUI(this);
+    }
 
-    // Show loading in mini gauges
     const shouldRenderPaneGauges = !(window.Workspace?.layoutPreset === 1 && this.paneId === 'pane-0');
     if (this.gaugesEl && shouldRenderPaneGauges && !this.hasMatchingAnalysis()) {
       this.gaugesEl.innerHTML = '<div class="loader-ring" style="width:16px;height:16px;border:2px solid rgba(40,80,140,0.15);border-top-color:var(--accent);animation:spin 0.8s linear infinite;border-radius:50%;"></div>';
     }
 
     const requestPromise = (async () => {
-      try {
-        const fData = await DataCoordinator.fetchForecast(requestSymbol, requestInterval, requestHorizon, controller.signal);
-        if (controller.signal.aborted) return null;
-        if (
-          this.symbol !== requestSymbol
-          || this.interval !== requestInterval
-          || (this.horizon || 24) !== requestHorizon
-        ) {
+      const successfulPayloads = {};
+      const failedModels = [];
+      const removePendingModel = (modelKey) => {
+        this.analysisProgress.pending = this.analysisProgress.pending.filter((key) => key !== modelKey);
+      };
+      const isRequestStale = () => (
+        controller.signal.aborted
+        || this.symbol !== requestSymbol
+        || this.interval !== requestInterval
+        || (this.horizon || 24) !== requestHorizon
+        || this.getAiModelSignature() !== requestModelSignature
+      );
+      const applyProgressivePayload = (isComplete = false) => {
+        if (typeof window.buildCombinedForecastPayloadForPane !== 'function') {
           return null;
         }
-        
-        const hasAnalysis = Boolean(fData?.analysis);
-        if (hasAnalysis) {
-          this.lastAnalysis = { payload: fData, symbol: requestSymbol, interval: requestInterval };
+        const payload = window.buildCombinedForecastPayloadForPane(
+          requestModels,
+          successfulPayloads,
+          {
+            pending: this.analysisProgress.pending,
+            failed: failedModels,
+          },
+        );
+        if (!payload || typeof window.applyForecastPayloadToPane !== 'function') {
+          return payload;
         }
-        
-        const forecastPoints = Array.isArray(fData.forecast) ? fData.forecast : [];
-        if (this.lastCandleData && this.forecastSeries?.p50) {
-          const fallbackActualPoint = {
-            time: this.lastCandleData.time,
-            value: (
-              Number(this.lastCandleData.open ?? 0)
-              + Number(this.lastCandleData.high ?? 0)
-              + Number(this.lastCandleData.low ?? 0)
-              + Number(this.lastCandleData.close ?? 0)
-            ) / 4,
-          };
-          const forecastLine = typeof window.buildForecastLineFromRows === 'function'
-            ? window.buildForecastLineFromRows(forecastPoints, fallbackActualPoint)
-            : [fallbackActualPoint, ...forecastPoints
-              .filter(d => d && d.time !== undefined && d.p50 !== undefined && d.time !== this.lastCandleData.time)
-              .map(d => ({ time: d.time, value: d.p50 }))];
-          const hasForecast = forecastLine.length > 1;
-
-          if (hasForecast) {
-            if (typeof window.renderPaneForecastVisuals === 'function') {
-              window.renderPaneForecastVisuals(this, forecastLine);
-            } else {
-              if (this.forecastSeries.candles?.setData) {
-                this.forecastSeries.candles.setData([]);
-              }
-              if (this.forecastSeries.p10?.setData) {
-                this.forecastSeries.p10.setData([]);
-              }
-              if (this.forecastSeries.p90?.setData) {
-                this.forecastSeries.p90.setData([]);
-              }
-              this.forecastSeries.p50.setData(forecastLine);
+        window.applyForecastPayloadToPane(
+          this,
+          payload,
+          {
+            symbol: requestSymbol,
+            interval: requestInterval,
+            horizon: requestHorizon,
+            models: requestModels,
+            modelSignature: requestModelSignature,
+            complete: isComplete,
+          },
+        );
+        return payload;
+      };
+
+      try {
+        const modelResults = await Promise.allSettled(
+          enabledModelKeys.map(async (modelKey) => {
+            const modelPayload = await DataCoordinator.fetchForecastModel(
+              requestSymbol,
+              requestInterval,
+              requestHorizon,
+              modelKey,
+              controller.signal,
+            );
+            if (isRequestStale()) {
+              return null;
             }
-            this.forecastContext = { symbol: requestSymbol, interval: requestInterval, ready: true };
-          }
-        }
+            successfulPayloads[modelKey] = modelPayload;
+            this.partialModelPayloads = { ...successfulPayloads };
+            if (!this.analysisProgress.ready.includes(modelKey)) {
+              this.analysisProgress.ready = [...this.analysisProgress.ready, modelKey];
+            }
+            removePendingModel(modelKey);
+            return applyProgressivePayload(false);
+          }),
+        );
 
-        if (typeof window.renderPaneAnalysisUI === 'function') {
-          window.renderPaneAnalysisUI(this);
+        if (isRequestStale()) {
+          return null;
         }
 
-        if (
-          hasAnalysis &&
-          typeof window.Workspace !== 'undefined' &&
-          window.Workspace?.activePaneId === this.paneId &&
-          typeof window.renderCompactGauges === 'function'
-        ) {
-          window.renderCompactGauges(this.symbol, this.interval, fData);
+        modelResults.forEach((result, index) => {
+          const modelKey = enabledModelKeys[index];
+          if (result.status === 'fulfilled') {
+            return;
+          }
+          if (result.reason?.name === 'AbortError') {
+            return;
+          }
+          failedModels.push(modelKey);
+          removePendingModel(modelKey);
+          console.error(`[Pane ${this.paneId}] ${modelKey} forecast error:`, result.reason);
+        });
+
+        this.analysisProgress.failed = [...failedModels];
+        const finalPayload = applyProgressivePayload(
+          failedModels.length === 0
+          && this.analysisProgress.ready.length === enabledModelKeys.length,
+        );
+
+        if (!this.analysisProgress.ready.length || !finalPayload) {
+          const failureMessage = failedModels.length
+            ? `Khong co AI model nao tra ket qua: ${failedModels.join(', ')}`
+            : 'Khong co AI model nao tra ket qua';
+          throw new Error(failureMessage);
         }
 
-        if (
-          hasAnalysis &&
-          this.analysisOpen &&
-          typeof window.renderAnalysisPanel === 'function' &&
-          typeof document !== 'undefined'
-        ) {
-          const analysisPanel = document.getElementById('analysisPanel');
-          if (analysisPanel?.classList.contains('active')) {
-            window.renderAnalysisPanel(this.symbol, this.interval, fData);
-            if (typeof window.updateDashboardScale === 'function') {
-              setTimeout(window.updateDashboardScale, 10);
-            }
+        if (failedModels.length) {
+          this.error = `Dang thieu du lieu: ${failedModels.join(', ')}`;
+          if (!this.analysisRetryTimer) {
+            this.analysisRetryTimer = setTimeout(() => {
+              this.analysisRetryTimer = null;
+              this.fetchAI({ force: true, preserveForecastVisuals: true });
+            }, 15000);
           }
         }
 
-        return fData;
+        return finalPayload;
       } catch (e) {
         if (e.name === 'AbortError') return null;
         console.error(`[Pane ${this.paneId}] AI fetch error:`, e);
+        this.error = e.message || String(e);
         if (typeof window.renderPaneAnalysisUI === 'function') {
           window.renderPaneAnalysisUI(this);
         }
-        
-        // Retry
+
         this.analysisRetryTimer = setTimeout(() => {
           this.analysisRetryTimer = null;
           this.fetchAI({ force: true });
         }, 15000);
-        
+
         return null;
       } finally {
         if (this.analysisFetchController === controller) {
@@ -274,6 +385,7 @@ class PaneState {
       interval: this.interval,
       indicator: this.indicatorMode,
       horizon: this.horizon,
+      aiModels: this.getAiModelSelection(),
     };
   }
 }
@@ -308,8 +420,10 @@ const StreamManager = {
     }
 
     const apiBase = window.__AIFORECAST_API_BASE || '';
-    const wsProtocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-    const wsUrl = `${apiBase.replace(/^https?:\/\//, wsProtocol)}/ws/price/${symbol}?interval=${encodeURIComponent(interval)}`;
+    const wsUrl = buildWebSocketUrl(
+      apiBase,
+      `/ws/price/${symbol}?interval=${encodeURIComponent(interval)}`,
+    );
     console.log(`[StreamManager] New WS: ${wsUrl} (pane ${paneId})`);
 
     const ws = new WebSocket(wsUrl);
@@ -451,11 +565,20 @@ const DataCoordinator = {
     );
   },
 
-  async fetchForecast(symbol, interval, horizon, signal) {
+  async fetchForecast(symbol, interval, horizon, aiModels, signal) {
+    const normalizedModels = normalizeAiModelSelection(aiModels);
     return this.fetch(
-      `/api/forecast/${encodeURIComponent(symbol)}?interval=${interval}&horizon=${horizon}`,
+      `/api/forecast/${encodeURIComponent(symbol)}?interval=${interval}&horizon=${horizon}&use_kronos=${normalizedModels.kronos}&use_timesfm=${normalizedModels.timesfm}&use_chronos=${normalizedModels.chronos}`,
       signal
     );
+  },
+
+  async fetchForecastModel(symbol, interval, horizon, modelKey, signal) {
+    const selection = FORECAST_MODEL_ORDER.reduce((accumulator, key) => {
+      accumulator[key] = key === modelKey;
+      return accumulator;
+    }, {});
+    return this.fetchForecast(symbol, interval, horizon, selection, signal);
   }
 };
 
@@ -601,7 +724,7 @@ const Workspace = {
   /* ── Persistence ───────────────────────────── */
   save() {
     const data = {
-      version: 1,
+      version: 2,
       layoutPreset: this.layoutPreset,
       activePaneId: this.activePaneId,
       panes: Array.from(this.panes.values()).map(p => p.toJSON()),
@@ -616,7 +739,7 @@ const Workspace = {
       const raw = localStorage.getItem(WORKSPACE_STORAGE_KEY);
       if (!raw) return null;
       const data = JSON.parse(raw);
-      if (!data || data.version !== 1) return null;
+      if (!data || ![1, 2].includes(data.version)) return null;
       return data;
     } catch (_) {
       return null;
@@ -762,4 +885,8 @@ Workspace.setActivePane = function setActivePaneOverride(id) {
       window.renderPaneAnalysisUI(pane);
     }
   });
+
+  if (prevId !== id && typeof this.save === 'function') {
+    this.save();
+  }
 };

requirements.txt

@@ -9,8 +9,12 @@ torch==2.11.0
 aiofiles==25.1.0
 pytz==2026.1.post1
 huggingface_hub==0.33.1
+einops==0.8.1
 matplotlib==3.9.3
 tqdm==4.67.1
 safetensors==0.6.2
 python-dotenv==1.1.0
 timesfm[torch]>=2.0.0
+transformers>=4.41,<5
+accelerate>=0.34,<2
+scikit-learn>=1.6,<2

run.bat

@@ -1,12 +1,11 @@
 @echo off
-TITLE Kronos AI Trading Terminal
+TITLE SuperAI Forecast Terminal
 COLOR 0B
 chcp 65001 >nul 2>&1
 
 echo.
-echo ====================================================
-echo   KRONOS AI TRADING TERMINAL - STARTUP
-echo   Powered by Google TimesFM 2.5 (200M params)
+echo   SUPERAI FORECAST TERMINAL - STARTUP
+echo   Powered by Kronos + TimesFM + Chronos
 echo ====================================================
 echo.
 
@@ -22,8 +21,8 @@ if not exist "%PYEXE%" (
 )
 echo [OK] venv found.
 
-:: [2/4] Check TimesFM installation
-echo [2/4] Checking TimesFM dependency...
+:: [2/4] Check AI model dependencies
+echo [2/4] Checking AI model dependencies...
 "%PYEXE%" -c "import timesfm; timesfm.TimesFM_2p5_200M_torch" >nul 2>&1
 if %ERRORLEVEL% neq 0 (
     echo [INFO] TimesFM not found. Installing...
@@ -50,6 +49,18 @@ if %ERRORLEVEL% neq 0 (
     echo [OK] TimesFM is ready.
 )
 
+if exist "%~dp0libs\chronos-forecasting\src\chronos\__init__.py" (
+    echo [OK] Chronos repository is ready.
+) else (
+    echo [INFO] Chronos repository not found. Cloning...
+    git clone --depth=1 https://github.com/amazon-science/chronos-forecasting "%~dp0libs\chronos-forecasting"
+    if %ERRORLEVEL% neq 0 (
+        echo [WARN] Chronos clone failed. The app will continue, but Chronos may be unavailable.
+    ) else (
+        echo [OK] Chronos repository is ready.
+    )
+)
+
 :: [3/4] Apply huggingface_hub compatibility patch
 echo [3/4] Applying compatibility patch...
 if exist "%~dp0scripts\patch_timesfm.py" (
@@ -62,8 +73,8 @@ if exist "%~dp0scripts\patch_timesfm.py" (
 :: [4/4] Launch server
 echo [4/4] Launching server...
 echo.
-echo [INFO] URL: http://127.0.0.1:8000
-echo [INFO] Browser opens automatically in ~3 seconds.
+echo [INFO] Browser opens automatically when the server is ready.
+echo [INFO] Check launcher log for the exact local address.
 echo [INFO] Press CTRL+C to stop.
 echo.
 

scripts/patch_timesfm.py

@@ -1,56 +1,105 @@
 """
-Auto-patch timesfm _from_pretrained to strip unknown kwargs (proxies, etc.)
-that huggingface_hub >=0.30 passes but TimesFM.__init__ doesn't accept.
+Apply local compatibility patches to installed TimesFM source files.
 
-This script is safe to run multiple times (idempotent).
+Patches:
+1. Strip unknown kwargs that huggingface_hub >= 0.30 may forward into
+   TimesFM.__init__.
+2. Make checkpoint loading work when the model was created with meta tensors
+   by using assign=True (or a to_empty fallback).
+
+This script is idempotent and safe to run multiple times.
 """
-import importlib.util
+
+from __future__ import annotations
+
 import sys
 from pathlib import Path
 
-MARKER = "# huggingface_hub >=0.30 passes extra kwargs"
-PATCH = '''\
-    # huggingface_hub >=0.30 passes extra kwargs (proxies, headers, etc.)
-    # that TimesFM.__init__ doesn't accept — strip them out.
+INIT_MARKER = "# AI Forecast patch: strip unsupported hub kwargs"
+INIT_TARGET = "    # Create an instance of the model wrapper class.\n"
+INIT_PATCH = """\
+    # AI Forecast patch: strip unsupported hub kwargs from huggingface_hub.
     _KNOWN_INIT_KWARGS = {"torch_compile", "config"}
     model_kwargs = {k: v for k, v in model_kwargs.items() if k in _KNOWN_INIT_KWARGS}
 
-'''
-TARGET_LINE = "    # Create an instance of the model wrapper class.\n"
+"""
+
+META_MARKER = "    # AI Forecast patch: support loading checkpoints into meta tensors.\n"
+META_TARGET = """\
+  def load_checkpoint(self, path: str, **kwargs):
+    \"\"\"Loads a PyTorch TimesFM model from a checkpoint.\"\"\"
+    tensors = load_file(path)
+    self.load_state_dict(tensors, strict=True)
+    self.to(self.device)
+"""
+META_PATCH = """\
+  def load_checkpoint(self, path: str, **kwargs):
+    \"\"\"Loads a PyTorch TimesFM model from a checkpoint.\"\"\"
+    tensors = load_file(path)
+    # AI Forecast patch: support loading checkpoints into meta tensors.
+    has_meta_parameters = any(
+      getattr(parameter, "is_meta", False) for parameter in self.parameters()
+    )
+    try:
+      if has_meta_parameters:
+        self.load_state_dict(tensors, strict=True, assign=True)
+      else:
+        self.load_state_dict(tensors, strict=True)
+    except TypeError:
+      if has_meta_parameters:
+        self.to_empty(device=self.device)
+      self.load_state_dict(tensors, strict=True)
+    self.to(self.device)
+"""
 
 
-def find_timesfm_torch_file() -> list[Path]:
-    """Find all timesfm_2p5_torch.py files accessible to the current Python."""
-    candidates = []
-    for sp in sys.path:
-        p = Path(sp) / "timesfm" / "timesfm_2p5" / "timesfm_2p5_torch.py"
-        if p.exists():
-            candidates.append(p)
+def find_timesfm_torch_files() -> list[Path]:
+    candidates: list[Path] = []
+    for sys_path_entry in sys.path:
+        path = Path(sys_path_entry) / "timesfm" / "timesfm_2p5" / "timesfm_2p5_torch.py"
+        if path.exists():
+            candidates.append(path)
     return candidates
 
 
-def patch_file(path: Path) -> str:
-    text = path.read_text(encoding="utf-8")
+def apply_patch_once(text: str, *, marker: str, target: str, replacement: str) -> tuple[str, bool, str]:
+    if marker in text:
+        return text, False, "already patched"
+    if target not in text:
+        return text, False, "target not found"
+    return text.replace(target, replacement, 1), True, "patched"
 
-    if MARKER in text:
-        return f"already patched: {path}"
 
-    if TARGET_LINE not in text:
-        return f"target line not found (different version?): {path}"
+def patch_file(path: Path) -> str:
+    original = path.read_text(encoding="utf-8")
+    updated = original
+
+    updated, _, init_status = apply_patch_once(
+        updated,
+        marker=INIT_MARKER,
+        target=INIT_TARGET,
+        replacement=INIT_PATCH + INIT_TARGET,
+    )
+    updated, _, meta_status = apply_patch_once(
+        updated,
+        marker=META_MARKER,
+        target=META_TARGET,
+        replacement=META_PATCH,
+    )
 
-    patched = text.replace(TARGET_LINE, PATCH + TARGET_LINE)
-    path.write_text(patched, encoding="utf-8")
-    return f"patched OK: {path}"
+    if updated != original:
+        path.write_text(updated, encoding="utf-8")
+        return f"patched OK: {path} | init={init_status} | meta={meta_status}"
+    return f"no changes: {path} | init={init_status} | meta={meta_status}"
 
 
 if __name__ == "__main__":
-    files = find_timesfm_torch_file()
+    files = find_timesfm_torch_files()
     if not files:
         print("[patch_timesfm] No timesfm installation found in sys.path.")
         sys.exit(1)
 
-    for f in files:
-        result = patch_file(f)
-        print(f"[patch_timesfm] {result}")
+    for file_path in files:
+        print(f"[patch_timesfm] {patch_file(file_path)}")
 
     sys.exit(0)