alpha research

# valoswiss-alpha-research

**Macro-categoria**: 📈 QUANT/MARKETS
**Scope**: Discovery e validazione alpha factor — LLM-augmented factor mining + alphalens IC validation + WorldQuant 101 production formulae + Qlib alpha158 feature library + alphagen RL discovery
**Born**: 2026-05-03 (V20 onboarding insieme quant-research, target W1-W6 roadmap)
**Owner downstream**: ADVISOR alpha library curation · SUPERVISOR/ADMIN factor mining batch + IC tear sheet export
**Last aligned**: 2026-05-03 V20

---

## §0 · Pre-flight check (entry rituale dell'agente)

Prima di ogni intervento, verifica in quest'ordine:

1. **Branch + working tree**
   ```bash
   cd ~/git/valoswiss && git status --short && git log -3 --oneline
   ```
2. **Sidecar Python health**
   ```bash
   curl -s http://127.0.0.1:8897/healthz | jq .
   ```
   Deve ritornare `{"status":"ok","version":"...","useReal":true|false,"alphalensAvailable":true|false,"qlibInitialized":true|false}`. Se 502/connection refused → sidecar PM2 down: `pm2 list | grep alpha-research-py`.
3. **NestJS proxy health**
   ```bash
   curl -s http://127.0.0.1:4010/api/alpha-research/health -H "Cookie: valo_token=<dev-token>"
   ```
   Deve ritornare `{ sidecar:{status:'ok'}, circuitBreaker:{state:'closed', failures:0}, llmCascade:{tier:'D-with-fallback'} }`.
4. **Prisma schema sync**
   ```bash
   cd apps/api && npx prisma migrate status
   ```
   Verifica che le 4 model `AlphaFactor` / `AlphaFactorEvaluation` / `AlphaFactorPortfolio` / `AlphaMiningRun` + 2 enum `AlphaFactorStatus` / `AlphaMiningMethod` siano applicati.
5. **Tenant configs**: `tenants/ws.json` e `tenants/az.json` devono avere `"alphaResearch": true` subito dopo `quantResearch`.
6. **Persona pack**: `apps/api/src/common/persona-packs/persona-packs.constants.ts` deve avere `'alphaResearch'` in `defaultModules` per `ADVISOR` + `RELATIONSHIP_MANAGER` (NON in PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL → MIFID II — alpha output advisor-only).
7. **Module registry**: `apps/web/src/lib/module-registry.ts` deve esporre entry `alphaResearch` con `sidebarSection: 'OPERARE'`, `requiredRole: 'ADVISOR'`, `personaHint: 'predictive'`, icon `📈`.
8. **LLM cascade health** (cascade orchestrator OK qui — generation expression, NON quant compute):
   ```bash
   curl -s http://127.0.0.1:4010/api/ai-routing/health -H "Cookie: valo_token=<token>" | jq '.tiers.A,.tiers.B'
   ```
9. **R-Audit gate**: prima di qualsiasi commit su file CRITICAL (vedi §3), eseguire `npx tsx scripts/r-audit.ts <file> --validate-business-logic --severity=MAJOR`.

Se uno qualunque dei 9 punti fallisce, **fermati e annota la deviazione** prima di procedere — la 3-Point Registration è invariante non negoziabile (vedi `feedback_new_module_registration.md`).

---

## §1 · Aree di competenza

### 1.1 Alpha factor discovery — pattern WorldQuant 101 Formulaic Alphas

WorldQuant ha pubblicato (Kakushadze 2015) 101 alpha formulae production-grade. Esempi concreti riusati come template baseline:

**Alpha #1** — short-term mean reversion via signed volatility:
```
rank(Ts_ArgMax(SignedPower((returns < 0 ? stddev(returns, 20) : close), 2), 5)) - 0.5
```

**Alpha #6** — correlation open vs volume invertita (price-volume divergence):
```
-1 * correlation(open, volume, 10)
```

**Alpha #41** — high-low geometric mean vs vwap deviation (intraday range arbitrage):
```
((high * low) ^ 0.5) - vwap
```

**Alpha #54** — open/close range vs high/low signed power:
```
(-1 * (low - close) * (open ^ 5)) / ((low - high) * (close ^ 5))
```

**Alpha #101** — high-low breakout combined volume:
```
((close - open) / ((high - low) + 0.001))
```

### 1.2 Alpha factor discovery — pattern QuantaAlpha LLM mining

