alphaengine 0.1.0__py3-none-any.whl

alphaengine/core/performance.py

@@ -0,0 +1,108 @@
+"""
+Performance, risk-adjusted metrics over a supplied return stream.
+
+Pure math, no data layer, no FRED. The risk-free rate is an explicit parameter
+(default 0.0) so results are reproducible and the no-fetch invariant holds, the
+upstream backend performance.py fetched the 3-month T-bill from FRED, which is
+exactly the landmine this copy removes.
+
+Sharpe, Sortino, Calmar, max drawdown, total/annualized return, VaR/CVaR(95),
+and alpha/beta/information-ratio when a benchmark return series is supplied.
+Loss metrics (max_drawdown, var, cvar) are reported as POSITIVE magnitudes in
+both decimal and percent; the sign convention is documented per field.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+_PPY = 252  # trading periods per year
+
+
+def _clean(v):
+    if isinstance(v, float) and (math.isnan(v) or math.isinf(v)):
+        return None
+    return v
+
+
+def performance_report(
+    returns: list[float],
+    *,
+    equity_curve: list[float] | None = None,
+    benchmark_returns: list[float] | None = None,
+    risk_free_rate: float = 0.0,
+    periods_per_year: int = _PPY,
+) -> dict:
+    """Risk-adjusted performance metrics for a daily return series (decimals).
+
+    `risk_free_rate` is ANNUAL (e.g. 0.04); supply it explicitly, the engine
+    never fetches it. Loss metrics are positive magnitudes.
+    """
+    arr = np.asarray([float(r) for r in (returns or []) if r is not None], dtype=float)
+    n = arr.size
+    if n < 30:
+        return {"error": "need >= 30 observations", "n_obs": int(n)}
+
+    ppy = int(periods_per_year)
+    rf_per = float(risk_free_rate) / ppy
+    excess = arr - rf_per
+    sd = float(arr.std(ddof=1))
+
+    sharpe = float(excess.mean() / sd) if sd > 0 else 0.0
+    sharpe_ann = sharpe * math.sqrt(ppy)
+
+    # Downside deviation is the TARGET SEMIDEVIATION: RMS of below-target
+    # excess around the target (0), averaged over ALL N, not the std of the
+    # negative subset (which measures spread around the negatives' own mean).
+    # Math-identical to backend/quant/performance.sortino_ratio (M1 fix).
+    downside = np.minimum(excess, 0.0)
+    dsd = float(np.sqrt(np.mean(downside**2))) if np.count_nonzero(downside) else 0.0
+    sortino_ann = (float(excess.mean()) / dsd) * math.sqrt(ppy) if dsd > 0 else 0.0
+
+    eq = np.asarray(equity_curve, dtype=float) if equity_curve else np.cumprod(1.0 + arr)
+    peak = np.maximum.accumulate(eq)
+    drawdown = eq / peak - 1.0
+    max_dd = float(drawdown.min()) if drawdown.size else 0.0
+
+    total_return = float(eq[-1] - 1.0) if eq.size else 0.0
+    ann_return = float((1.0 + total_return) ** (ppy / n) - 1.0) if total_return > -1 else -1.0
+    calmar = float(ann_return / abs(max_dd)) if max_dd < 0 else 0.0
+
+    cut = float(np.percentile(arr, 5))
+    var95 = abs(cut)
+    tail = arr[arr <= cut]
+    cvar95 = abs(float(tail.mean())) if tail.size else var95
+
+    out = {
+        "n_obs": int(n),
+        "sharpe_ratio": _clean(round(sharpe, 4)),  # per-period
+        "sharpe_annualized": _clean(round(sharpe_ann, 4)),
+        "sortino_ratio": _clean(round(sortino_ann, 4)),  # annualized
+        "calmar_ratio": _clean(round(calmar, 4)),
+        "max_drawdown_pct": _clean(round(abs(max_dd) * 100, 2)),  # positive magnitude
+        "total_return_pct": _clean(round(total_return * 100, 2)),
+        "annualized_return_pct": _clean(round(ann_return * 100, 2)),
+        "var_95": _clean(round(var95, 4)),  # positive daily loss fraction
+        "cvar_95": _clean(round(cvar95, 4)),
+        "volatility_annualized_pct": _clean(round(sd * math.sqrt(ppy) * 100, 2)),
+        "risk_free_rate": round(float(risk_free_rate), 4),
+    }
+
+    if benchmark_returns:
+        b = np.asarray([float(x) for x in benchmark_returns], dtype=float)
+        m = min(len(b), n)
+        if m >= 30:
+            a2, b2 = arr[-m:] - rf_per, b[-m:] - rf_per
+            var_b = float(np.var(b2, ddof=1))
+            beta = float(np.cov(a2, b2, ddof=1)[0, 1] / var_b) if var_b > 0 else 0.0
+            alpha_per = float(a2.mean() - beta * b2.mean())
+            active = arr[-m:] - b[-m:]
+            te = float(active.std(ddof=1))
+            ir = (float(active.mean()) / te) * math.sqrt(ppy) if te > 0 else 0.0
+            out["beta"] = _clean(round(beta, 4))
+            out["alpha_annualized_pct"] = _clean(round(alpha_per * ppy * 100, 2))
+            out["information_ratio"] = _clean(round(ir, 4))
+
+    return out

alphaengine/core/risk.py

@@ -0,0 +1,127 @@
+"""
+Risk, VaR / CVaR over a supplied portfolio return stream.
+
+Lifted (math-identical) from backend/quant/risk.py's returns-based paths, with
+the data/limits coupling removed: the caller supplies a daily portfolio return
+series; nothing is fetched. Three layers of VaR rigor plus Expected Shortfall:
+
+  1. Parametric Gaussian VaR, z·σ·√horizon.
+  2. Cornish-Fisher VaR, expands z by skew/kurtosis (observed non-normality).
+  3. Historical-percentile VaR + bootstrap CI (deterministic seed).
+  4. CVaR (Expected Shortfall), mean of the tail beyond the percentile VaR.
+
+z comes from scipy's inverse-normal so non-{0.95,0.99} confidences are exact.
+Pure numpy/scipy. Deterministic given inputs on the pinned stack.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+from scipy import stats
+
+
+def _clean(val):
+    if isinstance(val, float) and (math.isnan(val) or math.isinf(val)):
+        return None
+    return val
+
+
+def compute_var_cvar(
+    portfolio_returns: list[float],
+    *,
+    confidence: float = 0.95,
+    horizon_days: int = 1,
+    portfolio_value: float = 100_000.0,
+    bootstrap_samples: int = 1000,
+) -> dict:
+    """Portfolio VaR (parametric + Cornish-Fisher + historical) and CVaR.
+
+    `portfolio_returns`: historical daily portfolio returns as decimals. VaR is
+    reported as a positive loss fraction (and dollars at `portfolio_value`).
+    """
+    arr = np.array(
+        [
+            r
+            for r in (portfolio_returns or [])
+            if r is not None and not (isinstance(r, float) and np.isnan(r))
+        ],
+        dtype=float,
+    )
+    n_obs = arr.size
+    if n_obs < 20:
+        return {"error": "need >= 20 observations", "n_obs": int(n_obs)}
+
+    z = float(stats.norm.ppf(confidence))
+    mean = float(np.mean(arr))
+    std = float(np.std(arr, ddof=1)) if n_obs > 1 else 0.0
+
+    # 1. Parametric Gaussian VaR (per-period vol scaled to horizon).
+    parametric_daily = z * std * math.sqrt(horizon_days)
+    result = {
+        "n_obs": int(n_obs),
+        "confidence": confidence,
+        "horizon_days": int(horizon_days),
+        "low_sample": bool(n_obs < 60),
+        "parametric": {
+            "var_pct": _clean(round(parametric_daily * 100, 2)),
+            "var_dollars": _clean(round(parametric_daily * portfolio_value, 2)),
+            "daily_vol_pct": _clean(round(std * 100, 2)),
+        },
+        "method": "parametric_gaussian+cornish_fisher+historical",
+    }
+
+    # 2. Cornish-Fisher adjusted VaR.
+    if std > 0:
+        skew = float(np.mean(((arr - mean) / std) ** 3))
+        kurt = float(np.mean(((arr - mean) / std) ** 4) - 3.0)  # excess
+        z_cf = (
+            z + (z**2 - 1) * skew / 6.0 + (z**3 - 3 * z) * kurt / 24.0 - (2 * z**3 - 5 * z) * (skew**2) / 36.0
+        )
+        # The CF expansion is only valid near-normal; extreme skew/kurtosis
+        # can drive z_cf <= 0, which would report a NEGATIVE loss (violating
+        # the positive-loss convention). Outside the validity domain, fall
+        # back to the Gaussian z and say so, never fabricate from a broken
+        # expansion.
+        cf_invalid = bool(z_cf <= 0)
+        z_eff = z if cf_invalid else z_cf
+        cf_daily = z_eff * std * math.sqrt(horizon_days)
+        result["cornish_fisher"] = {
+            "var_pct": _clean(round(cf_daily * 100, 2)),
+            "var_dollars": _clean(round(cf_daily * portfolio_value, 2)),
+            "skewness": _clean(round(skew, 3)),
+            "excess_kurtosis": _clean(round(kurt, 3)),
+            "z_adjusted": _clean(round(float(z_eff), 3)),
+            "cf_fallback_gaussian": cf_invalid,
+        }
+
+    # 3. Historical-percentile VaR + bootstrap CI (deterministic seed).
+    rng = np.random.default_rng(42)
+    tail_pct = (1 - confidence) * 100
+    samples = rng.choice(arr, size=(bootstrap_samples, n_obs), replace=True)
+    boot_vars = np.percentile(samples, tail_pct, axis=1) * math.sqrt(horizon_days)
+    lo, hi = np.percentile(boot_vars, [2.5, 97.5])
+    point = float(np.percentile(arr, tail_pct)) * math.sqrt(horizon_days)
+    # Report VaR as a positive loss magnitude. The tail percentiles are
+    # negative returns, so abs() flips their order, sort so low <= high.
+    ci_low, ci_high = sorted((abs(float(lo)) * 100, abs(float(hi)) * 100))
+    result["historical"] = {
+        "var_pct": _clean(round(abs(point) * 100, 2)),
+        "ci_95_low_pct": _clean(round(ci_low, 2)),
+        "ci_95_high_pct": _clean(round(ci_high, 2)),
+        "bootstrap_samples": bootstrap_samples,
+    }
+
+    # 4. CVaR (Expected Shortfall), mean of the tail beyond the percentile VaR.
+    var_cutoff = np.percentile(arr, tail_pct)
+    tail = arr[arr <= var_cutoff]
+    cvar = float(np.mean(tail)) if tail.size > 0 else float(var_cutoff)
+    result["cvar"] = {
+        "cvar_pct": _clean(round(abs(cvar) * 100, 2)),
+        "cvar_dollars": _clean(round(abs(cvar) * portfolio_value, 2)),
+        "var_pct": _clean(round(abs(float(var_cutoff)) * 100, 2)),
+        "tail_observations": int(tail.size),
+    }
+
+    return result

