Sobre o projeto

Sellside Research Engine é um pipeline em Python open-source com dashboard web estático que automatiza um ciclo central de pesquisa de renda variável. Ele extrai fundamentos auditados do SEC EDGAR XBRL, preços e estimativas consensuais do Yahoo Finance (via yfinance), o Treasury de 2 anos do FRED e EUR/USD do ECB; depois seleciona 21 ações dos EUA e avalia as 10 principais. Não são necessárias chaves de API. Cobertura e saídas - Universo: 21 ações americanas em 8 setores, configurável por DEFAULT_US_TICKERS em trg_workbench/config.py. O dashboard mostra as top 10 por pontuação de pesquisa, reclassificadas a cada atualização; comps, mapa de calor de fatores e dispersões cobrem todas as 21. - Avaliação: DCF de FCF nos cenários bear/base/bull com previsão de 5 anos em fading e valor terminal Gordon; DCF reverso (o crescimento implícito no preço atual); residual income e P/B justificado para bancos, corretoras e seguradoras; um football field de intervalos; e múltiplos de pares. - Risco: VaR e CVaR históricos (95%, 1 dia), volatilidade 21D/63D, beta vs o S&P 500, Sharpe, Sortino, máximo drawdown e matriz de correlação. - Sentimento e posicionamento: revisões de EPS, surpresas de lucro, tendência de recomendação, short interest e atividade de insiders. - Setor e macro: 10 ETFs setoriais SPDR vs o S&P 500, visão de rotação, ao vivo 10Y, 2Y, bill de 3M, VIX, DXY, WTI e EUR/USD. - Saídas: dashboard_data.json para o dashboard, uma nota de pesquisa HTML (modelo navy/gold), PDF via WeasyPrint com fallback em HTML, uma nota Markdown e gráficos PNG de 150 DPI. Como funciona Uma CLI (main_v2.py) expõe fetch-all, build-report e build-all, com as opções --dry-run, --quiet e --formats. Os dados são normalizados em data/normalized, exportados para dashboard_data.json e renderizados por um index.html de arquivo único que carrega o JSON em runtime. Um workflow do GitHub Actions roda em dias úteis às 22:00 UTC, faz commit do JSON apenas quando ele muda, e a integração Git da Vercel refaz o deploy a cada push. Um build em duas etapas (fetch-all e depois export_dashboard_data.py --skip-fetch) também é suportado. Notas metodológicas - Proxy de FCF = lucro líquido do SEC (fallback do Yahoo) x 0,80; o WACC usa um build CAPM com beta ajustado por Blume e D/E fixo de 0,30; a taxa livre de risco é o Treasury de 10Y ao vivo, com fallback de 5,3%. - O crescimento padrão é o crescimento de receita consensus +1y, com crescimento trailing como fallback, 5% quando nenhum existir, limitado entre -20% e 50%. - Os ratings são mecânicos a partir do upside do preço-alvo consenso: BUY acima de +10%, SELL abaixo de -10%, HOLD caso contrário. - Valores ausentes são gravados como null e renderizados como n/a; lacunas conhecidas incluem o FRED estar um dia defasado em relação ao Yahoo e lacunas ocasionais de um único dia no Yahoo. - O comentário da administração é uma heurística de palavras-chave sobre anexos de resultados 8-K do SEC, não um LLM; aparece n/a no site ao vivo porque a CI não tem transcrições em cache. Setup e personalização Quick start: clonar, pip install -r requirements.txt (Python 3.12), executar python export_dashboard_data.py e depois servir localmente com python -m http.server 8000. A SEC pede aos usuários da API detalhes de contato por meio de SEC_USER_AGENT. Um fork mais uma importação na Vercel implanta uma cópia pessoal; os forks devem manter o arquivo NOTICE e dar crédito ao repositório original. Os pontos de personalização incluem o universo de tickers, pesos de fatores em build_research_dataset, premissas de DCF em valuation.py e overlays de analistas via data/analyst_views.csv (apenas relatórios v1). Uma suíte pytest cobre extração de XBRL do SEC, normalização do ECB, triagem, entradas e cenários de DCF, DCF reverso, residual income, comps, janelas de retorno, TTM/DuPont, sentimento, exportação JSON, extração de comentários, templates e gráficos; ainda não há pytest CI. O projeto é licenciado sob Apache 2.0 e posicionado como ferramenta de pesquisa e educação, não como recomendação de investimento. Um roadmap lista trabalhos planejados, como inteligência de 10-K/10-Q, DCF Monte Carlo, faixas históricas de múltiplos, scores Piotroski e Altman, tearsheets, exportação para PowerPoint, Docker e pytest CI.