14.4 · Primeira configuração pelo Assistente (sem terminal)

Este é o caminho de quem nunca abriu um terminal. Com o Python instalado (8.1), dê dois cliques em Assistente Lattes.vbs, na raiz do repositório — ou no atalho da área de trabalho. A janela abre na aba «0 · Início», e o primeiro cartão, «Primeira configuração», é o roteiro: nove passos numerados, de cima para baixo, na ordem em que um depende do outro — os sete primeiros obrigatórios, os dois últimos opcionais.

O passo atual — o primeiro que falta — fica em azul, e o botão dele faz o que falta. Cada botão mostra antes o que vai fazer (o comando, o tamanho do download, o tempo) e só age depois da sua confirmação; o andamento aparece no log, à direita. Nada fica travado: os botões dos outros passos continuam clicáveis, e cada um confere a própria condição antes de agir. Os opcionais nunca seguram o resto.

Se você trouxe esta pasta de outro computador, leia antes 8.8: os casos próprios dessa situação — a junção do venv, o ambiente copiado que não roda, a placa que não é NVIDIA — aparecem aqui nos passos 2 e 3, cada um com o seu botão.

Numa máquina recém-instalada, o cartão mostra o Python pronto e o passo 2 em azul: ainda não há ambiente virtual, e os passos 3 a 5, que dependem dele, esperam com um traço.

O cartão «Primeira configuração» numa máquina nova, com o passo 2 em azul — Figura 14.1 — Numa máquina nova, o passo 2 em azul: o ambiente virtual ainda não existe, e o botão «Criar venv» o cria; os passos 3 a 5 esperam com um traço. Ilustração: estado simulado numa máquina já configurada.

Python — nada a fazer: se a janela abriu, ele existe. A linha mostra a versão que abre a janela e a do ambiente virtual. Se disser «fora do medido (3.13)», instale o 3.13 (8.1) antes de seguir.
Ambiente virtual (venv) — botão «Criar venv». Cria a pasta venv na raiz do repositório, com o Python desta janela, em menos de um minuto (o que é um venv: 8.3). Ao terminar, pergunta «Reabrir o Assistente agora» ou «Depois»: a janela precisa reabrir para passar a usar o Python novo.

Quando o projeto veio de outro computador, este passo muda de botão em vez de falhar — os três casos estão em 8.8, e aqui está o que a linha mostra em cada um:

Junção apontando para o vazio — «…\venv não é uma pasta: é uma junção (o atalho de pasta do Windows) e aponta para …, que não existe neste computador». O botão «Remover a junção e criar o venv» faz as duas coisas na ordem: tira só o atalho e cria o ambiente. O diálogo diz o que é uma junção e que o destino não é tocado.

Junção cujo destino existe aqui — a janela não oferece remover. A linha explica que aquele destino pode ser o ambiente de outros projetos, e o único botão é «Abrir a pasta do destino», que mostra a pasta e não altera nada. Remover atalho vivo é decisão de uma pessoa, feita à mão.

Pasta de verdade que não roda — «é uma pasta de verdade, mas não roda nesta máquina: o Python que a criou (…) não existe neste computador — ela foi copiada de outra máquina». O botão «Renomear e criar um venv novo» guarda a pasta como venv_quebrado — nada é apagado, e desfazer é renomear de volta — e cria o ambiente desta máquina em seguida.

Com o venv criado e a janela reaberta, o passo 3 é o torch: a linha nomeia a placa desta máquina — lida do Windows, tenha ela driver ou não — e diz qual versão instalar. Com NVIDIA, «não instalado — placa … pronta para a versão com GPU»; sem ela, «placa AMD …, que não é NVIDIA: vai a versão para processador», com a consequência na mesma frase. O botão monta o comando certo para esta máquina, o mesmo de 9.3.

O cartão «Primeira configuração» com o passo 3, o torch, em azul — Figura 14.2 — O passo 3 em azul: o torch ainda não está instalado, a placa NVIDIA foi encontrada, e o botão «Instalar o torch» monta o comando certo para esta máquina. Ilustração: estado simulado numa máquina já configurada.

O diálogo «Instalar o PyTorch (passo 3)» — Figura 14.3 — O diálogo do passo 3: a placa encontrada, o comando que vai rodar no venv e o tamanho do download — nada é instalado antes de um dos botões. Ilustração: estado simulado numa máquina já configurada.

PyTorch (motor dos modelos) — botão «Instalar o torch». O diálogo «Instalar o PyTorch (passo 3)» mostra a placa encontrada, a linha exata e o tamanho: com placa, «Instalar (GPU · CUDA 12.8)» baixa cerca de 2,8 GB, de 5 a 30 minutos; sem placa, «Instalar (processador)» baixa uns 115 MB. Este passo não só mostra o que está instalado — ele recomenda o certo quando o instalado está errado, e o botão muda com a recomendação:

«Reinstalar com GPU», quando há um torch de processador numa máquina com placa NVIDIA visível; «Reinstalar para processador», quando há um torch +cu128 numa máquina sem NVIDIA — o caso de uma máquina AMD, em que a versão com CUDA estava instalada e nunca veria placa; «Abrir a página do driver», quando o Windows vê uma placa NVIDIA e o driver dela não responde (aí o que falta é o driver, não o pip), ou quando o driver é antigo demais para as rodas medidas.

Em todos os casos sem placa, a linha traz o número e o limite dele: a classificação fica de 10 a 50× mais lenta; a extração e a ingestão não usam placa e rodam igual. Sem placa NVIDIA o passo fica ✅ com ressalva em âmbar — está certo assim, e não segura o resto da configuração.

Bibliotecas do pipeline e do painel — botão «Instalar as bibliotecas». Instala as que faltam — pandas, numpy, pyarrow, openpyxl, sentence-transformers e, para o painel, fastapi e uvicorn —, em alguns minutos. Vem depois do torch de propósito: nessa ordem, o pip não troca o torch com placa pela versão sem placa (9.2). Se o torch ainda não estiver instalado, o botão avisa e manda para o passo 3.

O passo 5 baixa os modelos uma vez só: a linha diz o que falta — «E5 (1,1 GB, obrigatório) e reranker (2,2 GB, opcional) ainda não estão no cache» — e, depois do download, o pipeline não precisa mais de internet.

O cartão «Primeira configuração» com o passo 5, os modelos de IA, em azul — Figura 14.4 — O passo 5 em azul: o E5 e o reranker ainda não estão no cache, e o botão «⬇ Baixar os modelos» faz o download uma vez só. Ilustração: estado simulado numa máquina já configurada.

Modelos de IA locais — botão «⬇ Baixar os modelos». O diálogo «Baixar os modelos de IA (passo 5)» mostra o destino, o espaço livre no disco e o tempo — uns 10 minutos a 50 Mbit/s, até 1 hora numa conexão lenta — e oferece «Baixar os dois (3,3 GB)» ou «Só o E5 (1,1 GB)». É o python pipeline.py --baixar-modelos de 14.2; se a internet cair, clique de novo: ele continua de onde parou. Com o E5 no cache, o passo já fica ✅ mesmo sem o reranker — e o botão continua ali, para baixá-lo quando o desempate for ligado.
Pasta das bases — botão «Escolher a pasta…». Abre o seletor de pastas, grava a escolha e cria as subpastas que faltarem, de 1_ENTRADA a 6_PROSPECTA; se a pasta já existe e só faltam subpastas, a linha diz quais e o botão é «Criar as pastas». Segundos. Escolha uma pasta local, com espaço — nunca uma sincronizada pelo OneDrive.
Dicionário do domínio — botão «Escolher domínio», que leva à aba «3 · Pipeline». Numa instalação nova, o domínio padrão, industria, já traz o dicionário: em geral este passo já aparece ✅.

Opcionais — só para quem precisa deles:

Ollama (opcional) — botão «Ver aba IA». Só faz falta para redigir glosas com IA local (12); nada do pipeline depende dele.
Git (opcional) — sem botão: só para quem versiona o código (aba «9 · Git»). Instale em https://git-scm.com/download/win.

Quando os sete passos obrigatórios estão feitos, o cartão recolhe numa linha (os opcionais 8 e 9 não contam): «✅ Primeira configuração completa», seguida da versão do Python, do torch, da placa, dos modelos no cache e da pasta das bases. «Mostrar os passos» abre a lista de novo, e «Ocultar os passos» a recolhe. Daí em diante, o que interessa são os outros dois cartões, «Estado dos dados» e «Próximo passo» (15.4).

O cartão «Primeira configuração» recolhido numa linha verde — Figura 14.5 — Configuração completa: o cartão recolhe numa linha verde, com «Mostrar os passos» à direita.

O cartão «Primeira configuração» com os passos abertos — Figura 14.6 — Os passos abertos de novo por «Mostrar os passos», todos com ✅, e «Ocultar os passos» no fim.

CONFIRA — Se um comando terminar em erro, a linha do passo vira ✕ — «o último comando terminou com erro — veja o log à direita e clique de novo para tentar outra vez» — e o botão continua ali. O log costuma dizer o motivo: sem internet, proxy bloqueando, disco cheio, Python sem PyTorch para a versão dele (25). Quando o comando dá certo, a janela confere tudo de novo sozinha.

Depois da configuração, os dois comandos de estreia. Na aba «0 · Início», «🔄 Verificar novamente» é o --pre-voo; na aba «3 · Pipeline», ponha «Demonstração com N currículos simulados» em 300 e clique em «▶ Rodar tudo». O cartão «Comando» mostra a linha exata — os mesmos python pipeline.py --pre-voo e python pipeline.py --demonstracao 300 de 14.1. O roteiro completo do primeiro dia, até o painel, está no fim de 15.4.

LEMBRE-SE — O assistente não é um terceiro modo de cálculo: ele chama as mesmas funções e grava os mesmos arquivos. O que muda é só quem digita. A seção 15.4 descreve cada aba.

15.4 · O Assistente — a janela única

EM UMA FRASE — Um arquivo, dois cliques, nenhuma janela preta: tudo o que este manual manda digitar também se faz aqui por botões — e o comando exato que vai rodar aparece na tela antes de rodar.

O Assistente é uma janela Tkinter, o arquivo lattes_pipeline/ferramentas/assistente.py, lançada por Assistente Lattes.vbs, na raiz do repositório. Onze abas à esquerda, um log ao vivo à direita, mais de cem botões — cada um com uma dica que aparece ao pousar o mouse, inclusive nas ações irreversíveis.

O que ele não é: não é uma quinta etapa, não recalcula nada e não muda resultado nenhum. Cada botão monta uma das linhas de comando de 15.1 e a entrega a um subprocesso do Python do ambiente virtual. O motivo de existir é de alcance: quem opera o sistema nem sempre é quem o programou.

ANALOGIA — É o painel do carro. Os botões estão ali para você não precisar abrir o capô a cada viagem; o motor é exatamente o mesmo — e este painel ainda mostra, antes do arranque, o que vai acontecer.

LEMBRE-SE — Duas regras do projeto que a janela não relaxa. Currículo é dado pessoal e só é processado nesta máquina: não existe botão que envie texto de currículo a serviço externo. E a chave de API nunca aparece em log, em preferências, em arquivo versionado nem em variável de ambiente registrada.

Abrir: dois cliques em `Assistente Lattes.vbs`

O lançador fica na raiz do repositório, C:\0_Desenvolvimento\CNPQ, ao lado da pasta lattes_pipeline. Ele precisa ficar ali porque deriva todos os caminhos da própria posição.

Por dentro, em ordem: confere se lattes_pipeline\ferramentas\assistente.py existe; procura um pythonw.exe — primeiro venv\Scripts da raiz, depois .venv, depois lattes_pipeline\.venv, depois os Pythons de usuário 3.13, 3.12 e 3.11 e o Anaconda; e roda com lattes_pipeline como pasta atual, sem console. O pythonw.exe é o Python que não abre janela preta; a janela que você vê é a do Tkinter.

Para um atalho na área de trabalho, o caminho mais curto é de dentro da própria janela: na aba «0 · Início», no rodapé, o botão «🔗 Criar atalho na área de trabalho» grava um Assistente Lattes.lnk na sua área de trabalho — a de verdade, perguntada ao Windows, que é o que faz o atalho aparecer também quando o OneDrive redireciona essa pasta. O atalho aponta para o Assistente Lattes.vbs da raiz (alvo, nunca cópia: nada é movido nem duplicado), roda a partir da raiz do repositório e usa o ícone do app — o bloco azul com a treliça de três nós, desenhado por ferramentas/gerar_icone.py e versionado em ferramentas/assistente.ico nos sete tamanhos que o Windows pede, de 16 a 256 px. O log da janela diz onde o arquivo ficou; se já existir um atalho com esse nome, ele é substituído, com aviso no log. Quem preferir o caminho manual continua com ele: botão direito no .vbs → «Enviar para → Área de trabalho (criar atalho)». Se o repositório mudar de pasta, refaça o atalho: ele guarda o caminho antigo.

A mesma imagem é o ícone da janela, na barra de tarefas e no Alt+Tab. Num Tk que não leia arquivos .ico, o assistente abre sem ícone — nunca deixa de abrir.

CONFIRA — O .lnk é escrito pelo WScript.Shell do próprio Windows: com o pywin32 instalado, direto por COM (instantâneo); sem ele, por uma linha de PowerShell. O arquivo resultante é o mesmo.

ATENÇÃO — Se nada acontecer ao dar dois cliques, o lançador não falhou calado: ele avisa em caixa de mensagem. «Não encontrei o assistente em…» significa que o .vbs saiu da raiz — devolva-o. «Não consegui iniciar o Python» significa que ele não achou Python nenhum — nem o ambiente virtual do projeto, nem um Python instalado para o seu usuário: instale o Python 3.13 como em 8.1, marcando «Add python.exe to PATH», e dê os dois cliques de novo; o ambiente virtual e o resto se fazem pela aba «0 · Início» (14.4). Se nenhuma caixa apareceu, o duplo clique nem chegou a rodar — a associação do .vbs está desativada por política de segurança.

NO TERMINAL (PowerShell)

# O equivalente ao duplo clique — útil para ver a mensagem de erro de partida.
cd C:\0_Desenvolvimento\CNPQ\lattes_pipeline
python ferramentas\assistente.py