alphaengine/core/technical.py

@@ -0,0 +1,213 @@
+"""
+technical.py, price-derived technical features on a SUPPLIED price series.
+
+Pure deterministic math (no fetch, no LLM, no randomness): Wilder RSI, SMA/EMA,
+distance-from-MA, and ATR, with interpretive flags. Prices are caller-supplied
+(model "b": the engine never fetches prices). A feature that needs more data than
+supplied (RSI/EMA below their window, ATR with no high/low) is reported as
+absent-with-a-reason, never guessed. Coverage is a first-class output.
+
+Math conventions (so a caller can audit):
+  - SMA(w)  = mean of the trailing w closes.
+  - EMA(w)  = seeded with SMA of the first w closes, then alpha=2/(w+1) recursion.
+  - RSI(w)  = Wilder: seed avg gain/loss = simple mean of the first w deltas, then
+              avg = (prev*(w-1) + current)/w. RS = avg_gain/avg_loss;
+              RSI = 100 - 100/(1+RS). All-up -> 100, all-down -> 0, flat -> 50.
+  - ATR(w)  = Wilder smoothing of True Range; needs high/low (OHLC rows).
+  - distance_pct = (last_close - MA) / MA * 100.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+DEFAULT_SMA_WINDOWS = [50, 150, 200]
+RSI_OVERBOUGHT = 70.0
+RSI_OVERSOLD = 30.0
+_RND = 6
+
+
+def _unavailable(reason: str, **details) -> dict:
+    """Local capability-error shape (kept identical in the backend copy for parity)."""
+    return {"available": False, "reason": reason, **details}
+
+
+def _extract(series: Any) -> tuple[np.ndarray, np.ndarray | None, np.ndarray | None]:
+    """Return (closes, highs, lows). Accepts bare closes, {date: close}, or a list
+    of OHLC row dicts. highs/lows are None unless OHLC rows carry them."""
+    if isinstance(series, dict):
+        dates = sorted(series.keys())
+        return np.asarray([float(series[d]) for d in dates], dtype=float), None, None
+    if isinstance(series, list) and series and isinstance(series[0], dict):
+        rows = series
+        if all("date" in r for r in rows):
+            rows = sorted(rows, key=lambda r: r["date"])
+        closes = np.asarray([float(r["close"]) for r in rows], dtype=float)
+        if all(("high" in r and "low" in r) for r in rows):
+            highs = np.asarray([float(r["high"]) for r in rows], dtype=float)
+            lows = np.asarray([float(r["low"]) for r in rows], dtype=float)
+            return closes, highs, lows
+        return closes, None, None
+    closes = np.asarray([float(x) for x in (series or []) if x is not None], dtype=float)
+    return closes, None, None
+
+
+def _sma(closes: np.ndarray, window: int) -> float | None:
+    if len(closes) < window:
+        return None
+    return float(closes[-window:].mean())
+
+
+def _ema(closes: np.ndarray, window: int) -> float | None:
+    if len(closes) < window:
+        return None
+    alpha = 2.0 / (window + 1)
+    ema = float(closes[:window].mean())
+    for c in closes[window:]:
+        ema = alpha * float(c) + (1 - alpha) * ema
+    return ema
+
+
+def _wilder_rsi(closes: np.ndarray, window: int) -> float | None:
+    if len(closes) < window + 1:
+        return None
+    deltas = np.diff(closes)
+    gains = np.where(deltas > 0, deltas, 0.0)
+    losses = np.where(deltas < 0, -deltas, 0.0)
+    avg_gain = float(gains[:window].mean())
+    avg_loss = float(losses[:window].mean())
+    for i in range(window, len(deltas)):
+        avg_gain = (avg_gain * (window - 1) + float(gains[i])) / window
+        avg_loss = (avg_loss * (window - 1) + float(losses[i])) / window
+    if avg_loss == 0 and avg_gain == 0:
+        return 50.0
+    if avg_loss == 0:
+        return 100.0
+    rs = avg_gain / avg_loss
+    return 100.0 - 100.0 / (1.0 + rs)
+
+
+def _atr(highs: np.ndarray | None, lows: np.ndarray | None, closes: np.ndarray, window: int) -> float | None:
+    if highs is None or lows is None or len(closes) < window + 1:
+        return None
+    n = len(closes)
+    tr = np.empty(n - 1)
+    for i in range(1, n):
+        tr[i - 1] = max(highs[i] - lows[i], abs(highs[i] - closes[i - 1]), abs(lows[i] - closes[i - 1]))
+    atr = float(tr[:window].mean())
+    for i in range(window, len(tr)):
+        atr = (atr * (window - 1) + float(tr[i])) / window
+    return atr
+
+
+def _ma_block(last: float, value: float | None) -> dict | None:
+    if value is None:
+        return None
+    return {
+        "value": round(value, _RND),
+        "above": bool(last > value),
+        "distance_pct": round((last - value) / value * 100.0, 4) if value != 0 else None,
+    }
+
+
+def technical_features(
+    prices: dict,
+    *,
+    sma_windows: list[int] | None = None,
+    ema_windows: list[int] | None = None,
+    rsi_window: int = 14,
+    atr_window: int = 14,
+) -> dict:
+    """Per-symbol technical features over supplied prices. See module docstring for
+    the math. Returns per-symbol values + interpretive flags, plus coverage."""
+    sma_windows = list(sma_windows) if sma_windows else list(DEFAULT_SMA_WINDOWS)
+    ema_windows = list(ema_windows) if ema_windows else []
+
+    features: dict[str, dict] = {}
+    coverage_n = 0
+    for sym, series in prices.items():
+        closes, highs, lows = _extract(series)
+        n = len(closes)
+        if n == 0:
+            features[sym] = {
+                "n_observations": 0,
+                "last_close": None,
+                "insufficient": ["no_data"],
+                "flags": [],
+            }
+            continue
+        coverage_n += 1
+        last = float(closes[-1])
+        res: dict[str, Any] = {
+            "n_observations": n,
+            "last_close": round(last, _RND),
+            "sma": {},
+            "ema": {},
+            "flags": [],
+            "insufficient": [],
+        }
+
+        for w in sma_windows:
+            block = _ma_block(last, _sma(closes, w))
+            res["sma"][str(w)] = block
+            if block is None:
+                res["insufficient"].append(f"sma_{w}")
+            else:
+                res["flags"].append(f"{'above' if block['above'] else 'below'}_sma_{w}")
+        for w in ema_windows:
+            block = _ma_block(last, _ema(closes, w))
+            res["ema"][str(w)] = block
+            if block is None:
+                res["insufficient"].append(f"ema_{w}")
+            else:
+                res["flags"].append(f"{'above' if block['above'] else 'below'}_ema_{w}")
+
+        rsi = _wilder_rsi(closes, rsi_window)
+        if rsi is None:
+            res["rsi"] = None
+            res["insufficient"].append(f"rsi_{rsi_window}")
+        else:
+            ob, osd = rsi > RSI_OVERBOUGHT, rsi < RSI_OVERSOLD
+            res["rsi"] = {
+                "window": rsi_window,
+                "value": round(rsi, 4),
+                "overbought": bool(ob),
+                "oversold": bool(osd),
+            }
+            if ob:
+                res["flags"].append("rsi_overbought")
+            if osd:
+                res["flags"].append("rsi_oversold")
+
+        atr = _atr(highs, lows, closes, atr_window)
+        if atr is None:
+            res["atr"] = (
+                _unavailable("ATR needs high/low; supply OHLC rows", atr_window=atr_window)
+                if highs is None
+                else _unavailable(f"need >= {atr_window + 1} bars", atr_window=atr_window)
+            )
+        else:
+            res["atr"] = {
+                "window": atr_window,
+                "value": round(atr, _RND),
+                "pct_of_close": round(atr / last * 100.0, 4) if last != 0 else None,
+            }
+
+        features[sym] = res
+
+    return {
+        "features": features,
+        "params": {
+            "sma_windows": sma_windows,
+            "ema_windows": ema_windows,
+            "rsi_window": rsi_window,
+            "atr_window": atr_window,
+        },
+        "universe_size": len(prices),
+        "coverage_n": coverage_n,
+    }
+
+
+__all__ = ["technical_features"]