Skill cuFOLIO
Propósito
Construir y analizar portafolios cuantitativos con la optimización Mean-CVaR acelerada por NVIDIA. Use cuFOLIO para calcular rendimientos, generar escenarios KDE, resolver asignaciones con el solucionador cuOpt en GPU, trazar una frontera eficiente, hacer backtesting de portafolios y ejecutar flujos de rebalanceo a partir de datos de precios.
Cuándo Usarlo
Use este skill cuando la tarea sea:
- Construir u optimizar un portafolio Mean-CVaR a partir de precios de acciones.
- Asignar pesos entre tickers mientras se controla el riesgo de cola CVaR.
- Graficar o inspeccionar una frontera eficiente para un universo de portafolio.
- Producir una tabla de pesos por aversión al riesgo.
- Hacer backtesting de un portafolio optimizado contra benchmarks.
- Rebalancear un portafolio según un calendario o un desencadenante de desviación.
- Ejecutar flujos de trabajo en un conjunto de datos de precios S&P 500, S&P 100, Dow 30 o proporcionado por el usuario.
Las frases desencadenantes comunes incluyen "optimiza mi portafolio", "construye un portafolio CVaR", "usa cuFOLIO en estos tickers", "resuelve con cuOpt", "grafica la frontera eficiente", "muestra los pesos por aversión al riesgo", "haz backtesting de esta asignación", "rebalancea mensualmente", "analiza mis tenencias con CVaR", "compara asignaciones", "reduce el riesgo de cola", "construye una asignación", "evalúa opciones de asignación", "prueba de estrés mis tenencias", "evalúa la exposición al riesgo de cola", "revisa mis tenencias con límites de peso", "compara portafolios benchmark", "simula escenarios CVaR", "evalúa el riesgo del portafolio", "optimiza tenencias bajo restricciones" y "encuentra una asignación de menor riesgo".
No lo use para resúmenes financieros genéricos, predicción de precios, entrenamiento de redes neuronales, enrutamiento de vehículos u optimización no relacionada con portafolios.
Prerrequisitos
- Entorno Python con el paquete
cufolioinstalado. - Tiempo de ejecución GPU NVIDIA con cuOpt y cuML instalados.
- Extra de CUDA que coincida con el host, como
uv sync --extra cuda12ouv sync --extra cuda13. cvxpyque expongacp.CUOPT.- Acceso a red en la primera ejecución si el archivo CSV de precios predeterminado debe descargarse.
Configuración
Este skill utiliza el paquete cufolio instalado. Un entorno listo puede provenir del lanzable de Brev o de NVIDIA-AI-Blueprints/cuFOLIO después de instalar el extra de CUDA correspondiente.
En entornos de agentes/eval empaquetados, cufolio puede estar disponible a través de PYTHONPATH en lugar de como una rueda publicada por separado. Verifique el paquete local con python -c "import cufolio" antes de declararlo como faltante. No ejecute pip install cufolio, no reimplemente flujos de trabajo de cuFOLIO desde cero y no reemplace las APIs del paquete con código genérico de pandas/scipy/cvxpy para portafolios.
Para detalles de implementación concretos, use references/workflows/agent_recipes.md como la fuente de verdad. Contiene formas de trabajo exactas para cargar precios, preparar rendimientos, resolver con cuOpt, construir una frontera de 25 puntos, hacer backtesting contra peso igual y llamar al rebalanceador.
El conjunto de datos predeterminado es data/stock_data/sp500.csv. Está en gitignore. Antes de una descarga en la primera ejecución, informe al usuario que esto obtiene datos de mercado públicos a través del ayudante de datos cuFOLIO/yfinance y pídale que confirme:
import cvxpy as cp
from cufolio.cvar_parameters import CvarParameters
from cufolio.utils import download_data
download_data("data/stock_data", datasets=["sp500"])
SOLVER_SETTINGS = {"solver": cp.CUOPT, "verbose": False, "solver_method": "PDLP"}
cvar_params = CvarParameters(
w_min=0.0, w_max=1.0,
c_min=0.0, c_max=0.0,
risk_aversion=1.0, confidence=0.95,
)
Instrucciones
Indique brevemente los valores predeterminados que se están aplicando antes de la ejecución, luego use estas barreras de seguridad:
- Cargue
data/stock_data/sp500.csv; si falta, pregunte antes de descargarsp500concufolio.utils.download_data. No use glob, sustituciones ni fabrique datos de precios. - Valide los CSV del usuario antes de resolver: requiera un índice similar a fecha o una primera columna de fecha, columnas de tickers numéricas, al menos 60 filas después del filtrado de fechas y al menos un ticker solicitado. Si el usuario proporciona fechas de inicio/fin, corte el DataFrame de precios antes del cálculo de rendimientos e informe el rango de fechas retenido. Filtre los tickers en el DataFrame de precios antes de que se calculen los rendimientos.
regime_dictno toma un campo de ticker. - Calcule rendimientos LOG con
utils.calculate_returns(...). - Genere escenarios con
cvar_utils.generate_cvar_data(...), KDE yKDESettings(device="GPU"). - Defina
CvarParametersconw_minyw_maxexplícitos. Para solicitudes ordinarias de "construir el portafolio óptimo", establezcac_min=0.0yc_max=0.0para que el resultado esté completamente invertido en lugar de 100% en efectivo. - Construya
cvar_optimizer.CVaR(returns_dict, cvar_params)directamente desde ese diccionario de rendimientos; mantenga tickers, arreglos de escenarios, medias y covarianzas en las formas devueltas por los ayudantes de cuFOLIO. - Resuelva solo con NVIDIA cuOpt. Antes de resolver, verifique
hasattr(cp, "CUOPT")ystr(cp.CUOPT) in {str(s) for s in cp.installed_solvers()}. PaseSOLVER_SETTINGSa cada resolución única o resolución de frontera en bucle. Nunca recurra a CLARABEL, SCS, ECOS u otro solucionador de CPU. Si cuOpt está ausente, termine la validación/configuración e informe que el tiempo de ejecución de GPU/cuOpt falta en lugar de fabricar un resultado de CPU. - Para restricciones personalizadas, mapee las solicitudes del usuario a
CvarParameters: límites de peso aw_min/w_max, apetito de riesgo arisk_aversion, nivel de confianza aconfidence, asignación de efectivo ac_max, y cardinalidad solo cuando el paquete exponga una restricción explícita de conteo de activos para el flujo de trabajo. Si las restricciones entran en conflicto (por ejemplo, un peso máximo demasiado bajo para invertir en la cantidad de tickers solicitada), explique el conflicto y pida que se relaje la restricción en lugar de adivinar. - Si el usuario omite un benchmark para backtesting, use un portafolio de igual peso sobre los mismos tickers. Si el usuario omite una restricción, mantenga los valores predeterminados de la tabla y reafirme brevemente las suposiciones consecuentes antes de resolver.
- Entregue pesos ordenados por asignación, peso de efectivo, rendimiento esperado, CVaR, etiqueta del solucionador (
cuOpt GPU) y cualquier figura de frontera, tabla de pesos, métricas de backtesting o calendario de rebalanceo solicitados. Para tablas, incluya tickers como columnas o filas con pesos decimales y porcentajes; para gráficos, conserve la figura de cuFOLIO devuelta en lugar de redibujar desde cero. - Para respuestas de nivel de informe, incluya evidencia de que el flujo de trabajo solicitado realmente se ejecutó. Para una frontera eficiente, indique
len(results_df)y use elra_numsolicitado (25 a menos que el usuario especifique lo contrario). Para una tabla de pesos, expandaresults_df["weights"]en columnas de tickers e incluyacashmásrisk_aversion. Para un backtesting, incluyamean portfolio return,sharpe,sortinoymax drawdowntanto para el portafolio optimizado como para el benchmark. Para rebalanceo, incluyaresults_dataframe,re_optimize_datesy la cola decumulative_portfolio_value.
Esqueleto de Flujo de Trabajo Canónico
Comience las tareas positivas de cuFOLIO desde esta forma y adapte solo la salida solicitada. Para funciones copiables completas, lea references/workflows/agent_recipes.md antes de escribir código personalizado.
import cvxpy as cp
import pandas as pd
from cufolio import backtest, cvar_optimizer, cvar_utils, rebalance, utils
from cufolio.cvar_parameters import CvarParameters
from cufolio.portfolio import Portfolio
from cufolio.settings import KDESettings, ReturnsComputeSettings, ScenarioGenerationSettings
if not hasattr(cp, "CUOPT") or str(cp.CUOPT) not in {str(s) for s in cp.installed_solvers()}:
raise RuntimeError("Se requiere el solucionador GPU cuOpt; no sustituya con un solucionador de CPU.")
SOLVER_SETTINGS = {"solver": cp.CUOPT, "verbose": False, "solver_method": "PDLP"}
prices = utils.get_input_data("data/stock_data/sp500.csv")
returns_dict = utils.calculate_returns(
prices,
regime_dict=None,
returns_compute_settings=ReturnsComputeSettings(return_type="LOG"),
)
returns_dict = cvar_utils.generate_cvar_data(
returns_dict,
ScenarioGenerationSettings(
fit_type="kde",
kde_settings=KDESettings(device="GPU"),
),
)
cvar_params = CvarParameters(
w_min=0.0,
w_max=1.0,
c_min=0.0,
c_max=0.0,
risk_aversion=1.0,
confidence=0.95,
)
optimizer = cvar_optimizer.CVaR(returns_dict, cvar_params)
result, optimal_portfolio = optimizer.solve_optimization_problem(
solver_settings=SOLVER_SETTINGS,
print_results=False,
)
Para una frontera eficiente o tabla de pesos, llame:
results_df, fig, ax = cvar_utils.create_efficient_frontier(
returns_dict,
cvar_params,
SOLVER_SETTINGS,
ra_num=25,
show_plot=False,
show_discretized_portfolios=False,
benchmark_portfolios=False,
print_portfolio_results=False,
)
weights_table = pd.DataFrame(results_df["weights"].tolist(), index=results_df.index)
Para un backtesting con benchmark, envuelva la asignación resuelta en Portfolio(name="cuOpt Optimal", tickers=returns_dict["tickers"], weights=optimal_portfolio.weights, cash=optimal_portfolio.cash), cree un Portfolio de igual peso sobre los mismos returns_dict["tickers"], luego use backtest.portfolio_backtester(..., test_method="historical").backtest_against_benchmarks(...). El backtester devuelve (backtest_results, ax).
Para rebalanceo mensual, primero escriba el DataFrame de precios en una ruta CSV. Instancie rebalance.rebalance_portfolio(dataset_directory=<csv_path>, ...) con re_optimize_criteria={"type": "drift_from_optimal", "threshold": 0, "norm": 1} y llame a re_optimize(transaction_cost_factor=..., plot_title="Rebalanceo Mensual"). El rebalanceador devuelve (results_dataframe, re_optimize_dates, cumulative_portfolio_value).
Datos y Valores Predeterminados
| Configuración | Valor Predeterminado |
|---|---|
| Conjunto de datos | data/stock_data/sp500.csv |
| Rango de fechas | Rango completo disponible |
| Tipo de portafolio | Solo largo |
| Peso máximo | Ninguno a menos que se especifique |
| Aversión al riesgo | 1.0 |
| Confianza | 0.95 |
| Método de escenario | KDE en GPU |
| Solucionador | cuOpt GPU con PDLP |
| Rebalanceo | Ninguno a menos que se solicite |
El archivo predeterminado del S&P 500 es una instantánea histórica y puede omitir los componentes actuales. Los CSV proporcionados por el usuario deben ser tablas de precios indexadas por fecha con columnas de tickers, compatibles con utils.get_input_data. Si los tickers solicitados están ausentes, elimínelos, informe las omisiones y continúe con las columnas disponibles a menos que el usuario solicite explícitamente obtener otros datos.
APIs Clave
Use las APIs del paquete en lugar de reimplementar matemáticas de portafolio o bucles de simulación. Los ayudantes de cuFOLIO devuelven objetos planos: returns_dict tiene claves como returns, mean, covariance y tickers; no lo indexe como returns_dict["regime_1"]. solve_optimization_problem(...) devuelve (result_row, portfolio), no un diccionario de resultados anidado.
- Rendimientos:
utils.calculate_returns(input_dataset, regime_dict, returns_compute_settings). - Filtro de régimen:
regime_dictesNoneo{"name": "...", "range": ("YYYY-MM-DD", "YYYY-MM-DD")}; no está indexado por nombre de régimen y no contiene tickers. - Escenarios:
cvar_utils.generate_cvar_data(returns_dict, scenario_generation_settings). - Optimizador:
cvar_optimizer.CVaR(returns_dict, cvar_params). - Resolución:
result_row, portfolio = cvar_problem.solve_optimization_problem(solver_settings=SOLVER_SETTINGS, print_results=False). - Frontera eficiente:
cvar_utils.create_efficient_frontier(returns_dict, cvar_params, solver_settings=SOLVER_SETTINGS, ra_num=25). Elresults_dfdevuelto incluye métricas, una columna de diccionarioweightsycash. - Portafolio:
Portfolio(name="", tickers=None, weights=None, cash=0.0, time_range=None); pase tickers y un arreglo plano similar aweightsalineado con esos tickers. - Backtesting: cree objetos
portfolio.Portfoliopara la asignación optimizada y cada benchmark; para un benchmark de igual peso, use pesos de1 / len(tickers)ycash=0.0, luego llame abacktest.portfolio_backtester(test_portfolio, returns_dict, risk_free_rate=0.0, test_method="historical", benchmark_portfolios=[...]).backtest_against_benchmarks(...). - Rebalanceo:
rebalance.rebalance_portfolio(...)requiere quedataset_directorysea una ruta CSV, no un DataFrame. Llame are_optimize(...); devuelve(results_dataframe, re_optimize_dates, cumulative_portfolio_value). - Modelos de configuración:
ReturnsComputeSettings,ScenarioGenerationSettings,KDESettings,ApiSettingsyCvarParameters.
Ejemplos
- "Construye el portafolio óptimo del S&P 500": cargue precios, calcule rendimientos LOG, genere escenarios KDE en GPU, establezca
CvarParametersde solo largo totalmente invertido, resuelva con cuOpt e informe pesos diversificados más rendimiento/CVaR. - "Grafica la frontera eficiente": llame a
create_efficient_frontier(...), devuelvaresults_dfy muestre o guarde la figura según lo solicitado. - "Dame los pesos por aversión al riesgo": expanda
results_df["weights"]en una tabla por activo. - "Haz backtesting contra peso igual": construya los objetos
Portfoliooptimizado y de igual peso, luego use el backtester de cuFOLIO e informe Sharpe, Sortino y máxima pérdida. - "Haz backtesting con rebalanceo mensual": configure
rebalance_portfoliocon el desencadenante de desviación anterior y ejecutere_optimize(transaction_cost_factor=...).
Limitaciones
- Requiere una GPU NVIDIA con cuOpt y cuML; los solucionadores de CPU están intencionalmente deshabilitados.
- Los contenedores de evaluación solo con CPU aún pueden validar el enrutamiento, el manejo de datos y el comportamiento de informes, pero no pueden producir una resolución válida de cuOpt. En ese caso, informe explícitamente la falta de tiempo de ejecución de GPU/cuOpt.
- Los datos de precios predeterminados son una instantánea histórica y pueden omitir los componentes actuales.
- La descarga del conjunto de datos en la primera ejecución depende del acceso a la red a menos que el usuario proporcione un CSV.
Solución de Problemas
- Archivo CSV predeterminado faltante o
FileNotFoundError: explique que cuFOLIO obtendrá datos de mercado públicos condownload_data("data/stock_data", datasets=["sp500"]); ejecútelo solo después de la confirmación del usuario. SolverErrorocp.CUOPTfaltante: instale el extra de CUDA que coincida con el host y verifique conpython -c "import cvxpy as cp; print(hasattr(cp, 'CUOPT'), cp.installed_solvers())".ImportErroro función faltante de cuFOLIO: verifique que el paquete esté instalado y que la ruta esté enPYTHONPATH(en entornos empaquetados).- Datos de precios insuficientes: confirme que el CSV tenga al menos 60 filas y al menos un ticker solicitado, o pida un conjunto de datos más grande.
- Las restricciones no cuadran: describa el conflicto y pida al usuario que relaje un límite (por ejemplo,
w_maxpara cubrir todos los tickers) en lugar de elegir un valor arbitrario.
Notas Adicionales
- Mantenga los resultados de la resolución como objetos planos de Python (DataFrame, Portafolio, figura de matplotlib).
- No serialice ni convierta las figuras a base64; devuélvalas directamente.
- Para informes completos, incluya tanto los mensajes de texto como los artefactos visuales (por ejemplo, figura de la frontera, tabla de backtesting).
- Si el usuario solicita una comparación con benchmarks, presente una tabla lado a lado con métricas para cada portafolio.
- El código de rebalanceo requiere que la ruta del CSV se pase como
dataset_directory; no use un DataFrame directamente. - Para activar el rebalanceo por desviación, use
re_optimize_criteriacon"drift_from_optimal"y un umbral de 0 para rebalancear en cada fecha del historial. - Los valores predeterminados de
w_min=0.0,w_max=1.0,c_min=0.0,c_max=0.0garantizan una asignación totalmente invertida y solo larga, a menos que el usuario especifique lo contrario. - La frontera eficiente generada por
create_efficient_frontierpuede incluir puntos no convexos debido a la discretización; no la suavice ni la interpole. - Para backtesting, el portafolio de igual peso es un benchmark común; si el usuario no proporciona uno, asuma ese valor predeterminado e infórmelo.