CONFIRA — A janela depende do Tkinter, que vem com o instalador oficial do Python e não se instala com pip. Se o ambiente virtual foi criado por um Python sem Tk, o assistente não abre. O teste é python -c "import tkinter; print(tkinter.TkVersion)", que deve imprimir 8.6.

A janela: abas à esquerda, log à direita

A estrutura é fixa. As onze abas ficam à esquerda, na ordem em que se usam — «0 · Início», «1 · Baixar do CNPq», «2 · Ingestão», «3 · Pipeline», «4 · Prospecta», «5 · IA», «6 · Dicionário», «7 · Ambiente», «8 · Testes», «9 · Git» e «10 · Comandos» —, e o log de execução fica à direita, não embaixo: assim dá para acompanhar a etapa que roda enquanto se prepara a próxima. A divisória entre os dois é arrastável.

O log é um só: tudo o que qualquer aba dispara escreve ali ao vivo, linha a linha, colorido por tipo — erro, aviso, conclusão, comando disparado, início de etapa. Na barra do log estão «Limpar» (que não cancela nada, só apaga a tela), «Salvar log…», «Pasta de logs» e a caixa «seguir o fim», que se desmarca para ler uma linha antiga enquanto o processo continua imprimindo.

As preferências vivem fora do repositório, em %LOCALAPPDATA%\AssistenteLattes\prefs.json, ao lado do espelho diário do log. O que é perigoso nunca volta marcado de uma sessão anterior: a demonstração, o apagar a origem dos XML, o --forcar, o --sem-login, o endereço de rede, a base a servir e o aprimorar glosas nascem sempre desligados. É decisão consciente a cada vez, e não configuração esquecida.

A linha do tempo das quatro fases. As quatro abas que fazem trabalho — «1 · Baixar do CNPq», «2 · Ingestão», «3 · Pipeline» e «4 · Prospecta» — abrem com a mesma faixa no alto: 1 Trazer currículos › 2 Ingerir › 3 Pipeline › 4 Painel, cada fase com o seu estado logo abaixo — «não feito», «em dia», «desatualizado», «SIMULADA» e, na primeira, «feito · há arquivos a ingerir» ou «nada esperando». A faixa fica fora da área rolável, de propósito: a frase de cada fase perde o sentido se sair de vista quando se rola para ler um cartão. A fase da aba em que você está fica em negrito — é o «você está aqui», sem seta e sem cor nova. O sinal vem do mesmo cálculo que alimenta «Estado dos dados», na aba «0 · Início»: não existem duas verdades sobre onde o trabalho parou.

Cada aba abre dizendo o que resolve. Essas mesmas quatro abas começam com um cartão «O que esta aba resolve»: um parágrafo dizendo o que sai dali e uma faixa «Antes de usar esta aba: …» com o pré-requisito explícito — a liberação do IP, na aba 1; os arquivos depositados em 1_ENTRADA, na aba 2. É a resposta ao pedido do dono: «ele deve ser claro para que as pessoas sigam uma lógica na sua execução, além de explicações e impressões claras de cada acontecimento».

O glossário. Nas abas «1 · Baixar do CNPq» e «2 · Ingestão» há um cartão «Glossário», recolhido, com o botão «Mostrar o glossário». Ele explica as cinco palavras que essas telas usam desde o primeiro dia e que nunca tinham sido escritas em português de quem não programa: lote (um punhado de currículos tratados juntos — o download pede 100 por vez ao CNPq), manifesto (a lista, em 2_CURRICULOS/_controle, de qual currículo já entrou e em que versão), compactar (juntar os vários lote_NNNNNN.parquet de uma tabela num arquivo só — não é zipar), bruto (o arquivo como o CNPq entregou, o ZIP com o XML dentro, antes de ser lido) e reconciliar (conferir o disco contra o manifesto e acertar a diferença).

LEMBRE-SE — O log salvo costuma conter a resposta. Antes de pedir ajuda, clique em «Salvar log…» e anexe o arquivo: ele já sai com qualquer segredo mascarado.

Aba «0 · Início» — o que falta para esta máquina rodar

A aba responde uma pergunta só — o que falta para esta máquina rodar — em três cartões: «Primeira configuração», «Estado dos dados» e «Próximo passo».

Figura 15.1 — A aba «0 · Início» do Assistente Lattes: a primeira configuração recolhida em linha verde, o estado de cada pasta do fluxo e o próximo passo.

«Primeira configuração» é o --pre-voo de 14.1 em forma de roteiro: nove linhas numeradas, na ordem em que uma depende da outra — 1 Python, 2 ambiente virtual (venv), 3 PyTorch, 4 bibliotecas do pipeline e do painel, 5 modelos de IA locais, 6 pasta das bases, 7 dicionário do domínio, e as opcionais 8 Ollama e 9 Git. O passo atual, o primeiro obrigatório que falta, fica com fundo azul claro, filete azul à esquerda e o botão em destaque; o botão faz o que falta, sempre depois de mostrar o que vai fazer. O passo a passo, botão por botão, está em 14.4.

Os ícones: ✅ feito; ✅ com «⚠» feito com ressalva (por exemplo, torch sem placa NVIDIA); ⬜ falta; ⏳ consultando; – ainda não (os passos 3 a 5 sem venv); ✕ o último comando falhou; ○ opcional ausente, que nunca segura o resto. Quando os sete obrigatórios ficam prontos, o cartão recolhe numa linha verde, «✅ Primeira configuração completa — …», com o botão «Mostrar os passos»; recolhido é o padrão só quando está completo.

Estado dos dados traz uma linha por pasta do fluxo, com número de arquivos, tamanho, data mais recente e a situação: «desatualizado» quando a pasta é mais antiga que a etapa anterior, «simulado» quando a base veio de uma demonstração, «lotes: N» na ingestão em lote e «compactar» quando alguma tabela tem dois ou mais lotes. Duplo clique numa linha abre aquela pasta.

«Próximo passo» transforma as duas leituras acima numa recomendação e num botão. Enquanto a configuração não está completa, ele aponta o passo atual — «Primeira configuração: passo N — …» — e o botão aciona esse passo, com a mesma confirmação do cartão. Depois, o botão azul leva à aba certa com a ação já selecionada — nada roda sem um clique em ▶ lá. É também ele que avisa quando há arquivos esperando em 1_ENTRADA («Ingerir N arquivo(s) em lote»), linha que antes ficava no primeiro cartão. Ao lado do botão, «▶ Rodar tudo que falta». No rodapé, «🔄 Verificar novamente» e «📂 Abrir a pasta das bases».

CONFIRA — O ⏳ numa linha não é falha: é uma checagem que ainda está chegando, porque roda no Python do venv, fora desta janela. E o ○ cinza também não é erro: os passos 8 e 9 só fazem falta a quem redige glosas com IA local ou versiona o código.

Aba «1 · Baixar do CNPq» — a lista, o CPF, o nome e a tabela do CNPq

A primeira aba do fluxo. São duas perguntas diferentes, e misturá-las num cartão dentro da ingestão escondia a primeira: aqui você tem uma lista de pessoas e quer os currículos; na aba seguinte, os currículos já chegaram e falta lê-los para dentro da base. O botão desta aba baixa e já ingere — por isso ela vem antes, e por isso quem a usa normalmente nunca precisa da aba «2 · Ingestão». O Extrator, porta por porta, está em 16.8.

A aba «1 · Baixar do CNPq» do Assistente Lattes — Figura 15.2 — A aba «1 · Baixar do CNPq»: a linha do tempo das quatro fases no alto, o cartão «O que esta aba resolve» e os campos da lista e da tabela, os dois opcionais.

1 · Quem baixar. Duas entradas, e basta uma: «Arquivo da lista (opcional)», que é a sua planilha de identificadores, e «Tabela de IDs do CNPq (opcional)» com o campo «Nível», que é a tabela pública numero_identificador_lattes recortada por nível de formação. As duas juntas significam «filtre a minha lista por nível». Os dois campos dizem «(opcional)» — a pergunta do dono foi «qual a real necessidade do arquivo da lista?», e a resposta é nenhuma quando se entra pela tabela. «Conferir a lista» lê e confere sem tocar na rede; «Ver os níveis» mostra a distribuição dos códigos de nível do arquivo, e também não baixa nada.

2 · Acesso ao CNPq. Não há usuário nem senha: o CNPq libera o Extrator para o endereço IP fixo da instituição. «Testar o acesso» faz uma chamada leve antes de qualquer download; «Quais operações o CNPq aceita» diz qual nome de operação e qual nome de parâmetro o serviço aceitou — é o que se leva ao CNPq quando algo diverge; «Como pedir a liberação (gov.br)» abre o caminho do pedido.

3 · Baixar e ingerir. Três caixas e um botão. «Só o que mudou no CNPq desde a última extração» é a rotina mensal (--somente-alterados); «Guardar o ZIP bruto depois de ingerir (ocupa dezenas de GB)» é o --manter-bruto; «Baixar tudo de novo» refaz a extração inteira. «Baixar e ingerir» baixa em lotes de 100 e ingere cada lote na hora, no mesmo manifesto da aba de ingestão; «Parar» interrompe sem perder o que já entrou. Ao fim, «Abrir o relatório da extração» abre 5_RELATORIOS/0_extracao.xlsx.

ATENÇÃO — A caixa do ZIP bruto nasce desmarcada. O padrão é apagar depois de ingerir e conferir, e é preciso marcar a caixa — ou passar --manter-bruto no terminal — para guardar. A razão é do dono: não acumular milhões de currículos na máquina. O preço está dito na própria tela: apagado o bruto, uma reingestão motivada por mudança no leitor do XML exige baixar tudo de novo.

«Se o download parou no meio». Queda de rede, falta de luz, «Parar»: nada se perde, e a saída é sempre a mesma — clicar em «Baixar e ingerir» de novo, aqui. O cartão explica por que não é na aba de ingestão: o extrator guarda cada currículo em 1_ENTRADA/api/pasta_0001, pasta_0002… e a ingestão em lote lê apenas o nível de cima de 1_ENTRADA — ela não entra nessas subpastas, e diria «nada a ingerir» com centenas de currículos esperando dentro delas. Já o «Baixar e ingerir» reconcilia antes de começar: todo ZIP que está no disco e o registro não conhece é ingerido primeiro, sem pedir nada de novo ao CNPq; só depois ele volta a baixar, de onde parou. Quando há currículos nessa situação, uma linha âmbar diz quantos são e o botão «Ir para “Baixar e ingerir”» leva direto ao lugar.

Mais abaixo ficam o cartão «Pessoas fora da análise», explicado em 16.9, e o «Glossário».

Aba «2 · Ingestão» — os currículos que chegaram por fora

É a segunda porta, e a única aba em que 1_ENTRADA aparece na tela: os currículos chegaram por fora do CNPq — um ZIP que alguém mandou, a saída de um extrator antigo, uma pasta copiada de outra máquina — e é preciso lê-los para dentro de 2_CURRICULOS. A tela diz isso com todas as letras: se eles vieram pela aba «1 · Baixar do CNPq», já foram ingeridos, e esta aba não é o passo seguinte daquela — é o outro caminho. No mais, é a seção 16.6 em botões: «Inventariar 1_ENTRADA» conta o que está esperando, separando XML, ZIP e tabulares com o tamanho total; «Currículos por lote» é o tamanho do lote, de 100 a 5.000, com 1.000 de padrão; «Ingerir em lote» processa; «Parar» interrompe sem corromper o que já foi gravado.

A aba «2 · Ingestão» do Assistente Lattes — Figura 15.3 — A aba «2 · Ingestão»: a segunda porta, para os currículos que chegaram por fora do CNPq. É a única aba em que `1_ENTRADA` aparece na tela.

«Compactar lotes (todas as tabelas)» só fica habilitado quando há o que compactar, e a compactação é sempre global: funde todos os lotes, mantém apenas a versão que o manifesto aponta como atual e reescreve o manifesto. «Regravar amostras XLSX» refaz só as planilhas de conferência, sem processar nem compactar. «Conferir o parse» roda o inspetor sobre um arquivo ou pasta à sua escolha, antes de ingerir de verdade.

Abaixo dos botões há sempre o cartão «Comando», com a linha exata que será executada e um «Copiar». Nos atalhos, «Abrir 1_ingestao.xlsx» e «Abrir 2_CURRICULOS».

Por que a etapa 1 clássica não aparece aqui. A leitura de uma vez só — o botão pipeline.py --etapas ingestao — não fica ao lado da ingestão em lote, e isso é decisão, não esquecimento. As duas não são equivalentes: a leitura única reescreve 2_CURRICULOS inteira, não tem manifesto e não pode ser interrompida. Oferecê-las lado a lado, na mesma tela, a quem não programa é pedir que a pessoa escolha o pior caminho metade das vezes. A etapa continua existindo no pipeline — é a caixa «1 · Trazer» da aba «3 · Pipeline» e a linha python pipeline.py --etapas ingestao —, onde quem a marca sabe o que está fazendo, e é o que a demonstração usa.

O cartão «Baixar do CNPq pela lista de IDs», que ficava logo abaixo de «Ingerir em lote (recomendado)», virou a aba «1 · Baixar do CNPq» (acima, e em 16.8).

Mais abaixo, entre «Manutenção da base» e «Conferir um arquivo», fica o cartão «Pessoas fora da análise» — o mesmo que aparece na aba 1 —, explicado com figura em 16.9. O que se digita ali não vai para o log. No fim da aba ficam os «Atalhos», o cartão «Comando» com a linha exata que será executada e um «Copiar», e o «Glossário».

ATENÇÃO — A caixa «Apagar os arquivos de 1_ENTRADA depois de gravar» nasce desmarcada e nunca é herdada da sessão anterior. Apagar a origem depois da gravação conferida é o padrão do módulo e é proteção de dado pessoal em ação: o XML bruto do Lattes traz CPF, RG, data de nascimento e nome dos pais, campos que as dez tabelas canônicas nunca extraem. Manter os arquivos é para teste.

NA PRÁTICA — A primeira carga real: 50 currículos — 2 ZIP e 48 XML em ISO-8859-1, alguns com 7,4 MB — ingeridos em 5 segundos, 35.436 linhas nas dez tabelas, nenhuma falha.

