@kuandotdev/indicator 0.1.1 → 0.1.3

package/project/src/tv_indicator/model/forecast.py

@@ -0,0 +1,693 @@
+"""Server-side xs_range forecast API integration.
+
+Indicator no longer trains or runs the stock forecast model locally. This module
+keeps the public forecast payload stable while delegating inference/refresh to a
+configured HTTP API.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+from urllib.parse import urljoin
+
+import requests
+
+from ..config import PROJECT_ROOT
+
+DEFAULT_MODEL_ROOT = PROJECT_ROOT / "model_data"
+# Backwards-compatible alias for older imports; local model execution is removed.
+DEFAULT_MODEL_REPO = DEFAULT_MODEL_ROOT
+MODEL_UNIVERSE: tuple[str, ...] = ()
+
+_CRYPTO_EXCHANGES = {
+    "BINANCE",
+    "COINBASE",
+    "KRAKEN",
+    "BITSTAMP",
+    "BITFINEX",
+    "BYBIT",
+    "OKX",
+    "KUCOIN",
+    "GEMINI",
+    "MEXC",
+    "HUOBI",
+}
+_FOREX_EXCHANGES = {
+    "FX",
+    "FX_IDC",
+    "OANDA",
+    "FOREXCOM",
+    "SAXO",
+    "PEPPERSTONE",
+    "CAPITALCOM",
+    "ICMARKETS",
+    "EIGHTCAP",
+}
+_FUTURES_EXCHANGES = {
+    "CME",
+    "CME_MINI",
+    "CBOT",
+    "NYMEX",
+    "COMEX",
+    "ICEUS",
+    "ICEEUR",
+    "EUREX",
+}
+_COMMON_CRYPTO_BASES = {
+    "BTC",
+    "ETH",
+    "SOL",
+    "BNB",
+    "XRP",
+    "ADA",
+    "DOGE",
+    "AVAX",
+    "DOT",
+    "TRX",
+    "TON",
+    "LINK",
+    "LTC",
+    "BCH",
+    "UNI",
+    "MATIC",
+    "POL",
+    "SHIB",
+    "PEPE",
+    "APT",
+    "ARB",
+    "OP",
+    "ATOM",
+    "ETC",
+    "XLM",
+    "HBAR",
+    "ICP",
+    "NEAR",
+    "FIL",
+    "SUI",
+}
+_CRYPTO_QUOTES = ("USDT", "USDC", "BUSD", "FDUSD", "USD", "EUR", "BTC", "ETH")
+
+NUMERIC_FIELDS = {
+    "close",
+    "close_today",
+    "low_20d",
+    "pred_low_20d",
+    "high_20d",
+    "pred_high_20d",
+    "fair_value",
+    "pred_fair_value_20d",
+    "value_gap",
+    "value_gap_pct",
+    "pred_low_pct",
+    "pred_high_pct",
+    "pred_mid_pct",
+    "range_width_pct",
+    "downside_to_pred_low_pct",
+    "upside_to_pred_high_pct",
+    "risk_reward_ratio",
+    "position_score",
+    "mean_iou",
+    "iou60",
+    "dir_win",
+    "directional_win_rate",
+    "iou_ge_60_rate",
+    "iou_ge_70_rate",
+    "iou_ge_80_rate",
+    "iou_ge_90_rate",
+    "range_overlap_rate",
+    "close_in_range_rate",
+    "range_coverage_rate",
+}
+INT_FIELDS = {"rank", "position_rank", "eval_n_rows", "run_universe_size"}
+
+
+class ModelApiError(RuntimeError):
+    """Raised when the server-side model API cannot return a usable response."""
+
+
+def normalize_model_ticker(symbol: str) -> str:
+    """Map TradingView/Yahoo-ish symbols to the model ticker id."""
+    s = symbol.strip().upper()
+    if ":" in s:
+        s = s.split(":", 1)[1]
+    if s in {"^GSPC", "GSPC", "SPX500USD"}:
+        return "SPX"
+    if s.endswith(".TW"):
+        return s[:-3]
+    if s.endswith(".TWO"):
+        return s[:-4]
+    return s
+
+
+def _split_exchange(symbol: str) -> tuple[str | None, str]:
+    s = symbol.strip().upper()
+    if ":" in s:
+        exchange, ticker = s.split(":", 1)
+        return exchange, ticker
+    return None, s
+
+
+def _looks_like_crypto_pair(ticker: str) -> bool:
+    t = ticker.strip().upper()
+    if t.endswith(".P"):
+        t = t[:-2]
+    if t.endswith("PERP"):
+        t = t[:-4]
+    t = t.replace("-", "").replace("/", "")
+    for quote in _CRYPTO_QUOTES:
+        if not t.endswith(quote) or len(t) <= len(quote):
+            continue
+        base = t[: -len(quote)]
+        if base in _COMMON_CRYPTO_BASES:
+            return True
+    return False
+
+
+def model_applicability(symbol: str) -> dict[str, Any]:
+    """Return whether the stock model should handle this symbol by default."""
+    exchange, ticker = _split_exchange(symbol)
+    if exchange in _CRYPTO_EXCHANGES or _looks_like_crypto_pair(ticker):
+        return {
+            "model_applicable": False,
+            "asset_class": "crypto",
+            "reason": "xs_range model is stock/ETF/index-only; crypto pairs are not supported",
+        }
+    if exchange in _FOREX_EXCHANGES:
+        return {
+            "model_applicable": False,
+            "asset_class": "forex",
+            "reason": "xs_range model is stock/ETF/index-only; forex pairs are not supported",
+        }
+    if exchange in _FUTURES_EXCHANGES:
+        return {
+            "model_applicable": False,
+            "asset_class": "futures",
+            "reason": "xs_range model is stock/ETF/index-only; futures/contracts are not supported",
+        }
+    return {
+        "model_applicable": True,
+        "asset_class": "stock_like",
+        "reason": None,
+    }
+
+
+def _clean_url(value: str | None) -> str | None:
+    if value is None:
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+def _join_url(base: str, path: str) -> str:
+    return urljoin(base.rstrip("/") + "/", path.lstrip("/"))
+
+
+def model_api_forecast_url(api_url: str | None = None) -> str | None:
+    """Return the configured forecast endpoint URL."""
+    explicit = _clean_url(
+        api_url or os.getenv("TV_MODEL_API_URL") or os.getenv("TV_MODEL_API_FORECAST_URL")
+    )
+    if explicit:
+        return explicit
+
+    base = _clean_url(os.getenv("TV_MODEL_API_BASE_URL"))
+    if not base:
+        return None
+    path = os.getenv("TV_MODEL_API_FORECAST_PATH", "/forecast")
+    return _join_url(base, path)
+
+
+def model_api_status_url(status_url: str | None = None) -> str | None:
+    """Return the configured status endpoint URL, when one is available."""
+    explicit = _clean_url(status_url or os.getenv("TV_MODEL_API_STATUS_URL"))
+    if explicit:
+        return explicit
+
+    base = _clean_url(os.getenv("TV_MODEL_API_BASE_URL"))
+    if not base:
+        return None
+    path = os.getenv("TV_MODEL_API_STATUS_PATH", "/status")
+    return _join_url(base, path)
+
+
+def _api_timeout() -> float:
+    raw = os.getenv("TV_MODEL_API_TIMEOUT", "60")
+    try:
+        return float(raw)
+    except ValueError:
+        return 60.0
+
+
+def _api_headers() -> dict[str, str]:
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    token = os.getenv("TV_MODEL_API_KEY") or os.getenv("TV_MODEL_API_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def _decode_json_response(response: requests.Response) -> dict[str, Any]:
+    if response.status_code >= 400:
+        body = response.text.strip().replace("\n", " ")[:300]
+        detail = f": {body}" if body else ""
+        raise ModelApiError(f"model API returned HTTP {response.status_code}{detail}")
+
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise ModelApiError("model API did not return JSON") from exc
+    if not isinstance(payload, dict):
+        raise ModelApiError("model API JSON response must be an object")
+    return payload
+
+
+def _request_json(method: str, url: str, **kwargs: Any) -> dict[str, Any]:
+    try:
+        response = requests.request(
+            method,
+            url,
+            headers=_api_headers(),
+            timeout=_api_timeout(),
+            **kwargs,
+        )
+    except requests.RequestException as exc:
+        raise ModelApiError(f"model API request failed: {exc}") from exc
+    return _decode_json_response(response)
+
+
+def fetch_api_forecast(
+    symbol: str,
+    *,
+    api_url: str | None = None,
+    refresh: bool = False,
+    period: str = "10y",
+) -> dict[str, Any]:
+    """Fetch a forecast payload from the server-side model API."""
+    endpoint = model_api_forecast_url(api_url)
+    if not endpoint:
+        raise ModelApiError("model API is not configured; set TV_MODEL_API_URL")
+
+    body = {
+        "symbol": symbol,
+        "model_ticker": normalize_model_ticker(symbol),
+        "refresh": bool(refresh),
+        "period": period,
+    }
+    return _request_json("POST", endpoint, json=body)
+
+
+def _coerce_value(key: str, value: Any) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        value = value.strip()
+        if value == "":
+            return None
+    if key in NUMERIC_FIELDS:
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            return value
+    if key in INT_FIELDS:
+        try:
+            return int(float(value))
+        except (TypeError, ValueError):
+            return value
+    return value
+
+
+def _coerce_row(row: dict[str, Any]) -> dict[str, Any]:
+    out = {key: _coerce_value(key, value) for key, value in row.items()}
+    _add_forecast_aliases(out)
+    return out
+
+
+def _copy_alias(row: dict[str, Any], source: str, target: str) -> None:
+    if target not in row and source in row:
+        row[target] = row[source]
+
+
+def _add_forecast_aliases(row: dict[str, Any]) -> None:
+    """Normalize compact fields and legacy forecast fields in-place."""
+    _copy_alias(row, "close", "close_today")
+    _copy_alias(row, "close_today", "close")
+    _copy_alias(row, "low_20d", "pred_low_20d")
+    _copy_alias(row, "pred_low_20d", "low_20d")
+    _copy_alias(row, "high_20d", "pred_high_20d")
+    _copy_alias(row, "pred_high_20d", "high_20d")
+    _copy_alias(row, "fair_value", "pred_fair_value_20d")
+    _copy_alias(row, "pred_fair_value_20d", "fair_value")
+    _copy_alias(row, "value_gap", "value_gap_pct")
+    _copy_alias(row, "value_gap_pct", "value_gap")
+    _copy_alias(row, "signal", "valuation_signal")
+    _copy_alias(row, "valuation_signal", "signal")
+    _copy_alias(row, "class", "model_class")
+    _copy_alias(row, "asset_class", "class")
+    _copy_alias(row, "iou60", "iou_ge_60_rate")
+    _copy_alias(row, "iou_ge_60_rate", "iou60")
+    _copy_alias(row, "dir_win", "directional_win_rate")
+    _copy_alias(row, "directional_win_rate", "dir_win")
+
+    close = row.get("close_today")
+    low = row.get("pred_low_20d")
+    high = row.get("pred_high_20d")
+    if isinstance(close, (int, float)) and close:
+        if isinstance(low, (int, float)) and "pred_low_pct" not in row:
+            row["pred_low_pct"] = (low / close - 1.0) * 100.0
+        if isinstance(high, (int, float)) and "pred_high_pct" not in row:
+            row["pred_high_pct"] = (high / close - 1.0) * 100.0
+        if isinstance(low, (int, float)) and isinstance(high, (int, float)):
+            if "pred_mid_pct" not in row:
+                row["pred_mid_pct"] = (((low / close) + (high / close)) / 2.0 - 1.0) * 100.0
+            if "range_width_pct" not in row:
+                row["range_width_pct"] = (high / close - low / close) * 100.0
+    if "direction" not in row and isinstance(row.get("pred_mid_pct"), (int, float)):
+        row["direction"] = "UP" if row["pred_mid_pct"] >= 0 else "DOWN"
+
+
+def _looks_like_forecast_row(row: dict[str, Any]) -> bool:
+    fields = {
+        "low_20d",
+        "high_20d",
+        "pred_low_20d",
+        "pred_high_20d",
+        "fair_value",
+        "pred_fair_value_20d",
+    }
+    return any(field in row for field in fields)
+
+
+def _collect_forecast_rows(value: Any, rows: list[dict[str, Any]]) -> None:
+    if isinstance(value, dict):
+        if _looks_like_forecast_row(value):
+            rows.append(value)
+        for key in (
+            "row",
+            "rows",
+            "model_output",
+            "forecast",
+            "forecasts",
+            "data",
+            "result",
+            "results",
+        ):
+            child = value.get(key)
+            if child is not None:
+                _collect_forecast_rows(child, rows)
+    elif isinstance(value, list):
+        for item in value:
+            _collect_forecast_rows(item, rows)
+
+
+def extract_forecast_row(payload: dict[str, Any], ticker: str) -> dict[str, Any] | None:
+    rows: list[dict[str, Any]] = []
+    _collect_forecast_rows(payload, rows)
+    if not rows:
+        return None
+
+    normalized = normalize_model_ticker(ticker)
+    for row in rows:
+        row_ticker = row.get("ticker") or row.get("symbol") or row.get("model_ticker")
+        if row_ticker and normalize_model_ticker(str(row_ticker)) == normalized:
+            return _coerce_row(row)
+    return _coerce_row(rows[0])
+
+
+def compact_model_output(row: dict[str, Any] | None) -> dict[str, Any] | None:
+    if not row:
+        return None
+    return {
+        "ticker": row.get("ticker"),
+        "class": row.get("class") or row.get("model_class") or row.get("asset_class"),
+        "position": row.get("position"),
+        "rank": row.get("rank"),
+        "close": row.get("close"),
+        "low_20d": row.get("low_20d"),
+        "high_20d": row.get("high_20d"),
+        "fair_value": row.get("fair_value"),
+        "value_gap": row.get("value_gap"),
+        "signal": row.get("signal"),
+        "mean_iou": row.get("mean_iou"),
+        "iou60": row.get("iou60"),
+        "dir_win": row.get("dir_win"),
+    }
+
+
+def company_value_forecast(row: dict[str, Any] | None) -> dict[str, Any] | None:
+    if not row:
+        return None
+    keys = [
+        "date",
+        "ticker",
+        "class",
+        "position",
+        "position_rank",
+        "rank",
+        "close",
+        "fair_value",
+        "value_gap",
+        "signal",
+        "low_20d",
+        "high_20d",
+        "downside_to_pred_low_pct",
+        "upside_to_pred_high_pct",
+        "range_width_pct",
+        "mean_iou",
+        "dir_win",
+        "iou60",
+        "range_overlap_rate",
+        "close_in_range_rate",
+        "range_coverage_rate",
+    ]
+    return {key: row.get(key) for key in keys if key in row}
+
+
+def model_status(
+    *,
+    repo: str | Path | None = None,
+    csv_path: str | Path | None = None,
+    conda_env: str | None = None,
+    api_url: str | None = None,
+    status_url: str | None = None,
+) -> dict[str, Any]:
+    """Show server-side model API configuration and optional health status."""
+    _ = repo
+    _ = csv_path
+    _ = conda_env
+    forecast_url = model_api_forecast_url(api_url)
+    health_url = model_api_status_url(status_url)
+    api_status: dict[str, Any] | None = None
+    api_error: str | None = None
+    api_reachable: bool | None = None
+
+    if health_url:
+        try:
+            api_status = _request_json("GET", health_url)
+            api_reachable = True
+        except ModelApiError as exc:
+            api_error = str(exc)
+            api_reachable = False
+
+    temp_dir = Path.cwd() / "temp"
+    commands = {
+        "status": "make model-status",
+        "configure_api": "set TV_MODEL_API_URL in .env or environment",
+        "forecast": "make model-forecast SYMBOL=NASDAQ:TSLA",
+        "refresh_forecast": "make model-forecast SYMBOL=NASDAQ:TSLA REFRESH=1",
+    }
+    next_actions: list[str] = []
+    if not forecast_url:
+        next_actions.append("Set TV_MODEL_API_URL to the server-side model forecast endpoint.")
+    if health_url and api_reachable is False:
+        next_actions.append("Check TV_MODEL_API_STATUS_URL / server health and network access.")
+    if not temp_dir.exists():
+        next_actions.append("Run `mkdir -p temp` or rerun `make install` to create the analysis artifact directory.")
+
+    return {
+        "model_api_url": forecast_url,
+        "model_api_configured": bool(forecast_url),
+        "model_api_status_url": health_url,
+        "model_api_reachable": api_reachable,
+        "model_api_status": api_status,
+        "model_api_error": api_error,
+        "model_backend": "server_api",
+        "model_root": None,
+        "model_root_exists": False,
+        "model_repo": None,
+        "model_repo_exists": False,
+        "model_docs": str(PROJECT_ROOT / "skills/stock-model-forecast/SKILL.md"),
+        "model_docs_exists": (PROJECT_ROOT / "skills/stock-model-forecast/SKILL.md").exists(),
+        "forecast_csv": None,
+        "forecast_csv_exists": False,
+        "covered_tickers": list(MODEL_UNIVERSE),
+        "refresh_conda_env": None,
+        "refresh_dependencies": {},
+        "temp_dir": str(temp_dir),
+        "temp_dir_exists": temp_dir.exists(),
+        "commands": commands,
+        "next_actions": next_actions,
+    }
+
+
+def setup_model_env(
+    *,
+    repo: str | Path | None = None,
+    conda_env: str | None = None,
+    install_extra_deps: bool = True,
+    timeout: int = 3600,
+    api_url: str | None = None,
+    status_url: str | None = None,
+) -> dict[str, Any]:
+    """Validate server-side model API configuration.
+
+    The name is kept for the existing `training-view model setup` command; it no
+    longer installs local ML dependencies.
+    """
+    _ = repo
+    _ = conda_env
+    _ = install_extra_deps
+    _ = timeout
+    status = model_status(api_url=api_url, status_url=status_url)
+    ok = bool(status["model_api_configured"]) and status["model_api_reachable"] is not False
+    if ok:
+        stdout = "Server-side model API is configured."
+    else:
+        stdout = "Set TV_MODEL_API_URL to the server-side model forecast endpoint."
+    return {
+        "ok": ok,
+        "command": ["configure", "TV_MODEL_API_URL"],
+        "returncode": 0 if ok else 1,
+        "stdout": stdout,
+        "stderr": status.get("model_api_error") or "",
+        "status": status,
+    }
+
+
+def forecast_for_symbol(
+    symbol: str,
+    *,
+    repo: str | Path | None = None,
+    csv_path: str | Path | None = None,
+    refresh: bool = False,
+    conda_env: str | None = None,
+    period: str = "10y",
+    api_url: str | None = None,
+) -> dict[str, Any]:
+    _ = repo
+    _ = csv_path
+    _ = conda_env
+    ticker = normalize_model_ticker(symbol)
+    applicability = model_applicability(symbol)
+    forecast_url = model_api_forecast_url(api_url)
+
+    if not applicability["model_applicable"]:
+        return {
+            "ok": False,
+            "symbol": symbol,
+            "model_ticker": ticker,
+            "covered": False,
+            "seed_covered": False,
+            "model_applicable": False,
+            "asset_class": applicability["asset_class"],
+            "unsupported_reason": applicability["reason"],
+            "model_api_url": forecast_url,
+            "model_root": None,
+            "model_repo": None,
+            "forecast_csv": None,
+            "forecast_csv_exists": False,
+            "model_output": None,
+            "company_value_forecast": None,
+            "row": None,
+            "run_universe_size": None,
+            "refresh_requested": refresh,
+            "refresh_results": [],
+            "error": f"model forecast not applicable: {applicability['reason']}",
+        }
+
+    if not forecast_url:
+        return {
+            "ok": False,
+            "symbol": symbol,
+            "model_ticker": ticker,
+            "covered": False,
+            "seed_covered": False,
+            "model_applicable": True,
+            "asset_class": applicability["asset_class"],
+            "unsupported_reason": None,
+            "model_api_url": None,
+            "model_root": None,
+            "model_repo": None,
+            "forecast_csv": None,
+            "forecast_csv_exists": False,
+            "model_output": None,
+            "company_value_forecast": None,
+            "row": None,
+            "run_universe_size": None,
+            "refresh_requested": refresh,
+            "refresh_results": [],
+            "error": "model API is not configured; set TV_MODEL_API_URL",
+        }
+
+    api_payload: dict[str, Any] | None = None
+    api_error: str | None = None
+    try:
+        api_payload = fetch_api_forecast(symbol, api_url=forecast_url, refresh=refresh, period=period)
+    except ModelApiError as exc:
+        api_error = str(exc)
+
+    row = extract_forecast_row(api_payload, ticker) if api_payload else None
+
+    # Some gateways only accept the model ticker in the `symbol` field even
+    # though Indicator also sends `model_ticker`. Keep TradingView symbols as
+    # the first attempt, then retry with the normalized ticker when needed.
+    if row is None and ticker != symbol:
+        retry_payload: dict[str, Any] | None = None
+        retry_error: str | None = None
+        try:
+            retry_payload = fetch_api_forecast(ticker, api_url=forecast_url, refresh=refresh, period=period)
+        except ModelApiError as exc:
+            retry_error = str(exc)
+
+        retry_row = extract_forecast_row(retry_payload, ticker) if retry_payload else None
+        if retry_row is not None:
+            api_payload = retry_payload
+            api_error = None
+            row = retry_row
+        elif api_error is None:
+            api_error = retry_error
+
+    error = api_error
+    if row is None and error is None:
+        error = str(api_payload.get("error") or "model API did not return a forecast row")
+
+    return {
+        "ok": row is not None,
+        "symbol": symbol,
+        "model_ticker": ticker,
+        "covered": bool(row) or bool((api_payload or {}).get("covered")),
+        "seed_covered": bool((api_payload or {}).get("seed_covered", False)),
+        "model_applicable": True,
+        "asset_class": applicability["asset_class"],
+        "unsupported_reason": None,
+        "model_api_url": forecast_url,
+        "model_root": None,
+        "model_repo": None,
+        "forecast_csv": None,
+        "forecast_csv_exists": False,
+        "model_output": compact_model_output(row),
+        "company_value_forecast": company_value_forecast(row),
+        "row": row,
+        "run_universe_size": (api_payload or {}).get("run_universe_size"),
+        "refresh_requested": refresh,
+        "refresh_results": [],
+        "error": error,
+    }
+
+
+def dumps_json(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, indent=2, sort_keys=False, default=str)