project-smaug

O project-smaug começou com uma necessidade pessoal: consultar os fundamentos das nove ações da minha carteira. As fontes oficiais usadas pelo projeto publicam arquivos consolidados do mercado, não uma resposta pronta por empresa. Para chegar aos ativos que eu queria analisar, o processamento precisou abranger a base completa.

Por que existe

Eu precisava combinar demonstrações financeiras, eventos societários e preços de uma forma que pudesse ser rastreada até a origem. As plataformas gratuitas que avaliei não disponibilizavam todo esse conjunto no formato necessário para os indicadores do projeto.

O objetivo passou a ser construir uma base própria, mantendo uma fronteira explícita entre o dado publicado pela fonte e qualquer cálculo feito depois.

O sistema possui duas fases independentes

CVM e B3
  → ingestão dos arquivos oficiais
  → espelho bruto no MongoDB
  → normalização e cálculos
  → indicadores no PostgreSQL
  → API de leitura com FastAPI

• Ingestão: copia e identifica os dados fundamentais sem adicionar cálculos ou interpretações.
• Análise: deriva os indicadores, persiste os resultados e os disponibiliza por uma API de leitura.

O projeto usa Python 3.13, uv, Beanie com MongoDB, SQLAlchemy e Alembic com PostgreSQL, FastAPI, mypy em modo estrito, ruff e pytest.

Um erro levou à criação do espelho bruto

Durante o desenvolvimento, regras plausíveis sobre os dados foram tratadas como fatos sem confirmação na fonte. A correção pontual não seria suficiente: outro cálculo poderia repetir o mesmo problema mais tarde.

A arquitetura passou a guardar uma cópia fiel do material coletado. Os cálculos vivem em outra etapa e podem ser refeitos sem alterar o registro original. Assim, um indicador consegue apontar para a entrada que o originou.

O preço também só entra na análise depois do ajuste pelos eventos societários posteriores, conforme a decisão registrada na ADR 0033. Essa separação evita misturar coleta e interpretação no mesmo processo.

Os arquivos oficiais exigem tratamento próprio

No fluxo implementado pelo projeto, os dados chegam principalmente em arquivos ZIP e planilhas consolidadas. O formato pode variar entre períodos, e uma coluna nem sempre ocupa a mesma posição em todos os arquivos.

A biblioteca pycvm atendia aos casos gerais avaliados, mas não oferecia o controle necessário para alguns indicadores. Por isso, estou separando o parser aprendido neste projeto em uma biblioteca chamada smaugcvm.

O parser ainda não foi publicado. Até isso acontecer, ele deve ser tratado como parte interna do project-smaug, não como uma biblioteca disponível para uso externo.

As decisões ficam ligadas à evidência

O repositório registra decisões de arquitetura em ADRs. Entre elas estão:

• uso apenas das fontes públicas da CVM e da B3 no fluxo atual;
• leitura da série histórica COTAHIST_A{ano}.ZIP para preços;
• conversão dos valores publicados em milhares antes do cruzamento com preços;
• coleta incremental e reexecutável, sem duplicar registros já processados;
• isolamento de falhas para que um ticker não interrompa os demais.

As conclusões que precisam continuar válidas também são verificadas por testes e pelo comando smaug doctor. Os planos antigos permanecem no histórico, mas não são usados como fonte atual das regras.

Estado atual

As fases de ingestão e análise funcionam com a minha carteira. A API lê os indicadores que já foram persistidos, e a separação entre MongoDB e PostgreSQL permite refazer a análise sem modificar o espelho das fontes.

O próximo passo técnico é publicar o smaugcvm. Existe também uma proposta de usar IA na análise das ações, mas os critérios dessa etapa ainda não foram definidos nem implementados. Ela permanece fora do estado atual do produto até que esses critérios possam ser testados.