Metadata-Version: 2.3
Name: bacen-ifdata-scraper
Version: 0.0.5
Summary: Um sistema ETL ponta a ponta para extrair, transformar e carregar relatórios financeiros do portal IF.data do Banco Central do Brasil.
Keywords: bacen,banco-central,banco-central-brasil,ifdata,if-data,web-scraping,scraper,automation,financial-data,banking-data,financial-reports,institucoes-financeiras,financial-institutions,financial-analysis,banking-analysis,etl,open-data,public-data,data-pipeline,data-processing,data-cleaning,csv-processing,data-extraction,data-transformation,data-automation,brazil,brasil,selenium,polars,duckdb
Author: Alexsander Lopes Camargos
Author-email: Alexsander Lopes Camargos <alcamargos@vivaldi.net>
License: MIT License
         
         Copyright (c) 2023 - 2026 [Alexsander Lopes Camargos]
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Requires-Dist: selenium>=4.16.0,<5
Requires-Dist: loguru>=0.7.2,<0.8
Requires-Dist: pandas>=2.2.2,<3
Requires-Dist: pydantic>=2.9.2,<3
Requires-Dist: duckdb>=1.1.1,<2
Requires-Dist: polars>=1.32.2,<2
Requires-Dist: pyarrow>=21.0.0,<22
Requires-Dist: python-dotenv>=1.1.1,<2
Requires-Dist: fire>=0.7.0,<0.8
Requires-Dist: pandera>=0.26.0,<0.27
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: dbt-duckdb>=1.10.0
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/alexcamargos/bacen-ifdata-scraper
Project-URL: Repository, https://github.com/alexcamargos/bacen-ifdata-scraper
Project-URL: Issues, https://github.com/alexcamargos/bacen-ifdata-scraper/issues
Description-Content-Type: text/markdown

# Bacen IF.data AutoScraper & Data Manager

