Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(factors): industry-neutralized CN value alphas + PIT SW2021 sector tag (csi300) (#1802)

shadowinlifefa17ca1cef67
diff --git a/README.md b/README.md
index a5efb2526..518bef9ee 100644
--- a/README.md
+++ b/README.md
@@ -379,7 +379,7 @@ It is designed for research, simulation, and backtesting — and, when you choos
| **Run analyst teams** | Multi-agent research reviews for investment, quant, crypto, macro, and risk workflows. |
| **Put research into IM channels** | Run the same session runtime through WebSocket, Telegram, Slack, Discord, Matrix, WhatsApp, Signal, QQ/NapCat, WeChat/WeCom, Feishu/Lark, DingTalk, Teams, email, and Mochat with CLI, REST, and Web UI controls. |
| **Ship usable artifacts** | Reports, TradingView Pine Script, TDX, MetaTrader 5, MCP tools, and later research sessions. |
-| **Bench a pre-built alpha zoo** | One-line IC + alive/reversed/dead categorisation across 475 alphas (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental) on your universe. |
+| **Bench a pre-built alpha zoo** | One-line IC + alive/reversed/dead categorisation across 478 alphas (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental) on your universe. |
| **Spot correlation regimes** | An edge-density + hysteresis timeline on the `/correlation` surface showing when markets fuse into one bloc — descriptive risk context, not a signal. Undefined pair correlations keep edge density unknown, so constant-price histories cannot claim a measured zero density. |
Daily correlation and regime requests align each source by its local calendar date, including mixed timezone-aware and timezone-naive histories.
@@ -798,9 +798,9 @@ alongside the bundled roster (same-name files override it, like user skills) and
</details>
<details>
-<summary><b>Alpha Zoo</b> <sub>475 pre-built quant alphas across 5 families</sub></summary>
+<summary><b>Alpha Zoo</b> <sub>478 pre-built quant alphas across 5 families</sub></summary>
-- 🧬 475 cross-sectional alphas, lookahead-banned at the operator layer
+- 🧬 478 cross-sectional alphas, lookahead-banned at the operator layer
- 📈 IC + IR + alive/reversed/dead categorisation in one CLI command
- 🔬 AST purity gate + 300-row lookahead sentinel test + `pytest-socket` network kill-switch
- 📦 Apache-2 attribution for Qlib; per-zoo `LICENSE.md` declaring formulas as mathematical content
@@ -1201,7 +1201,7 @@ The interactive TUI (`vibe-trading`) now uses a terminal-native transcript: a st
vibe-trading # interactive TUI
vibe-trading run -p "..." # single run
vibe-trading serve # API server
-vibe-trading alpha list # browse 475 pre-built alphas; show / bench / compare / export-manifest sub-commands available
+vibe-trading alpha list # browse 478 pre-built alphas; show / bench / compare / export-manifest sub-commands available
vibe-trading playbook list # five scheduled-research templates; show / create sub-commands available
vibe-trading channels status --local # inspect IM channel config and install hints
vibe-trading provider doctor # print redacted provider/proxy/package diagnostics
@@ -2126,7 +2126,7 @@ Vibe-Trading/
│ │ │ ├── web_search_tool.py # DuckDuckGo web search
│ │ │ └── ... # bash, file I/O, factor analysis, options, alpha browser + bench, etc.
│ │ │
-│ │ ├── factors/ # Alpha Zoo — 475 alphas across 5 families
+│ │ ├── factors/ # Alpha Zoo — 478 alphas across 5 families
│ │ │ ├── base.py # 19 operators (rank/scale/ts_*/delta/decay_linear/safe_div/vwap)
│ │ │ ├── registry.py # AST-only metadata load + lazy compute + sanity gates
│ │ │ ├── bench_runner.py # IC + alive/reversed/dead categorisation
@@ -2209,7 +2209,7 @@ Vibe-Trading is part of the **[HKUDS](https://github.com/HKUDS)** agent ecosyste
| **Data Bridge** | Bring-your-own data: local CSV/Parquet/SQL connectors with schema mapping | Local loader Shipped |
| **Options Lab** | Vol surface, Greeks dashboard, payoff/scenario explorer | Analytic payoff/scenario tool **Shipped**; surface/dashboard Planned |
| **Portfolio Studio** | Risk x-ray, constraints, turnover-aware optimizer, rebalance notes | Turnover-aware optimizer **Shipped 0.1.11**; rest Planned |
-| **Alpha Zoo** | 475 pre-built alphas (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental) with one-line bench, agent integration, and Web UI | **Shipped 0.1.8**, extended through 0.1.12 |
+| **Alpha Zoo** | 478 pre-built alphas (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental) with one-line bench, agent integration, and Web UI | **Shipped 0.1.8**, extended through 0.1.12 |
| **Strategy Development Manager** | Register papers / broker research as factors & strategies with a persistent store + automated IC/Sharpe decay lifecycle | **Shipped 0.1.11** |
| **Correlation Regime** | Edge-density + hysteresis regime timeline layered on `/correlation` — spot when markets fuse into one bloc | **Shipped 0.1.12** |
| **Research Delivery** | Scheduled briefs and live research sessions through Slack / Telegram / email-style IM channels | Scheduler + IM Runtime Shipped |
diff --git a/README_ar.md b/README_ar.md
index 50c79cf3a..474b8c37e 100644
--- a/README_ar.md
+++ b/README_ar.md
@@ -380,7 +380,7 @@ Vibe-Trading مساحة عمل بحثية مفتوحة المصدر تحول ا
| **تشغيل فرق محللين** | مراجعات بحث متعددة الوكلاء لتدفقات الاستثمار والكم والكريبتو والماكرو والمخاطر. |
| **وصل الأبحاث بقنوات IM** | إدارة بيئة جلسة واحدة عبر WebSocket وTelegram وSlack وDiscord وMatrix وWhatsApp وSignal وQQ/NapCat وWeChat/WeCom وFeishu/Lark وDingTalk وTeams وemail وMochat من CLI وREST وWeb UI. |
| **إنتاج مخرجات قابلة للاستخدام** | تقارير، وTradingView Pine Script، وTDX، وMetaTrader 5، وأدوات MCP، وجلسات بحث لاحقة. |
-| **bench ألفا zoo جاهزة** | تشغيل IC + IR + تصنيف alive/reversed/dead عبر 475 ألفا (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental) بسطر أوامر واحد على universe الخاص بك. |
+| **bench ألفا zoo جاهزة** | تشغيل IC + IR + تصنيف alive/reversed/dead عبر 478 ألفا (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental) بسطر أوامر واحد على universe الخاص بك. |
| **رصد أنظمة الارتباط** | جدول زمني قائم على كثافة الحواف + التباطؤ (hysteresis) على واجهة `/correlation` يُظهر متى تندمج الأسواق في كتلة واحدة — سياق مخاطر وصفي، لا إشارة تداول. |
---
@@ -667,9 +667,9 @@ LONGBRIDGE_ACCESS_TOKEN=...
</details>
<details>
-<summary><b>Alpha Zoo</b> <sub>475 ألفا كمّي جاهز عبر 5 families</sub></summary>
+<summary><b>Alpha Zoo</b> <sub>478 ألفا كمّي جاهز عبر 5 families</sub></summary>
-- 🧬 475 ألفا cross-sectional، مع منع lookahead على طبقة العوامل (operators)
+- 🧬 478 ألفا cross-sectional، مع منع lookahead على طبقة العوامل (operators)
- 📈 IC + IR + تصنيف alive/reversed/dead بأمر CLI واحد
- 🔬 بوابة نقاء AST + اختبار حماية lookahead بـ 300 صف + قاطع شبكة عبر `pytest-socket`
- 📦 إسناد Apache-2 لـ Qlib؛ ملف `LICENSE.md` لكل zoo يصرّح بأن الصيغ محتوى رياضي
@@ -977,7 +977,7 @@ Vibe-Trading وكيل كثيف الأدوات؛ المهارات والاختب
vibe-trading # interactive TUI
vibe-trading run -p "..." # single run
vibe-trading serve # API server
-vibe-trading alpha list # استعرض 475 ألفا جاهز؛ متاح show / bench / compare / export-manifest
+vibe-trading alpha list # استعرض 478 ألفا جاهز؛ متاح show / bench / compare / export-manifest
vibe-trading playbook list # خمسة قوالب بحث مجدولة؛ متاح show / create
vibe-trading channels status --local # فحص إعدادات قنوات IM وتلميحات التثبيت
vibe-trading provider doctor # طباعة تشخيصات المزود/الوكيل/الحزم بعد إخفاء الأسرار
@@ -1731,7 +1731,7 @@ Vibe-Trading/
│ │ │ ├── web_search_tool.py # DuckDuckGo web search
│ │ │ └── ... # bash, file I/O, factor analysis, options, alpha browser + bench, etc.
│ │ │
-│ │ ├── factors/ # Alpha Zoo — 475 ألفا عبر 5 families
+│ │ ├── factors/ # Alpha Zoo — 478 ألفا عبر 5 families
│ │ │ ├── base.py # 19 عاملاً (rank/scale/ts_*/delta/decay_linear/safe_div/vwap)
│ │ │ ├── registry.py # تحميل بيانات وصفية AST فقط + حساب كسول + بوابات سلامة
│ │ │ ├── bench_runner.py # IC + تصنيف alive/reversed/dead
@@ -1814,7 +1814,7 @@ Vibe-Trading جزء من نظام وكلاء **[HKUDS](https://github.com/HKUDS)
| **Data Bridge** | أحضر بياناتك: موصلات CSV/Parquet/SQL محلية مع schema mapping | المُحمِّل المحلي شُحن |
| **Options Lab** | سطح تقلب، ولوحة Greeks، ومستكشف payoff/scenario | مخطط |
| **Portfolio Studio** | أشعة مخاطر، وقيود، ومحسن يراعي الدوران، وملاحظات إعادة توازن | محسن يراعي الدوران **تم الإطلاق 0.1.11**؛ الباقي مخطط |
-| **Alpha Zoo** | 475 ألفا كمّي جاهز (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental)، سطر أوامر واحد للـ bench، تكامل agent، وواجهة Web | **تم الإطلاق 0.1.8**، موسّع حتى 0.1.12 |
+| **Alpha Zoo** | 478 ألفا كمّي جاهز (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental)، سطر أوامر واحد للـ bench، تكامل agent، وواجهة Web | **تم الإطلاق 0.1.8**، موسّع حتى 0.1.12 |
| **Strategy Development Manager** | تسجيل الأوراق البحثية / أبحاث الوسطاء كعوامل واستراتيجيات مع مخزن دائم + دورة حياة آلية لاضمحلال IC/Sharpe | **تم الإطلاق 0.1.11** |
| **Correlation Regime** | جدول زمني لنظام الارتباط قائم على كثافة الحواف + التباطؤ (hysteresis) فوق `/correlation` — رصد متى تندمج الأسواق في كتلة واحدة | **تم الإطلاق 0.1.12** |
| **Research Delivery** | موجزات مجدولة وجلسات بحث حي عبر Slack / Telegram / قنوات IM شبيهة بالبريد | المُجدوِل + IM Runtime شُحنا |
diff --git a/README_es.md b/README_es.md
index 260f3bec4..f9e8b718d 100644
--- a/README_es.md
+++ b/README_es.md
@@ -379,7 +379,7 @@ Está diseñado para investigación, simulación y backtesting, y, cuando tú lo
| **Ejecutar equipos de analistas** | Revisiones de investigación multiagente para flujos de trabajo de inversión, cuantitativo, cripto, macro y riesgo. |
| **Llevar la investigación a canales de mensajería** | Ejecuta el mismo runtime de sesión a través de WebSocket, Telegram, Slack, Discord, Matrix, WhatsApp, Signal, QQ/NapCat, WeChat/WeCom, Feishu/Lark, DingTalk, Teams, correo electrónico y Mochat, con controles de CLI, REST y Web UI. |
| **Entregar artefactos utilizables** | Informes, TradingView Pine Script, TDX, MetaTrader 5, herramientas MCP y sesiones de investigación posteriores. |
-| **Evaluar un zoológico de alfas preconstruido** | Clasificación IC + viva/invertida/muerta en una línea, en 475 alfas (Qlib 158 + Kakushadze 101 + GTJA 191 + académicas + fundamentales PIT-safe) sobre tu universo. |
+| **Evaluar un zoológico de alfas preconstruido** | Clasificación IC + viva/invertida/muerta en una línea, en 478 alfas (Qlib 158 + Kakushadze 101 + GTJA 191 + académicas + fundamentales PIT-safe) sobre tu universo. |
| **Detectar regímenes de correlación** | Una línea de tiempo de densidad de aristas + histéresis en la superficie `/correlation` que muestra cuándo los mercados se fusionan en un solo bloque: contexto de riesgo descriptivo, no una señal. |
---
@@ -673,9 +673,9 @@ junto al catálogo incluido (los archivos con el mismo nombre lo sobrescriben, i
</details>
<details>
-<summary><b>Alpha Zoo</b> <sub>475 alphas cuantitativos preconstruidos en 5 familias</sub></summary>
+<summary><b>Alpha Zoo</b> <sub>478 alphas cuantitativos preconstruidos en 5 familias</sub></summary>
-- 🧬 475 alphas cross-sectional, con prohibición de lookahead a nivel de la capa de operadores
+- 🧬 478 alphas cross-sectional, con prohibición de lookahead a nivel de la capa de operadores
- 📈 Categorización de IC + IR + vivo/invertido/muerto en un solo comando de la CLI
- 🔬 Puerta de pureza AST + test centinela de lookahead de 300 filas + interruptor de apagado de red `pytest-socket`
- 📦 Atribución Apache-2 para Qlib; `LICENSE.md` por zoo que declara las fórmulas como contenido matemático
@@ -1015,7 +1015,7 @@ La TUI interactiva (`vibe-trading`) ahora usa una transcripción nativa de termi
vibe-trading # interactive TUI
vibe-trading run -p "..." # single run
vibe-trading serve # API server
-vibe-trading alpha list # explora 475 alphas preconstruidos; subcomandos show / bench / compare / export-manifest disponibles
+vibe-trading alpha list # explora 478 alphas preconstruidos; subcomandos show / bench / compare / export-manifest disponibles
vibe-trading playbook list # cinco plantillas de investigación programada; subcomandos show / create disponibles
vibe-trading channels status --local # inspecciona la configuración de canales IM y sugerencias de instalación
vibe-trading provider doctor # imprime diagnósticos redactados de provider/proxy/paquetes
@@ -1819,7 +1819,7 @@ Vibe-Trading/
│ │ │ ├── web_search_tool.py # búsqueda web con DuckDuckGo
│ │ │ └── ... # bash, E/S de archivos, análisis de factores, opciones, navegador de alpha + bench, etc.
│ │ │
-│ │ ├── factors/ # Alpha Zoo — 475 alphas en 5 familias
+│ │ ├── factors/ # Alpha Zoo — 478 alphas en 5 familias
│ │ │ ├── base.py # 19 operadores (rank/scale/ts_*/delta/decay_linear/safe_div/vwap)
│ │ │ ├── registry.py # carga de metadatos solo por AST + cómputo diferido + puertas de sanidad
│ │ │ ├── bench_runner.py # IC + categorización alive/reversed/dead
@@ -1902,7 +1902,7 @@ Vibe-Trading forma parte del ecosistema de agentes de **[HKUDS](https://github.c
| **Data Bridge** | Trae tus propios datos: conectores locales CSV/Parquet/SQL con mapeo de esquema | Cargador local publicado |
| **Options Lab** | Superficie de volatilidad, panel de Greeks, explorador de payoff/escenarios | Herramienta analítica de payoff/escenarios **publicada**; superficie/panel planificados |
| **Portfolio Studio** | Risk x-ray, restricciones, optimizador con reducción de turnover, notas de rebalanceo | Optimizador con reducción de turnover **publicado en 0.1.11**; el resto planificado |
-| **Alpha Zoo** | 475 alphas preconstruidas (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental) con benchmark en una línea, integración con el agente y Web UI | **Publicado en 0.1.8**, ampliado hasta 0.1.12 |
+| **Alpha Zoo** | 478 alphas preconstruidas (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental) con benchmark en una línea, integración con el agente y Web UI | **Publicado en 0.1.8**, ampliado hasta 0.1.12 |
| **Strategy Development Manager** | Registra papers / research de brokers como factores y estrategias con un almacén persistente + lifecycle automatizado de decaimiento de IC/Sharpe | **Publicado en 0.1.11** |
| **Correlation Regime** | Línea temporal de régimen por edge-density + histéresis, superpuesta en `/correlation` — detecta cuándo los mercados se fusionan en un solo bloque | **Publicado en 0.1.12** |
| **Research Delivery** | Briefs programados y sesiones de investigación en vivo a través de canales IM tipo Slack / Telegram / correo | Scheduler + runtime de IM publicados |
diff --git a/README_id.md b/README_id.md
index 295b5ee63..a4eaab835 100644
--- a/README_id.md
+++ b/README_id.md
@@ -502,7 +502,7 @@ Vibe-Trading dirancang untuk riset, simulasi, dan backtest — serta, jika Anda
| **Jalankan tim analis** | Review riset multi-agent untuk workflow investasi, quant, crypto, makro, dan risiko. |
| **Bawa riset ke channel IM** | Jalankan runtime sesi yang sama melalui WebSocket, Telegram, Slack, Discord, Matrix, WhatsApp, Signal, QQ/NapCat, WeChat/WeCom, Feishu/Lark, DingTalk, Teams, email, dan Mochat dengan kontrol CLI, REST, dan Web UI. |
| **Hasilkan artefak yang siap digunakan** | Laporan, TradingView Pine Script, TDX, MetaTrader 5, tool MCP, dan sesi riset lanjutan. |
-| **Benchmark alpha zoo siap pakai** | Satu baris untuk IC + kategorisasi alive/reversed/dead pada 475 alpha (Qlib 158 + Kakushadze 101 + GTJA 191 + akademik + fundamental PIT-safe) di universe Anda. |
+| **Benchmark alpha zoo siap pakai** | Satu baris untuk IC + kategorisasi alive/reversed/dead pada 478 alpha (Qlib 158 + Kakushadze 101 + GTJA 191 + akademik + fundamental PIT-safe) di universe Anda. |
| **Deteksi regime korelasi** | Timeline edge-density + hysteresis pada surface `/correlation` yang menunjukkan kapan market menyatu menjadi satu blok — konteks risiko deskriptif, bukan sinyal. |
---
@@ -833,9 +833,9 @@ bersama roster bawaan (file dengan nama sama akan override, seperti user skill)
</details>
<details>
-<summary><b>Alpha Zoo</b> <sub>475 alpha quant siap pakai dalam 5 keluarga</sub></summary>
+<summary><b>Alpha Zoo</b> <sub>478 alpha quant siap pakai dalam 5 keluarga</sub></summary>
-- 🧬 475 alpha cross-sectional, lookahead dilarang pada layer operator
+- 🧬 478 alpha cross-sectional, lookahead dilarang pada layer operator
- 📈 IC + IR + kategorisasi alive/reversed/dead dalam satu perintah CLI
- 🔬 AST purity gate + test sentinel lookahead 300 baris + network kill-switch `pytest-socket`
- 📦 Atribusi Apache-2 untuk Qlib; `LICENSE.md` per-zoo menyatakan formula sebagai konten matematis
@@ -1202,7 +1202,7 @@ TUI interaktif (`vibe-trading`) kini memakai transcript native terminal: startup
vibe-trading # interactive TUI
vibe-trading run -p "..." # single run
vibe-trading serve # API server
-vibe-trading alpha list # browse 475 pre-built alphas; show / bench / compare / export-manifest sub-commands available
+vibe-trading alpha list # browse 478 pre-built alphas; show / bench / compare / export-manifest sub-commands available
vibe-trading playbook list # five scheduled-research templates; show / create sub-commands available
vibe-trading channels status --local # inspect IM channel config and install hints
vibe-trading provider doctor # print redacted provider/proxy/package diagnostics
@@ -2064,7 +2064,7 @@ Vibe-Trading/
│ │ │ ├── web_search_tool.py # DuckDuckGo web search
│ │ │ └── ... # bash, file I/O, factor analysis, options, alpha browser + bench, etc.
│ │ │
-│ │ ├── factors/ # Alpha Zoo — 475 alphas across 5 families
+│ │ ├── factors/ # Alpha Zoo — 478 alphas across 5 families
│ │ │ ├── base.py # 19 operators (rank/scale/ts_*/delta/decay_linear/safe_div/vwap)
│ │ │ ├── registry.py # AST-only metadata load + lazy compute + sanity gates
│ │ │ ├── bench_runner.py # IC + alive/reversed/dead categorisation
@@ -2148,7 +2148,7 @@ Vibe-Trading adalah bagian dari ekosistem agent **[HKUDS](https://github.com/HKU
| **Data Bridge** | Bawa data sendiri: connector CSV/Parquet/SQL lokal dengan schema mapping | Loader lokal Dirilis |
| **Options Lab** | Vol surface, dashboard Greeks, explorer payoff/scenario | Tool analitik payoff/scenario **Dirilis**; surface/dashboard Direncanakan |
| **Portfolio Studio** | Risk x-ray, constraint, optimizer turnover-aware, catatan rebalance | Optimizer turnover-aware **Dirilis 0.1.11**; sisanya Direncanakan |
-| **Alpha Zoo** | 475 alpha siap pakai (Qlib 158 + Kakushadze 101 + GTJA 191 + akademik + fundamental) dengan bench satu baris, integrasi agent, dan Web UI | **Dirilis 0.1.8**, diperluas hingga 0.1.12 |
+| **Alpha Zoo** | 478 alpha siap pakai (Qlib 158 + Kakushadze 101 + GTJA 191 + akademik + fundamental) dengan bench satu baris, integrasi agent, dan Web UI | **Dirilis 0.1.8**, diperluas hingga 0.1.12 |
| **Strategy Development Manager** | Daftarkan paper / riset broker sebagai faktor & strategi dengan store persisten + lifecycle decay IC/Sharpe otomatis | **Dirilis 0.1.11** |
| **Correlation Regime** | Timeline regime edge-density + hysteresis di `/correlation` — deteksi saat market menyatu menjadi satu blok | **Dirilis 0.1.12** |
| **Research Delivery** | Brief terjadwal dan sesi riset live melalui Slack / Telegram / channel IM bergaya email | Scheduler + IM Runtime Dirilis |
diff --git a/README_ja.md b/README_ja.md
index 57cf22a78..d45beed41 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -380,7 +380,7 @@ Vibe-Trading は、金融に関する問いを実行可能な分析へ変換す
| **アナリストチームを走らせる** | 投資、クオンツ、暗号資産、マクロ、リスクのワークフロー向けマルチエージェント・リサーチレビュー。 |
| **リサーチを IM チャンネルへ接続する** | WebSocket、Telegram、Slack、Discord、Matrix、WhatsApp、Signal、QQ/NapCat、WeChat/WeCom、Feishu/Lark、DingTalk、Teams、email、Mochat から同じ session runtime を CLI、REST、Web UI で管理。 |
| **使える artifacts を出力する** | レポート、TradingView Pine Script、TDX、MetaTrader 5、MCP tools、後続リサーチセッション。 |
-| **事前構築 alpha zoo をベンチ** | 475 個の alpha 因子(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental)に対し、1 行 CLI で IC + IR + alive/reversed/dead 分類を実行 |
+| **事前構築 alpha zoo をベンチ** | 478 個の alpha 因子(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental)に対し、1 行 CLI で IC + IR + alive/reversed/dead 分類を実行 |
| **相関レジームを見抜く** | `/correlation` 面上のエッジ密度 + ヒステリシスのタイムライン。市場が 1 つのブロックに融合するタイミングを示す —— シグナルではなく記述的なリスクコンテキスト。 |
---
@@ -667,9 +667,9 @@ Paper-vs-live is a **structural per-broker runtime guard** (account-id format, h
</details>
<details>
-<summary><b>Alpha Zoo</b> <sub>5 つのファミリーに渡る 475 個の事前構築 quant alpha</sub></summary>
+<summary><b>Alpha Zoo</b> <sub>5 つのファミリーに渡る 478 個の事前構築 quant alpha</sub></summary>
-- 🧬 475 個のクロスセクショナル alpha、オペレーター層でルックアヘッドを禁止
+- 🧬 478 個のクロスセクショナル alpha、オペレーター層でルックアヘッドを禁止
- 📈 IC + IR + alive/reversed/dead 分類を 1 つの CLI コマンドで
- 🔬 AST 純関数ゲート + 300 行のルックアヘッド sentinel テスト + `pytest-socket` によるネットワーク遮断
- 📦 Qlib には Apache-2 帰属表示、各 zoo ごとに `LICENSE.md` で formula を数学的内容として宣言
@@ -982,7 +982,7 @@ Vibe-Trading は tool-heavy agent です。skills、backtests、memory、swarms
vibe-trading # interactive TUI
vibe-trading run -p "..." # single run
vibe-trading serve # API server
-vibe-trading alpha list # 475 個の事前構築 alpha を閲覧;show / bench / compare / export-manifest サブコマンド利用可
+vibe-trading alpha list # 478 個の事前構築 alpha を閲覧;show / bench / compare / export-manifest サブコマンド利用可
vibe-trading playbook list # 定期リサーチのテンプレート 5 本;show / create サブコマンド利用可
vibe-trading channels status --local # IM チャンネル設定と install hints を確認
vibe-trading provider doctor # 秘匿処理済みの provider/proxy/package 診断を出力
@@ -1739,7 +1739,7 @@ Vibe-Trading/
│ │ │ ├── web_search_tool.py # DuckDuckGo Web 検索
│ │ │ └── ... # bash、file I/O、factor analysis、options、alpha browser + bench など
│ │ │
-│ │ ├── factors/ # Alpha Zoo — 5 つのファミリーにまたがる 475 個の alpha
+│ │ ├── factors/ # Alpha Zoo — 5 つのファミリーにまたがる 478 個の alpha
│ │ │ ├── base.py # 19 個のオペレーター (rank/scale/ts_*/delta/decay_linear/safe_div/vwap)
│ │ │ ├── registry.py # AST 限定のメタデータ読み込み + 遅延計算 + sanity gate
│ │ │ ├── bench_runner.py # IC + alive/reversed/dead 分類
@@ -1822,7 +1822,7 @@ Vibe-Trading は **[HKUDS](https://github.com/HKUDS)** agent ecosystem の一部
| **Data Bridge** | Bring-your-own data: local CSV/Parquet/SQL connectors with schema mapping | ローカルローダー出荷済み |
| **Options Lab** | Vol surface, Greeks dashboard, payoff/scenario explorer | Planned |
| **Portfolio Studio** | Risk x-ray, constraints, turnover-aware optimizer, rebalance notes | Turnover を考慮したオプティマイザは **0.1.11 でリリース済み**;残りは Planned |
-| **Alpha Zoo** | 475 個の事前構築 alpha 因子(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental)、1 行 CLI でベンチ、agent 統合、Web UI | **0.1.8 でリリース済み**、0.1.12 まで拡張 |
+| **Alpha Zoo** | 478 個の事前構築 alpha 因子(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental)、1 行 CLI でベンチ、agent 統合、Web UI | **0.1.8 でリリース済み**、0.1.12 まで拡張 |
| **Strategy Development Manager** | Register papers / broker research as factors & strategies with a persistent store + automated IC/Sharpe decay lifecycle | **0.1.11 でリリース済み** |
| **Correlation Regime** | Edge-density + hysteresis regime timeline layered on `/correlation` — spot when markets fuse into one bloc | **0.1.12 でリリース済み** |
| **Research Delivery** | Slack / Telegram / email-style IM channels 経由の scheduled briefs と live research sessions | スケジューラ + IM Runtime 出荷済み |
diff --git a/README_ko.md b/README_ko.md
index c78142641..129d48ade 100644
--- a/README_ko.md
+++ b/README_ko.md
@@ -380,7 +380,7 @@ Vibe-Trading은 금융 질문을 실행 가능한 분석으로 바꾸는 오픈
| **애널리스트 팀 실행하기** | 투자, 퀀트, 크립토, 매크로, 리스크 워크플로를 위한 멀티 에이전트 리서치 리뷰. |
| **리서치를 IM 채널에 연결하기** | WebSocket, Telegram, Slack, Discord, Matrix, WhatsApp, Signal, QQ/NapCat, WeChat/WeCom, Feishu/Lark, DingTalk, Teams, email, Mochat에서 같은 session runtime을 CLI, REST, Web UI로 관리. |
| **사용 가능한 artifacts 만들기** | 리포트, TradingView Pine Script, TDX, MetaTrader 5, MCP tools, 이후 리서치 세션. |
-| **사전 빌드된 alpha zoo 벤치** | 475개의 alpha 인자(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental)에 대해 한 줄 CLI로 IC + IR + alive/reversed/dead 분류 수행 |
+| **사전 빌드된 alpha zoo 벤치** | 478개의 alpha 인자(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental)에 대해 한 줄 CLI로 IC + IR + alive/reversed/dead 분류 수행 |
| **상관관계 국면 포착하기** | `/correlation` 화면의 엣지 밀도 + 히스테리시스 타임라인으로 시장이 한 덩어리로 움직이기 시작하는 시점을 보여줍니다 — 시그널이 아니라 서술적 리스크 컨텍스트입니다. |
---
@@ -667,9 +667,9 @@ Paper-vs-live는 **구조적 브로커별 런타임 가드**(account-id 형식,
</details>
<details>
-<summary><b>Alpha Zoo</b> <sub>5개 패밀리에 걸친 475개 사전 빌드된 quant alpha</sub></summary>
+<summary><b>Alpha Zoo</b> <sub>5개 패밀리에 걸친 478개 사전 빌드된 quant alpha</sub></summary>
-- 🧬 operator 계층에서 lookahead가 금지된 475개 cross-sectional alpha
+- 🧬 operator 계층에서 lookahead가 금지된 478개 cross-sectional alpha
- 📈 한 줄 CLI로 IC + IR + alive/reversed/dead 분류 수행
- 🔬 AST 순수성 게이트 + 300-row lookahead sentinel 테스트 + `pytest-socket` 네트워크 kill-switch
- 📦 Qlib에 대한 Apache-2 출처 표기, zoo별 `LICENSE.md`에서 수식을 수학적 콘텐츠로 명시
@@ -980,7 +980,7 @@ Vibe-Trading은 tool-heavy agent입니다. skills, backtests, memory, swarms가
vibe-trading # interactive TUI
vibe-trading run -p "..." # single run
vibe-trading serve # API server
-vibe-trading alpha list # 사전 빌드된 475개 alpha 탐색; show / bench / compare / export-manifest 서브커맨드 사용 가능
+vibe-trading alpha list # 사전 빌드된 478개 alpha 탐색; show / bench / compare / export-manifest 서브커맨드 사용 가능
vibe-trading playbook list # 예약 리서치 템플릿 5개; show / create 서브커맨드 사용 가능
vibe-trading channels status --local # IM 채널 설정과 설치 힌트 확인
vibe-trading provider doctor # 마스킹된 provider/proxy/패키지 진단 출력
@@ -1736,7 +1736,7 @@ Vibe-Trading/
│ │ │ ├── web_search_tool.py # DuckDuckGo web search
│ │ │ └── ... # bash, file I/O, factor analysis, options, alpha browser + bench, etc.
│ │ │
-│ │ ├── factors/ # Alpha Zoo — 5개 패밀리에 걸친 475개 alpha
+│ │ ├── factors/ # Alpha Zoo — 5개 패밀리에 걸친 478개 alpha
│ │ │ ├── base.py # 19개 operator (rank/scale/ts_*/delta/decay_linear/safe_div/vwap)
│ │ │ ├── registry.py # AST-only 메타데이터 로딩 + lazy compute + sanity gate
│ │ │ ├── bench_runner.py # IC + alive/reversed/dead 분류
@@ -1819,7 +1819,7 @@ Vibe-Trading은 **[HKUDS](https://github.com/HKUDS)** agent ecosystem의 일부
| **Data Bridge** | Bring-your-own data: local CSV/Parquet/SQL connectors with schema mapping | 로컬 로더 출시 |
| **Options Lab** | Vol surface, Greeks dashboard, payoff/scenario explorer | Planned |
| **Portfolio Studio** | Risk x-ray, constraints, turnover-aware optimizer, rebalance notes | Turnover-aware optimizer **0.1.11 출시 완료**; 나머지 Planned |
-| **Alpha Zoo** | 5개 패밀리에 걸친 475개의 사전 빌드된 alpha 인자(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental), 한 줄 CLI 벤치, agent 통합, Web UI | **0.1.8 출시 완료**, 0.1.12까지 확장 |
+| **Alpha Zoo** | 5개 패밀리에 걸친 478개의 사전 빌드된 alpha 인자(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental), 한 줄 CLI 벤치, agent 통합, Web UI | **0.1.8 출시 완료**, 0.1.12까지 확장 |
| **Strategy Development Manager** | 논문 / 브로커 리서치를 영속 store + 자동 IC/Sharpe decay 라이프사이클과 함께 팩터 & 전략으로 등록 | **0.1.11 출시 완료** |
| **Correlation Regime** | `/correlation` 위에 얹은 엣지 밀도 + 히스테리시스 레짐 타임라인 — 시장이 하나의 블록으로 융합되는 시점 포착 | **0.1.12 출시 완료** |
| **Research Delivery** | Slack / Telegram / email-style IM channels를 통한 예약 brief와 live research sessions | 스케줄러 + IM Runtime 출시 |
diff --git a/README_zh.md b/README_zh.md
index dfc27ab4d..06839eaef 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -379,7 +379,7 @@ Vibe-Trading 是一个开源研究工作台,用于把金融问题转化为可
| **运行分析师团队** | 面向投资、量化、加密、宏观和风控工作流的多智能体研究评审。 |
| **把研究接入 IM 通道** | 通过 WebSocket、Telegram、Slack、Discord、Matrix、WhatsApp、Signal、QQ/NapCat、微信/企业微信、飞书/Lark、钉钉、Teams、email、Mochat,在 CLI、REST 和 Web UI 中管理同一套 session runtime。 |
| **交付可用成果** | 报告、TradingView Pine Script、TDX、MetaTrader 5、MCP tools,以及可延续的研究 sessions。 |
-| **跑预置 alpha zoo 横评** | 475 个 alpha 因子(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental),一行 CLI 在你选的 universe 上算 IC + IR + alive/reversed/dead 分类 |
+| **跑预置 alpha zoo 横评** | 478 个 alpha 因子(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental),一行 CLI 在你选的 universe 上算 IC + IR + alive/reversed/dead 分类 |
| **识别相关性状态** | `/correlation` 界面上的边密度 + 迟滞时间线,显示市场何时融合为一个板块——属于描述性风险上下文,而非交易信号。 |
---
@@ -680,9 +680,9 @@ LONGBRIDGE_ACCESS_TOKEN=...
</details>
<details>
-<summary><b>Alpha Zoo</b> <sub>475 个预置 alpha,覆盖 5 个家族</sub></summary>
+<summary><b>Alpha Zoo</b> <sub>478 个预置 alpha,覆盖 5 个家族</sub></summary>
-- 🧬 475 个横截面 alpha,算子层即禁用 lookahead
+- 🧬 478 个横截面 alpha,算子层即禁用 lookahead
- 📈 一条 CLI 命令完成 IC + IR + alive/reversed/dead 分类
- 🔬 AST 纯函数门禁 + 300 行 lookahead 哨兵测试 + `pytest-socket` 网络阻断
- 📦 Qlib 部分附 Apache-2 出处声明;每个 zoo 一份 `LICENSE.md`,声明公式属于数学内容
@@ -987,7 +987,7 @@ Vibe-Trading 是高度依赖工具的智能体:skills、backtests、memory 和
vibe-trading # interactive TUI
vibe-trading run -p "..." # single run
vibe-trading serve # API server
-vibe-trading alpha list # 浏览 475 个预置 alpha;支持 show / bench / compare / export-manifest 子命令
+vibe-trading alpha list # 浏览 478 个预置 alpha;支持 show / bench / compare / export-manifest 子命令
vibe-trading playbook list # 五个定时研究模板;支持 show / create 子命令
vibe-trading channels status --local # 检查 IM 通道配置和依赖安装提示
vibe-trading provider doctor # 打印脱敏后的 provider/proxy/依赖诊断
@@ -1734,7 +1734,7 @@ Vibe-Trading/
│ │ │ ├── web_search_tool.py # DuckDuckGo 网络搜索
│ │ │ └── ... # bash、文件 I/O、因子分析、期权、alpha 浏览 + 横评等
│ │ │
-│ │ ├── factors/ # Alpha Zoo —— 5 个家族共 475 个 alpha
+│ │ ├── factors/ # Alpha Zoo —— 5 个家族共 478 个 alpha
│ │ │ ├── base.py # 19 个算子(rank/scale/ts_*/delta/decay_linear/safe_div/vwap)
│ │ │ ├── registry.py # 纯 AST 元数据加载 + 惰性计算 + sanity 校验
│ │ │ ├── bench_runner.py # IC + alive/reversed/dead 分类
@@ -1817,7 +1817,7 @@ Vibe-Trading 是 **[HKUDS](https://github.com/HKUDS)** 智能体生态的一部
| **Data Bridge** | 自带数据:本地 CSV/Parquet/SQL connectors 与 schema mapping | 本地加载器已发布 |
| **Options Lab** | Vol surface、Greeks dashboard、payoff/scenario explorer | Planned |
| **Portfolio Studio** | Risk x-ray、constraints、turnover-aware optimizer、rebalance notes | Turnover-aware optimizer **已发布 0.1.11**;其余 Planned |
-| **Alpha Zoo** | 475 个预置 alpha 因子(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental),一行 CLI 跑横评,agent 集成,Web UI 浏览 | **已发布 0.1.8**,延续至 0.1.12 |
+| **Alpha Zoo** | 478 个预置 alpha 因子(Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental),一行 CLI 跑横评,agent 集成,Web UI 浏览 | **已发布 0.1.8**,延续至 0.1.12 |
| **Strategy Development Manager** | 把论文 / 券商研报注册为因子与策略,配持久化 store + 自动化 IC/Sharpe 衰减生命周期 | **已发布 0.1.11** |
| **Correlation Regime** | 叠加在 `/correlation` 上的边密度 + 迟滞状态时间线——识别市场何时融合为一个板块 | **已发布 0.1.12** |
| **Research Delivery** | 通过 Slack / Telegram / email-style IM channels 发送定时 briefs 与实时研究 sessions | 调度器 + IM Runtime 已发布 |
diff --git a/agent/SKILL.md b/agent/SKILL.md
index 073862eb1..45a148a76 100644
--- a/agent/SKILL.md
+++ b/agent/SKILL.md
@@ -1,7 +1,7 @@
---
name: vibe-trading
version: 0.1.16
-description: Professional finance research toolkit — backtesting (11 engines + benchmark comparison panel), factor analysis, Alpha Zoo (475 pre-built alphas across qlib158/alpha101/gtja191/academic/fundamental), options pricing, 90 finance skills, 30 multi-agent swarm teams, Trade Journal analyzer, and Shadow Account (extract → backtest → render) across 29 market-data sources (tushare, yfinance, okx, binance, akshare, baostock, tencent, mootdx, ccxt, futu, mt5, tickerall, local, eastmoney, sina, stooq, yahoo, pykrx, india_broker, qveris, longbridge, nobitex, wallex, plus optional-key finnhub/alphavantage/tiingo/fmp/gildata).
+description: Professional finance research toolkit — backtesting (11 engines + benchmark comparison panel), factor analysis, Alpha Zoo (478 pre-built alphas across qlib158/alpha101/gtja191/academic/fundamental), options pricing, 90 finance skills, 30 multi-agent swarm teams, Trade Journal analyzer, and Shadow Account (extract → backtest → render) across 29 market-data sources (tushare, yfinance, okx, binance, akshare, baostock, tencent, mootdx, ccxt, futu, mt5, tickerall, local, eastmoney, sina, stooq, yahoo, pykrx, india_broker, qveris, longbridge, nobitex, wallex, plus optional-key finnhub/alphavantage/tiingo/fmp/gildata).
dependencies:
python: ">=3.11"
pip:
@@ -23,7 +23,7 @@ mcp:
# Vibe-Trading
-Professional finance research toolkit with AI-powered backtesting (11 engines), multi-agent teams, 90 specialized skills, the **Alpha Zoo** (475 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 (11 engines), multi-agent teams, 90 specialized skills, the **Alpha Zoo** (478 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/Canada/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 (475 pre-built alphas), and all 90 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/Canada/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 (478 pre-built alphas), and all 90 skills are ready to use. IBKR tools require a local TWS / IB Gateway session; `run_swarm` requires an LLM key.
| Feature | Key needed | When |
|---------|-----------|------|
@@ -110,13 +110,13 @@ Example workflow:
Use `list_swarm_presets()` to see all teams, then `run_swarm()` to execute.
-### Alpha Zoo (475 pre-built alphas)
+### Alpha Zoo (478 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** (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** (17 factors) — PIT-safe earnings yield, ROE, gross profitability and asset growth, plus ten SEC XBRL additions: book-to-market, FCF yield, accruals, ROA, CFO yield, operating margin, cash-to-assets, leverage, revenue growth and earnings growth, from daily fundamental panels; and three CN A-share daily-valuation factors (PB, PS_TTM, dividend yield) fed by the new ``val:*`` panel namespace from tushare daily_basic.
+- **fundamental** (20 factors) — PIT-safe earnings yield, ROE, gross profitability and asset growth, plus ten SEC XBRL additions: book-to-market, FCF yield, accruals, ROA, CFO yield, operating margin, cash-to-assets, leverage, revenue growth and earnings growth, from daily fundamental panels; three CN A-share daily-valuation factors (PB, PS_TTM, dividend yield) fed by the ``val:*`` panel namespace from tushare daily_basic; and three industry-neutralized variants of those CN value factors, z-scored within Shenwan L1 peers against a PIT SW2021 industry tag from tushare index_member_all (membership is point-in-time; the SW2021 taxonomy itself is retroactive).
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/backtest/loaders/industry_loader.py b/agent/backtest/loaders/industry_loader.py
new file mode 100644
index 000000000..5c2c5c739
--- /dev/null
+++ b/agent/backtest/loaders/industry_loader.py
@@ -0,0 +1,292 @@
+"""CN industry classification loader from Tushare ``index_member_all`` (SW2021).
+
+Supplies the wide ``sector`` label frame the industry-neutralized CN value
+alphas z-score against (issue #1789 follow-up #2): one label per symbol per
+trading day, point-in-time via each membership row's ``in_date``/``out_date``.
+
+PIT semantics: symbol ``s`` carries label ``L`` on date ``d`` iff a membership
+row exists with ``in_date <= d`` and (``out_date`` is null OR ``d < out_date``)
+— ``in_date`` inclusive, ``out_date`` exclusive. If overlapping rows ever claim
+the same ``(s, d)``, the LATER ``in_date`` wins; on equal ``in_date`` the row
+with the later (or null = current) ``out_date`` wins. Both rules are fixed so
+the frame is deterministic regardless of API row order.
+
+Taxonomy caveat: SW2021 classifications are applied retroactively to history —
+a name reclassified in 2021 carries its 2021 industry back through the whole
+window. This is the same class of caveat the csi300 bench already discloses
+for PIT index membership, not a lookahead in the price/valuation data.
+
+Endpoint contract (pinned by tests, verified live 2026-10-12):
+``index_member_all`` accepts ONLY the documented ``l1_code``/``l2_code``/
+``l3_code``/``ts_code``/``is_new`` filters — passing ``src`` (undocumented)
+silently returns an empty 200-row-columns frame, so ``src`` is used for
+``index_classify`` in the truncation fallback only. ``is_new`` defaults to
+"Y" server-side (current members, no out_date rows), so the historical
+half ("N") is fetched separately and concatenated — without it every label
+would be today's classification and the PIT claim above false.
+
+Truncation guard: ``index_member_all`` documents a 2000-row cap per call.
+A live full-permission token returns the whole snapshot in one call (~5900
+current + ~2000 historical rows), but a response of exactly 2000 rows is
+treated as truncated and refetched per L1 industry (``index_classify`` then
+one ``index_member_all(l1_code=..., is_new=...)`` call per industry).
+
+Degradation: a provider failure after backoff warns and returns an all-None
+frame aligned to ``index`` x ``symbols`` — the caller benches without the
+sector tag (``requires_sector`` alphas SkipAlpha) instead of crashing. A
+missing/placeholder ``TUSHARE_TOKEN`` raises ``RuntimeError`` like every
+sibling loader; no label is ever invented.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from backtest.loaders.tushare import (
+ TUSHARE_TOKEN_PLACEHOLDERS,
+ _call_with_backoff,
+)
+
+logger = logging.getLogger(__name__)
+
+#: Shenwan classification levels ``index_member_all`` serves name columns for.
+INDUSTRY_LEVELS: tuple[str, ...] = ("L1", "L2", "L3")
+
+_LEVEL_NAME_COLUMN = {"L1": "l1_name", "L2": "l2_name", "L3": "l3_name"}
+
+#: Documented per-call row cap of ``index_member_all``; a snapshot of exactly
+#: this size is treated as truncated and triggers the per-L1 refetch.
+_SNAPSHOT_ROW_CAP = 2000
+
+#: Sentinel standing in for a null ``out_date`` (still a member). Inside the
+#: ``datetime64[ns]`` range so int64 comparisons against trading days work.
+_OPEN_ENDED = pd.Timestamp("2262-01-01")
+
+
+def validate_industry_params(level: str, src: str) -> str:
+ """Validate the requested classification level and source.
+
+ Args:
+ level: Shenwan level, one of :data:`INDUSTRY_LEVELS`.
+ src: Classification source, e.g. ``"SW2021"``; must be non-empty.
+
+ Returns:
+ The ``index_member_all`` name column serving ``level``.
+
+ Raises:
+ ValueError: If ``level`` is unknown or ``src`` is empty.
+ """
+ if level not in INDUSTRY_LEVELS:
+ raise ValueError(
+ f"unsupported industry level {level!r}; expected one of {list(INDUSTRY_LEVELS)}"
+ )
+ if not isinstance(src, str) or not src.strip():
+ raise ValueError(f"src must be a non-empty string, got {src!r}")
+ return _LEVEL_NAME_COLUMN[level]
+
+
+def _build_api() -> Any:
+ """Build a Tushare pro API client from the configured token.
+
+ Raises:
+ RuntimeError: If ``TUSHARE_TOKEN`` is unset or a placeholder.
+ """
+ import tushare as ts
+
+ from src.config.accessor import get_env_config
+
+ token = get_env_config().data.tushare_token.strip()
+ if token in TUSHARE_TOKEN_PLACEHOLDERS:
+ raise RuntimeError(
+ "TUSHARE_TOKEN not configured; required for industry classification"
+ )
+ return ts.pro_api(token)
+
+
+def _fetch_membership_part(api: Any, src: str, is_new: str) -> pd.DataFrame | None:
+ """Fetch one ``is_new`` half of the snapshot, refetching per L1 if truncated."""
+ frame = _call_with_backoff(api.index_member_all, is_new=is_new)
+ if frame is None or len(frame) != _SNAPSHOT_ROW_CAP:
+ return frame
+ logger.warning(
+ "index_member_all(is_new=%s) returned exactly %d rows (documented per-call cap); "
+ "refetching per L1 industry",
+ is_new,
+ _SNAPSHOT_ROW_CAP,
+ )
+ classify = _call_with_backoff(api.index_classify, level="L1", src=src)
+ if classify is None or classify.empty or "index_code" not in classify.columns:
+ raise RuntimeError(
+ "index_classify served no L1 codes for the per-industry refetch"
+ )
+ parts = []
+ for code in classify["index_code"].astype(str):
+ part = _call_with_backoff(api.index_member_all, l1_code=code, is_new=is_new)
+ if part is not None and not part.empty:
+ parts.append(part)
+ if not parts:
+ return None
+ return pd.concat(parts, ignore_index=True)
+
+
+def _fetch_membership(api: Any, src: str) -> pd.DataFrame | None:
+ """Fetch the full PIT membership snapshot (current "Y" + historical "N").
+
+ Args:
+ api: Tushare pro API (real or injected fake).
+ src: Classification source — passed to ``index_classify`` only;
+ ``index_member_all`` rejects an undocumented ``src`` with a
+ silently empty response (see the module docstring).
+
+ Returns:
+ The concatenated membership rows, or None if nothing was served.
+
+ Raises:
+ Exception: The endpoint's own exception after backoff — the caller
+ decides whether that degrades or propagates.
+ """
+ parts = []
+ for is_new in ("Y", "N"):
+ part = _fetch_membership_part(api, src, is_new)
+ if part is not None and not part.empty:
+ parts.append(part)
+ if not parts:
+ return None
+ return pd.concat(parts, ignore_index=True)
+
+
+def load_industry_frame_with_coverage(
+ *,
+ symbols: Sequence[str],
+ start: str,
+ end: str,
+ index: pd.DatetimeIndex,
+ api: Any | None = None,
+ level: str = "L1",
+ src: str = "SW2021",
+) -> tuple[pd.DataFrame, float]:
+ """Load PIT industry labels as a wide frame plus a coverage fraction.
+
+ Args:
+ symbols: Panel symbols; only names present in the membership data get
+ a label, the rest stay NaN.
+ start: Period start (YYYY-MM-DD). Accepted for loader-contract
+ symmetry with ``valuation_loader``; PIT evaluation uses the actual
+ ``index`` dates, so an index reaching outside the window is still
+ labelled correctly.
+ end: Period end (YYYY-MM-DD), same contract note as ``start``.
+ index: Price-panel trading-day index the frame aligns to.
+ api: Optional pre-built Tushare pro API (tests inject fakes here).
+ level: Shenwan level, one of :data:`INDUSTRY_LEVELS`.
+ src: Classification source, e.g. ``"SW2021"``.
+
+ Returns:
+ ``(frame, coverage)`` — ``frame`` is ``dates x symbols`` with the
+ industry NAME (str) where a membership row covers the date and NaN
+ where none does (never an invented label); ``coverage`` is the
+ fraction of ``symbols`` with at least one label anywhere in the frame.
+
+ Raises:
+ ValueError: If ``level`` or ``src`` is invalid.
+ RuntimeError: If no API is injected and ``TUSHARE_TOKEN`` is missing.
+ """
+ name_column = validate_industry_params(level, src)
+ columns = list(symbols)
+ empty = pd.DataFrame(np.nan, index=index, columns=columns, dtype=object)
+ if not columns or len(index) == 0:
+ return empty, 0.0
+ logger.debug("industry frame requested for %s..%s (%d symbols)", start, end, len(columns))
+
+ if api is None:
+ api = _build_api()
+ try:
+ membership = _fetch_membership(api, src)
+ except Exception as exc: # noqa: BLE001 - degrade, never crash the caller
+ logger.warning(
+ "index_member_all industry fetch failed (%s); returning unmapped frame", exc
+ )
+ return empty, 0.0
+
+ if (
+ membership is None
+ or membership.empty
+ or "ts_code" not in membership.columns
+ or name_column not in membership.columns
+ # Without the PIT interval columns no membership can be established —
+ # degrade rather than guess a mapping from names alone.
+ or "in_date" not in membership.columns
+ or "out_date" not in membership.columns
+ ):
+ logger.warning(
+ "index_member_all served no usable membership rows (src=%s, level=%s)",
+ src,
+ level,
+ )
+ return empty, 0.0
+
+ rows = membership[membership["ts_code"].isin(columns)].copy()
+ in_dt = pd.to_datetime(rows.get("in_date"), format="%Y%m%d", errors="coerce")
+ out_dt = pd.to_datetime(rows.get("out_date"), format="%Y%m%d", errors="coerce")
+ labels = rows[name_column]
+ # A row with no in_date can never satisfy in_date <= d, and a row with no
+ # label has nothing to serve — dropped, never defaulted.
+ usable = in_dt.notna() & labels.notna() & (labels.astype(str).str.strip() != "")
+ rows, in_dt, labels = rows[usable], in_dt[usable], labels[usable]
+ out_dt = out_dt[usable].fillna(_OPEN_ENDED)
+ if rows.empty:
+ return empty, 0.0
+
+ # Later in_date wins, then later/open out_date: a fixed sort makes the
+ # per-date winner independent of API row order (dict(zip) keeps the last).
+ order = np.lexsort((out_dt.to_numpy(dtype="int64"), in_dt.to_numpy(dtype="int64")))
+ codes = rows["ts_code"].to_numpy()[order]
+ ordered_labels = labels.to_numpy()[order]
+ in_ns = in_dt.to_numpy(dtype="int64")[order]
+ out_ns = out_dt.to_numpy(dtype="int64")[order]
+
+ position = {symbol: j for j, symbol in enumerate(columns)}
+ values = np.full((len(index), len(columns)), np.nan, dtype=object)
+ for i, day_ns in enumerate(index.asi8):
+ applicable = (in_ns <= day_ns) & (day_ns < out_ns)
+ if not applicable.any():
+ continue
+ for symbol, label in dict(zip(codes[applicable], ordered_labels[applicable])).items():
+ values[i, position[symbol]] = label
+
+ frame = pd.DataFrame(values, index=index, columns=columns)
+ coverage = float(frame.notna().any(axis=0).mean())
+ if coverage < 1.0:
+ logger.warning(
+ "industry coverage %.1f%% of %d requested symbols (src=%s, level=%s)",
+ coverage * 100,
+ len(columns),
+ src,
+ level,
+ )
+ return frame, coverage
+
+
+def load_industry_frame(
+ *,
+ symbols: Sequence[str],
+ start: str,
+ end: str,
+ index: pd.DatetimeIndex,
+ api: Any | None = None,
+ level: str = "L1",
+ src: str = "SW2021",
+) -> pd.DataFrame:
+ """Load PIT industry labels as a wide ``dates x symbols`` frame.
+
+ Thin wrapper over :func:`load_industry_frame_with_coverage` for callers
+ that do not need the coverage fraction; same contract, same degradation.
+ """
+ frame, _ = load_industry_frame_with_coverage(
+ symbols=symbols, start=start, end=end, index=index, api=api, level=level, src=src
+ )
+ return frame
diff --git a/agent/mcp_server.py b/agent/mcp_server.py
index b718408d7..b6e16b34a 100644
--- a/agent/mcp_server.py
+++ b/agent/mcp_server.py
@@ -896,6 +896,7 @@ def alpha_bench(
alpha_id: str | None = None,
zoo: str | None = None,
top: int = 20,
+ horizon: int = 1,
output_dir: str | None = None,
) -> str:
"""Benchmark one Alpha Zoo alpha or a complete zoo on a universe.
@@ -906,6 +907,10 @@ def alpha_bench(
alpha_id: Optional single alpha id; mutually exclusive with ``zoo``.
zoo: Optional zoo id; mutually exclusive with ``alpha_id``.
top: Number of top-ranked alphas to include in the report.
+ horizon: Forward-return horizon in bars (default 1 = next-bar).
+ ``h > 1`` computes h-bar forward returns and samples IC rows
+ non-overlapping (end-anchored); 21 ≈ monthly, the conventional
+ horizon for fundamental factors. Range 1-252.
output_dir: Optional directory for the generated HTML report.
"""
if not alpha_id and not zoo:
@@ -928,7 +933,7 @@ def alpha_bench(
try:
from datetime import date
- from src.tools.alpha_bench_tool import _parse_period
+ from src.tools.alpha_bench_tool import _MAX_HORIZON, _parse_period
start_raw, end_raw = _parse_period(period)
start_date = date.fromisoformat(start_raw)
@@ -957,10 +962,20 @@ def alpha_bench(
ensure_ascii=False,
)
+ if isinstance(horizon, bool) or not isinstance(horizon, int) or not 1 <= horizon <= _MAX_HORIZON:
+ return json.dumps(
+ {
+ "status": "error",
+ "error": f"MCP alpha_bench horizon must be an integer between 1 and {_MAX_HORIZON}",
+ },
+ ensure_ascii=False,
+ )
+
params: dict[str, Any] = {
"universe": universe,
"period": period,
"top": top,
+ "horizon": horizon,
}
if alpha_id is not None:
params["alpha_id"] = alpha_id
diff --git a/agent/src/factors/base.py b/agent/src/factors/base.py
index 4cd3a3e1e..b2a8a7c21 100644
--- a/agent/src/factors/base.py
+++ b/agent/src/factors/base.py
@@ -96,6 +96,75 @@ def zscore(df: pd.DataFrame) -> pd.DataFrame:
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``.
diff --git a/agent/src/factors/bench_runner.py b/agent/src/factors/bench_runner.py
index 111c4ffd5..b954a94ce 100644
--- a/agent/src/factors/bench_runner.py
+++ b/agent/src/factors/bench_runner.py
@@ -37,7 +37,7 @@ from src.factors.registry import (
SkipAlpha,
get_default_registry,
)
-from src.tools.alpha_bench_tool import _compute_forward_returns, _load_universe_panel, _prepare_bench_panel, _validate_bench_data_requirements
+from src.tools.alpha_bench_tool import _MAX_HORIZON, _compute_forward_returns, _load_universe_panel, _prepare_bench_panel, _split_alphas_by_universe_support, _validate_bench_data_requirements
logger = logging.getLogger(__name__)
@@ -108,7 +108,12 @@ def t_stat(ic_mean: float, ic_std: float, n: int) -> float:
def categorise(row: dict[str, Any]) -> str:
- """Bucket a per-alpha row into alive / reversed / dead."""
+ """Bucket a per-alpha row into alive / reversed / dead.
+
+ Thresholds are calibrated on daily next-bar ICs; at horizon h > 1 the
+ |IC| > 0.02 floor is a looser bar (h-bar ICs are naturally larger in
+ magnitude). The run envelope states its own horizon.
+ """
ic_mean = row["ic_mean"]
pos = row["ic_positive_ratio"]
t = t_stat(ic_mean, row["ic_std"], row["ic_count"])
@@ -143,6 +148,7 @@ def run_bench(
registry: Registry | None = None,
only: Iterable[str] | None = None,
on_stage: Callable[[str], None] | None = None,
+ horizon: int = 1,
) -> dict[str, Any]:
"""Run a bench end-to-end and return the API-shaped summary.
@@ -161,11 +167,17 @@ def run_bench(
alpha list is restricted to this set — used by ``alpha compare`` to
bench just a handful of named alphas instead of the whole zoo. Ids
not registered under ``zoo`` are silently dropped from the subset.
+ horizon: Forward-return horizon in bars (default 1 = next-bar,
+ unchanged behaviour). ``h > 1`` computes h-bar forward returns
+ sampled non-overlapping (end-anchored) so the naive-iid t-stat
+ stays honest; 21 ≈ monthly, the conventional horizon for
+ fundamental factors.
Returns:
Dict with keys: ``status``, ``zoo``, ``universe``, ``period``,
- ``n_alphas_tested``, ``n_skipped``, ``alive``, ``reversed``, ``dead``,
- ``by_theme``, ``top5_by_ir``, ``dead_examples``, ``wall_seconds`` —
+ ``horizon``, ``forward_return_sampling``, ``n_alphas_tested``,
+ ``n_skipped``, ``alive``, ``reversed``, ``dead``, ``by_theme``,
+ ``top5_by_ir``, ``dead_examples``, ``wall_seconds`` —
and on failure: ``status="error"``, ``error``.
"""
start = time.monotonic()
@@ -174,8 +186,24 @@ def run_bench(
"zoo": zoo,
"universe": universe,
"period": period,
+ "horizon": horizon,
+ "forward_return_sampling": (
+ "non_overlapping"
+ if isinstance(horizon, int) and not isinstance(horizon, bool) and horizon > 1
+ else "daily"
+ ),
}
+ # Fail fast before any panel load (network): same 1.._MAX_HORIZON contract
+ # the tool and MCP wrapper enforce.
+ if isinstance(horizon, bool) or not isinstance(horizon, int) or not 1 <= horizon <= _MAX_HORIZON:
+ entry["status"] = "error"
+ entry["error"] = (
+ f"horizon must be an integer between 1 and {_MAX_HORIZON}, got {horizon!r}"
+ )
+ entry["wall_seconds"] = round(time.monotonic() - start, 2)
+ return entry
+
reg = registry if registry is not None else get_default_registry()
alpha_ids = reg.list(zoo=zoo)
if not alpha_ids:
@@ -193,6 +221,25 @@ def run_bench(
entry["wall_seconds"] = round(time.monotonic() - start, 2)
return entry
+ alpha_ids, universe_excluded = _split_alphas_by_universe_support(reg, alpha_ids, universe)
+ if universe_excluded:
+ entry["universe_excluded"] = universe_excluded
+ logger.info(
+ "bench: %d alpha(s) excluded on %s — fund:* inputs need SEC US filings (sp500): %s",
+ len(universe_excluded),
+ universe,
+ ", ".join(universe_excluded[:10]),
+ )
+ if not alpha_ids:
+ entry["status"] = "error"
+ entry["error"] = (
+ f"all {len(universe_excluded)} selected alphas require SEC US filings "
+ f"(fund:* inputs); the {universe!r} universe cannot serve them. "
+ "Choose the S&P 500 universe."
+ )
+ entry["wall_seconds"] = round(time.monotonic() - start, 2)
+ return entry
+
try:
_validate_bench_data_requirements(reg, alpha_ids, universe)
if on_stage:
@@ -208,7 +255,7 @@ def run_bench(
panel = _prepare_bench_panel(reg, alpha_ids, panel, universe, period)
if on_stage:
on_stage("preparing_returns")
- return_df = _compute_forward_returns(panel)
+ return_df = _compute_forward_returns(panel, horizon=horizon)
except Exception as exc: # noqa: BLE001
entry["status"] = "error"
entry["error"] = f"forward returns failed: {exc}"
diff --git a/agent/src/factors/bench_runner_strict.py b/agent/src/factors/bench_runner_strict.py
index d26fb1da9..0bd31ddd1 100644
--- a/agent/src/factors/bench_runner_strict.py
+++ b/agent/src/factors/bench_runner_strict.py
@@ -63,7 +63,7 @@ from src.factors.registry import (
SkipAlpha,
get_default_registry,
)
-from src.tools.alpha_bench_tool import _compute_forward_returns, _load_universe_panel
+from src.tools.alpha_bench_tool import _MAX_HORIZON, _compute_forward_returns, _load_universe_panel
logger = logging.getLogger(__name__)
@@ -325,6 +325,7 @@ def run_bench_strict(
training_cutoff: str | None = None,
thresholds: StrictThresholds | None = None,
top: int = 20,
+ horizon: int = 1,
on_progress: ProgressCb | None = None,
registry: Registry | None = None,
) -> dict[str, Any]:
@@ -352,6 +353,11 @@ def run_bench_strict(
Harvey-Liu-Zhu (2016) multiple-testing correction when bench
covers a large zoo.
top: How many top-IR alphas to keep in summary lists.
+ horizon: Forward-return horizon in bars (default 1 = next-bar,
+ unchanged behaviour). ``h > 1`` computes h-bar forward returns
+ sampled non-overlapping (end-anchored) so the naive-iid t-stats
+ stay honest; 21 ≈ monthly, the conventional horizon for
+ fundamental factors.
on_progress: Optional ``(n_done, n_total, alpha_id)`` callback.
registry: Optional pre-built registry for tests.
@@ -395,6 +401,12 @@ def run_bench_strict(
"zoo": zoo,
"universe": universe,
"period": period,
+ "horizon": horizon,
+ "forward_return_sampling": (
+ "non_overlapping"
+ if isinstance(horizon, int) and not isinstance(horizon, bool) and horizon > 1
+ else "daily"
+ ),
"random_control": random_control,
"n_random_seeds": effective_seeds,
"oos_split": effective_oos_split,
@@ -430,6 +442,13 @@ def run_bench_strict(
if training_cutoff is not None and oos_split is not None:
return _finish_error("pass either training_cutoff or oos_split, not both")
+ # Fail fast before any panel load (network): same 1.._MAX_HORIZON contract
+ # the tool and MCP wrapper enforce.
+ if isinstance(horizon, bool) or not isinstance(horizon, int) or not 1 <= horizon <= _MAX_HORIZON:
+ return _finish_error(
+ f"horizon must be an integer between 1 and {_MAX_HORIZON}, got {horizon!r}"
+ )
+
reg = registry if registry is not None else get_default_registry()
alpha_ids = reg.list(zoo=zoo)
if not alpha_ids:
@@ -441,7 +460,7 @@ def run_bench_strict(
return _finish_error(f"universe load failed: {exc}")
try:
- return_df = _compute_forward_returns(panel)
+ return_df = _compute_forward_returns(panel, horizon=horizon)
except Exception as exc: # noqa: BLE001
return _finish_error(f"forward returns failed: {exc}")
diff --git a/agent/src/factors/cli_handlers.py b/agent/src/factors/cli_handlers.py
index 79aba4e41..5d080b147 100644
--- a/agent/src/factors/cli_handlers.py
+++ b/agent/src/factors/cli_handlers.py
@@ -492,6 +492,8 @@ def _run_all_zoos_with_progress(
total_alphas = sum(len(reg.list(zoo=z)) for z in zoos)
all_rows: list[dict[str, Any]] = []
all_skipped: list[dict[str, Any]] = []
+ all_excluded: list[str] = []
+ run_config: dict[str, Any] = {}
def _run_zoo(z: str, base: int, update: Callable[[int, str], None] | None) -> None:
cb: Callable[[int, int, str], None] | None = None
@@ -506,6 +508,10 @@ def _run_all_zoos_with_progress(
on_progress=cb,
registry=reg,
)
+ if not run_config and "horizon" in sub:
+ run_config["horizon"] = sub["horizon"]
+ run_config["forward_return_sampling"] = sub.get("forward_return_sampling")
+ all_excluded.extend(sub.get("universe_excluded", []) or [])
if sub.get("status") == "ok":
all_rows.extend(sub.get("rows", []) or [])
all_skipped.extend(sub.get("skipped", []) or [])
@@ -549,6 +555,8 @@ def _run_all_zoos_with_progress(
"skipped": all_skipped,
"n_alphas_tested": len(all_rows),
"n_skipped": len(all_skipped),
+ **run_config,
+ **({"universe_excluded": all_excluded} if all_excluded else {}),
"wall_seconds": round(time.monotonic() - start_ts, 2),
**({"error": "no alphas produced IC across any zoo"} if not all_rows else {}),
}
@@ -563,6 +571,17 @@ def cmd_alpha_bench(args: argparse.Namespace) -> int:
"""
_load_cli_env()
try:
+ from src.tools.alpha_bench_tool import _MAX_HORIZON
+
+ horizon = getattr(args, "horizon", 1)
+ horizon = 1 if horizon is None else int(horizon)
+ if not 1 <= horizon <= _MAX_HORIZON:
+ # Usage error → argparse's exit-code convention (2), not a traceback.
+ _err(
+ f"alpha bench: --horizon must be an integer in 1..{_MAX_HORIZON} "
+ f"(got {horizon})."
+ )
+ return 2
if (
getattr(args, "oos_split", None)
or getattr(args, "training_cutoff", None)
@@ -583,9 +602,12 @@ def cmd_alpha_bench(args: argparse.Namespace) -> int:
n_random_seeds=max(1, int(getattr(args, "random_seeds", 5) or 5)),
oos_split=getattr(args, "oos_split", None),
training_cutoff=getattr(args, "training_cutoff", None),
+ horizon=horizon,
)
else:
- from src.factors.bench_runner import run_bench
+ from src.factors.bench_runner import run_bench as _run_bench_plain
+
+ run_bench = functools.partial(_run_bench_plain, horizon=horizon)
except ImportError as exc:
_err(f"alpha bench failed: bench_runner unavailable ({exc})")
return 1
@@ -780,6 +802,12 @@ def cmd_alpha_bench(args: argparse.Namespace) -> int:
"top": top_rows,
"wall_seconds": result.get("wall_seconds"),
}
+ # Run-config disclosure: a saved envelope must state its own horizon,
+ # sampling and any universe-based exclusions — numbers that show
+ # where they came from.
+ for key in ("horizon", "forward_return_sampling", "universe_excluded"):
+ if key in result:
+ envelope[key] = result[key]
if getattr(args, "strict", False):
envelope["strict"] = True
for key in ("confirmed_alive", "train_only", "reversed_strict", "noise"):
@@ -944,6 +972,27 @@ def cmd_alpha_export_manifest(args: argparse.Namespace) -> int:
# --------------------------------------------------------------------------- #
+def _horizon_arg(value: str) -> int:
+ """argparse type for ``--horizon``: integer in 1.._MAX_HORIZON.
+
+ Raising ``ArgumentTypeError`` makes argparse exit with its usage-error
+ code (2) instead of letting a bad value reach the bench engine.
+ """
+ from src.tools.alpha_bench_tool import _MAX_HORIZON
+
+ try:
+ ivalue = int(value)
+ except ValueError:
+ raise argparse.ArgumentTypeError(
+ f"--horizon expects an integer in 1..{_MAX_HORIZON}, got {value!r}"
+ ) from None
+ if not 1 <= ivalue <= _MAX_HORIZON:
+ raise argparse.ArgumentTypeError(
+ f"--horizon must be in 1..{_MAX_HORIZON} (got {ivalue})"
+ )
+ return ivalue
+
+
_DISPATCH: dict[str, Callable[[argparse.Namespace], int]] = {
"list": cmd_alpha_list,
"show": cmd_alpha_show,
@@ -1036,6 +1085,17 @@ def add_subparser(subparsers: Any) -> argparse.ArgumentParser:
help="Period spec: YYYY-YYYY or YYYY-MM-DD/YYYY-MM-DD (e.g. 2020-2025)",
)
p_bench.add_argument("--top", type=int, default=20, help="Top-N alphas to keep (default: 20)")
+ p_bench.add_argument(
+ "--horizon",
+ type=_horizon_arg,
+ default=1,
+ help=(
+ "Forward-return horizon in bars, range 1-252 (default: 1 = next-bar). "
+ "h>1 computes h-bar forward returns and samples IC non-overlapping "
+ "(end-anchored); 21 ≈ monthly, the conventional horizon for "
+ "fundamental factors."
+ ),
+ )
p_bench.add_argument(
"--strict",
action="store_true",
diff --git a/agent/src/factors/compare_runner.py b/agent/src/factors/compare_runner.py
index 4b87661fa..19f662be2 100644
--- a/agent/src/factors/compare_runner.py
+++ b/agent/src/factors/compare_runner.py
@@ -166,6 +166,13 @@ def compare_alphas(
row.setdefault("zoo", zoo)
rows.append(row)
skipped.extend(sub.get("skipped", []) or [])
+ skipped.extend(
+ {
+ "id": aid,
+ "reason": f"excluded on {universe}: fund:* inputs need SEC US filings (sp500)",
+ }
+ for aid in sub.get("universe_excluded", []) or []
+ )
else:
reason = sub.get("error", "bench failed")
skipped.extend({"id": aid, "reason": reason} for aid in zids)
diff --git a/agent/src/factors/zoo/fundamental/dividend_yield_ind_neutral.py b/agent/src/factors/zoo/fundamental/dividend_yield_ind_neutral.py
new file mode 100644
index 000000000..1ea05a68f
--- /dev/null
+++ b/agent/src/factors/zoo/fundamental/dividend_yield_ind_neutral.py
@@ -0,0 +1,46 @@
+"""Industry-neutralized fundamental dividend-yield (TTM) value factor (CN daily market data)."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from src.factors.base import zscore_by_group
+
+__alpha_meta__ = {
+ "id": "fund_dividend_yield_ind_neutral",
+ "nickname": "Dividend yield TTM industry-neutral - within-industry dv_ttm (daily market data)",
+ "theme": ["value"],
+ "formula_latex": r"\mathrm{zscore}_{x\mid\mathrm{industry}}(\mathrm{DY_{TTM}})",
+ "columns_required": ["val:dv_ttm"],
+ "requires_sector": True,
+ "universe": ["equity_cn"],
+ "frequency": ["1d"],
+ "decay_horizon": 252,
+ "min_warmup_bars": 1,
+ "notes": (
+ "Industry-neutralized trailing dividend yield: each name is z-scored "
+ "against its Shenwan level-1 industry peers instead of the whole "
+ "cross-section (sector tag from tushare index_member_all SW2021 "
+ "membership, point-in-time via in_date/out_date). This removes the "
+ "industry confounding that dominates raw A-share dividend yield — "
+ "mature banks and utilities pay structurally high dividends while "
+ "growth industries pay almost none, so a raw high-yield screen is "
+ "largely an industry bet. High dividend yield relative to industry "
+ "peers scores high; dv_ttm is reported in percent units and "
+ "cross-sectional z-scoring is scale-invariant, so no unit "
+ "conversion is applied. A name with no industry label on a date "
+ "stays NaN and is excluded from that date's cross-section; an "
+ "industry group with fewer than two labelled names cannot form a "
+ "within-group z-score and stays NaN. Keyed by trade_date, so "
+ "PIT-safe by construction with no filing lag. Membership is "
+ "point-in-time but the SW2021 taxonomy itself is retroactive — a "
+ "name reclassified in 2021 carries its 2021 industry back through "
+ "history. Lineage: "
+ "industry-neutral variant of fund_dividend_yield (#1789 follow-up)."
+ ),
+}
+
+
+def compute(panel: dict[str, pd.DataFrame]) -> pd.DataFrame:
+ """Return within-industry z-scored trailing dividend yield."""
+ return zscore_by_group(panel["val:dv_ttm"], panel["sector"])
diff --git a/agent/src/factors/zoo/fundamental/pb_ind_neutral.py b/agent/src/factors/zoo/fundamental/pb_ind_neutral.py
new file mode 100644
index 000000000..4f75eb7e6
--- /dev/null
+++ b/agent/src/factors/zoo/fundamental/pb_ind_neutral.py
@@ -0,0 +1,46 @@
+"""Industry-neutralized fundamental price-to-book value factor (CN daily market data)."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from src.factors.base import zscore_by_group
+
+__alpha_meta__ = {
+ "id": "fund_pb_ind_neutral",
+ "nickname": "P/B industry-neutral - inverse within-industry price-to-book (daily market data)",
+ "theme": ["value"],
+ "formula_latex": r"-\mathrm{zscore}_{x\mid\mathrm{industry}}(\mathrm{PB})",
+ "columns_required": ["val:pb"],
+ "requires_sector": True,
+ "universe": ["equity_cn"],
+ "frequency": ["1d"],
+ "decay_horizon": 252,
+ "min_warmup_bars": 1,
+ "notes": (
+ "Nonpositive multiples are excluded rather than ranked as cheap. "
+ "Industry-neutralized inverse price-to-book: each name is z-scored "
+ "against its Shenwan level-1 industry peers instead of the whole "
+ "cross-section (sector tag from tushare index_member_all SW2021 "
+ "membership, point-in-time via in_date/out_date). This removes the "
+ "industry confounding that dominates raw A-share PB — banks and "
+ "cyclicals are structurally cheap on book value while technology "
+ "names are structurally expensive, so a raw low-PB screen is largely "
+ "an industry bet. Low PB relative to industry peers scores high. A "
+ "name with no industry label on a date stays NaN and is excluded "
+ "from that date's cross-section; an industry group with fewer than "
+ "two labelled names cannot form a within-group z-score and stays "
+ "NaN. Keyed by trade_date, so PIT-safe by construction with no "
+ "filing lag. Membership is point-in-time but the SW2021 taxonomy "
+ "itself is retroactive — a name reclassified in 2021 carries its "
+ "2021 industry back through history. Lineage: industry-neutral "
+ "variant of fund_pb (#1789 "
+ "follow-up)."
+ ),
+}
+
+
+def compute(panel: dict[str, pd.DataFrame]) -> pd.DataFrame:
+ """Return within-industry z-scored inverse price-to-book."""
+ values = panel["val:pb"]
+ return -zscore_by_group(values.where(values > 0), panel["sector"])
diff --git a/agent/src/factors/zoo/fundamental/ps_ttm_ind_neutral.py b/agent/src/factors/zoo/fundamental/ps_ttm_ind_neutral.py
new file mode 100644
index 000000000..87fe97dfe
--- /dev/null
+++ b/agent/src/factors/zoo/fundamental/ps_ttm_ind_neutral.py
@@ -0,0 +1,48 @@
+"""Industry-neutralized fundamental price-to-sales (TTM) value factor (CN daily market data)."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from src.factors.base import zscore_by_group
+
+__alpha_meta__ = {
+ "id": "fund_ps_ttm_ind_neutral",
+ "nickname": "P/S TTM industry-neutral - inverse within-industry price-to-sales (daily market data)",
+ "theme": ["value"],
+ "formula_latex": r"-\mathrm{zscore}_{x\mid\mathrm{industry}}(\mathrm{PS_{TTM}})",
+ "columns_required": ["val:ps_ttm"],
+ "requires_sector": True,
+ "universe": ["equity_cn"],
+ "frequency": ["1d"],
+ "decay_horizon": 252,
+ "min_warmup_bars": 1,
+ "notes": (
+ "Nonpositive multiples are excluded rather than ranked as cheap. "
+ "Industry-neutralized inverse trailing price-to-sales: each name is "
+ "z-scored against its Shenwan level-1 industry peers instead of the "
+ "whole cross-section (sector tag from tushare index_member_all "
+ "SW2021 membership, point-in-time via in_date/out_date). This "
+ "removes the industry confounding that dominates raw A-share PS — "
+ "software and platform names carry structurally high margins and "
+ "high PS while distributors and manufacturers are structurally "
+ "low, so a raw low-PS screen is largely an industry bet. Low PS "
+ "relative to industry peers scores high, and PS stays informative "
+ "for loss-making names where earnings yield fails. A name with no "
+ "industry label on a date stays NaN and is excluded from that "
+ "date's cross-section; an industry group with fewer than two "
+ "labelled names cannot form a within-group z-score and stays NaN. "
+ "Keyed by trade_date, so PIT-safe by construction with no filing "
+ "lag. Membership is point-in-time but the SW2021 taxonomy itself "
+ "is retroactive — a name reclassified in 2021 carries its 2021 "
+ "industry back through history. Lineage: industry-neutral variant "
+ "of fund_ps_ttm (#1789 "
+ "follow-up)."
+ ),
+}
+
+
+def compute(panel: dict[str, pd.DataFrame]) -> pd.DataFrame:
+ """Return within-industry z-scored inverse price-to-sales (TTM)."""
+ values = panel["val:ps_ttm"]
+ return -zscore_by_group(values.where(values > 0), panel["sector"])
diff --git a/agent/src/tools/alpha_bench_tool.py b/agent/src/tools/alpha_bench_tool.py
index 0f0606875..574ceca73 100644
--- a/agent/src/tools/alpha_bench_tool.py
+++ b/agent/src/tools/alpha_bench_tool.py
@@ -465,6 +465,11 @@ def _load_csi300_panel(start: str, end: str) -> dict[str, pd.DataFrame]:
# Prices are corporate-action adjusted; raw pro.daily is not.
"price_adjustment": "qfq",
"dropped_unadjustable": len(dropped),
+ # Sector labels attach later, outside the pickled price panel (see
+ # _attach_sector_column); null/0.0 until then, and they stay that way
+ # when the loader degrades or the coverage gate refuses the tag.
+ "sector_source": None,
+ "sector_coverage": 0.0,
}
return panel
@@ -699,6 +704,40 @@ def _validate_bench_data_requirements(registry: Any, alpha_ids: list[str], unive
return columns
+def _split_alphas_by_universe_support(
+ registry: Any, alpha_ids: list[str], universe: str
+) -> tuple[list[str], list[str]]:
+ """Split the selection into (benchable, excluded) for this universe.
+
+ ``fund:*`` inputs are served from SEC US filings, which only the sp500
+ panel carries; on any other universe the declaring alphas are excluded
+ with disclosure instead of failing the whole bench — the mirror of the
+ sp500 path, where CN ``val:*`` alphas SkipAlpha cleanly on missing
+ columns. ``_validate_bench_data_requirements`` remains the backstop for
+ callers that bypass this split.
+
+ Args:
+ registry: Registry holding the selected factors.
+ alpha_ids: Factors selected for the bench.
+ universe: Requested stock universe.
+
+ Returns:
+ ``(kept, excluded)`` — alphas benchable on this universe, and alphas
+ excluded because they declare ``fund:*`` columns off sp500.
+ """
+ if universe == "sp500":
+ return list(alpha_ids), []
+ kept: list[str] = []
+ excluded: list[str] = []
+ for aid in alpha_ids:
+ columns = (registry.get(aid).meta or {}).get("columns_required", [])
+ if any(str(column).startswith("fund:") for column in columns):
+ excluded.append(aid)
+ else:
+ kept.append(aid)
+ return kept, excluded
+
+
def _val_columns_required(registry: Any, alpha_ids: list[str], panel: dict) -> list[str]:
"""Collect declared ``val:*`` columns missing from the panel.
@@ -757,6 +796,72 @@ def _attach_valuation_columns(
return enriched
+# Same gate as _SP500_MIN_SECTOR_COVERAGE, same reasoning: a mostly-unlabelled
+# panel would z-score one big bucket, which is the global cross-section wearing
+# an industry-neutral label. Below the gate the tag stays off and the
+# requires_sector alphas SkipAlpha cleanly.
+_CSI300_MIN_SECTOR_COVERAGE = 0.9
+
+
+def _attach_sector_column(enriched: dict, panel: dict, start: str, end: str) -> dict:
+ """Attach PIT SW2021 L1 industry labels as ``sector`` for a CN universe.
+
+ The csi300 counterpart of the sp500 Wikipedia-GICS attach: labels come
+ from tushare ``index_member_all`` (point-in-time via in_date/out_date),
+ align to the price panel and inherit its PIT membership mask through
+ ``.where(close.notna())`` — the same trick the ``val:*`` attach uses.
+ Attached here, not in ``_load_csi300_panel``, so the labels never enter
+ the pickled price-panel cache. ``sector_coverage`` in ``_meta`` is the
+ fraction of panel columns with at least one non-null label anywhere in
+ the window — per-date coverage can be lower; unlabelled cells stay NaN
+ through ``zscore_by_group``.
+
+ Never raises: no token or a provider failure leaves the tag off (the
+ loader degrades to an all-None frame; ``RuntimeError`` on a missing token
+ is caught here) and ``_meta`` keeps ``sector_source=None`` as disclosure.
+
+ Args:
+ enriched: Panel copy being extended.
+ panel: Observed price panel (source of the cross-section mask).
+ start: Period start (YYYY-MM-DD).
+ end: Period end (YYYY-MM-DD).
+
+ Returns:
+ The enriched panel, with ``sector`` and updated ``_meta`` when the
+ coverage gate passes.
+ """
+ from backtest.loaders.industry_loader import load_industry_frame
+
+ close = panel["close"]
+ try:
+ labels = load_industry_frame(
+ symbols=list(close.columns), start=start, end=end, index=close.index
+ )
+ except Exception as exc: # noqa: BLE001 — enrichment, never fatal to the bench
+ logger.warning(
+ "csi300: industry loader failed (%s); benching without the sector tag", exc
+ )
+ return enriched
+
+ sector = labels.reindex(index=close.index, columns=close.columns).where(close.notna())
+ coverage = float(sector.notna().any(axis=0).mean()) if sector.shape[1] else 0.0
+ if coverage < _CSI300_MIN_SECTOR_COVERAGE:
+ logger.warning(
+ "csi300: sector coverage %.1f%% below %.0f%% — leaving the tag off so "
+ "industry-neutralized alphas skip rather than z-score one bucket",
+ coverage * 100,
+ _CSI300_MIN_SECTOR_COVERAGE * 100,
+ )
+ else:
+ enriched["sector"] = sector
+ enriched["_meta"] = {
+ **enriched.get("_meta", {}),
+ "sector_source": "tushare index_member_all SW2021 L1" if "sector" in enriched else None,
+ "sector_coverage": round(coverage, 4),
+ }
+ return enriched
+
+
def _prepare_bench_panel(registry: Any, alpha_ids: list[str], panel: dict, universe: str, period: str) -> dict:
"""Load only the declared PIT fundamental inputs for the selected factors.
@@ -765,12 +870,15 @@ def _prepare_bench_panel(registry: Any, alpha_ids: list[str], panel: dict, unive
alpha_ids: Selected factor identifiers.
panel: Observed price panel; never mutated or filled with invented values.
universe: Stock universe; SEC fundamentals currently cover US stocks,
- ``val:*`` daily valuation columns cover the CN universe only —
- other universes skip them and declaring alphas SkipAlpha.
+ ``val:*`` daily valuation columns and the PIT ``sector`` tag cover
+ the CN universe only — other universes skip them and declaring
+ alphas SkipAlpha.
period: Requested historical period.
Returns:
- A panel including the required fundamental columns.
+ A panel including the required fundamental columns and, when a
+ selected csi300 alpha declares ``requires_sector``, the ``sector``
+ label frame.
Raises:
ValueError: If SEC inputs are requested for a non-US universe, or a
@@ -779,7 +887,12 @@ def _prepare_bench_panel(registry: Any, alpha_ids: list[str], panel: dict, unive
"""
columns = [column for column in _validate_bench_data_requirements(registry, alpha_ids, universe) if column not in panel]
val_columns = _val_columns_required(registry, alpha_ids, panel) if universe == "csi300" else []
- if not columns and not val_columns:
+ needs_sector = (
+ universe == "csi300"
+ and "sector" not in panel
+ and any((registry.get(aid).meta or {}).get("requires_sector") for aid in alpha_ids)
+ )
+ if not columns and not val_columns and not needs_sector:
return panel
start, end = _parse_period(period)
@@ -800,16 +913,71 @@ def _prepare_bench_panel(registry: Any, alpha_ids: list[str], panel: dict, unive
enriched["_meta"] = {**enriched.get("_meta", {}), "fundamental_source": "sec", "fundamental_pit": True, "fundamental_pit_lag_bars": 1}
if val_columns:
enriched = _attach_valuation_columns(enriched, panel, val_columns, start, end)
+ if needs_sector:
+ enriched = _attach_sector_column(enriched, panel, start, end)
return enriched
-def _compute_forward_returns(panel: dict[str, pd.DataFrame]) -> pd.DataFrame:
- """Next-bar forward simple returns from close, aligned to factor timestamp."""
+# Cap for the tool-level bench horizon parameter: 252 bars ≈ one trading year.
+# Beyond that a typical bench period leaves almost no non-overlapping IC
+# samples, so the t-stat stops meaning anything.
+_MAX_HORIZON = 252
+
+
+def _validate_horizon(value: Any) -> int:
+ """Validate the bench ``horizon`` parameter (integer, 1.._MAX_HORIZON).
+
+ ``None`` is treated as "not supplied" and defaults to 1, matching how
+ ``run_alpha_bench`` tolerates absent optional kwargs.
+ """
+ if value is None:
+ return 1
+ if isinstance(value, bool) or not isinstance(value, int):
+ raise ValueError(
+ f"horizon must be an integer between 1 and {_MAX_HORIZON}, got {value!r}"
+ )
+ if not 1 <= value <= _MAX_HORIZON:
+ raise ValueError(
+ f"horizon must be an integer between 1 and {_MAX_HORIZON}, got {value}"
+ )
+ return value
+
+
+def _compute_forward_returns(panel: dict[str, pd.DataFrame], horizon: int = 1) -> pd.DataFrame:
+ """Forward simple returns over ``horizon`` bars, aligned to the factor timestamp.
+
+ ``horizon=1`` keeps the historical next-bar formula byte-for-byte. For
+ ``horizon=h > 1`` the return at row t is ``close[t+h]/close[t] - 1``,
+ sampled non-overlapping and end-anchored (see the inline comment) so the
+ naive-iid t-stat downstream stays honest.
+ """
+ if isinstance(horizon, bool) or not isinstance(horizon, int) or horizon < 1:
+ raise ValueError(f"horizon must be an integer >= 1, got {horizon!r}")
close = panel.get("close")
if close is None:
raise ValueError("panel missing 'close' — cannot derive forward returns")
- # Next-period return aligned to current row (use t+1 close, shift back).
- fwd = close.pct_change(fill_method=None).shift(-1)
+ if horizon == 1:
+ # Next-period return aligned to current row (use t+1 close, shift back).
+ fwd = close.pct_change(fill_method=None).shift(-1)
+ return fwd
+ # h-bar return aligned to row t: close[t+h]/close[t] - 1. Deliberately no
+ # pct_change/ffill anywhere: a NaN close at t or t+h must yield a NaN
+ # return, so halted names never bridge a return across a missing bar.
+ fwd = (close.shift(-horizon) / close) - 1
+ # Sample non-overlapping windows anchored to the END of the frame: keep
+ # row t iff (n_rows - 1 - t) % h == 0, so the most recent complete window
+ # is always sampled. Overlapping h-bar windows share h-1 bars of price
+ # data, which autocorrelates consecutive ICs and inflates the naive-iid
+ # t-stat by ~sqrt(h); keeping every h-th row removes that dominant
+ # mechanical inflation, so the existing t_stat/categorise math is a
+ # defensible approximation (standard monthly-IC practice). Residual
+ # autocorrelation from persistent factor exposures is not modeled.
+ n_rows = len(fwd.index)
+ if n_rows:
+ positions = np.arange(n_rows)
+ drop = ((n_rows - 1 - positions) % horizon) != 0
+ if drop.any():
+ fwd.iloc[drop] = np.nan
return fwd
@@ -1104,6 +1272,11 @@ def run_alpha_bench(**kwargs: Any) -> dict[str, Any]:
if top_n <= 0:
return {"status": "error", "error": "top must be > 0"}
+ try:
+ horizon = _validate_horizon(kwargs.get("horizon", 1))
+ except ValueError as exc:
+ return {"status": "error", "error": str(exc)}
+
output_dir_raw = kwargs.get("output_dir") or str(_default_output_dir())
output_dir = Path(output_dir_raw).expanduser().resolve()
@@ -1135,6 +1308,25 @@ def run_alpha_bench(**kwargs: Any) -> dict[str, Any]:
"error": "no alphas matched the selection (registry empty or filters too narrow)",
}
+ alpha_ids, universe_excluded = _split_alphas_by_universe_support(registry, alpha_ids, universe)
+ if not alpha_ids:
+ return {
+ "status": "error",
+ "error": (
+ f"all {len(universe_excluded)} selected alphas require SEC US filings "
+ f"(fund:* inputs); the {universe!r} universe cannot serve them. "
+ "Choose the S&P 500 universe."
+ ),
+ "universe_excluded": universe_excluded,
+ }
+ if universe_excluded:
+ logger.info(
+ "alpha_bench: %d alpha(s) excluded on %s — fund:* inputs need SEC US filings (sp500): %s",
+ len(universe_excluded),
+ universe,
+ ", ".join(universe_excluded[:10]),
+ )
+
# Load panel — W4 universe loader fetches constituents + OHLCV (+ amount, vwap).
try:
_validate_bench_data_requirements(registry, alpha_ids, universe)
@@ -1151,7 +1343,7 @@ def run_alpha_bench(**kwargs: Any) -> dict[str, Any]:
try:
panel = _prepare_bench_panel(registry, alpha_ids, panel, universe, period)
- return_df = _compute_forward_returns(panel)
+ return_df = _compute_forward_returns(panel, horizon=horizon)
except Exception as exc:
return {"status": "error", "error": f"forward returns failed: {exc}"}
@@ -1194,13 +1386,18 @@ def run_alpha_bench(**kwargs: Any) -> dict[str, Any]:
except OSError as exc:
return {"status": "error", "error": f"failed to write report: {exc}"}
- return {
+ envelope: dict[str, Any] = {
"status": "ok",
"report_path": str(report_path),
"n_alphas_tested": len(results),
"n_skipped": len(failures),
+ "horizon": horizon,
+ "forward_return_sampling": "non_overlapping" if horizon > 1 else "daily",
"top": top,
}
+ if universe_excluded:
+ envelope["universe_excluded"] = universe_excluded
+ return envelope
class AlphaBenchTool(BaseTool):
@@ -1236,6 +1433,16 @@ class AlphaBenchTool(BaseTool):
"default": 20,
"description": "Report the top-N alphas ranked by IR.",
},
+ "horizon": {
+ "type": "integer",
+ "default": 1,
+ "description": (
+ "Forward-return horizon in bars. 1 = next-bar (default). "
+ "h>1 computes h-bar forward returns and samples IC rows "
+ "non-overlapping (end-anchored); 21 ≈ monthly, the "
+ "conventional horizon for fundamental factors. Range 1-252."
+ ),
+ },
"output_dir": {
"type": "string",
"description": "Where to write the HTML report; default ~/.vibe-trading/reports/.",
diff --git a/agent/tests/factors/test_alpha_compare.py b/agent/tests/factors/test_alpha_compare.py
index 13c1496c7..9981c6d6c 100644
--- a/agent/tests/factors/test_alpha_compare.py
+++ b/agent/tests/factors/test_alpha_compare.py
@@ -76,7 +76,7 @@ def _stub_panel(monkeypatch: pytest.MonkeyPatch, n_rows: int = 80, n_cols: int =
)
monkeypatch.setattr(
"src.factors.bench_runner._compute_forward_returns",
- lambda panel_in: panel_in["close"].pct_change().shift(-1),
+ lambda panel_in, horizon=1: panel_in["close"].pct_change().shift(-1),
)
@@ -350,3 +350,29 @@ def test_core_invalid_sort_falls_back_to_ir(monkeypatch) -> None:
)
assert env["sort"] == "ir"
assert env["winner"] == "b"
+
+
+def test_compare_discloses_universe_excluded_alphas(monkeypatch, capsys) -> None:
+ """A compare shortlist must not silently swallow universe-excluded alphas."""
+ id_to_zoo = {"fund_us": "fundamental", "fund_cn": "fundamental"}
+ metrics = {"fund_cn": _metrics(0.01, 0.05, 0.20)}
+
+ def fake_run_bench(*, zoo, universe, period, top, only, registry, on_progress=None, on_stage=None): # noqa: ARG001
+ rows = [{"id": aid, **metrics[aid]} for aid in only if aid in metrics]
+ excluded = [aid for aid in only if aid not in metrics]
+ return {
+ "status": "ok",
+ "zoo": zoo,
+ "rows": rows,
+ "skipped": [],
+ "universe_excluded": excluded,
+ }
+
+ _wire(monkeypatch, id_to_zoo, fake_run_bench)
+ rc, env = _run(capsys, _args(alpha_ids=["fund_us", "fund_cn"]))
+
+ assert rc == 0
+ assert env["n_compared"] == 1
+ assert env["n_skipped"] == 1
+ assert env["skipped"][0]["id"] == "fund_us"
+ assert "SEC US filings" in env["skipped"][0]["reason"]
diff --git a/agent/tests/factors/test_bench_strict.py b/agent/tests/factors/test_bench_strict.py
index 57fed45e1..d769cbd11 100644
--- a/agent/tests/factors/test_bench_strict.py
+++ b/agent/tests/factors/test_bench_strict.py
@@ -235,7 +235,7 @@ def _stub_panel(monkeypatch: pytest.MonkeyPatch, n_rows: int = 80, n_cols: int =
lambda universe, period: panel, # noqa: ARG005
)
- def _fwd(panel_in: dict[str, pd.DataFrame]) -> pd.DataFrame:
+ def _fwd(panel_in: dict[str, pd.DataFrame], horizon: int = 1) -> pd.DataFrame:
c = panel_in["close"]
return c.pct_change().shift(-1)
@@ -613,7 +613,7 @@ def test_run_bench_strict_catches_planted_alive_signal(
)
monkeypatch.setattr(
"src.factors.bench_runner_strict._compute_forward_returns",
- lambda p: p["close"].pct_change().shift(-1),
+ lambda p, horizon=1: p["close"].pct_change().shift(-1),
)
class PlantedReg:
@@ -651,7 +651,7 @@ def test_run_bench_strict_catches_planted_reversed_signal(
)
monkeypatch.setattr(
"src.factors.bench_runner_strict._compute_forward_returns",
- lambda p: p["close"].pct_change().shift(-1),
+ lambda p, horizon=1: p["close"].pct_change().shift(-1),
)
class ReversedReg:
diff --git a/agent/tests/factors/test_fundamental_ind_neutral_samples.py b/agent/tests/factors/test_fundamental_ind_neutral_samples.py
new file mode 100644
index 000000000..aec8eae55
--- /dev/null
+++ b/agent/tests/factors/test_fundamental_ind_neutral_samples.py
@@ -0,0 +1,255 @@
+"""Registration + numeric regression for the three industry-neutral CN value factors.
+
+Covers ``fund_pb_ind_neutral``, ``fund_ps_ttm_ind_neutral`` and
+``fund_dividend_yield_ind_neutral`` in ``zoo/fundamental/`` (issue #1789
+follow-up #2): the ``requires_sector`` gate, within-industry z-score values
+recomputed here with independent numpy math, the sign convention (PB/PS
+negated, dividend yield positive), and the NaN contract — no label, a
+singleton industry group or a blanked dependency all stay NaN, never a
+global-fallback number.
+
+Assertions are membership-based, never an exact registry total: the zoo grows
+concurrently.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from src.factors.registry import Registry, SkipAlpha
+
+_DATES = pd.to_datetime(["2024-01-01", "2024-01-02"])
+_CODES = ["BANK1", "BANK2", "TECH1", "TECH2"]
+_SECTORS = ["银行", "银行", "科技", "科技"]
+
+# alpha_id -> (columns_required, module stem, sign multiplier on the z-score)
+_EXPECTED: dict[str, tuple[list[str], str, float]] = {
+ "fund_pb_ind_neutral": (["val:pb"], "pb_ind_neutral", -1.0),
+ "fund_ps_ttm_ind_neutral": (["val:ps_ttm"], "ps_ttm_ind_neutral", -1.0),
+ "fund_dividend_yield_ind_neutral": (["val:dv_ttm"], "dividend_yield_ind_neutral", 1.0),
+}
+
+_DEPENDENCY: dict[str, str] = {
+ "fund_pb_ind_neutral": "val:pb",
+ "fund_ps_ttm_ind_neutral": "val:ps_ttm",
+ "fund_dividend_yield_ind_neutral": "val:dv_ttm",
+}
+
+
[email protected](scope="module")
+def registry() -> Registry:
+ return Registry()
+
+
+def _frame(rows: list[list[float]]) -> pd.DataFrame:
+ return pd.DataFrame(rows, index=_DATES, columns=_CODES, dtype="float64")
+
+
+def _sector_frame(labels: list[list] | None = None) -> pd.DataFrame:
+ rows = [list(row) for row in (labels or [_SECTORS, _SECTORS])]
+ return pd.DataFrame(rows, index=_DATES, columns=_CODES, dtype=object)
+
+
+def _build_panel() -> dict[str, pd.DataFrame]:
+ """Hand-built 2-date x 4-symbol panel, two industries of two names each."""
+ return {
+ # Within 银行: BANK2 cheaper; within 科技: TECH2 cheaper.
+ "val:pb": _frame([[0.5, 1.5, 8.0, 12.0], [0.6, 1.4, 9.0, 11.0]]),
+ "val:ps_ttm": _frame([[1.0, 3.0, 10.0, 30.0], [1.2, 2.8, 12.0, 28.0]]),
+ "val:dv_ttm": _frame([[4.0, 2.0, 0.5, 1.5], [3.8, 2.2, 0.6, 1.4]]),
+ "sector": _sector_frame(),
+ }
+
+
+def _numpy_group_zscore(values: np.ndarray, labels: np.ndarray) -> np.ndarray:
+ """Independent per-row within-group z-score: (x - mean) / sample-std."""
+ out = np.full(values.shape, np.nan, dtype=np.float64)
+ for i in range(values.shape[0]):
+ for tag in {label for label in labels[i] if label is not None}:
+ mask = labels[i] == tag
+ finite = values[i][mask & ~np.isnan(values[i])]
+ if finite.size < 2:
+ continue
+ std = finite.std(ddof=1)
+ if std <= 0:
+ continue
+ out[i, mask] = (values[i, mask] - finite.mean()) / std
+ return out
+
+
+def _expected_output(panel: dict[str, pd.DataFrame], alpha_id: str) -> pd.DataFrame:
+ columns, _, sign = _EXPECTED[alpha_id]
+ values = panel[columns[0]].to_numpy(dtype=np.float64)
+ labels = panel["sector"].to_numpy()
+ return pd.DataFrame(
+ sign * _numpy_group_zscore(values, labels), index=_DATES, columns=_CODES
+ )
+
+
+# ------------------------------------------------------- (a) gate + registry
+
+
[email protected]("alpha_id", sorted(_EXPECTED))
+def test_registry_loads_factor_with_expected_meta(
+ registry: Registry, alpha_id: str
+) -> None:
+ columns, stem, _ = _EXPECTED[alpha_id]
+ alpha = registry.get(alpha_id)
+ assert alpha.zoo == "fundamental"
+ assert alpha.module_path == f"src.factors.zoo.fundamental.{stem}"
+ assert alpha.meta["theme"] == ["value"]
+ assert alpha.meta["columns_required"] == columns
+ assert alpha.meta["requires_sector"] is True
+ assert alpha.meta["universe"] == ["equity_cn"]
+ assert alpha.meta["frequency"] == ["1d"]
+ assert alpha.meta["decay_horizon"] == 252
+ assert alpha.meta["min_warmup_bars"] == 1
+ assert alpha.meta["notes"].strip()
+ assert alpha.meta["formula_latex"].strip()
+
+
+def test_the_three_raw_siblings_stay_unsectorized(registry: Registry) -> None:
+ """The neutral variants are additions; the raw factors keep their contract."""
+ for alpha_id in ("fund_pb", "fund_ps_ttm", "fund_dividend_yield"):
+ assert not registry.get(alpha_id).meta.get("requires_sector")
+
+
+# ------------------------------------------------- (b) numeric correctness
+
+
[email protected]("alpha_id", sorted(_EXPECTED))
+def test_compute_matches_independent_numpy_math(
+ registry: Registry, alpha_id: str
+) -> None:
+ panel = _build_panel()
+ result = registry.compute(alpha_id, panel)
+ expected = _expected_output(panel, alpha_id)
+
+ assert list(result.columns) == _CODES
+ assert list(result.index) == list(_DATES)
+ np.testing.assert_allclose(
+ result.to_numpy(dtype=np.float64),
+ expected.to_numpy(dtype=np.float64),
+ rtol=1e-9,
+ atol=1e-12,
+ equal_nan=True,
+ err_msg=f"{alpha_id} diverged from independent numpy expectation",
+ )
+
+
+def test_pb_ranks_within_industry_not_across_the_row(registry: Registry) -> None:
+ """Industry level no longer dominates the score, only relative cheapness.
+
+ A raw -zscore(PB) puts every bank above every tech purely because banks
+ carry structurally lower PB. The neutral variant scores each name against
+ its own group: the cheap name of each industry gets the same top score
+ (+1/sqrt(2) in a two-member group), so TECH1 — expensive in absolute
+ terms yet cheap among techs — is no longer ranked below both banks.
+ """
+ out = registry.compute("fund_pb_ind_neutral", _build_panel())
+ date = _DATES[0]
+ # Within 银行: cheaper BANK1 scores high. Within 科技: cheaper TECH1 scores high.
+ assert out.loc[date, "BANK1"] > out.loc[date, "BANK2"]
+ assert out.loc[date, "TECH1"] > out.loc[date, "TECH2"]
+ # Two-member groups z-score to exactly ±1/sqrt(2) regardless of level.
+ s = 1.0 / np.sqrt(2.0)
+ np.testing.assert_allclose(
+ out.loc[date].to_numpy(dtype=np.float64), [s, -s, s, -s], rtol=1e-12
+ )
+
+
+def test_dividend_yield_sign_direction(registry: Registry) -> None:
+ """High dv_ttm scores high within the industry group (no inversion)."""
+ out = registry.compute("fund_dividend_yield_ind_neutral", _build_panel())
+ for date in _DATES:
+ assert out.loc[date, "BANK1"] > out.loc[date, "BANK2"]
+ assert out.loc[date, "TECH2"] > out.loc[date, "TECH1"]
+
+
+# ------------------------------------------------------------ (c) NaN contract
+
+
[email protected]("alpha_id", sorted(_EXPECTED))
+def test_missing_sector_tag_skips_cleanly(registry: Registry, alpha_id: str) -> None:
+ panel = _build_panel()
+ del panel["sector"]
+
+ with pytest.raises(SkipAlpha, match="missing sector tag"):
+ registry.compute(alpha_id, panel)
+
+
[email protected]("alpha_id", sorted(_EXPECTED))
+def test_blank_dependency_bar_yields_all_nan(registry: Registry, alpha_id: str) -> None:
+ panel = _build_panel()
+ panel[_DEPENDENCY[alpha_id]].loc[_DATES[1]] = np.nan
+
+ out = registry.compute(alpha_id, panel)
+
+ assert out.loc[_DATES[1]].isna().all(), (
+ f"{alpha_id}: emitted a value on a bar whose declared dependency was NaN"
+ )
+ assert out.loc[_DATES[0]].notna().all()
+
+
+def test_unlabelled_name_is_nan_not_globally_zscored(registry: Registry) -> None:
+ """A name with no industry label stays NaN — no global fallback."""
+ panel = _build_panel()
+ labels = [list(_SECTORS), list(_SECTORS)]
+ labels[1][2] = None # TECH1 unlabelled on date 2
+ panel["sector"] = _sector_frame(labels)
+
+ out = registry.compute("fund_pb_ind_neutral", panel)
+
+ assert pd.isna(out.loc[_DATES[1], "TECH1"])
+ # Its former group peer loses the second observation → singleton → NaN too.
+ assert pd.isna(out.loc[_DATES[1], "TECH2"])
+ # The 银行 group is untouched by the tech-side unlabelling: a two-member
+ # group z-scores to ±1/sqrt(2) on both dates.
+ assert out.loc[_DATES[1], "BANK1"] == pytest.approx(out.loc[_DATES[0], "BANK1"])
+ assert out.loc[_DATES[0]].notna().all()
+
+
+def test_singleton_industry_group_is_nan(registry: Registry) -> None:
+ panel = _build_panel()
+ panel["sector"] = _sector_frame([["银行", "银行", "科技", "医药"]] * 2)
+
+ out = registry.compute("fund_pb_ind_neutral", panel)
+
+ # TECH1 (科技) and TECH2 (医药) are each a one-name industry → NaN.
+ assert out.loc[:, "TECH1"].isna().all()
+ assert out.loc[:, "TECH2"].isna().all()
+ assert out.loc[:, ["BANK1", "BANK2"]].notna().all().all()
+
+
[email protected]("alpha_id", sorted(_EXPECTED))
+def test_no_inf_on_degenerate_group_values(
+ registry: Registry, alpha_id: str
+) -> None:
+ """A constant industry group degrades to NaN, never to inf or silent zero."""
+ panel = _build_panel()
+ panel[_DEPENDENCY[alpha_id]].loc[_DATES[0]] = [7.0, 7.0, 0.0, -3.0]
+
+ out = registry.compute(alpha_id, panel)
+ arr = out.to_numpy(dtype=np.float64, na_value=np.nan)
+
+ assert not np.isinf(arr).any()
+ assert out.loc[_DATES[0], ["BANK1", "BANK2"]].isna().all()
+
+
+ "stem,column",
+ [("pb_ind_neutral", "pb"), ("ps_ttm_ind_neutral", "ps_ttm")],
+)
+def test_nonpositive_multiples_are_not_ranked_as_cheap(stem: str, column: str) -> None:
+ """Mirrors the raw siblings' upstream guard: PB/PS <= 0 is excluded, never 'cheapest'."""
+ import importlib
+
+ mod = importlib.import_module(f"src.factors.zoo.fundamental.{stem}")
+ frame = pd.DataFrame([[-1.0, 0.0, 1.0, 2.0, 3.0]], columns=list("ABCDE"))
+ sector = pd.DataFrame([["G1"] * 5], columns=list("ABCDE"))
+
+ actual = mod.compute({f"val:{column}": frame, "sector": sector})
+
+ assert actual[["A", "B"]].isna().all().all()
+ np.testing.assert_allclose(actual[["C", "D", "E"]].to_numpy(), [[1.0, 0.0, -1.0]])
diff --git a/agent/tests/factors/test_zscore_by_group.py b/agent/tests/factors/test_zscore_by_group.py
new file mode 100644
index 000000000..1b3dffc32
--- /dev/null
+++ b/agent/tests/factors/test_zscore_by_group.py
@@ -0,0 +1,193 @@
+"""Unit contract for ``src.factors.base.zscore_by_group``.
+
+The shared within-group z-score the industry-neutralized CN value factors run
+on. Expected values are hand-computed (or recomputed with independent numpy
+math) rather than derived from the helper itself, so a regression in the
+helper cannot validate itself. The refusal cases matter as much as the numbers:
+a singleton group, a zero-variance group, a missing label and a ±inf input all
+stay NaN — there is no global fallback wearing an industry-neutral label.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from src.factors.base import zscore_by_group
+
+_DATES = pd.to_datetime(["2024-01-01", "2024-01-02"])
+_COLS = ["A", "B", "C", "D"]
+
+
+def _frame(rows: list[list], cols: list[str] | None = None) -> pd.DataFrame:
+ return pd.DataFrame(rows, index=_DATES, columns=cols or _COLS, dtype=object)
+
+
+def _labels(rows: list[list]) -> pd.DataFrame:
+ return pd.DataFrame(rows, index=_DATES, columns=_COLS, dtype=object)
+
+
+def test_two_group_row_matches_hand_computation() -> None:
+ """Row [1,3 | 10,20] in two groups: every cell is ±1/sqrt(2)."""
+ values = pd.DataFrame(
+ [[1.0, 3.0, 10.0, 20.0], [2.0, 4.0, 4.0, 2.0]],
+ index=_DATES, columns=_COLS, dtype="float64",
+ )
+ groups = _labels([["G1", "G1", "G2", "G2"]] * 2)
+
+ out = zscore_by_group(values, groups)
+
+ s = 1.0 / np.sqrt(2.0) # (x - mean) / sample-std of a two-point group
+ np.testing.assert_allclose(
+ out.to_numpy(dtype=np.float64),
+ np.array([[-s, s, -s, s], [-s, s, s, -s]]),
+ rtol=1e-12, atol=1e-15,
+ )
+
+
+def test_group_stats_use_only_that_group() -> None:
+ """A three-member group's mean/std come from its own cells, not the row."""
+ values = pd.DataFrame(
+ [[1.0, 2.0, 3.0, 100.0]], index=_DATES[:1], columns=_COLS, dtype="float64"
+ )
+ groups = pd.DataFrame(
+ [["G1", "G1", "G1", "G2"]], index=_DATES[:1], columns=_COLS, dtype=object
+ )
+
+ out = zscore_by_group(values, groups)
+
+ # G1: mean 2, sample std 1 → [-1, 0, 1]; G2 singleton → NaN (not 100's z vs the row).
+ np.testing.assert_allclose(
+ out.to_numpy(dtype=np.float64)[0, :3], [-1.0, 0.0, 1.0], rtol=1e-12
+ )
+ assert np.isnan(out.to_numpy(dtype=np.float64)[0, 3])
+
+
+def test_singleton_group_is_nan() -> None:
+ values = pd.DataFrame([[1.0, 3.0, 7.0, 9.0]], index=_DATES[:1], columns=_COLS, dtype="float64")
+ groups = pd.DataFrame([["G1", "G1", "G2", "G3"]], index=_DATES[:1], columns=_COLS, dtype=object)
+
+ out = zscore_by_group(values, groups)
+
+ row = out.to_numpy(dtype=np.float64)[0]
+ assert np.isfinite(row[0]) and np.isfinite(row[1])
+ assert np.isnan(row[2]) and np.isnan(row[3])
+
+
+def test_zero_variance_group_is_nan_never_inf_never_zero() -> None:
+ values = pd.DataFrame([[5.0, 5.0, 1.0, 2.0]], index=_DATES[:1], columns=_COLS, dtype="float64")
+ groups = pd.DataFrame([["G1", "G1", "G2", "G2"]], index=_DATES[:1], columns=_COLS, dtype=object)
+
+ out = zscore_by_group(values, groups)
+
+ row = out.to_numpy(dtype=np.float64)[0]
+ assert np.isnan(row[0]) and np.isnan(row[1])
+ assert not np.isinf(row).any()
+ assert np.isfinite(row[2]) and np.isfinite(row[3])
+
+
+def test_nan_cell_stays_nan_and_is_excluded_from_group_stats() -> None:
+ """The NaN cell does not enter the mean/std; the survivors still z-score."""
+ values = pd.DataFrame(
+ [[1.0, np.nan, 3.0, 10.0]], index=_DATES[:1], columns=_COLS, dtype="float64"
+ )
+ groups = pd.DataFrame(
+ [["G1", "G1", "G1", "G2"]], index=_DATES[:1], columns=_COLS, dtype=object
+ )
+
+ out = zscore_by_group(values, groups)
+
+ row = out.to_numpy(dtype=np.float64)[0]
+ # G1 finite {1, 3}: mean 2, std sqrt(2) → ±1/sqrt(2); the NaN cell stays NaN.
+ s = 1.0 / np.sqrt(2.0)
+ assert row[0] == pytest.approx(-s)
+ assert np.isnan(row[1])
+ assert row[2] == pytest.approx(s)
+
+
+def test_none_and_nan_labels_are_nan_with_no_global_fallback() -> None:
+ values = pd.DataFrame([[1.0, 2.0, 3.0, 4.0]], index=_DATES[:1], columns=_COLS, dtype="float64")
+ groups = pd.DataFrame(
+ [[None, np.nan, "G1", "G1"]], index=_DATES[:1], columns=_COLS, dtype=object
+ )
+
+ out = zscore_by_group(values, groups)
+
+ row = out.to_numpy(dtype=np.float64)[0]
+ assert np.isnan(row[0]) and np.isnan(row[1])
+ assert np.isfinite(row[2]) and np.isfinite(row[3])
+
+
+def test_inf_inputs_are_scrubbed_to_nan() -> None:
+ values = pd.DataFrame(
+ [[np.inf, 1.0, 3.0, -np.inf]], index=_DATES[:1], columns=_COLS, dtype="float64"
+ )
+ groups = pd.DataFrame([["G1"] * 4], index=_DATES[:1], columns=_COLS, dtype=object)
+
+ out = zscore_by_group(values, groups)
+
+ row = out.to_numpy(dtype=np.float64)[0]
+ assert not np.isinf(row).any()
+ assert np.isnan(row[0]) and np.isnan(row[3])
+ # G1 finite {1, 3} → ±1/sqrt(2), the infinities excluded from mean/std.
+ s = 1.0 / np.sqrt(2.0)
+ assert row[1] == pytest.approx(-s)
+ assert row[2] == pytest.approx(s)
+
+
+def test_shape_index_columns_preserved() -> None:
+ values = pd.DataFrame(
+ [[1.0, 2.0, 3.0, 4.0], [4.0, 3.0, 2.0, 1.0]], index=_DATES, columns=_COLS, dtype="float64"
+ )
+ groups = _labels([["G1", "G1", "G2", "G2"]] * 2)
+
+ out = zscore_by_group(values, groups)
+
+ assert out.shape == values.shape
+ assert list(out.index) == list(_DATES)
+ assert list(out.columns) == _COLS
+
+
+def test_groups_align_positionally_not_by_label() -> None:
+ """A groups frame with different index/column labels gives the same result."""
+ values = pd.DataFrame(
+ [[1.0, 3.0, 10.0, 20.0]], index=_DATES[:1], columns=_COLS, dtype="float64"
+ )
+ aligned = pd.DataFrame(
+ [["G1", "G1", "G2", "G2"]], index=_DATES[:1], columns=_COLS, dtype=object
+ )
+ shifted_labels = pd.DataFrame(
+ [["G1", "G1", "G2", "G2"]],
+ index=pd.to_datetime(["1999-12-31"]),
+ columns=["W", "X", "Y", "Z"],
+ dtype=object,
+ )
+
+ a = zscore_by_group(values, aligned)
+ b = zscore_by_group(values, shifted_labels)
+
+ np.testing.assert_allclose(
+ a.to_numpy(dtype=np.float64), b.to_numpy(dtype=np.float64), equal_nan=True
+ )
+ assert list(b.columns) == _COLS # output keeps df's columns, not groups'
+
+
+def test_integer_labels_work() -> None:
+ """The sweep panels carry integer sector buckets; labels need not be str."""
+ values = pd.DataFrame([[1.0, 3.0, 10.0, 20.0]], index=_DATES[:1], columns=_COLS, dtype="float64")
+ groups = pd.DataFrame([[0, 0, 1, 1]], index=_DATES[:1], columns=_COLS)
+
+ out = zscore_by_group(values, groups)
+
+ s = 1.0 / np.sqrt(2.0)
+ np.testing.assert_allclose(
+ out.to_numpy(dtype=np.float64)[0], [-s, s, -s, s], rtol=1e-12
+ )
+
+
+def test_shape_mismatch_raises() -> None:
+ values = pd.DataFrame([[1.0, 2.0, 3.0, 4.0]], index=_DATES[:1], columns=_COLS, dtype="float64")
+ groups = pd.DataFrame([["G1", "G1", "G2"]], index=_DATES[:1], columns=_COLS[:3], dtype=object)
+
+ with pytest.raises(ValueError, match=r"groups shape .* != df shape"):
+ zscore_by_group(values, groups)
diff --git a/agent/tests/test_alpha_bench_csi300_sector.py b/agent/tests/test_alpha_bench_csi300_sector.py
new file mode 100644
index 000000000..ce15b92ee
--- /dev/null
+++ b/agent/tests/test_alpha_bench_csi300_sector.py
@@ -0,0 +1,240 @@
+"""The csi300 bench attaches a PIT SW2021 sector tag for requires_sector alphas.
+
+csi300 was the one universe with no ``sector`` frame: the 19 alpha101
+industry-neutralized alphas and the three ``fund_*_ind_neutral`` CN value
+alphas SkipAlpha'd on every run. These tests extend the existing csi300 fake
+pro with ``index_member_all`` and pin the attach contract: labels land outside
+the pickled price panel, inherit the PIT membership mask, disclose source and
+coverage in ``_meta``, stay off below the coverage gate, and never take the
+bench down when the loader fails.
+"""
+from __future__ import annotations
+
+import logging
+import sys
+from types import SimpleNamespace
+from typing import Any
+
+import pandas as pd
+import pytest
+
+from src.config.accessor import reset_env_config
+from src.tools import alpha_bench_tool as tool
+
+_ALPHA_ID = "fund_pb_ind_neutral"
+_META = {"columns_required": ["val:pb"], "requires_sector": True}
+_PLAIN_META = {"columns_required": ["val:pb"]}
+
+
+class _StubRegistry:
+ """Registry surface ``_prepare_bench_panel`` uses: ``get(aid).meta``."""
+
+ def __init__(self, metas: dict[str, dict]) -> None:
+ self._metas = metas
+
+ def get(self, alpha_id: str) -> Any:
+ return SimpleNamespace(meta=self._metas[alpha_id])
+
+
+def _member_row(ts_code: str, l1_name: str) -> dict[str, Any]:
+ return {
+ "l1_code": f"800-{l1_name}",
+ "l1_name": l1_name,
+ "l2_code": "801-x",
+ "l2_name": "x",
+ "l3_code": "802-y",
+ "l3_name": "y",
+ "ts_code": ts_code,
+ "name": ts_code.split(".")[0],
+ "in_date": "20200101",
+ "out_date": None,
+ "is_new": "Y",
+ }
+
+
+class _FakeTusharePro:
+ """The csi300 fake from test_alpha_bench_universe_metadata, plus industry
+ membership and daily_basic so the whole _prepare_bench_panel path runs."""
+
+ def __init__(self, members: list[dict[str, Any]] | Exception) -> None:
+ self.members = members
+ self.industry_calls: list[dict[str, Any]] = []
+
+ def index_weight(self, **_kwargs) -> pd.DataFrame:
+ return pd.DataFrame(
+ {
+ "trade_date": ["20240102"] * 3,
+ "con_code": ["600000.SH", "000001.SZ", "000002.SZ"],
+ }
+ )
+
+ def daily(self, **_kwargs) -> pd.DataFrame:
+ return pd.DataFrame(
+ {
+ "trade_date": ["20240102"],
+ "open": [10.0],
+ "high": [11.0],
+ "low": [9.0],
+ "close": [10.5],
+ "vol": [100.0],
+ "amount": [105.0],
+ }
+ )
+
+ def adj_factor(self, **_kwargs) -> pd.DataFrame:
+ return pd.DataFrame({"trade_date": ["20240102"], "adj_factor": [1.0]})
+
+ def daily_basic(self, **kwargs) -> pd.DataFrame:
+ code = kwargs["ts_code"]
+ return pd.DataFrame(
+ {"ts_code": [code], "trade_date": ["20240102"], "pb": [1.5]}
+ )
+
+ def index_member_all(self, **kwargs) -> pd.DataFrame:
+ self.industry_calls.append(kwargs)
+ if isinstance(self.members, Exception):
+ raise self.members
+ return pd.DataFrame(self.members)
+
+
+def _install(
+ monkeypatch: pytest.MonkeyPatch, pro: _FakeTusharePro
+) -> None:
+ monkeypatch.setenv("TUSHARE_TOKEN", "ts-test-token")
+ monkeypatch.setattr(
+ tool,
+ "get_env_config",
+ lambda: SimpleNamespace(data=SimpleNamespace(tushare_token="ts-test-token")),
+ )
+ monkeypatch.setitem(
+ sys.modules, "tushare", SimpleNamespace(pro_api=lambda _token: pro)
+ )
+
+
+def _prepare(panel: dict, metas: dict[str, dict] | None = None) -> dict:
+ metas = metas if metas is not None else {_ALPHA_ID: _META}
+ registry = _StubRegistry(metas)
+ return tool._prepare_bench_panel(
+ registry, list(metas), panel, "csi300", "2024-01-01/2024-01-31"
+ )
+
+
+def test_sector_attaches_with_pit_labels_and_meta_disclosure(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ pro = _FakeTusharePro(
+ [
+ _member_row("600000.SH", "银行"),
+ _member_row("000001.SZ", "非银金融"),
+ _member_row("000002.SZ", "房地产"),
+ ]
+ )
+ _install(monkeypatch, pro)
+
+ panel = tool._load_csi300_panel("2024-01-01", "2024-01-31")
+ # The tag must not ride inside the pickled price panel: at load time the
+ # meta keys sit at their null/0.0 defaults and no sector frame exists.
+ assert "sector" not in panel
+ assert panel["_meta"]["sector_source"] is None
+ assert panel["_meta"]["sector_coverage"] == 0.0
+
+ enriched = _prepare(panel)
+
+ assert "sector" in enriched
+ close = enriched["close"]
+ sector = enriched["sector"]
+ assert sector.shape == close.shape
+ assert list(sector.columns) == list(close.columns)
+ assert sector.index.equals(close.index)
+ assert sector.loc["2024-01-02", "600000.SH"] == "银行"
+ assert sector.loc["2024-01-02", "000001.SZ"] == "非银金融"
+ assert sector.loc["2024-01-02", "000002.SZ"] == "房地产"
+ # The original panel (the dict that was pickled into the cache) is never
+ # mutated: the attach adds keys to its own copy only.
+ assert "sector" not in panel
+ assert panel["_meta"]["sector_source"] is None
+ assert panel["_meta"]["sector_coverage"] == 0.0
+ # Inherits the PIT membership mask: a label exists only where close does.
+ assert (sector.notna() <= close.notna()).all().all()
+ assert enriched["_meta"]["sector_source"] == "tushare index_member_all SW2021 L1"
+ assert enriched["_meta"]["sector_coverage"] == 1.0
+ # The val: attach still ran first, same stage.
+ assert "val:pb" in enriched
+
+
+def test_low_coverage_leaves_the_tag_off_and_discloses(
+ monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+ """1 of 3 columns labelled < 0.9: attaching would z-score one bucket."""
+ pro = _FakeTusharePro([_member_row("600000.SH", "银行")])
+ _install(monkeypatch, pro)
+ panel = tool._load_csi300_panel("2024-01-01", "2024-01-31")
+
+ with caplog.at_level(logging.WARNING, logger=tool.logger.name):
+ enriched = _prepare(panel)
+
+ assert "sector" not in enriched
+ assert enriched["_meta"]["sector_source"] is None
+ assert enriched["_meta"]["sector_coverage"] == pytest.approx(0.3333, abs=1e-4)
+ assert any("sector coverage" in message for message in caplog.messages)
+ # The rest of the bench prep is untouched: val: columns still attach.
+ assert "val:pb" in enriched
+
+
+def test_loader_failure_never_takes_the_bench_down(
+ monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+ """Placeholder token → loader RuntimeError → warn, no sector, bench proceeds."""
+ pro = _FakeTusharePro(
+ [
+ _member_row("600000.SH", "银行"),
+ _member_row("000001.SZ", "非银金融"),
+ _member_row("000002.SZ", "房地产"),
+ ]
+ )
+ _install(monkeypatch, pro)
+ panel = tool._load_csi300_panel("2024-01-01", "2024-01-31")
+ # Pre-attach val:pb so the token pull below isolates the sector loader
+ # (the valuation loader would raise its own RuntimeError on the empty token).
+ panel["val:pb"] = panel["close"].notna().astype(float).where(panel["close"].notna()) * 1.5
+
+ monkeypatch.setenv("TUSHARE_TOKEN", "")
+ reset_env_config()
+ with caplog.at_level(logging.WARNING, logger=tool.logger.name):
+ enriched = _prepare(panel)
+
+ assert "sector" not in enriched
+ assert enriched["_meta"]["sector_source"] is None
+ assert enriched["_meta"]["sector_coverage"] == 0.0
+ assert any("industry loader failed" in message for message in caplog.messages)
+ assert "val:pb" in enriched
+
+
+def test_provider_exception_degrades_to_no_sector(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """index_member_all raising after backoff: the loader itself degrades."""
+ pro = _FakeTusharePro(RuntimeError("provider down"))
+ _install(monkeypatch, pro)
+ panel = tool._load_csi300_panel("2024-01-01", "2024-01-31")
+
+ enriched = _prepare(panel)
+
+ assert "sector" not in enriched
+ assert enriched["_meta"]["sector_source"] is None
+ assert enriched["_meta"]["sector_coverage"] == 0.0
+
+
+def test_no_sector_fetch_when_nothing_declares_requires_sector(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """The membership endpoint is only paid for when an alpha needs the tag."""
+ pro = _FakeTusharePro([_member_row("600000.SH", "银行")])
+ _install(monkeypatch, pro)
+ panel = tool._load_csi300_panel("2024-01-01", "2024-01-31")
+
+ enriched = _prepare(panel, metas={_ALPHA_ID: _PLAIN_META})
+
+ assert pro.industry_calls == []
+ assert "sector" not in enriched
+ assert enriched["_meta"]["sector_source"] is None
diff --git a/agent/tests/test_alpha_bench_forward_returns.py b/agent/tests/test_alpha_bench_forward_returns.py
index 66b2085cc..82606ed94 100644
--- a/agent/tests/test_alpha_bench_forward_returns.py
+++ b/agent/tests/test_alpha_bench_forward_returns.py
@@ -1,8 +1,11 @@
-"""Regression tests for alpha-bench forward-return missing-data handling."""
+"""Regression tests for alpha-bench forward-return missing-data handling
+and monthly-horizon support (issue #1789 follow-up #1)."""
from __future__ import annotations
+import numpy as np
import pandas as pd
+import pytest
from src.tools.alpha_bench_tool import _compute_forward_returns
@@ -16,3 +19,90 @@ def test_forward_returns_preserve_missing_close_boundaries() -> None:
forward = _compute_forward_returns({"close": close})
assert forward["AAA"].isna().all()
+
+
+def _close(values: list[float]) -> pd.DataFrame:
+ return pd.DataFrame(
+ {"AAA": list(values)},
+ index=pd.date_range("2026-01-01", periods=len(values), freq="D"),
+ )
+
+
+def test_horizon_default_is_byte_identical_to_legacy_formula() -> None:
+ close = _close([100.0, 102.0, np.nan, 105.0, 104.0, 108.0, 110.0])
+ legacy = close.pct_change(fill_method=None).shift(-1)
+
+ assert _compute_forward_returns({"close": close}).equals(legacy)
+ assert _compute_forward_returns({"close": close}, horizon=1).equals(legacy)
+
+
+def test_horizon_three_samples_every_third_row_end_anchored() -> None:
+ values = [100.0, 101.0, 103.0, 106.0, 110.0, 115.0, 121.0, 128.0, 136.0, 145.0]
+ close = _close(values)
+
+ forward = _compute_forward_returns({"close": close}, horizon=3)
+
+ # n=10, h=3 → kept positions satisfy (9 - pos) % 3 == 0 → 0, 3, 6, 9.
+ for pos in (0, 3, 6):
+ expected = values[pos + 3] / values[pos] - 1.0
+ assert forward["AAA"].iloc[pos] == pytest.approx(expected)
+ # The most recent sampled row has no t+h close → NaN, never bridged.
+ assert np.isnan(forward["AAA"].iloc[9])
+ # Non-sampled rows are NaN so consecutive IC windows never overlap.
+ for pos in (1, 2, 4, 5, 7, 8):
+ assert np.isnan(forward["AAA"].iloc[pos])
+
+
+def test_horizon_samples_the_most_recent_complete_window() -> None:
+ # n=9, h=2 → sampled positions 0, 2, 4, 6, 8 (end-anchored); the row at
+ # position 6 carries the return over the most recent complete window [6→8].
+ values = [100.0, 102.0, 101.0, 104.0, 107.0, 106.0, 110.0, 112.0, 115.0]
+ close = _close(values)
+
+ forward = _compute_forward_returns({"close": close}, horizon=2)
+
+ assert forward["AAA"].iloc[6] == pytest.approx(values[8] / values[6] - 1.0)
+ assert np.isnan(forward["AAA"].iloc[8]) # sampled but no future close
+ assert np.isnan(forward["AAA"].iloc[7]) # not sampled
+
+
+def test_horizon_nan_close_at_t_plus_h_never_bridges() -> None:
+ # n=6, h=3 → sampled positions 2 and 5. close[5] is NaN (halted), so the
+ # return at position 2 must be NaN — no bridging off close[4].
+ values = [100.0, 101.0, 103.0, 106.0, 110.0, np.nan]
+ close = _close(values)
+
+ forward = _compute_forward_returns({"close": close}, horizon=3)
+
+ assert np.isnan(forward["AAA"].iloc[2])
+
+
+def test_horizon_nan_close_at_t_never_bridges() -> None:
+ # Same geometry, NaN at the sampled row t itself.
+ values = [100.0, 101.0, np.nan, 106.0, 110.0, 115.0]
+ close = _close(values)
+
+ forward = _compute_forward_returns({"close": close}, horizon=3)
+
+ assert np.isnan(forward["AAA"].iloc[2])
+
+
[email protected]("bad", [0, -1, -21])
+def test_horizon_below_one_raises(bad: int) -> None:
+ close = _close([100.0, 101.0, 102.0])
+
+ with pytest.raises(ValueError, match="horizon"):
+ _compute_forward_returns({"close": close}, horizon=bad)
+
+
[email protected]("bad", ["3", 1.5, True, None])
+def test_horizon_non_int_raises(bad: object) -> None:
+ close = _close([100.0, 101.0, 102.0])
+
+ with pytest.raises(ValueError, match="horizon"):
+ _compute_forward_returns({"close": close}, horizon=bad)
+
+
+def test_horizon_missing_close_still_raises() -> None:
+ with pytest.raises(ValueError, match="close"):
+ _compute_forward_returns({}, horizon=3)
diff --git a/agent/tests/test_alpha_bench_horizon.py b/agent/tests/test_alpha_bench_horizon.py
new file mode 100644
index 000000000..cfb87ff78
--- /dev/null
+++ b/agent/tests/test_alpha_bench_horizon.py
@@ -0,0 +1,521 @@
+"""Threading tests for monthly-horizon IC support (issue #1789 follow-up #1).
+
+Covers the ``horizon`` parameter end to end without touching the network:
+run_bench / run_bench_strict result meta, run_alpha_bench parameter
+validation, and the CLI ``--horizon`` surface. Engine internals are
+monkeypatched with fakes following the existing bench-test patterns
+(test_bench_multiple_testing.py / test_alpha_bench_strict_cli.py).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+from unittest.mock import MagicMock
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from src.factors import cli_handlers
+from src.factors.bench_runner import run_bench
+from src.factors.bench_runner_strict import run_bench_strict
+from src.tools.alpha_bench_tool import _validate_horizon, run_alpha_bench
+
+
+# ── run_bench meta ──────────────────────────────────────────────────────────
+
+
+def _make_panel(n_symbols: int = 6, n_days: int = 60) -> dict[str, pd.DataFrame]:
+ rng = np.random.default_rng(42)
+ dates = pd.date_range("2020-01-01", periods=n_days, freq="B")
+ symbols = [f"SYM{i:03d}" for i in range(n_symbols)]
+ close = pd.DataFrame(
+ np.cumsum(rng.standard_normal((n_days, n_symbols)), axis=0) + 100,
+ index=dates,
+ columns=symbols,
+ )
+ return {"close": close, "open": close, "high": close, "low": close, "volume": close}
+
+
+def _setup_bench(monkeypatch: pytest.MonkeyPatch, captured: dict[str, Any]) -> MagicMock:
+ panel = _make_panel()
+ rng = np.random.default_rng(7)
+
+ reg = MagicMock()
+ reg.list.return_value = ["alpha_0", "alpha_1"]
+ reg.get.return_value = MagicMock(meta={"theme": ["test"], "formula_latex": ""})
+ reg.compute.side_effect = lambda aid, p: pd.DataFrame(
+ rng.standard_normal(p["close"].shape),
+ index=p["close"].index,
+ columns=p["close"].columns,
+ )
+
+ def fake_fwd(p: dict[str, pd.DataFrame], horizon: int = 1) -> pd.DataFrame:
+ captured["horizon"] = horizon
+ return p["close"].pct_change(fill_method=None).shift(-1)
+
+ monkeypatch.setattr("src.factors.bench_runner._load_universe_panel", lambda u, p: panel)
+ monkeypatch.setattr("src.factors.bench_runner._compute_forward_returns", fake_fwd)
+ monkeypatch.setattr("src.factors.bench_runner.get_default_registry", lambda: reg)
+ return reg
+
+
+def test_run_bench_default_meta_says_daily(monkeypatch: pytest.MonkeyPatch) -> None:
+ captured: dict[str, Any] = {}
+ reg = _setup_bench(monkeypatch, captured)
+
+ result = run_bench("test_zoo", "mock", "2020-2021", registry=reg)
+
+ assert result["status"] == "ok"
+ assert result["horizon"] == 1
+ assert result["forward_return_sampling"] == "daily"
+ assert captured["horizon"] == 1
+
+
+def test_run_bench_horizon_meta_says_non_overlapping(monkeypatch: pytest.MonkeyPatch) -> None:
+ captured: dict[str, Any] = {}
+ reg = _setup_bench(monkeypatch, captured)
+
+ result = run_bench("test_zoo", "mock", "2020-2021", registry=reg, horizon=21)
+
+ assert result["status"] == "ok"
+ assert result["horizon"] == 21
+ assert result["forward_return_sampling"] == "non_overlapping"
+ assert captured["horizon"] == 21
+
+
+def test_run_bench_invalid_horizon_errors_without_crashing(monkeypatch: pytest.MonkeyPatch) -> None:
+ # No fake for _compute_forward_returns here: the real engine validation
+ # must turn horizon=0 into a clean error entry, not a traceback.
+ monkeypatch.setattr(
+ "src.factors.bench_runner._load_universe_panel", lambda u, p: _make_panel()
+ )
+ reg = MagicMock()
+ reg.list.return_value = ["alpha_0"]
+ reg.get.return_value = MagicMock(meta={"theme": ["test"], "formula_latex": ""})
+
+ result = run_bench("test_zoo", "mock", "2020-2021", registry=reg, horizon=0)
+
+ assert result["status"] == "error"
+ assert "horizon" in result["error"]
+
+
+# ── run_bench_strict meta ───────────────────────────────────────────────────
+
+
+class _StubRegistry:
+ def list(self, *, zoo: str) -> list[str]: # noqa: ARG002
+ return ["test_signal"]
+
+ def get(self, aid: str) -> Any: # noqa: ARG002
+ class _Handle:
+ meta = {"theme": ["test"], "formula_latex": "stub"}
+
+ return _Handle()
+
+ def compute(self, aid: str, panel: dict[str, pd.DataFrame]) -> pd.DataFrame: # noqa: ARG002
+ return panel["close"].pct_change(5)
+
+
+def _setup_strict(monkeypatch: pytest.MonkeyPatch, captured: dict[str, Any]) -> None:
+ rng = np.random.default_rng(0)
+ idx = pd.date_range("2024-01-01", periods=80, freq="D")
+ cols = [f"S{i}" for i in range(8)]
+ close = pd.DataFrame(
+ 100.0 + np.cumsum(rng.normal(size=(80, 8)), axis=0), index=idx, columns=cols
+ )
+ panel = {
+ "close": close, "high": close * 1.01, "low": close * 0.99,
+ "open": close, "volume": close * 0 + 1_000_000,
+ "vwap": close, "amount": close * 1_000_000,
+ }
+ monkeypatch.setattr(
+ "src.factors.bench_runner_strict._load_universe_panel",
+ lambda universe, period: panel, # noqa: ARG005
+ )
+
+ def fake_fwd(p: dict[str, pd.DataFrame], horizon: int = 1) -> pd.DataFrame:
+ captured["horizon"] = horizon
+ return p["close"].pct_change(fill_method=None).shift(-1)
+
+ monkeypatch.setattr(
+ "src.factors.bench_runner_strict._compute_forward_returns",
+ fake_fwd,
+ )
+
+
+def test_run_bench_strict_accepts_horizon_and_carries_meta(monkeypatch: pytest.MonkeyPatch) -> None:
+ captured: dict[str, Any] = {}
+ _setup_strict(monkeypatch, captured)
+
+ result = run_bench_strict(
+ zoo="alpha101", universe="csi300", period="2024-2024",
+ random_control=False, registry=_StubRegistry(), horizon=21,
+ )
+
+ assert result["status"] == "ok"
+ assert result["horizon"] == 21
+ assert result["forward_return_sampling"] == "non_overlapping"
+ assert captured["horizon"] == 21
+
+
+def test_run_bench_strict_default_meta_says_daily(monkeypatch: pytest.MonkeyPatch) -> None:
+ captured: dict[str, Any] = {}
+ _setup_strict(monkeypatch, captured)
+
+ result = run_bench_strict(
+ zoo="alpha101", universe="csi300", period="2024-2024",
+ random_control=False, registry=_StubRegistry(),
+ )
+
+ assert result["status"] == "ok"
+ assert result["horizon"] == 1
+ assert result["forward_return_sampling"] == "daily"
+ assert captured["horizon"] == 1
+
+
+# ── Tool-level parameter validation ─────────────────────────────────────────
+
+
[email protected]("bad", [0, -1, 253, "21", 1.5, True])
+def test_run_alpha_bench_rejects_invalid_horizon_before_touching_the_engine(bad: object) -> None:
+ # Validation must fire before registry init / panel load so this stays
+ # offline-safe with a real-looking universe and period.
+ envelope = run_alpha_bench(
+ universe="sp500", period="2020-2024", zoo="alpha101", horizon=bad
+ )
+
+ assert envelope["status"] == "error"
+ assert "horizon" in envelope["error"]
+
+
+def test_validate_horizon_accepts_in_range_values() -> None:
+ assert _validate_horizon(1) == 1
+ assert _validate_horizon(21) == 21
+ assert _validate_horizon(252) == 252
+ assert _validate_horizon(None) == 1
+
+
[email protected]("bad", [0, -1, 253, "21", 1.5, True])
+def test_validate_horizon_rejects_out_of_range_or_non_int(bad: object) -> None:
+ with pytest.raises(ValueError, match="horizon"):
+ _validate_horizon(bad)
+
+
+# ── CLI surface ─────────────────────────────────────────────────────────────
+
+
+def _ns(**overrides: Any) -> argparse.Namespace:
+ base = dict(
+ zoo="alpha101",
+ universe="csi300",
+ period="2020-2025",
+ top=20,
+ yes=True,
+ strict=False,
+ oos_split=None,
+ training_cutoff=None,
+ random_seeds=5,
+ horizon=1,
+ )
+ base.update(overrides)
+ return argparse.Namespace(**base)
+
+
+def _legacy_result() -> dict[str, Any]:
+ return {
+ "status": "ok",
+ "alive": 1,
+ "rows": [
+ {
+ "id": "alpha001",
+ "ic_mean": 0.05,
+ "ic_std": 0.01,
+ "ir": 0.9,
+ "ic_positive_ratio": 0.7,
+ "ic_count": 100,
+ "theme": ["momentum"],
+ "formula_latex": "x",
+ "_category": "alive",
+ }
+ ],
+ "skipped": [],
+ "wall_seconds": 1.0,
+ }
+
+
+def _strict_result() -> dict[str, Any]:
+ return {
+ "status": "ok",
+ "confirmed_alive": 1,
+ "train_only": 0,
+ "reversed_strict": 0,
+ "noise": 0,
+ "rows": [
+ {
+ "id": "alpha001",
+ "ic_mean": 0.05,
+ "ic_std": 0.01,
+ "ir": 0.9,
+ "ic_positive_ratio": 0.7,
+ "ic_count": 100,
+ "theme": ["momentum"],
+ "formula_latex": "x",
+ "_category": "confirmed_alive",
+ "alpha_t_full": 2.7,
+ "alpha_t_train": None,
+ "alpha_t_test": None,
+ "random_ic_mean": 0.0,
+ }
+ ],
+ "skipped": [],
+ "wall_seconds": 1.0,
+ }
+
+
+class _FakeReg:
+ def list(self, zoo=None): # noqa: ARG002
+ return ["alpha001"]
+
+ def get(self, aid): # noqa: ARG002
+ class _Entry:
+ zoo = "alpha101"
+ meta = {"theme": ["momentum"], "formula_latex": "x"}
+
+ return _Entry()
+
+
+def _reg(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(cli_handlers, "Registry", _FakeReg)
+
+
+def _no_report(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
+ import src.tools.alpha_bench_tool as tool
+
+ monkeypatch.setattr(tool, "_default_output_dir", lambda: tmp_path)
+
+
+def test_cli_horizon_reaches_legacy_runner(
+ capsys, monkeypatch: pytest.MonkeyPatch, _reg, _no_report
+) -> None:
+ import src.factors.bench_runner as legacy_mod
+
+ called: dict[str, Any] = {}
+
+ def fake_legacy(**kwargs):
+ called.update(kwargs)
+ return _legacy_result()
+
+ monkeypatch.setattr(legacy_mod, "run_bench", fake_legacy)
+ rc = cli_handlers.cmd_alpha_bench(_ns(horizon=21))
+
+ assert rc == 0
+ assert called["horizon"] == 21
+ capsys.readouterr()
+
+
+def test_cli_horizon_default_reaches_legacy_runner_as_one(
+ capsys, monkeypatch: pytest.MonkeyPatch, _reg, _no_report
+) -> None:
+ import src.factors.bench_runner as legacy_mod
+
+ called: dict[str, Any] = {}
+
+ def fake_legacy(**kwargs):
+ called.update(kwargs)
+ return _legacy_result()
+
+ monkeypatch.setattr(legacy_mod, "run_bench", fake_legacy)
+ rc = cli_handlers.cmd_alpha_bench(_ns())
+
+ assert rc == 0
+ assert called["horizon"] == 1
+ capsys.readouterr()
+
+
+def test_cli_horizon_reaches_strict_runner(
+ capsys, monkeypatch: pytest.MonkeyPatch, _reg, _no_report
+) -> None:
+ import src.factors.bench_runner_strict as strict_mod
+
+ called: dict[str, Any] = {}
+
+ def fake_strict(zoo, universe, period, **kwargs): # noqa: ARG001
+ called.update(kwargs)
+ return _strict_result()
+
+ monkeypatch.setattr(strict_mod, "run_bench_strict", fake_strict)
+ rc = cli_handlers.cmd_alpha_bench(_ns(strict=True, horizon=21))
+
+ assert rc == 0
+ assert called["horizon"] == 21
+ assert called["random_control"] is True
+ capsys.readouterr()
+
+
+def test_cli_rejects_horizon_below_one_with_usage_exit_code(
+ capsys, monkeypatch: pytest.MonkeyPatch, _reg
+) -> None:
+ rc = cli_handlers.cmd_alpha_bench(_ns(horizon=0))
+
+ assert rc == 2
+ assert "--horizon" in capsys.readouterr().err
+
+
+def test_horizon_namespace_without_attribute_defaults_to_one(
+ capsys, monkeypatch: pytest.MonkeyPatch, _reg, _no_report
+) -> None:
+ # Pre-existing callers/tests build Namespaces without a horizon attribute;
+ # the handler must fall back to 1 rather than raise AttributeError.
+ import src.factors.bench_runner as legacy_mod
+
+ called: dict[str, Any] = {}
+
+ def fake_legacy(**kwargs):
+ called.update(kwargs)
+ return _legacy_result()
+
+ monkeypatch.setattr(legacy_mod, "run_bench", fake_legacy)
+ ns = _ns()
+ del ns.horizon
+ rc = cli_handlers.cmd_alpha_bench(ns)
+
+ assert rc == 0
+ assert called["horizon"] == 1
+ capsys.readouterr()
+
+
+def test_horizon_argparse_parses_and_rejects() -> None:
+ parser = argparse.ArgumentParser()
+ sub = parser.add_subparsers()
+ cli_handlers.add_subparser(sub)
+
+ args = parser.parse_args(["alpha", "bench", "--zoo", "alpha101", "--horizon", "21"])
+ assert args.horizon == 21
+
+ args_default = parser.parse_args(["alpha", "bench", "--zoo", "alpha101"])
+ assert args_default.horizon == 1
+
+ with pytest.raises(SystemExit) as excinfo:
+ parser.parse_args(["alpha", "bench", "--zoo", "alpha101", "--horizon", "0"])
+ assert excinfo.value.code == 2
+
+ with pytest.raises(SystemExit) as excinfo:
+ parser.parse_args(["alpha", "bench", "--zoo", "alpha101", "--horizon", "abc"])
+ assert excinfo.value.code == 2
+
+
+def test_json_envelope_still_parses_with_horizon(
+ capsys, monkeypatch: pytest.MonkeyPatch, _reg, _no_report
+) -> None:
+ import src.factors.bench_runner as legacy_mod
+
+ monkeypatch.setattr(legacy_mod, "run_bench", lambda **kw: _legacy_result())
+ rc = cli_handlers.cmd_alpha_bench(_ns(horizon=21))
+ assert rc == 0
+
+ out = capsys.readouterr().out
+ start = out.find("\n{")
+ assert start >= 0
+ envelope = json.loads(out[start + 1 :])
+ assert envelope["status"] == "ok"
+
+
+def test_json_envelope_discloses_horizon_and_exclusions(
+ capsys, monkeypatch: pytest.MonkeyPatch, _reg, _no_report
+) -> None:
+ import src.factors.bench_runner as legacy_mod
+
+ result = _legacy_result()
+ result.update(
+ {
+ "horizon": 21,
+ "forward_return_sampling": "non_overlapping",
+ "universe_excluded": ["fund_roa"],
+ }
+ )
+ monkeypatch.setattr(legacy_mod, "run_bench", lambda **kw: result)
+ rc = cli_handlers.cmd_alpha_bench(_ns(horizon=21))
+ assert rc == 0
+
+ out = capsys.readouterr().out
+ envelope = json.loads(out[out.find("\n{") + 1 :])
+ assert envelope["horizon"] == 21
+ assert envelope["forward_return_sampling"] == "non_overlapping"
+ assert envelope["universe_excluded"] == ["fund_roa"]
+
+
+def test_parser_rejects_horizon_above_the_cap() -> None:
+ parser = argparse.ArgumentParser()
+ sub = parser.add_subparsers(dest="command")
+ cli_handlers.add_subparser(sub)
+
+ with pytest.raises(SystemExit) as excinfo:
+ parser.parse_args(["alpha", "bench", "--zoo", "alpha101", "--horizon", "253"])
+ assert excinfo.value.code == 2
+
+
+def test_cli_rejects_horizon_above_cap_with_usage_exit_code(capsys, _reg) -> None:
+ rc = cli_handlers.cmd_alpha_bench(_ns(horizon=253))
+
+ assert rc == 2
+ assert "--horizon" in capsys.readouterr().err
+
+
[email protected]("bad", [253, 10_000, True, "21"])
+def test_run_bench_rejects_out_of_range_horizon_before_panel_load(
+ monkeypatch: pytest.MonkeyPatch, bad: object
+) -> None:
+ from unittest.mock import Mock
+
+ fetch = Mock()
+ monkeypatch.setattr("src.factors.bench_runner._load_universe_panel", fetch)
+ reg = MagicMock()
+ reg.list.return_value = ["alpha_0"]
+ reg.get.return_value = MagicMock(meta={"theme": ["test"], "formula_latex": ""})
+
+ result = run_bench("test_zoo", "mock", "2020-2021", registry=reg, horizon=bad)
+
+ assert result["status"] == "error"
+ assert "horizon" in result["error"]
+ fetch.assert_not_called()
+
+
+def test_multi_zoo_aggregate_discloses_horizon_and_exclusions() -> None:
+ """The all-zoos aggregation must not drop the per-sub-run disclosure keys."""
+ import time
+ from types import SimpleNamespace
+
+ reg = SimpleNamespace(
+ get=lambda aid: SimpleNamespace(zoo="fundamental"),
+ list=lambda zoo=None: ["fund_cn"],
+ )
+
+ def fake_run_bench(**_kw: Any) -> dict[str, Any]:
+ return {
+ "status": "ok",
+ "rows": [{"id": "fund_cn", "ir": 0.5}],
+ "skipped": [],
+ "horizon": 21,
+ "forward_return_sampling": "non_overlapping",
+ "universe_excluded": ["fund_us"],
+ }
+
+ out = cli_handlers._run_all_zoos_with_progress(
+ target_ids=["fund_cn"],
+ universe="csi300",
+ period="2020-2021",
+ top=5,
+ start_ts=time.monotonic(),
+ reg=reg,
+ run_bench=fake_run_bench,
+ )
+
+ assert out["status"] == "ok"
+ assert out["horizon"] == 21
+ assert out["forward_return_sampling"] == "non_overlapping"
+ assert out["universe_excluded"] == ["fund_us"]
diff --git a/agent/tests/test_alpha_bench_universe_metadata.py b/agent/tests/test_alpha_bench_universe_metadata.py
index 66137347b..0a4cf47e0 100644
--- a/agent/tests/test_alpha_bench_universe_metadata.py
+++ b/agent/tests/test_alpha_bench_universe_metadata.py
@@ -91,6 +91,11 @@ def test_csi300_reports_point_in_time_membership(
"constituent_count": 3,
"price_adjustment": "qfq",
"dropped_unadjustable": 0,
+ # Sector labels attach later in _prepare_bench_panel, outside the
+ # pickled price panel; the load-time defaults are the disclosure for
+ # a run where the attach never happens or degrades.
+ "sector_source": None,
+ "sector_coverage": 0.0,
}
@@ -141,6 +146,8 @@ def test_csi300_reports_hand_picked_fallback(
"constituent_count": 2,
"price_adjustment": "qfq",
"dropped_unadjustable": 0,
+ "sector_source": None,
+ "sector_coverage": 0.0,
}
diff --git a/agent/tests/test_bench_multiple_testing.py b/agent/tests/test_bench_multiple_testing.py
index 45855b227..2fe4402cf 100644
--- a/agent/tests/test_bench_multiple_testing.py
+++ b/agent/tests/test_bench_multiple_testing.py
@@ -42,7 +42,7 @@ def _setup(monkeypatch, n_alphas=8, n_days=120):
)
monkeypatch.setattr("src.factors.bench_runner._load_universe_panel", lambda u, p: panel)
- monkeypatch.setattr("src.factors.bench_runner._compute_forward_returns", lambda p: return_df)
+ monkeypatch.setattr("src.factors.bench_runner._compute_forward_returns", lambda p, horizon=1: return_df)
monkeypatch.setattr("src.factors.bench_runner.get_default_registry", lambda: reg)
return reg
diff --git a/agent/tests/test_bench_parallel.py b/agent/tests/test_bench_parallel.py
index aa682a212..3c89c56d6 100644
--- a/agent/tests/test_bench_parallel.py
+++ b/agent/tests/test_bench_parallel.py
@@ -80,7 +80,7 @@ class TestParallelBench:
mock_reg.compute.side_effect = lambda aid, p: p["close"] * np.random.randn(*p["close"].shape)
monkeypatch.setattr("src.factors.bench_runner._load_universe_panel", lambda u, p: panel)
- monkeypatch.setattr("src.factors.bench_runner._compute_forward_returns", lambda p: return_df)
+ monkeypatch.setattr("src.factors.bench_runner._compute_forward_returns", lambda p, horizon=1: return_df)
monkeypatch.setattr("src.factors.bench_runner.get_default_registry", lambda: mock_reg)
return mock_reg
diff --git a/agent/tests/test_bench_universe_selection.py b/agent/tests/test_bench_universe_selection.py
new file mode 100644
index 000000000..c89ab7e05
--- /dev/null
+++ b/agent/tests/test_bench_universe_selection.py
@@ -0,0 +1,160 @@
+"""Universe-support selection: fund:* alphas exclude with disclosure off sp500.
+
+``--zoo fundamental --universe csi300`` used to hard-fail the whole bench
+("Choose the S&P 500 universe") because the SEC-fed ``fund:*`` alphas cannot
+be served there, while the mirror case — CN ``val:*`` alphas on sp500 —
+skips cleanly per alpha. The runners now exclude the unservable alphas up
+front, disclose them in the result envelope, and only error when nothing is
+left to bench. ``_validate_bench_data_requirements`` stays as the backstop
+for direct callers (its own pinned tests are untouched).
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, Mock
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from src.tools.alpha_bench_tool import _split_alphas_by_universe_support
+
+_SPECS = {
+ "fund_us": {"columns_required": ["fund:roe"], "theme": ["quality"], "formula_latex": ""},
+ "fund_cn": {"columns_required": ["val:pb"], "theme": ["value"], "formula_latex": ""},
+ "px": {"columns_required": ["close"], "theme": ["momentum"], "formula_latex": ""},
+}
+
+
+def _registry(specs: dict[str, dict]) -> MagicMock:
+ reg = MagicMock()
+ reg.list.return_value = list(specs)
+ reg.get.side_effect = lambda aid: SimpleNamespace(meta=specs[aid])
+ return reg
+
+
+# ── splitter ─────────────────────────────────────────────────────────────────
+
+
+def test_splitter_keeps_everything_on_sp500() -> None:
+ kept, excluded = _split_alphas_by_universe_support(_registry(_SPECS), list(_SPECS), "sp500")
+
+ assert kept == list(_SPECS)
+ assert excluded == []
+
+
[email protected]("universe", ["csi300", "btc-usdt"])
+def test_splitter_excludes_fund_alphas_off_sp500(universe: str) -> None:
+ kept, excluded = _split_alphas_by_universe_support(_registry(_SPECS), list(_SPECS), universe)
+
+ assert kept == ["fund_cn", "px"]
+ assert excluded == ["fund_us"]
+
+
+def test_splitter_treats_missing_columns_required_as_benchable() -> None:
+ reg = _registry({"bare": {"theme": ["test"], "formula_latex": ""}})
+
+ kept, excluded = _split_alphas_by_universe_support(reg, ["bare"], "csi300")
+
+ assert kept == ["bare"]
+ assert excluded == []
+
+
+# ── run_bench ────────────────────────────────────────────────────────────────
+
+
+def _panel() -> dict[str, pd.DataFrame]:
+ rng = np.random.default_rng(7)
+ dates = pd.date_range("2020-01-01", periods=120, freq="B")
+ close = pd.DataFrame(
+ np.cumsum(rng.standard_normal((120, 6)), axis=0) + 100.0,
+ index=dates,
+ columns=[f"SYM{i}" for i in range(6)],
+ )
+ return {"close": close}
+
+
+def test_run_bench_excludes_with_disclosure_and_benches_the_rest(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from src.factors.bench_runner import run_bench
+
+ panel = _panel()
+ monkeypatch.setattr("src.factors.bench_runner._load_universe_panel", lambda u, p: panel)
+ monkeypatch.setattr(
+ "src.factors.bench_runner._prepare_bench_panel", lambda reg, ids, pnl, u, p: pnl
+ )
+ monkeypatch.setenv("VIBE_TRADING_BENCH_WORKERS", "1")
+ reg = _registry(_SPECS)
+ rng = np.random.default_rng(11)
+ reg.compute.side_effect = lambda aid, p: pd.DataFrame(
+ rng.standard_normal(p["close"].shape), index=p["close"].index, columns=p["close"].columns
+ )
+
+ result = run_bench(zoo="fundamental", universe="csi300", period="2020-2021", registry=reg)
+
+ assert result["status"] == "ok"
+ assert result["universe_excluded"] == ["fund_us"]
+ assert result["n_alphas_tested"] == 2
+
+
+def test_run_bench_all_excluded_errors_before_loading_the_panel(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from src.factors.bench_runner import run_bench
+
+ fetch = Mock()
+ monkeypatch.setattr("src.factors.bench_runner._load_universe_panel", fetch)
+ reg = _registry({"fund_us": _SPECS["fund_us"]})
+
+ result = run_bench(zoo="fundamental", universe="csi300", period="2020-2021", registry=reg)
+
+ assert result["status"] == "error"
+ assert "SEC US filings" in result["error"]
+ assert result["universe_excluded"] == ["fund_us"]
+ fetch.assert_not_called()
+
+
+def test_run_bench_sp500_selection_is_untouched(monkeypatch: pytest.MonkeyPatch) -> None:
+ from src.factors.bench_runner import run_bench
+
+ panel = _panel()
+ monkeypatch.setattr("src.factors.bench_runner._load_universe_panel", lambda u, p: panel)
+ monkeypatch.setattr(
+ "src.factors.bench_runner._prepare_bench_panel", lambda reg, ids, pnl, u, p: pnl
+ )
+ monkeypatch.setenv("VIBE_TRADING_BENCH_WORKERS", "1")
+ reg = _registry(_SPECS)
+ rng = np.random.default_rng(13)
+ reg.compute.side_effect = lambda aid, p: pd.DataFrame(
+ rng.standard_normal(p["close"].shape), index=p["close"].index, columns=p["close"].columns
+ )
+
+ result = run_bench(zoo="fundamental", universe="sp500", period="2020-2021", registry=reg)
+
+ assert result["status"] == "ok"
+ assert "universe_excluded" not in result
+ assert result["n_alphas_tested"] == 3
+
+
+# ── tool path ────────────────────────────────────────────────────────────────
+
+
+def test_tool_all_excluded_returns_error_envelope(
+ monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+ import src.tools.alpha_bench_tool as tool
+
+ reg = _registry({"fund_us": _SPECS["fund_us"]})
+ monkeypatch.setattr("src.factors.registry.get_default_registry", lambda: reg)
+ monkeypatch.setattr(tool, "_default_output_dir", lambda: tmp_path)
+ load = Mock()
+ monkeypatch.setattr(tool, "_load_universe_panel", load)
+
+ result = tool.run_alpha_bench(universe="csi300", period="2020-2021", zoo="fundamental")
+
+ assert result["status"] == "error"
+ assert "SEC US filings" in result["error"]
+ assert result["universe_excluded"] == ["fund_us"]
+ load.assert_not_called()
diff --git a/agent/tests/test_industry_loader.py b/agent/tests/test_industry_loader.py
new file mode 100644
index 000000000..871795511
--- /dev/null
+++ b/agent/tests/test_industry_loader.py
@@ -0,0 +1,324 @@
+"""PIT contract for ``backtest.loaders.industry_loader``.
+
+Every test injects a fake tushare API — no network. The behaviours pinned here
+are the ones a silent bug would ruin: ``in_date`` inclusive / ``out_date``
+exclusive membership boundaries, later-``in_date``-wins on overlapping rows,
+the 2000-row truncation guard's per-L1 refetch, placeholder-token rejection,
+graceful degradation on provider failure, and the never-invent-a-label rule
+(unmapped symbols stay NaN).
+"""
+from __future__ import annotations
+
+import sys
+from types import SimpleNamespace
+from typing import Any
+
+import pandas as pd
+import pytest
+
+from backtest.loaders.industry_loader import (
+ load_industry_frame,
+ load_industry_frame_with_coverage,
+ validate_industry_params,
+)
+
+_INDEX = pd.to_datetime(["2024-01-01", "2024-01-02", "2024-01-03", "2024-01-04"])
+_SYMBOLS = ["600000.SH", "000001.SZ"]
+
+
+def _row(
+ ts_code: str,
+ l1_name: str,
+ in_date: str,
+ out_date: str | None = None,
+ *,
+ l2_name: str = "L2-default",
+ l3_name: str = "L3-default",
+) -> dict[str, Any]:
+ return {
+ "l1_code": f"800-{l1_name}",
+ "l1_name": l1_name,
+ "l2_code": f"801-{l2_name}",
+ "l2_name": l2_name,
+ "l3_code": f"802-{l3_name}",
+ "l3_name": l3_name,
+ "ts_code": ts_code,
+ "name": ts_code.split(".")[0],
+ "in_date": in_date,
+ "out_date": out_date,
+ "is_new": "Y" if out_date is None else "N",
+ }
+
+
+def _frame(rows: list[dict[str, Any]]) -> pd.DataFrame:
+ return pd.DataFrame(rows)
+
+
+class _FakeApi:
+ """Serves a fixed membership snapshot; records every call.
+
+ Mirrors the real endpoint's ``is_new`` filtering (server default "Y"):
+ rows carry is_new = "Y" when out_date is null, "N" otherwise.
+ """
+
+ def __init__(self, snapshot: pd.DataFrame | Exception) -> None:
+ self.snapshot = snapshot
+ self.calls: list[dict[str, Any]] = []
+
+ def index_member_all(self, **kwargs: Any) -> pd.DataFrame:
+ self.calls.append(kwargs)
+ if isinstance(self.snapshot, Exception):
+ raise self.snapshot
+ return _filter_is_new(self.snapshot, kwargs)
+
+
+def _filter_is_new(frame: pd.DataFrame, kwargs: dict[str, Any]) -> pd.DataFrame:
+ is_new = kwargs.get("is_new")
+ if is_new is not None and "is_new" in getattr(frame, "columns", []):
+ return frame[frame["is_new"] == is_new]
+ return frame
+
+
+def _load(api: Any, symbols: list[str] | None = None, **kwargs: Any) -> pd.DataFrame:
+ return load_industry_frame(
+ symbols=symbols or _SYMBOLS,
+ start="2024-01-01",
+ end="2024-01-04",
+ index=_INDEX,
+ api=api,
+ **kwargs,
+ )
+
+
+# ------------------------------------------------------------- PIT boundaries
+
+
+def test_in_date_is_inclusive() -> None:
+ api = _FakeApi(_frame([_row("600000.SH", "银行", "20240102")]))
+
+ frame = _load(api)
+
+ assert pd.isna(frame.loc["2024-01-01", "600000.SH"])
+ assert frame.loc["2024-01-02", "600000.SH"] == "银行"
+ assert frame.loc["2024-01-04", "600000.SH"] == "银行" # null out_date = current
+
+
+def test_out_date_is_exclusive() -> None:
+ api = _FakeApi(_frame([_row("600000.SH", "银行", "20240101", "20240103")]))
+
+ frame = _load(api)
+
+ assert frame.loc["2024-01-01", "600000.SH"] == "银行"
+ assert frame.loc["2024-01-02", "600000.SH"] == "银行"
+ assert pd.isna(frame.loc["2024-01-03", "600000.SH"])
+ assert pd.isna(frame.loc["2024-01-04", "600000.SH"])
+
+
+def test_historical_membership_applies_only_inside_its_interval() -> None:
+ """A closed row labels the past; the open row labels the present."""
+ api = _FakeApi(
+ _frame(
+ [
+ _row("600000.SH", "旧行业", "20230101", "20240103"),
+ _row("600000.SH", "新行业", "20240103"),
+ ]
+ )
+ )
+
+ frame = _load(api)
+
+ assert frame.loc["2024-01-01", "600000.SH"] == "旧行业"
+ assert frame.loc["2024-01-02", "600000.SH"] == "旧行业"
+ assert frame.loc["2024-01-03", "600000.SH"] == "新行业"
+ assert frame.loc["2024-01-04", "600000.SH"] == "新行业"
+
+
+def test_overlapping_rows_resolve_to_the_later_in_date() -> None:
+ api = _FakeApi(
+ _frame(
+ [
+ _row("600000.SH", "A", "20240101"),
+ _row("600000.SH", "B", "20240103"),
+ ]
+ )
+ )
+
+ frame = _load(api)
+
+ assert frame.loc["2024-01-02", "600000.SH"] == "A"
+ assert frame.loc["2024-01-03", "600000.SH"] == "B"
+ assert frame.loc["2024-01-04", "600000.SH"] == "B"
+
+
+def test_row_order_does_not_change_the_winner() -> None:
+ rows = [_row("600000.SH", "A", "20240101"), _row("600000.SH", "B", "20240103")]
+ forward = _load(_FakeApi(_frame(rows)))
+ reversed_ = _load(_FakeApi(_frame(list(reversed(rows)))))
+
+ pd.testing.assert_frame_equal(forward, reversed_)
+
+
+# ---------------------------------------------------------------- never invent
+
+
+def test_unmapped_symbols_and_dates_stay_nan() -> None:
+ api = _FakeApi(_frame([_row("600000.SH", "银行", "20240101")]))
+
+ frame, coverage = load_industry_frame_with_coverage(
+ symbols=_SYMBOLS, start="2024-01-01", end="2024-01-04", index=_INDEX, api=api
+ )
+
+ assert frame["000001.SZ"].isna().all()
+ assert list(frame.columns) == _SYMBOLS
+ assert list(frame.index) == list(_INDEX)
+ assert coverage == pytest.approx(0.5)
+
+
+def test_rows_with_a_blank_label_are_dropped_not_defaulted() -> None:
+ api = _FakeApi(
+ _frame(
+ [
+ _row("600000.SH", None, "20240101"),
+ {"ts_code": "000001.SZ", "l1_name": "银行", "in_date": None, "out_date": None},
+ ]
+ )
+ )
+
+ frame, coverage = load_industry_frame_with_coverage(
+ symbols=_SYMBOLS, start="2024-01-01", end="2024-01-04", index=_INDEX, api=api
+ )
+
+ assert frame.isna().all().all()
+ assert coverage == 0.0
+
+
+def test_level_selects_the_name_column() -> None:
+ api = _FakeApi(
+ _frame([_row("600000.SH", "L1x", "20240101", l2_name="L2x", l3_name="L3x")])
+ )
+
+ assert _load(api, level="L1").loc["2024-01-01", "600000.SH"] == "L1x"
+ assert _load(api, level="L2").loc["2024-01-01", "600000.SH"] == "L2x"
+ assert _load(api, level="L3").loc["2024-01-01", "600000.SH"] == "L3x"
+
+
+# ------------------------------------------------------------ validation gate
+
+
[email protected]("level", ["L0", "l1", "L4", ""])
+def test_invalid_level_raises(level: str) -> None:
+ with pytest.raises(ValueError, match="unsupported industry level"):
+ validate_industry_params(level, "SW2021")
+
+
[email protected]("src", ["", " "])
+def test_empty_src_raises(src: str) -> None:
+ with pytest.raises(ValueError, match="non-empty"):
+ validate_industry_params("L1", src)
+
+
+def test_invalid_level_raises_through_the_loader() -> None:
+ with pytest.raises(ValueError, match="unsupported industry level"):
+ _load(_FakeApi(_frame([])), level="L9")
+
+
+# ------------------------------------------------------------ truncation guard
+
+
+def test_exactly_2000_rows_triggers_the_per_l1_refetch() -> None:
+ """A snapshot at the documented cap is treated as truncated and refetched."""
+ truncated = _frame([_row(f"99999{i}.SZ", "填充", "20240101") for i in range(2000)])
+ real_a = _frame([_row("600000.SH", "银行", "20240101")])
+ real_b = _frame([_row("000001.SZ", "非银金融", "20240101")])
+
+ class _TruncatingApi:
+ def __init__(self) -> None:
+ self.member_calls: list[dict[str, Any]] = []
+ self.classify_calls: list[dict[str, Any]] = []
+
+ def index_member_all(self, **kwargs: Any) -> pd.DataFrame:
+ self.member_calls.append(kwargs)
+ if "l1_code" not in kwargs:
+ return _filter_is_new(truncated, kwargs)
+ return _filter_is_new(
+ {"801780.SI": real_a, "801790.SI": real_b}[kwargs["l1_code"]], kwargs
+ )
+
+ def index_classify(self, **kwargs: Any) -> pd.DataFrame:
+ self.classify_calls.append(kwargs)
+ return pd.DataFrame(
+ {"index_code": ["801780.SI", "801790.SI"], "industry_name": ["银行", "非银金融"]}
+ )
+
+ api = _TruncatingApi()
+ frame = _load(api)
+
+ assert api.classify_calls == [{"level": "L1", "src": "SW2021"}]
+ assert [call.get("l1_code") for call in api.member_calls] == [
+ None,
+ "801780.SI",
+ "801790.SI",
+ None,
+ ]
+ assert frame.loc["2024-01-01", "600000.SH"] == "银行"
+ assert frame.loc["2024-01-01", "000001.SZ"] == "非银金融"
+
+
+def test_below_the_cap_snapshot_is_used_as_is() -> None:
+ snapshot = _frame([_row("600000.SH", "银行", "20240101")])
+ api = _FakeApi(snapshot)
+
+ frame = _load(api)
+
+ assert api.calls == [{"is_new": "Y"}, {"is_new": "N"}]
+ assert frame.loc["2024-01-01", "600000.SH"] == "银行"
+
+
+def test_src_is_never_passed_to_index_member_all() -> None:
+ """Pins the live-verified endpoint quirk: an undocumented ``src`` param
+ silently empties the index_member_all response (0 rows, HTTP 200)."""
+ api = _FakeApi(_frame([_row("600000.SH", "银行", "20240101")]))
+
+ _load(api, src="SW2021")
+
+ assert api.calls, "expected index_member_all to be called"
+ for call in api.calls:
+ assert "src" not in call
+
+
+# ------------------------------------------------------------- failure paths
+
+
+def test_provider_exception_degrades_to_an_all_none_frame() -> None:
+ api = _FakeApi(RuntimeError("provider down"))
+
+ frame, coverage = load_industry_frame_with_coverage(
+ symbols=_SYMBOLS, start="2024-01-01", end="2024-01-04", index=_INDEX, api=api
+ )
+
+ assert frame.shape == (len(_INDEX), len(_SYMBOLS))
+ assert frame.isna().all().all()
+ assert coverage == 0.0
+
+
+def test_empty_snapshot_degrades_to_an_all_none_frame() -> None:
+ frame = _load(_FakeApi(_frame([])))
+
+ assert frame.isna().all().all()
+
+
+def test_snapshot_missing_pit_columns_degrades_to_an_all_none_frame() -> None:
+ """A payload without in_date/out_date cannot establish membership — degrade, never guess."""
+ frame = _load(_FakeApi(pd.DataFrame({"ts_code": ["600000.SH"], "l1_name": ["银行"]})))
+
+ assert frame.isna().all().all()
+
+
+def test_placeholder_token_raises_runtime_error(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("TUSHARE_TOKEN", "")
+ monkeypatch.setitem(sys.modules, "tushare", SimpleNamespace(pro_api=lambda _token: None))
+
+ with pytest.raises(RuntimeError, match="TUSHARE_TOKEN not configured"):
+ load_industry_frame(
+ symbols=_SYMBOLS, start="2024-01-01", end="2024-01-04", index=_INDEX
+ )
diff --git a/agent/tests/test_mcp_alpha_zoo_contract.py b/agent/tests/test_mcp_alpha_zoo_contract.py
index af68c14fb..fb0422847 100644
--- a/agent/tests/test_mcp_alpha_zoo_contract.py
+++ b/agent/tests/test_mcp_alpha_zoo_contract.py
@@ -92,6 +92,7 @@ def test_alpha_bench_forwards_selection(monkeypatch) -> None:
"universe": "sp500",
"period": "2018-2025",
"top": 10,
+ "horizon": 1,
"zoo": "alpha101",
"output_dir": str(output_dir.resolve()),
},
@@ -187,6 +188,50 @@ def test_alpha_bench_rejects_unbounded_top(monkeypatch) -> None:
assert registry.calls == []
+def test_alpha_bench_forwards_horizon(monkeypatch) -> None:
+ registry = _RecordingRegistry()
+ monkeypatch.setattr(mcp_server, "_get_registry", lambda: registry)
+
+ _ALPHA_BENCH(
+ universe="sp500",
+ period="2018-2025",
+ zoo="fundamental",
+ horizon=21,
+ )
+
+ assert registry.calls == [
+ (
+ "alpha_bench",
+ {
+ "universe": "sp500",
+ "period": "2018-2025",
+ "top": 20,
+ "horizon": 21,
+ "zoo": "fundamental",
+ },
+ )
+ ]
+
+
[email protected]("bad", [0, -1, 253, 21.5, "21", True])
+def test_alpha_bench_rejects_invalid_horizon(monkeypatch, bad) -> None:
+ registry = _RecordingRegistry()
+ monkeypatch.setattr(mcp_server, "_get_registry", lambda: registry)
+
+ result = json.loads(
+ _ALPHA_BENCH(
+ universe="sp500",
+ period="2018-2025",
+ zoo="alpha101",
+ horizon=bad,
+ )
+ )
+
+ assert result["status"] == "error"
+ assert "between 1 and 252" in result["error"]
+ assert registry.calls == []
+
+
def test_alpha_bench_rejects_output_outside_allowed_roots(monkeypatch) -> None:
registry = _RecordingRegistry()
monkeypatch.setattr(mcp_server, "_get_registry", lambda: registry)
@@ -230,7 +275,7 @@ def test_alpha_bench_does_not_follow_preexisting_report_symlink(monkeypatch, tmp
monkeypatch.setattr(alpha_bench_module, "datetime", _FixedDateTime)
monkeypatch.setattr(alpha_bench_module.secrets, "token_hex", lambda length: "fixed")
monkeypatch.setattr(alpha_bench_module, "_load_universe_panel", lambda *args, **kwargs: {})
- monkeypatch.setattr(alpha_bench_module, "_compute_forward_returns", lambda panel: {})
+ monkeypatch.setattr(alpha_bench_module, "_compute_forward_returns", lambda panel, horizon=1: {})
monkeypatch.setattr(
alpha_bench_module,
"_bench_one_alpha",
diff --git a/wiki/alpha-library/i18n.zh.json b/wiki/alpha-library/i18n.zh.json
index 4b4c5c115..707198fad 100644
--- a/wiki/alpha-library/i18n.zh.json
+++ b/wiki/alpha-library/i18n.zh.json
@@ -180,6 +180,10 @@
"en": "Trailing dividend yield from the val: namespace (tushare daily_basic dv_ttm, CN A-share only), reported in percent units — cross-sectional z-scoring is scale-invariant, so no unit conversion is applied. High dividend yield scores high. Keyed by trade_date, so PIT-safe by construction with no filing lag. Missing dates or non-CN symbols stay NaN and are excluded from that date's cross-section. Lineage: JoinQuant style-pro divyild; akshare/Eastmoney dv_ttm convention.",
"zh": "来自 val: 命名空间的滚动股息率(tushare daily_basic dv_ttm,仅 CN A 股),以百分比单位报告——截面 z 打分具有尺度不变性,因此不做单位换算。高股息率得分高。按 trade_date 键控,因此构造上即时点正确(PIT),无财报滞后。缺失日期或非 CN 标的保持 NaN,并被排除在当日截面之外。血缘:JoinQuant style-pro divyild;akshare/东方财富 dv_ttm 口径。"
},
+ "fund_dividend_yield_ind_neutral": {
+ "en": "Industry-neutralized trailing dividend yield: each name is z-scored against its Shenwan level-1 industry peers instead of the whole cross-section (sector tag from tushare index_member_all SW2021 membership, point-in-time via in_date/out_date). This removes the industry confounding that dominates raw A-share dividend yield — mature banks and utilities pay structurally high dividends while growth industries pay almost none, so a raw high-yield screen is largely an industry bet. High dividend yield relative to industry peers scores high; dv_ttm is reported in percent units and cross-sectional z-scoring is scale-invariant, so no unit conversion is applied. A name with no industry label on a date stays NaN and is excluded from that date's cross-section; an industry group with fewer than two labelled names cannot form a within-group z-score and stays NaN. Keyed by trade_date, so PIT-safe by construction with no filing lag. Membership is point-in-time but the SW2021 taxonomy itself is retroactive — a name reclassified in 2021 carries its 2021 industry back through history. Lineage: industry-neutral variant of fund_dividend_yield (#1789 follow-up).",
+ "zh": "行业中性化的滚动股息率:每只股票在其申万一级行业同类中做 z 打分,而非在全截面上(sector 标签来自 tushare index_member_all SW2021 成分数据,通过 in_date/out_date 实现时点正确 PIT)。这消除了主导 A 股原始股息率的行业混淆——成熟的银行与公用事业结构性高分红,而成长行业几乎不分红,因此原始高股息筛选在很大程度上是行业押注。相对行业同类股息率高者得分高;dv_ttm 以百分比单位报告,截面 z 打分具有尺度不变性,因此不做单位换算。某日无行业标签的股票保持 NaN,并被排除在当日截面之外;标签成员不足两只的行业组无法构成组内 z 分数,保持 NaN。按 trade_date 键控,因此构造上即时点正确(PIT),无财报滞后。成分归属是时点正确的(PIT),但 SW2021 分类体系本身是回溯性的——2021 年被重新分类的股票会将其 2021 行业标签带回历史。血缘:fund_dividend_yield 的行业中性变体(#1789 后续)。"
+ },
"fund_earnings_growth": {
"en": "PIT-safe earnings growth from the fundamental panel's derived field ``earnings_growth``. The schema-side formula is sign-safe: delta net_income / abs(lag_365d net_income), so a negative year-ago base does not flip the growth sign (the proposal #6 footnote resolution; the alternative NaN-on-negative-base was not chosen). Calendar-day lag per the #1564 lesson. High earnings growth scores high, matching the JoinQuant net_profit_growth_rate convention. Missing statements or a zero/missing year-ago base remain NaN and are excluded from that date's cross-section.",
"zh": "基于基本面面板派生字段 ``earnings_growth`` 的时点正确(PIT)盈利增长。schema 侧公式符号安全:净利润变化量 / abs(滞后 365 天净利润),因此上年基数为负不会翻转增长符号(提案 #6 脚注的决议;未选择负基数置 NaN 的替代方案)。按 #1564 教训使用日历日滞后。高盈利增长得分高,与 JoinQuant net_profit_growth_rate 约定一致。缺失的财务报表或为零/缺失的上年基数保持 NaN,并被排除在当日截面之外。"
@@ -208,10 +212,18 @@
"en": "Nonpositive multiples are excluded rather than ranked as cheap. Inverse price-to-book from the val: namespace (tushare daily_basic pb, CN A-share only): low PB (cheap relative to book value) scores high, the daily-market-data counterpart of fund_book_to_market. Keyed by trade_date, so PIT-safe by construction with no filing lag. Missing dates or non-CN symbols stay NaN and are excluded from that date's cross-section. Lineage: JoinQuant style book_to_price_ratio; akshare/Eastmoney pb convention.",
"zh": "非正估值倍数不参与排名,不能当作低估。来自 val: 命名空间的反向市净率(tushare daily_basic pb,仅 CN A 股):低 PB(相对账面价值便宜)得分高,是 fund_book_to_market 的日频市场口径对应因子。按 trade_date 键控,因此构造上即时点正确(PIT),无财报滞后。缺失日期或非 CN 标的保持 NaN,并被排除在当日截面之外。血缘:JoinQuant style book_to_price_ratio;akshare/东方财富 pb 口径。"
},
+ "fund_pb_ind_neutral": {
+ "en": "Nonpositive multiples are excluded rather than ranked as cheap. Industry-neutralized inverse price-to-book: each name is z-scored against its Shenwan level-1 industry peers instead of the whole cross-section (sector tag from tushare index_member_all SW2021 membership, point-in-time via in_date/out_date). This removes the industry confounding that dominates raw A-share PB — banks and cyclicals are structurally cheap on book value while technology names are structurally expensive, so a raw low-PB screen is largely an industry bet. Low PB relative to industry peers scores high. A name with no industry label on a date stays NaN and is excluded from that date's cross-section; an industry group with fewer than two labelled names cannot form a within-group z-score and stays NaN. Keyed by trade_date, so PIT-safe by construction with no filing lag. Membership is point-in-time but the SW2021 taxonomy itself is retroactive — a name reclassified in 2021 carries its 2021 industry back through history. Lineage: industry-neutral variant of fund_pb (#1789 follow-up).",
+ "zh": "非正估值倍数不参与排名,不能当作低估。行业中性化的反向市净率:每只股票在其申万一级行业同类中做 z 打分,而非在全截面上(sector 标签来自 tushare index_member_all SW2021 成分数据,通过 in_date/out_date 实现时点正确 PIT)。这消除了主导 A 股原始 PB 的行业混淆——银行与周期股在账面价值口径上结构性便宜,而科技股结构性昂贵,因此原始低 PB 筛选在很大程度上是行业押注。相对行业同类 PB 低者得分高。某日无行业标签的股票保持 NaN,并被排除在当日截面之外;标签成员不足两只的行业组无法构成组内 z 分数,保持 NaN。按 trade_date 键控,因此构造上即时点正确(PIT),无财报滞后。成分归属是时点正确的(PIT),但 SW2021 分类体系本身是回溯性的——2021 年被重新分类的股票会将其 2021 行业标签带回历史。血缘:fund_pb 的行业中性变体(#1789 后续)。"
+ },
"fund_ps_ttm": {
"en": "Nonpositive multiples are excluded rather than ranked as cheap. Inverse trailing price-to-sales from the val: namespace (tushare daily_basic ps_ttm, CN A-share only): low PS scores high. PS stays informative for loss-making names where earnings yield fails. Keyed by trade_date, so PIT-safe by construction with no filing lag. Missing dates or non-CN symbols stay NaN and are excluded from that date's cross-section. Lineage: JoinQuant style-pro sales-to-price; akshare/Eastmoney ps_ttm convention.",
"zh": "非正估值倍数不参与排名,不能当作低估。来自 val: 命名空间的反向滚动市销率(tushare daily_basic ps_ttm,仅 CN A 股):低 PS 得分高。PS 对亏损股依然有效(盈利收益率失效的场景)。按 trade_date 键控,因此构造上即时点正确(PIT),无财报滞后。缺失日期或非 CN 标的保持 NaN,并被排除在当日截面之外。血缘:JoinQuant style-pro sales-to-price;akshare/东方财富 ps_ttm 口径。"
},
+ "fund_ps_ttm_ind_neutral": {
+ "en": "Nonpositive multiples are excluded rather than ranked as cheap. Industry-neutralized inverse trailing price-to-sales: each name is z-scored against its Shenwan level-1 industry peers instead of the whole cross-section (sector tag from tushare index_member_all SW2021 membership, point-in-time via in_date/out_date). This removes the industry confounding that dominates raw A-share PS — software and platform names carry structurally high margins and high PS while distributors and manufacturers are structurally low, so a raw low-PS screen is largely an industry bet. Low PS relative to industry peers scores high, and PS stays informative for loss-making names where earnings yield fails. A name with no industry label on a date stays NaN and is excluded from that date's cross-section; an industry group with fewer than two labelled names cannot form a within-group z-score and stays NaN. Keyed by trade_date, so PIT-safe by construction with no filing lag. Membership is point-in-time but the SW2021 taxonomy itself is retroactive — a name reclassified in 2021 carries its 2021 industry back through history. Lineage: industry-neutral variant of fund_ps_ttm (#1789 follow-up).",
+ "zh": "非正估值倍数不参与排名,不能当作低估。行业中性化的反向滚动市销率:每只股票在其申万一级行业同类中做 z 打分,而非在全截面上(sector 标签来自 tushare index_member_all SW2021 成分数据,通过 in_date/out_date 实现时点正确 PIT)。这消除了主导 A 股原始 PS 的行业混淆——软件与平台类公司毛利率结构性高、PS 也高,而分销与制造商结构性低,因此原始低 PS 筛选在很大程度上是行业押注。相对行业同类 PS 低者得分高,且 PS 对亏损股依然有效(盈利收益率失效的场景)。某日无行业标签的股票保持 NaN,并被排除在当日截面之外;标签成员不足两只的行业组无法构成组内 z 分数,保持 NaN。按 trade_date 键控,因此构造上即时点正确(PIT),无财报滞后。成分归属是时点正确的(PIT),但 SW2021 分类体系本身是回溯性的——2021 年被重新分类的股票会将其 2021 行业标签带回历史。血缘:fund_ps_ttm 的行业中性变体(#1789 后续)。"
+ },
"fund_revenue_growth": {
"en": "PIT-safe revenue growth from the fundamental panel's derived field ``revenue_growth`` (revenue / lag_365d(revenue) - 1, calendar-day lag per the #1564 lesson rather than a row-wise shift). High top-line growth scores high, matching the JoinQuant operating_revenue_growth_rate convention. Missing statements or a missing year-ago base remain NaN and are excluded from that date's cross-section.",
"zh": "基于基本面面板派生字段 ``revenue_growth`` 的时点正确(PIT)营收增长(revenue / lag_365d(revenue) - 1,按 #1564 教训使用日历日滞后而非按行位移)。高顶线增长得分高,与 JoinQuant operating_revenue_growth_rate 约定一致。缺失的财务报表或缺失的上年基数保持 NaN,并被排除在当日截面之外。"
@@ -1294,6 +1306,10 @@
"en": "Dividend yield TTM - dv_ttm (daily market data)",
"zh": "股息率 TTM - dv_ttm(日频市场数据)"
},
+ "fund_dividend_yield_ind_neutral": {
+ "en": "Dividend yield TTM industry-neutral - within-industry dv_ttm (daily market data)",
+ "zh": "股息率行业中性 - 行业内 dv_ttm(日频市场数据)"
+ },
"fund_earnings_growth": {
"en": "Earnings growth - sign-safe YoY net income expansion",
"zh": "盈利增长 - 符号安全的同比净利润扩张"
@@ -1322,10 +1338,18 @@
"en": "P/B - inverse price-to-book (daily market data)",
"zh": "市净率 P/B - 反向市净率(日频市场数据)"
},
+ "fund_pb_ind_neutral": {
+ "en": "P/B industry-neutral - inverse within-industry price-to-book (daily market data)",
+ "zh": "市净率行业中性 - 行业内反向市净率(日频市场数据)"
+ },
"fund_ps_ttm": {
"en": "P/S TTM - inverse price-to-sales (daily market data)",
"zh": "市销率 P/S TTM - 反向滚动市销率(日频市场数据)"
},
+ "fund_ps_ttm_ind_neutral": {
+ "en": "P/S TTM industry-neutral - inverse within-industry price-to-sales (daily market data)",
+ "zh": "市销率行业中性 - 行业内反向滚动市销率(日频市场数据)"
+ },
"fund_revenue_growth": {
"en": "Revenue growth - YoY top-line expansion",
"zh": "营收增长 - 同比顶线扩张"