SQUAD: LegoDados - Projeto de Inteligência Legislativa & Engenharia de dados

Este repositório contém o Projeto Integrador da pós-graduação em Engenharia de Dados e Inteligência Artificial. O objetivo é desenvolver um pipeline de dados completo (ETL) que automatiza a captura, organização e análise de dados da API de Dados Abertos da Câmara dos Deputados.

Propósito do Projeto:

Transformar o oceano de dados brutos do legislativo brasileiro em sinais acionáveis para consultorias de relações governamentais e empresas reguladas. O projeto visa substituir processos manuais e inconsistentes por uma arquitetura escalável que utiliza IA Generativa para classificação temática e resumos executivos.

Stack Tecnológica:

Arquitetura e Roadmap de Desenvolvimento:

O projeto está estruturado em cinco etapas principais. Abaixo está o status atual de desenvolvimento do que já foi mapeado e implementado:

Exploração e Extração (Ingestão) [CONCLUÍDO]

Desenvolvimento de scripts Python em src/extraction.py para consumo estruturado da API de Dados Abertos.
Extração modularizada através de extratores específicos: DeputadosExtractor, PartidosExtractor, ProposicoesExtractor e VotacoesExtractor.
Tratamento de paginação, resiliência contra erros de timeout e persistência do JSON bruto no diretório local data_raw/ (Camada Bronze).

Diagnóstico e Configuração [CONCLUÍDO]

Implementação de rotinas de validação inicial (src/diagnostico.py) disparadas antes da execução principal para garantir a integridade dos diretórios e conexões.
Centralização das configurações e segurança através de variáveis de ambiente gerenciadas em src/config.py e .env.

Transformação e Carga (ETL) [CONCLUÍDO]

Limpeza, padronização e processamento dos dados brutos utilizando Pandas (src/transformers.py).
Modelagem relacional transformando arquivos JSON em estruturas adequadas para tabelas Fato e Dimensão (ex: fato_proposicoes_autores, fato_votacoes, fato_votos).
Orquestração e execução da carga incremental em banco de dados PostgreSQL via SQLAlchemy (src/transformation.py).

Camada de Inteligência Artificial [CONCLUÍDO]

Estruturação da lógica em src/ai_layer.py para enriquecimento analítico inteligente de proposições parlamentares pendentes através da API da OpenAI.
Modo de Simulação (Dry Run): Implementação de estimativas financeiras automatizadas de consumo de tokens (Métricas de Custo Estimado em USD/BRL baseadas no modelo gpt-4o-mini) para validação prévia de lotes (Batch) antes do processamento real.
Resumo Executivo: Geração automática de resumos simplificados e acionáveis das proposições legislativas pendentes diretamente integrados à base de dados.
Classificação Temática (Etapa 5 - Caminho A): cada proposição é classificada por embeddings (text-embedding-3-small) + similaridade de cosseno contra um catálogo de temas de negócio, gravando tema, tema_score e data_tema em fato_proposicoes (src/classificacao_tematica.py).

Automação e Monitoramento [CONCLUÍDO]

Workflow no n8n (n8n/bussola_publica_ingestao_diaria.json) agendado para 06h diariamente (cron 0 6 * * *), executando o pipeline principal (main.py) via Execute Command.
Notificação automática por e-mail com o digest do dia: as 5 proposições mais relevantes das últimas 24h, já com tema (embeddings) e resumo executivo (GPT) — a IA chega ao produto final.
Tratamento de falha: ramo dedicado que dispara e-mail de alerta com o stderr caso o pipeline quebre, sem depender da memória do analista.
Passo a passo de importação e credenciais em n8n/GUIA_IMPORTACAO_n8n.md; decisões técnicas e prompts da IA em docs/Etapa5_Documentacao_Tecnica.md.

Visualização de Dados e Analytics (Power BI) [CONCLUÍDO]

Criação do layout e prototipagem de alta fidelidade das telas utilizando o Figma.
Conexão nativa do Power BI Desktop ao data warehouse (PostgreSQL) hospedado no Supabase.
Modelagem e relacionamentos Star Schema replicados no Power BI, com criação de medidas em DAX para contadores e distribuições.
Publicação do relatório no Power BI Service e disponibilização de link público para consumo.

