ifdata-bcb 0.1.0__tar.gz

ifdata_bcb-0.1.0/.gitattributes

@@ -0,0 +1,59 @@
+# Git attributes for consistent line endings across platforms
+# See: https://git-scm.com/docs/gitattributes
+
+# Auto detect text files and normalize line endings to LF in the repository
+* text=auto
+
+# Source code files - enforce LF in repository, CRLF on checkout for Windows
+*.py text eol=lf
+*.pyx text eol=lf
+*.pxd text eol=lf
+*.pyi text eol=lf
+
+# Configuration files - enforce LF
+*.json text eol=lf
+*.toml text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.ini text eol=lf
+*.cfg text eol=lf
+
+# Documentation - enforce LF
+*.md text eol=lf
+*.rst text eol=lf
+*.txt text eol=lf
+
+# Jupyter notebooks - enforce LF
+*.ipynb text eol=lf
+
+# Shell scripts - enforce LF (must use LF even on Windows)
+*.sh text eol=lf
+*.bash text eol=lf
+
+# Windows scripts - enforce CRLF
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# Data files - treat as binary (no line ending conversion)
+*.parquet binary
+*.csv binary
+*.xlsx binary
+*.db binary
+*.sqlite binary
+
+# Image files - binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.svg binary
+
+# Archive files - binary
+*.zip binary
+*.tar binary
+*.gz binary
+*.7z binary
+*.rar binary
+

ifdata_bcb-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,49 @@
+name: Bug Report
+description: Reportar um problema ou comportamento inesperado
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Descricao do bug
+      description: Descreva o que aconteceu e o que voce esperava que acontecesse.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Como reproduzir
+      description: Passos ou codigo minimo para reproduzir o problema.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: error
+    attributes:
+      label: Mensagem de erro
+      description: Cole o traceback ou mensagem de erro, se houver.
+      render: shell
+  - type: input
+    id: version
+    attributes:
+      label: Versao do ifdata-bcb
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Sistema operacional
+      options:
+        - Windows
+        - Linux
+        - macOS
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Versao do Python
+      placeholder: "3.12"
+    validations:
+      required: true

ifdata_bcb-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature Request
+description: Sugerir uma nova funcionalidade
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problema
+      description: Que problema essa feature resolveria?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Solucao proposta
+      description: Como voce imagina que a API ou interface funcionaria?
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternativas consideradas
+      description: Voce tentou algum workaround ou abordagem alternativa?

ifdata_bcb-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+## O que muda
+
+<!-- Descreva brevemente o que esse PR faz -->
+
+## Tipo de mudanca
+
+- [ ] Bug fix
+- [ ] Nova feature
+- [ ] Refatoracao
+- [ ] Documentacao
+- [ ] Outro: <!-- descreva -->
+
+## Checklist
+
+- [ ] Testes passando (`uv run pytest tests/ -v`)
+- [ ] Linter passando (`uvx ruff check .`)
+- [ ] Documentacao atualizada (se aplicavel)

ifdata_bcb-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v7
+      - run: uvx ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run --frozen pytest tests/ -v

ifdata_bcb-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

ifdata_bcb-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python
+.venv
+__pycache__
+*egg-info
+
+# Temp Folders
+temp
+
+# Agents
+CLAUDE.md
+.claude/

