portfolio optimization

# valoswiss-portfolio-optimization (31°)

**Macro-categoria**: 💼 WEALTH/PORTFOLIO (sub-categoria QUANT-INTELLIGENCE bridge)
**Scope**: Portfolio construction & optimization advisor-side — pesi target, efficient frontier, risk decomposition, what-if scenario, IPS-aware constraint engine
**Born**: 2026-05-03 V20 (sidecar planning + monorepo skeleton in commit window)
**Owner downstream**: ADVISOR (allocation proposals proprie portfolios) · RELATIONSHIP_MANAGER (idem) · SUPERVISOR/ADMIN (cross-tenant + tier override + factor model upload)
**Last aligned**: 2026-05-03 V20

> **PROTOTYPE-PHASE caveat**: questo agente opera in fase prototipo. La normativa applicabile (MIFID II, suitability, IPS adherence, ex-ante stress test obbligatori art. 50 CdR) è trattata come **signal target post-prototipo**, NON come hard gate bloccante. La R-Audit gate è MAJOR (peso 8) — segnalazione obbligatoria su ogni file CRITICAL, ma capability over compliance: si può mergere con remarks se la business logic regge. Compliance hardening è esplicito milestone V21+ (vedi §9 roadmap).

---

## §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 optimization health**
   ```bash
   curl -s http://127.0.0.1:8892/healthz | jq .
   ```
   Deve ritornare `{"status":"ok","version":"...","engines":{"pypfopt":"1.5.x","riskfolio":"7.2.1","cvxportfolio":"1.6.x"}}`. Se 502/connection refused → sidecar PM2 down: `pm2 list | grep portfolio-opt-py`.
3. **Sidecar parallel trading-agents (per overlay alpha)**
   ```bash
   curl -s http://127.0.0.1:8890/healthz | jq .
   ```
   Non bloccante — se down, l'agente lavora ugualmente ma senza signal overlay (fallback prior-only).
4. **NestJS proxy health (futuro modulo)**
   ```bash
   curl -s http://127.0.0.1:4010/api/portfolio-opt/health -H "Cookie: valo_token=<dev-token>"
   ```
   Deve ritornare `{ sidecar:{status:'ok'}, circuitBreaker:{state:'closed'} }`. In V20 questo endpoint potrebbe non esistere ancora — annotare nel handoff.
5. **Prisma schema sync**
   ```bash
   cd apps/api && npx prisma migrate status
   ```
   Verifica che le model `OptimizationRun` / `OptimizationConstraintProfile` / `OptimizationFactorModel` siano applicate (post-W3).
6. **Tenant configs**: `tenants/ws.json` e `tenants/az.json` devono avere `"portfolioOptimization": true` subito dopo `tradingAgents` (3-Point Registration V16).
7. **Persona pack**: `apps/api/src/common/persona-packs/persona-packs.constants.ts` deve avere `'portfolioOptimization'` in `defaultModules` per `ADVISOR` + `RELATIONSHIP_MANAGER`. **NON** in CLIENT-facing packs (PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL) — l'advisor è il proponente, il cliente firma l'IPS, NON sceglie weights direttamente.
8. **Module registry**: `apps/web/src/lib/module-registry.ts` deve esporre entry `portfolioOptimization` con `sidebarSection: 'OPERARE'`, `requiredRole: 'ADVISOR'`, `personaHint: 'allocator'`, icon `💼`.
9. **R-Audit gate (MAJOR, peso 8)**: prima di qualsiasi commit su file CRITICAL (vedi §3 R-Audit gates), eseguire `npx tsx scripts/r-audit.ts <file> --validate-business-logic --weight major`. In prototype-phase il verdict NEEDS-CHANGES è merge-able con remarks documentati nel commit body, MA mai con CRITICAL findings business-logic.

Se uno qualunque dei 8 punti operativi (1-8) 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 Optimization engines supportati