Motivo das decisões técnicas:

Por que orquestrar main.py no n8n (Execute Command) em vez de reimplementar a ingestão em nós nativos?

A lógica de paginação, retry, validação e carga já está testada em Python. Reescrevê-la em nós HTTP do n8n duplicaria código e criaria duas fontes de verdade. O n8n entra como orquestrador e camada de notificação, não como ETL paralelo. O custo dessa escolha é que o n8n precisa rodar no mesmo host do repositório (VPS/Docker/local self-hosted) — documentado no guia.

Por que classificação por embeddings (Caminho A) e não pedir o tema direto à LLM?

Três motivos:
- custo — 1 embedding por ementa com text-embedding-3-small custa frações de centavo, muito abaixo de uma chamada de chat por proposição;
- consistência — a lista de ~11 temas é um catálogo fechado, então a similaridade de cosseno sempre escolhe um rótulo válido, enquanto a LLM poderia inventar categorias novas;
- auditabilidade — guardamos o tema_score, deixando a classificação transparente e com limiar ajustável (LIMIAR_TEMA).

Por que e-mail e não Telegram (nesta entrega) ?

E-mail é o canal mais simples de configurar, demonstrar e printar para a avaliação, e é o formato que o cliente corporativo da Bússola Pública já consome. O workflow é trivialmente extensível para Telegram (basta um nó Telegram em paralelo ao e-mail de sucesso).

Por que o digest mostra tema + resumo ?

Para a IA não ser decoração. O e-mail das 06h traz, para cada proposição priorizada, o tema (embeddings) e o resumo executivo (GPT). A IA aparece no produto final que chega ao cliente — exatamente o que o desafio cobra.

Controle de custo de IA:

Tanto (resumo) quanto (tema) do ai_layer.py sobem em DRY_RUN=true por padrão: estimam tokens e custo (USD/BRL) antes de gastar. Só com DRY_RUN=false há chamada real e gravação. Processamento é idempotente — pula o que já tem resumo_executivo/tema.

Por que o deploy público do Power BI não atualiza em tempo real com o n8n?

O link de compartilhamento web público (Embed to website) no plano gratuito do Power BI Service possui restrições de atualização automática para fontes cloud diretas via DirectQuery sem Gateway corporativo. Portanto, o painel online reflete os dados históricos estáticos da última publicação manual do arquivo .pbix. O pipeline no n8n popula o banco de dados Supabase em tempo real, mas o painel público web exige um reenvio do arquivo para refletir o estado mais recente.

Resolução de Problema Crítico: Conexão Power BI ↔ Supabase (Erro de SSL):

Durante a configuração inicial, o Power BI Desktop rejeitou a conexão criptografada com o PostgreSQL do Supabase, retornando um erro de handshake SSL.
Solução: Foi necessário baixar o certificado raiz do Supabase (prod-ca-2021.crt) e instalá-lo no Windows na pasta de Autoridades de Certificação Raiz Confiáveis (via certlm.msc). Isso permitiu que o driver ODBC/PostgreSQL do Power BI validasse a identidade do servidor e estabelecesse a conexão segura.

Prompts e Lógica da camada de IA:

Caminho B — Resumo Executivo (`src/ai_layer.py`)

Modelo: gpt-4o-mini (10x mais barato que o gpt-4o, qualidade adequada para resumos de 3 frases).

System prompt:

Você é um analista legislativo sênior da consultoria Bússola Pública.
Sua função é transformar ementas técnicas de proposições da Câmara dos Deputados
em resumos claros e acionáveis para executivos e áreas de relações governamentais.

Regras para o resumo:
- Máximo 3 frases objetivas
- Linguagem direta, sem jargão jurídico
- Estrutura: (1) O que propõe, (2) Quem/o que é impactado, (3) Ponto de atenção para empresas
- Se a ementa for muito técnica ou vaga, informe isso claramente
- Responda APENAS com o resumo, sem introduções como 'O resumo é:' ou 'Esta proposição...'

User prompt (template):

Proposição: {sigla_tipo} {numero}/{ano}

Ementa oficial:
{ementa}

Gere o resumo executivo:

O resumo gerado é gravado em fato_proposicoes.resumo_executivo (+ data_resumo), e um backup local em JSON é salvo em data/processed/.

Caminho A — Classificação Temática por Embeddings (`src/classificacao_tematica.py`)

Modelo: text-embedding-3-small (~$0.00002 / 1K tokens).

Gera o embedding da ementa de cada proposição pendente (tema IS NULL).

Gera, uma única vez por execução (com cache em memória), o embedding de cada um dos ~11 temas do catálogo de negócio — cada tema é descrito por uma frase rica em vocabulário, não só uma palavra:

Tema	Descrição (texto embedado)
Tecnologia e IA	Tecnologia, inteligência artificial, dados pessoais, internet, telecomunicações, inovação, startups, software, plataformas digitais e regulação de algoritmos.
Tributário	Tributos, impostos, reforma tributária, carga fiscal, ICMS, IRPF, isenções, incentivos fiscais e arrecadação.
Saúde	Saúde pública, SUS, medicamentos, planos de saúde, vigilância sanitária, hospitais, vacinas e profissionais de saúde.
Trabalho e Previdência	Direitos trabalhistas, CLT, emprego, salário mínimo, sindicatos, previdência social, aposentadoria e relações de trabalho.
Meio Ambiente	Meio ambiente, clima, licenciamento ambiental, desmatamento, saneamento, energia renovável, resíduos e sustentabilidade.
Economia e Finanças	Economia, mercado financeiro, bancos, crédito, juros, inflação, câmbio, investimentos e orçamento público.
Educação	Educação básica e superior, escolas, universidades, FIES, professores, currículo, financiamento educacional e ensino.
Segurança Pública	Segurança pública, polícia, crime, armas, código penal, sistema prisional e combate ao tráfico.
Agronegócio	Agronegócio, agricultura, pecuária, crédito rural, defensivos, exportação de commodities e produção no campo.
Infraestrutura e Transporte	Infraestrutura, rodovias, portos, aeroportos, mobilidade urbana, concessões, obras públicas e transporte.
Direitos e Cidadania	Direitos humanos, igualdade, direitos do consumidor, família, minorias, acesso à justiça e cidadania.

Calcula a similaridade de cosseno entre o embedding da ementa e o embedding de cada tema.
O tema de maior similaridade é a classificação; se o melhor score ficar abaixo do limiar LIMIAR_TEMA (padrão 0.20), a proposição recebe o tema "Outros".
Grava tema, tema_score e data_tema em fato_proposicoes e salva backup local em JSON.

Por que cosseno em vez de pedir o tema direto ao LLM?

Custo: 1 embedding por ementa é ordens de magnitude mais barato que uma chamada de chat por proposição.
Consistência: a lista de temas é fixa; um LLM generativo poderia inventar rótulos novos a cada execução. O cosseno sempre escolhe um tema do catálogo controlado.
Auditabilidade: o score fica salvo em tema_score, dando transparência à classificação.

Insights Extraídos do Dashboard (LegoDados)

Visualização das Telas do Painel

A análise do painel legislativo consolidado (com dados mapeados entre 01/06/2026 e 12/06/2026) gera diagnósticos acionáveis para consultorias de relações governamentais:

Predomínio Temático de "Segurança Pública" e "Saúde": Das 200 proposições classificadas por IA, o tema Saúde desponta com 39 projetos. Isso indica uma forte janela de oportunidade (ou risco regulatório) para empresas do setor monitorarem o Plenário.
Eficiência da IA no Filtro de Ruído: O alto volume de proposições em "Outros" (115) demonstra a precisão do modelo em isolar matérias administrativas ou protocolares, focando o esforço humano apenas no que é estratégico.
Concentração Política: A visualização por partido mostra que PL e PT dominam o volume de proposições, sendo os stakeholders centrais para qualquer estratégia de advocacy.
Detalhamento Executivo: O cruzamento direto entre o resumo gerado pela IA e a ementa original permite uma tomada de decisão rápida sem a necessidade de ler o documento íntegro da Câmara.

[IMPORTANTE] Observação sobre Atualização: O link de deploy (Power BI Web) reflete os dados da última publicação manual do arquivo .pbix. Embora o pipeline (Python + n8n) atualize o banco de dados diariamente, o painel público só apresentará os novos dados após o reenvio do arquivo para o Power BI Service.

