Create app.py

app.py

@@ -0,0 +1,1330 @@
+"""
+PORTFOLIO INTELLIGENCE ENGINE
+Institutional-grade multi-asset portfolio construction system
+
+Extends single-asset AI forecasting to portfolio-level optimization with:
+- Risk-aware optimization
+- Regime-adaptive allocation
+- Stress testing
+- Explainable narratives
+
+Author: Portfolio Intelligence Team
+Version: 2.0
+Date: 2026-02-07
+"""
+
+import numpy as np
+import pandas as pd
+from datetime import datetime, timedelta
+from typing import List, Dict, Tuple, Optional, Union
+from dataclasses import dataclass, field
+from scipy.optimize import minimize
+from scipy import stats
+import warnings
+warnings.filterwarnings('ignore')
+
+# ============================================================================
+# LAYER 1: INPUT & CONSTRAINTS
+# ============================================================================
+
+@dataclass
+class PortfolioConstraints:
+    """Portfolio construction constraints and parameters"""
+    
+    # Asset Universe
+    assets: List[str] = field(default_factory=list)
+    asset_types: Dict[str, str] = field(default_factory=dict)
+    
+    # Weight Constraints
+    min_weight: Dict[str, float] = field(default_factory=dict)
+    max_weight: Dict[str, float] = field(default_factory=dict)
+    sector_caps: Dict[str, float] = field(default_factory=dict)
+    
+    # Cash & Liquidity
+    cash_allowance: Tuple[float, float] = (0.0, 0.30)
+    min_liquidity_threshold: float = 1e6
+    
+    # Rebalancing Rules
+    rebalance_frequency: str = 'weekly'
+    rebalance_threshold: float = 0.05
+    transaction_cost: float = 0.001
+    
+    # Risk Profile
+    risk_profile: str = 'balanced'
+    max_portfolio_volatility: Optional[float] = None
+    target_sharpe: Optional[float] = None
+    
+    # Advanced Constraints
+    leverage_allowed: bool = False
+    short_selling_allowed: bool = False
+    concentration_limit: float = 0.35
+    
+    def validate(self) -> 'ValidationResult':
+        """Validate constraint feasibility"""
+        errors = []
+        warnings_list = []
+        
+        # Check sum of min weights
+        if self.min_weight:
+            min_sum = sum(self.min_weight.values())
+            if min_sum > 1.0:
+                errors.append(f"Sum of min_weights ({min_sum:.2%}) exceeds 100%")
+        
+        # Check min < max for each asset
+        for asset in self.assets:
+            min_w = self.min_weight.get(asset, 0.0)
+            max_w = self.max_weight.get(asset, 1.0)
+            if min_w >= max_w:
+                errors.append(f"{asset}: min_weight ({min_w}) >= max_weight ({max_w})")
+        
+        # Check risk profile validity
+        if self.risk_profile not in ['conservative', 'balanced', 'aggressive']:
+            errors.append(f"Invalid risk_profile: {self.risk_profile}")
+        
+        # Check concentration limit
+        if self.concentration_limit < 0 or self.concentration_limit > 1:
+            errors.append(f"concentration_limit must be in [0, 1], got {self.concentration_limit}")
+        
+        # Warnings for common issues
+        if not self.sector_caps:
+            warnings_list.append("No sector caps specified - portfolio may be over-concentrated")
+        
+        if self.transaction_cost == 0:
+            warnings_list.append("transaction_cost = 0 may lead to excessive rebalancing")
+        
+        return ValidationResult(
+            is_valid=len(errors) == 0,
+            errors=errors,
+            warnings=warnings_list
+        )
+
+@dataclass
+class ValidationResult:
+    """Result of constraint validation"""
+    is_valid: bool
+    errors: List[str]
+    warnings: List[str]
+
+# Risk profile templates
+RISK_PROFILES = {
+    'conservative': {
+        'max_volatility': 0.10,
+        'max_drawdown': 0.15,
+        'min_sharpe': 0.8,
+        'cash_range': (0.10, 0.40),
+        'max_beta': 0.7,
+        'regime_sensitivity': 'high'
+    },
+    'balanced': {
+        'max_volatility': 0.15,
+        'max_drawdown': 0.25,
+        'min_sharpe': 0.6,
+        'cash_range': (0.05, 0.20),
+        'max_beta': 1.0,
+        'regime_sensitivity': 'medium'
+    },
+    'aggressive': {
+        'max_volatility': 0.25,
+        'max_drawdown': 0.40,
+        'min_sharpe': 0.4,
+        'cash_range': (0.00, 0.10),
+        'max_beta': 1.5,
+        'regime_sensitivity': 'low'
+    }
+}
+
+
+# ============================================================================
+# LAYER 2: DATA & FEATURE
+# ============================================================================
+
+@dataclass
+class AssetFeatures:
+    """Comprehensive features for a single asset"""
+    
+    symbol: str
+    
+    # Historical Data
+    historical_returns: pd.Series = None
+    historical_prices: pd.Series = None
+    historical_volume: pd.Series = None
+    
+    # Technical Indicators
+    sma_20: float = 0.0
+    sma_50: float = 0.0
+    sma_200: float = 0.0
+    rsi: float = 50.0
+    macd: float = 0.0
+    macd_signal: float = 0.0
+    
+    # Forward-Looking AI Forecast
+    expected_return: float = 0.0
+    expected_return_confidence: float = 0.5
+    forecast_horizon: int = 30
+    return_distribution: np.ndarray = None
+    
+    # Volatility Metrics
+    realized_volatility: float = 0.15
+    predicted_volatility: float = 0.15
+    volatility_regime: str = 'medium'
+    
+    # Market Regime
+    current_regime: str = 'sideways'
+    regime_probability: float = 0.5
+    regime_transition_risk: float = 0.3
+    
+    # Risk Metrics
+    beta: float = 1.0
+    correlation_to_market: float = 0.5
+    downside_deviation: float = 0.10
+    max_drawdown: float = -0.20
+    
+    # Liquidity & Fundamental
+    avg_daily_volume: float = 1e6
+    market_cap: Optional[float] = None
+    sector: Optional[str] = None
+    
+    # Metadata
+    last_update: datetime = field(default_factory=datetime.now)
+    data_quality_score: float = 1.0
+
+
+class DataFeatureLayer:
+    """Layer 2: Extract and compute asset features"""
+    
+    def compute_asset_features(
+        self,
+        symbol: str,
+        historical_data: pd.DataFrame,
+        forecast_result: Dict,
+        regime_result: Dict
+    ) -> AssetFeatures:
+        """Transform raw data into structured features"""
+        
+        features = AssetFeatures(symbol=symbol)
+        
+        # Historical statistics
+        if 'Close' in historical_data.columns:
+            features.historical_prices = historical_data['Close']
+            features.historical_returns = np.log(
+                historical_data['Close'] / historical_data['Close'].shift(1)
+            ).dropna()
+            
+            # Calculate realized volatility
+            features.realized_volatility = features.historical_returns.std() * np.sqrt(252)
+        
+        if 'Volume' in historical_data.columns:
+            features.historical_volume = historical_data['Volume']
+            features.avg_daily_volume = historical_data['Volume'].tail(20).mean()
+        
+        # Extract AI forecast
+        if forecast_result:
+            exp_ret, confidence = self._extract_expected_return(forecast_result)
+            features.expected_return = exp_ret
+            features.expected_return_confidence = confidence
+            
+            if 'probabilistic_samples' in forecast_result:
+                features.return_distribution = forecast_result['probabilistic_samples']
+        
+        # Regime information
+        if regime_result:
+            features.current_regime = regime_result.get('regime', 'sideways')
+            features.regime_probability = regime_result.get('confidence', 0.5)
+        
+        # Compute forward volatility
+        features.predicted_volatility = self._compute_forward_volatility(
+            features.realized_volatility,
+            None,  # GARCH forecast (placeholder)
+            features.current_regime
+        )
+        
+        # Compute beta (vs market)
+        if len(features.historical_returns) > 60:
+            # Simple market proxy (would normally fetch SPY)
+            features.beta = 1.0  # Placeholder
+        
+        features.last_update = datetime.now()
+        
+        return features
+    
+    def _extract_expected_return(self, forecast_result: Dict) -> Tuple[float, float]:
+        """Convert probabilistic forecast to expected return + confidence"""
+        
+        if 'probabilistic_samples' in forecast_result:
+            samples = forecast_result['probabilistic_samples']
+            median_return = np.median(samples)
+            p10 = np.percentile(samples, 10)
+            p90 = np.percentile(samples, 90)
+            
+            # Confidence based on uncertainty
+            uncertainty = (p90 - p10) / abs(median_return) if median_return != 0 else 10.0
+            confidence = 1.0 / (1.0 + uncertainty)
+            confidence = np.clip(confidence, 0.0, 1.0)
+            
+            # Annualize (assuming 30-day forecast)
+            annualized_return = median_return * (252 / 30)
+            
+            return annualized_return, confidence
+        
+        return 0.0, 0.5
+    
+    def _compute_forward_volatility(
+        self,
+        historical_vol: float,
+        garch_forecast: Optional[float],
+        regime: str
+    ) -> float:
+        """Blend historical, GARCH, and regime-adjusted volatility"""
+        
+        # Regime multipliers
+        regime_multipliers = {
+            'bull': 0.85,
+            'sideways': 1.0,
+            'bear': 1.3
+        }
+        
+        multiplier = regime_multipliers.get(regime, 1.0)
+        
+        if garch_forecast:
+            # Weighted blend
+            vol = 0.4 * historical_vol + 0.4 * garch_forecast + 0.2 * historical_vol * multiplier
+        else:
+            # Simple regime adjustment
+            vol = historical_vol * multiplier
+        
+        return vol
+
+
+# ============================================================================
+# LAYER 3: CORRELATION & DEPENDENCY
+# ============================================================================
+
+class CovarianceEstimator:
+    """Layer 3: Model asset interdependencies"""
+    
+    def rolling_covariance(
+        self,
+        returns: pd.DataFrame,
+        window: int = 60
+    ) -> np.ndarray:
+        """Exponentially weighted rolling covariance"""
+        
+        # Use exponential weighting
+        cov_matrix = returns.ewm(span=window).cov()
+        
+        # Extract the most recent covariance matrix
+        n_assets = len(returns.columns)
+        latest_cov = cov_matrix.iloc[-n_assets:, :].values
+        
+        return self._ensure_positive_definite(latest_cov)
+    
+    def regime_conditional_covariance(
+        self,
+        returns: pd.DataFrame,
+        regimes: pd.Series
+    ) -> Dict[str, np.ndarray]:
+        """Compute separate covariance matrices per regime"""
+        
+        regime_covs = {}
+        
+        for regime in regimes.unique():
+            regime_mask = (regimes == regime)
+            regime_returns = returns[regime_mask]
+            
+            if len(regime_returns) > 20:  # Minimum sample size
+                cov = regime_returns.cov().values
+                regime_covs[regime] = self._ensure_positive_definite(cov)
+        
+        return regime_covs
+    
+    def stress_covariance(
+        self,
+        base_cov: np.ndarray,
+        stress_scenario: str
+    ) -> np.ndarray:
+        """Adjust covariance for stress scenarios"""
+        
+        n = base_cov.shape[0]
+        
+        if stress_scenario == 'market_crash':
+            # All correlations → 0.8
+            corr_matrix = np.full((n, n), 0.8)
+            np.fill_diagonal(corr_matrix, 1.0)
+            
+            # Extract standard deviations
+            std_devs = np.sqrt(np.diag(base_cov))
+            
+            # Reconstruct covariance
+            stressed_cov = np.outer(std_devs, std_devs) * corr_matrix
+            
+        elif stress_scenario == 'volatility_spike':
+            # Scale all variances by 2x
+            stressed_cov = base_cov * 2.0
+            
+        else:
+            stressed_cov = base_cov
+        
+        return self._ensure_positive_definite(stressed_cov)
+    
+    def _ensure_positive_definite(self, cov_matrix: np.ndarray) -> np.ndarray:
+        """Ensure covariance matrix is positive definite"""
+        
+        # Eigenvalue decomposition
+        eigvals, eigvecs = np.linalg.eigh(cov_matrix)
+        
+        # Replace negative eigenvalues
+        eigvals[eigvals < 1e-8] = 1e-8
+        
+        # Reconstruct matrix
+        return eigvecs @ np.diag(eigvals) @ eigvecs.T
+
+
+def calculate_diversification_ratio(
+    weights: np.ndarray,
+    volatilities: np.ndarray,
+    cov_matrix: np.ndarray
+) -> float:
+    """
+    Diversification Ratio = (Weighted Avg Vol) / (Portfolio Vol)
+    Higher ratio = better diversification
+    """
+    weighted_vol = np.sum(weights * volatilities)
+    portfolio_vol = np.sqrt(weights @ cov_matrix @ weights)
+    
+    if portfolio_vol > 0:
+        return weighted_vol / portfolio_vol
+    return 1.0
+
+
+# ============================================================================
+# LAYER 4: FORECAST AGGREGATION
+# ============================================================================
+
+@dataclass
+class OptimizationInputs:
+    """Aggregated inputs for portfolio optimization"""
+    expected_returns: np.ndarray
+    cov_matrix: np.ndarray
+    confidence_weights: np.ndarray
+    symbols: List[str]
+
+
+class ForecastAggregator:
+    """Layer 4: Transform individual forecasts into portfolio inputs"""
+    
+    def aggregate_to_optimization_inputs(
+        self,
+        asset_features: List[AssetFeatures],
+        current_regime: str
+    ) -> OptimizationInputs:
+        """Convert asset-level forecasts into portfolio vectors"""
+        
+        n_assets = len(asset_features)
+        
+        # Extract expected returns
+        raw_returns = np.array([f.expected_return for f in asset_features])
+        confidences = np.array([f.expected_return_confidence for f in asset_features])
+        volatilities = np.array([f.predicted_volatility for f in asset_features])
+        
+        # Confidence-adjusted returns
+        adjusted_returns = self._confidence_adjusted_returns(
+            raw_returns, confidences, risk_aversion=2.5
+        )
+        
+        # Apply regime tilts
+        regime_adjusted_returns = self._apply_regime_tilts(
+            adjusted_returns, volatilities, current_regime
+        )
+        
+        # Build covariance matrix
+        returns_df = pd.DataFrame({
+            f.symbol: f.historical_returns 
+            for f in asset_features if f.historical_returns is not None
+        })
+        
+        cov_estimator = CovarianceEstimator()
+        cov_matrix = cov_estimator.rolling_covariance(returns_df)
+        
+        # Symbols
+        symbols = [f.symbol for f in asset_features]
+        
+        return OptimizationInputs(
+            expected_returns=regime_adjusted_returns,
+            cov_matrix=cov_matrix,
+            confidence_weights=confidences,
+            symbols=symbols
+        )
+    
+    def _confidence_adjusted_returns(
+        self,
+        raw_returns: np.ndarray,
+        confidences: np.ndarray,
+        risk_aversion: float = 2.5
+    ) -> np.ndarray:
+        """Adjust returns based on forecast confidence"""
+        
+        rf = 0.04  # Risk-free rate
+        
+        # Shrink toward risk-free rate based on confidence
+        adjusted = confidences * raw_returns + (1 - confidences) * rf
+        
+        return adjusted
+    
+    def _apply_regime_tilts(
+        self,
+        returns: np.ndarray,
+        volatilities: np.ndarray,
+        regime: str
+    ) -> np.ndarray:
+        """Apply regime-based adjustments"""
+        
+        regime_tilts = {
+            'bull': {'multiplier': 1.2, 'vol_penalty': 0.8},
+            'bear': {'multiplier': 0.7, 'vol_penalty': 1.5},
+            'sideways': {'multiplier': 1.0, 'vol_penalty': 1.0}
+        }
+        
+        tilt = regime_tilts.get(regime, {'multiplier': 1.0, 'vol_penalty': 1.0})
+        
+        # Adjust returns and penalize volatility
+        adjusted_returns = returns * tilt['multiplier']
+        adjusted_returns -= volatilities * tilt['vol_penalty'] * 0.1
+        
+        return adjusted_returns
+
+
+# ============================================================================
+# LAYER 5: OPTIMIZATION ENGINE
+# ============================================================================
+
+class OptimizationEngine:
+    """Layer 5: Solve for optimal portfolio weights"""
+    
+    def minimize_variance(
+        self,
+        cov_matrix: np.ndarray,
+        constraints: PortfolioConstraints
+    ) -> np.ndarray:
+        """Minimum variance portfolio"""
+        
+        n = cov_matrix.shape[0]
+        
+        def objective(w):
+            return w @ cov_matrix @ w
+        
+        # Bounds
+        bounds = []
+        for i, symbol in enumerate(constraints.assets[:n]):
+            min_w = constraints.min_weight.get(symbol, 0.0)
+            max_w = constraints.max_weight.get(symbol, 1.0)
+            bounds.append((min_w, max_w))
+        
+        # Constraints
+        constraints_list = [
+            {'type': 'eq', 'fun': lambda w: np.sum(w) - 1.0}
+        ]
+        
+        # Initial guess: equal weights
+        x0 = np.ones(n) / n
+        
+        result = minimize(
+            objective,
+            x0=x0,
+            method='SLSQP',
+            bounds=bounds,
+            constraints=constraints_list
+        )
+        
+        return result.x if result.success else x0
+    
+    def maximize_sharpe(
+        self,
+        returns: np.ndarray,
+        cov_matrix: np.ndarray,
+        risk_free_rate: float,
+        constraints: PortfolioConstraints
+    ) -> np.ndarray:
+        """Maximum Sharpe ratio portfolio"""
+        
+        n = len(returns)
+        
+        def negative_sharpe(w):
+            portfolio_return = returns @ w
+            portfolio_vol = np.sqrt(w @ cov_matrix @ w)
+            
+            if portfolio_vol == 0:
+                return 1e10
+            
+            return -(portfolio_return - risk_free_rate) / portfolio_vol
+        
+        # Bounds
+        bounds = []
+        for i, symbol in enumerate(constraints.assets[:n]):
+            min_w = constraints.min_weight.get(symbol, 0.0)
+            max_w = constraints.max_weight.get(symbol, 1.0)
+            bounds.append((min_w, max_w))
+        
+        # Constraints
+        constraints_list = [
+            {'type': 'eq', 'fun': lambda w: np.sum(w) - 1.0}
+        ]
+        
+        x0 = np.ones(n) / n
+        
+        result = minimize(
+            negative_sharpe,
+            x0=x0,
+            method='SLSQP',
+            bounds=bounds,
+            constraints=constraints_list
+        )
+        
+        return result.x if result.success else x0
+    
+    def risk_parity_allocation(
+        self,
+        cov_matrix: np.ndarray,
+        constraints: PortfolioConstraints
+    ) -> np.ndarray:
+        """Risk parity: equal risk contribution from each asset"""
+        
+        n = cov_matrix.shape[0]
+        
+        def risk_contribution_objective(w):
+            portfolio_var = w @ cov_matrix @ w
+            
+            if portfolio_var == 0:
+                return 1e10
+            
+            marginal_contrib = cov_matrix @ w
+            risk_contrib = w * marginal_contrib / portfolio_var
+            target_rc = 1.0 / n
+            
+            return np.sum((risk_contrib - target_rc) ** 2)
+        
+        # Bounds
+        bounds = [(0.01, 1.0) for _ in range(n)]
+        
+        # Constraints
+        constraints_list = [
+            {'type': 'eq', 'fun': lambda w: np.sum(w) - 1.0}
+        ]
+        
+        x0 = np.ones(n) / n
+        
+        result = minimize(
+            risk_contribution_objective,
+            x0=x0,
+            method='SLSQP',
+            bounds=bounds,
+            constraints=constraints_list
+        )
+        
+        return result.x if result.success else x0
+    
+    def ai_weighted_allocation(
+        self,
+        returns: np.ndarray,
+        cov_matrix: np.ndarray,
+        confidences: np.ndarray,
+        regime_scores: np.ndarray,
+        constraints: PortfolioConstraints
+    ) -> np.ndarray:
+        """
+        AI-weighted: Blend forecast confidence, regime suitability, Sharpe
+        This is the proprietary "secret sauce" mode
+        """
+        
+        n = len(returns)
+        
+        # Calculate Sharpe per asset
+        volatilities = np.sqrt(np.diag(cov_matrix))
+        sharpe_per_asset = returns / (volatilities + 1e-8)
+        
+        # Utility score
+        utility = confidences * np.array(regime_scores) * sharpe_per_asset
+        
+        def objective(w):
+            # Maximize utility while controlling risk
+            portfolio_utility = np.dot(utility, w)
+            portfolio_risk = np.sqrt(w @ cov_matrix @ w)
+            
+            # Risk-adjusted utility
+            return -(portfolio_utility - 2.0 * portfolio_risk)
+        
+        # Bounds
+        bounds = []
+        for i, symbol in enumerate(constraints.assets[:n]):
+            min_w = constraints.min_weight.get(symbol, 0.0)
+            max_w = constraints.max_weight.get(symbol, 0.5)  # Cap at 50%
+            bounds.append((min_w, max_w))
+        
+        # Constraints
+        constraints_list = [
+            {'type': 'eq', 'fun': lambda w: np.sum(w) - 1.0}
+        ]
+        
+        x0 = np.ones(n) / n
+        
+        result = minimize(
+            objective,
+            x0=x0,
+            method='SLSQP',
+            bounds=bounds,
+            constraints=constraints_list
+        )
+        
+        return result.x if result.success else x0
+
+
+# ============================================================================
+# LAYER 6: RISK ANALYTICS
+# ============================================================================
+
+@dataclass
+class RiskReport:
+    """Comprehensive risk analysis of portfolio"""
+    
+    expected_return: float
+    portfolio_volatility: float
+    sharpe_ratio: float
+    sortino_ratio: float = 0.0
+    max_drawdown: float = 0.0
+    max_drawdown_recovery_days: int = 0
+    var_95: float = 0.0
+    cvar_95: float = 0.0
+    risk_contribution: Dict[str, float] = field(default_factory=dict)
+    diversification_ratio: float = 1.0
+    concentration_index: float = 0.0
+    
+    def to_markdown(self) -> str:
+        """Generate investor-ready risk summary"""
+        
+        md = f"""
+## Risk Metrics
+
+**Return & Volatility:**
+- Expected Return: {self.expected_return:.2%} annually
+- Portfolio Volatility: {self.portfolio_volatility:.2%} annually
+- Sharpe Ratio: {self.sharpe_ratio:.2f}
+- Sortino Ratio: {self.sortino_ratio:.2f}
+
+**Downside Risk:**
+- Maximum Drawdown: {self.max_drawdown:.2%}
+- Recovery Time: {self.max_drawdown_recovery_days} days
+- 95% VaR (1-day): {self.var_95:.2%}
+- 95% CVaR: {self.cvar_95:.2%}
+
+**Diversification:**
+- Diversification Ratio: {self.diversification_ratio:.2f}
+- Concentration Index (HHI): {self.concentration_index:.3f}
+
+**Risk Contributors:**
+"""
+        
+        for asset, contrib in sorted(self.risk_contribution.items(), 
+                                     key=lambda x: x[1], reverse=True):
+            md += f"- {asset}: {contrib:.2%}\n"
+        
+        return md
+
+
+class PortfolioRiskAnalytics:
+    """Layer 6: Compute institutional-grade risk metrics"""
+    
+    def compute_all_metrics(
+        self,
+        weights: np.ndarray,
+        returns: np.ndarray,
+        cov_matrix: np.ndarray,
+        asset_features: List[AssetFeatures]
+    ) -> RiskReport:
+        """Comprehensive risk analysis"""
+        
+        # Basic metrics
+        expected_return = self.expected_return(weights, returns)
+        portfolio_vol = self.portfolio_volatility(weights, cov_matrix)
+        sharpe = self.sharpe_ratio(expected_return, portfolio_vol)
+        
+        # VaR / CVaR
+        var_95 = self.value_at_risk(weights, returns, cov_matrix)
+        cvar_95 = self.conditional_var(weights, returns, cov_matrix)
+        
+        # Risk contribution
+        risk_contrib = self.risk_contribution_per_asset(weights, cov_matrix)
+        risk_contrib_dict = {
+            f.symbol: risk_contrib[i] 
+            for i, f in enumerate(asset_features)
+        }
+        
+        # Diversification
+        volatilities = np.sqrt(np.diag(cov_matrix))
+        div_ratio = calculate_diversification_ratio(weights, volatilities, cov_matrix)
+        
+        # Concentration (HHI)
+        hhi = np.sum(weights ** 2)
+        
+        return RiskReport(
+            expected_return=expected_return,
+            portfolio_volatility=portfolio_vol,
+            sharpe_ratio=sharpe,
+            var_95=var_95,
+            cvar_95=cvar_95,
+            risk_contribution=risk_contrib_dict,
+            diversification_ratio=div_ratio,
+            concentration_index=hhi
+        )
+    
+    def expected_return(self, weights: np.ndarray, returns: np.ndarray) -> float:
+        """E[R_p] = w^T μ"""
+        return np.dot(weights, returns)
+    
+    def portfolio_volatility(self, weights: np.ndarray, cov_matrix: np.ndarray) -> float:
+        """σ_p = sqrt(w^T Σ w)"""
+        return np.sqrt(weights @ cov_matrix @ weights)
+    
+    def sharpe_ratio(
+        self,
+        portfolio_return: float,
+        portfolio_vol: float,
+        risk_free_rate: float = 0.04
+    ) -> float:
+        """Sharpe = (R_p - R_f) / σ_p"""
+        if portfolio_vol == 0:
+            return 0.0
+        return (portfolio_return - risk_free_rate) / portfolio_vol
+    
+    def value_at_risk(
+        self,
+        weights: np.ndarray,
+        returns: np.ndarray,
+        cov_matrix: np.ndarray,
+        confidence_level: float = 0.95
+    ) -> float:
+        """95% VaR: Maximum loss at confidence level"""
+        
+        portfolio_return = returns @ weights
+        portfolio_vol = np.sqrt(weights @ cov_matrix @ weights)
+        
+        # Daily VaR (parametric)
+        z_score = stats.norm.ppf(1 - confidence_level)
+        var_daily = -(portfolio_return / 252 + z_score * portfolio_vol / np.sqrt(252))
+        
+        return var_daily
+    
+    def conditional_var(
+        self,
+        weights: np.ndarray,
+        returns: np.ndarray,
+        cov_matrix: np.ndarray,
+        confidence_level: float = 0.95
+    ) -> float:
+        """CVaR: Expected loss beyond VaR"""
+        
+        portfolio_return = returns @ weights
+        portfolio_vol = np.sqrt(weights @ cov_matrix @ weights)
+        
+        z_score = stats.norm.ppf(1 - confidence_level)
+        pdf_at_z = stats.norm.pdf(z_score)
+        
+        cvar = -(portfolio_return / 252 + portfolio_vol / np.sqrt(252) * pdf_at_z / (1 - confidence_level))
+        
+        return cvar
+    
+    def risk_contribution_per_asset(
+        self,
+        weights: np.ndarray,
+        cov_matrix: np.ndarray
+    ) -> np.ndarray:
+        """Marginal risk contribution of each asset"""
+        
+        portfolio_vol = self.portfolio_volatility(weights, cov_matrix)
+        
+        if portfolio_vol == 0:
+            return np.zeros_like(weights)
+        
+        marginal_contrib = cov_matrix @ weights
+        risk_contrib = weights * marginal_contrib / portfolio_vol
+        
+        # Normalize to sum to 1
+        return risk_contrib / risk_contrib.sum()
+
+
+# ============================================================================
+# LAYER 7: STRESS TEST & SCENARIO
+# ============================================================================
+
+@dataclass
+class StressTestResult:
+    """Result of a stress test scenario"""
+    
+    scenario_name: str
+    portfolio_loss_median: float
+    portfolio_loss_95th: float
+    max_drawdown: float
+    recovery_time_days: int
+    asset_level_losses: Dict[str, float]
+    vs_benchmark: float = 0.0
+    
+    def to_narrative(self) -> str:
+        """Generate human-readable stress summary"""
+        
+        return f"""
+**{self.scenario_name}:**
+- Median loss: {self.portfolio_loss_median:.2%}
+- Worst case (95th percentile): {self.portfolio_loss_95th:.2%}
+- Maximum drawdown: {self.max_drawdown:.2%}
+- Recovery time: {self.recovery_time_days} days
+- vs Benchmark: {self.vs_benchmark:+.2%}
+"""
+
+
+class StressTestEngine:
+    """Layer 7: Simulate portfolio under stress"""
+    
+    SCENARIOS = {
+        'market_crash': {
+            'description': '2008-style market crash',
+            'equity_shock': -0.35,
+            'vol_multiplier': 2.5,
+            'correlation_surge': 0.85,
+            'duration_days': 120
+        },
+        'volatility_spike': {
+            'description': 'VIX spikes to 60',
+            'equity_shock': -0.20,
+            'vol_multiplier': 3.0,
+            'correlation_surge': 0.75,
+            'duration_days': 30
+        },
+        'sector_selloff': {
+            'description': 'Tech sector crash',
+            'sector_shocks': {'Technology': -0.40, 'Consumer': -0.15},
+            'vol_multiplier': 2.0,
+            'duration_days': 90
+        }
+    }
+    
+    def run_stress_test(
+        self,
+        weights: np.ndarray,
+        asset_features: List[AssetFeatures],
+        scenario_name: str
+    ) -> StressTestResult:
+        """Simulate portfolio under stress scenario"""
+        
+        scenario = self.SCENARIOS.get(scenario_name, {})
+        
+        # Apply shocks to expected returns
+        shocked_returns = np.array([f.expected_return for f in asset_features])
+        equity_shock = scenario.get('equity_shock', 0.0)
+        shocked_returns += equity_shock
+        
+        # Portfolio loss
+        portfolio_loss_median = np.dot(weights, shocked_returns)
+        portfolio_loss_95th = portfolio_loss_median * 1.5  # Simplified
+        
+        # Asset-level losses
+        asset_losses = {
+            f.symbol: shocked_returns[i]
+            for i, f in enumerate(asset_features)
+        }
+        
+        # Recovery time (simplified)
+        recovery_days = scenario.get('duration_days', 90)
+        
+        return StressTestResult(
+            scenario_name=scenario_name,
+            portfolio_loss_median=portfolio_loss_median,
+            portfolio_loss_95th=portfolio_loss_95th,
+            max_drawdown=portfolio_loss_95th,
+            recovery_time_days=recovery_days,
+            asset_level_losses=asset_losses
+        )
+
+
+# ============================================================================
+# LAYER 8: REGIME-ADAPTIVE LOGIC
+# ============================================================================
+
+@dataclass
+class RegimeState:
+    """Current market regime state"""
+    regime: str
+    confidence: float
+    transition_probability: float = 0.0
+
+
+class RegimeAdaptiveAllocator:
+    """Layer 8: Dynamically adjust allocations by regime"""
+    
+    REGIME_RULES = {
+        'bull': {
+            'strategy': 'maximize_sharpe',
+            'equity_target': (0.70, 0.90),
+            'cash_target': (0.00, 0.10),
+            'rebalance_frequency': 'weekly'
+        },
+        'bear': {
+            'strategy': 'minimum_variance',
+            'equity_target': (0.30, 0.50),
+            'cash_target': (0.20, 0.40),
+            'rebalance_frequency': 'daily'
+        },
+        'sideways': {
+            'strategy': 'risk_parity',
+            'equity_target': (0.50, 0.70),
+            'cash_target': (0.10, 0.20),
+            'rebalance_frequency': 'monthly'
+        }
+    }
+    
+    def detect_current_regime(
+        self,
+        market_data: pd.DataFrame,
+        asset_features: List[AssetFeatures]
+    ) -> RegimeState:
+        """Detect current market regime"""
+        
+        # Aggregate regime signals from individual assets
+        regime_votes = {}
+        for feature in asset_features:
+            regime = feature.current_regime
+            regime_votes[regime] = regime_votes.get(regime, 0) + feature.regime_probability
+        
+        # Most probable regime
+        if regime_votes:
+            current_regime = max(regime_votes, key=regime_votes.get)
+            confidence = regime_votes[current_regime] / len(asset_features)
+        else:
+            current_regime = 'sideways'
+            confidence = 0.5
+        
+        return RegimeState(regime=current_regime, confidence=confidence)
+    
+    def apply_regime_rules(
+        self,
+        weights: np.ndarray,
+        regime: RegimeState,
+        asset_features: List[AssetFeatures]
+    ) -> np.ndarray:
+        """Apply regime-specific adjustments to weights"""
+        
+        rules = self.REGIME_RULES.get(regime.regime, self.REGIME_RULES['sideways'])
+        
+        # For bear markets, increase defensive assets
+        if regime.regime == 'bear' and regime.confidence > 0.7:
+            # Identify defensive assets (low beta, commodities)
+            for i, feature in enumerate(asset_features):
+                if feature.sector in ['Commodities', 'Utilities'] or feature.beta < 0.8:
+                    weights[i] *= 1.3  # Increase defensive weight
+                elif feature.beta > 1.2:
+                    weights[i] *= 0.7  # Reduce high-beta weight
+            
+            # Renormalize
+            weights = weights / weights.sum()
+        
+        return weights
+
+
+# ============================================================================
+# LAYER 9: EXPLAINABILITY & NARRATIVE
+# ============================================================================
+
+class PortfolioNarrativeGenerator:
+    """Layer 9: Generate human-readable investment rationale"""
+    
+    def generate_full_report(
+        self,
+        weights: np.ndarray,
+        asset_features: List[AssetFeatures],
+        risk_metrics: RiskReport,
+        regime: str,
+        optimization_mode: str
+    ) -> str:
+        """Create investor-grade portfolio summary"""
+        
+        report = f"""
+# 📊 PORTFOLIO INTELLIGENCE REPORT
+
+**Generated:** {datetime.now().strftime('%Y-%m-%d %H:%M')}
+**Optimization Mode:** {optimization_mode.replace('_', ' ').title()}
+**Market Regime:** {regime.title()}
+
+---
+
+## 🎯 PORTFOLIO SNAPSHOT
+
+{risk_metrics.to_markdown()}
+
+---
+
+## 📈 ALLOCATION BREAKDOWN
+
+"""
+        
+        # Asset allocations
+        for i, feature in enumerate(asset_features):
+            weight = weights[i]
+            report += f"""
+### {feature.symbol} - {weight:.1%}
+
+**Key Metrics:**
+- Expected Return: {feature.expected_return:.2%} (AI Confidence: {feature.expected_return_confidence:.0%})
+- Volatility: {feature.predicted_volatility:.2%}
+- Sector: {feature.sector or 'Unknown'}
+- Beta: {feature.beta:.2f}
+- Risk Contribution: {risk_metrics.risk_contribution.get(feature.symbol, 0):.2%}
+
+**Allocation Rationale:** 
+{self._explain_single_asset_weight(feature, weight, regime)}
+
+---
+"""
+        
+        return report
+    
+    def _explain_single_asset_weight(
+        self,
+        feature: AssetFeatures,
+        weight: float,
+        regime: str
+    ) -> str:
+        """Explain why a specific asset has its allocation"""
+        
+        reasons = []
+        
+        if feature.expected_return_confidence > 0.75:
+            reasons.append(f"High AI forecast confidence ({feature.expected_return_confidence:.0%})")
+        
+        if feature.current_regime == regime:
+            reasons.append(f"Favorable in {regime} regime")
+        
+        if feature.beta < 0.8:
+            reasons.append("Defensive characteristics (low beta)")
+        elif feature.beta > 1.2:
+            reasons.append("Growth characteristics (high beta)")
+        
+        if weight > 0.15:
+            reasons.append("High conviction position")
+        elif weight < 0.05:
+            reasons.append("Diversification play")
+        
+        return " | ".join(reasons) if reasons else "Balanced allocation"
+
+
+# ============================================================================
+# MAIN PORTFOLIO MODE CLASS
+# ============================================================================
+
+@dataclass
+class PortfolioResult:
+    """Complete portfolio construction result"""
+    
+    weights: np.ndarray
+    symbols: List[str]
+    risk_metrics: RiskReport
+    stress_tests: List[StressTestResult]
+    narrative: str
+    regime: RegimeState
+    timestamp: datetime = field(default_factory=datetime.now)
+    
+    def to_dict(self) -> Dict:
+        """Export as dictionary"""
+        return {
+            'weights': {self.symbols[i]: float(self.weights[i]) for i in range(len(self.symbols))},
+            'expected_return': float(self.risk_metrics.expected_return),
+            'volatility': float(self.risk_metrics.portfolio_volatility),
+            'sharpe_ratio': float(self.risk_metrics.sharpe_ratio),
+            'regime': self.regime.regime,
+            'timestamp': self.timestamp.isoformat()
+        }
+
+
+class PortfolioMode:
+    """
+    Main orchestrator for institutional-grade portfolio construction.
+    
+    Integrates all 10 layers into a single workflow.
+    """
+    
+    def __init__(
+        self,
+        constraints: PortfolioConstraints,
+        chronos_pipeline = None,  # Existing AI forecaster
+        regime_detector = None    # Existing regime detector
+    ):
+        self.constraints = constraints
+        self.chronos_pipeline = chronos_pipeline
+        self.regime_detector = regime_detector
+        
+        # Initialize layer components
+        self.data_layer = DataFeatureLayer()
+        self.correlation_layer = CovarianceEstimator()
+        self.forecast_aggregator = ForecastAggregator()
+        self.optimizer = OptimizationEngine()
+        self.risk_analytics = PortfolioRiskAnalytics()
+        self.stress_tester = StressTestEngine()
+        self.regime_allocator = RegimeAdaptiveAllocator()
+        self.narrative_generator = PortfolioNarrativeGenerator()
+    
+    def construct_portfolio(
+        self,
+        symbols: List[str],
+        historical_data: Dict[str, pd.DataFrame],
+        forecast_results: Dict[str, Dict],
+        regime_results: Dict[str, Dict],
+        optimization_mode: str = 'ai_weighted'
+    ) -> PortfolioResult:
+        """
+        End-to-end portfolio construction pipeline.
+        
+        Args:
+            symbols: List of asset tickers
+            historical_data: Dict of symbol -> DataFrame with OHLCV data
+            forecast_results: Dict of symbol -> AI forecast result
+            regime_results: Dict of symbol -> regime detection result
+            optimization_mode: 'min_variance' | 'max_sharpe' | 'risk_parity' | 'ai_weighted'
+        
+        Returns:
+            PortfolioResult with allocations, metrics, narratives
+        """
+        
+        # Layer 1: Validate
+        validation = self.constraints.validate()
+        if not validation.is_valid:
+            raise ValueError(f"Invalid constraints: {validation.errors}")
+        
+        # Layer 2: Compute features for each asset
+        asset_features = []
+        for symbol in symbols:
+            hist_data = historical_data.get(symbol)
+            forecast = forecast_results.get(symbol, {})
+            regime = regime_results.get(symbol, {})
+            
+            if hist_data is not None:
+                features = self.data_layer.compute_asset_features(
+                    symbol, hist_data, forecast, regime
+                )
+                asset_features.append(features)
+        
+        if not asset_features:
+            raise ValueError("No valid asset features computed")
+        
+        # Layer 3: Build correlation/covariance
+        returns_df = pd.DataFrame({
+            f.symbol: f.historical_returns 
+            for f in asset_features if f.historical_returns is not None
+        })
+        
+        # Layer 4: Aggregate forecasts
+        current_regime = self.regime_allocator.detect_current_regime(
+            returns_df, asset_features
+        )
+        
+        opt_inputs = self.forecast_aggregator.aggregate_to_optimization_inputs(
+            asset_features, current_regime.regime
+        )
+        
+        # Layer 5: Optimize
+        if optimization_mode == 'min_variance':
+            weights = self.optimizer.minimize_variance(
+                opt_inputs.cov_matrix, self.constraints
+            )
+        elif optimization_mode == 'max_sharpe':
+            weights = self.optimizer.maximize_sharpe(
+                opt_inputs.expected_returns,
+                opt_inputs.cov_matrix,
+                risk_free_rate=0.04,
+                constraints=self.constraints
+            )
+        elif optimization_mode == 'risk_parity':
+            weights = self.optimizer.risk_parity_allocation(
+                opt_inputs.cov_matrix, self.constraints
+            )
+        elif optimization_mode == 'ai_weighted':
+            weights = self.optimizer.ai_weighted_allocation(
+                opt_inputs.expected_returns,
+                opt_inputs.cov_matrix,
+                opt_inputs.confidence_weights,
+                regime_scores=[f.regime_probability for f in asset_features],
+                constraints=self.constraints
+            )
+        else:
+            raise ValueError(f"Unknown optimization mode: {optimization_mode}")
+        
+        # Layer 6: Risk analytics
+        risk_report = self.risk_analytics.compute_all_metrics(
+            weights, opt_inputs.expected_returns, opt_inputs.cov_matrix, asset_features
+        )
+        
+        # Layer 7: Stress testing
+        stress_results = []
+        for scenario_name in ['market_crash', 'volatility_spike', 'sector_selloff']:
+            stress_result = self.stress_tester.run_stress_test(
+                weights, asset_features, scenario_name
+            )
+            stress_results.append(stress_result)
+        
+        # Layer 8: Regime adaptation
+        regime_adjusted_weights = self.regime_allocator.apply_regime_rules(
+            weights, current_regime, asset_features
+        )
+        
+        # Layer 9: Generate narrative
+        narrative = self.narrative_generator.generate_full_report(
+            regime_adjusted_weights,
+            asset_features,
+            risk_report,
+            current_regime.regime,
+            optimization_mode
+        )
+        
+        return PortfolioResult(
+            weights=regime_adjusted_weights,
+            symbols=[f.symbol for f in asset_features],
+            risk_metrics=risk_report,
+            stress_tests=stress_results,
+            narrative=narrative,
+            regime=current_regime,
+            timestamp=datetime.now()
+        )
+
+
+# ============================================================================
+# EXAMPLE USAGE
+# ============================================================================
+
+if __name__ == "__main__":
+    
+    # Example: Construct a balanced portfolio
+    
+    # Define constraints
+    constraints = PortfolioConstraints(
+        assets=['AAPL', 'MSFT', 'GLD', 'TLT'],
+        asset_types={
+            'AAPL': 'equity',
+            'MSFT': 'equity',
+            'GLD': 'commodity',
+            'TLT': 'bond'
+        },
+        min_weight={'AAPL': 0.05, 'MSFT': 0.05, 'GLD': 0.0, 'TLT': 0.0},
+        max_weight={'AAPL': 0.30, 'MSFT': 0.30, 'GLD': 0.25, 'TLT': 0.25},
+        sector_caps={'Technology': 0.60},
+        risk_profile='balanced',
+        rebalance_frequency='weekly'
+    )
+    
+    # Validate
+    validation = constraints.validate()
+    print(f"Constraints valid: {validation.is_valid}")
+    if validation.warnings:
+        print(f"Warnings: {validation.warnings}")
+    
+    # Initialize portfolio mode (without actual AI models for demo)
+    portfolio_mode = PortfolioMode(constraints=constraints)
+    
+    print("\n✅ Portfolio Intelligence Engine initialized successfully!")
+    print(f"   - {len(constraints.assets)} assets in universe")
+    print(f"   - Risk profile: {constraints.risk_profile}")
+    print(f"   - Rebalance frequency: {constraints.rebalance_frequency}")