Aba «3 · Pipeline» — as quatro etapas e o desempate

Lê-se de cima para baixo. Primeiro o que fazer: «Rodar tudo», «Rodar a seleção», «Parar agora», «Pré-voo» e «Mostrar configuração».

A aba «3 · Pipeline» do Assistente Lattes — Figura 15.4 — A aba «3 · Pipeline»: o que fazer no alto, as quatro etapas no meio, as opções gerais e o comando exato no fim.

Depois as quatro etapas, uma por linha, na ordem de execução: «1 · Trazer (leitura única de 1_ENTRADA)», «2 · Classificar (E5 + desempate opcional)», «3 · Medir (contagens por pesquisador)» e «4 · Vetorizar (texto consolidado → vetor E5)». Cada linha tem ícone de estado, caixa de seleção, barra de progresso, tempo estimado, um «Rodar só esta» e o arquivo que ela produz.

Valendo para a execução inteira: «Domínio», «Dispositivo» (auto, cuda ou cpu), «Desempate de precisão (reranker)» e «Demonstração com N currículos simulados». A demonstração gera currículos falsos numa raiz separada, <raiz>/_demo_assistente, e nunca se mistura à base real. Abaixo de tudo, o cartão «Comando» com a linha exata e o «Copiar».

Por que não há um cartão «Avançado» aqui. Houve um: mostrava cinco números lidos do config.py e dois botões que abriam código no editor — inúteis para quem não programa, porque ali não se mudava nada. O dono foi direto: «o que é esse avançado? Ele não faz nada!»; e, ao abri-lo, «na verdade isso é importante e deveria estar na aba IA, com todos os campos configuráveis». Foi o que aconteceu: o assunto virou o cartão «Calibração da classificação», na aba «5 · IA», agora com os campos editáveis (adiante, e em 20.14). Os dois botões de abrir código sumiram com o cartão.

ATENÇÃO — Mudar o desempate invalida o cache de classificação — tudo é reclassificado. E a classificação domina o tempo total (17). Parar no meio não corrompe nada: o que já foi gravado em disco permanece, e o que não foi é refeito na execução seguinte.

LEMBRE-SE — Confira 5_RELATORIOS/1_ingestao.xlsx antes de olhar qualquer resultado de classificação (14.3).

Aba «4 · Prospecta» — preparar o pacote e subir o painel

O Prospecta é o painel web que lê o que o pipeline gerou. Vive em prospecta/ e tem manual próprio, documentacao/Manual_Prospecta_2.0.docx; aqui ficam só os botões.

A aba «4 · Prospecta» do Assistente Lattes — Figura 15.5 — A aba «4 · Prospecta»: o estado do pacote por conteúdo, a pasta que o painel serve, o servidor, as contas de acesso e os quatro passos de «Publicar».

O cartão «Contas de acesso ao painel» na aba «4 · Prospecta» — Figura 15.5b — O cartão «Contas de acesso ao painel», na aba «4 · Prospecta», com o painel fora do ar: a janela fala com a API de administração, nunca com o arquivo do cofre, e por isso pede que o painel suba antes.

«Ler estado do pacote» diz quando 6_PROSPECTA foi preparada, com quantas pessoas, e se ela ainda corresponde ao que está no disco, comparando conteúdo e não data (adiante). «Pasta que o painel serve (PROSPECTA_RAIZ)» escolhe entre três: «a mesma pasta das bases (LATTES_RAIZ efetiva)», «demonstração (_demo_assistente)» e «outra pasta — a que eu indiquei em “Ambiente”», esta última habilitada só quando o campo correspondente da aba «7 · Ambiente» estiver preenchido. «Refazer mesmo se já existir (--forcar)» é o que faz o preparar trabalhar quando pessoas.parquet já existe. «Preparar pacote» monta o pacote: lê 2_CURRICULOS (inclusive as pastas de lote, deduplicadas pelo manifesto), 3_CLASSIFICADO e 4_RESULTADOS, e calcula dimensões, rede, BM25 e o índice denso.

Um nome só para a pasta que o painel serve. A pasta aparece com um nome na janela, e em um lugar só. Já teve dois — «Base a servir / real (LATTES_RAIZ efetiva)» aqui e «PROSPECTA_RAIZ / Raiz servida pelo Prospecta» na aba de caminhos —, e a confusão escondia um defeito: esta aba sobrescrevia em silêncio o que a outra oferecia, de modo que quem preenchia PROSPECTA_RAIZ e subia o painel daqui tinha o valor ignorado. Hoje o seletor é o valor de PROSPECTA_RAIZ, o rótulo é o mesmo nas duas abas, e a linha logo abaixo mostra a «PROSPECTA_RAIZ efetiva» — que quer dizer o que sobra depois de aplicar, nesta ordem, o campo preenchido na aba «7 · Ambiente», a variável de ambiente já definida no sistema e o padrão do config.py. Quando as duas abas divergem, a aba de caminhos avisa em âmbar, em vez de deixar o campo prometer um efeito que não acontece.

«Estado do pacote» responde por conteúdo, não por data. O caso que ensinou a diferença é do dono: ele rodou uma atualização em que tudo foi aproveitado do cache — nenhum currículo novo, nenhum alterado — e o cartão acusou «desatualizado (por data)». A causa era o *mtime*: uma execução que não muda nada ainda assim regrava os arquivos, e a data avança sozinha. Hoje o cartão compara a assinatura do conteúdo das pastas com a que o pacote guardou, e responde uma frase pronta, em português: «conferido em <hoje>: nada mudou desde o preparo de <data>» quando está em dia; «N currículos novos ou alterados desde o preparo de <data>» quando está desatualizado; e «não dá para saber: o pacote é antigo e não guardou assinatura do conteúdo — refazer a base resolve» quando é indeterminado, com um botão «Refazer o pacote (uma vez só, e passa a saber)». As duas datas convivem no cartão porque respondem a perguntas diferentes: «preparado em» diz o que você tem agora; «conferido em» diz se isso ainda está em dia.

No cartão «Servidor»: «Endereço» (127.0.0.1 é só esta máquina), «Porta» (8100), «Entrar sem senha (só avaliação)», «Subir o Prospecta», «Reiniciar», «Encerrar» e «Abrir no navegador». O selo ao lado da porta é conferido contra a porta real a cada cinco segundos: «parado», «subindo…», «no ar :8100» ou «no ar :8100 (de fora)» — este último quando quem ocupa a porta não foi subido por esta janela. «Preparar e subir» faz as duas coisas de uma vez.

No cartão «Publicar (pronto, não publicado)» ficam os quatro passos para o painel virar um endereço de verdade — e nenhum deles publica coisa alguma. 1 · Gerar o certificado: «Gerar certificado autoassinado» faz o par nesta máquina, sem baixar nada, e preenche os campos «Certificado (.pem)» e «Chave (.key)». 2 · Escolher endereço e porta: «Ir para Endereço e porta» leva aos controles do cartão «Servidor», logo acima. 3 · Subir com HTTPS: a caixa «Subir com HTTPS (usa o par acima)» e o botão do mesmo nome. 4 · Instalar como serviço do Windows: «Ver o comando do serviço» mostra e copia a linha de instalação, e «Estado do serviço» consulta se ele já existe. O Assistente não pede elevação: instalar um serviço exige privilégio de administrador, e a janela prefere lhe entregar o comando a pedir a senha.

Contas de acesso ao painel. Há um cartão para criar, alterar e excluir quem entra no Prospecta, sem sair desta janela: «1 · Entrar como administrador», «2 · Como a senha precisa ser», «3 · Criar acesso» e «4 · Contas cadastradas». O acesso é o CPF — validado no dígito verificador ao cadastrar, guardado sem pontuação, exibido formatado e mascarado na trilha de auditoria («•••.•••.•••-XX»), a mesma máscara de ingestao/exclusoes.py. Contas antigas, criadas com nome («admin», «maria.silva»), continuam valendo e aparecem na lista com a pastilha «acesso antigo»: a validação vale só na criação.

Duas regras dessa tela merecem estar escritas. A primeira: este cartão fala com a API de administração do painel, nunca com o arquivo do cofre — por isso o painel precisa estar no ar, e o cartão diz isso com o botão de subir ao lado. Não existem duas verdades sobre quem tem acesso. A segunda: a política de senha não mudou — o dono foi explícito («vamos continuar mantendo o padrão das senhas exigidas, mas deixe isso claramente informado»), e o que mudou é que as regras aparecem antes do campo, e a recusa diz qual delas falhou. O texto das regras vem do servidor, não está escrito na janela: se um dia o painel exigir outro tamanho mínimo, as duas telas mudam juntas.

LEMBRE-SE — A senha inicial não tem exceção. «1234» não é aceita nem para o primeiro acesso: ela é escolhida pelo administrador e precisa atender à política inteira. O que existe é a troca obrigatória no primeiro acesso — toda conta criada aqui nasce marcada, e a lista mostra quem «ainda não trocou». E o CPF não se edita: ele é a chave da conta; quem digitou errado exclui e cria de novo.

Por que um cartão, e não uma décima segunda aba. O dono pediu a administração de contas «nos dois lugares» — no painel e aqui. Ela cabe nesta aba por três razões, registradas no código: administrar contas exige o painel no ar, e o botão que o sobe está três centímetros acima; contas não são uma fase do trabalho (trazer · ingerir · pipeline · painel), são uma configuração do painel, como o endereço, a porta e o HTTPS, que já moram aqui; e a barra de abas já está no limite — onze rótulos pedem mais espaço do que a janela dá, e uma aba a mais cobraria esse preço das outras dez para servir a uma tarefa que se faz uma vez por contratação.

Um aviso em destaque fica no alto do cartão: sem HTTPS, o painel não deve sair de 127.0.0.1 — a senha de sessão viajaria legível pela rede local. O detalhe de cada passo está no Manual do Prospecta, seção 2.4.

ATENÇÃO — «Entrar sem senha» só funciona escutando em 127.0.0.1: o servidor recusa fora do loopback, a cada requisição, e o assistente nem tenta. Escolher 0.0.0.0 expõe o painel em HTTP sem criptografia a quem estiver na rede local — e uma faixa de aviso fica à vista enquanto esse endereço estiver escolhido. Encerrar o servidor pede confirmação mostrando os PIDs.

LEMBRE-SE — Rode «Preparar» de novo sempre que as etapas 3 ou 4 forem refeitas: o painel lê o pacote de 6_PROSPECTA, não os Parquet. Ele mostra por conta própria a tarja BASE SIMULADA ou DESATUALIZADA quando for o caso.

O servidor carrega os índices que o «Preparar» gravou, em vez de refazê-los a cada vez que sobe — medido na base de demonstração de 118 currículos, 14,3 s para remontar contra 0,29 s para carregar —, e aquece o modelo de vetores no arranque, para a primeira busca não pagar essa espera. A consequência prática é esta: rode «Preparar» sempre que as etapas 3 ou 4 forem refeitas. Nada mais recalcula sozinho.

Aba «5 · IA» — o Ollama, a calibração, o provedor das glosas e a chave

Cartão «Ollama (local)»: «URL do Ollama», «Verificar Ollama», «Iniciar Ollama» (habilitado só quando ele não responde), «Modelo a baixar» com «Baixar (ollama pull)», «Testar o modelo» e «Descarregar da GPU». É a seção 12 em botões.

O cartão «Calibração da classificação» na aba «5 · IA» — Figura 15.6 — A aba «5 · IA», com o cartão «Calibração da classificação» e os seus sete campos editáveis.

Cartão «Calibração da classificação». Vem da aba do pipeline, e com uma diferença que não é de lugar: aqui os campos são editáveis. São sete, cada um com o padrão de fábrica escrito ao lado, lido do próprio config.py: «Textos por vez na placa de vídeo» (LATTES_LOTE, padrão 32), «Margem entre o 1º e o 2º lugar» (LATTES_MARGEM, 0,015), «Exigência em textos curtos» (LATTES_LIMIAR_CURTO, 0,78), «Exigência em textos longos» (LATTES_LIMIAR_LONGO, 0,72), «Candidatos reexaminados no desempate» (LATTES_RERANKER_TOPK, 5), «Zona cinzenta · início» (LATTES_ZONA_MIN, 0,60) e «Zona cinzenta · fim» (LATTES_ZONA_MAX, 0,85). Campo em branco significa o padrão. O que você digitar vale na próxima execução do pipeline e vai no comando como variável de ambiente — o Assistente não edita o `config.py`, e é por isso que as seis variáveis novas tiveram de nascer no config.py primeiro (20.14).

ATENÇÃO — Mudar qualquer um dos seis reclassifica tudo, e a faixa vermelha do cartão diz isso antes de você digitar. Os seis são todos menos o primeiro: margem, os dois limiares, os candidatos do desempate e as duas pontas da zona cinzenta entram na assinatura do eixo, que é parte da chave do cache — mudar um deles reclassifica a base inteira na execução seguinte, sem precisar de --forcar. «Textos por vez na placa de vídeo» é o único que não entra: ele só diz quantos textos o modelo lê de uma vez, e é o que se reduz quando aparece «CUDA out of memory» (numa placa de 4 GB, 8 a 16). Era o «Lote do codificador», nome que, como o dono observou, não dizia nada a ninguém. Valor fora da faixa ou que não seja número é ignorado com aviso, e o pipeline usa o padrão — nunca derruba uma execução no meio de uma base.

No mesmo cartão ficou a nota de calibração, que antes morava num «Avançado» que ninguém abria: com a calibração de fábrica, medido na base real, «ambíguo» fica entre 67% e 99,8% em todos os eixos, e a margem 0,015 com a zona 0,60–0,85 manda cerca de 98% dos textos ao desempate. É por isso que ligar o desempate transforma minutos em horas. Para reduzir: aumentar a margem (0,03–0,05) e/ou estreitar a zona cinzenta. O botão «Voltar ao padrão de fábrica» esvazia os campos.