Links do Painel

Protótipo do Layout (Figma): Dowload dos layouts
Painel Interativo (Power BI Web): Acesse o Dashboard Publicado
Arquivo Fonte do Projeto: Download do arquivo LegoDados_Relatorio_Legislativo.pbix

Evidências de Execução:

Recurso	Evidência Visual
DWH (30 Dias)
Email Digest
Camada de IA
Workflow n8n

O Table Editor do Supabase exige login (sem link público no plano Free); os prints acima + a Reference ID do projeto servem como evidência de acesso ao banco.

Modelo de Dados (DWH / Camada Relacional):

Para suportar as análises legislativas e o enriquecimento com Inteligência Artificial, os dados transformados foram estruturados em um modelo relacional (Fatos e Dimensões).

Tabelas de Dimensão (Dim):

dim_deputados

Armazena os dados cadastrais e identificadores únicos dos deputados federais.

Campo	Tipo	Restrição	Descrição
id_deputado	int8	Primary Key	Identificador único do deputado na API da Câmara.
nome	text	Nullable	Nome parlamentar do deputado.
sigla_partido	text	Nullable	Sigla do partido político atual.
sigla_uf	text	Nullable	Estado (Unidade da Federação) pelo qual foi eleito.
id_legislatura	int8	Nullable	Identificador da legislatura atual.
url_foto	text	Nullable	Link para a foto oficial do parlamentar.
uri	text	Nullable	Link do endpoint oficial do deputado na API.

dim_partidos

Dicionário de partidos políticos mapeados no pipeline.

Campo	Tipo	Restrição	Descrição
id_partido	int8	Primary Key	Identificador único do partido na API.
sigla	text	Nullable	Sigla oficial do partido político.
nome	text	Nullable	Nome completo do partido político.
uri	text	Nullable	Link do endpoint oficial do partido na API.

Tabelas de Fato (Fact):

fato_proposicoes

Entidade central de análise que armazena os textos, metadados e os enriquecimentos de IA (resumos executivos).

Campo	Tipo	Restrição	Descrição
id_proposicao	int8	Primary Key	Identificador único da proposição (projeto de lei, PEC, etc).
sigla_tipo	text	Nullable	Tipo da proposição (ex: PL, PEC, MPV).
numero	int8	Nullable	Número oficial da proposição no ano.
ano	int8	Nullable	Ano de apresentação da matéria legislativa.
ementa	text	Nullable	Texto original da ementa detalhando o objetivo do projeto.
data_apresentacao	timestamptz	Nullable	Data e hora em que a matéria foi protocolada.
created_at	timestamptz	Nullable	Data/Hora de inserção do registro no banco de dados.
resumo_executivo	text	Nullable	[IA Layer] Resumo analítico simplificado gerado via OpenAI.
data_resumo	timestamptz	Nullable	[IA Layer] Timestamp de quando o resumo de IA foi gerado.
tema	text	Nullable	[Etapa 5] Tema classificado via embeddings + cosseno (ex: Saúde, Tributário).
tema_score	float8	Nullable	[Etapa 5] Score de similaridade de cosseno (0 a 1) do tema atribuído.
data_tema	timestamptz	Nullable	[Etapa 5] Timestamp em que a classificação temática foi gerada.

fato_proposicoes_autores

Tabela associativa que mapeia a autoria ou coautoria de cada proposição legislativa.

Campo	Tipo	Restrição	Descrição
id_proposicao	int8	Nullable	ID da proposição (chave estrangeira para fato_proposicoes).
nome_autor	text	Nullable	Nome do parlamentar ou órgão autor da matéria.
tipo_autor	text	Nullable	Categoria do autor (ex: Deputado, Órgão Executivo).
uri_autor	text	Nullable	Link do endpoint do autor na API.

fato_votacoes

Registra as sessões de votações ocorridas na Câmara para deliberação das matérias.

