@wentorai/research-plugins 1.0.0 → 1.2.0

package/skills/domains/finance/portfolio-optimization-guide/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: portfolio-optimization-guide
+description: "Portfolio theory, optimization algorithms, and asset allocation methods"
+metadata:
+  openclaw:
+    emoji: "briefcase"
+    category: "domains"
+    subcategory: "finance"
+    keywords: ["portfolio", "optimization", "markowitz", "asset-allocation", "mean-variance", "black-litterman"]
+    source: "wentor"
+---
+
+# Portfolio Optimization Guide
+
+A skill for implementing and researching portfolio optimization methods, from classical mean-variance optimization to modern robust and factor-based approaches. Covers Markowitz theory, Black-Litterman, risk parity, and machine learning-enhanced portfolio construction.
+
+## Mean-Variance Optimization
+
+### Classical Markowitz Portfolio
+
+```python
+import numpy as np
+from scipy.optimize import minimize
+
+def mean_variance_optimize(expected_returns: np.ndarray,
+                             cov_matrix: np.ndarray,
+                             target_return: float = None,
+                             risk_free_rate: float = 0.02) -> dict:
+    """
+    Markowitz mean-variance optimization.
+    expected_returns: array of expected returns for each asset
+    cov_matrix: covariance matrix of asset returns
+    target_return: target portfolio return (None for max Sharpe)
+    """
+    n_assets = len(expected_returns)
+
+    def portfolio_volatility(weights):
+        return np.sqrt(weights @ cov_matrix @ weights)
+
+    def neg_sharpe(weights):
+        ret = weights @ expected_returns
+        vol = portfolio_volatility(weights)
+        return -(ret - risk_free_rate) / vol
+
+    # Constraints
+    constraints = [
+        {"type": "eq", "fun": lambda w: np.sum(w) - 1},  # weights sum to 1
+    ]
+    if target_return is not None:
+        constraints.append(
+            {"type": "eq", "fun": lambda w: w @ expected_returns - target_return}
+        )
+
+    # Bounds: no short selling (0 to 1 per asset)
+    bounds = [(0, 1) for _ in range(n_assets)]
+
+    # Initial guess: equal weight
+    w0 = np.ones(n_assets) / n_assets
+
+    if target_return is not None:
+        # Minimize volatility for given return
+        result = minimize(portfolio_volatility, w0,
+                         bounds=bounds, constraints=constraints)
+    else:
+        # Maximize Sharpe ratio
+        result = minimize(neg_sharpe, w0,
+                         bounds=bounds, constraints=constraints)
+
+    weights = result.x
+    ret = weights @ expected_returns
+    vol = portfolio_volatility(weights)
+
+    return {
+        "weights": {f"asset_{i}": round(w, 4) for i, w in enumerate(weights)},
+        "expected_return": round(ret, 4),
+        "volatility": round(vol, 4),
+        "sharpe_ratio": round((ret - risk_free_rate) / vol, 4),
+    }
+```
+
+### Efficient Frontier
+
+```python
+def compute_efficient_frontier(expected_returns: np.ndarray,
+                                 cov_matrix: np.ndarray,
+                                 n_points: int = 50) -> list[dict]:
+    """
+    Compute the efficient frontier by solving for minimum variance
+    portfolios at each target return level.
+    """
+    min_ret = expected_returns.min() * 0.8
+    max_ret = expected_returns.max() * 1.1
+    target_returns = np.linspace(min_ret, max_ret, n_points)
+
+    frontier = []
+    for target in target_returns:
+        try:
+            result = mean_variance_optimize(
+                expected_returns, cov_matrix, target_return=target
+            )
+            frontier.append({
+                "return": result["expected_return"],
+                "volatility": result["volatility"],
+                "sharpe": result["sharpe_ratio"],
+            })
+        except Exception:
+            continue
+
+    return frontier
+```
+
+## Black-Litterman Model
+
+### Incorporating Investor Views
+
+```python
+def black_litterman(market_cap_weights: np.ndarray,
+                      cov_matrix: np.ndarray,
+                      P: np.ndarray,
+                      Q: np.ndarray,
+                      omega: np.ndarray = None,
+                      risk_aversion: float = 2.5,
+                      tau: float = 0.05) -> dict:
+    """
+    Black-Litterman model for combining market equilibrium with
+    investor views.
+    market_cap_weights: market-cap weighted portfolio
+    cov_matrix: covariance matrix
+    P: pick matrix (k views x n assets), identifies assets in each view
+    Q: view returns (k x 1), expected returns for each view
+    omega: view uncertainty (k x k), diagonal matrix
+    """
+    # Step 1: Implied equilibrium returns (reverse optimization)
+    pi = risk_aversion * cov_matrix @ market_cap_weights
+
+    # Step 2: View uncertainty (if not provided, use He-Litterman)
+    if omega is None:
+        omega = np.diag(np.diag(tau * P @ cov_matrix @ P.T))
+
+    # Step 3: Posterior expected returns
+    tau_sigma = tau * cov_matrix
+    inv_tau_sigma = np.linalg.inv(tau_sigma)
+    inv_omega = np.linalg.inv(omega)
+
+    posterior_precision = inv_tau_sigma + P.T @ inv_omega @ P
+    posterior_cov = np.linalg.inv(posterior_precision)
+    posterior_mean = posterior_cov @ (inv_tau_sigma @ pi + P.T @ inv_omega @ Q)
+
+    return {
+        "equilibrium_returns": pi.round(4).tolist(),
+        "posterior_returns": posterior_mean.round(4).tolist(),
+        "posterior_covariance": posterior_cov.round(6).tolist(),
+    }
+```
+
+## Risk Parity
+
+### Equal Risk Contribution Portfolio
+
+```python
+def risk_parity(cov_matrix: np.ndarray, budget: np.ndarray = None) -> dict:
+    """
+    Risk parity: each asset contributes equally to total portfolio risk.
+    budget: risk budget (default: equal, 1/n each)
+    """
+    n = cov_matrix.shape[0]
+    if budget is None:
+        budget = np.ones(n) / n
+
+    def objective(weights):
+        portfolio_vol = np.sqrt(weights @ cov_matrix @ weights)
+        marginal_risk = cov_matrix @ weights
+        risk_contribution = weights * marginal_risk / portfolio_vol
+        target_risk = budget * portfolio_vol
+        return np.sum((risk_contribution - target_risk) ** 2)
+
+    constraints = [{"type": "eq", "fun": lambda w: np.sum(w) - 1}]
+    bounds = [(0.01, 1) for _ in range(n)]
+    w0 = np.ones(n) / n
+
+    result = minimize(objective, w0, bounds=bounds, constraints=constraints)
+    weights = result.x
+
+    # Verify risk contributions
+    portfolio_vol = np.sqrt(weights @ cov_matrix @ weights)
+    marginal_risk = cov_matrix @ weights
+    risk_contrib = weights * marginal_risk / portfolio_vol
+    risk_pct = risk_contrib / risk_contrib.sum()
+
+    return {
+        "weights": weights.round(4).tolist(),
+        "portfolio_volatility": round(portfolio_vol, 4),
+        "risk_contributions": risk_pct.round(4).tolist(),
+        "max_risk_deviation": round(np.max(np.abs(risk_pct - budget)), 4),
+    }
+```
+
+## Factor-Based Portfolio Construction
+
+### Fama-French Factor Exposures
+
+```python
+import statsmodels.api as sm
+
+def estimate_factor_exposures(asset_returns: pd.DataFrame,
+                                factor_returns: pd.DataFrame) -> pd.DataFrame:
+    """
+    Estimate asset exposures to Fama-French factors using regression.
+    factor_returns columns: Mkt-RF, SMB, HML, RMW, CMA (5-factor model)
+    """
+    results = []
+    for asset in asset_returns.columns:
+        y = asset_returns[asset] - factor_returns.get("RF", 0)
+        X = sm.add_constant(factor_returns[["Mkt-RF", "SMB", "HML", "RMW", "CMA"]])
+        model = sm.OLS(y, X).fit()
+
+        results.append({
+            "asset": asset,
+            "alpha": round(model.params["const"], 6),
+            "beta_market": round(model.params["Mkt-RF"], 4),
+            "beta_size": round(model.params["SMB"], 4),
+            "beta_value": round(model.params["HML"], 4),
+            "beta_profit": round(model.params["RMW"], 4),
+            "beta_invest": round(model.params["CMA"], 4),
+            "r_squared": round(model.rsquared, 4),
+        })
+
+    return pd.DataFrame(results)
+```
+
+## Rebalancing and Transaction Costs
+
+### Optimal Rebalancing with Costs
+
+```python
+def rebalance_with_costs(current_weights: np.ndarray,
+                          target_weights: np.ndarray,
+                          portfolio_value: float,
+                          cost_per_trade: float = 0.001,
+                          threshold: float = 0.02) -> dict:
+    """
+    Determine rebalancing trades considering transaction costs.
+    threshold: minimum deviation to trigger rebalancing (2% default)
+    cost_per_trade: proportional transaction cost (10 bps)
+    """
+    deviations = np.abs(current_weights - target_weights)
+    needs_rebalance = np.any(deviations > threshold)
+
+    if not needs_rebalance:
+        return {"action": "hold", "reason": "within threshold"}
+
+    trades = target_weights - current_weights
+    trade_value = np.abs(trades) * portfolio_value
+    total_cost = trade_value.sum() * cost_per_trade
+
+    return {
+        "action": "rebalance",
+        "trades": trades.round(4).tolist(),
+        "turnover": np.abs(trades).sum() / 2,
+        "transaction_cost": round(total_cost, 2),
+        "cost_as_pct": round(total_cost / portfolio_value * 100, 4),
+    }
+```
+
+## Key Academic References
+
+- Markowitz, H. (1952). Portfolio Selection. *Journal of Finance*.
+- Black, F. and Litterman, R. (1992). Global Portfolio Optimization. *Financial Analysts Journal*.
+- Maillard, S., Roncalli, T., and Teiletche, J. (2010). The Properties of Equally Weighted Risk Contribution Portfolios. *Journal of Portfolio Management*.
+- Fama, E. and French, K. (2015). A Five-Factor Asset Pricing Model. *Journal of Financial Economics*.
+
+## Tools and Libraries
+
+- **PyPortfolioOpt**: Portfolio optimization in Python (mean-variance, Black-Litterman, HRP)
+- **riskfolio-lib**: Advanced portfolio optimization with risk measures
+- **cvxpy**: Convex optimization for custom portfolio problems
+- **QuantLib**: Fixed income and derivatives analytics
+- **Kenneth French Data Library**: Factor returns data (free)
+- **zipline / backtrader**: Backtesting frameworks for strategy evaluation

