Portfolio Analysis Engine

Descrizione del Progetto

Motore di analisi quantitativa per portafogli di investimento sviluppato in Python. Il sistema scarica dati storici da Yahoo Finance, calcola oltre 40 metriche finanziarie (Sharpe, Sortino, Calmar, VaR, CVaR, CAGR, risk contribution, ecc.) e valida la coerenza strutturale del portafoglio tramite un sistema di gate decisionali a tre stadi.

Il progetto nasce per rispondere a due domande fondamentali su un portafoglio di ETF/fondi: il portafoglio è strutturalmente solido? (diversificazione, contribuzione al rischio, qualità dei dati) e il comportamento del portafoglio è coerente con l'intento di rischio dichiarato? (allineamento beta, aspettative di drawdown). Non è un tool di trading o di raccomandazione: è uno strumento di diagnostica e backtesting per analisi ripetibili e di qualità istituzionale.

Architettura

Il progetto segue un'architettura a layer con flusso dati unidirezionale, organizzata in 8 moduli principali:

• core/ — Orchestrazione della pipeline di analisi (data loading → metriche → gate → output)
• analytics/ — Layer di calcolo puro: metriche di performance, rischio, contribuzione al rischio, ottimizzazione Markowitz con frontiera efficiente e Monte Carlo (distribuzione t-Student)
• decision/ — Sistema di gate a 3 stadi (Data Integrity → Risk Intent → Benchmark) con pattern "Risk Intent as Contract" che valida il beta del portafoglio rispetto all'intento dichiarato
• data/ — Download e validazione dati con policy STAGGERED_ENTRY per gestire asset con date di inizio diverse
• reporting/ — Generazione report in modalità RETAIL o PROFESSIONAL con export multi-formato (PDF, Excel, CSV, JSON, HTML)
• models/ — Dataclass immutabili (frozen=True) condivise tra tutti i layer
• config/ — Configurazione con soglie documentate e preset portafoglio
• utils/ — Eccezioni, logging, helper

Funzionalità Principali

• 40+ metriche finanziarie: CAGR, Sharpe, Sortino, Calmar, Max Drawdown, VaR/CVaR 95%, risk contribution (MCR, CCR), correlazioni con shrinkage Ledoit-Wolf
• Gate System: validazione automatica della qualità dei dati, coerenza tra rischio dichiarato e rischio effettivo, confronto con benchmark — con meccanismo di override auditabile
• Ottimizzazione di portafoglio: frontiera efficiente Markowitz (150 portafogli ottimali), portafogli chiave (Min Variance, Max Sharpe, Risk Parity), stress test Monte Carlo con 10.000 simulazioni
• Dual-Correlation Framework: matrice RAW per diagnostica e matrice REG (regularizzata) per i calcoli, per evitare instabilità da correlazioni campionarie
• Market Regime Detection: identificazione automatica dei regimi di mercato e delle crisi sistemiche (2008, 2020, ecc.)
• Report istituzionali: output strutturato in ZIP con timestamp, esportabile in 6 formati diversi