Cartão «Estágio TRL: o que recebe a pergunta». Fica logo abaixo do de calibração, desde 05/10/2026, e tem duas partes. Na primeira, treze caixas, uma por tipo de produção técnica, com as oito de entrega técnica marcadas — as que recebem estágio TRL no padrão (17.3). Na segunda, uma caixa só, «Perguntar o estágio também à atuação profissional», que nasce desmarcada. No padrão, nenhuma variável é mandada e vale o config.py; mudar as caixas faz o comando levar LATTES_TRL_TIPOS ou LATTES_TRL_ATUACAO, e a linha de baixo do cartão mostra exatamente o que vai. «↺ Voltar ao padrão» remarca as oito e desmarca a atuação. Ao contrário do cartão de calibração, este não reclassifica: a faixa azul diz o que rodar para valer — «2 · Classificar», «3 · Medir» e «4 · Vetorizar» na aba do pipeline, todas do cache, e depois o «Preparar» do Prospecta. A escolha volta na próxima vez que a janela abrir.

O cartão «Estágio TRL: o que recebe a pergunta» no Assistente, com as oito caixas da entrega técnica marcadas e a atuação profissional desmarcada — Figura 15.6b — O cartão «Estágio TRL: o que recebe a pergunta», no padrão: as oito caixas da entrega técnica marcadas, a atuação profissional desmarcada e nenhuma variável mandada (captura de 05/10/2026).

Cartão «Quem redige as glosas»: «Provedor das glosas», «Modelo», «Chave de API» — o campo nasce vazio a cada sessão e nunca mostra o que se digita —, «Guardar chave protegida» e «Esquecer chave». Cartão «Dispositivo e GPU»: «Dispositivo do pipeline» e «Ler GPU», que roda o nvidia-smi e mostra a placa e a memória usada — útil para descobrir quem ainda está carregado antes de uma execução longa.

ATENÇÃO — Duas regras, e são do projeto, não da configuração. A primeira: o provedor de nuvem vale só para a redação das glosas do dicionário, que é texto público de categorias. Não existe botão que envie currículo para fora, e a variável que ligaria IA em nuvem no Prospecta nunca é definida — ela é removida do ambiente de todo processo filho. A segunda: a chave fica cifrada pela proteção de dados do Windows em %LOCALAPPDATA%\AssistenteLattes\chaves.bin, fora do repositório e ilegível por outra conta ou máquina, e é injetada apenas no processo que redige as glosas. Se uma chave aparecer num log salvo, é defeito — avise.

O mascaramento vale para tudo o que entra no log, e não só para a chave: a senha do primeiro administrador, que o Prospecta imprime em claro ao subir pela primeira vez, aparece uma única vez numa janela «Anote agora» e tem os bytes apagados do arquivo assim que são lidos. Ver também 12.5 e 26.

Aba «6 · Dicionário» — planilha, cobertura, glosas e os pesos

«Abrir a planilha» abre o dicionário do domínio; «Abrir pasta dos backups», as cópias anteriores; «Validar / cobertura» roda a validação e responde no próprio cartão. Depois vêm os controles do assistente de glosas de 13.4: «Taxonomia», «No máximo N categorias», «Reescrever também as que já têm glosa (não revisadas)», «Simular (nada muda)», «Redigir glosas com IA» e «Parar». «Abrir glosas_geradas.xlsx» abre o relatório, cuja aba REVISAR_PRIMEIRO está descrita em 13.6.

Figura 15.7 — A aba «6 · Dicionário» do Assistente Lattes.

«Pesos da quantificação» é o segundo cartão da aba. Ele mostra quanto vale cada item na hora de virar nota — uma patente, uma orientação de doutorado, um artigo A1 — e é editável. São 16 grupos e 52 números, numa tabela que se abre grupo a grupo: «Produção técnica» abre em patente 5, software 3, material didático 0,8 e por aí; «Qualis do veículo» abre nos estratos das duas escalas. Cada número traz ao lado o padrão de fábrica e, quando difere dele, a marca MUDADO.

O cartão nasceu aqui, e não numa aba nova, por uma razão de natureza: peso é conhecimento de domínio, como a glosa de uma categoria. Uma patente valer mais que uma apostila é uma afirmação sobre a indústria brasileira — discutível e revisável; que caibam 32 textos na placa de vídeo não é. Por isso o arquivo mora ao lado do dicionário, em dominios/<domínio>/pesos.json, e o caminho dele aparece clicável no alto do cartão, junto da linha «em uso: padrão CNPq×CNI · v1 · 21/09/2026 · assinatura … · domínio industria».

O aviso vem antes do clique, não depois: mudar um peso recalcula todas as notas — é preciso refazer a quantificação (etapa 3) e o pacote do Prospecta, pelo botão «Preparar pacote» da aba «4 · Prospecta». A classificação não muda, porque ela chaveia por conteúdo e o conteúdo dos textos não mudou; por isso é rápido.

Três botões fecham o cartão: «Ler os pesos», que relê o arquivo; «Gravar os pesos», que sobe a versão, carimba a data de hoje e grava um arquivo completo; e «Voltar ao padrão de fábrica», que repõe os 52 números. Antes de gravar, o rodapé diz exatamente o que vai acontecer — «1 peso(s) mudado(s) e AINDA NÃO GRAVADO(S). Ao gravar: v2 de 21/09/2026, assinatura …». Toda recusa diz o motivo: digitar 0 em «patente» responde «peso tem de ser POSITIVO: zero apagaria o item da nota e negativo a inverteria. Para “sem efeito” use 1,0».

⚠ A janela não reimplementa a conta. Quem lê o perfil, mescla com o padrão de fábrica e calcula o carimbo e a assinatura é o próprio motor, prospecta/dimensoes.py, chamado por um subcomando dentro do ambiente virtual. Duas contas da mesma assinatura divergiriam no primeiro ajuste, e a auditoria do painel acusaria divergência à toa. E se o arquivo estiver quebrado, o motor pontua com o padrão de fábrica inteiro e diz que caiu — nunca com peso pela metade.

A aba «6 · Dicionário» com o cartão «Pesos da quantificação» — Figura 15.7b — A aba «6 · Dicionário», cartão «Pesos da quantificação»: os 16 grupos com a faixa aceita e o que cada um significa, o carimbo em uso no alto, o caminho clicável do `pesos.json` e o aviso de que mudar um peso recalcula todas as notas.

O cartão dos pesos com um grupo aberto e um peso marcado MUDADO — Figura 15.7c — O mesmo cartão com um grupo aberto: os pesos individuais com o padrão de fábrica ao lado, a marca MUDADO no que foi alterado e o rodapé dizendo o que a gravação vai fazer — «1 peso(s) mudado(s) e AINDA NÃO GRAVADO(S). Ao gravar: v2 de 21/09/2026».

LEMBRE-SE — Categoria com revisado = SIM nunca é alterada. Nem por este botão, nem por nenhuma opção desta aba (13.2).

NA PRÁTICA — O ciclo curto: ponha o limite em 3, clique em «Simular (nada muda)», leia as três glosas no log, ajuste ia/prompts.py e repita. Só então rode com o limite de verdade.

Aba «7 · Ambiente» — caminhos, venv, bibliotecas e GPU

Os cinco campos que mandam em tudo — «LATTES_RAIZ (pasta das bases)», «LATTES_TRABALHO (cache)», «PROSPECTA_RAIZ», «HF_HOME (cache dos modelos de IA)» e «LATTES_DOMINIO» — aparecem com o valor efetivo logo abaixo de cada campo, e campo em branco significa o padrão: o do config.py para os do projeto, o da Hugging Face para o HF_HOME. Ao lado, «💾 Salvar caminhos», «Conferir o que existe» e «Criar as pastas da raiz».

Figura 15.8 — A aba «7 · Ambiente» do Assistente Lattes: os caminhos, com a linha «em uso:» abaixo de cada campo.

«HF_HOME (cache dos modelos de IA)» é onde a Hugging Face guarda o E5 e o reranker depois de baixados (14.2). Vazio, vale o padrão, dentro do seu perfil do Windows; a linha cinza embaixo do campo mostra a pasta em uso e se cada modelo já está lá — «✓ E5 no cache · ○ reranker não baixado». O valor vai para todo processo que a janela dispara: o pipeline, o Prospecta, o download dos modelos e a conferência do passo 5. Numa máquina com várias contas, aponte para uma pasta fora do perfil, legível por todas (26, item 9) — nunca uma pasta sincronizada pelo OneDrive.

Bibliotecas: «↻ Conferir bibliotecas» lê as versões de dentro do ambiente virtual — é o subcomando --info-ambiente, não um palpite —, «Instalar as que faltam» instala as do pipeline e do painel, e «Instalar o torch (GPU ou CPU)» instala o PyTorch com o índice certo para esta máquina: lê a placa pelo nvidia-smi, mostra o comando e o tamanho do download e só roda depois da confirmação — o mesmo botão do passo 3 da aba 0 (9.3). Completam a aba «🐍 Qual Python está em uso», «📂 Abrir pasta do assistente», «📂 Abrir raiz» e «📂 Abrir _trabalho».

ATENÇÃO — A instalação errada do PyTorch, sem CUDA, é o erro que mais custa tempo (10.1). Confira a placa aqui ou na aba «5 · IA» antes da primeira execução longa, não depois dela.

Aba «8 · Testes» — as baterias que não tocam em dado real

«Teste de integração do pipeline» roda testes/test_integracao.py, a bateria completa de 15.1; «Autoteste do assistente» roda testes/test_assistente.py; e «Teste do Prospecta (test_preparar.py)», o do painel. Os rápidos são «Pré-voo», «Simular glosas» e «Rodar os rápidos em sequência». «Fumaça ponta a ponta (60 simulados, GPU)» exercita o fluxo inteiro com dados falsos, e «Ingerir sem apagar» roda a ingestão sobre uma «Pasta de teste» à sua escolha, sem apagar nada.

Figura 15.9 — A aba «8 · Testes» do Assistente Lattes.

Numa linha à parte, «▶ Teste de línguas (base carregada)» é a exceção da aba: não roda em pasta temporária — lê a base que a janela está usando, só para contar, e responde numa frase logo abaixo dos botões (17.8). Por isso não entra em «Rodar os rápidos em sequência».

CONFIRA — No fim do log, a linha «N/N verificações passaram». Qualquer falha traz o nome da verificação em português. Nenhuma dessas baterias toca em dado real nem chama IA; o teste de línguas lê a base, mas só conta.

Aba «9 · Git» — conferir o sensível antes de gravar

Leitura primeiro: «O que mudou» (git status --short), «Resumo (diff --stat)», «Últimos commits» e «Branch e remote».

Figura 15.10 — A aba «9 · Git» do Assistente Lattes.

Depois a barreira. «Conferir dado sensível» cruza os arquivos alterados e novos com os padrões proibidos — CNPQ_bases/, Documentos GECC/, *.parquet, *.xml, *.zip, chaves*, prefs.json, *.log, .env, usuarios.json, auditoria.jsonl e _cofre/ — e varre o diff atrás de trechos com cara de chave. A tabela mostra, arquivo por arquivo, se ele entra ou não no commit, e o que estiver marcado como SENSÍVEL fica de fora do git add. Só então «Mensagem do commit», «Gravar (add + commit)» e «Enviar (push)».

ATENÇÃO — Commit e push só quando alguém pedir, e sempre depois de conferir o dado sensível. O .gitignore não protege arquivo que já foi versionado uma vez.

Aba «10 · Comandos» — escrever um comando, sem sair da janela

As oito abas anteriores cobrem o que este manual manda fazer, cada botão montando uma linha conhecida. Esta cobre o resto: o comando que ainda não virou botão, uma pergunta específica ao git log, um script novo. Escreva no campo e tecle Enter — ou clique em «▶ Rodar». A saída vai para o mesmo log das outras abas, e «■ Parar» interrompe.

Figura 15.11 — A aba «10 · Comandos» do Assistente Lattes.

Três coisas que o assistente resolve por você, e que são a razão de a aba existir em vez de um PowerShell aberto por fora. A palavra python passa a ser o interpretador do ambiente virtual do projeto — sem isso ela cairia no primeiro do PATH, que nesta máquina é o atalho da Microsoft Store e não executa nada. O PYTHONIOENCODING já vem em utf-8, sem o qual os emojis do pipeline derrubam a execução antes da primeira linha útil. E o comando roda na raiz do repositório, de modo que um «cd» colado na frente é reconhecido e retirado — se apontar para outra pasta, ele é obedecido e o log diz de onde veio.

ATENÇÃO — O que se digita aqui não passa pela trava de «um de cada vez». Os botões das outras abas declaram o que vão usar (a base, a placa de vídeo) e o assistente recusa dois trabalhos que disputariam o mesmo recurso. Um texto livre não dá para adivinhar: se você mandar o pipeline por aqui enquanto ele já roda pela aba 3, as duas execuções escreverão na mesma base. O assistente reconhece os nomes dos programas do projeto e AVISA quando há algo em andamento, mas não bloqueia — a decisão fica com você.

O cartão «Comandos que você mais usa» traz seis atalhos de um clique: o pré-voo, a configuração efetiva, a conferência da raiz do Prospecta, as duas baterias de teste e o «Qual Python?». Pouse o mouse em qualquer um para ver o que ele faz e a linha exata que será executada. Acima deles, uma linha cinzenta mostra a pasta, o interpretador, a raiz das bases e qual PowerShell está instalado — é o que permite conferir em vez de confiar.

LEMBRE-SE — Comandos que apagam ou reescrevem pedem confirmação antes de rodar: Remove-Item, git reset --hard, --forcar, e também os dois nomes que neste projeto não têm volta — o manifesto registro_curriculos (a única prova de que um currículo foi ingerido, já que o XML de origem foi apagado) e a pasta _cofre (contas e auditoria do painel). O histórico guarda os 25 últimos comandos, entre sessões, e passa pela mesma máscara do log: um segredo colado por engano não fica em claro no disco.

O último cartão abre uma janela de PowerShell de verdade, já preparada do mesmo jeito. Ela existe por um limite honesto: o log desta janela mostra a saída, mas não tem teclado. Um comando que PERGUNTA alguma coisa — um git push pedindo usuário e senha — ficaria pendurado esperando uma resposta que ninguém pode digitar. Para esses casos, a janela separada.

Sem janela: quatro subcomandos

