quant research

# valoswiss-quant-research

**Macro-categoria**: 📈 QUANT/MARKETS
**Scope**: Research quantitativa institutional-grade — factor model construction, risk model decomposition, backtest framework, statistical arbitrage, regime detection
**Born**: 2026-05-03 (V20 onboarding insieme alpha-research, target W1-W6 roadmap)
**Owner downstream**: ADVISOR research notebook · SUPERVISOR/ADMIN factor model + risk model 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:8896/healthz | jq .
   ```
   Deve ritornare `{"status":"ok","version":"...","useReal":true|false,"qlibInitialized":true|false}`. Se 502/connection refused → sidecar PM2 down: `pm2 list | grep quant-research-py`.
3. **NestJS proxy health**
   ```bash
   curl -s http://127.0.0.1:4010/api/quant-research/health -H "Cookie: valo_token=<dev-token>"
   ```
   Deve ritornare `{ sidecar:{status:'ok'}, circuitBreaker:{state:'closed', failures:0}, qlib:{provider:'localfs', region:'us'} }`.
4. **Prisma schema sync**
   ```bash
   cd apps/api && npx prisma migrate status
   ```
   Verifica che le 5 model `QuantResearchSession` / `FactorModel` / `RiskModel` / `BacktestRun` / `ResearchNote` + 3 enum `QuantSessionStatus` / `FactorModelType` / `RiskModelMethod` siano applicati.
5. **Tenant configs**: `tenants/ws.json` e `tenants/az.json` devono avere `"quantResearch": true` subito dopo `tradingAgents`.
6. **Persona pack**: `apps/api/src/common/persona-packs/persona-packs.constants.ts` deve avere `'quantResearch'` in `defaultModules` per `ADVISOR` + `RELATIONSHIP_MANAGER` (NON in PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL → MIFID II — research output advisor-only).
7. **Module registry**: `apps/web/src/lib/module-registry.ts` deve esporre entry `quantResearch` con `sidebarSection: 'OPERARE'`, `requiredRole: 'ADVISOR'`, `personaHint: 'predictive'`, icon `📈`.
8. **Qlib data provider**: verifica path local data store
   ```bash
   ls -la ~/.qlib/qlib_data/us_data 2>/dev/null && ls -la ~/.qlib/qlib_data/cn_data 2>/dev/null
   ```
   Se mancante, `python -m qlib.run.get_data qlib_data --target_dir ~/.qlib/qlib_data/us_data --region us` (one-shot ~2GB).
9. **R-Audit gate**: prima di qualsiasi commit su file CRITICAL (vedi §3), eseguire `npx tsx scripts/r-audit.ts <file> --validate-business-logic`.

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 Factor Model Construction (pattern Fama-French 5+ extensions)

**Modello base Fama-French 5-factor**:
- **MKT-RF** (market risk premium)
- **SMB** (size: small minus big)
- **HML** (value: high book-to-market minus low)
- **RMW** (profitability: robust minus weak operating profitability)
- **CMA** (investment: conservative minus aggressive)

**Estensioni proprietarie ValoSwiss**:
- **MOM** (12-1 momentum, Carhart extension)
- **QMJ** (Quality minus Junk, AQR Asness 2019)
- **BAB** (Betting Against Beta, Frazzini-Pedersen)
- **LIQ** (Pastor-Stambaugh liquidity factor)

**Output**: matrice exposure `B[N×K]` (N asset × K factor) + factor returns `F[T×K]` + residual returns `eps[T×N]` con `cov_residual` per risk model.

### 1.2 Risk Model (pattern BARRA + PCA decomposition)

**Approccio 1 — BARRA-style fundamental**:
- 11 industry factor (GICS sector dummies)
- 8 style factor (size, value, momentum, volatility, quality, growth, leverage, liquidity)
- Cov matrix `V = B Σ_F B' + Σ_eps` (Σ_F factor cov, Σ_eps idiosincratic diag o block-diag)

**Approccio 2 — PCA statistical**:
- Eigendecomposition `Σ = U Λ U'`
- Top-K principal components (default K=15, scree plot per cutoff)
- Output `B_pca[N×K]` + `var_explained_ratio[K]`

**Output**: `RiskModel` Prisma row con `B`, `factor_cov`, `idio_var`, `K`, `var_explained_total`, `method` (`BARRA` | `PCA` | `HYBRID`).