[![LinkedIn](https://img.shields.io/badge/%40alexcamargos-230A66C2?style=social&logo=LinkedIn&label=LinkedIn&color=white)](https://www.linkedin.com/in/alexcamargos)

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

*Um sistema ETL ponta a ponta para extrair, transformar e carregar relatórios financeiros do portal IF.data do Banco Central do Brasil.*

[![Python](https://img.shields.io/badge/Python-3.11%2B-blue?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[![uv](https://img.shields.io/badge/uv-blue?style=for-the-badge&logo=bun&logoColor=white)](https://github.com/astral-sh/uv)
[![Selenium](https://img.shields.io/badge/Selenium-43B02A?style=for-the-badge&logo=selenium&logoColor=white)](https://www.selenium.dev/)
[![Polars](https://img.shields.io/badge/Polars-000000?style=for-the-badge&logo=polars&logoColor=white)](https://pola.rs/)
[![DuckDB](https://img.shields.io/badge/DuckDB-FFFFFF?style=for-the-badge&logo=duckdb&logoColor=black)](https://duckdb.org/)
[![dbt](https://img.shields.io/badge/dbt-FF694B?style=for-the-badge&logo=dbt&logoColor=white)](https://www.getdbt.com/)

Este projeto automatiza a coleta, o processamento e a carga dos relatórios financeiros disponibilizados pelo Banco Central do Brasil através do portal IF.data. Diante do desafio de extrair dados valiosos de um formato de CSV não padronizado e de um processo de download manual, esta ferramenta utiliza **Selenium** para a automação da navegação e download, e scripts **Python** com **Polars**, **DuckDB** e **dbt** para a limpeza, transformação e modelagem dos dados.

O objetivo é transformar os dados brutos e inconsistentes do Bacen em um conjunto de dados limpo, organizado e pronto para análise, eliminando a necessidade de trabalho manual e garantindo a precisão das informações através de um pipeline ETL (Extract, Transform, Load) completo.

**Sumário**

- [Bacen IF.data AutoScraper \& Data Manager](#bacen-ifdata-autoscraper--data-manager)
  - [Tecnologias Utilizadas](#tecnologias-utilizadas)
  - [Funcionalidades Principais](#funcionalidades-principais)
  - [Demonstração de Execução](#demonstração-de-execução)
  - [Motivação](#motivação)
  - [O Portal IF.Data](#o-portal-ifdata)
  - [O Banco Central do Brasil](#o-banco-central-do-brasil)
  - [Objetivo Geral](#objetivo-geral)
  - [Instalação](#instalação)
  - [Uso do Pipeline](#uso-do-pipeline)
    - [Extração (Scraping)](#extração-scraping)
    - [Limpeza (Cleaning)](#limpeza-cleaning)
    - [Transformação (Transforming)](#transformação-transforming)
    - [Carga (Loading)](#carga-loading)
    - [Execução Padrão](#execução-padrão)
  - [Arquitetura do Sistema](#arquitetura-do-sistema)
  - [Desafios e Aprendizados](#desafios-e-aprendizados)
  - [Autor](#autor)
  - [Licença](#licença)

## Tecnologias Utilizadas

- **Linguagem Principal:** Python
- **Gerenciador de Dependências e Build:** uv
- **Automação Web (Scraping):** Selenium
- **Manipulação de Dados:** Polars
- **Banco de Dados Analítico:** DuckDB
- **Validação de Dados:** Pydantic, Pandera
- **CLI:** Fire
- **Web Driver:** GeckoDriver (para Firefox)

## Funcionalidades Principais

- [x] **Extração (Extract):** Realiza o download automático de todos os relatórios CSV do portal IF.data para um determinado período.
- [x] **Limpeza (Clean):** Corrige arquivos CSV com formatação não-padrão, removendo cabeçalhos e informações consolidadas indesejadas.
- [x] **Transformação (Transform):** Estrutura os dados limpos, aplicando schemas e transformações para prepará-los para análise.
- [x] **Carga (Load):** Carrega os dados transformados em um banco de dados DuckDB para consulta e análise eficientes.
- [x] **Analytics (Model):** Cria modelos dimencionais (Star Schema) prontos para BI usando dbt.
- [x] **Setup Simplificado:** Suporte para instalação de dependências e execução com uv.
- [x] **Relatório de Execução:** Gera um relatório ao final da execução do scraper com o total de arquivos baixados e o tempo de execução.

## Demonstração de Execução

Veja o pipeline de automação em ação.

![scraper running](assets/scraper_running.png)

![Firefox Webdriver running](assets/scraper_webdriver.png)

<!-- Project details -->
<details>

  <summary>Clique para saber mais sobre o contexto do projeto</summary>

## Motivação

  Embora o Bacen disponibilize dados para o público em geral, com o objetivo de atender ao disposto na Lei 12.527 de 2011 (popularmente conhecida como Lei de Acesso à Informação), a forma como esses dados são apresentados exige a aplicação de métodos especializados para sua interpretação. É necessário empregar uma série de procedimentos e técnicas para extrair informações mais sofisticadas desses dados. A utilização de algoritmos e técnicas de tratamento e mineração de dados é fundamental nesse contexto. Essas abordagens permitem a extração de insights mais complexos dos dados fornecidos pelo Bacen, facilitando análises mais profundas e detalhadas sobre o sistema financeiro brasileiro.

## O Portal IF.Data

  O Portal IF.Data, criado pelo Banco Central do Brasil (Bacen), atende às exigências da Lei de Acesso à Informação ([Lei 12.527 de 2011](https://www.planalto.gov.br/ccivil_03/_ato2011-2014/2011/lei/l12527.htm)). Essa legislação obriga o poder público a publicar informações na internet de maneira acessível e em formatos compatíveis com processamento automatizado. O portal se caracteriza por ser interativo, armazenando e disponibilizando uma série de relatórios sobre instituições financeiras. Estes relatórios, que são atualizados trimestralmente, incluem dados abertos e podem ser visualizados online ou baixados em formato .csv.

  No Portal IF.Data, é possível encontrar dados relacionados a contabilidade e capital, crédito, câmbio e segmentação das instituições financeiras. O portal abrange dados desde o ano 2000, e também oferece acesso a informações anteriores, de 1994 a 2000, embora em formatos diferentes. Para acessar os dados, o usuário pode selecionar no portal o trimestre de interesse, o tipo de instituição financeira e o relatório desejado.

## O Banco Central do Brasil

  O Banco Central do Brasil, frequentemente referido como Bacen, é a autoridade monetária principal do Brasil e desempenha um papel crucial na economia do país. Sua principal função é garantir a estabilidade do poder de compra da moeda nacional, o Real, e manter um sistema financeiro sólido e eficiente. Para isso, o Bacen regula a quantidade de dinheiro em circulação, administra as reservas internacionais do país, e atua como um regulador e supervisor do sistema financeiro, controlando e fiscalizando as instituições financeiras. Além disso, é responsável pela formulação e execução da política monetária, buscando controlar a inflação e influenciar as atividades econômicas. Como parte de suas funções, o Bacen também coleta e divulga dados econômicos e financeiros importantes, como os disponibilizados no Portal IF.Data, para garantir transparência e acesso à informação para o público em geral e para instituições financeiras.

## Objetivo Geral

  Este projeto visa aprimorar a coleta e o processamento de dados através da automação de atividades em navegadores web, utilizando a biblioteca [Selenium](https://www.selenium.dev). Selenium é uma ferramenta poderosa para a automação de browsers, permitindo a extração eficiente de dados de diversas fontes online. Após a coleta, o projeto focará no agrupamento e tratamento desses dados, organizando-os de maneira sistemática e coerente.

  Essa abordagem não só economiza tempo e recursos, eliminando a necessidade de coleta manual de dados, mas também aumenta a precisão e a confiabilidade das informações obtidas. A fase de tratamento dos dados é crucial, pois envolve limpeza, normalização e consolidação de informações de múltiplas fontes, preparando-as para análises mais aprofundadas.

  O resultado final será um conjunto de dados estruturado e de fácil acesso, proporcionando uma base sólida para análises futuras. Este conjunto de dados permitirá aos analistas e pesquisadores extrair insights valiosos e realizar avaliações detalhadas em seus respectivos campos de estudo ou indústrias. Além disso, o uso de automação e tratamento avançado de dados representa um passo importante na direção da modernização e eficiência dos processos de coleta e análise de dados.
</details>

## Instalação

Primeiro, clone o repositório:

```bash
git clone https://github.com/alexcamargos/bacen-ifdata-scraper.git

cd bacen-ifdata-scraper
```

Para criar um ambiente virtual e instalar as dependências com `uv`:

```bash
# Crie o ambiente virtual
uv venv

# Ative o ambiente (Linux/macOS)
source .venv/bin/activate

# Ou no Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Sincronize o ambiente com as dependências
uv sync
```

Configure as variáveis de ambiente do projeto para permitir execução do dbt via pipeline e standalone:

```bash
# Crie o arquivo de variáveis a partir do exemplo
cp .env.example .env
```

No Windows PowerShell:

```powershell
Copy-Item .env.example .env
```

Edite o arquivo `.env` se necessário para ajustar os caminhos locais dos bancos DuckDB.

> **Observação:** Antes de iniciar o processo de captura, certifique-se de que o [GeckoDriver](https://github.com/mozilla/geckodriver/releases) (para Firefox) esteja devidamente instalado e configurado no `PATH` do seu sistema.

## Uso do Pipeline

O `ifdata.py` é a interface de linha de comando para controlar o pipeline ETL.

### Extração (Scraping)

Para baixar os relatórios do portal IF.data, use a flag `-s` ou `--scraper`. O script irá navegar pelo portal, selecionar as instituições e relatórios, e baixar os arquivos CSV.

```bash
uv run ifdata.py -s
```

O script exibirá em tempo real quais arquivos estão sendo baixados. Ao final, um relatório detalhará o número total de arquivos baixados e o tempo de execução.

### Limpeza (Cleaning)

Os arquivos CSV baixados do Bacen não seguem um padrão consistente, contendo múltiplos cabeçalhos e linhas de resumo. A etapa de limpeza corrige essas inconsistências. Use a flag `-c` ou `--cleaner`.

```bash
uv run ifdata.py -c
```

### Transformação (Transforming)

Após a limpeza, os dados são transformados para um formato estruturado e analítico, aplicando schemas e preparando-os para serem carregados. Use a flag `-t` ou `--transformer`.

```bash
uv run ifdata.py -t
```

### Carga (Loading)

Finalmente, os dados transformados são carregados em um banco de dados DuckDB para fácil consulta e análise. Use a flag `-l` ou `--loader`.

```bash
uv run ifdata.py -l
```

### Analytics (Modeling)

Após a carga, a camada de analytics modela os dados em um Star Schema para Business Intelligence usando dbt. Use a flag `-a` ou `--analytics`.

```bash
uv run ifdata.py -a
```

### dbt standalone com uv

Também é possível executar apenas a camada analytics sem chamar o pipeline:

```bash
cd src/bacen_ifdata/data_analytics
uv run --env-file ../../../.env dbt build
```

Execução seletiva de modelos e testes:

```bash
uv run --env-file ../../../.env dbt run -s view_resumo_financeiro_relatorios
uv run --env-file ../../../.env dbt test -s view_resumo_financeiro_relatorios
```

### Execução Padrão

Se nenhum argumento for fornecido, o pipeline executará as etapas de limpeza e transformação por padrão:

```bash
uv run ifdata.py
```

## Arquitetura do Sistema

Para informações detalhadas sobre a arquitetura do projeto, padrões de design utilizados, estrutura de diretórios e guia de contribuição, consulte a [documentação de arquitetura](docs/ARCHITECTURE.md).

Para entender o modelo de dados e o processo de transformação (Bronze -> Gold), veja a [documentação do pipeline](docs/DATA_PIPELINE.md).

## Desafios e Aprendizados

- **Desafio: Construção de um Pipeline de Dados de Ponta a Ponta**
  - **Problema:** As informações financeiras do Bacen, apesar de públicas, não são disponibilizadas através de uma API. Elas estão "presas" em um portal web que exige navegação manual e os arquivos para download estão em um formato inconsistente e "sujo". Para realizar qualquer análise séria e replicável, era necessário um sistema que superasse essas barreiras.
  - **Solução:** Projetei e implementei um pipeline de dados em quatro etapas (ETL):
        1. **Extração (Extract):** Um scraper automatizado com Selenium que simula a interação humana com o portal IF.data, navegando pelos menus e realizando o download sistemático de todos os relatórios necessários.
        2. **Limpeza (Clean):** Um módulo de pré-processamento que recebe os arquivos brutos e corrige a formatação não-padrão.
        3. **Transformação (Transform):** Um módulo que estrutura os dados limpos usando **Polars**, aplicando schemas de dados com **Pydantic** para garantir a consistência e o formato correto para análise.
        4. **Carga (Load):** Um módulo que carrega os dados transformados em um banco de dados **DuckDB**, criando tabelas otimizadas para consultas analíticas rápidas.
  - **Aprendizado:** Este projeto foi um exercício prático completo de **Engenharia de Dados (ETL - Extract, Transform, Load)**. Aprendi a decompor um problema complexo em etapas lógicas, selecionar as ferramentas adequadas para cada fase (Selenium, Polars, DuckDB) e a construir um fluxo de trabalho automatizado e confiável. O resultado final não é apenas um conjunto de dados, mas um **sistema replicável que transforma uma fonte de dados manual e não confiável em um ativo de informação pronto para análise**.

- **Desafio: Parsing de CSVs Não-Padronizados**
  - **Problema:** Os arquivos CSV disponibilizados pelo Bacen não seguem o padrão convencional. Eles incluem múltiplos cabeçalhos, linhas de resumo e agrupamentos de dados dentro do mesmo arquivo, tornando a importação direta com bibliotecas padrão inviável.
  - **Solução:** Desenvolvi um script de processamento em Python que lê cada arquivo linha por linha. Utilizando lógica condicional, o script identifica e ignora os cabeçalhos secundários e as linhas de resumo. Ele localiza o cabeçalho principal correto e extrai apenas as linhas de dados pertencentes às instituições financeiras, reescrevendo um novo arquivo CSV limpo e bem formatado.
  - **Aprendizado:** Este desafio aprofundou minhas habilidades em manipulação de arquivos e parsing de texto em baixo nível. Aprendi a importância de não confiar cegamente em formatos de arquivo e a desenvolver soluções robustas para lidar com dados sujos e inconsistentes, uma habilidade fundamental em qualquer projeto de engenharia ou ciência de dados.

- **Desafio: Modelagem Dimensional para BI a Partir de Dados Heterogêneos**
  - **Problema:** Com os dados já carregados no DuckDB (camada Silver), o próximo desafio era transformá-los em um formato adequado para análise de Business Intelligence. Os dados Silver, embora limpos, apresentavam diversos obstáculos para análises transversais:
    - **Fragmentação por tipo de instituição:** Ativos, passivos e resultados estavam em tabelas separadas por tipo (Conglomerados Prudenciais, Financeiros, Instituições Individuais), impossibilitando comparações diretas entre o sistema financeiro como um todo.
    - **Ausência de chaves padronizadas:** Não existiam chaves surrogadas ou dimensões compartilhadas; cada tabela operava de forma isolada.
    - **Inconsistência de schemas entre períodos:** Relatórios de diferentes épocas possuíam estruturas distintas (colunas extras ou ausentes), exigindo tratamento especial para unificação temporal.
    - **Dados desnormalizados e repetidos:** Informações de instituições (nome, código, segmento) eram replicadas em cada tabela de fato, gerando redundância e risco de inconsistência.
  - **Solução:** Projetei e implementei um **Star Schema (Esquema Estrela)** usando **dbt** sobre DuckDB, criando uma camada Gold analítica:
    1. **Dimensões unificadas (`dim_instituicao`):** Consolidei instituições de 3 fontes distintas em uma única dimensão com chave surrogada (`MD5`), permitindo análises transversais independentes do tipo de instituição.
    2. **Dimensão de tempo (`dim_tempo`):** Criei uma dimensão temporal com chave numérica (`YYYYMMDD`), extraindo ano, trimestre e mês para facilitar filtros e agregações sem funções de data complexas.
    3. **Fatos compostos (`fato_balanco_patrimonial`):** Unifiquei Ativos e Passivos via `FULL OUTER JOIN`, utilizando `COALESCE` para resiliência contra dados ausentes, consolidando o balanço patrimonial completo em uma única tabela.
    4. **Dimensões estáticas via Seeds:** Mapeei categorias de crédito, risco e localização como arquivos CSV (Seeds do dbt), garantindo consistência e versionamento dessas tabelas de referência.
  - **Aprendizado:** Este desafio consolidou minha experiência em **modelagem dimensional (Kimball)** e no uso de **dbt** como ferramenta de transformação analítica. Aprendi que a construção de um Data Warehouse eficiente não se resume a mover dados — exige decisões conscientes sobre granularidade, unificação de entidades e design de chaves. A separação clara entre Silver (dados operacionais) e Gold (dados analíticos) provou ser essencial para manter a rastreabilidade e permitir reprocessamento sem impactar a ingestão.

## Autor

**Alexsander Lopes Camargos**

Engenheiro de dados e inteligência artificial focado em soluções de alta performance para o mercado financeiro.
Este projeto reflete meu interesse em automação de processos, engenharia de dados e análise financeira.

Fique à vontade para entrar em contato para discussões técnicas, sugestões ou oportunidades:

[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/alexcamargos/)
[![Email](https://img.shields.io/badge/Email-D14836?style=for-the-badge&logo=gmail&logoColor=white)](mailto:alcamargos@vivaldi.net)

## Licença

Este projeto está sob a licença [MIT](LICENSE).