O mesmo arquivo responde a quatro perguntas em JSON, sem abrir janela nenhuma — úteis para diagnosticar uma máquina por telefone ou dentro de um script:

python ferramentas\assistente.py --info-ambiente
python ferramentas\assistente.py --modelos-ia
python ferramentas\assistente.py --sonda <raiz>
python ferramentas\assistente.py --validar-dicionario industria

--info-ambiente imprime as versões das bibliotecas, o torch, se o CUDA está visível e o nome e a memória da placa. --modelos-ia diz se o E5 e o reranker estão no cache da Hugging Face, com o tamanho e a pasta do cache, sem carregar o torch — é a leitura do passo 5 da Primeira configuração. --sonda imprime o estado de 2_CURRICULOS: o formato da base, quantos ids há, se são simulados e quantos lotes existem por tabela. --validar-dicionario imprime a cobertura do dicionário do domínio. São exatamente as leituras que a janela usa para se pintar.

O roteiro do primeiro dia, pelo assistente

Sete passos, nenhum terminal.

Instale o Python (8.1) — a única coisa que a janela não faz por você.
Dois cliques em «Assistente Lattes.vbs» (ou no atalho da área de trabalho).
Aba «0 · Início», cartão «Primeira configuração»: siga o passo em azul até o cartão virar uma linha verde — criar o venv (e reabrir), instalar o torch, instalar as bibliotecas, baixar os modelos, escolher a pasta das bases. Cada botão mostra o que vai fazer e pede confirmação; o andamento sai no log à direita.
Aba «3 · Pipeline»: «Demonstração com N currículos simulados» = 300 e «▶ Rodar tudo» — é o python pipeline.py --demonstracao 300 de 14.1.
Aba «2 · Ingestão»: «📂 Abrir 1_ENTRADA», deposite os XML/ZIP, «↻ Inventariar 1_ENTRADA», «▶ Ingerir em lote».
Aba «0 · Início»: «▶ Rodar tudo que falta» (classificar → quantificar → vetorizar → preparar → subir); confira 5_RELATORIOS/1_ingestao.xlsx antes de olhar qualquer classificação.
Aba «4 · Prospecta»: «🌐 Abrir no navegador».

(Opcional, quando for redigir glosas: aba «5 · IA», «Verificar Ollama».)

LEMBRE-SE — Cada botão desses roda um comando conhecido (15.1), e a linha exata aparece — no cartão «Comando» ou no log — antes de rodar. Copie-a para documentar um procedimento ou para agendar a execução.

8. O Python e o ambiente virtual

EM UMA FRASE — Primeiro o Python, uma vez por máquina; depois, uma pasta isolada com as bibliotecas deste projeto, para que ele não brigue com os outros.

8.1 · Instalar o Python (Windows)

O Python é o programa que faz todo o sistema funcionar — o pipeline, o painel e a própria janela do Assistente. É a única instalação feita à mão, uma vez por máquina: tudo o que vem depois o Assistente faz por botões (14.4). São cinco passos, uns dez minutos, e convém ter uns 10 GB livres no disco — o Python e o ambiente virtual ocupam pouco, mas o PyTorch com placa de vídeo leva 2,8 GB e os modelos de IA, 3,3 GB.

Passo 1 — baixe o instalador certo.

No navegador, abra https://www.python.org/downloads/windows/. Na lista, procure a versão mais recente do Python 3.13 — aparece como «Python 3.13.x», com um número no lugar do x — e clique em «Download Windows installer (64-bit)», logo abaixo dela.

Duas escolhas parecem iguais e não são. Não use o Python da Microsoft Store. E não pegue o 3.14: ele trocou o instalador clássico pelo «Python install manager», e este manual descreve o instalador do 3.13, a versão medida neste projeto.

Passo 2 — abra o arquivo baixado.

Ele fica na pasta Downloads, com um nome como python-3.13.x-amd64.exe. Dois cliques.

Passo 3 — marque o PATH e clique em «Install Now».

Na primeira tela, embaixo, marque «Add python.exe to PATH» — a caixa vem desmarcada, e é ela que faz o comando python funcionar em qualquer janela. Deixe «Use admin privileges when installing py.exe» como está. Então clique em «Install Now», em cima.

O «Install Now» instala só para o seu usuário, em %LOCALAPPDATA%\Programs\Python\Python313 — exatamente onde o lançador do Assistente procura. Se o Windows pedir uma senha de administrador que você não tem, feche o instalador, abra-o de novo e, desta vez, desmarque «Use admin privileges when installing py.exe»: essa caixa só instala o atalho py.exe para todas as contas, e nada neste manual depende dele.

Passo 4 — espere «Setup was successful».

Leva de um a três minutos. Se a tela final oferecer «Disable path length limit», clique nela: é inofensivo e evita erros com caminhos longos. Depois, «Close».

Passo 5 — confira.

Feche qualquer janela de terminal que já estivesse aberta — o PATH novo só vale para as janelas abertas depois da instalação — e siga 8.2. Quem não vai usar o terminal confere de outro jeito: dois cliques em Assistente Lattes.vbs, na raiz do repositório; se a janela abrir, o Python está pronto.

ATENÇÃO — Se, ao digitar python, abrir a Microsoft Store — ou não acontecer nada —, quem respondeu foi o atalho que o Windows traz de fábrica, e não o Python que você instalou. Duas saídas: desligue o atalho em Configurações → Aplicativos → Configurações avançadas de aplicativos → Aliases de execução de aplicativo (os dois do Python, «python.exe» e «python3.exe»), ou reinstale marcando «Add python.exe to PATH», o passo 3.

LEMBRE-SE — O Assistente não instala o Python porque precisa dele para abrir. Tudo o que vem depois — o ambiente virtual, o PyTorch, as bibliotecas, os modelos de IA e as pastas das bases — ele faz por botões, na Primeira configuração (14.4).

CONFIRA — Sem Python, os dois cliques no Assistente Lattes.vbs não abrem a janela: aparece a caixa «Não consegui iniciar o Python.», com a linha «Tentei: …» — o que o lançador procurou — e a orientação «Instale o Python 3.13 pelo instalador oficial (python.org), marcando "Add python.exe to PATH" — manual, seção 8.1 — ou crie o ambiente virtual pela aba 0 do Assistente depois de instalar o Python. Depois, tente de novo.» É esta seção. Com o Python instalado, os mesmos dois cliques abrem a janela.

8.2 · Conferir que o Python certo responde

Três perguntas, num PowerShell aberto depois da instalação (menu Iniciar → digite «PowerShell» → Enter). Digite uma linha por vez; embaixo de cada uma está a resposta certa.

python --version
# Python 3.13.x

python -c "import tkinter; print(tkinter.TkVersion)"
# 8.6

where.exe python
# C:\Users\<você>\AppData\Local\Programs\Python\Python313\python.exe   ← o primeiro da lista

A versão precisa começar por 3.13 (3.11 e 3.12 também funcionam; fora de 3.11 a 3.14 não há o PyTorch deste manual — 9.3). O Tkinter é o que desenha a janela do Assistente: vem com o instalador oficial, não se instala com pip, e responde 8.6. O caminho: where.exe lista, em ordem, todos os python.exe que o Windows encontra — e é o primeiro que vale. Ele precisa terminar em \Python313\python.exe; se o primeiro for …\Microsoft\WindowsApps\python.exe, é o atalho da Store (ATENÇÃO de 8.1).

ATENÇÃO — No PowerShell é where.exe, com o .exe. Sem ele, where é um comando do próprio PowerShell, que não procura programa nenhum e não responde nada.

LEMBRE-SE — Sem terminal, a mesma conferência está no Assistente: se a janela abriu, o Python e o Tkinter estão bons, e o passo 1 da «Primeira configuração» mostra a versão — «Python 3.13.x — o que abre esta janela».

Git é opcional — só para quem versiona o código (aba «9 · Git»): https://git-scm.com/download/win.

8.3 · O que é, e por que usar

Quando você instala uma biblioteca Python, ela vai por padrão para a instalação do sistema — compartilhada por todos os projetos da máquina. Isso cria um problema previsível: o projeto A precisa da versão 1.2 de uma biblioteca, o projeto B precisa da 2.0, e instalar uma quebra a outra.

Um ambiente virtual é uma pasta isolada com sua própria cópia do Python e suas próprias bibliotecas. O que você instala nele não afeta mais nada na máquina.

ANALOGIA — É a diferença entre guardar as ferramentas de todos os serviços numa gaveta só, e ter uma caixa por serviço. Na gaveta comum, alguém sempre leva a chave que você precisava.

8.4 · Onde criar

Vamos usar como exemplo a pasta de trabalho do projeto:

C:\0_Desenvolvimento\CNPQ

8.5 · Criar e ativar (Windows PowerShell)

Passo 1 — vá até a pasta do projeto.

cd C:\0_Desenvolvimento\CNPQ

Passo 2 — crie o ambiente virtual.

python -m venv venv

Isso cria a subpasta venv dentro de C:\0_Desenvolvimento\CNPQ. Leva alguns segundos e só precisa ser feito uma vez.

Passo 3 — ative o ambiente.

.\venv\Scripts\Activate.ps1

CONFIRA — O prompt passa a exibir (venv) no início:
(venv) PS C:\0_Desenvolvimento\CNPQ>
Esse prefixo é a única confirmação visual de que você está dentro do ambiente. Se ele não aparecer, o ambiente não está ativo — e tudo o que você instalar irá para o Python do sistema.

8.6 · O erro mais comum no PowerShell

Na primeira ativação, é provável que apareça:

.\venv\Scripts\Activate.ps1 : O arquivo não pode ser carregado porque a
execução de scripts foi desabilitada neste sistema.

Não é um defeito do projeto. O Windows bloqueia a execução de scripts por padrão, como medida de segurança. A solução é liberar apenas para o seu usuário:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Responda S (ou Y) à confirmação e tente ativar de novo. RemoteSigned permite rodar scripts locais e exige assinatura apenas nos baixados da internet — é a configuração recomendada, e não desprotege a máquina.

Isso é feito uma vez por usuário, não a cada projeto.

8.7 · Outros ambientes

Prompt de Comando (CMD):

venv\Scripts\activate.bat

Linux ou macOS:

source venv/bin/activate

8.8 · Levar o projeto para outro computador

Copiar a pasta não basta, e o que falta não está à vista. A primeira instalação deste projeto em outro computador — uma máquina do MGI, com placa AMD e sem NVIDIA — tropeçou em sete coisas diferentes. Nenhuma delas era defeito do código: eram coisas que a pasta copiada não consegue levar consigo, ou que ela leva quebradas. Esta seção é a lista, e o atalho que resolve a lista.

O atalho: dois cliques em Primeira configuracao.bat. Ele está na raiz do projeto, ao lado do Assistente Lattes.vbs. Abre uma janela preta que confere a máquina de cima a baixo, explica cada passo antes de agir e para quando a decisão é sua. Ele nunca apaga dado, nunca instala o Python sozinho e nunca baixa modelo sem perguntar; rodar duas vezes não estraga nada, e é o que se faz quando a internet cai no meio.

Por que existem dois arquivos. O trabalho está no Primeira configuracao.ps1; o .bat ao lado existe só para dar o duplo clique. Um .ps1 sozinho não executa com duplo clique no Windows — ele abre no bloco de notas —, e a política de execução costuma barrar script que veio de outra máquina (é o mesmo bloqueio de 8.6). O .bat resolve as duas coisas de uma vez: chama o PowerShell com -ExecutionPolicy Bypass, que libera a política só para aquela execução, sem mudar nada no sistema.

Sem terminal nenhum. Quem não usa o script não fica sem saída: a aba «0 · Início» do Assistente detecta e resolve os mesmos casos, um por passo, com botão e explicação em cada linha (14.4). O .bat é o caminho de quem quer ver tudo de uma vez, numa tela; o Assistente, de quem já deu os dois cliques na janela e quer ser conduzido.

Os nove passos do script, na ordem em que um depende do outro — é a mesma ordem do cartão «Primeira configuração» do Assistente (14.4), porque a ordem é a das dependências, não a do gosto de quem escreveu:

1. a pasta veio inteira?          6. as bibliotecas realmente importam?
2. o venv (junção? cópia morta?)  7. os modelos de IA estão no cache?
3. o Python e o tcl/tk            8. a base de currículos está aqui?
4. a placa: qual torch instalar   9. o serviço do CNPq responde?
5. instalar as bibliotecas

1 · O venv não é uma pasta: é uma junção. Uma junção é o atalho de pasta do Windows — um nome que aponta para outro lugar do disco. Neste projeto, venv\ aponta para um ambiente compartilhado fora da pasta (C:\Projetos_IA\venv_recruta, o mesmo de outros dois projetos). Copiada, a junção viaja quebrada: o nome continua ocupado e o destino ficou na máquina de origem. É um estado que engana todas as perguntas usuais — exists() e is_dir() seguem o atalho e respondem «não existe» —, e o python -m venv venv falha sempre, porque o nome já está tomado. O conserto é remover só o atalho (o destino não é tocado) e criar o ambiente desta máquina.

A recusa que vem com isso: quando o destino da junção existe neste computador, nem o script nem o Assistente removem o atalho. O motivo é concreto — nesta máquina de origem esse destino é o ambiente que três projetos compartilham, e apagar o vínculo «para desencalhar a instalação» deixaria os três sem ambiente. Destino vivo não tem botão: tem explicação, e a decisão é de uma pessoa. O mesmo vale se ali houver pasta de verdade.

2 · O venv copiado parece intacto e não roda. Se na máquina de origem o venv era pasta de verdade, ele chega inteiro — com Scripts\python.exe, com Lib, com tudo — e não roda uma linha. O motivo está escrito dentro dele: o arquivo pyvenv.cfg guarda home = <pasta do Python que o criou>, e é de lá que o ambiente pega a biblioteca padrão. Se esse Python não existe aqui, o python.exe de dentro morre no arranque, antes de qualquer import. Não há conserto — as bibliotecas de dentro também foram baixadas para a outra máquina. O que se faz é renomear para venv_quebrado e criar um ambiente novo: nada é apagado, e desfazer é renomear de volta.