ifdata_bcb-0.1.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Project Changelog
+
+## [2026-03-15 03:00]
+
+### Fixed
+- `NormalizedDates` agora valida range de mes (1-12), rejeitando inputs como `202413` ou `202400` que antes eram aceitos silenciosamente e resultavam em queries vazias sem erro informativo
+  - Eliminada duplicacao de parsing: validator agora delega para `normalize_date_to_int()` (fonte unica de verdade para conversao de datas)
+- String de ano puro (`"2024"`) agora levanta `InvalidDateFormatError` em vez de ser interpretada como YYYYMM=2024 (ano 20, mes 24)
+- Parametro `cadastro` com colunas invalidas agora levanta `InvalidScopeError` mesmo quando o resultado da query e vazio
+  - Validacao movida para o inicio de `read()` (antes do query), garantindo feedback imediato independente dos dados
+
+## [2026-03-15 02:12]
+
+### Added
+- Parametro `cadastro` em `cosif.read()` e `ifdata.read()` para enriquecer dados financeiros com atributos cadastrais inline (ex: `cadastro=["TCB", "SEGMENTO", "UF"]`)
+  - Elimina o pattern manual de ler cadastro separado e fazer merge por CNPJ
+  - Alinhamento temporal automatico: dados mensais COSIF recebem cadastro do trimestre mais recente via `merge_asof` backward-looking
+  - Dados trimestrais IFDATA fazem merge exato por DATA + CNPJ_8
+  - Colunas cadastrais invalidas levantam `InvalidScopeError` (consistente com hierarquia de excecoes da lib)
+- `openpyxl` como dev dependency para exportacao Excel em scripts
+
+## [2026-03-13 19:48]
+
+Refatoracao significativa focada em validacao com Pydantic, configuracao centralizada, e melhoria da resolucao de entidades no IFDATA.
+
+Correcao de 6 bugs de usabilidade nas APIs publicas e flexibilizacao do Cadastro.
+
+### Fixed
+- Filtros de `conta`, `segmento`, `relatorio` agora sao accent-insensitive (`'Lucro Liquido'` funciona igual a `'Lucro Liquido'` com acento)
+  - `_build_string_condition` aceita `accent_insensitive=True` usando `strip_accents()` do DuckDB
+  - `list_accounts()` do COSIF e IFDATA tambem usam accent-insensitive no LIKE
+- DataFrames vazios agora retornam colunas de apresentacao (DATA, INSTITUICAO) em vez de nomes de storage (DATA_BASE, NomeInstituicao)
+- `cosif.read()` nao retorna mais linhas duplicadas causadas pelo campo DOCUMENTO (balancete vs semestral)
+  - `_finalize_read` base agora chama `drop_duplicates()` apos mapeamento de colunas
+- Parametro `columns` aceita nomes de apresentacao (DATA, VALOR) alem de nomes de storage (DATA_BASE, SALDO)
+  - Novo metodo `_translate_columns()` no BaseExplorer traduz antes de passar ao DuckDB
+- `search('')` retorna DataFrame vazio sem warning do thefuzz
+- `search(limit=0)` e `search(limit=-1)` agora levantam `ValueError`
+
+### Added
+- `domain/validation.py`: Validadores Pydantic para datas, CNPJs, instituicoes e contas (`NormalizedDates`, `ValidatedCnpj8`, `InstitutionList`, `AccountList`)
+- `infra/paths.py`: Utilitarios `ensure_dir` e `temp_dir` para gerenciamento seguro de diretorios temporarios
+- `domain/exceptions.py`: Nova excecao `DataProcessingError` para falhas de processamento de fontes
+- `infra/config.py`: Classe `Settings` baseada em `pydantic-settings` substituindo funcoes avulsas de configuracao
+- `IFDATAExplorer`: Novos metodos de introspeccao (`list_accounts`, `list_institutions`, `list_reporters`, `list_reports`) e validacao de escopo
+- `EntityLookup`: Resolucao canonica de entidades com suporte a CodInst e heuristica para caches legados
+- Suite de testes formal em `tests/` com 11 modulos cobrindo core, domain, infra e providers
+- `pyproject.toml`: Dependencias `pydantic` e `pydantic-settings`; grupo dev com `pytest`; configuracao pytest
+
+### Changed
+- `cadastro.read()`, `cadastro.info()`, `cadastro.get_conglomerate_members()`: `start` agora e opcional (default: ultimo periodo disponivel)
+  - Novo metodo `_resolve_start()` no CadastroExplorer
+  - Novo metodo `_get_latest_period()` no BaseExplorer
+- `BaseExplorer`: Validacao de inputs delegada para modelos Pydantic em vez de regex manual; novo metodo `_align_to_quarter_end`
+- `BaseCollector`: Downloads isolados em `temp_dir` context manager; `_normalize_text_fields` agora opera em todas as colunas object
+- `BaseCollector._download_period`: Assinatura atualizada para receber `work_dir` explicitamente
+- `infra/log.py`: Logging de arquivo usa `get_settings().logs_path` com fallback silencioso para ambientes restritos
+- `infra/__init__.py`: Exports atualizados (`Settings`, `get_settings`, `ensure_dir`, `temp_dir` substituem `get_cache_path`)
+- `IFDATAExplorer._add_institution_names`: Usa `get_canonical_names_for_cnpjs` para nomes canonicos
+- Documentacao atualizada em todos os docs para refletir nova arquitetura (README, getting-started, internals, providers)
+- `notebooks/quickstart.ipynb`: Exemplos atualizados para nova API
+
+### Removed
+- `CHANGELOG.md` anterior (substituido por esta versao atualizada)
+- `EntityLookup._build_entity_union_sql`: Substituido por resolucao canonica via cadastro com CodInst
+- `get_cache_path` e `get_logs_path`: Substituidos pela classe `Settings`
+- Lista fixa de colunas de texto em `_normalize_text_fields`

