2026-06-21 Retrospectiva | idea_world

Perguntando novamente sobre o fluxo de conversão da documentação oficial do Godot para JSONL

Coloquei o esquema de 2026-06-21-initial-rag-classifier-architecture.md no Qwen e perguntei sobre a direção do código Python para converter documentos Markdown em JSONL.

O ponto central da primeira pergunta era um script de conversão simples.

Preciso de um código Python que converta Markdown em JSONL
Seria bom se incluísse também o comando de execução
Quero gerar o conteúdo JSONL chamando a API do Qwen
Como o JSONL será salvo, deve haver lógica de verificação para que o esquema não seja corrompido
Quero validar o formato JSONL usando expressões regulares ou validação de esquema
Também seria útil se o modelo determinasse a que tabela o resultado deve ser mapeado ao chamar a API
Se necessário, devo gerar os esquemas completos de docs_chunks, api_mapping e label_prototypes

A ideia evoluiu de script CLI para ferramenta baseada na web

Depois percebi que um simples conversor CLI não mostraria bem o fluxo. Então comecei a pensar em uma estrutura que fosse chamada via web.

Seria bom poder inserir a chave da API na tela web
Gostaria de suportar upload de arquivo Markdown ou upload de pasta
Seria útil visualizar as diferenças ou alterações antes e depois da conversão diretamente na web
Mais do que gerar apenas o arquivo de resultado, o processo de conversão e os resultados de classificação precisam ser revisados por uma pessoa

Ao formular essa pergunta, percebi que o conversor JSONL deve ser mais que um script em lote; ele precisa ser uma ferramenta de processamento de dados que permite revisão e aprovação humana.

Reconfirmando o problema de um arquivo gerar múltiplas tabelas

A pergunta adicional mais importante foi que um único arquivo Markdown pode não ser mapeado para apenas uma tabela.

Por exemplo, um documento de migração pode gerar simultaneamente três tipos diferentes de JSONL.

Trechos de explicação oficial vão para docs_chunks.jsonl
Regras de mudança de API vão para api_mapping.jsonl
Exemplos de conversão/classificação vão para label_prototypes.jsonl

Portanto, o conversor não deve receber um arquivo e produzir apenas um JSONL; ele deve chamar o Qwen para determinar quais registros de tabela são necessários e, se houver múltiplas respostas, gerar dois ou mais registros JSONL a partir de um único arquivo.

Nova direção de design definida hoje

A conversão de Markdown para JSONL será dividida nas etapas classificação → geração → validação → salvamento.
O Qwen pode ler o conteúdo e determinar quais tabelas de destino são necessárias.
Contudo, a resposta do Qwen não será aceita cegamente; um validador de esquema local decidirá se o salvamento ocorre.
Expressões regulares serão usadas apenas para validação mínima de formato; a validação real de campos deve ser feita com JSON Schema ou algo como Pydantic.
Partiremos do pressuposto de que um arquivo Markdown pode gerar múltiplos resultados JSONL.
A UI web será mais que uma conveniência; será uma camada de inspeção onde registros gerados automaticamente são revisados e aprovados por humanos.

Próximas tarefas

Redigir rascunhos de JSON Schema para docs_chunks, api_mapping e label_prototypes.
Projetar o prompt que recebe um arquivo Markdown e faz o Qwen identificar as tabelas-alvo.
Definir regras para separar e salvar arquivos quando a resposta do Qwen contiver registros de várias tabelas.
Criar primeiro um script CLI que valide JSONL linha a linha.
Em seguida, expandir a UI web para upload, conversão, diff, resultados de validação e fluxo de aprovação/rejeição.

Perguntas deixadas

Se delegarmos a determinação do mapeamento de tabela ao Qwen, em quais situações a aprovação humana será obrigatória?
Os candidatos de api_mapping devem ser inseridos diretamente no banco ou armazenados apenas em estado candidate?
Na UI web, o diff deve ser exibido em relação ao Markdown original ou em relação à versão anterior do JSONL?
Como lidar com arquivos que falharam ou tiveram sucesso parcial ao fazer upload de pastas, e como reprocessá‑los?