| Engine | Repo riferimento | Use case primario | Modello matematico |
|---|---|---|---|
| **Markowitz mean-variance** | PyPortfolioOpt 7.x `EfficientFrontier` | baseline classic, IPS-band constrained | min wᵀΣw s.t. wᵀμ ≥ R, Σw=1, l ≤ w ≤ u |
| **Black-Litterman** | PyPortfolioOpt `BlackLittermanModel` | views advisor + equilibrium fusion | μ_BL = ((τΣ)⁻¹ + PᵀΩ⁻¹P)⁻¹((τΣ)⁻¹Π + PᵀΩ⁻¹Q) |
| **HRP** Hierarchical Risk Parity | PyPortfolioOpt `HRPOpt` | robusto a outlier covariance, no inversione Σ | clustering linkage single/ward + recursive bisection |
| **CLA** Critical Line Algorithm | PyPortfolioOpt `CLA` | turning points dell'efficient frontier completa | Markowitz LCP turning point enumeration |
| **Risk Parity** (CVaR/EVaR/MDD) | Riskfolio-Lib 7.2.1 `RiskParityPortfolio` | equal risk contribution multi-measure | minimize variance(RC_i) s.t. RC_i = w_i ∂R/∂w_i |
| **Kelly fractional** | Riskfolio-Lib `Kelly` + half-haircut | growth-optimal con safety haircut | f* = (μ-r)/σ² · haircut (default 0.5) |
| **Multi-period convex** | cvxgrp/cvxportfolio (Stanford, Boyd lab) | dynamic rebalancing T-period | min Σ_t (cost_t + risk_t) CVXPY |
| **skfolio cross-validated** | skfolio `CombinatorialPurgedCV` | OOS robust weights, anti-overfit | sklearn-style CV pipeline |

### 1.2 Risk measures supportati (Riskfolio-Lib + custom)

- **Variance** (Markowitz baseline)
- **CVaR** Conditional Value-at-Risk α=0.05 (Rockafellar-Uryasev)
- **MAD** Mean Absolute Deviation
- **MDD** Maximum Drawdown
- **Sortino** downside semi-deviation
- **Omega ratio** threshold-based gain/loss probability
- **EVaR** Entropic Value-at-Risk (coherent + tractable)
- **RLVaR** Relativistic Value-at-Risk (Riskfolio 7.0+)
- **ULCER index** depth-duration drawdown composite

### 1.3 Constraint engine multi-tipo

```yaml
ConstraintProfile:
  bands:                              # IPS hard bands (overrides any optimizer)
    equity_min: 0.45                  # 45% minimum equity
    equity_max: 0.75                  # 75% maximum equity
    fixed_income_min: 0.20
    cash_max: 0.10
  sector_caps:                        # max % per GICS sector
    Technology: 0.30
    Energy: 0.15
    Healthcare: 0.25
  esg_min_score: 7.0                  # MSCI ESG average minimum
  esg_exclusions:                     # hard exclusions
    - tobacco
    - coal_thermal
    - controversial_weapons
  concentration:
    max_single_name: 0.08             # 8% singolo titolo max (UHNW può salire a 0.15)
    max_top10: 0.50
  turnover:
    annual_max: 0.40                  # 40% turnover/anno (after-tax friendly)
    one_way_cost_bps: 15              # 15bps round-trip
  tax_lots:                           # passa al valoswiss-tax-fees
    enable_tlh: true
    short_term_penalty_bps: 100       # IT 26% short-term tax drag
    wash_sale_window_days: 30
  factor_tilts:                       # opzionale, da quant-research
    value_target: 0.20                # +20bps tilt verso value
    momentum_target: 0.15
    quality_min: 0.0                  # neutral minimo
```

### 1.4 Output strutturato Pydantic v2

```python
{
  "runId": "uuid",
  "tenantSlug": "ws",
  "portfolioId": "uuid",
  "engine": "markowitz",         # markowitz|black-litterman|hrp|risk-parity|kelly|multi-period|skfolio
  "riskMeasure": "variance",     # variance|cvar|mad|mdd|sortino|omega|evar|rlvar|ulcer
  "asOfDate": "2026-05-03",
  "objective": "max_sharpe",     # max_sharpe|min_variance|target_return|target_risk|max_quadratic_utility|min_cvar
  "weights": {                   # target weights (sum to 1.0)
    "AAPL": 0.072, "MSFT": 0.054, "AGG.US": 0.18, ...
  },
  "metrics": {
    "expectedReturn": 0.087,     # annualized
    "expectedVol": 0.142,
    "sharpe": 0.612,
    "sortino": 0.84,
    "cvar95": -0.058,
    "maxDrawdown": -0.18,
    "kellyFraction": 0.43,
    "turnover": 0.27,            # vs current weights
    "afterTaxAlpha": 0.012       # post-TLH bps
  },
  "efficientFrontier": [         # 30 points
    { "vol": 0.08, "ret": 0.04, "sharpe": 0.25, "weights": {...} }, ...
  ],
  "riskDecomposition": {         # marginal contribution to risk
    "AAPL": 0.084, "MSFT": 0.062, ... // sum to 1.0
  },
  "constraintBindings": [        # quali constraint sono attive (binding)
    "sector_cap.Technology@0.30",
    "esg_min_score@7.0"
  ],
  "rationale": "Max-Sharpe constrained by IPS bands + sector cap Tech 30%. ESG 7.0 binding excluded XOM/CVX. After-tax overlay TLH +12bps annualized.",
  "warnings": [                  # PROTOTYPE-PHASE — non bloccanti
    "covariance window 252d may underestimate tail-risk; consider Ledoit-Wolf shrinkage",
    "no MIFID II ex-ante stress published yet (V21+ milestone)"
  ]
}
```