```
LLM (Claude Opus 4.7 deep_think via cascade orchestrator)
  ├─ prompt template "Generate N=20 alpha factor expressions for asset class <equity-us>
  │                    using primitives <rank, ts_argmax, correlation, stddev, returns,
  │                    open, high, low, close, volume, vwap>. Constraints:
  │                    no lookahead, max 10 ops, prefer cross-sectional rank wrappers."
  ├─ LLM generates JSON list of expression strings
  ├─ Parser validates AST against grammar
  ├─ Evaluator computes IC + IR + turnover on training fold
  ├─ Top-K selected for evolutionary refinement
  ├─ Mutation operators: ts-window perturb (5→10), op swap (+ → *),
  │                       sub-tree replace, primitive swap (open ↔ vwap)
  ├─ Crossover: parent A sub-tree + parent B sub-tree
  └─ Generation loop N=10, fitness = IC IR alphalens-validated on oos fold
```

### 1.3 Qlib alpha158 + alpha360 feature library

Microsoft Qlib `qlib.contrib.data.handler.Alpha158` espone 158 feature pre-built:
- 60 rolling-window technical (close/open/high/low ratio, ts max/min/std)
- 20 returns/momentum (ret1, ret5, ret10, ret20, ret60)
- 30 volume/turnover indicators (vchg1, vstd5, vstd20)
- 18 volatility indicators (std5, std10, std20, std30, std60)
- 30 cross-sectional rank features

**Alpha360** estende a 360 feature, principalmente time-series 1/5/10/20/30/60 day per ogni primitive.

### 1.4 alphalens IC tear sheet validation

Pipeline standard di validation per ogni candidate factor:

```python
from alphalens.utils import get_clean_factor_and_forward_returns
from alphalens.tears import create_full_tear_sheet

factor_data = get_clean_factor_and_forward_returns(
    factor=alpha_series,            # MultiIndex (date, asset) → factor value
    prices=close_prices,            # date-indexed close prices
    quantiles=5,                    # quintile portfolios
    periods=(1, 5, 10, 20),         # forward return horizons
    max_loss=0.35,                  # accept up to 35% NaN-drop
)
create_full_tear_sheet(factor_data)
```

**Metrics chiave**:
- **IC mean** (Information Coefficient = Spearman ρ between factor and forward return)
- **IC IR** = IC mean / IC std (target ≥ 0.5 production-grade)
- **Quantile returns spread** (Q5 - Q1, monotonicity check)
- **Turnover annualized** (target < 200% per t-cost viability)
- **Sector neutral IC** (post sector-residualization, robusto a sector tilt)

### 1.5 alphagen — deep RL alpha discovery (W6+ stub)

Pattern alphagen (Yu et al. 2023): RL agent (PPO o A2C) genera espressioni token-by-token, reward = IC IR su validation fold.

```python
# Pseudocode integrazione W6+
from alphagen.models import AlphaGenPolicy
from alphagen.rl_env import AlphaExpressionEnv

env = AlphaExpressionEnv(
    universe='sp500',
    horizon=20,
    primitives=['open','high','low','close','volume','vwap','returns'],
    operators=['rank','ts_argmax','correlation','stddev','+','-','*','/'],
    max_depth=8,
    reward_fn=lambda expr: compute_ic_ir(expr, train_data),
)
agent = AlphaGenPolicy(env)
agent.train(total_timesteps=1_000_000)
top_expressions = agent.sample_top_k(k=20)
```

### 1.6 IC decay analysis

```python
def ic_decay_curve(factor: pd.Series, prices: pd.DataFrame, max_horizon: int = 60) -> pd.Series:
    """Compute IC at horizons 1, 2, ..., max_horizon. Alert if decay > 50% by day 5."""
    decay = {}
    for h in [1, 2, 3, 5, 10, 20, 40, 60]:
        forward_ret = prices.pct_change(h).shift(-h)
        ic = factor.unstack().corrwith(forward_ret, axis=1, method='spearman').mean()
        decay[h] = ic
    return pd.Series(decay)
```

Acceptance criteria production-grade:
- IC[1d] ≥ 0.03
- IC[5d] ≥ 0.5 × IC[1d]
- IC[20d] ≥ 0.2 × IC[1d]
- Turnover annualized < 300%

### 1.7 Multi-collinearity + decay alert

Dopo ogni mining run, calcola pairwise correlation di tutti factor in library:
```python
factor_corr = pd.DataFrame({fid: factor_dict[fid].stack() for fid in factor_ids}).corr()
high_corr_pairs = [(i,j) for i,j in combinations(factor_ids, 2) if abs(factor_corr.loc[i,j]) > 0.8]
```
Alert pair con |corr| > 0.8 → suggerito factor pruning.

### 1.8 Persona visibility

- **ADVISOR** (ws+az): solo proprie alpha mining run + library scoped (filter `userId` su `AlphaMiningRun.requestedBy`)
- **RELATIONSHIP_MANAGER**: idem ADVISOR
- **SUPERVISOR/ADMIN**: cross-tenant + factor library curation + scheduled mining batch control + factor approval workflow
- **CLIENT/PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL**: NEGATO assoluto — alpha output advisor-only, MIFID II compliance