### 1.3 Backtest Framework (vectorbt-style + gs-quant integration)

**Pipeline**:
1. **Universe definition** — top-K liquid US/EU equity (filter min ADV > $5M)
2. **Signal ingestion** — da `valoswiss-alpha-research` factor expression valutate
3. **Portfolio construction** — long-short, market-neutral, sector-neutral, vol-targeted
4. **Transaction cost model** — linear (0.05% per side) + impact (sqrt rule)
5. **Rebalance schedule** — daily / weekly / monthly
6. **Walk-forward** — train 24m / oos 6m / step 1m

**Metrics output**:
- Sharpe annualizzato
- Max drawdown + recovery time
- Calmar ratio
- Hit rate + avg win/loss
- Turnover annualizzato
- IC mean + IC IR (per signal-driven strategy)
- Net return after t-cost
- Beta vs MKT, alpha annualizzato

### 1.4 Statistical Arbitrage Signals

**Pattern supportati**:
- **Pairs trading** — cointegration test (Engle-Granger, Johansen) + spread Z-score reversion
- **Index arbitrage** — basket vs futures basis convergence
- **ETF NAV arbitrage** — primary basket vs ETF intraday spread
- **Cross-sectional mean reversion** — N-day return ranking, long bottom decile / short top decile

### 1.5 Regime Detection (HMM + change-point)

**Approccio HMM 2-state**:
- State 0: low-vol bull regime
- State 1: high-vol bear regime
- Observation: daily return + realized vol + VIX level
- Transition matrix learned via Baum-Welch
- Inference Viterbi posterior path

**Approccio change-point Bayesian**:
- BOCPD (Bayesian Online Change Point Detection, Adams-MacKay 2007)
- Run-length posterior + hazard rate
- Trigger model retrain quando hazard > 0.7

### 1.6 Calendar/Event-driven Strategy

**Eventi monitorati**:
- Earnings announcement (PEAD post-earnings drift)
- FOMC meetings (drift days -1/+1)
- ECB meetings + BOJ
- Index rebalance (S&P 500 add/delete)
- Macro release (CPI, NFP)

### 1.7 Persona visibility

- **ADVISOR** (ws+az): solo proprie research session (filter `userId` su `QuantResearchSession.requestedBy`); export factor model verso portfolio-optimization
- **RELATIONSHIP_MANAGER**: idem ADVISOR
- **SUPERVISOR/ADMIN**: cross-tenant + factor model templates + scheduled batch refresh control
- **CLIENT/PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL**: NEGATO assoluto — research output advisor-only, MIFID II compliance, no raccomandazioni dirette al cliente finale

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

| Tier | Universe | Lookback | Backtest engine | use case |
|---|---|---|---|---|
| `quant-base` | Top-500 US | 60m | vectorbt | default ws+az ADVISOR |
| `quant-extended` | Top-1500 US+EU | 120m | vectorbt + gs-quant subset | UHNW + family office |
| `quant-research` | Custom universe up to 3000 | 240m | vectorbt + Qlib + gs-quant | SUPERVISOR research-only |

---

## §2 · Pattern di codice

### 2.1 Fama-French 5-factor regression (Python sidecar `services/quant-research-py/factor_model.py`)

```python
from __future__ import annotations
import numpy as np
import pandas as pd
import statsmodels.api as sm
from typing import Literal

def build_ff5_factor_model(
    returns: pd.DataFrame,           # T × N excess returns
    factor_returns: pd.DataFrame,    # T × 5 [MKT-RF, SMB, HML, RMW, CMA]
    method: Literal['ols', 'wls'] = 'ols',
    weights: pd.Series | None = None,
) -> dict:
    """
    Time-series regression per ogni asset N: r_i,t = a_i + b_i' F_t + e_i,t
    Ritorna B[N×5], alpha[N], R2[N], residual_cov[N×N].
    """
    assert returns.index.equals(factor_returns.index), 'index mismatch'
    n_assets = returns.shape[1]
    B = np.zeros((n_assets, factor_returns.shape[1]))
    alpha = np.zeros(n_assets)
    r2 = np.zeros(n_assets)
    residuals = pd.DataFrame(index=returns.index, columns=returns.columns, dtype=float)

    X = sm.add_constant(factor_returns.values)
    for j, ticker in enumerate(returns.columns):
        y = returns[ticker].values
        if method == 'wls' and weights is not None:
            model = sm.WLS(y, X, weights=weights.values).fit()
        else:
            model = sm.OLS(y, X).fit()
        alpha[j] = model.params[0]
        B[j] = model.params[1:]
        r2[j] = model.rsquared
        residuals.iloc[:, j] = model.resid

    residual_cov = residuals.cov().values
    return {
        'B': B,
        'alpha': alpha,
        'R2': r2,
        'factor_names': list(factor_returns.columns),
        'residual_cov': residual_cov,
        'n_assets': n_assets,
        'n_obs': returns.shape[0],
    }
```