3 · A placa de vídeo decide qual torch instalar. O requirements-medido.txt pede torch==2.11.0+cu128 — a versão com CUDA, que só funciona com placa NVIDIA. Numa máquina AMD ela instala, importa e nunca vê placa; pior, o pip pode falhar sem dizer o porquê. Por isso o script e o Assistente leem a placa antes de escolher: com NVIDIA, o índice cu128 (download de cerca de 2,8 GB); sem ela, o índice cpu (uns 115 MB). A leitura é a do Windows — a lista de placas do Win32_VideoController, que o Assistente obtém do registro em menos de um milissegundo —, e não o nvidia-smi: o nvidia-smi só responde quando há driver NVIDIA instalado, e por ele «máquina AMD» e «NVIDIA sem driver» davam a mesma resposta.

A consequência, em número, e com o limite do número: sem placa NVIDIA a classificação fica de 10 a 50 vezes mais lenta (10.1) — mas a extração e a ingestão não usam placa nenhuma e rodam igual. É isso que faz uma máquina sem NVIDIA continuar útil: ela baixa currículos do CNPq e monta as dez tabelas na mesma velocidade. Com muitos currículos, o caminho é classificar numa máquina com placa e trazer as tabelas prontas.

4 · Uma biblioteca faltava na lista. O requests não estava no requirements-medido.txt, e numa máquina limpa o Extrator do CNPq morria no import — aqui ele nunca aparecera porque o ambiente compartilhado já o tinha, trazido por outro projeto. Corrigido: requests==2.34.2 entrou na lista. É a razão do passo 6 do script, que importa cada biblioteca em vez de confiar no «instalado sem erro»: instalar e importar não são a mesma pergunta.

5 · Os modelos de IA podem ir de pendrive. O E5 e o reranker somam cerca de 3,8 GB e não estão no repositório. Copiar a pasta de modelos da máquina de origem num pendrive é mais rápido que baixar e funciona sem internet: na máquina nova, aponte o HF_HOME para a pasta copiada (campo «HF_HOME (cache dos modelos de IA)», aba «7 · Ambiente»; pelo terminal, a variável de ambiente). A alternativa é deixar o passo 5 da primeira configuração baixar. Sem os modelos o sistema abre e funciona, mas só com busca por palavra exata.

6 · A base de currículos não vem no git. CNPQ_bases\ está fora do repositório porque currículo é dado pessoal, e numa máquina nova a ausência dela é o combinado, não um defeito. A primeira configuração diz isso em vez de reclamar, e o passo 6 do Assistente oferece escolher onde a base vai ficar. Para experimentar sem base real existe a dados_demo\, sintética do primeiro ao último campo (27).

7 · O endereço do serviço do CNPq estava errado — e nunca existiu. O material do workshop trazia https://ws.cnpq.br/WSCurriculo/WSCurriculo, e o dono só descobriu ao tentar extrair da máquina nova: o servidor DNS autoritativo do próprio CNPq responde «domínio inexistente» para ws.cnpq.br. Três coisas estavam erradas ao mesmo tempo — o host, o caminho e o esquema. O endereço correto é http://servicosweb.cnpq.br/srvcurriculo/WSCurriculo?wsdl: responde HTTP 200 e devolve o WSDL de verdade, que confirmou as oito operações, o parâmetro id, o estilo rpc e o namespace http://ws.servico.repositorio.cnpq.br/. Ele já é o padrão do config.py (16.8); quem precisar de outro usa o campo «LATTES_WS_URL (Extrator)» da aba «7 · Ambiente».

Duas coisas que o mesmo passo separa, porque o conserto de cada uma é com gente diferente: o WSDL é público — ele responde de qualquer lugar, e é o que o passo 9 testa —, mas as chamadas de dados exigem que o IP de saída da máquina esteja habilitado pelo CNPq. O script imprime o IP público que o mundo vê, porque ele costuma não ser o que o TI informou: trocar de tomada, de andar ou usar Wi-Fi pode mudá-lo.

ATENÇÃO — O que a primeira configuração nunca faz, de propósito: apagar dado, instalar o Python sozinho, baixar modelo sem perguntar, ou tocar num venv que esteja funcionando. Se ela recusar uma remoção, a recusa é a resposta — não é um passo que faltou.

LEMBRE-SE — A ordem completa numa máquina nova: Primeira configuracao.bat (ou a aba «0 · Início», 14.4) → os modelos, de pendrive ou baixados → escolher a pasta das bases → os currículos, pelo Extrator (16.8) ou pela pasta 1_ENTRADA (16.6). Só o primeiro passo é obrigatório antes de todos os outros.

9. Instalar as bibliotecas

EM UMA FRASE — Instale tudo de uma vez, na ordem certa, e só depois gere o requirements.txt.

ATENÇÃO — Use sempre python -m pip, nunca pip sozinho.

pip sozinho pode apontar para o Python do sistema mesmo com o ambiente ativo, dependendo de como o PATH está configurado. O resultado é confuso: a instalação diz que deu certo, e o projeto não encontra a biblioteca. python -m pip usa o interpretador que está de fato ativo — sempre.

9.1 · O que cada biblioteca faz aqui

Antes de instalar, vale saber o que se está instalando. Nenhuma destas bibliotecas está no projeto por hábito: cada uma resolve um problema específico, e o manual indica onde ela é usada.

Obrigatórias — o pipeline não roda sem elas

Biblioteca	Para que serve neste projeto	Onde é usada
`torch` (PyTorch)	O motor de cálculo que roda o modelo de vetores. É ele que decide se o trabalho vai para a placa de vídeo ou para o processador.	`semantica/vetores.py`
`sentence-transformers`	A camada que carrega o modelo E5 e transforma texto em vetor com uma chamada só. Também traz o `CrossEncoder`, usado no desempate.	`vetores.py`, `reranker.py`
`pandas`	A tabela em memória. Todas as dez tabelas do currículo, os CSVs classificados e as contagens são objetos do pandas.	todo o pipeline
`numpy`	A matemática dos vetores: similaridade, top-K, ordenação. É o que torna viável comparar 500 mil textos com 295 categorias.	`vetores.py`, `classificador.py`
`pyarrow`	Lê e grava os arquivos `.parquet` — o formato em que ficam os dados completos, com tipos preservados.	`nucleo/arquivos.py`
`openpyxl`	Lê e grava os arquivos `.xlsx` — o dicionário de entrada e todos os relatórios em Excel.	`planilha.py`, `arquivos.py`

LEMBRE-SE — Instala-se só o torch. Os tutoriais da internet costumam trazer, no mesmo comando, mais dois pacotes do PyTorch — um de imagem e um de áudio. O pipeline não usa nenhum dos dois, o ambiente medido (requirements-medido.txt) não os tem, e cada um é mais um download que pode travar: os comandos deste manual os deixam de fora.

Para trabalhar no notebook

Biblioteca	Para que serve	Quando instalar
`jupyter`	O ambiente de notebook em si — o servidor e a interface no navegador.	se você for usar o Jupyter (seção 11)
`ipykernel`	Registra o ambiente virtual como um kernel, para o notebook enxergar as bibliotecas do projeto. Sem ele o notebook usa o Python do sistema.	sempre, junto com o Jupyter

Opcionais — só para a descoberta de temas (seção 20.13)

Biblioteca	Para que serve	Consequência de não instalar
`umap-learn`	Reduz os vetores de mais de mil dimensões para cerca de dez, preservando a vizinhança. É o passo ① da descoberta.	a descoberta de temas não roda; o resto do pipeline funciona normalmente
`hdbscan`	Encontra grupos densos entre os itens `Indefinido`, e marca como ruído o que estiver espalhado. É o passo ②.	idem
`scikit-learn`	Fornece o cálculo de termos característicos (c-TF-IDF) que nomeia cada grupo encontrado. É o passo ③.	idem

Opcionais — só para redigir glosas com um modelo de nuvem (seção 12.5)

Biblioteca	Provedor	Quando instalar
`google-generativeai`	Google Gemini	só se `provedor = "google"`
`anthropic`	Anthropic Claude	só se `provedor = "anthropic"`
`openai`	OpenAI GPT	só se `provedor = "openai"`

Nenhuma delas é necessária para o padrão do projeto, que é o Ollama — e o Ollama não exige biblioteca Python nenhuma: o sistema fala com ele por HTTP, usando o urllib que já vem no Python.

NA PRÁTICA — Instalação mínima para classificar currículos: torch + sentence-transformers + pandas + numpy + pyarrow + openpyxl. Todo o resto é conveniência (notebook), exploração (descoberta) ou redação de glosas (nuvem).

O que vem junto sem você pedir. O sentence-transformers puxa como dependências o transformers e o huggingface_hub (baixam e executam o modelo), o tokenizers (parte o texto em pedaços que o modelo entende) e o safetensors (formato dos pesos do modelo). Você não os instala nem os chama diretamente — mas eles aparecem no requirements.txt, e agora não são um mistério.

9.2 · Ordem de instalação

A ordem importa em um ponto: o PyTorch deve ser instalado antes do sentence-transformers. Se você instalar na ordem inversa, o sentence-transformers puxa a versão de CPU do PyTorch como dependência, e ela sobrescreve a versão com GPU que você queria.

1º  PyTorch (com suporte a GPU)     ← primeiro, sempre
2º  Bibliotecas do pipeline
3º  Jupyter
4º  Opcionais (calibração e descoberta)
─────────────────────────────────────
5º  requirements.txt                 ← só no fim, com tudo instalado

9.3 · Passo 1 — PyTorch com suporte a GPU

O PyTorch não vem do endereço padrão do pip: cada tipo de máquina tem um índice próprio, e o que muda é o fim do endereço — cu128 para placa NVIDIA, cpu para quem não tem. Escolha um dos dois comandos. A versão fica fixada em 2.11.0, a medida neste projeto (requirements-medido.txt): sem ela, o pip escolheria sozinho a mais nova que encontrasse — que não é a medida.

Placa NVIDIA (o caso desta máquina):

python -m pip install torch==2.11.0 --index-url https://download.pytorch.org/whl/cu128

Download de cerca de 2,8 GB — de 5 a 30 minutos, conforme a internet. Vale para driver com «CUDA Version» 12.0 ou mais novo (como ler, logo abaixo).

Sem placa NVIDIA (só processador):

python -m pip install torch==2.11.0 --index-url https://download.pytorch.org/whl/cpu

Cerca de 115 MB. Tudo funciona; a classificação fica de 10 a 50 vezes mais lenta (10.1).

Qual é o seu caso. Rode o nvidia-smi no PowerShell:

nvidia-smi

Se o PowerShell disser que não reconhece o nome nvidia-smi, a máquina não tem placa NVIDIA visível — use o índice cpu. Se o quadro aparecer, a primeira linha traz, à direita, a «CUDA Version»: a versão mais nova do CUDA que o driver aceita. Nesta máquina (RTX 2050, 4 GB):

| NVIDIA-SMI 595.79   Driver Version: 595.79   CUDA Version: 13.2 |

12.0 ou mais → índice cu128: as rodas para CUDA 12.8 rodam em qualquer driver da série 12 ou mais nova. Abaixo de 12 → driver antigo: atualize em https://www.nvidia.com/drivers e rode o nvidia-smi de novo; enquanto isso, o índice cpu funciona.

ATENÇÃO — Se você não souber qual tem, abra o Gerenciador de Tarefas → Desempenho no Windows. As placas aparecem como “GPU 0”, “GPU 1”, com o nome do fabricante. Placas integradas Intel não servem para acelerar este trabalho; procure por NVIDIA ou AMD dedicada.

Python × índice — o que cada endereço oferece:

Índice	Quando usar	Versão do torch	Python
`cu128`	placa NVIDIA com «CUDA Version» 12.0 ou mais	2.11.0 — a medida neste projeto	3.11, 3.12, 3.13 e 3.14
`cpu`	sem placa NVIDIA	2.11.0	3.11, 3.12, 3.13 e 3.14
`cu118`	driver antigo (abaixo de 12), como último recurso — não medido	até 2.7.1	até 3.13; nada para 3.14
`cu121`	não use — era o índice das versões anteriores deste manual	até 2.5.1	nada para 3.13 nem 3.14

Para o cu118, troque o fim do endereço e tire o ==2.11.0 — ele não tem essa versão.

ATENÇÃO — ERROR: No matching distribution found for torch quer dizer que o índice do comando não tem o torch para a sua versão do Python — não é falta de internet nem erro de digitação. É o que acontece com o índice cu121, o das versões anteriores deste manual, num Python 3.13: a versão mais nova que ele oferece é a 2.5.1, anterior ao 3.13. A correção é o comando de cima, com cu128 (ou cpu) e torch==2.11.0. Se o erro continuar, confira a versão do Python (8.2): fora de 3.11 a 3.14, instale o 3.13 (8.1).

AMD, Linux e Apple — não medido neste projeto. Os comandos abaixo ficam como referência; nenhuma bateria deste projeto rodou neles.

AMD no Windows (via DirectML):

python -m pip install torch
python -m pip install torch-directml

AMD no Linux (via ROCm):

python -m pip install torch --index-url https://download.pytorch.org/whl/rocm6.0

Apple Silicon (M1/M2/M3):

python -m pip install torch

LEMBRE-SE — Pelo Assistente, é o passo 3 da Primeira configuração (14.4): o botão «Instalar o torch» lê o nvidia-smi, escolhe entre cu128 e cpu, mostra o comando e o tamanho do download e só roda depois da sua confirmação.

9.4 · Passo 2 — bibliotecas do pipeline

python -m pip install pandas numpy pyarrow openpyxl sentence-transformers

9.5 · Passo 3 — Jupyter

python -m pip install jupyter ipykernel

9.6 · Passo 4 — opcionais

Necessárias apenas para a calibração e a descoberta de temas:

python -m pip install scikit-learn umap-learn hdbscan

9.7 · Tudo de uma vez

Se preferir um bloco único, com a ordem já correta (sem placa NVIDIA, troque cu128 por cpu — 9.3):

cd C:\0_Desenvolvimento\CNPQ
.\venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install torch==2.11.0 --index-url https://download.pytorch.org/whl/cu128
python -m pip install pandas numpy pyarrow openpyxl sentence-transformers
python -m pip install jupyter ipykernel
python -m pip install scikit-learn umap-learn hdbscan

9.8 · Passo 5 — gerar o `requirements.txt`

Só depois de tudo instalado e verificado. Este arquivo registra exatamente quais bibliotecas e versões o projeto usa, e serve para reproduzir o mesmo ambiente em outra máquina.

python -m pip freeze > requirements.txt

ATENÇÃO — Gerar o requirements.txt cedo demais é um erro comum. Se você o gerar antes de instalar o PyTorch com GPU, ele congela a versão de CPU — e a máquina seguinte, ao restaurar o ambiente, herda o problema sem ninguém perceber.

Restaurar em outra máquina:

python -m pip install -r requirements.txt

ATENÇÃO — O requirements.txt gerado por pip freeze não preserva o --index-url do PyTorch. Numa máquina nova, instale o PyTorch primeiro, pelo comando da seção 9.3, e só depois rode o install -r.

9.9 · Desativar e recriar

deactivate

O prefixo (venv) desaparece e você volta ao Python do sistema.

Se algo der muito errado, a saída mais rápida é apagar e refazer. Nada de importante se perde: o ambiente virtual contém apenas bibliotecas, nunca o seu código nem os seus dados.

deactivate
Remove-Item -Recurse -Force venv
python -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install torch==2.11.0 --index-url https://download.pytorch.org/whl/cu128
python -m pip install -r requirements.txt

ATENÇÃO — Nunca versione a pasta venv. Ela tem centenas de megabytes, é específica do sistema operacional e é inteiramente reconstruível a partir do requirements.txt. Se o projeto usar Git, inclua no .gitignore:
venv/
__pycache__/

10. Forçar o uso da GPU

EM UMA FRASE — A placa de vídeo torna o processamento de 10 a 50 vezes mais rápido, e a instalação errada faz tudo cair no processador sem avisar.

10.1 · Por que isso importa tanto

A etapa 2 é a mais demorada do pipeline, e o que ela faz — converter texto em vetores — é exatamente o tipo de cálculo em que uma placa de vídeo é muitas vezes mais rápida que um processador.

A diferença não é de conforto, é de viabilidade:

Dispositivo	10 mil currículos	100 mil currículos
GPU dedicada	minutos a poucas horas	horas
Processador (CPU)	horas	dias

ATENÇÃO — O modo de falha é silencioso. Se o PyTorch instalado for a versão de CPU, ou se o driver estiver desatualizado, a biblioteca simplesmente usa o processador. Não há erro, não há aviso. A pessoa conclui que “o modelo é lento assim” e espera seis horas pelo que levaria vinte minutos.

É por isso que a checagem abaixo não é opcional.

10.2 · Confira se a GPU está sendo vista

Com o ambiente ativo, rode:

python -c "import torch; print('GPU disponível:', torch.cuda.is_available()); print('Placa:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'nenhuma')"

Resultado desejado:

GPU disponível: True
Placa: NVIDIA GeForce RTX 4070

Se aparecer False:

Causa provável	Solução
PyTorch de CPU instalado	Reinstale pelo comando da seção 9.3, com o `--index-url` correto
Driver da placa desatualizado	Atualize pelo site do fabricante
Placa integrada Intel apenas	Não há aceleração possível; use `dispositivo = "cpu"`
Ambiente virtual errado	Confira o `(venv)` no prompt

10.3 · Forçar no pipeline

O sistema tem um parâmetro dedicado em config.py:

dispositivo: str = "auto"

Valor	Efeito
`"auto"`	Descobre sozinho: usa GPU se houver, processador se não
`"cuda"`	Força GPU NVIDIA — ou AMD no Linux, via ROCm
`"mps"`	Força GPU Apple Silicon
`"directml"`	Força GPU AMD/Intel no Windows
`"cpu"`	Força processador

ATENÇÃO — Forçar é melhor que confiar. Com "auto", uma instalação errada cai no processador em silêncio. Com "cuda" explícito, você recebe um erro claro se a GPU não estiver disponível — o que é infinitamente preferível a uma espera inexplicável.

Em produção, deixe explícito.

Também é possível definir sem editar o arquivo:

$env:LATTES_DISPOSITIVO = "cuda"

10.4 · Confirme na execução

O pipeline anuncia onde está rodando, logo ao carregar o modelo:

🧠 Carregando modelo vetorial: intfloat/multilingual-e5-large-instruct
⚡ Dispositivo: GPU · NVIDIA GeForce RTX 4070 · 12.0 GB

Se aparecer:

⚡ Dispositivo: PROCESSADOR (CPU) — muito mais lento; confira a instalação do PyTorch

…interrompa e volte à seção 10.2. Vale muito mais gastar cinco minutos ali do que descobrir o problema no fim de uma execução longa.

CONFIRA — O comando python pipeline.py --pre-voo também mostra o dispositivo detectado, antes de processar qualquer coisa. É o primeiro comando a rodar em qualquer máquina nova.

10.5 · Se a memória da placa estourar

Erro típico:

torch.cuda.OutOfMemoryError: CUDA out of memory

Significa que o lote é grande demais para a sua placa. Reduza em config.py:

lote: int = 16     # ou 8, em placas de 4 GB

O resultado da classificação é idêntico com qualquer valor de lote — muda apenas a velocidade e o consumo de memória.

12. Instalar o Ollama e o modelo de linguagem

EM UMA FRASE — O Ollama roda um modelo de linguagem na sua máquina, de graça, sem que nenhum texto saia do computador.

Opcional: só quem vai redigir glosas com IA local precisa dele — é o passo 8 da Primeira configuração (14.4). Nada do pipeline depende dele: classificar, medir e vetorizar funcionam sem o Ollama.

12.1 · Para que ele serve aqui

O modelo de linguagem não classifica currículos. Ele é usado por uma única ferramenta: o assistente que redige as glosas do dicionário (seção 13).

ATENÇÃO — A separação é deliberada. Classificar precisa ser determinístico e auditável: mesmo texto, mesmo resultado, sempre. Um modelo de linguagem daria respostas ligeiramente diferentes a cada execução, e não haveria como explicar uma decisão a um comitê.

Redigir glosa é o oposto: é trabalho de texto, sem resposta única correta, e o resultado passa por revisão humana antes de valer.

12.2 · Instalar

Windows / macOS: baixe o instalador em https://ollama.com/download e execute. Ele se instala como serviço e sobe sozinho com o sistema.

Linux:

curl -fsSL https://ollama.com/install.sh | sh

CONFIRA — Abra um terminal novo e rode:
ollama --version
Se aparecer um número de versão, está instalado.

12.3 · Baixar o modelo

O padrão do projeto é o Gemma 2, do Google. Cerca de 5,4 GB.

ollama pull gemma2

Alternativas, conforme a sua máquina:

Modelo	Comando	Tamanho	Quando usar
Gemma 2	`ollama pull gemma2`	~5,4 GB	padrão — bom equilíbrio
Gemma 2 grande	`ollama pull gemma2:27b`	~16 GB	placa de 24 GB ou mais
Qwen 2.5	`ollama pull qwen2.5:14b`	~9 GB	forte em texto técnico
Gemma 4	`ollama pull gemma4:12b`	~8 GB	geração mais recente
Gemma 2 pequeno	`ollama pull gemma2:2b`	~1,6 GB	máquina modesta

ATENÇÃO — O modelo precisa caber na memória da placa de vídeo. Numa placa de 4 GB, o gemma2 padrão já fica apertado — se a resposta demorar demais ou falhar, use gemma2:2b. O Ollama também roda no processador, mas fica bem mais lento.

12.4 · Verificar se o Ollama está pronto

Três formas de conferir: pelo terminal, pelo notebook e pelo próprio sistema. Todas respondem à mesma pergunta — “o Ollama está no ar e o modelo que eu quero está baixado?”.

NO TERMINAL (PowerShell)

ollama --version               # está instalado?
ollama list                    # quais modelos estão baixados?
ollama run gemma2 "Diga olá"   # o modelo responde?

NO NOTEBOOK — forma rápida

A exclamação manda o comando para o terminal do sistema sem sair do notebook:

!ollama list

ATENÇÃO — Não use !ollama run gemma2 "Diga olá" no notebook. Esse comando abre uma sessão interativa, que fica esperando a próxima pergunta — e a célula trava, sem devolver o controle. Para testar a resposta do modelo pelo notebook, use uma das duas formas abaixo.

NO NOTEBOOK — a verificação que o próprio sistema faz

Esta é a melhor: usa exatamente o mesmo código que o assistente de glosas executa antes de trabalhar, e devolve a mesma mensagem de erro — já escrita para ser lida por quem vai resolver o problema.

import sys
sys.path.insert(0, r"C:\0_Desenvolvimento\CNPQ\lattes_pipeline")

from config import CFG
from ia.provedores import Ollama

provedor = Ollama(modelo=CFG.ia.modelo, url=CFG.ia.ollama_url)
ok, mensagem = provedor.disponivel()

print("✅" if ok else "❌", mensagem)

Saída quando está tudo certo:

✅ Ollama ativo · modelo 'gemma2' disponível

Saída quando o Ollama está rodando mas falta o modelo — repare que ele já entrega o comando da correção:

❌ O Ollama está rodando, mas o modelo 'gemma2' não foi baixado.
   Baixe com:  ollama pull gemma2
   Modelos presentes: llama3:latest

Saída quando o serviço não está no ar:

❌ Não consegui falar com o Ollama em http://localhost:11434.
   Confira se ele está instalado e rodando (veja o manual).
   Teste rápido:  ollama list

NO NOTEBOOK — testar a resposta do modelo de verdade

Se quiser ir além da checagem e ver o modelo escrever:

resposta = provedor.conversar(
    sistema="Você responde em uma frase curta, em português.",
    usuario="Diga olá.",
)
print(resposta)

A primeira chamada demora mais: o Ollama carrega o modelo na memória da placa. As seguintes são rápidas.

NO NOTEBOOK — perguntar direto ao serviço, sem o projeto

Útil para depurar quando nem o import está funcionando:

import json, urllib.request

with urllib.request.urlopen("http://localhost:11434/api/tags", timeout=5) as r:
    modelos = json.loads(r.read())["models"]

for m in modelos:
    print(f"{m['name']:24s} {m['size'] / 1e9:5.1f} GB")

Se esta célula levantar erro de conexão, o problema é o serviço do Ollama — não o Python, não o kernel, não o projeto.

CONFIRA — O assistente de glosas faz essa verificação sozinho, antes de qualquer trabalho, e diz exatamente o que falta:
🤖 Ollama ativo · modelo 'gemma2' disponível
Se algo estiver errado, ele mostra o comando exato para corrigir. Ou seja: rodar o assistente é, por si só, um teste do Ollama.

LEMBRE-SE — O Ollama é um serviço, não uma biblioteca Python. Ele roda fora do ambiente virtual, sobe junto com o sistema operacional e responde por HTTP na porta 11434. Por isso ele não aparece no pip list e não é afetado por recriar o venv.

12.5 · Se preferir usar um serviço de nuvem

O Ollama é o padrão porque é gratuito e privado. Mas modelos de nuvem são maiores e redigem melhor. O sistema aceita três:

Provedor	Modelo padrão	Chave (variável de ambiente)	Onde obter
Google	`gemini-2.0-flash`	`GOOGLE_API_KEY`	https://aistudio.google.com/apikey
Anthropic	`claude-sonnet-4-5`	`ANTHROPIC_API_KEY`	https://console.anthropic.com/settings/keys
OpenAI	`gpt-4o-mini`	`OPENAI_API_KEY`	https://platform.openai.com/api-keys

Instale a biblioteca do provedor escolhido:

python -m pip install google-generativeai    # Google
python -m pip install anthropic              # Anthropic
python -m pip install openai                 # OpenAI

Defina a chave. Só na sessão atual do PowerShell:

$env:ANTHROPIC_API_KEY = "sua-chave-aqui"

Permanentemente, para o seu usuário:

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sua-chave", "User")

(Feche e reabra o PowerShell para a mudança valer.)

ATENÇÃO — Nunca escreva a chave dentro de um arquivo do projeto. Chave em código vaza no primeiro git push, e chave vazada é chave usada por outra pessoa, na sua conta. O sistema lê as chaves exclusivamente de variáveis de ambiente, e não há como configurá-las de outro jeito — isso é proposital.

Escolha o provedor em config.py:

provedor: str = "anthropic"      # ollama | google | anthropic | openai
modelo:   str = "claude-sonnet-4-5"

Ou, sem editar arquivo:

python ferramentas/construir_glosas.py --provedor anthropic

LEMBRE-SE — Serviços de nuvem cobram por uso e enviam o texto para fora da sua máquina. Se a base contiver dado sensível, ou se houver restrição institucional de sigilo, use o Ollama.

13. O assistente de glosas

EM UMA FRASE — Ele escreve o rascunho de cada glosa; você revisa e aprova. O que você aprova, ele nunca mais toca.

13.1 · O que ele faz, e o que não faz

Faz: percorre o dicionário, monta uma instrução técnica para cada categoria — incluindo as categorias irmãs do mesmo agrupador — e pede ao modelo uma glosa escrita de forma contrastiva.

Não faz: substituir a curadoria humana. Ele produz um rascunho qualificado, o que reduz muito o trabalho de escrever do zero. A revisão continua sendo o passo que determina a qualidade final.

ANALOGIA — É a diferença entre receber uma minuta e receber uma folha em branco. A minuta acelera; ela não decide.

13.2 · A regra inviolável

ATENÇÃO — Categoria com revisado = SIM nunca é alterada. Nem com --aprimorar, nem com qualquer outra opção.

O motivo é de confiança: se o script pudesse sobrescrever o trabalho de revisão, ninguém o usaria. Uma tarde de curadoria apagada por engano custa mais do que toda a automação economiza.

Para reescrever uma glosa já revisada, mude revisado para NAO na planilha. É um ato deliberado e visível.

13.3 · Por que o assistente recebe as categorias irmãs

Esta é a decisão de projeto que mais afeta a qualidade do resultado.

Uma glosa escrita no vácuo sai genérica — não por incapacidade do modelo, mas por falta de informação. Ele não tem como saber de que precisa se distinguir.