### 1.5 Persona visibility (MIFID II posture prototype-phase)

- **ADVISOR** (ws+az): vede SOLO portfolios proprie (filter `userId` su `OptimizationRun.requestedBy`)
- **RELATIONSHIP_MANAGER**: idem ADVISOR
- **SUPERVISOR/ADMIN**: cross-tenant + factor model upload + tier override
- **CLIENT/PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL**: NEGATO assoluto — il cliente firma l'IPS, l'advisor è il responsabile della costruzione weights. Nessuna view direct-to-client per ora (post-prototype: client può vedere read-only target weights firmati nel reporting periodico, NON il what-if scenario panel).

### 1.6 Tier presets

| Tier | Engines abilitati | CVXPY solver | use case |
|---|---|---|---|
| `opt-standard` | Markowitz, BL, HRP, Risk-Parity (variance/CVaR) | ECOS | default ws+az ADVISOR |
| `opt-uhnw` | tutti + Kelly, Multi-period, skfolio CV | MOSEK (commercial) o SCS fallback | UHNW + family office, factor tilts custom |

Override env (priorità: env > tier preset):
- `PORTFOLIO_OPT_DEFAULT_ENGINE` (default `markowitz`)
- `PORTFOLIO_OPT_CVXPY_SOLVER` (default `ECOS`)
- `PORTFOLIO_OPT_LEDOIT_WOLF_SHRINKAGE` (default `true` — covariance hardening)

---

## §2 · Pattern di codice (esempi realistici)

### 2.1 Markowitz mean-variance con vincoli IPS (PyPortfolioOpt)

```python
# services/portfolio-optimization-py/engines/markowitz.py
from __future__ import annotations
from pypfopt import EfficientFrontier, risk_models, expected_returns
from pypfopt.objective_functions import L2_reg
from .contracts import OptimizationRequest, OptimizationOutput, ConstraintProfile

def run_markowitz(req: OptimizationRequest) -> OptimizationOutput:
    """
    Markowitz mean-variance con vincoli IPS:
    - bands min/max per asset class (equity/fi/cash)
    - sector caps GICS
    - max single-name + top10
    - L2 regularization per evitare corner solutions
    """
    # 1. Expected returns: shrunk historical (Ledoit-Wolf) o BL prior
    mu = expected_returns.mean_historical_return(
        req.price_history,
        frequency=252,
        compounding=True,
    )
    # 2. Covariance: Ledoit-Wolf shrinkage (anti-overfit small N)
    S = risk_models.CovarianceShrinkage(req.price_history).ledoit_wolf()

    # 3. Init optimizer con weight bounds (single-name cap)
    constraints = req.constraints
    n = len(mu)
    upper = constraints.concentration.max_single_name
    ef = EfficientFrontier(mu, S, weight_bounds=(0.0, upper), solver="ECOS")

    # 4. Sector constraints — sector_mapper {ticker: sector}
    sector_mapper = req.sector_mapper
    sector_lower = {s: 0.0 for s in constraints.sector_caps}
    sector_upper = constraints.sector_caps  # e.g., {"Technology": 0.30}
    ef.add_sector_constraints(sector_mapper, sector_lower, sector_upper)

    # 5. IPS bands per asset class — encode tramite ticker→class mapping + sector_constraints stile
    asset_class_mapper = req.asset_class_mapper  # {ticker: 'equity'|'fixed_income'|'cash'}
    asset_class_lower = {
        "equity": constraints.bands.equity_min,
        "fixed_income": constraints.bands.fixed_income_min,
        "cash": 0.0,
    }
    asset_class_upper = {
        "equity": constraints.bands.equity_max,
        "fixed_income": 1.0,
        "cash": constraints.bands.cash_max,
    }
    ef.add_sector_constraints(asset_class_mapper, asset_class_lower, asset_class_upper)

    # 6. ESG exclusions: hard-zero weight per excluded tickers
    excluded = [t for t in mu.index if t in req.esg_exclusions_ticker_set]
    for t in excluded:
        

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