Campo	Tipo	Restrição	Descrição
id_votacao	text	Primary Key	Identificador alfanumérico único da votação.
descricao	text	Nullable	Detalhamento do que está sendo votado em plenário ou comissão.
data_hora_registro	timestamptz	Nullable	Data e hora exata da sessão de votação.
aprovacao	int2	Nullable	Indicador binário/status se a matéria foi aprovada (1) ou não (0).
proposicao_objeto	text	Nullable	Descrição ou link da matéria que originou a votação.
created_at	timestamptz	Nullable	Registro de auditoria de inserção da linha no banco.

fato_votos

Contém o posicionamento individual e nominal de cada parlamentar em uma votação específica.

Campo	Tipo	Restrição	Descrição
id	int4	PK / Identity	Chave primária sequencial auto-incremental da tabela.
id_votacao	varchar	Non-Nullable	ID da votação correspondente (Relaciona-se com fato_votacoes).
tipo_voto	varchar	Nullable	O voto computado do deputado (ex: Sim, Não, Abstenção, Obstrução).
id_deputado	int4	Nullable	ID do parlamentar que votou (Relaciona-se com dim_deputados).
created_at	timestamptz	Nullable	Data de inserção do registro de voto.

Relacionamentos:

fato_proposicoes 1—N fato_proposicoes_autores (por id_proposicao).
fato_votacoes 1—N fato_votos (por id_votacao).
fato_votos N—1 dim_deputados (por id_deputado).
dim_deputados N—1 dim_partidos (por sigla_partido / sigla).
fato_proposicoes.tema alimenta os alertas/digest do workflow n8n da Etapa de automação.

Critérios de avaliação atendidos

Funcionamento: pipeline roda do início ao fim (extração → carga → IA → notificação).
Modelagem: modelo estrela preservado; IA adiciona colunas, não quebra o schema.
IA aplicada: tema (embeddings) e resumo (GPT) chegam ao e-mail do cliente — não é decoração.
Automação: workflow n8n agendado, com sucesso e falha tratados.
Comunicação: diagrama, doc técnica, prompts e pitch executivo.

Equipe (Squad LegoDados):

Micael Lima
^{Data Analytics & AI Engineer}
Python • SQL • Power BI • AI Automation

Guilherme Sobral
^{Analista de Dados / BI}
Power BI • SQL • Excel • BI

Heitor Nogueira
^{Inteligência de Negócios}
BI • SQL • Excel • MIS

Marlon Vargas
^{Power BI Specialist}
Data Analyst • Data Engineer • Power Apps

Como Executar o Projeto:

Siga os passos abaixo para clonar o repositório, configurar o ambiente virtual com o Poetry, definir as variáveis de ambiente e executar o pipeline de inteligência legislativa.

Pré-requisitos:

Antes de começar, certifique-se de ter instalado em sua máquina:

Python (versão ^3.11 requisitada pelo projeto)
Poetry (gerenciador de pacotes e ambientes virtuais)
Git

Passo a Passo:

Clonar o Repositório e Acessar a Pasta: Abra o seu terminal e execute os comandos abaixo para clonar o projeto e entrar no diretório raiz:

git clone https://github.com/micaellimal/Bussola-Publica-Pipeline-de-Inteligencia-Legislativa-com-IA.git
cd Bussola-Publica-Pipeline-de-Inteligencia-Legislativa-com-IA

Instalar as Dependências com o Poetry:

O projeto utiliza o Poetry para isolar o ambiente e gerenciar as bibliotecas estruturadas no pyproject.toml (como pandas, sqlalchemy, openai, entre outras). Instale todas as dependências executando:

poetry install

Este comando criará o ambiente virtual automaticamente e instalará os pacotes nas versões exatas necessárias.

Configurar as Variáveis de Ambiente (.env):

O pipeline precisa de credenciais do banco de dados e da API da OpenAI para funcionar.

Duplique o arquivo de exemplo para criar o seu arquivo .env definitivo:

cp .env.example .env

Abra o arquivo .env recém-criado no seu editor (como o VS Code) e preencha os campos com as suas credenciais reais conforme o modelo abaixo:

# =============================================================================
# BUSSOLA PUBLICA - Variáveis de Ambiente
# =============================================================================

# --- PostgreSQL (Supabase / Neon / Railway) ---
# No Supabase: Settings > Database > Connection string > URI
DATABASE_URL=postgresql://usuario:senha@host:5432/banco