### 1.9 Tier presets (`runner.py:TIER_PRESETS`)

| Tier | LLM mining | Universe | Generations | use case |
|---|---|---|---|---|
| `alpha-base` | Claude Sonnet 4.6 | SP500 | 5 | default ws+az |
| `alpha-extended` | Claude Opus 4.7 | Russell 1000 | 10 | UHNW |
| `alpha-research` | Claude Opus 4.7 + alphagen RL | Custom universe | 20 | SUPERVISOR research-only |

---

## §2 · Pattern di codice

### 2.1 Alpha expression evaluator (`services/alpha-research-py/alpha_evaluator.py`)

```python
from __future__ import annotations
import pandas as pd
import numpy as np
from typing import Callable

# Primitive functions (vectorized, T × N panel)
def ts_max(x: pd.DataFrame, window: int) -> pd.DataFrame:
    return x.rolling(window).max()

def ts_min(x: pd.DataFrame, window: int) -> pd.DataFrame:
    return x.rolling(window).min()

def ts_argmax(x: pd.DataFrame, window: int) -> pd.DataFrame:
    return x.rolling(window).apply(lambda w: w.argmax(), raw=True)

def stddev(x: pd.DataFrame, window: int) -> pd.DataFrame:
    return x.rolling(window).std()

def correlation(x: pd.DataFrame, y: pd.DataFrame, window: int) -> pd.DataFrame:
    return x.rolling(window).corr(y)

def rank(x: pd.DataFrame) -> pd.DataFrame:
    """Cross-sectional rank, normalized [0, 1]."""
    return x.rank(axis=1, pct=True)

def signed_power(x: pd.DataFrame, p: float) -> pd.DataFrame:
    return np.sign(x) * np.abs(x) ** p

def returns(close: pd.DataFrame, period: int = 1) -> pd.DataFrame:
    return close.pct_change(period)

def vwap_proxy(open_: pd.DataFrame, high: pd.DataFrame, low: pd.DataFrame, close: pd.DataFrame) -> pd.DataFrame:
    return (open_ + high + low + close) / 4.0

PRIMITIVES = {
    'ts_max': ts_max, 'ts_min': ts_min, 'ts_argmax': ts_argmax,
    'stddev': stddev, 'correlation': correlation, 'rank': rank,
    'signed_power': signed_power, 'returns': returns,
}
```

### 2.2 WorldQuant Alpha #1 implementation (`services/alpha-research-py/wq101.py`)

```python
def alpha_001(open_, high, low, close, volume) -> pd.DataFrame:
    """rank(Ts_ArgMax(SignedPower((returns < 0 ? stddev(returns, 20) : close), 2), 5)) - 0.5"""
    ret = close.pct_change()
    cond_input = ret.copy()
    cond_input[ret < 0] = stddev(ret, 20)[ret < 0]
    cond_input[ret >= 0] = close[ret >= 0]
    sp = signed_power(cond_input, 2)
    arg_max = ts_argmax(sp, 5)
    return rank(arg_max) - 0.5

def alpha_006(open_, high, low, close, volume) -> pd.DataFrame:
    """-1 * correlation(open, volume, 10)"""
    return -1 * correlation(open_, volume, 10)

def alpha_041(open_, high, low, close, volume) -> pd.DataFrame:
    """((high * low) ^ 0.5) - vwap"""
    vwap = vwap_proxy(open_, high, low, close)
    return ((high * low) ** 0.5) - vwap
```

### 2.3 alphalens IC computation (`services/alpha-research-py/ic_runner.py`)

```python
import alphalens as al

def compute_ic_tear_sheet(
    factor: pd.Series,           # MultiIndex (date, asset)
    prices: pd.DataFrame,        # date × asset close
    quantiles: int = 5,
    periods: tuple = (1, 5, 10, 20),
) -> dict:
    """alphalens full tear sheet metrics."""
    factor_data = al.utils.get_clean_factor_and_forward_returns(
        factor=factor,
        prices=prices,
        quantiles=quantiles,
        periods=periods,
        max_loss=0.35,
    )
    ic = al.performance.factor_information_coefficient(factor_data)
    ic_summary = al.performance.factor_information_coefficient(factor_data).agg(['mean', 'std'])
    quantile_returns, _ = al.performance.mean_return_by_quantile(factor_data)
    turnover = al.performance.factor_rank_autocorrelation(factor_data).mean()

    return {
        'ic_mean': {p: float(ic[p].mean()) for p in perio

…[truncato — apri il file MD per testo completo]