Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(factors): add academic_corr_rewire (correlation-rewiring stability score)

ebujinovcheafdd4bf9fd3
diff --git a/agent/SKILL.md b/agent/SKILL.md
index bfe39de61..762bb9c90 100644
--- a/agent/SKILL.md
+++ b/agent/SKILL.md
@@ -1,7 +1,7 @@
---
name: vibe-trading
version: 0.1.11
-description: Professional finance research toolkit — backtesting (8 engines + benchmark comparison panel), factor analysis, Alpha Zoo (461 pre-built alphas across qlib158/alpha101/gtja191/academic/fundamental), options pricing, 88 finance skills, 30 multi-agent swarm teams, Trade Journal analyzer, and Shadow Account (extract → backtest → render) across 21 market-data sources (tushare, yfinance, okx, akshare, baostock, tencent, mootdx, ccxt, futu, local, eastmoney, sina, stooq, yahoo, india_broker, qveris, longbridge, plus optional-key finnhub/alphavantage/tiingo/fmp).
+description: Professional finance research toolkit — backtesting (8 engines + benchmark comparison panel), factor analysis, Alpha Zoo (462 pre-built alphas across qlib158/alpha101/gtja191/academic/fundamental), options pricing, 88 finance skills, 30 multi-agent swarm teams, Trade Journal analyzer, and Shadow Account (extract → backtest → render) across 21 market-data sources (tushare, yfinance, okx, akshare, baostock, tencent, mootdx, ccxt, futu, local, eastmoney, sina, stooq, yahoo, india_broker, qveris, longbridge, plus optional-key finnhub/alphavantage/tiingo/fmp).
dependencies:
python: ">=3.11"
pip:
@@ -23,7 +23,7 @@ mcp:
# Vibe-Trading
-Professional finance research toolkit with AI-powered backtesting (8 engines), multi-agent teams, 88 specialized skills, the **Alpha Zoo** (461 pre-built quantitative alphas across qlib158 / alpha101 / gtja191 / academic / fundamental with one-line CLI benchmarking), and the Shadow Account loop — extract your implicit trading rules from a journal, backtest them across A股/港股/美股/crypto, then see where they would have served you better.
+Professional finance research toolkit with AI-powered backtesting (8 engines), multi-agent teams, 88 specialized skills, the **Alpha Zoo** (462 pre-built quantitative alphas across qlib158 / alpha101 / gtja191 / academic / fundamental with one-line CLI benchmarking), and the Shadow Account loop — extract your implicit trading rules from a journal, backtest them across A股/港股/美股/crypto, then see where they would have served you better.
## Setup
@@ -53,7 +53,7 @@ Add to your agent's MCP config:
### API Key Requirements
-Core research MCP tools work with zero API keys for HK/US/crypto. After `pip install`, backtesting, market data, factor analysis, options pricing, chart patterns, web search, document reading, trade journal analysis, shadow-account extraction/backtest/report, the Alpha Zoo (461 pre-built alphas), and all 88 skills are ready to use. IBKR tools require a local TWS / IB Gateway session; `run_swarm` requires an LLM key.
+Core research MCP tools work with zero API keys for HK/US/crypto. After `pip install`, backtesting, market data, factor analysis, options pricing, chart patterns, web search, document reading, trade journal analysis, shadow-account extraction/backtest/report, the Alpha Zoo (462 pre-built alphas), and all 88 skills are ready to use. IBKR tools require a local TWS / IB Gateway session; `run_swarm` requires an LLM key.
| Feature | Key needed | When |
|---------|-----------|------|
@@ -106,12 +106,12 @@ Example workflow:
Use `list_swarm_presets()` to see all teams, then `run_swarm()` to execute.
-### Alpha Zoo (461 pre-built alphas)
+### Alpha Zoo (462 pre-built alphas)
One-line cross-sectional IC / IR / alive-reversed-dead categorisation across five bundled zoos:
- **qlib158** (154 alphas) — Microsoft Qlib's `Alpha158` feature handler, Apache-2.0 with pinned commit SHA.
- **alpha101** (101 alphas) — Kakushadze (2015) "101 Formulaic Alphas" (arXiv:1601.00991), written from the paper appendix.
- **gtja191** (191 alphas) — Guotai Junan 2014 "191 Short-period Trading Alpha Factors" research report.
-- **academic** (11 factors) — Fama-French 5 + Carhart momentum + Jegadeesh reversal + George-Hwang 52-week-high + Amihud illiquidity + Harvey-Siddique skew + Frazzini-Pedersen betting-against-beta (price-based proxies).
+- **academic** (12 factors) — Fama-French 5 + Carhart momentum + Jegadeesh reversal + George-Hwang 52-week-high + Amihud illiquidity + Harvey-Siddique skew + Frazzini-Pedersen betting-against-beta (price-based proxies) + a correlation-rewiring stability score (from the in-repo correlation-regime skill).
- **fundamental** (4 factors) — PIT-safe earnings yield, ROE, gross profitability, and asset growth from daily fundamental panels.
Each alpha ships with `__alpha_meta__` (formula LaTeX + theme + universe + warmup + columns required), guarded by an AST purity gate + 300-row lookahead sentinel test. Use the `vibe-trading alpha {list,show,bench,compare,export-manifest}` CLI, the `/alpha/*` REST routes (browser at `/alpha-zoo`), or compose multi-factor signals via `ZooSignalEngine.from_zoo(...)`.
diff --git a/agent/src/factors/zoo/academic/LICENSE.md b/agent/src/factors/zoo/academic/LICENSE.md
index 0140cdd84..d9232b1e4 100644
--- a/agent/src/factors/zoo/academic/LICENSE.md
+++ b/agent/src/factors/zoo/academic/LICENSE.md
@@ -2,8 +2,9 @@
This subdirectory contains price-based proxies for the canonical academic
factor portfolios used as long-short benchmarks in the empirical
-asset-pricing literature. None of the original papers' prose is reproduced
-here.
+asset-pricing literature, plus one house factor sourced from this
+repository's own skill library (see the last attribution entry). None of
+the original papers' prose is reproduced here.
## Source attributions
@@ -27,6 +28,14 @@ here.
*Journal of Financial Economics*, 111(1), 1-25. — BAB (low-beta
premium; leverage-constrained investors bid up high-beta assets,
depressing their risk-adjusted return relative to low-beta assets).
+- corr_rewire (correlation-rewiring stability score) — not sourced from
+ an academic paper: its methodology is the causal rolling rendition of
+ Mode 4 ("Correlation-Rewiring Leaderboard") of this repository's own
+ `correlation-regime` skill (`agent/src/skills/correlation-regime/`).
+ Streaming JVM reference implementation of the surrounding regime
+ machinery: https://github.com/tarvyn-analytics/corrcalc-graphs-pipeline
+ (Apache-2.0; no code from that repository is reproduced here — the
+ factor is an original pandas/numpy implementation).
## Disclosure: these are price-based proxies, not the original factors
diff --git a/agent/src/factors/zoo/academic/corr_rewire.py b/agent/src/factors/zoo/academic/corr_rewire.py
new file mode 100644
index 000000000..2d0b620bb
--- /dev/null
+++ b/agent/src/factors/zoo/academic/corr_rewire.py
@@ -0,0 +1,184 @@
+# ============================================================
+# 中文名称: 相关性重连因子 (Correlation Rewiring)
+# 简要说明: 近期事件窗口与前置平静基线窗口的相关系数矩阵逐行平均绝对变化,衡量资产与市场整体关系的重构幅度;因子值取负(相关性结构稳定的资产得分高)。
+# 典型用途: 风险/拥挤度横截面监控,慢性恶化(阴跌)资产识别;与波动率类因子互补的结构性风险视角。
+# ============================================================
+"""Correlation-rewiring score: how much an asset's correlation row changed.
+
+Reference:
+ The ``correlation-regime`` skill in this repository
+ (``agent/src/skills/correlation-regime/SKILL.md``), Mode 4
+ ("Correlation-Rewiring Leaderboard"). Streaming JVM reference
+ implementation of the surrounding regime machinery:
+ https://github.com/tarvyn-analytics/corrcalc-graphs-pipeline (Apache-2.0).
+
+The skill's Mode 4 scores each asset by the row mean of |Δρ| between an
+event-window correlation matrix and a calm-baseline correlation matrix:
+assets whose relationship to the rest of the market rewired the most rank
+highest. That formulation compares two analyst-chosen windows; this factor
+is its causal rolling rendition for daily cross-sectional use: at each bar
+the "event" window is the trailing ``event_window`` bars and the "calm"
+baseline is the ``calm_window`` bars immediately preceding it (both strictly
+trailing — no future data, no same-bar baseline).
+
+The factor value is the cross-sectional z-score of the NEGATIVE rewiring
+score, i.e. names with a stable correlation profile rank highest. This
+direction encodes a stability-premium hypothesis (rapid rewiring flags
+structural/crowding risk, the classic slow-bleed shape); it is a risk lens,
+not a validated return predictor — see ``notes``.
+
+Missing data: within each window, a column must have at least
+``min_coverage`` of its bars observed, else its correlations (and score)
+are NaN at that bar. Observed entries are demeaned per column and missing
+entries contribute zero to the cross-products (a deterministic, causal
+approximation of pairwise-complete correlation).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+__alpha_meta__ = {
+ "id": "academic_corr_rewire",
+ "nickname": "correlation-rewiring stability score",
+ "theme": ["volatility"],
+ "formula_latex": (
+ r"\mathrm{zscore}_{x}\Bigl(-\,\frac{1}{|J_i|}\sum_{j \in J_i}"
+ r"\bigl|\rho_{ij}^{\mathrm{event}} - \rho_{ij}^{\mathrm{calm}}\bigr|\Bigr),"
+ r"\quad \rho^{\mathrm{event}} = \mathrm{corr}(r_{t-19..t}),\ "
+ r"\rho^{\mathrm{calm}} = \mathrm{corr}(r_{t-139..t-20})"
+ ),
+ "columns_required": ["close"],
+ "universe": ["equity_us", "equity_cn", "equity_hk", "crypto"],
+ "frequency": ["1d"],
+ "decay_horizon": 60,
+ "min_warmup_bars": 142,
+ "notes": (
+ "Causal rolling rendition of the correlation-regime skill's Mode 4 "
+ "(rewiring leaderboard): per-asset row mean of |corr(event) - "
+ "corr(calm)| where the event window is the trailing 20 bars and the "
+ "calm baseline is the 120 bars immediately before it, sign-flipped "
+ "and cross-sectionally z-scored so correlation-stable names rank "
+ "highest. Framed as a structural risk / crowding lens, not a "
+ "validated alpha: the author's public validation of the underlying "
+ "regime machinery covers regime detection and attribution on "
+ "historical replays only and makes no return-prediction claim for "
+ "this cross-sectional form. Missing data: columns need >= 90% "
+ "in-window coverage, else NaN; observed entries are demeaned and "
+ "missing entries contribute zero to the correlation cross-products."
+ ),
+}
+
+
+def _window_corr(window: np.ndarray, min_obs: int) -> np.ndarray:
+ """NaN-aware correlation matrix of one trailing window.
+
+ Args:
+ window: Array of shape (bars, n_assets) of returns, may contain NaN.
+ min_obs: Minimum observed bars a column needs; below it the column's
+ row/column in the result is NaN.
+
+ Returns:
+ (n_assets, n_assets) correlation matrix. Columns with insufficient
+ coverage or zero variance are NaN.
+ """
+ observed = np.isfinite(window)
+ n_obs = observed.sum(axis=0)
+ enough = n_obs >= min_obs
+
+ filled = np.where(observed, window, 0.0)
+ col_mean = filled.sum(axis=0) / np.maximum(n_obs, 1)
+ centered = np.where(observed, window - col_mean, 0.0)
+ norm = np.sqrt((centered * centered).sum(axis=0))
+ scaled = centered / np.where(norm > 0.0, norm, np.nan)
+
+ corr = scaled.T @ scaled
+ corr[~enough, :] = np.nan
+ corr[:, ~enough] = np.nan
+ return corr
+
+
+def _rewiring_scores(
+ returns: np.ndarray,
+ event_window: int,
+ calm_window: int,
+ min_coverage: float,
+ min_peers: int,
+) -> np.ndarray:
+ """Rolling per-bar, per-asset rewiring scores (row means of |Δρ|).
+
+ Args:
+ returns: (n_bars, n_assets) return matrix, may contain NaN.
+ event_window: Trailing bars forming the event correlation matrix.
+ calm_window: Bars immediately preceding the event window forming the
+ calm-baseline correlation matrix.
+ min_coverage: Required fraction of observed bars per column, per window.
+ min_peers: Minimum finite |Δρ| entries a row needs for a score.
+
+ Returns:
+ (n_bars, n_assets) array of rewiring scores (NaN during warmup and
+ wherever coverage is insufficient).
+ """
+ n_bars, n_assets = returns.shape
+ scores = np.full((n_bars, n_assets), np.nan)
+ warmup = calm_window + event_window
+ min_obs_event = int(np.ceil(min_coverage * event_window))
+ min_obs_calm = int(np.ceil(min_coverage * calm_window))
+ diag = np.arange(n_assets)
+
+ for t in range(warmup - 1, n_bars):
+ # Both windows trail bar t. Worked example with event=20, calm=120 at
+ # t=139: event = rows 120..139 (the 20 bars up to and including t),
+ # calm = rows 0..119 (the 120 bars immediately before the event
+ # window). Nothing after row t is ever touched.
+ event = returns[t - event_window + 1 : t + 1]
+ calm = returns[t - warmup + 1 : t - event_window + 1]
+ delta = np.abs(
+ _window_corr(event, min_obs_event) - _window_corr(calm, min_obs_calm)
+ )
+ delta[diag, diag] = np.nan
+ finite = np.isfinite(delta)
+ n_finite = finite.sum(axis=1)
+ row_sum = np.where(finite, delta, 0.0).sum(axis=1)
+ with np.errstate(invalid="ignore"):
+ row_mean = row_sum / np.where(n_finite >= min_peers, n_finite, np.nan)
+ scores[t] = row_mean
+ return scores
+
+
+def _cross_sectional_zscore(df: pd.DataFrame) -> pd.DataFrame:
+ """Per-row z-score: (x - row_mean) / row_std; zero/NaN std rows -> NaN."""
+ mean = df.mean(axis=1, skipna=True)
+ std = df.std(axis=1, ddof=1, skipna=True)
+ centered = df.sub(mean, axis=0)
+ result = centered.div(std.where(std > 0), axis=0)
+ return result.replace([np.inf, -np.inf], np.nan)
+
+
+def compute(panel: dict[str, pd.DataFrame]) -> pd.DataFrame:
+ """Return the cross-sectional z-scored negative correlation-rewiring score.
+
+ At each bar, each asset's rewiring score is the mean over peers of the
+ absolute change in pairwise correlation between the trailing 20-bar event
+ window and the 120-bar calm baseline immediately preceding it. The factor
+ is the z-scored negative score: correlation-stable names rank highest.
+
+ Args:
+ panel: Wide OHLCV panel; only ``close`` is used.
+
+ Returns:
+ DataFrame shaped like ``panel['close']`` with the factor values.
+ """
+ close = panel["close"]
+ returns = close.pct_change()
+
+ scores = _rewiring_scores(
+ returns.to_numpy(dtype=float),
+ event_window=20,
+ calm_window=120,
+ min_coverage=0.9,
+ min_peers=2,
+ )
+ rewiring = pd.DataFrame(scores, index=close.index, columns=close.columns)
+ return _cross_sectional_zscore(-rewiring)
diff --git a/agent/tests/factors/test_corr_rewire.py b/agent/tests/factors/test_corr_rewire.py
new file mode 100644
index 000000000..cfa52f9c0
--- /dev/null
+++ b/agent/tests/factors/test_corr_rewire.py
@@ -0,0 +1,108 @@
+"""Semantic tests for ``zoo/academic/corr_rewire``.
+
+The AST purity gate and the look-ahead sentinel cover safety; these tests
+pin the factor's *meaning*:
+
+* an asset that decouples from its bloc must rank last (most negative
+ factor value — it rewired the most, and the factor is stability-high);
+* columns with insufficient in-window coverage go NaN without poisoning
+ their peers' scores;
+* output is invariant to column order (permutation equivariance);
+* warmup rows are NaN, post-warmup rows are populated.
+
+All panels are seeded and deterministic.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from src.factors.zoo.academic.corr_rewire import compute
+
+N_BARS = 300
+N_BLOC = 5 # correlated bloc members; one extra decoupling asset is added
+
+
+def _bloc_panel(decouple_last: int = 25, seed: int = 7) -> dict[str, pd.DataFrame]:
+ """Panel of one tight return bloc plus one asset that decouples late.
+
+ Assets BLOC0..BLOC4 share a common return driver for all bars. DECOUPLER
+ follows the same driver until the last ``decouple_last`` bars, then
+ switches to independent noise of the same scale — so at the final bar its
+ trailing 20-bar correlation row has collapsed while its 120-bar calm
+ baseline is still bloc-like.
+
+ Args:
+ decouple_last: Bars at the end where DECOUPLER goes independent.
+ seed: RNG seed (panel is fully deterministic).
+
+ Returns:
+ Panel dict with a ``close`` wide DataFrame.
+ """
+ rng = np.random.default_rng(seed)
+ common = rng.normal(0.0, 0.02, N_BARS)
+ cols = {}
+ for i in range(N_BLOC):
+ cols[f"BLOC{i}"] = common + rng.normal(0.0, 0.006, N_BARS)
+ dec = common + rng.normal(0.0, 0.006, N_BARS)
+ dec[-decouple_last:] = rng.normal(0.0, 0.02, decouple_last)
+ cols["DECOUPLER"] = dec
+
+ returns = pd.DataFrame(cols, index=pd.date_range("2024-01-01", periods=N_BARS))
+ close = 100.0 * (1.0 + returns).cumprod()
+ return {"close": close}
+
+
+def test_decoupling_asset_ranks_last() -> None:
+ """The asset whose correlation row rewired the most gets the lowest value."""
+ out = compute(_bloc_panel())
+ last = out.iloc[-1]
+ assert last.notna().all()
+ assert last.idxmin() == "DECOUPLER"
+ # Cross-sectionally it should be a clear outlier, not a coin flip.
+ assert last["DECOUPLER"] < -1.0
+
+
+def test_low_coverage_column_is_nan_without_poisoning_peers() -> None:
+ """A column below the 90% in-window coverage floor is NaN; peers are not."""
+ panel = _bloc_panel()
+ close = panel["close"].copy()
+ close.iloc[::2, close.columns.get_loc("BLOC0")] = np.nan # 50% coverage
+ out = compute({"close": close})
+ last = out.iloc[-1]
+ assert np.isnan(last["BLOC0"])
+ assert last.drop("BLOC0").notna().all()
+
+
+def test_column_order_invariance() -> None:
+ """Reversing panel column order must not change any per-symbol value."""
+ panel = _bloc_panel()
+ out = compute(panel)
+ reversed_close = panel["close"].iloc[:, ::-1]
+ out_reversed = compute({"close": reversed_close})
+ pd.testing.assert_frame_equal(
+ out_reversed[out.columns], out, check_exact=False, atol=1e-12
+ )
+
+
+def test_warmup_rows_are_nan_then_values_appear() -> None:
+ """Everything before the 140-bar warmup is NaN; afterwards values exist."""
+ out = compute(_bloc_panel())
+ warmup = 120 + 20 # calm_window + event_window, matching the module
+ assert out.iloc[: warmup - 1].isna().all().all()
+ assert out.iloc[warmup - 1 :].notna().any().any()
+
+
+def test_declared_warmup_covers_first_valid_row() -> None:
+ """``min_warmup_bars`` in the meta must not promise values earlier than real."""
+ from src.factors.zoo.academic.corr_rewire import __alpha_meta__
+
+ out = compute(_bloc_panel())
+ first_valid = int(np.argmax(out.notna().any(axis=1).to_numpy()))
+ assert __alpha_meta__["min_warmup_bars"] >= first_valid
+
+
+if __name__ == "__main__": # pragma: no cover
+ pytest.main([__file__, "-q"])