# --- OpenAI API ---
# Obtenha em: https://platform.openai.com/api-keys
OPENAI_API_KEY=sk-proj-SUA_CHAVE_REAL_AQUI

# --- Configurações do Pipeline de IA (Etapas 4 e 5) ---
# DRY_RUN=true  -> Modo Simulação: apenas estima custos de tokens, não consome API e não grava no banco.
# DRY_RUN=false -> Modo Produção: executa o enriquecimento real e salva os dados.
DRY_RUN=true

# Quantidade de proposições pendentes a processar por lote/execução
BATCH_SIZE=10

# Modelo OpenAI escolhido (gpt-4o-mini é ~10x mais barato e ideal para os resumos)
MODELO_IA=gpt-4o-mini

# Etapa 5 — Classificação temática por embeddings
MODELO_EMBEDDING=text-embedding-3-small
LIMIAR_TEMA=0.20


# --- Configurações de Acesso e Sincronização do n8n ---
N8N_USER=admin
N8N_PASSWORD=bussola123
REPO_PATH=C:/Caminho/Ate/O/Projeto/Bussola-Publica-Pipeline-de-Inteligencia-Legislativa-com-IA

3. Subir a Infraestrutura com Docker

Com o Docker Desktop aberto e exibindo o status Engine Running, execute:

docker compose up -d --build

Este comando irá construir e iniciar todos os containers necessários para o funcionamento do projeto.

4. Sincronizar as Dependências Python no Container

Após os containers estarem em execução, instale as dependências do projeto dentro do container do n8n.

Opção A: Via requirements.txt (Recomendado)

Instalação direta utilizando o pip3 nativo do Linux:

docker compose exec -T n8n sh -c "cd /opt/bussola-publica && pip3 install --no-cache-dir --break-system-packages -r requirements.txt"

Opção B: Via Poetry

Caso prefira manter o gerenciamento de dependências através do Poetry:

docker compose exec -T n8n sh -c "cd /opt/bussola-publica && poetry config cache-dir /home/node/.cache/pypoetry && poetry config virtualenvs.create false && poetry install --no-root"

5. Configurar e Executar o Workflow no n8n

Agora que os containers e as dependências estão prontos, todo o pipeline passa a ser controlado visualmente pelo n8n.

Acessar a Interface

Abra o navegador e acesse:

http://localhost:5678

Criar a Conta de Administrador

No primeiro acesso, será exibida a tela Set up owner account. Crie o usuário e senha que serão utilizados para administrar sua instância local do n8n.

Importar o Workflow

No canto superior direito do painel do n8n, clique no menu de três pontos.
Selecione Import from File.
Escolha o arquivo:

n8n/bussola_publica_ingestao_diaria.json

Configurar as Credenciais

Após importar o fluxo:

Configure as credenciais de banco de dados (PostgreSQL / Supabase).
Configure as credenciais de e-mail (SMTP), caso utilize notificações.

Executar o Pipeline

Para testar toda a esteira de processamento imediatamente:

Abra o workflow importado.
Clique em Execute Workflow.

A execução percorrerá todas as etapas do pipeline, incluindo:

Gatilho de agendamento;
Coleta das proposições legislativas;
Processamento e enriquecimento com IA;
Persistência dos dados;
Geração do Digest HTML;
Envio das notificações configuradas.

6. Encerrar os Serviços

Quando finalizar o desenvolvimento ou desejar desligar a infraestrutura local, execute:

docker compose down

Este comando interromperá e removerá os containers criados pelo projeto.

Relatório Técnico e Pitch do Projeto:

Pitch - Negócios (CLIQUE)	Relatório Técnico (CLIQUE)

Estrutura de Pastas e Arquivos:

Abaixo está a arquitetura modular implementada no projeto para garantir a separação de responsabilidades em cada etapa do pipeline:

├── .venv/                         # Ambiente virtual local
├── .vscode/                       # Configurações do editor (settings.json)
├── data\raw/                      # Data Lake - Camada Bronze (Arquivos JSON brutos)
│   ├── deputados/                 # JSONs de deputados com timestamp
│   ├── partidos/                  # JSONs de partidos
│   ├── proposicoes/               # JSONs de proposições e autores
│   └── votacoes/                  # JSONs de votações e votos
├── docs/                          # Documentações e relatórios das etapas
│   ├── apresentacoes/             # Arquivos e materiais de apresentação do projeto
│   ├── figma/                     # Arquivos ou links do design de interface
│   ├── power-BI/                  # Arquivo fonte (.pbix) e documentação do dashboard
│   ├── Etapa4_Camada_IA.pdf       # Relatório de especificação da camada de IA
│   ├── Etapa5_Documentacao_Tecnica.md # Etapa 5: decisões técnicas + prompts da IA
│   └── modelo_dados.md            # Modelo dimensional (tabelas e relacionamentos)
├── logs/                          # Logs de execução do pipeline
├── n8n/                           # Etapa 5: automação
│   ├── bussola_publica_ingestao_diaria_WINDOWS.json # Variante para ambiente Windows
│   ├── bussola_publica_ingestao_diaria.json         # Workflow n8n (ingestão 06h + digest)
│   └── GUIA_IMPORTACAO_n8n.md     # Passo a passo de importação e credenciais
├── readme/                        # Recursos e mídias visuais do README
│   ├── arquitetura/               # Diagramas e fluxogramas da arquitetura
│   ├── identidade/                # Elementos visuais e logos do projeto
│   ├── powerBI/                   # Prints das telas do painel Power BI
│   ├── prints/                    # Prints das evidências do projeto (Supabase/n8n)
│   └── team/                      # Fotos individuais dos integrantes do squad
├── src/                           # Código-fonte principal do projeto
│   ├── __pycache__/
│   ├── __init__.py
│   ├── ai_layer.py                # Etapa 4: Integração com OpenAI (Resumos executivos)
│   ├── classificacao_tematica.py  # Etapa 5: Classificação temática (embeddings + cosseno)
│   ├── config.py                  # Configurações globais e variáveis de ambiente
│   ├── diagnostico.py             # Script de validação e saúde do ambiente
│   ├── extraction.py              # Etapa 1: Scripts de extração/ingestão da API
│   ├── transformation.py          # Etapa 3: Classe PipelineEtapa3 (Orquestrador de carga)
│   └── transformers.py            # Funções de transformação e limpeza com Pandas
├── .env                           # Variáveis de ambiente locais (Credenciais)
├── .env.example                   # Modelo de configuração das variáveis de ambiente
├── .gitignore                     # Arquivos ignorados pelo Git
├── LICENSE                        # Licença do projeto
├── main.py                        # Ponto de entrada do pipeline de extração/ingestão
├── main2.py                       # Ponto de entrada alternativo/testes de execução
├── poetry.lock                    # Trava de versões das dependências
├── pyproject.toml                 # Configurações do projeto e dependências (Poetry)
└── README.md                      # Documentação do projeto

Segurança

O arquivo .env (com DATABASE_URL e OPENAI_API_KEY reais) não é versionado — está no .gitignore. Use sempre o .env.example como modelo.
O workflow do n8n usa placeholders de credencial (REPLACE_POSTGRES_CRED_ID, REPLACE_SMTP_CRED_ID); as credenciais reais ficam apenas na sua instância local do n8n.

Avaliação e Reconhecimento:

O projeto Radar Legislativo recebeu Nota 100 e um feedback de excelência técnica pelo corpo docente.

Feedback do Professor — Fase 1 (T01): Projeto Integrador: Radar Legislativo

Nota do SQUAD: 100

SQUAD 21005 LegoDados, Após análise profunda do repositório, confirmamos que a entrega atinge excelência técnica e justifica plenamente a nota máxima. Este projeto estabelece um padrão ouro para IA aplicada à Engenharia de Dados no cenário legislativo brasileiro.

Funcionamento e Robustez: Pipeline completo de ponta a ponta (Extração → Carga → IA → Notificação) com tratamento robusto de falhas, retry automático e modo DRY_RUN que estima custos antes do processamento real — maturidade operacional avançada. A persistência do JSON bruto na camada Bronze garante integridade e rollback granular caso haja falha nas etapas seguintes.

