portfolio-optimization

What it does

Guides an AI agent to build and analyze quantitative portfolios using NVIDIA cuOpt for Mean-CVaR and Mean-Variance optimizations, including scenario generation, efficient frontier, backtesting, and rebalancing workflows.

How it works

• Ensures a Python environment with the portfolio_optimization package and cuOpt/cuML are available; defines CVaR solver settings as CVAR_SOLVER_SETTINGS for single-shot or frontier solves.
• Loads price data from data/stock_data/sp500.csv, validates the CSV structure (date-like index or first date column, numeric tickers, at least 60 rows, at least one ticker).
• If start/end dates are provided, slices the price data accordingly and reports the retained date range.
• Computes LOG returns via utils.calculate_returns.
• For Mean-CVaR tasks, generates CVaR data with cvar_utils.generate_cvar_data using KDE with KDESettings(device="GPU"). For Mean-Variance SOCP tasks, uses returns_dict directly and does not generate CVaR scenarios.
• For classic Mean-CVaR, defines CvarParameters with w_min, w_max, c_min=0.0, c_max=0.0, risk_aversion, and confidence.
• For variance-cap/SOCP/QCQP tasks, defines MeanVarianceParameters with var_limit, c_min=0.0, c_max=0.0, and L_tar=1.0; if a volatility cap is provided, squares it before assigning var_limit.
• Constructs the appropriate optimizer: CVaR(returns_dict, cvar_params) for Mean-CVaR or MeanVariance(returns_dict, mean_variance_params, api_settings=ApiSettings(api="cuopt_python")) for cuOpt Mean-Variance.
• Solves exclusively with cuOpt. Verifies cuOpt is available; if absent, reports missing GPU runtime instead of fabricating a CPU result.
• Maps custom constraints to the corresponding parameter fields (CvarParameters, MeanVarianceParameters) and notes unsupported mixed-integer conic constraints.
• If no benchmark is supplied for backtesting, uses an equal-weight portfolio; preserves default behavior for missing constraints.
• Returns results: weights sorted by allocation, cash, expected return, solver label (cuOpt GPU), and the risk metric; includes frontier figure, weights table, backtest metrics, or rebalancing schedule as requested.

When to use it

• When asked to build, optimize, backtest, rebalance, or analyze a stock portfolio with Mean-CVaR, Mean-Variance/SOCP variance caps, efficient frontiers, scenario generation, or NVIDIA cuOpt.
• Trigger phrases include: "optimize my portfolio", "build a CVaR portfolio", "use cuOpt to optimize these tickers", "solve with cuOpt", "plot the efficient frontier", "show weights by risk aversion", "backtest this allocation", "rebalance monthly", "analyze my holdings with CVaR", "stress-test my holdings", "evaluate downside-risk exposure".

What it can touch

• Uses the portfolio_optimization package APIs: utils.get_input_data, utils.calculate_returns, cvar_utils.generate_cvar_data, cvar_optimizer.CVaR, mean_variance_optimizer.MeanVariance, and settings like KDESettings, ReturnsComputeSettings, ApiSettings.
• No external file writes are mandated unless backtesting or rebalancing steps produce outputs; the workflow references data/stock_data/sp500.csv and relies on cuOpt for solving.

Caveats

• Requires cuOpt GPU solver; CPU solvers are not used. If cuOpt is absent, the skill reports missing GPU runtime instead of fabricating results.
• For Mean-Variance, cuOpt Python API must be importable; otherwise the setup cannot proceed.
• Data loading requires valid sp500 data; missing data prompts guidance to download via the package helper before proceeding.