### 2.2 BARRA-style risk model PCA (`services/quant-research-py/risk_model.py`)

```python
import numpy as np
from sklearn.decomposition import PCA

def build_pca_risk_model(
    returns: pd.DataFrame,    # T × N
    n_components: int = 15,
    shrinkage: float = 0.1,   # Ledoit-Wolf-style shrink toward diag
) -> dict:
    """
    Σ = U Λ U' decomposition, top-K loadings retained.
    Idiosyncratic var = diag(Σ - B Σ_F B').
    """
    X = returns.values
    pca = PCA(n_components=n_components)
    F = pca.fit_transform(X - X.mean(axis=0))      # T × K factor returns
    B = pca.components_.T                           # N × K loadings
    factor_cov = np.cov(F.T)                        # K × K diag of eigenvalues

    # Idiosyncratic variance via residual
    reconstructed = (F @ pca.components_) + X.mean(axis=0)
    residuals = X - reconstructed
    idio_var = np.diag(np.cov(residuals.T))

    # Ledoit-Wolf shrinkage toward diag
    sample_cov = np.cov(X.T)
    target = np.diag(np.diag(sample_cov))
    shrunk_cov = (1 - shrinkage) * sample_cov + shrinkage * target

    var_explained_ratio = pca.explained_variance_ratio_
    return {
        'B': B,
        'factor_cov': factor_cov,
        'idio_var': idio_var,
        'var_explained_ratio': var_explained_ratio.tolist(),
        'var_explained_total': float(var_explained_ratio.sum()),
        'method': 'PCA',
        'n_components': n_components,
        'shrinkage': shrinkage,
    }
```

### 2.3 vectorbt backtest pipeline (`services/quant-research-py/backtest_runner.py`)

```python
import vectorbt as vbt
import pandas as pd

def run_backtest(
    signals: pd.DataFrame,        # T × N float [-1, +1] (long-short signal)
    prices: pd.DataFrame,         # T × N close prices
    rebalance: str = 'M',         # pandas freq alias
    cost_per_side: float = 0.0005,
    target_vol: float | None = 0.10,
    max_position: float = 0.05,
) -> dict:
    """vectorbt-based long-short, vol-targeted backtest."""
    weights = signals.div(signals.abs().sum(axis=1), axis=0).fillna(0.0)
    weights = weights.clip(lower=-max_position, upper=max_position)

    if target_vol is not None:
        port_vol = (weights.shift(1) * prices.pct_change()).sum(axis=1).rolling(20).std() * (252 ** 0.5)
        scale = (target_vol / port_vol).clip(upper=2.0).fillna(1.0)
        weights = weights.mul(scale, axis=0)

    pf = vbt.Portfolio.from_orders(
        close=prices,
        size=weights.diff().fillna(weights),
        size_type='targetpercent',
        fees=cost_per_side,
        freq='1D',
    )
    return {
        'sharpe': float(pf.sharpe_ratio()),
        'max_drawdown': float(pf.max_drawdown()),
        'calmar': float(pf.calmar_ratio()),
        'total_return': float(pf.total_return()),
        'turnover_annualized': float(pf.turnover().mean() * 252),
        'win_rate': float(pf.trades.win_rate()) if pf.trades.count() > 0 else 0.0,
        'n_trades': int(pf.trades.count()),
        'beta_market': None,  # populated by post-process vs SPY
    }
```

### 2.4 HMM regime detection (`services/quant-research-py/regime.py`)

```python
import numpy as np
from hmmlearn import hmm

def detect_market_regime(
    daily_returns: pd.Series,
    realized_vol: pd.Series,
    vix: pd.Series | None = None,
    n_states: int = 2,
) -> dict:
    

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