Modelagem de Dados: Segue rigorosamente o Modelo Estrela (Star Schema), com tabelas dimensionais (dim_deputados, dim_partidos) e fatos separados (fato_proposicoes, fato_votacoes). Inclui até uma tabela associativa para resolver relações N:N de autoria legislativa. A documentação técnica é exaustiva, com esquemas completos e descrições de campos detalhadas.

IA Aplicada: Arquitetura híbrida inteligente! No Caminho A, usa-se Embeddings (text-embedding-3-small) + Similaridade de Cosseno para classificação temática com academicismo e auditabilidade via tema_score. No Caminho B, resumos executivos acionáveis com GPT-4o-mini, focados em stakeholders corporativos. A decisão de separar esses caminhos — baixo custo vs. alto valor analítico — demonstra entendimento profundo de custo versus benefício na aplicação prática de IA.

Comunicação: Documentação impecável! Inclui diagramas detalhados, prompts da IA, relatórios técnicos no Canva e Gamma, além de um dashboard Power BI publicado com insights acionáveis sobre distribuição temática e concentração política. O prompt do resumo segue estrutura clara: ('O que propõe, Quem é impactado, Ponto de atenção').

Escalabilidade: Automação robusta no n8n! Workflow agendado para execução diária às 6h, tratamento de falhas dedicado com alertas por e-mail, e integração nativa com Docker. Documentação completa para importação local do workflow — preocupação genuína com adoção por outros times.

In vigore / Em suma: Vocês transformaram o oceano de dados brutos da API da Câmara dos Deputados em sinais acionáveis, com IA integrada ao produto final (não como decoração), automação confiável e documentação executiva clara. Este trabalho define o padrão para projetos similares no Brasil!

Conclusão e Aprendizados:

Este projeto marca a consolidação prática dos conhecimentos adquiridos ao longo da Fase 1 (Fundamentos e Primeiros Pipelines) da pós-graduação em Engenharia de Dados e Inteligência Artificial da Xperiun (XP Educação). A construção desta esteira de inteligência legislativa permitiu aplicar de ponta a ponta as seguintes disciplinas e competências modulares:

Modelagem Relacional & DWH: Estruturação lógica e física de tabelas Fato e Dimensão utilizando PostgreSQL (Supabase) via SQLAlchemy, garantindo o armazenamento de dados históricos por mais de 30 dias.
Manipulação e Limpeza de Dados: Desenvolvimento de rotinas robustas em Python com a biblioteca Pandas para tratamento de paginação da API da Câmara, saneamento de strings e normalização de payloads brutos (Camada Bronze para Silver).
Automação e Orquestração Low-Code: Integração de scripts nativos em Python dentro do ecossistema n8n através de containers Docker, programando cronjobs diários e gerenciando fluxos alternativos de alertas e falhas (notificações automatizadas).
Engenharia de Prompt e IA Generativa: Implementação prática de LLMs (gpt-4o-mini) para geração de resumos executivos acionáveis e enriquecimento de dados por meio de embeddings (text-embedding-3-small) combinados com similaridade de cosseno.
Colaboração e DevOps: Controle de versão profissional via Git/GitHub, organização de branches, documentação técnica clara e isolamento de ambientes virtuais com o Poetry.

Agradecimentos:

Agradecemos primeiramente à Xperiun / XP Educação e ao corpo docente (Ítalo Mesquita, Leon Solón, César Germano, Iago Braz) por fornecerem a base teórica e os insights práticos que viabilizaram o desenvolvimento de arquiteturas modernas e integradas.

Por fim, expressamos nosso sincero agradecimento a cada integrante do Squad LegoDados. A sinergia, dedicação técnica e o esforço mútuo durante as madrugadas de código, testes de API e refinamento do dashboard no Power BI foram os verdadeiros pilares para transformar dados legislativos complexos em um produto final de alto valor estratégico.

🧱 Assim como cada bloco de LEGO se encaixa perfeitamente para dar vida a grandes estruturas, nossa arquitetura une dados, IA e orquestração para construir uma visão legislativa sólida, transparente e indestrutível. 🧱

Name		Name	Last commit message	Last commit date
.vscode		.vscode
docs		docs
n8n		n8n
readme		readme
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
main.py		main.py
main2.py		main2.py
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation