v0.1.8 — Alpha Zoo v1 (452 alphas across 4 zoos)

🧬 v0.1.8 — Alpha Zoo v1 + research workflow polish

v0.1.8 is a major content release for Vibe-Trading. The headline is the Alpha Zoo: 452 pre-built quantitative alphas across four bundled libraries — qlib158, alpha101, gtja191, and academic — with a one-line CLI to bench any zoo on your universe, agent integration via two new tools, four new REST routes with SSE-streamed progress, and a browse/detail/bench Web UI at /alpha-zoo. The release also lands the long-running MCP client integration, a Trust Layer run card in the Web UI, the public wiki launch at vibetrading.wiki, the Hypothesis Registry MVP, and a substantial security + hardening pass driven by community PRs.

This release is available on PyPI, ClawHub, and GitHub Releases.

pip install -U vibe-trading-ai
# or
uv tool install --reinstall vibe-trading-ai

Highlights

🧬 Alpha Zoo — 452 pre-built quant alphas across 4 zoos

Cross-sectional formulaic alphas with metadata, lookahead-banned at the operator layer, registry-validated, and reachable from CLI, agent, REST API, and Web UI:

• qlib158 — 154 alphas. Apache-2.0 port of Microsoft Qlib's Alpha158 feature handler, with the upstream commit SHA pinned in every adapted module's header and the upstream NOTICE bundled.
• alpha101 — 101 alphas. Implementation of Kakushadze (2015) "101 Formulaic Alphas" (arXiv:1601.00991), written from the paper appendix. 19 industry-neutral alphas flag requires_sector=True and skip cleanly on universes without sector tags.
• gtja191 — 191 alphas. Implementation of Guotai Junan Securities' 2014 "191 Short-period Trading Alpha Factors" research report. Operator-mapping decisions (SMA / WMA / REGBETA / HIGHDAY interpretations) documented per alpha.
• academic — 6 factors. Fama-French 5 + Carhart momentum, shipped as honest price-based proxies (the canonical FF series need book-to-market / profitability / investment growth fundamentals we don't bundle). The nicknames carry a [PRICE PROXY] prefix; Kenneth French's data library is referenced for users who need the canonical monthly returns.

Each alpha carries a __alpha_meta__ dict (formula LaTeX, theme, universe, columns_required, warmup, decay horizon, notes) validated by a pydantic extra="forbid" schema.

🖥️ One-line CLI

vibe-trading alpha list --zoo gtja191 --theme momentum --limit 10
vibe-trading alpha show gtja191_171
vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20
vibe-trading alpha compare --all
vibe-trading alpha export-manifest --out wiki/alpha-library/manifest.json

bench drives a Rich progress bar with live alpha-id + ETA banner, returns proper exit codes on failure, and silences scipy ConstantInputWarning noise. All five subcommands honour TTY hints and a --json mode for scripting.

🌐 Web UI at /alpha-zoo + 4 REST routes with SSE

Three views in the React Web UI: Browse (4 zoo cards, filter bar, paginated table), Detail (formula, metadata, source code), Bench (form → SSE-streamed progress → Alive/Reversed/Dead stat cards + Top-5-by-IR + Most-Reversed tables + by-theme bar chart). Auto-Vite route at /alpha-zoo, nav entry in the Layout.

GET  /alpha/list?zoo=&theme=&universe=&limit=
GET  /alpha/{alpha_id}
POST /alpha/bench               (body: {zoo, universe, period, top}) → 202 + job_id
GET  /alpha/bench/{job_id}/stream   (SSE: progress / result / done / error)

Background bench jobs run via asyncio.to_thread with a 2-concurrent-job semaphore (429 on saturation), in-memory state with 1-hour TTL, 15-second heartbeat comment frames to keep proxies from closing idle streams, and sanitised error messages so unexpected exceptions don't leak server-side paths.

🤖 Agent integration

Two new auto-discovered tools (AlphaZooTool, AlphaBenchTool) plus a panel-style ZooSignalEngine.from_zoo(...) factory in the multi-factor skill that composes one or more alphas into a long-short signal compatible with the existing backtest engines. The legacy per-symbol example_signal_engine.py is preserved for backward compatibility.

🛡️ Safety floor

Quality gates that fire on every PR and vibe-trading alpha bench run:

• AST purity gate (test_alpha_purity.py) — scans every zoo/**/*.py module, allows only pandas, numpy, scipy.*, src.factors.base, __future__, typing, math, dataclasses imports; bans os / sys / subprocess / socket / urllib / requests / httpx / pathlib / Path / open / eval / exec / compile / __import__ plus breakpoint / input / globals / locals / vars / __class__ / __subclasses__ / __mro__ / __globals__ / __builtins__, plus dunder-string getattr access (including BinOp-concatenated dunders).
• Lookahead sentinel test (test_lookahead.py) — 300-row synthetic panel; corrupt rows past the probe; assert factor at probe unchanged within 1e-9.
• pytest-socket integration — factors test suite runs network-disabled.
• CI grep gates (tools/ci_grep_gates.sh) — rejects yaml.load( without safe_load, the trademarked-name string in shipped artifacts, and any per-stock-code data leak in wiki/**/*.{json,csv,html}.

📡 MCP client integration (stdio v1)

The agent can now load tools from external MCP servers via ~/.vibe-trading/agent.json, opt-in per session via ALLOW_SESSION_MCP_SERVERS=1. Stdio transport only in v1; HTTP/SSE deferred. Tool-name collisions get a deterministic hash suffix; remote-tool failures normalise to error payloads instead of bubbling. Big thank-you to @shadowinlife (#83) for the end-to-end implementation and the security-conscious defaults.

🪪 Trust Layer run card in Web UI

The run detail page now renders run_card.json alongside metrics and artifacts, completing the UI half of the trust-layer work that landed earlier.

🧠 Hypothesis Registry (backend MVP)

create_hypothesis / update_hypothesis / link_backtest / search_hypotheses give research hypotheses a durable lifecycle, links to run cards, and invalidation notes. UI integration to follow.

🔬 Memory, swarm, and tooling hardening

A focused PR cycle from @Teerapat-Vatpitak strengthened the lower-level surfaces this release leans on:

• PersistentMemory.add() hardened against length overflow, empty / whitespace-only names, and C0/C1 control bytes (#112)
• Swarm error surfacing + output contract, Windows-safe store, path redaction (#119)
• MCP unresolved-symbol, finite options validation, row cap (#120)
• Bounded CCXT + OKX fetch with timeout / retry / budget (#121)
• read_url Jina dependency disclosure + cache opt-out (#122)
• API path-ID validation for run/session routes (#80, via @SJoon99)

Plus @hp083625 taught memory recall to treat underscores as token boundaries (#87) so mcp_wiring_test matches "mcp wiring", @voidborne-d kept the Vite dev proxy honoring VITE_API_URL and fixed CJK slug preservation (#82, #95), and @ykykj added the CLI startup preflight (#96).

🌐 Public wiki at vibetrading.wiki

The wiki ships its own Alpha Library renderer (wiki/scripts/build_alpha_library.py) that reads the manifest JSON and emits 452 per-alpha pages + 4 per-zoo overview pages, each with script-src 'none' CSP. The research-lab gains its first long-form post: "Which of the 191 GTJA alphas still work in 2026?" — aggregate IC, theme survival rates, and the top alphas that survive eight years of out-of-sample data on CSI 300 (2018-2025), with a survivorship-bias caveat.

Install / upgrade

Channel	Command
PyPI	pip install -U vibe-trading-ai
uv tool	uv tool install --reinstall vibe-trading-ai
ClawHub (Claude Desktop / OpenClaw / MCP clients)	clawhub install vibe-trading or update the installed skill
Docker	docker compose pull && docker compose up -d

Remote API/Web deployments should set API_AUTH_KEY and explicit trusted CORS origins. Local CLI and localhost Web UI workflows remain low-friction.

By the numbers

• 66 non-merge commits since v0.1.6's successor branch (since v0.1.7)
• 452 pre-built quant alphas across 4 zoos
• 75 bundled finance skills (+ the alpha-zoo skill folder)
• 31 default agent tools (was 29; +alpha_zoo_tool, +alpha_bench_tool)
• 29 swarm presets
• 6 data sources with auto-fallback: tushare, yfinance, okx, akshare, ccxt, futu
• 7 backtest engines + composite cross-market engine + options portfolio
• 22 MCP tools (alpha tools to be MCP-wrapped in 0.1.9)
• 969 tests passing + 1 documented skip (alpha101_096 NaN-cascade on synthetic panel)

🙌 Credits

This release stands on the shoulders of giants. Heavy emphasis because the Alpha Zoo borrows mathematical content from decades of public research.

Code contributors this cycle

• @warren618 / Haozhe Wu — Alpha Zoo framework + 4 zoos, CLI, Web UI, REST + SSE API, bench runner, safety floor, wiki + research-lab post, multi-language READMEs, integration, release.
• @shadowinlife — MCP client integration (stdio, v1) (#83)
• @Teerapat-Vatpitak — PersistentMemory.add() hardening (#112), swarm error surfacing + Windows-safe store + redaction (#119), MCP unresolved-symbol + options validation (#120), bounded CCXT + OKX fetch (#121), read_url Jina disclosure (#122)
• @SJoon99 — API path-ID validation hardening (#80)
• @hp083625 — memory recall underscore tokenization (#87)
• @voidborne-d — CJK slug preservation in memory (#95), Vite dev proxy VITE_API_URL (#82)
• @ykykj — CLI startup preflight (#96)
• @mrbob-git — Tushare statement-field filtering (#76, #77)
• @Teerapat-Vatpitak (also) — extend tokenizer + slug regex to Thai/Arabic/Hebrew/Cyrillic (#104)

Open-source software cited / bundled

• Microsoft Qlib team (microsoft/qlib) — the qlib158 zoo is an Apache-2.0 port of the Alpha158 feature handler. Commit-pinned in every adapted module's header; upstream NOTICE bundled at agent/src/factors/zoo/qlib158/NOTICE.
• Menooker / KunQuant (Menooker/KunQuant) — Apache-2.0 reference implementations of the 101 formulaic alphas, used only for numerical cross-validation on a sample of alphas at the ±1% level. No code was copied; we wrote from the paper appendix and compared outputs.
• Kenneth R. French Data Library (mba.tuck.dartmouth.edu/.../ken.french/data_library.html) — the canonical Fama-French monthly returns; users who need the real series should pull from there. Our academic zoo ships honest price-based proxies, not the real series.

Academic / research sources cited

• Zura Kakushadze (2015) — "101 Formulaic Alphas", arXiv:1601.00991. Implemented in the alpha101 zoo. Display name throughout the codebase is "Kakushadze 101 Formulaic Alphas"; the trademarked alternative is intentionally absent (CI gate enforced).
• 国泰君安证券 (Guotai Junan Securities), 2014 — "191 个短周期交易型 alpha 因子" research report. Implemented in the gtja191 zoo.
• William F. Sharpe (1964) — "Capital Asset Prices: A Theory of Market Equilibrium under Conditions of Risk". Market factor baseline.
• Eugene F. Fama & Kenneth R. French (1993) — "Common Risk Factors in the Returns on Stocks and Bonds". SMB, HML baselines.
• Eugene F. Fama & Kenneth R. French (2015) — "A Five-Factor Asset Pricing Model". RMW, CMA baselines.
• Mark M. Carhart (1997) — "On Persistence in Mutual Fund Performance". Carhart momentum baseline.
• Kewei Hou, Chen Xue, Lu Zhang (2015) — "Digesting Anomalies: An Investment Approach". Q-factor framing.

The bundled formulas are reproduced as mathematical content (formulas are not subject to copyright); paper prose, tables, and figures are not reproduced in this repository. Each zoo has its own LICENSE.md documenting this stance.

Lab + community

• HKUDS (HKU Data Intelligence Lab) — research direction, infrastructure, and the broader Vibe-Trading platform this builds on.
• Everyone who filed issues, reviewed PRs, and stress-tested the framework in the pre-release cycle. Community PRs from the v0.1.7 cycle whose hardening still underpins the safer defaults this release ships against: lemi9090 (S2W) for the coordinated security validation.

Caveats / Known limitations

• btc-usdt universe is single-asset. Cross-sectional IC needs ≥2 instruments, so alpha101_btc returns alive/reversed/dead = 0/0/0 by construction. A curated crypto-majors multi-symbol basket is planned for 0.2.
• SP500 universe uses today's constituent list as a proxy for point-in-time index membership, introducing survivorship bias. Documented in bench_summary.json["meta"] and in the wiki blog caveat section. Point-in-time constituent source is a 0.2 follow-up.
• MCP server does not yet expose alpha_zoo / alpha_bench tools. The Python agent layer, REST API, CLI, and Web UI all expose them; MCP wrap-up planned for 0.1.9.
• 19 industry-neutral alpha101 alphas (#48, 56, 58, 59, 63, 67, 69, 70, 76, 79, 80, 82, 87, 89, 90, 91, 93, 97, 100) need a sector tag. Tushare provides this; yfinance does not, so SP500 benches skip these 19. Cross-zoo SP500 follow-up will plug a sector data source.
• docs/ is gitignored, internal planning only. Do not push contents of docs/ to public branches.

Changelog

Full changes: v0.1.7...v0.1.8

Notable commits since v0.1.7 (66 non-merge)

• 5237ce3 chore: move tweet draft out of public wiki — Haozhe Wu
• 78bc1e5 chore(0.1.8): version, CHANGELOG, packaging, News across 5 READMEs, SKILL.md — Haozhe Wu
• 7912b77 feat(wiki): Alpha Library auto-render + Alpha 191 in 2026 blog — Haozhe Wu
• 9854035 feat(alpha-zoo): bench runner + CLI + Web UI + 4 REST routes — Haozhe Wu
• 81e2a53 feat(factors): port 452 alphas across 4 zoos — Haozhe Wu
• 7d678aa feat(factors): Alpha Zoo framework — registry, operators, safety gates — Haozhe Wu
• 8d3ae19 refactor(loaders): extract bounded retry/budget pattern into base.py — Haozhe Wu
• 0a254c0 fix(swarm): surface errors, output contract, Windows-safe store, redact paths (#119) — Teerapat-Vatpitak
• cdf343d fix(mcp): unresolved symbols, finite options validation, row cap (#120) — Teerapat-Vatpitak
• e155087 fix(loaders): bound ccxt + okx fetch (timeout, retry, budget) (#121) — Teerapat-Vatpitak
• 199f77a feat: add security scanner and hypothesis registry — Haozhe Wu
• 1b547d2 fix(tools): disclose read_url Jina dependency + cache opt-out (#122) — Teerapat-Vatpitak
• d20b590 fix(loop): populate reason field on AgentLoop cancelled / max-iter exits (#116) — Haozhe Wu
• f1c7a50 feat(swarm): universal data-citation discipline in worker prompt (#115) — Haozhe Wu
• 2c70ef5 feat(agent): add MCP client integration (stdio, v1) (#83) — shadowinlife
• 14b160e feat(run-card): surface trust layer card in web UI — Haozhe Wu
• 379fb0c feat(memory): harden PersistentMemory.add() for control bytes, length, empty names (#112) — Teerapat-Vatpitak
• 4e72ca1 ci: deploy wiki to Cloudflare Pages — Haozhe Wu
• f85f3b8 fix(memory): extend tokenizer + slug regex to Thai/Arabic/Hebrew/Cyrillic (#104) — Teerapat-Vatpitak
• 892cd16 feat(cli): add memory introspection commands — Haozhe Wu
• ... and 46 more — see the compare link above for the full list.

Validation before publishing

• Tests: 969 passed, 1 skipped (pytest agent/tests/factors/); pytest-socket enabled.
• CI grep gates (tools/ci_grep_gates.sh): all 3 pass — no yaml.load( misuse, no trademarked-name leak, no per-stock-code data in wiki/**.
• AST purity gate clean across all 452 alpha modules.
• Lookahead sentinel test clean on all 452 alphas (1 documented skip for NaN-cascade on synthetic panel; not a real lookahead violation).
• Wheel sanity: dist/vibe_trading_ai-0.1.8-py3-none-any.whl (1.7 MB) contains 452 alpha .py files, 4 per-zoo LICENSE.md, the upstream Qlib NOTICE, all framework modules (base, registry, bench_runner, factor_analysis_core, cli_handlers), both new tools, the alpha_routes API module, and all CLI / API entry points. No critical files missing.
• Frontend: npx tsc --noEmit clean.
• Multi-language READMEs: English / 中文 / 日本語 / 한국어 / العربية all updated with consistent 0.1.8 numbers, route table, and Alpha Zoo capability section.
• PyPI vibe-trading-ai==0.1.8 published.
• ClawHub vibe-trading@0.1.8 published (k9709z89sf9j7rzyhz3c96r4p986xf68).