v0.1.8

## 🧬 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](https://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.

```bash
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

```bash
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?"](https://vibetrading.wiki/research-lab/posts/alpha-191-in-2026.html) — 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](https://github.com/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](https://github.com/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](https://mba.tuck.dartmouth.edu/pages/faculty/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](https://arxiv.org/abs/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**: https://github.com/HKUDS/Vibe-Trading/compare/v0.1.7...v0.1.8

<details>
<summary><b>Notable commits since v0.1.7</b> (66 non-merge)</summary>

- `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.

</details>

## 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`).