Processador de Questões BNCC

Sistema Python para processar arquivos CSV com questões da BNCC e realizar busca semântica no Supabase.

Funcionalidades

Processamento de Dados

• Leitura de arquivos CSV das pastas docs/EF, docs/EI e docs/EM
• Extração de códigos BNCC usando regex
• Limpeza de descrições removendo códigos entre parênteses
• Suporte a colunas opcionais (Unidade Temática, Objeto do Conhecimento)
• Conversão de campos vazios em NULL
• Envio de dados em lotes de 50 registros via UPSERT
• Tratamento de erros e logs detalhados

Busca Vetorial

• Vetorização usando Google Gemini Embeddings (768 dimensões)
• Integração com LangChain
• Busca semântica por similaridade usando pgvector
• Função SQL otimizada para cosine similarity
• Threshold de similaridade configurável

Pré-requisitos

• Python 3.7 ou superior
• Conta no Supabase
• Chave de API do Google Gemini

Instalação

Instale as dependências:

pip install -r requirements.txt

Configuração

1. Copie o arquivo de exemplo:

copy .env.example .env

2. Configure as credenciais no arquivo .env:
   • SUPABASE_URL: URL do projeto Supabase
   • SUPABASE_KEY: Chave de API do Supabase (anon/public key)
   • GOOGLE_API_KEY: Chave de API do Google Gemini

Exemplo:

SUPABASE_URL=https://seuproject.supabase.co
SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
GOOGLE_API_KEY=AIzaSy...

O arquivo .env não será versionado (está no .gitignore).

Como usar

1. Criar a estrutura no Supabase

Execute o script SQL setup_database.sql no SQL Editor do Supabase:

• Cria a tabela base_questoes_bncc
• Cria índices para performance
• Configura triggers de atualização

2. Processar e enviar questões

python processar_questoes_bncc.py

O script:

1. Conecta ao Supabase
2. Lê os arquivos CSV
3. Extrai os códigos BNCC
4. Envia os dados em lotes
5. Exibe resumo do processamento

3. Configurar busca vetorial

Execute o script SQL setup_vetorial.sql no SQL Editor do Supabase:

• Habilita a extensão pgvector
• Adiciona coluna embedding (768 dimensões)
• Cria índice para busca eficiente
• Cria função buscar_questoes_similares()

4. Vetorizar as questões

python vetorizar_questoes.py

O script:

1. Busca registros sem embedding
2. Gera embeddings usando Google Gemini
3. Atualiza o banco com os vetores
4. Processa em lotes de 10 registros

Estrutura do Banco de Dados

Tabela: base_questoes_bncc

CREATE TABLE base_questoes_bncc (
    id BIGSERIAL PRIMARY KEY,
    disciplina TEXT,
    ano TEXT,
    unidade_tematica TEXT,
    objeto_conhecimento TEXT,
    codigo_bncc TEXT UNIQUE,
    descricao_habilidade TEXT,
    embedding vector(768),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Índices

• codigo_bncc (UNIQUE) - busca direta por código
• embedding (IVFFlat) - busca vetorial otimizada
• disciplina - filtros por disciplina

Estrutura dos Arquivos CSV

Ensino Fundamental (EF)

Disciplina, Ano, Unidade Temática, Objeto do Conhecimento, Habilidade

Ensino Médio (EM) e Ensino Infantil (EI)

Disciplina, Ano, Habilidade

O script detecta automaticamente a estrutura e processa adequadamente.

Comportamento do Sistema

Processamento de Dados

• Usa UPSERT baseado no campo codigo_bncc (UNIQUE)
• Códigos existentes são atualizados
• Novos códigos são inseridos
• Registros sem código BNCC válido são ignorados com aviso
• Campos vazios são convertidos para NULL
• Colunas opcionais são processadas automaticamente

Vetorização

• Processa apenas registros sem embedding
• Respeita rate limits da API Google Gemini
• Gera vetores de 768 dimensões
• Atualiza registros individualmente

Tecnologias

• Python 3.7+
• Supabase (PostgreSQL)
• pgvector
• LangChain
• Google Gemini Embeddings