O assistente entrega, junto com o pedido, todas as categorias do mesmo agrupador com suas glosas atuais. O modelo então enxerga a vizinhança e consegue escrever a fronteira.

NA PRÁTICA — Ao redigir «Metalurgia e Siderurgia», o assistente informa que existem «Mineração e Beneficiamento Mineral» e «Metalmecânica e Bens de Capital» no mesmo grupo. A glosa resultante diz onde uma termina e a outra começa — que é exatamente o que separa os vetores.

Passamos apenas as irmãs do mesmo agrupador porque é ali que a confusão acontece. Ninguém confunde «Metalurgia» com «Farmacêutica»; confunde-se «Metalurgia» com «Metalmecânica».

13.4 · Como usar — no terminal (PowerShell)

Fluxo recomendado — não pule os dois primeiros passos:

# 1. Ver o que seria feito, sem alterar nada
python ferramentas/construir_glosas.py --simular

# 2. Testar a qualidade num eixo só, com poucas categorias
python ferramentas/construir_glosas.py --taxonomia setor_industrial --limite 3

# 3. Se gostou do resultado, rodar completo
python ferramentas/construir_glosas.py

# 4. Revisar na planilha e marcar revisado = SIM nas aprovadas

# 5. Rodar de novo — as aprovadas ficam intocadas
python ferramentas/construir_glosas.py --aprimorar

Todas as opções:

Opção	O que faz
`--simular`	Mostra o que seria feito; não altera nada
`--aprimorar`	Reescreve também as que já têm glosa (e não foram revisadas)
`--taxonomia <nome>`	Limita a um eixo
`--limite <n>`	Processa no máximo N categorias
`--provedor <nome>`	`ollama` · `google` · `anthropic` · `openai`
`--modelo <nome>`	Sobrepõe o modelo do `config.py`
`--dominio <nome>`	Trabalha noutra área

13.5 · Como usar — no notebook

O assistente é um script de linha de comando, e por isso tem duas formas de ser chamado do notebook. A primeira é a mais simples; a segunda dá controle e devolve o resultado em memória.

Forma 1 — chamar o script pelo terminal, sem sair do notebook

Basta pôr a exclamação na frente. É o mesmo comando da seção 13.4, com o mesmo resultado:

!python ferramentas/construir_glosas.py --simular
!python ferramentas/construir_glosas.py --taxonomia setor_industrial --limite 3
!python ferramentas/construir_glosas.py --aprimorar

ATENÇÃO — O ! executa a partir da pasta em que o notebook foi aberto, não da pasta do projeto. Se der No such file or directory, confirme onde você está com !cd (Windows) ou passe o caminho completo: !python C:\0_Desenvolvimento\CNPQ\lattes_pipeline\ferramentas\construir_glosas.py --simular.

Forma 2 — chamar a função Python diretamente

Aqui você monta as opções como um objeto e chama a mesma função executar() que a linha de comando chama. A vantagem é poder mudar um parâmetro e repetir a célula, sem redigitar o comando inteiro:

import sys
sys.path.insert(0, r"C:\0_Desenvolvimento\CNPQ\lattes_pipeline")

from argparse import Namespace
from ferramentas import construir_glosas
from config import CFG

opcoes = Namespace(
    dominio=CFG.dominio,      # "industria"
    provedor="",              # "" = usa o do config.py
    modelo="",                # "" = usa o do config.py
    taxonomia="setor_industrial",
    limite=3,
    aprimorar=False,
    simular=True,             # ⬅️ comece SEMPRE por aqui
)

construir_glosas.executar(opcoes)

Para valer de verdade, troque simular=True por simular=False. Para reescrever as glosas que já existem e ainda não foram revisadas, aprimorar=True.

LEMBRE-SE — A regra inviolável da seção 13.2 vale igual nos dois modos: categoria com revisado = SIM nunca é alterada, nem pelo terminal, nem pelo notebook, nem com --aprimorar.

Conferir o resultado sem sair do notebook

Depois de rodar, o relatório e o dicionário podem ser abertos ali mesmo:

import pandas as pd

# as glosas que a validação automática marcou como frágeis
rel = pd.read_excel(CFG.caminhos.relatorios / "glosas_geradas.xlsx",
                    sheet_name="REVISAR_PRIMEIRO")
rel.head(20)

# o dicionário atualizado
import dominios
dic = pd.read_excel(dominios.caminho_dicionario(CFG.dominio))
dic[dic["taxonomia"] == "setor_industrial"][["nivel2", "glosa", "revisado"]]

NA PRÁTICA — O ciclo de curadoria fica bom no notebook: rodar com --limite 3, ler as três glosas na tela, ajustar o prompt em ia/prompts.py, recarregar (%autoreload 2 cuida disso) e rodar de novo. Só quando o padrão agradar é que se roda o dicionário inteiro.

13.6 · O que ele grava

Onde	O quê
O dicionário	glosa e exemplares novos
`origem`	`ia:<modelo>` — a procedência fica registrada
`revisado`	`NAO` — sempre; nada gerado por máquina nasce aprovado
Backup	cópia do dicionário anterior, com a data no nome
`5_RELATORIOS/glosas_geradas.xlsx`	o antes e o depois de cada glosa

CONFIRA — O relatório tem três abas. Comece pela REVISAR_PRIMEIRO: são as glosas que a validação automática apontou como frágeis. Se o tempo for curto, revise só essas.

13.7 · A validação automática

Antes de gravar, o assistente confere cada glosa recebida:

Verificação	Por quê
Entre 25 e 55 palavras	Curta não dá sinal; longa dilui o foco
Cita alguma categoria irmã	É o contraste que separa os vetores
Não começa com metalinguagem	“Esta categoria abrange…” não carrega significado
Não repete o rótulo no início	Redundante — o rótulo já entra separadamente
Ao menos 4 exemplares	Termos de busca reforçam o vetor

LEMBRE-SE — Os avisos não impedem a gravação. Eles vão para o relatório, sinalizando o que a revisão humana deve olhar primeiro. Só glosa vazia é descartada.

13.8 · Se a qualidade não agradar

Em ordem de eficácia:

Troque o modelo. gemma2:27b ou um provedor de nuvem redigem visivelmente melhor que modelos pequenos.
Escreva você mesmo 2 ou 3 glosas exemplares do domínio e marque-as como revisado = SIM. Elas passam a ser exibidas como irmãs, e o modelo imita o padrão.
Ajuste o prompt em ia/prompts.py. É o único lugar que define o estilo — mudar ali muda todas as glosas seguintes.

14. Primeira execução

EM UMA FRASE — Dois comandos: um confere o ambiente, o outro roda tudo com dados simulados. Se os dois passarem, a instalação está correta — pelo terminal, pelo notebook ou por dois botões do Assistente (14.4).

14.1 · Os dois comandos de estreia

NO TERMINAL (PowerShell)

# 1. Confira o ambiente. Ele diz exatamente o que falta.
python pipeline.py --pre-voo

# 2. Rode com dados simulados, para ver tudo funcionando.
python pipeline.py --demonstracao 300

NO NOTEBOOK

import sys
sys.path.insert(0, r"C:\0_Desenvolvimento\CNPQ\lattes_pipeline")

import pipeline
pipeline.pre_voo()                    # 1. confere o ambiente
pipeline.executar(demonstracao=300)   # 2. roda com dados simulados

Se os dois funcionarem, a instalação está correta.

Os dois modelos de IA — o de vetores (E5, 1,1 GB) e o de desempate (reranker, 2,2 GB) — são baixados uma vez só, de preferência antes desta estreia: 14.2 mostra como. Se ainda não estiverem no cache, a primeira classificação os baixa sozinha — e parece travada em «Carregando modelo vetorial» durante o download. Depois disso, o sistema funciona inteiramente offline — nenhum currículo sai da sua máquina.

CONFIRA — O --pre-voo é o primeiro comando a rodar em qualquer máquina nova. Ele confere caminhos, dicionário, dados de entrada, bibliotecas e os modelos de IA no cache (14.2), mostra o dispositivo detectado (GPU ou processador) e sai — sem processar nada. Cinco segundos ali evitam descobrir um problema no fim de uma execução de seis horas.

14.2 · Os modelos de IA: baixar antes da primeira execução

O pipeline usa dois modelos de IA que rodam na sua máquina. Eles não vêm com o pip: são arquivos grandes, baixados uma vez do Hugging Face — o repositório público de modelos — e guardados num cache local. Baixá-los antes da primeira execução evita duas surpresas: a primeira classificação parada por muitos minutos em «Carregando modelo vetorial», e a falha numa máquina sem internet.

Modelo	Para que serve	Tamanho	É preciso?
E5 · `intfloat/multilingual-e5-large-instruct`	transforma texto em vetor: classificação, vetorização e busca	1,1 GB	sempre
reranker · `BAAI/bge-reranker-v2-m3`	o desempate de precisão (6)	2,2 GB	só com o desempate ligado

NO TERMINAL (PowerShell)

# os dois modelos (3,3 GB)
python pipeline.py --baixar-modelos

# ou um só
python pipeline.py --baixar-modelos e5
python pipeline.py --baixar-modelos reranker

O andamento sai arquivo por arquivo, com o percentual — e a última linha diz se deu certo:

⬇ E5 · intfloat/multilingual-e5-large-instruct → C:\…\huggingface\hub
  ⬇ E5 · 3/11 · model.safetensors (1,1 GB)
  ✓ E5 · 37% · 412 MB de 1.120 MB
✅ E5 pronto (1,1 GB, 11 arquivos)

Uns 10 minutos a 50 Mbit/s; até 1 hora numa conexão lenta. Antes de começar, o comando confere o espaço livre no disco do cache e para, sem baixar nada, se faltar. Se a internet cair no meio, rode de novo: ele continua de onde parou. Sem acesso, a resposta é uma linha só:

❌ sem acesso à internet (ou proxy bloqueando huggingface.co): nada foi gravado pela metade

Onde ficam. No cache da Hugging Face — por padrão, dentro do seu perfil do Windows, em C:\Users\<conta>\.cache\huggingface\hub. Para guardar em outro lugar, defina a variável HF_HOME com a pasta desejada: os modelos vão para <HF_HOME>\hub. Pelo Assistente, é o campo «HF_HOME (cache dos modelos de IA)», na aba «7 · Ambiente». Numa máquina com mais de uma conta, leia antes o item 9 do capítulo 26.

Conferir. O pré-voo passou a dizer, logo abaixo do nome do modelo, se cada um está no cache:

  modelo ............ intfloat/multilingual-e5-large-instruct
  cache do E5 ....... ✅ no cache (1,1 GB) — C:\Users\x\.cache\huggingface\hub
  cache do reranker . ○ não baixado (2,2 GB) — só é preciso com o desempate ligado

O ○ cinza não é erro: com o desempate desligado, o reranker não faz falta. Com o desempate ligado, a mesma linha vira ❌ e já traz o comando da correção — python pipeline.py --baixar-modelos reranker; sem o E5, python pipeline.py --baixar-modelos (ou o passo 5 do Assistente). E «○ não conferido (huggingface_hub ausente)» quer dizer que as bibliotecas ainda não foram instaladas (9.4).

Sem internet na máquina de trabalho. Baixe numa máquina com internet, com o mesmo comando, e copie as duas pastas do cache — models--intfloat--multilingual-e5-large-instruct e models--BAAI--bge-reranker-v2-m3, dentro de hub — para o hub do HF_HOME da máquina de trabalho. Lá, defina também HF_HUB_OFFLINE=1: se faltar algum arquivo, o pipeline falha na hora, com mensagem, em vez de tentar a internet.

LEMBRE-SE — Pelo Assistente, é o passo 5 da Primeira configuração (14.4): o botão «⬇ Baixar os modelos» roda este mesmo comando, depois de mostrar o destino, o espaço livre e o tempo estimado. Nenhum currículo é enviado — é só download.

14.3 · Com dados reais

NO TERMINAL (PowerShell)

# 1. Deposite os arquivos do Lattes na pasta de entrada.
#    A pasta é mostrada por: python pipeline.py --config

# 2. Rode.
python pipeline.py

# 3. Confira o primeiro relatório antes de qualquer coisa.
#    5_RELATORIOS\1_ingestao.xlsx

NO NOTEBOOK

from config import CFG
print("deposite os arquivos em:", CFG.caminhos.entrada)

import pipeline
pipeline.executar()

# conferir o primeiro relatório sem sair do notebook
import pandas as pd
pd.read_excel(CFG.caminhos.relatorios / "1_ingestao.xlsx",
              sheet_name="RESUMO")

ATENÇÃO — Confira o relatório da etapa 1 antes de olhar qualquer resultado de classificação. Se uma tabela veio vazia porque o caminho de tag mudou, tudo o que vier depois estará incompleto — e o defeito é muito mais barato de corrigir agora do que depois de uma execução completa. Ver a seção 24.

27. Dados de demonstração

A base de demonstração do projeto é a pasta dados_demo\, versionada junto com o código: 118 currículos gerados por ingestao/simulador.py e já processados pelas quatro etapas. Serve para experimentar o painel em segundos, numa máquina nova, sem tocar em dado real — e é dela que saem as capturas do Manual do Prospecta.

Pasta	Conteúdo
2_CURRICULOS/	as dez tabelas da etapa 1, em Parquet — com `cpf` e `data_nascimento` sintéticos, gerados, nunca reais
3_CLASSIFICADO/	os sete blocos com rótulos (etapa 2), em CSV
4_RESULTADOS/	uma linha por pesquisador (etapa 3) e os vetores (etapa 4)
_controle/	o manifesto e o registro, para a ingestão incremental reconhecer o que já entrou
6_PROSPECTA/	não versionada: o `preparar.py` a reconstrói em segundos

python preparar.py --de dados_demo        # monta o pacote do painel
python servidor.py --raiz dados_demo --sem-login

ATENÇÃO — Estes dados são simulados. Foram gerados por ingestao/simulador.py para exercitar o sistema antes da extração real — inclusive o CPF e a data de nascimento, que são sintéticos. Nenhum número descreve pessoas reais, e o painel mostra a faixa «BASE SIMULADA» o tempo todo. Servem para demonstrar o formato da entrega, não para produzir conclusões.