package/skills/domains/finance/risk-modeling-guide/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: risk-modeling-guide
+description: "Financial risk modeling including VaR, stress testing, and credit risk"
+metadata:
+  openclaw:
+    emoji: "chart-decreasing"
+    category: "domains"
+    subcategory: "finance"
+    keywords: ["risk-modeling", "var", "stress-testing", "credit-risk", "monte-carlo", "basel"]
+    source: "wentor"
+---
+
+# Risk Modeling Guide
+
+A skill for quantitative financial risk modeling, covering Value at Risk, Expected Shortfall, credit risk, stress testing, and Monte Carlo simulation methods. Essential for financial engineering research and regulatory risk analysis.
+
+## Market Risk: Value at Risk
+
+### VaR Methodologies
+
+| Method | Description | Pros | Cons |
+|--------|-------------|------|------|
+| Historical simulation | Replay past returns | No distributional assumption | Assumes past repeats |
+| Variance-covariance | Assume normal returns | Fast, analytical | Underestimates tail risk |
+| Monte Carlo simulation | Simulate from fitted model | Flexible distributions | Computationally expensive |
+| Filtered historical simulation | GARCH + historical innovations | Captures volatility clustering | More complex |
+
+### Implementation
+
+```python
+import numpy as np
+import pandas as pd
+from scipy.stats import norm, t as t_dist
+
+def historical_var(returns: np.ndarray, confidence: float = 0.99,
+                    horizon_days: int = 1) -> dict:
+    """
+    Compute Value at Risk using historical simulation.
+    returns: array of daily log returns
+    confidence: confidence level (e.g., 0.99 for 99% VaR)
+    horizon_days: risk horizon in days
+    """
+    # Scale returns to horizon
+    if horizon_days > 1:
+        # Rolling sum for overlapping returns
+        scaled_returns = pd.Series(returns).rolling(horizon_days).sum().dropna().values
+    else:
+        scaled_returns = returns
+
+    alpha = 1 - confidence
+    var = -np.percentile(scaled_returns, alpha * 100)
+    es = -np.mean(scaled_returns[scaled_returns <= -var])
+
+    return {
+        "VaR": round(var, 6),
+        "Expected_Shortfall": round(es, 6),
+        "confidence": confidence,
+        "horizon_days": horizon_days,
+        "n_observations": len(scaled_returns),
+    }
+
+def parametric_var(returns: np.ndarray, confidence: float = 0.99,
+                    distribution: str = "normal") -> dict:
+    """
+    Parametric VaR assuming normal or Student-t distribution.
+    """
+    mu = np.mean(returns)
+    sigma = np.std(returns, ddof=1)
+
+    if distribution == "normal":
+        z = norm.ppf(1 - confidence)
+        var = -(mu + sigma * z)
+        # Analytical ES for normal
+        es = -mu + sigma * norm.pdf(norm.ppf(1 - confidence)) / (1 - confidence)
+    elif distribution == "student-t":
+        # Fit Student-t
+        df, loc, scale = t_dist.fit(returns)
+        z = t_dist.ppf(1 - confidence, df)
+        var = -(loc + scale * z)
+        # ES for Student-t
+        t_pdf = t_dist.pdf(t_dist.ppf(1 - confidence, df), df)
+        es = -loc + scale * (t_pdf / (1 - confidence)) * ((df + z**2) / (df - 1))
+    else:
+        raise ValueError(f"Unknown distribution: {distribution}")
+
+    return {
+        "VaR": round(var, 6),
+        "Expected_Shortfall": round(es, 6),
+        "distribution": distribution,
+        "mean": round(mu, 6),
+        "std": round(sigma, 6),
+    }
+```
+
+### Monte Carlo VaR
+
+```python
+def monte_carlo_var(returns: np.ndarray, n_simulations: int = 100000,
+                     confidence: float = 0.99,
+                     horizon_days: int = 10) -> dict:
+    """
+    Monte Carlo VaR using GBM (Geometric Brownian Motion).
+    """
+    mu = np.mean(returns)
+    sigma = np.std(returns, ddof=1)
+
+    # Simulate daily returns for the horizon
+    rng = np.random.default_rng(42)
+    simulated = rng.normal(
+        mu * horizon_days,
+        sigma * np.sqrt(horizon_days),
+        size=n_simulations,
+    )
+
+    alpha = 1 - confidence
+    var = -np.percentile(simulated, alpha * 100)
+    es = -np.mean(simulated[simulated <= -var])
+
+    return {
+        "VaR": round(var, 6),
+        "Expected_Shortfall": round(es, 6),
+        "n_simulations": n_simulations,
+        "confidence": confidence,
+        "horizon_days": horizon_days,
+    }
+```
+
+## Credit Risk Modeling
+
+### Probability of Default Estimation
+
+```python
+from sklearn.linear_model import LogisticRegression
+
+def build_pd_model(features: pd.DataFrame,
+                    default_flag: pd.Series) -> dict:
+    """
+    Build a Probability of Default (PD) model using logistic regression.
+    Common features: debt-to-income, credit utilization, payment history,
+    employment length, loan amount.
+    """
+    model = LogisticRegression(max_iter=1000, class_weight="balanced")
+    model.fit(features, default_flag)
+
+    # Coefficient interpretation
+    coef_df = pd.DataFrame({
+        "feature": features.columns,
+        "coefficient": model.coef_[0],
+        "odds_ratio": np.exp(model.coef_[0]),
+    }).sort_values("coefficient", ascending=False)
+
+    # Model discrimination
+    from sklearn.metrics import roc_auc_score
+    pred_proba = model.predict_proba(features)[:, 1]
+    auc = roc_auc_score(default_flag, pred_proba)
+
+    return {
+        "auc": round(auc, 4),
+        "coefficients": coef_df.to_dict("records"),
+        "intercept": round(model.intercept_[0], 4),
+    }
+```
+
+### Loss Given Default and EAD
+
+```python
+def compute_expected_loss(pd_score: float, lgd: float,
+                           ead: float) -> dict:
+    """
+    Compute Expected Loss = PD x LGD x EAD.
+    pd_score: probability of default (0-1)
+    lgd: loss given default (0-1, fraction of exposure lost)
+    ead: exposure at default (dollar amount)
+    """
+    el = pd_score * lgd * ead
+    return {
+        "PD": pd_score,
+        "LGD": lgd,
+        "EAD": ead,
+        "Expected_Loss": round(el, 2),
+        "Unexpected_Loss_99": round(el * 2.33 * np.sqrt(pd_score * (1 - pd_score)), 2),
+    }
+```
+
+## Stress Testing
+
+### Scenario-Based Stress Tests
+
+```python
+def run_stress_test(portfolio_returns: pd.DataFrame,
+                     scenarios: dict[str, dict]) -> pd.DataFrame:
+    """
+    Apply macroeconomic stress scenarios to a portfolio.
+    scenarios: {name: {factor: shock_value}} where factors are
+    macroeconomic variables (interest_rate, gdp_growth, unemployment, etc.)
+    """
+    # Factor sensitivities (betas from regression)
+    # In practice, estimated via historical regression
+    factor_betas = {
+        "interest_rate": -0.15,    # portfolio loses 15bp per 1% rate increase
+        "gdp_growth": 0.08,        # gains 8bp per 1% GDP growth
+        "unemployment": -0.12,     # loses 12bp per 1% unemployment increase
+        "equity_market": 0.45,     # 45bp per 1% equity market move
+        "credit_spread": -0.25,    # loses 25bp per 1% spread widening
+    }
+
+    results = []
+    for name, shocks in scenarios.items():
+        portfolio_impact = 0
+        for factor, shock in shocks.items():
+            beta = factor_betas.get(factor, 0)
+            portfolio_impact += beta * shock
+
+        results.append({
+            "scenario": name,
+            "portfolio_impact_pct": round(portfolio_impact * 100, 2),
+            "shocks": shocks,
+        })
+
+    return pd.DataFrame(results)
+
+# Example scenarios
+scenarios = {
+    "Mild Recession": {
+        "interest_rate": -0.5, "gdp_growth": -2.0,
+        "unemployment": 2.0, "equity_market": -15.0,
+        "credit_spread": 1.5,
+    },
+    "Severe Recession": {
+        "interest_rate": -1.0, "gdp_growth": -5.0,
+        "unemployment": 5.0, "equity_market": -40.0,
+        "credit_spread": 4.0,
+    },
+    "Rate Shock": {
+        "interest_rate": 3.0, "gdp_growth": -1.0,
+        "unemployment": 1.0, "equity_market": -10.0,
+        "credit_spread": 1.0,
+    },
+}
+```
+
+## Regulatory Framework
+
+### Basel III Capital Requirements
+
+| Risk Type | Measurement | Capital Charge |
+|-----------|-------------|---------------|
+| Market risk | FRTB (Fundamental Review of the Trading Book) | ES at 97.5%, stressed calibration |
+| Credit risk | SA or IRB approach | PD, LGD, EAD based risk weights |
+| Operational risk | Basic Indicator / Standardized | Business indicator x ILM |
+| Liquidity risk | LCR and NSFR ratios | High-quality liquid assets buffer |
+
+## Tools and Libraries
+
+- **QuantLib (Python/C++)**: Derivatives pricing and risk analytics
+- **riskfolio-lib**: Portfolio risk and optimization in Python
+- **arch (Python)**: GARCH models for volatility estimation
+- **pyfolio**: Portfolio performance and risk analysis
+- **OpenGamma Strata**: Open-source market risk analytics (Java)
+- **Moody's Analytics / Bloomberg PORT**: Commercial risk platforms