Derivado: exportar o dataset em JSON Lines (e avaliar Parquet)

[marcosbeto]

Hoje o pipeline/derivar.py gera três formatos a partir dos JSONs canônicos: SQLite, o dump lógico .sql e 15 CSVs. Falta um formato colunar/streaming, que é o que o público de dados e pesquisa espera encontrar — quem usa pandas, polars, DuckDB ou Spark.

Esta issue propõe adicionar JSON Lines, Parquet, ou os dois.

Uma decisão de projeto embutida (leia antes de escolher)

O pipeline é stdlib puro, com uma única exceção: jsonschema, usado só na validação de formato. Isso é deliberado — mantém a reprodutibilidade barata e o CI simples.

Isso afeta a escolha:

• JSON Lines é gerável com a stdlib (json + escrita linha a linha). Não adiciona dependência nenhuma. É o caminho de menor atrito.
• Parquet exige pyarrow (ou equivalente), que é uma dependência pesada. Vale a pena, mas é uma decisão a discutir na issue antes do PR — talvez como passo opcional do derivar.py, que só roda se a biblioteca estiver disponível, mantendo o CI mínimo funcionando sem ela.

Comece comentando qual caminho pretende seguir. Se for Parquet, vamos conversar sobre onde a dependência entra antes de você escrever código — não quero que trabalho seja jogado fora.

O que fazer

O ponto de extensão é pipeline/derivar.py. A função gerar_csvs() (por volta da linha 218) é o modelo mais próximo: itera as entidades e escreve um arquivo por entidade. Um gerar_jsonl() análogo seguiria a mesma forma, escrevendo em derivados/jsonl/.

Pontos de atenção:

• Determinismo é obrigatório. O CI compara o derivado commitado com o reproduzido e reprova qualquer divergência. Ordenação estável, sem timestamps, sem iteração sobre conjunto não ordenado. Já tivemos um caso de quebra por normalização de nome de arquivo diferente entre macOS e Linux (commit 5d3f413), então vale rodar antes de abrir o PR.
• Derivado nunca altera o dado. Os JSONs de dados/ são a fonte canônica; o derivado é projeção.
• Como representar listas. Os CSVs usam o separador " | " para colunas multivaloradas. Em JSON Lines isso não é necessário — arrays nativos são melhores. Documente a escolha.

Critério de aceite

• python3 pipeline/derivar.py gera o novo formato de forma determinística: rodar duas vezes seguidas produz bytes idênticos.
• Os arquivos gerados entram no repositório e o CI passa (Dataset commitado = dataset reproduzido).
• derivados/README.md documenta o novo formato, com um exemplo de leitura (pandas, polars ou DuckDB).
• Nenhuma mudança em dados/.

Como rodar o pipeline localmente

pip install --upgrade jsonschema
cd pipeline
python3 extrair.py && python3 extrair_ei.py && python3 extrair_computacao.py
python3 verificar.py && python3 verificar_computacao.py
python3 validar_schema.py && python3 validar.py
python3 derivar.py
git diff --exit-code dados/ derivados/    # tem que sair limpo

Requer Python 3.10+ e pdftotext (poppler). Detalhes em docs/instalacao.md.