## https://sploitus.com/exploit?id=6DB3A131-0E33-5C3C-A04C-C64B2A20E158
# PoC — Inteligência Tributária de Palmas-TO
[](https://github.com/DavidNadlerPrata/poc-inteligencia-tributaria-palmas/actions/workflows/ci.yml)
[](https://www.python.org/)
[](tests/)
[](tests/)
Prova de conceito do **Projeto Integrador do Eixo II** — Opção D: predição de
inadimplência e priorização da cobrança da dÃvida ativa do municÃpio de
Palmas-TO.
Bacharelado Interdisciplinar em Inteligência Artificial — UFT
Coordenação: Prof. Dr. David Nadler Prata
---
## O que este PoC é
Uma **referência executável** do caminho completo que cada equipe vai percorrer
ao longo do semestre: da coleta na API pública da Prefeitura até a auditoria de
justiça algorÃtmica, passando por ETL, banco relacional, dois modelos de ML e um
painel de demonstração.
Não é a solução pronta a ser copiada. É o esqueleto que mostra **como as peças
se encaixam** — e, principalmente, como lidar honestamente com o obstáculo que
toda equipe vai encontrar na Sprint 2: os dados individuais de dÃvida ativa não
são públicos.
## Como executar
```bash
pip install -r requirements.txt
```
```bash
python executar_poc.py
```
O pipeline roda de ponta a ponta em cerca de um minuto: coleta (ou usa cache),
gera a carteira, monta o banco, treina os dois modelos, produz a fila de
cobrança e roda a auditoria de fairness.
Para forçar nova coleta na API da Prefeitura:
```bash
python executar_poc.py --coletar
```
Sem internet, use os dados locais:
```bash
python executar_poc.py --sem-rede
```
Depois, o painel:
```bash
streamlit run app/painel.py
```
A suÃte de testes:
```bash
python -m pytest
```
O notebook de EDA da Sprint 2 (já vem executado; para regerá-lo do script):
```bash
python notebooks/gerar_eda.py
```
---
## A questão dos dados — leia antes de tudo
O projeto pede predição de inadimplência **por contribuinte**. Esse dado é
pessoal, protegido pela LGPD, e **não está publicado**. Nenhuma API municipal
expõe quem deve quanto — e nem deveria.
O que é realmente público, e o que este PoC **coleta de verdade**, são os
agregados de arrecadação: valor por código de receita, órgão e mês. São 17.507
registros de 2025, obtidos da API do portal de transparência.
Para a camada individual, o PoC usa uma **carteira sintética calibrada** pelos
agregados oficiais da Sefin (R$ 363 milhões de IPTU em dÃvida ativa, 111.252
imóveis tributáveis). É o procedimento padrão em prova de conceito sobre domÃnio
sensÃvel, e traz duas vantagens: nenhum dado pessoal é tratado, e a estrutura de
colunas reproduz a de um cadastro imobiliário real — trocar o gerador pela
extração real exige apenas reapontar a origem, sem tocar no resto do pipeline.
**Isso não é uma limitação a esconder na defesa; é um achado a apresentar.** A
banca vai valorizar mais a equipe que mapeia com precisão o que é público, o que
não é e por quê, do que a que finge ter dados que ninguém tem.
Detalhes em [`src/sintetico.py`](src/sintetico.py) e em
[`docs/RIA.md`](docs/RIA.md), seção 1.
---
## Arquitetura
```
API REST da Prefeitura gerador calibrado
(sgreceitas/listar — REAL) (carteira SINTÉTICA)
│ │
└────────────┬───────────────────┘
â–¼
ETL (src/etl.py)
limpeza · normalização 3FN · carga
│
â–¼
SQLite inteligencia_tributaria.db
setor_urbano ─ O artefato `notebook-verificacao-amostra` publicado pelo CI roda sobre essa
> amostra: seus números **não** batem com o texto do notebook, que descreve a
> base completa. Ele serve para confirmar que o código executa, não como
> relatório de EDA.
Rodando as mesmas verificações localmente:
```bash
python -m ruff check .
python -m pytest --cov=src
python executar_poc.py --sem-rede
```
---
## O que cada equipe deve fazer a partir daqui
Este PoC é ponto de partida, não linha de chegada. Caminhos de evolução:
1. **Buscar o dado real.** Formalizar contato com a Sefin. Um convênio, mesmo
com dados agregados por setor, muda o patamar do projeto.
2. **Enriquecer com o IBGE.** Cruzar setor censitário real com os dados
territoriais — substitui o proxy grosseiro de renda por informação de campo.
3. **Explorar outras fontes.** O portal traz também contratos, licitações,
despesas e folha. Há projeto ali.
4. **Aprofundar a modelagem.** Comparar algoritmos com justificativa empÃrica,
calibrar limiares por custo real de diligência, testar séries temporais.
5. **Melhorar a explicação.** Trocar importância global por SHAP local, que
responde "por que eu?" em vez de "o que o modelo olha em média".
6. **Resolver a pendência do achado 2 da EDA.** A receita de dezembro é quase
3× a dos demais meses e ainda não sabemos por quê. Abrir por código de
receita e por órgão é tarefa concreta e de resultado rápido.
7. **Ampliar os testes.** A suÃte cobre as regras crÃticas e 90% de `src/`, mas
não o painel Streamlit. O módulo menos coberto é `coleta.py` (70%), onde
faltam os caminhos de rede — testáveis com um servidor HTTP falso.
---
## Ética na coleta
O PoC segue as diretrizes da seção 11 do plano de ensino: usa apenas fonte
oficial e verificável, aplica pausa de 0,3 s entre requisições, não coleta dado
pessoal identificável, documenta origem e data de coleta, e exclui os
beneficiários do IPTU Social de toda ação preditiva de cobrança.
## Requisitos
Python 3.11+ · pandas · scikit-learn · streamlit · plotly · requests · joblib
---
*PoC acadêmico. Os resultados demonstram o funcionamento do sistema, não a
situação fiscal real do municÃpio de Palmas.*