Skill cuFOLIO
Propósito
Construir e analisar portfólios quantitativos com otimização Mean-CVaR acelerada por NVIDIA. Use cuFOLIO para calcular retornos, gerar cenários KDE, resolver alocações com o solver GPU cuOpt, traçar uma fronteira eficiente, realizar backtest de portfólios e executar fluxos de rebalanceamento a partir de dados de preços.
Quando Usar
Use esta skill quando a tarefa for:
- Construir ou otimizar um portfólio Mean-CVaR a partir de preços de ações.
- Alocar pesos entre ativos enquanto controla o risco CVaR de cauda.
- Plotar ou inspecionar uma fronteira eficiente para um universo de portfólio.
- Produzir uma tabela de pesos por aversão ao risco.
- Backtestar um portfólio otimizado contra benchmarks.
- Rebalancear um portfólio em uma agenda programada ou por gatilho de desvio.
- Executar fluxos em um dataset S&P 500, S&P 100, Dow 30 ou fornecido pelo usuário.
Frases de gatilho comuns incluem "otimize meu portfólio", "construa um portfólio CVaR", "use cuFOLIO nestes tickers", "resolva com cuOpt", "plote a fronteira eficiente", "mostre pesos por aversão ao risco", "backteste esta alocação", "rebalanceie mensalmente", "analise meus ativos com CVaR", "compare alocações", "reduza o risco de cauda", "construa uma alocação", "avalie opções de alocação", "stress-teste meus ativos", "avalie exposição ao risco de cauda", "revise meus ativos sob limites de peso", "compare portfólios de benchmark", "simule cenários CVaR", "analise risco do portfólio", "otimize ativos sob restrições" e "encontre uma alocação de menor risco".
Não use para resumos financeiros genéricos, previsão de preços, treinamento de redes neurais, roteamento de veículos ou otimização não relacionada a portfólios.
Pré-requisitos
- Ambiente Python com o pacote
cufolioinstalado. - GPU NVIDIA com cuOpt e cuML instalados.
- Extra CUDA correspondente ao host, como
uv sync --extra cuda12ouuv sync --extra cuda13. cvxpyexpondocp.CUOPT.- Acesso à rede na primeira execução se o CSV de preços padrão precisar ser baixado.
Configuração
Esta skill utiliza o pacote cufolio instalado. Um ambiente pronto pode vir do Brev launchable ou de NVIDIA-AI-Blueprints/cuFOLIO após instalar o extra CUDA correspondente.
Em sandboxes de agentes/avaliação empacotados, cufolio pode estar disponível via PYTHONPATH em vez de uma wheel publicada separadamente. Verifique o pacote local com python -c "import cufolio" antes de declará-lo ausente. Não execute pip install cufolio, não reimplemente fluxos cuFOLIO do zero e não substitua as APIs do pacote por código genérico de portfólio com pandas/scipy/cvxpy.
Para detalhes de implementação concretos, use references/workflows/agent_recipes.md como fonte da verdade. Ele contém formas exatas de trabalho para carregar preços, preparar retornos, resolver com cuOpt, construir uma fronteira de 25 pontos, backtestar contra peso igual e chamar o rebalanceador.
O dataset padrão é data/stock_data/sp500.csv. Ele está no .gitignore. Antes de um download na primeira execução, informe ao usuário que isso busca dados de mercado públicos através do helper de dados cuFOLIO/yfinance e peça confirmação:
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,
)
Instruções
Declare brevemente os padrões sendo aplicados antes da execução, depois use estas diretrizes:
- Carregue
data/stock_data/sp500.csv; se estiver faltando, peça antes de baixarsp500comcufolio.utils.download_data. Não use glob, substitua ou fabrique dados de preços. - Valide CSVs do usuário antes de resolver: exija um índice do tipo data ou primeira coluna de data, colunas de ticker numéricas, pelo menos 60 linhas após filtragem por data e pelo menos um ticker solicitado. Se o usuário fornecer datas de início/fim, fatie o DataFrame de preços antes do cálculo de retornos e informe o intervalo de datas retido. Filtre tickers no DataFrame de preços antes de calcular retornos.
regime_dictnão aceita um campo ticker. - Calcule retornos LOG com
utils.calculate_returns(...). - Gere cenários com
cvar_utils.generate_cvar_data(...), KDE eKDESettings(device="GPU"). - Defina
CvarParameterscomw_minew_maxexplícitos. Para solicitações comuns de "construir o portfólio ótimo", definac_min=0.0ec_max=0.0para que o resultado seja totalmente investido em vez de 100% em dinheiro. - Construa
cvar_optimizer.CVaR(returns_dict, cvar_params)diretamente a partir desse dicionário de retornos; mantenha tickers, arrays de cenário, médias e covariância nas formas retornadas pelos helpers do cuFOLIO. - Resolva apenas com NVIDIA cuOpt. Antes de resolver, verifique
hasattr(cp, "CUOPT")estr(cp.CUOPT) in {str(s) for s in cp.installed_solvers()}. PasseSOLVER_SETTINGSpara cada resolução única ou em loop de fronteira. Nunca recorra a CLARABEL, SCS, ECOS ou outro solver de CPU. Se cuOpt estiver ausente, finalize validação/configuração e reporte que o runtime GPU/cuOpt está faltando em vez de fabricar um resultado de CPU. - Para restrições personalizadas, mapeie solicitações do usuário para
CvarParameters: limites de peso paraw_min/w_max, apetite ao risco pararisk_aversion, nível de confiança paraconfidence, tolerância a dinheiro parac_max, e cardinalidade apenas quando o pacote expuser uma restrição explícita de contagem de ativos para o fluxo. Se as restrições entrarem em conflito (por exemplo, um peso máximo muito baixo para investir no número solicitado de tickers), explique o conflito e peça para a restrição ser relaxada em vez de adivinhar. - Se o usuário omitir um benchmark para backtesting, use um portfólio de peso igual sobre os mesmos tickers. Se o usuário omitir uma restrição, mantenha os valores padrão da tabela e reafirme brevemente as suposições consequentes antes de resolver.
- Entregue pesos ordenados por alocação, peso em dinheiro, retorno esperado, CVaR, rótulo do solver (
cuOpt GPU) e qualquer figura de fronteira solicitada, tabela de pesos, métricas de backtest ou cronograma de rebalanceamento. Para tabelas, inclua tickers como colunas ou linhas com pesos decimais e percentuais; para gráficos, preserve a figura retornada pelo cuFOLIO em vez de redesenhar do zero. - Para respostas de nível de relatório, inclua evidências de que o fluxo solicitado realmente foi executado. Para uma fronteira eficiente, informe
len(results_df)e use ora_numsolicitado (25 a menos que o usuário especifique o contrário). Para uma tabela de pesos, expandaresults_df["weights"]em colunas de ticker e incluacashmaisrisk_aversion. Para um backtest, incluamean portfolio return,sharpe,sortinoemax drawdowntanto para o portfólio otimizado quanto para o benchmark. Para rebalanceamento, incluaresults_dataframe,re_optimize_datese o final decumulative_portfolio_value.
Esqueleto de Fluxo Canônico
Inicie tarefas cuFOLIO positivas a partir desta forma e adapte apenas a saída solicitada. Para funções copiáveis completas, leia references/workflows/agent_recipes.md antes de escrever 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("cuOpt GPU solver is required; do not substitute a CPU solver.")
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,
scenario_generation_settings=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 uma fronteira eficiente ou tabela de pesos, chame:
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 um backtest com benchmark, envolva a alocação resolvida em Portfolio(name="cuOpt Optimal", tickers=returns_dict["tickers"], weights=optimal_portfolio.weights, cash=optimal_portfolio.cash), crie um Portfolio de peso igual sobre os mesmos returns_dict["tickers"], então use backtest.portfolio_backtester(..., test_method="historical").backtest_against_benchmarks(...). O backtester retorna (backtest_results, ax).
Para rebalanceamento mensal, escreva o DataFrame de preços primeiro em um caminho CSV. Instancie rebalance.rebalance_portfolio(dataset_directory=<csv_path>, ...) com re_optimize_criteria={"type": "drift_from_optimal", "threshold": 0, "norm": 1} e chame re_optimize(transaction_cost_factor=..., plot_title="Monthly Rebalancing"). O rebalanceador retorna (results_dataframe, re_optimize_dates, cumulative_portfolio_value).
Dados e Padrões
| Configuração | Padrão |
|---|---|
| Dataset | data/stock_data/sp500.csv |
| Intervalo de datas | Intervalo completo disponível |
| Tipo de portfólio | Apenas comprado (long-only) |
| Peso máximo | Nenhum a menos que especificado |
| Aversão ao risco | 1.0 |
| Confiança | 0.95 |
| Método de cenário | KDE na GPU |
| Solver | cuOpt GPU com PDLP |
| Rebalanceamento | Nenhum a menos que solicitado |
O arquivo S&P 500 padrão é um snapshot histórico e pode omitir constituintes atuais. CSVs fornecidos pelo usuário devem ser tabelas de preços indexadas por data com colunas de ticker, compatíveis com utils.get_input_data. Se tickers solicitados estiverem ausentes, remova-os, reporte as omissões e continue com as colunas disponíveis, a menos que o usuário peça explicitamente para buscar outros dados.
Principais APIs
Use as APIs do pacote em vez de reimplementar matemática de portfólio ou loops de simulação. Os helpers do cuFOLIO retornam objetos planos: returns_dict tem chaves como returns, mean, covariance e tickers; não o indexe como returns_dict["regime_1"]. solve_optimization_problem(...) retorna (result_row, portfolio), não um dicionário de resultado aninhado.
- Retornos:
utils.calculate_returns(input_dataset, regime_dict, returns_compute_settings). - Filtro de regime:
regime_dictéNoneou{"name": "...", "range": ("YYYY-MM-DD", "YYYY-MM-DD")}; não é chaveado por nome de regime e não contém tickers. - Cenários:
cvar_utils.generate_cvar_data(returns_dict, scenario_generation_settings). - Otimizador:
cvar_optimizer.CVaR(returns_dict, cvar_params). - Resolver:
result_row, portfolio = cvar_problem.solve_optimization_problem(solver_settings=SOLVER_SETTINGS, print_results=False). - Fronteira eficiente:
cvar_utils.create_efficient_frontier(returns_dict, cvar_params, solver_settings=SOLVER_SETTINGS, ra_num=25). Oresults_dfretornado inclui métricas, uma coluna de dicionárioweightsecash. - Portfólio:
Portfolio(name="", tickers=None, weights=None, cash=0.0, time_range=None); passe tickers e um array-like planoweightsalinhado a esses tickers. - Backtest: crie objetos
portfolio.Portfoliopara a alocação otimizada e cada benchmark; para um benchmark de peso igual, use pesos de1 / len(tickers)ecash=0.0, depois chamebacktest.portfolio_backtester(test_portfolio, returns_dict, risk_free_rate=0.0, test_method="historical", benchmark_portfolios=[...]).backtest_against_benchmarks(...). - Rebalanceamento:
rebalance.rebalance_portfolio(...)requer quedataset_directoryseja um caminho CSV, não um DataFrame. Chamere_optimize(...); ele retorna(results_dataframe, re_optimize_dates, cumulative_portfolio_value). - Modelos de configuração:
ReturnsComputeSettings,ScenarioGenerationSettings,KDESettings,ApiSettingseCvarParameters.
Exemplos
- "Construa o portfólio ótimo a partir do S&P 500": carregue preços, calcule retornos LOG, gere cenários GPU KDE, defina
CvarParametersapenas comprado e totalmente investido, resolva com cuOpt e reporte pesos diversificados mais retorno/CVaR. - "Plote a fronteira eficiente": chame
create_efficient_frontier(...), retorneresults_dfe mostre ou salve a figura conforme solicitado. - "Me dê pesos por aversão ao risco": expanda
results_df["weights"]em uma tabela por ativo. - "Backteste contra peso igual": construa os objetos
Portfoliootimizado e de peso igual, use o backtester cuFOLIO e reporte Sharpe, Sortino e drawdown máximo. - "Backteste rebalanceamento mensal": configure
rebalance_portfoliocom o gatilho de desvio acima e executere_optimize(transaction_cost_factor=...).
Limitações
- Requer uma GPU NVIDIA com cuOpt e cuML; solvers de CPU são intencionalmente proibidos.
- Contêineres de avaliação apenas CPU ainda podem validar roteamento, manipulação de dados e comportamento de relatório, mas não podem produzir uma resolução cuOpt válida. Nesse caso, reporte o runtime GPU/cuOpt faltante explicitamente.
- Dados de preços padrão são um snapshot histórico e podem omitir constituintes atuais.
- O download do dataset na primeira execução depende de acesso à rede, a menos que o usuário forneça um CSV.
Solução de Problemas
- CSV padrão ausente ou
FileNotFoundError: explique que cuFOLIO buscará dados de mercado públicos comdownload_data("data/stock_data", datasets=["sp500"]); execute apenas após confirmação do usuário. SolverErroroucp.CUOPTausente: instale o extra CUDA correspondente ao host e verifique compython -c "import cvxpy as cp; print(hasattr(cp, 'CUOPT'), cp.installed_solvers())".- `Im
...
[truncado para tradução]