"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Alpha Zoo base operators.
Operators all act on **wide** ``pd.DataFrame`` where ``index = trading_date``
(DatetimeIndex) and ``columns = instrument_code`` (str). The factor compute
contract returns a DataFrame of the same shape — raw scores, NaN preserved
in warmup / missing data; +/- inf is forbidden (registry rejects it).
NaN policy: every operator propagates NaN; no silent ``fillna(0)``. A constant
window for ``ts_corr`` / ``ts_cov`` returns NaN, not zero. A missing input is
never replaced by a constant — not a comparison read as False, not
``.where(cond, 0)``, not ``np.fmax`` returning the other side (#1463) — and a
full-window operator (``min_periods`` equal to its window) is NaN on every bar
whose window holds the gap. The one exception, decided on #1463 (2026-09-18):
a recursive statistic skips a missing observation and continues from its last
state — the GTJA ``SMA(A, n, m)`` written as ``.ewm(alpha=m/n, adjust=False)``,
a running product — and so does a window that declares its own partial
coverage (``min_periods`` below its length, or a coverage rule in its notes).
Those emit a value on the bars after a gap, computed from the observations
they did see. Nothing rewarms them, and nothing should: the registry already
masks the gap bar itself.
A comparison gate or ``np.fmin`` / ``np.fmax`` over operands that can be
undefined on complete data (a constant window's correlation) masks on its
inputs' reach with :func:`observed_over`, not on its operands' NaN: a gap
inside the reach is NaN, and a correlation that is undefined without any gap
keeps the verdict it always had (#1452).
Lookahead ban: ``delta(df, d)`` requires ``d >= 1``; the negative-shift
``Ref(df, -n)`` form is intentionally absent.
"""
from __future__ import annotations
from dataclasses import dataclass, field
from enum import Enum
from typing import Any, Protocol, runtime_checkable
import numpy as np
import pandas as pd
from src.factors._backend import HAS_BOTTLENECK, bn, sliding_window_view
class Market(str, Enum):
"""Market identifier used by ``vwap`` for market-specific formulas."""
EQUITY_US = "equity_us"
EQUITY_CN = "equity_cn"
EQUITY_HK = "equity_hk"
EQUITY_IN = "equity_in"
EQUITY_KR = "equity_kr"
CRYPTO = "crypto"
FUTURES = "futures"
@dataclass(frozen=True, slots=True)
class Alpha:
"""Lightweight handle for a registered alpha (registry-owned)."""
id: str
zoo: str
module_path: str
meta: dict[str, Any] = field(default_factory=dict)
@runtime_checkable
class AlphaCompute(Protocol):
"""Structural protocol every alpha ``.py`` module satisfies."""
def __call__(self, panel: dict[str, pd.DataFrame]) -> pd.DataFrame: ...
def _as_float(df: pd.DataFrame) -> pd.DataFrame:
if df.dtypes.eq(np.float64).all():
return df
return df.astype(np.float64)
def rank(df: pd.DataFrame) -> pd.DataFrame:
"""Cross-sectional percentile rank per row (axis=1, ties=average, pct=True).
NaN inputs stay NaN. An all-NaN row returns an all-NaN row.
"""
return df.rank(axis=1, method="average", pct=True, na_option="keep")
def zscore(df: pd.DataFrame) -> pd.DataFrame:
"""Cross-sectional z-score per row (axis=1, sample std).
Rows with zero or NaN standard deviation become NaN — never silent zero.
"""
df = _as_float(df)
mean = df.mean(axis=1, skipna=True)
std = df.std(axis=1, ddof=1, skipna=True)
result = df.sub(mean, axis=0).div(std.where(std > 0), axis=0)
return result.replace([np.inf, -np.inf], np.nan)
def zscore_by_group(df: pd.DataFrame, groups: pd.DataFrame) -> pd.DataFrame:
"""Per-row within-group z-score (axis=1 groups, sample std, ddof=1).
The z-scoring sibling of the per-row sector demean the industry-neutralized
alpha101 alphas use: instead of one cross-sectional mean/std per date, each
label group in the row gets its own. One difference is deliberate — there is
NO global fallback. A cell whose group cannot produce a statistic stays NaN
rather than silently degrading to a whole-cross-section z-score wearing an
industry-neutral label.
Contract:
* ``groups`` is a wide label frame with the SAME shape as ``df``,
positionally aligned (same precedent as the alpha101 ``sector`` tag);
labels may be any hashable value (str, int) and are compared by
position, never by index/column join.
* Per row: within each label group, ``(x - group_mean) / group_std``
with ``ddof=1`` over the group's finite observations.
* A group with fewer than two finite observations on that row → NaN for
that group's cells (no statistic exists); a zero-variance group → NaN
(never inf, never silent zero).
* NaN input cells stay NaN; cells whose label is None/NaN → NaN; ±inf
inputs are scrubbed to NaN before grouping.
* Output keeps ``df``'s shape, index and columns exactly.
Args:
df: Wide numeric frame (dates x symbols).
groups: Wide label frame, same shape as ``df``, positionally aligned.
Returns:
Wide frame of within-group z-scores, NaN wherever the contract above
refuses to produce a number.
Raises:
ValueError: If ``groups`` does not have the same shape as ``df``.
"""
if df.shape != groups.shape:
raise ValueError(
f"zscore_by_group: groups shape {groups.shape} != df shape {df.shape}; "
"the label frame must be positionally aligned with the value frame"
)
values = _as_float(df).to_numpy(dtype=np.float64, na_value=np.nan).copy()
# ±inf is not an observation: scrub before it poisons a group mean/std.
values[~np.isnan(values) & ~np.isfinite(values)] = np.nan
labels = groups.to_numpy()
# Per-row python/numpy loop, same mechanics as the alpha101 precedent —
# correctness over cleverness; cross-sections are a few hundred cells wide.
for i in range(values.shape[0]):
row = values[i]
label_row = labels[i]
unlabeled = pd.isna(label_row)
if unlabeled.any():
row[unlabeled] = np.nan
for tag in pd.unique(label_row):
if tag is None or (isinstance(tag, float) and np.isnan(tag)) or pd.isna(tag):
continue # handled by the unlabeled mask above
mask = label_row == tag
vals = row[mask]
finite = vals[~np.isnan(vals)]
if finite.size < 2:
row[mask] = np.nan
continue
std = finite.std(ddof=1)
if not np.isfinite(std) or std <= 0:
row[mask] = np.nan
continue
row[mask] = (vals - finite.mean()) / std
return pd.DataFrame(values, index=df.index, columns=df.columns)
def scale(df: pd.DataFrame, a: float = 1.0) -> pd.DataFrame:
"""Per-row L1 normalize so sum of absolute values equals ``a``.
Rows whose abs-sum is 0 (or all-NaN) become NaN — never silent zero.
"""
df = _as_float(df)
abs_sum = df.abs().sum(axis=1, skipna=True)
abs_sum = abs_sum.where(abs_sum > 0) # zero → NaN
return df.mul(a).div(abs_sum, axis=0)
def ts_rank(df: pd.DataFrame, n: int) -> pd.DataFrame:
"""Rolling rank (last value's rank within the n-window), per column.
Warmup (first ``n-1`` rows per column) returns NaN. Result is a percentile
in [0, 1] so it is compositionally compatible with cross-sectional rank.
Uses numpy ``sliding_window_view`` for vectorized computation (~45x faster
than pandas rolling().apply()). Note: ``bottleneck.move_rank`` computes
Spearman rank correlation, not percentile rank, so it is not used here.
"""
if n < 1:
raise ValueError(f"ts_rank window must be >= 1, got {n}")
def _last_rank(arr: np.ndarray) -> float:
if np.isnan(arr).all():
return np.nan
last = arr[-1]
if np.isnan(last):
return np.nan
valid = arr[~np.isnan(arr)]
if valid.size == 0:
return np.nan
# average rank for ties; pct
less = (valid < last).sum()
eq = (valid == last).sum()
rank_avg = less + 0.5 * (eq + 1)
return float(rank_avg / valid.size)
arr = df.to_numpy(dtype=np.float64)
T, C = arr.shape
if T < n:
return df.rolling(window=n, min_periods=n).apply(_last_rank, raw=True)
windows = sliding_window_view(arr, window_shape=n, axis=0) # (T-n+1, C, n)
last_vals = windows[:, :, -1] # (T-n+1, C)
nan_last = np.isnan(last_vals)
nan_count = np.isnan(windows).sum(axis=2)
valid_count = n - nan_count
last_expanded = last_vals[:, :, np.newaxis]
valid_mask = ~np.isnan(windows) & ~nan_last[:, :, np.newaxis]
less = np.sum(np.where(valid_mask, windows < last_expanded, 0), axis=2)
eq = np.sum(np.where(valid_mask, windows == last_expanded, 0), axis=2)
rank_avg = less + 0.5 * (eq + 1)
with np.errstate(divide="ignore", invalid="ignore"):
pct = rank_avg / valid_count
# min_periods=n: any NaN in window → NaN output
pct[nan_last | (nan_count > 0)] = np.nan
result = np.full((T, C), np.nan)
result[n - 1 :] = pct
return pd.DataFrame(result, index=df.index, columns=df.columns)
def ts_corr(x: pd.DataFrame, y: pd.DataFrame, n: int) -> pd.DataFrame:
"""Rolling Pearson correlation per column, min_periods=n.
Constant series in the window → NaN (no silent zero). Pairs are inner-joined
on columns; columns missing from either side become NaN.
"""
if n < 2:
raise ValueError(f"ts_corr window must be >= 2, got {n}")
x = _as_float(x)
y = _as_float(y)
cols = x.columns.union(y.columns)
xa = x.reindex(columns=cols)
ya = y.reindex(columns=cols)
corr = xa.rolling(window=n, min_periods=n).corr(ya)
# corr above can produce +/- inf when one series is constant in some
# pandas versions; force to NaN.
return corr.replace([np.inf, -np.inf], np.nan)
def ts_cov(x: pd.DataFrame, y: pd.DataFrame, n: int) -> pd.DataFrame:
"""Rolling sample covariance per column, min_periods=n."""
if n < 2:
raise ValueError(f"ts_cov window must be >= 2, got {n}")
x = _as_float(x)
y = _as_float(y)
cols = x.columns.union(y.columns)
xa = x.reindex(columns=cols)
ya = y.reindex(columns=cols)
cov = xa.rolling(window=n, min_periods=n).cov(ya)
return cov.replace([np.inf, -np.inf], np.nan)
def ts_mean(df: pd.DataFrame, n: int) -> pd.DataFrame:
"""Rolling mean per column, warmup → NaN."""
if n < 1:
raise ValueError(f"ts_mean window must be >= 1, got {n}")
return df.rolling(window=n, min_periods=n).mean()
def ts_std(df: pd.DataFrame, n: int) -> pd.DataFrame:
"""Rolling sample std (ddof=1) per column, warmup → NaN."""
if n < 2:
raise ValueError(f"ts_std window must be >= 2, got {n}")
return df.rolling(window=n, min_periods=n).std(ddof=1)
def ts_slope(df: pd.DataFrame, n: int) -> pd.DataFrame:
"""Rolling OLS slope against ``0, ..., n - 1``, requiring a full window."""
if n < 2:
raise ValueError(f"ts_slope window must be >= 2, got {n}")
arr = _as_float(df).to_numpy(dtype=np.float64, na_value=np.nan)
T, C = arr.shape
result = np.full((T, C), np.nan)
if T < n:
return pd.DataFrame(result, index=df.index, columns=df.columns)
x = np.arange(n, dtype=np.float64)
x -= x.mean()
windows = sliding_window_view(arr, window_shape=n, axis=0)
slopes = np.einsum("ijk,k->ij", windows, x) / np.dot(x, x)
result[n - 1 :] = slopes
return pd.DataFrame(result, index=df.index, columns=df.columns)
def ts_resi(df: pd.DataFrame, n: int) -> pd.DataFrame:
"""Latest observation's residual from the same trailing OLS fit."""
slope = ts_slope(df, n)
fitted_at_last = ts_mean(df, n) + slope * ((n - 1) / 2.0)
return df - fitted_at_last
def ts_max(df: pd.DataFrame, n: int) -> pd.DataFrame:
"""Rolling max per column, warmup → NaN."""
if n < 1:
raise ValueError(f"ts_max window must be >= 1, got {n}")
return df.rolling(window=n, min_periods=n).max()
def ts_min(df: pd.DataFrame, n: int) -> pd.DataFrame:
"""Rolling min per column, warmup → NaN."""
if n < 1:
raise ValueError(f"ts_min window must be >= 1, got {n}")
return df.rolling(window=n, min_periods=n).min()
def _argmax_last(arr: np.ndarray) -> float:
if np.isnan(arr).all():
return np.nan
arr_filled = np.where(np.isnan(arr), -np.inf, arr)
# Ties resolve to the most recent bar, matching bottleneck's move_argmax.
return float(len(arr) - 1 - np.argmax(arr_filled[::-1]))
def _argmin_last(arr: np.ndarray) -> float:
if np.isnan(arr).all():
return np.nan
arr_filled = np.where(np.isnan(arr), np.inf, arr)
# Ties resolve to the most recent bar, matching bottleneck's move_argmin.
return float(len(arr) - 1 - np.argmin(arr_filled[::-1]))
def ts_argmax(df: pd.DataFrame, n: int) -> pd.DataFrame:
"""Rolling argmax (0-based index into the window), warmup → NaN.
Uses ``bottleneck.move_argmax`` when available (~350x faster).
Correction: ``bn.move_argmax`` returns distance from window end,
so we convert via ``(n - 1) - bn_result`` to get 0-based index from start.
"""
if n < 1:
raise ValueError(f"ts_argmax window must be >= 1, got {n}")
if HAS_BOTTLENECK:
arr = df.to_numpy(dtype=np.float64)
raw = bn.move_argmax(arr, window=n, min_count=n, axis=0)
corrected = (n - 1) - raw
return pd.DataFrame(corrected, index=df.index, columns=df.columns)
return df.rolling(window=n, min_periods=n).apply(_argmax_last, raw=True)
def ts_argmin(df: pd.DataFrame, n: int) -> pd.DataFrame:
"""Rolling argmin (0-based index into the window), warmup → NaN.
Uses ``bottleneck.move_argmin`` when available (~350x faster).
Correction: ``bn.move_argmin`` returns distance from window end,
so we convert via ``(n - 1) - bn_result`` to get 0-based index from start.
"""
if n < 1:
raise ValueError(f"ts_argmin window must be >= 1, got {n}")
if HAS_BOTTLENECK:
arr = df.to_numpy(dtype=np.float64)
raw = bn.move_argmin(arr, window=n, min_count=n, axis=0)
corrected = (n - 1) - raw
return pd.DataFrame(corrected, index=df.index, columns=df.columns)
return df.rolling(window=n, min_periods=n).apply(_argmin_last, raw=True)
def delta(df: pd.DataFrame, d: int) -> pd.DataFrame:
"""First difference at lag ``d``: ``df - df.shift(d)``.
Lookahead ban: ``d >= 1`` strictly. Negative lag forbidden.
"""
if d < 1:
raise ValueError(f"delta lag must be >= 1 (lookahead ban), got {d}")
return df - df.shift(d)
def decay_linear(df: pd.DataFrame, n: int) -> pd.DataFrame:
"""Linear decay-weighted moving average, weights ``n, n-1, ..., 1`` normalized.
The most recent bar gets weight ``n`` and the oldest bar in the window
gets weight ``1`` (Kakushadze, *101 Formulaic Alphas*, Appendix A).
Warmup (first ``n-1`` rows) → NaN.
Uses numpy ``sliding_window_view`` + ``einsum`` for vectorized computation
(~40x faster than pandas rolling().apply()). Causal alignment is guaranteed:
output[i] depends only on input[i-n+1:i+1].
"""
if n < 1:
raise ValueError(f"decay_linear window must be >= 1, got {n}")
# Windows run oldest -> newest, so ascending weights put n on today's bar.
weights = np.arange(1, n + 1, dtype=np.float64)
weights /= weights.sum()
def _apply(arr: np.ndarray) -> float:
if np.isnan(arr).any():
return np.nan
return float(np.dot(arr, weights))
arr = df.to_numpy(dtype=np.float64)
T, C = arr.shape
if T < n:
return df.rolling(window=n, min_periods=n).apply(_apply, raw=True)
windows = sliding_window_view(arr, window_shape=n, axis=0) # (T-n+1, C, n)
nan_mask = np.isnan(windows).any(axis=2) # (T-n+1, C)
weighted = np.where(nan_mask[..., np.newaxis], 0.0, windows)
dot = np.einsum("ijk,k->ij", weighted, weights)
result = np.full((T, C), np.nan)
result[n - 1 :] = np.where(nan_mask, np.nan, dot)
return pd.DataFrame(result, index=df.index, columns=df.columns)
def signed_power(df: pd.DataFrame, p: float) -> pd.DataFrame:
"""``sign(df) * |df|**p`` — preserves sign; never produces complex output."""
arr = df.to_numpy(dtype=np.float64, na_value=np.nan)
out = np.sign(arr) * np.power(np.abs(arr), p)
return pd.DataFrame(out, index=df.index, columns=df.columns)
def observed_over(*inputs: tuple[pd.DataFrame, int]) -> pd.DataFrame:
"""Mask of the cells whose every input was observed on each of its last ``n`` bars.
A comparison or ``np.fmin`` turns an operand that is missing because its
window holds a missing input into a verdict — a NaN comparison is False —
so those cells must be NaN (#1463). An operand that is undefined on complete
data, a constant window's correlation, keeps the alpha's existing verdict
(#1452). Masking on the inputs' presence rather than on the operand's NaN is
what separates the two. ``n`` is how far back the input reaches through the
alpha's nested windows, so the first ``n - 1`` bars (warmup) are masked too.
Args:
*inputs: ``(frame, n)`` pairs, one per input the alpha reads across
bars, each with that input's reach in bars.
Returns:
Boolean frame, True where every input was observed throughout its reach.
"""
present = None
for frame, n in inputs:
seen = frame.notna().astype(float).rolling(n, min_periods=n).min().eq(1.0)
present = seen if present is None else present & seen
if present is None:
raise ValueError("observed_over needs at least one (frame, n) pair")
return present
def safe_div(a: pd.DataFrame, b: pd.DataFrame, eps: float = 1e-12) -> pd.DataFrame:
"""Safe division: ``a / (b + eps * sign(b))``.
Where ``b == 0`` exactly (or NaN), result is NaN — never silently inf or 0.
"""
a = _as_float(a)
b = _as_float(b)
sign = np.sign(b.to_numpy(dtype=np.float64, na_value=np.nan))
# b == 0 → sign == 0 → denom == 0 → NaN below
denom_arr = b.to_numpy(dtype=np.float64, na_value=np.nan) + eps * sign
denom = pd.DataFrame(denom_arr, index=b.index, columns=b.columns)
result = a.div(denom)
return result.replace([np.inf, -np.inf], np.nan)
def vwap(panel: dict[str, pd.DataFrame], market: Market | str) -> pd.DataFrame:
"""Market-aware VWAP-equivalent reference price.
- ``equity_cn``: ``(amount * 1000) / (volume * 100 + 1)`` — Tushare's
``daily.amount`` is in **千元 (thousand CNY)** and ``daily.vol`` is in
**手 (100 shares)**. Probe 2026-05-17 against ``000001.SZ`` shows
``amount/(vol*100) ≈ 0.0093`` for a close of 9.27 — confirming the 1000x
scale. We multiply ``amount`` by 1000 (CNY) and divide by
``volume * 100`` (shares); ``+1`` keeps the denominator positive on
suspended bars.
- ``equity_us`` / ``equity_hk`` / ``equity_in`` / ``equity_kr`` /
``futures``: typical price ``(H + L + C + O) / 4`` when ``panel["vwap"]``
is absent. India (NSE/BSE) bars from Yahoo and Korea (KRX) bars from
pykrx carry raw price/volume (no Tushare 千元/手 scaling), so the
typical-price form applies unchanged.
- ``crypto``: prefer ``panel["vwap"]`` if provided, else typical price.
Any missing required column → NaN propagation; never silent zero.
"""
if isinstance(market, str):
market = Market(market)
if "vwap" in panel:
return panel["vwap"]
if market is Market.EQUITY_CN:
if "amount" not in panel or "volume" not in panel:
raise KeyError("vwap(equity_cn) requires panel['amount'] and panel['volume']")
return safe_div(panel["amount"] * 1000.0, panel["volume"] * 100.0 + 1.0)
required = ("open", "high", "low", "close")
missing = [k for k in required if k not in panel]
if missing:
raise KeyError(f"vwap({market.value}) requires panel keys {required}; missing {missing}")
return (panel["open"] + panel["high"] + panel["low"] + panel["close"]) / 4.0