ifdata_bcb-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Codigo de Conduta - Contributor Covenant
+
+## Nosso Compromisso
+
+No interesse de promover um ambiente aberto e acolhedor, nos, como contribuidores e mantenedores, nos comprometemos a tornar a participacao em nosso projeto e em nossa comunidade uma experiencia livre de assedio para todos, independentemente de idade, tamanho corporal, deficiencia, etnia, caracteristicas sexuais, identidade e expressao de genero, nivel de experiencia, educacao, status socioeconomico, nacionalidade, aparencia pessoal, raca, religiao ou identidade e orientacao sexual.
+
+## Nossos Padroes
+
+Exemplos de comportamento que contribuem para criar um ambiente positivo:
+
+- Usar linguagem acolhedora e inclusiva
+- Respeitar pontos de vista e experiencias diferentes
+- Aceitar criticas construtivas com graca
+- Focar no que e melhor para a comunidade
+- Mostrar empatia com outros membros da comunidade
+
+Exemplos de comportamento inaceitavel:
+
+- Uso de linguagem ou imagens sexualizadas e atencao ou avancos sexuais indesejados
+- Trolling, comentarios insultuosos/depreciativos e ataques pessoais ou politicos
+- Assedio publico ou privado
+- Publicar informacoes privadas de terceiros sem permissao explicita
+- Outra conduta que poderia ser considerada inapropriada em um ambiente profissional
+
+## Nossas Responsabilidades
+
+Os mantenedores do projeto sao responsaveis por esclarecer os padroes de comportamento aceitavel e devem tomar acoes corretivas apropriadas e justas em resposta a qualquer instancia de comportamento inaceitavel.
+
+## Escopo
+
+Este Codigo de Conduta se aplica em todos os espacos do projeto e tambem quando um individuo esta representando o projeto ou sua comunidade em espacos publicos.
+
+## Aplicacao
+
+Instancias de comportamento abusivo, de assedio ou de outra forma inaceitavel podem ser reportadas entrando em contato com o mantenedor do projeto. Todas as reclamacoes serao revisadas e investigadas e resultarao em uma resposta considerada necessaria e apropriada as circunstancias.
+
+## Atribuicao
+
+Este Codigo de Conduta e adaptado do [Contributor Covenant](https://www.contributor-covenant.org), versao 2.1.

ifdata_bcb-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contribuindo com ifdata-bcb
+
+Obrigado pelo interesse em contribuir! Este guia explica como participar do projeto.
+
+## Primeiros Passos
+
+### Requisitos
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/) como gerenciador de pacotes
+
+### Setup local
+
+```bash
+# Clone o repositorio
+git clone https://github.com/enzoomoreira/ifdata-bcb.git
+cd ifdata-bcb
+
+# Instale dependencias
+uv sync
+
+# Rode os testes
+uv run pytest tests/ -v
+```
+
+## Como Contribuir
+
+### Reportando Bugs
+
+Abra uma [issue](https://github.com/enzoomoreira/ifdata-bcb/issues) com:
+
+- Descricao clara do problema
+- Passos para reproduzir
+- Comportamento esperado vs. observado
+- Versao do Python e do ifdata-bcb
+- Sistema operacional
+
+### Sugerindo Features
+
+Abra uma [issue](https://github.com/enzoomoreira/ifdata-bcb/issues) descrevendo:
+
+- O problema que a feature resolve
+- Como voce imagina a API/interface
+- Exemplos de uso
+
+### Enviando Pull Requests
+
+1. Fork o repositorio
+2. Crie uma branch a partir de `master` (`git checkout -b feat/minha-feature`)
+3. Faca suas alteracoes
+4. Rode os testes (`uv run pytest tests/ -v`)
+5. Rode o linter (`uvx ruff check .`)
+6. Commit seguindo [Conventional Commits](https://www.conventionalcommits.org/):
+   - `feat:` nova funcionalidade
+   - `fix:` correcao de bug
+   - `docs:` documentacao
+   - `refactor:` refatoracao sem mudanca de comportamento
+   - `test:` adicao ou correcao de testes
+7. Abra o PR contra `master`
+
+## Estilo de Codigo
+
+- **Formatacao**: ruff format
+- **Linting**: ruff check
+- **Type hints**: obrigatorios em todas as funcoes
+- **Docstrings**: apenas em API publica ou comportamento nao-obvio
+- **Encoding**: UTF-8, sem emojis
+
+## Estrutura do Projeto
+
+```
+src/ifdata_bcb/
+  core/        # Logica central (BaseExplorer, EntityLookup, Constants)
+  domain/      # Modelos, excecoes, validacao
+  infra/       # Infraestrutura (paths, config, QueryEngine)
+  providers/   # Provedores de dados (cosif, ifdata)
+  utils/       # Utilitarios
+  ui/          # Componentes de interface
+```
+
+## Testes
+
+```bash
+# Rodar todos os testes
+uv run pytest tests/ -v
+
+# Rodar um modulo especifico
+uv run pytest tests/test_validation.py -v
+```
+
+Os testes usam dados reais do BCB. Algumas execucoes podem ser lentas na primeira vez por conta da coleta de dados.
+
+## Duvidas?
+
+Abra uma [issue](https://github.com/enzoomoreira/ifdata-bcb/issues) com sua pergunta. Ficaremos felizes em ajudar.

ifdata_bcb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enzo Moreira
+
+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.

ifdata_bcb-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: ifdata-bcb
+Version: 0.1.0
+Summary: Analise de dados financeiros do Banco Central do Brasil (BCB)
+Project-URL: Homepage, https://github.com/enzoomoreira/ifdata-bcb
+Project-URL: Repository, https://github.com/enzoomoreira/ifdata-bcb
+Project-URL: Documentation, https://github.com/enzoomoreira/ifdata-bcb/tree/master/docs
+Project-URL: Bug Tracker, https://github.com/enzoomoreira/ifdata-bcb/issues
+Project-URL: Changelog, https://github.com/enzoomoreira/ifdata-bcb/blob/master/CHANGELOG.md
+License: MIT License
+        
+        Copyright (c) 2026 Enzo Moreira
+        
+        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.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: duckdb>=1.4.4
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: platformdirs>=3.0.0
+Requires-Dist: pyarrow>=10.0.0
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: requests>=2.28.0
+Requires-Dist: rich>=14.3.1
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: thefuzz[speedup]>=0.22.0
+Description-Content-Type: text/markdown
+
+# ifdata-bcb
+
+[![PyPI version](https://img.shields.io/pypi/v/ifdata-bcb)](https://pypi.org/project/ifdata-bcb/)
+[![Python](https://img.shields.io/pypi/pyversions/ifdata-bcb)](https://pypi.org/project/ifdata-bcb/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/enzoomoreira/ifdata-bcb/actions/workflows/ci.yml/badge.svg)](https://github.com/enzoomoreira/ifdata-bcb/actions/workflows/ci.yml)
+
+Coleta e analise de dados contabeis e financeiros de instituicoes financeiras brasileiras. Dados publicos do Banco Central do Brasil.
+
+| Fonte | Modulo | Dados | Periodicidade |
+|-------|--------|-------|---------------|
+| COSIF | `bcb.cosif` | Plano contabil (individual e prudencial) | Mensal |
+| IFDATA | `bcb.ifdata` | Informacoes financeiras | Trimestral |
+| Cadastro | `bcb.cadastro` | Metadados de instituicoes (segmento, conglomerado) | Trimestral |
+
+## Instalacao
+
+```bash
+uv add ifdata-bcb
+```
+
+Requer Python 3.12+.
+
+## Uso Rapido
+
+```python
+import ifdata_bcb as bcb
+
+# 1. Coletar dados (primeira vez ou atualizar)
+bcb.cadastro.collect('2024-01', '2024-12')
+bcb.cosif.collect('2024-01', '2024-12')
+bcb.ifdata.collect('2024-01', '2024-12')
+
+# 2. Buscar instituicao por nome (fuzzy matching)
+bcb.search('Itau')
+bcb.search('Bradesco')
+#    CNPJ_8                       INSTITUICAO  SITUACAO  FONTES  SCORE
+# 0  60872504  ITAU UNIBANCO HOLDING S.A.           A    ...    100
+# Quando possivel, prioriza resultados com dados disponiveis em FONTES.
+
+# 3. Ler dados usando CNPJ de 8 digitos
+# COSIF/IFDATA: instituicao e start sao OBRIGATORIOS
+# start sozinho = data unica; start + end = range
+
+# COSIF (escopo=None busca em todos os escopos)
+df = bcb.cosif.read(
+    instituicao='60872504',
+    start='2024-12',
+    conta='TOTAL GERAL DO ATIVO',
+    escopo='prudencial'
+)
+
+# IFDATA
+df = bcb.ifdata.read(
+    instituicao='60872504',
+    start='2024-01',
+    end='2024-12',
+    conta='Lucro Liquido'
+)
+
+# Enriquecer com dados cadastrais inline
+df = bcb.ifdata.read(
+    instituicao='60872504',
+    start='2024-01',
+    end='2024-12',
+    escopo='prudencial',
+    cadastro=['TCB', 'SEGMENTO']
+)
+
+# Cadastro
+info = bcb.cadastro.info('60872504', start='2024-12')
+
+# Cadastro tambem pode ser filtrado sem instituicao
+df = bcb.cadastro.read(start='2024-12', segmento='Banco Multiplo')
+
+# 4. Listar contas e instituicoes disponiveis
+bcb.cosif.list_accounts(escopo='prudencial')
+bcb.cosif.list_institutions(escopo='prudencial')
+
+# 5. SQL direto com DuckDB (para analises avancadas)
+from ifdata_bcb.infra import QueryEngine
+
+qe = QueryEngine()
+df = qe.sql("""
+    SELECT CNPJ_8, NOME_INSTITUICAO, SALDO
+    FROM '{cache}/cosif/prudencial/*.parquet'
+    WHERE DATA_BASE = 202412 AND NOME_CONTA = 'TOTAL GERAL DO ATIVO'
+    ORDER BY SALDO DESC
+    LIMIT 10
+""")
+```
+
+## Documentacao
+
+### Guias de Uso
+
+- **[getting-started.md](docs/getting-started.md)** - Instalacao e primeiro uso
+
+### Fontes de Dados
+
+- **[cosif.md](docs/providers/cosif.md)** - Plano contabil (individual/prudencial)
+- **[ifdata.md](docs/providers/ifdata.md)** - Informacoes financeiras trimestrais
+- **[cadastro.md](docs/providers/cadastro.md)** - Metadados de instituicoes
+
+### Uso Avancado
+
+- **[sql-queries.md](docs/advanced/sql-queries.md)** - Queries SQL com DuckDB
+- **[extending.md](docs/advanced/extending.md)** - Como criar novos providers
+
+### Arquitetura Interna
+
+- **[architecture.md](docs/internals/architecture.md)** - Visao geral da arquitetura
+- **[core.md](docs/internals/core.md)** - BaseExplorer, EntityLookup, Constants
+- **[domain.md](docs/internals/domain.md)** - Exceptions, Models, Types, Validation
+- **[infra.md](docs/internals/infra.md)** - Settings, QueryEngine, DataManager
+- **[providers.md](docs/internals/providers.md)** - BaseCollector, Explorers
+
+## Estrutura de Dados
+
+```
+{cache}/
+  cosif/
+    individual/       # cosif_ind_YYYYMM.parquet
+    prudencial/       # cosif_prud_YYYYMM.parquet
+  ifdata/
+    valores/          # ifdata_val_YYYYMM.parquet
+    cadastro/         # ifdata_cad_YYYYMM.parquet
+```
+
+O diretorio de cache varia por sistema:
+
+| Sistema | Caminho |
+|---------|---------|
+| Windows | `%LOCALAPPDATA%\py-bacen\Cache\` |
+| Linux | `~/.cache/py-bacen/` |
+| macOS | `~/Library/Caches/py-bacen/` |
+
+Customizavel via variavel de ambiente `BACEN_DATA_DIR`.
+
+## API Publica
+
+### Modulo Principal
+
+```python
+import ifdata_bcb as bcb
+
+# Explorers (lazy loading)
+bcb.cosif       # COSIFExplorer
+bcb.ifdata      # IFDATAExplorer
+bcb.cadastro    # CadastroExplorer
+
+# Funcoes
+bcb.search(termo, limit=10)  # Busca instituicoes por nome
+
+# Exceptions
+bcb.BacenAnalysisError       # Classe base para todos os erros
+bcb.DataUnavailableError     # Dados nao disponiveis
+```
+
+### Metodos dos Explorers
+
+Todos os explorers possuem:
+
+| Metodo | Descricao |
+|--------|-----------|
+| `collect(start, end, ...)` | Coleta dados do BCB |
+| `read(instituicao, start, ...)` | Le dados com filtros |
+| `list_periods()` | Periodos disponiveis |
+| `has_data()` | Verifica se tem dados |
+
+Metodos especificos:
+
+| Explorer | Metodos Adicionais |
+|----------|-------------------|
+| `cosif` | `list_accounts()`, `list_institutions()` |
+| `ifdata` | `list_accounts()`, `list_institutions()`, `list_reporters()`, `list_reports()` |
+| `cadastro` | `info()`, `list_segmentos()`, `list_ufs()`, `get_conglomerate_members()` |
+
+## Limitacoes Conhecidas
+
+- **Dependencia de APIs do BCB**: a coleta depende da disponibilidade dos endpoints publicos do Banco Central. Se a API estiver fora do ar ou mudar seu schema, a coleta pode falhar.
+- **Dados historicos**: nem todos os periodos estao disponiveis para todas as fontes. Use `list_periods()` para verificar disponibilidade.
+- **Primeira coleta lenta**: a coleta inicial de dados pode demorar dependendo do range de datas solicitado, pois faz requisicoes HTTP sequenciais ao BCB.
+- **Cache sem invalidacao automatica**: dados coletados ficam em cache local indefinidamente. Para atualizar, colete novamente o periodo desejado.
+- **Sem suporte offline**: a coleta requer conexao com a internet. A leitura funciona offline se os dados ja estiverem em cache.
+
+## Contribuindo
+
+Contribuicoes sao bem-vindas! Consulte o [guia de contribuicao](CONTRIBUTING.md) para detalhes sobre como participar.
+
+## Licenca
+
+Distribuido sob a licenca MIT. Veja [LICENSE](LICENSE) para mais informacoes.