‹ Recruta.Gov · dadosrgb

Como ler este manual

São oito partes, e elas não precisam ser lidas em ordem.

0.1 · O acervo, de uma vez

212.801 servidores com currículo preenchido · 34,3% da força de trabalho ativa · 200.298 currículos distintos por conteúdo · 537 já pontuados nas nove dimensões

Números medidos em 06/09/2026 às 12:27, direto dos arquivos em disco. Cada execução do pipeline os altera, e cada geração deste manual os relê — então o que está escrito aqui é o retrato daquele instante, não uma estimativa que envelhece.

O que foi lido para chegar aqui

O currículo do SouGov não é um documento — são nove tabelas que descrevem pedaços da trajetória de alguém. O pipeline as costura num texto único por pessoa, e é esse texto que vira vetor e vira nota.

0.2 · Cobertura — onde o sistema enxerga, e onde não

Três coberturas diferentes, e confundi-las produz conclusão errada. Uma coisa é quantos servidores escreveram currículo; outra é quantos desses currículos já passaram pela análise das nove dimensões; outra ainda é quanto do lado da demanda — unidades e editais — está descrito.

0.3 · Quem tem currículo preenchido

A distribuição responde a uma pergunta prática: em que órgãos e carreiras uma busca por talento tem chance de encontrar gente — e onde o silêncio é falta de currículo, não falta de pessoa.

0.4 · O tamanho de um currículo

Quanto texto cada pessoa escreveu importa por dois motivos concretos: define o custo da análise por IA e determina quem é afetado pelo teto de caracteres.

A distância entre média e mediana conta a história: a maioria escreve pouco, e uma minoria escreve muitíssimo. É por isso que o teto de caracteres afeta uma fração pequena da base — e por isso ele só entra na chave do cache de quem ele realmente corta (Parte III · III.13).

0.5 · A qualidade do que foi declarado

Nem todo número baixo é problema do sistema; alguns são retrato fiel de uma fonte pobre. O caso mais importante está no dimensionamento das unidades.

I.1 · Em uma página

O Recruta.Gov responde a uma pergunta que a administração pública faz todo dia e quase sempre responde no escuro: quem, dentro da casa, tem a competência de que esta unidade precisa?

Ele faz isso lendo três coisas que já existem e ninguém consegue ler junto: os currículos dos servidores, o dimensionamento da força de trabalho (DFT) de cada unidade e os editais de oportunidade. Traduz os três para uma mesma régua de nove dimensões de competência e mostra, lado a lado, onde há encaixe e onde há lacuna.

O sistema tem duas metades. A primeira é o pipeline: um programa que roda de tempos em tempos, busca os dados no Data Lake, classifica os textos, chama a inteligência artificial e deixa tudo pronto em arquivos. A segunda é o sistema Recruta: as telas em que o gestor pesquisa, compara e simula. Entre as duas há um princípio que atravessa este manual inteiro: o pipeline pensa devagar e uma vez; a tela responde rápido e sempre com o mesmo número.

As duas metades são operadas por um único aplicativo assistente, uma janela com oito abas. Quem usa o Recruta.Gov não precisa abrir prompt de comando, não precisa saber Python e não precisa decorar caminho de pasta.

I.2 · O problema que este sistema resolve

Um órgão do porte do MGI guarda dezenas de milhares de currículos e centenas de descrições de unidade. Estão todos lá, em campos de texto livre, escritos por pessoas diferentes, em épocas diferentes, com palavras diferentes para a mesma coisa. É informação que existe e não se deixa usar.

Por que uma busca comum não basta

Procurar «orçamento» encontra quem escreveu «orçamento» — e perde quem escreveu «execução financeira», «SIAFI», «empenho e liquidação» ou «PLOA». A busca por palavra não sabe que essas expressões falam do mesmo trabalho. Numa base de centenas de milhares de linhas, isso não é um detalhe: é a diferença entre achar cinco pessoas e achar cinquenta.

O Recruta.Gov compara significado, não letra. Ele converte cada texto num conjunto de números que representa o sentido da frase, e mede a distância entre esses conjuntos. Textos que falam da mesma coisa ficam perto, mesmo sem compartilhar uma única palavra.

Por que classificar em categorias

Encontrar é metade do problema. A outra metade é agrupar: saber quantas pessoas da unidade trabalham com dado, quantas com licitação, quantas com gestão de pessoas. Para isso é preciso etiquetar cada texto com um rótulo de uma lista fechada — a taxonomia —, e é isso que o pipeline faz.

Por que usar inteligência artificial

Contar rótulo não diz o nível de uma competência, nem o que uma unidade espera de quem chega. Para isso é preciso ler o texto inteiro e formar um juízo — que é exatamente o que um modelo de linguagem faz bem e um contador de palavras não faz de jeito nenhum.

A IA aqui tem um papel estreito e vigiado: ela lê e resume, e atribui notas de 0 a 5 nas nove dimensões, sempre obrigada a citar de onde tirou cada nota. Ela não escolhe candidato, não ordena ranking sozinha e não inventa: os prompts a proíbem explicitamente de afirmar o que não estiver no texto lido, e o sistema exibe a origem de cada número na própria tela.

I.3 · Como funciona, sem termos técnicos

1. A impressão digital de um texto

Antes de processar qualquer texto caro, o sistema calcula uma impressão digital dele: um código curto que muda completamente se uma vírgula mudar. Se a impressão digital é a mesma da última vez, o texto não mudou, e o resultado guardado continua valendo. É por isso que a segunda execução do pipeline leva minutos, e não horas.

2. O arquivo de trabalhos prontos

Toda resposta cara — uma análise de IA, um vetor de significado — vai para um cache, indexado pela impressão digital do texto, e não pelo número do servidor. Isso tem uma consequência prática importante: se duas pessoas escreveram exatamente a mesma frase, o trabalho é feito uma vez só.

3. A lista de verificação do que já foi feito

O pipeline mantém um manifesto: um registro do que cada etapa produziu, com a assinatura das condições em que rodou (quais arquivos, qual modelo de IA, quais parâmetros). Se nada mudou na assinatura, a etapa se anuncia como já feita e passa adiante. Se qualquer coisa mudou — inclusive o modelo de IA —, ela roda de novo. Foi um bug real: um modelo trocado sem trocar a assinatura fez o sistema servir resultado velho por semanas.

4. O dicionário e seus verbetes

A taxonomia não é uma lista de palavras soltas: cada rótulo tem uma glosa, um verbete curto que explica o que aquele rótulo abrange e o que ele não abrange. É a glosa, e não o nome do rótulo, que o classificador compara com o texto. Rótulo bem glosado classifica bem; rótulo sem verbete classifica pelo nome, que quase sempre é ambíguo.

5. O que fazer quando nada se encaixa

Quando nenhum rótulo serve, o sistema não força: marca «Indefinido» e guarda o texto. Depois, a etapa de descoberta agrupa os indefinidos que se parecem entre si e devolve sugestões de rótulos novos para a curadoria humana avaliar. O dicionário cresce a partir do que a realidade trouxe, e não do que alguém imaginou na mesa.

6. Falha não é resultado

Esta é a regra que mais aparece no código, e a que mais custou a chegar. Quando a IA falha — o serviço caiu, a resposta veio truncada, o PDF era uma imagem sem texto —, o sistema diz que falhou. Ele não preenche zero, não monta uma justificativa plausível e não deixa a pessoa aparecer no fim do ranking como se tivesse sido avaliada e ido mal. Aparece «análise não concluída», com o motivo técnico, e a pessoa fica fora das médias.

I.4 · O caminho dos dados, contado como uma história

Nove etapas, sempre nesta ordem. Cada uma só faz o seu pedaço e grava o resultado em arquivo; a seguinte lê o que a anterior deixou.

1. BuscarA extração conecta no Data Lake do MGI e traz as tabelas: servidores, currículos, unidades, editais. É a única etapa que fala com o mundo externo do órgão, e a única que pede autenticação — pelo navegador, com a conta do próprio operador, sem senha guardada em lugar nenhum.
2. EtiquetarA classificação lê cada texto de currículo e atribui um rótulo da taxonomia: área e subárea. Compara o significado do texto com a glosa de cada rótulo e escolhe o mais próximo — ou marca «Indefinido».
3. Descobrir o que faltaA descoberta pega os textos que ficaram sem rótulo, agrupa os parecidos e sugere verbetes novos para a curadoria.
4. Traduzir os códigosA etapa do SIAPE transforma códigos funcionais em informação legível: vínculo, cargo, unidade de exercício, situação.
5. Montar o retrato de cada pessoaA etapa de currículos junta tudo o que se sabe de cada servidor num texto único, gera o vetor de significado que a busca vai usar e — quando pedido — a nota fixa nas nove dimensões.
6. Ler os editaisA etapa de oportunidades lê cada edital e extrai o perfil desejado, também nas nove dimensões, para que vaga e pessoa fiquem na mesma régua.
7. Retratar as unidadesA etapa do DFT lê o dimensionamento de cada unidade e produz missão, entregas, competências exigidas e a pontuação da unidade nas nove dimensões.
8. Catalogar os cursosA etapa de cursos varre o catálogo da Escola Virtual de Governo e marca que dimensões cada curso desenvolve — é o que permite responder «e agora, o que faço com essa lacuna?».
9. Contar gente e folhaA etapa de pessoal apura o efetivo real de cada unidade por situação funcional e a folha bruta correspondente.

I.5 · As nove dimensões

Tudo — pessoa, unidade, edital, vaga descrita à mão, curso — é traduzido para as mesmas nove dimensões, com nota de 0 a 5. É essa tradução que permite comparar coisas de naturezas diferentes na mesma tela.

A escala é sempre a mesma: 0 = não há evidência no texto lido; 1–2 = presente de forma incipiente; 3 = presente e consolidada; 4–5 = presente com profundidade e evidência forte.

I.6 · Perguntas frequentes

Algum dado sai do computador?

Na configuração padrão, não. O modelo de IA roda localmente e os arquivos ficam na pasta de bases. Sai apenas se o operador ligar o agente por API — e aí só as etapas sem dado pessoal, salvo se ele marcar, explicitamente e a cada execução, a opção de currículo por API anonimizada.

A inteligência artificial decide quem é contratado?

Não. Ela lê, resume e atribui notas justificadas. Quem seleciona é a pessoa responsável pelo processo, com os documentos à vista. O sistema foi desenhado para tornar a decisão auditável, não para tomá-la.

E se a análise da IA estiver errada?

Toda nota vem acompanhada da justificativa e da indicação de origem — se veio do pipeline (🧮) ou da execução daquela tela (🧠). O texto integral do currículo continua disponível. Divergiu, prevalece o documento; a nota é leitura, não fato.

Quanto tempo leva uma execução?

A primeira, com tudo do zero, leva horas — a maior parte é a IA lendo currículo. As seguintes levam minutos, porque só reprocessam o que mudou. Rodar sem IA (--sem-ia) leva poucos minutos em qualquer caso.

Preciso saber programar para operar?

Não. O aplicativo assistente cobre a operação inteira: extrair, processar, subir os servidores, abrir o site, rodar os testes e conferir o ambiente. A Parte II deste manual é o passo a passo dele.

Posso usar em outro computador?

Sim. É preciso ter Python, o repositório e permissão de acesso ao Data Lake e à pasta de dados da equipe. O assistente cria o ambiente virtual e instala as dependências pelos botões da aba 4 · Ambiente.

O que preciso decidir antes de colocar em produção?

Quatro coisas, todas listadas na Parte VI: onde ficam os dados, quem tem acesso a essa pasta, se o agente por API será usado e para quais etapas, e qual é a política de retenção dos PDFs de dossiê gerados.

II.1 · Abrir o assistente

O assistente é o ponto de entrada de tudo. Ele opera o pipeline, sobe a API e o site, cuida do ambiente Python, da curadoria do dicionário, dos testes e do Git. Não existe operação normal que exija abrir um terminal — incluindo abrir o próprio assistente.

Dois cliques, e pronto

Na raiz do repositório há o arquivo Assistente Recruta.vbs. Dois cliques nele abrem a janela, e nenhuma janela preta de console aparece.

O que ele faz por dentro, em ordem: confere se o assistente está no lugar esperado; procura um Python com Tkinter, preferindo o ambiente virtual do próprio projeto (recruta_pipeline/.venv), porque é lá que estão as bibliotecas certas; e roda com a pasta do pipeline como diretório atual.

Pela linha de comando, quando for preciso

Equivalente ao duplo clique — útil para ver mensagens de erro de partida

cd <pasta do repositório>\recruta_pipeline
python ferramentas\assistente.py

A janela

Abre em 1180x860, com mínimo de 1000x620, e guarda a geometria para a próxima vez. A estrutura é sempre a mesma:

• no topo, a faixa azul com o nome do aplicativo — a âncora visual;
• à esquerda, as dez abas, na ordem em que se usa;
• à direita, o log de execução, lado a lado com os controles.

O log de execução

Todo comando disparado por qualquer aba escreve aqui, ao vivo, linha a linha, em fundo escuro e fonte monoespaçada — porque numa execução longa ele passa de mil linhas e precisa continuar legível. É onde aparece o erro quando algo falha, e é a primeira coisa a olhar antes de perguntar o que aconteceu. Dois botões, no canto direito da barra:

• Limpar — esvazia a área de log. Não cancela nada que esteja rodando.
• Salvar log… — grava o conteúdo num arquivo de texto à sua escolha. Use antes de pedir ajuda: o log salvo costuma conter a resposta.

As linhas são coloridas por tipo: erro em vermelho, aviso em âmbar, conclusão em verde, comando disparado em azul e início de etapa em roxo. Numa execução longa o log passa de mil linhas — sem cor, o erro que importa fica indistinguível do progresso normal.

II.2 · Aba 0 · Início — o diagnóstico

A aba de abertura responde a uma pergunta só: o que ainda falta para este computador operar o Recruta.Gov? Cada linha é um pré-requisito, com ✅ quando está pronto e ⬜ quando não está — e, quando não está, um botão ao lado que resolve ou leva à aba certa.

O botão 🔄 Verificar novamente refaz o diagnóstico. Use depois de criar um venv, instalar dependências ou rodar uma etapa.

Abaixo do diagnóstico vem a sequência recomendada para a primeira vez — que é também o roteiro do item II.10 deste manual — e o bloco do manual.

Manual do sistema

Este manual é gerado a partir da pasta manual/, na raiz do repositório. Três botões, aqui mesmo:

• 📘 Gerar o manual (Word) — Produz Manual_Recruta_Gov_v6.docx — a versão para circular e imprimir.
• 🌐 Gerar o manual (site) — Produz Manual_Recruta_Gov_v6.html — navegável, com sumário lateral e busca do navegador.
• Abrir o manual — Abre a versão mais recente das duas.

II.3 · Aba 1 · Pipeline — o fluxo completo, do início ao fim

Esta é a aba onde o processamento acontece, e ela foi desenhada para ser lida de cima para baixo: o que você quer fazer, depois as etapas em três fases, depois rodar uma combinação e atalhos.

A ordem em que as etapas aparecem é a ordem de execução. Ninguém precisa decorá-la, e não há como marcá-las fora de ordem.

1 · O que você quer fazer?

• ▶ Rodar tudo — Executa as nove etapas na ordem, aproveitando o que já está pronto. É o botão do dia a dia.
• ⏸ Parar ao fim do ciclo — A forma recomendada de interromper. A execução termina o item em curso, grava tudo o que já processou, escreve o relatório e sai limpa. Nada se perde.
• ■ Parar agora — Mata o processo imediatamente. O que já foi salvo em disco permanece — mas o que estava entre o último ponto de salvamento e agora é perdido.
• Conferir o ambiente de IA — Valida o modelo e as chaves sem processar nada — é o --pre-voo da linha de comando. Vale rodar antes de um lote longo.

Ao lado dos botões, um indicador mostra se o pipeline está parado ou rodando…. Ele é emitido pelo processo de verdade, e não otimisticamente ao clique — se aparecer rodando…, está mesmo.

As três opções que valem para a execução inteira

2 · As etapas, em três fases

As nove etapas estão agrupadas pelo papel que cumprem, e cada grupo diz numa linha o que faz.

Anatomia de uma linha de etapa

Cada etapa ocupa uma linha, sempre com os mesmos seis elementos, da esquerda para a direita:

As opções de cada etapa

Escolher quais bases classificar

O menu 🎯 Bases ao lado da etapa classificacao restringe quais blocos serão classificados nesta execução. O padrão é todas, e é o certo para a rotina; a seleção serve para quando você mexeu na taxonomia de um eixo e não quer esperar os outros.

Na linha de comando corresponde a RECRUTA_BLOCOS_CLASSIFICACAO, com os nomes separados por vírgula. O log anuncia a restrição: «🎯 Classificação restrita a 2 de 6 bloco(s)».

3 · Rodar uma combinação

As caixas de seleção das linhas montam um conjunto. Este bloco o executa:

• Marcar todas / Desmarcar — Operam as nove caixas de uma vez.
• ▶ Rodar a seleção — Executa o que estiver marcado, sempre na ordem correta.

Abaixo dos botões, numa faixa cinza e em fonte monoespaçada, aparece o comando exato que será executado, atualizado a cada clique. Serve para confirmar a intenção antes de rodar, e para copiar — para um agendamento, ou para um chamado de suporte.

Recorte do lote de currículos

O lote inteiro leva horas e consome cota, e muitas vezes o que se quer é bem menor: reprocessa a minha coordenação, estas oito pessoas do concurso, o INSS inteiro. Antes a escolha era binária — tudo ou nada. Agora há um buscador na própria aba 1.

1. ProcurePor nome, CPF, sigla de órgão ou hierarquia. A busca lê a MESMA base que o pipeline gera (SIAPE_ENRIQUECIDO), então o que aparece aqui é o que a etapa vai encontrar.
2. Selecione na listaCtrl e Shift funcionam para escolher várias linhas. Para grupos grandes há dois atalhos: ☑ marcar todas seleciona as linhas exibidas, e ➕ todas as encontradas leva ao recorte o resultado inteiro da busca — inclusive o que ficou além das 300 linhas mostradas na tela.
3. Escolha o critério👤 estas pessoas usa o CPF; 🏛️ o órgão delas usa a sigla; 🌳 o setor delas usa a hierarquia — e inclui tudo abaixo do nó escolhido, que é o que «setor» significa para quem olha o organograma.
4. Marque «resumo por IA» e rodeO recorte só entra no comando quando o resumo por IA está ligado — é ele que a seleção limita.

Na linha de comando: --curriculos-cpfs, --curriculos-orgaos e --curriculos-hierarquia (várias separadas por ;). Cada um aceita os valores diretos ou o caminho de um arquivo com um por linha.

Rodar em paralelo (por recurso)

Etapas que usam recursos diferentes não competem: a classificação e os currículos moem no E5 (placa de vídeo); os editais e os cursos são rede/API. Rodá-las ao mesmo tempo corta o tempo total.

1. 🖥️ Trilha LOCALclassificacao,curriculos — usa a GPU, nenhuma cota de API.
2. ☁️ Trilha APIoportunidades,cursos — só rede, não toca na placa.
3. ▶ Rodar as marcadas como trilha paralelaTransforma as etapas marcadas nas caixas numa trilha independente, sem ocupar a fila principal.

4 · Atalhos

Combinações prontas para as situações mais comuns. Não dependem do que está marcado acima — clicar num atalho executa a combinação dele, e só ela.

Cache e reprocessamento — o que é refeito, e quando

O cartão de mesmo nome, no alto da aba, existe porque esta é a dúvida mais frequente de quem opera. O resumo:

II.4 · Aba 2 · Servidores — subir o sistema Recruta

O sistema Recruta são dois processos: a API, que lê o que o pipeline gerou e faz as contas, e o site, que serve as telas. Os dois precisam estar no ar.

API (motor de dados e IA)

Site (as telas)

Tudo de uma vez

▶▶ Subir API + site e abrir o navegador faz os três passos em sequência, com quatro segundos de espera antes de abrir o navegador — tempo para os servidores responderem. É o botão do dia a dia.

⏻ Encerrar API + site derruba o par que aquele botão levanta, listando antes o PID de cada processo que será encerrado.

Ações na API (sem reiniciar)

Consultas rápidas ao que a API está enxergando agora, sem derrubar nada. O resultado sai no log.

II.5 · Aba 3 · Usuários — quem entra no Recruta

A lista de acesso do sistema é uma planilha (usuarios.xlsx) com três colunas: CPF, Senha e Nome. É ela que a tela de login consulta. Até a versão 6.1 só dava para editá-la abrindo o arquivo à mão, num caminho do OneDrive que ninguém lembrava de cor.

A lista

O campo Planilha mostra onde o arquivo está, com o botão … para apontar outro e 🔄 Recarregar para reler do disco, descartando alterações não salvas. A tabela abaixo lista todos os usuários, ordenados por nome — e com a senha mascarada, porque a tela do assistente costuma estar aberta com outra pessoa por perto.

Clique numa linha para carregá-la nos campos de edição.

Incluir ou editar

II.6 · Aba 4 · Prompts — o texto que a IA recebe

Os cinco prompts do pipeline, com o texto exato enviado ao modelo, editáveis na tela. Para cada um, a aba diz onde ele é usado e por que ele importa — porque um prompt fora de contexto é só um parágrafo.

Os controles

• 💾 Salvar este prompt — Grava a personalização em ia/prompts_customizados.json, que é versionado no Git — um prompt ajustado é decisão do projeto, não configuração de máquina, e precisa aparecer no diff e poder ser revertida.
• ↺ Restaurar o original — Descarta a personalização e volta ao texto de fábrica. Sem personalização alguma, o arquivo deixa de existir.
• Descartar edição — Recarrega o texto em uso, jogando fora o que você digitou e ainda não salvou.

A escolha que importa: reprocessar ou não

Ao salvar, a aba pergunta se a edição muda o resultado da IA. A resposta decide o que acontece com tudo o que já foi gerado:

II.7 · Aba 5 · IA / Modelos

Aqui se decide onde a inteligência artificial roda. É a aba com a maior consequência de privacidade do sistema inteiro, e por isso a que mais explica na própria tela.

Local ou por API

• Local (Ollama) — Padrão. Nada sai da máquina. Mais lento, e depende de o Ollama estar instalado e com o modelo baixado.
• Por API — Muito mais rápido. Vale para as etapas sem dado pessoal: oportunidades, dft e cursos. Currículo só vai por API com a opção explícita de anonimização, marcada a cada execução.

Os provedores oferecidos são Google (Gemini / Gemma), OpenAI e Anthropic (Claude). Cabem quantas chaves você quiser — o botão ➕ Adicionar chave acrescenta linhas, e o ✕ de cada linha remove. O sistema alterna entre elas para respeitar o limite de requisições de cada uma.

Qualidade da classificação

• Refinar as decisões duvidosas com um segundo modelo (reranker) — Liga um segundo modelo, mais caro e mais preciso, só para os casos da zona cinzenta. Baixa cerca de 2 GB na primeira vez.
• Guardar os N melhores rótulos — 0 (padrão) grava só o rótulo escolhido. 3, 5 ou 10 fazem a coluna de auditoria registrar as alternativas em ordem, com o score de cada uma — permite revisar classificação duvidosa sem reprocessar nada.

Onde cada etapa de IA roda

Não é tudo local nem tudo por API. Cada etapa lida com um tipo diferente de informação, e a escolha certa varia — por isso ela é por etapa:

Pela linha de comando, o equivalente é a variável RECRUTA_IA_POR_ETAPA="dft=local,oportunidades=api,cursos=api". Valor inválido é ignorado e prevalece o padrão — uma variável mal digitada não pode mudar para onde o dado vai.

Limite de caracteres por currículo

Define quanto de cada currículo vai ao modelo. Ao lado do campo, uma estimativa viva de tokens se atualiza enquanto você digita, usando a mesma régua do limitador de taxa (~4 caracteres por token) — é ela que diz se o lote cabe na cota do dia.

Onde cada etapa de IA roda

A escolha é por etapa, e o padrão reflete a natureza do dado:

II.8 · Aba 6 · Ambiente

A aba mais densa, e a que quase nunca é aberta depois do primeiro dia. Cinco blocos.

Ambiente Python

Um grupo para o Pipeline e outro para a API e site, cada um com três botões idênticos:

• Criar venv — Cria o ambiente virtual .venv na pasta do projeto. O assistente passa a usá-lo sozinho a partir daí.
• Instalar dependências — Instala o requirements.txt daquele projeto dentro do venv.
• Qual Python está em uso — Mostra a versão do Python que o assistente vai usar para aquele projeto — a forma mais rápida de confirmar que o venv está sendo respeitado.

Pastas e arquivos das bases

Onde o pipeline lê e grava. Em branco = usa o padrão. O que for definido aqui vale para tudo o que o assistente executa, e não altera a configuração do sistema operacional. Cada campo tem um botão … que abre o seletor de pasta ou de arquivo.

Conexão com o Data Lake (etapa extracao)

Quatro campos — HOST, HTTP_PATH, CATALOG e TENANT. Peça-os à equipe que administra o workspace. Em branco, valem os padrões do projeto.

Salvar e conferir

• 💾 Salvar caminhos — Grava os caminhos e as opções nas preferências.
• Conferir o que existe — Lista, no log, quais dos arquivos esperados já existem.
• Abrir a pasta das bases — Abre o explorador de arquivos na pasta configurada.

Mudar a pasta de dados de lugar

Copia a pasta BASES inteira para outro lugar — o OneDrive da equipe, por exemplo —, confere arquivo a arquivo e só então oferece apagar a origem. Três botões, na ordem, e nessa ordem:

1. 1· Ver o plano (não copia)Mostra o inventário: quantos arquivos, quanto espaço, e quais caminhos ficariam longos demais no destino. Não move nada.
2. 2· Copiar e conferirCopia e depois confere — tamanho e conteúdo, arquivo por arquivo. A origem continua intacta.
3. 3· Apagar a origemSó depois da conferência limpa. Botão âmbar, com confirmação, porque é a única ação irreversível da aba.

II.9 · Aba 7 · Querys/Colunas — o que a extração traz

Cada consulta ao Data Lake traz dezenas de colunas, e nem todas são usadas. Esta aba mostra, tabela por tabela, quais colunas o sistema realmente consome — e permite deixar de trazer as que não servem para nada.

A classificação não é opinião: ela é derivada do uso real no código.

O efeito é duplo: as colunas marcadas saem do SELECT da consulta (menos dado trafegado do Data Lake) e são descartadas depois da leitura, como rede de segurança para quando a consulta não puder ser enxugada com segurança.

II.10 · Aba 8 · Dicionário — a curadoria da taxonomia

O dicionário (dicionarios/dicionario.xlsx) é a fonte de verdade da classificação: define cada área e subárea, e a glosa que explica o rótulo. Esta aba existe porque a curadoria era a última coisa que ainda exigia terminal.

O fluxo é: exportar (uma única vez) → curar na planilha → validar → rodar a etapa classificacao.

Editar aqui, sem abrir o Excel

A aba tem uma tabela com os 305 rótulos (filtro por taxonomia e busca por texto) e campos de edição: agrupador, rótulo, glosa, exemplares, observação, e as marcas revisado e ativo. Os botões: 💾 Gravar rótulo, ＋ Novo rótulo e ⏻ Aposentar selecionado — aposentar marca ativo = NÃO em vez de apagar a linha, porque o rótulo já classificou servidores e o relatório do mês passado precisa continuar explicável. Cada gravação cria cópia de segurança, e as duas portas — planilha e assistente — gravam no mesmo arquivo, com o mesmo escritor.

Rascunho de glosas por IA

Redige um rascunho da glosa de cada rótulo com o modelo local e grava na planilha marcado como revisado = NAO. Há um seletor de taxonomia (todas, areas, categorias) e a caixa só as ainda não revisadas, marcada por padrão.

Calibrar os limiares da classificação

Mede a distribuição real de similaridade de um bloco e mostra onde ficam o limiar e a zona cinzenta — troca o chute por evidência. Escolha o bloco (experiencia, conhecimentos, formacao, resumo, area_atuacao, capacitacao, soft_skills) e o tamanho da amostra (padrão 3000), e clique em Diagnosticar. A ferramenta só diagnostica; não altera nada sozinha.

II.11 · Aba 9 · Testes

Três baterias, que rodam em segundos, sem tocar nas bases reais e sem chamar IA. Use depois de qualquer mudança para conferir que nada quebrou.

▶ Rodar as três encadeia as baterias: cada uma começa quando a anterior termina, e o resultado consolidado fica no log.

II.12 · Aba 10 · Git

São dois repositórios independentes, com remotes diferentes: a raiz (pipeline) e a pasta da API/site, que tem o próprio .git. Um commit num não afeta o outro. O primeiro controle da aba é justamente a escolha de qual deles está sendo operado.

Antes de gravar

🔎 Conferir dado sensível antes do commit

O botão âmbar. Lista o que entraria num commit agora e destaca o que não pode ser versionado. É puramente informativo — não altera nada. Os padrões vigiados são:

• cache_ia.json — respostas de IA sobre currículos reais;
• config_ia_rapido.json — contém a chave de API;
• TEMP_RECRUTA/ — área temporária de trabalho;
• .pdf — dossiês gerados contêm nome, CPF e análise de pessoas reais;
• .parquet — as bases;
• assistente_prefs.json — caminhos locais da máquina;
• .env — variáveis de ambiente com segredos.

Gravar e enviar

• Mensagem — O texto do commit.
• Gravar (add + commit) — Adiciona tudo e grava no repositório selecionado.
• Enviar para o GitHub (push) — Envia para o remote. Confira antes em «Branch e remote» para qual repositório o envio vai.

II.13 · Roteiro do primeiro dia

A sequência abaixo leva de um computador zerado até o sistema aberto no navegador. Cada passo tem o seu botão; nenhum exige terminal.

1. Abrir o assistenteDois cliques em Assistente Recruta.vbs, na raiz do repositório. Nenhuma janela de console aparece.
2. Ambiente → criar o venv dos dois projetosAba 4 · Ambiente, botão Criar venv no grupo Pipeline e no grupo API e site.
3. Ambiente → instalar as dependências dos dois projetosMesmo grupo, botão Instalar dependências. Leva alguns minutos.
4. Ambiente → conferir a pasta das basesPreencha RECRUTA_RAIZ se as bases não estiverem no caminho padrão, e use Conferir o que existe.
5. IA → escolher onde a IA rodaAba 3 · IA / Modelos. Ficar no Ollama local é uma escolha legítima e não exige nada além do Ollama instalado. Se for usar API, informe a chave e clique em Testar conexão antes de seguir.
6. Pipeline → começar pelas etapas rápidasAba 1 · Pipeline, atalhos Contagem de pessoal e Catálogo de cursos. São minutos, e já provam que o encanamento funciona.
7. Pipeline → rodar o que interessacurriculos com Resumo e nota do currículo por IA é o que alimenta a régua única. Se a base for grande, considere rodar primeiro com Amostra de teste marcada.
8. Servidores → subir tudoAba 2 · Servidores, botão ▶▶ Subir API + site e abrir o navegador.
9. Testes → confirmarAba 6 · Testes, ▶ Rodar as três. Se as três fecharem em verde, o sistema está íntegro nesta máquina.

III.1 · Os sete conceitos que explicam o resto

1. Hash — a impressão digital de um texto

Uma função que transforma qualquer texto num código curto de tamanho fixo. Mudou uma vírgula, muda o código inteiro. O pipeline usa isso para responder à pergunta mais econômica que existe: este texto é o mesmo da última vez? Se for, o resultado guardado vale, e nada precisa ser refeito.

2. Canonicalização — antes de hashear, uniformizar

Dois textos iguais que diferem só em espaço duplo ou quebra de linha produziriam hashes diferentes e trabalho duplicado. Por isso o texto passa antes por uma normalização — e essa função é única e versionada. Foi um problema real na versão 4.0: mexer numa f-string de montagem invalidava silenciosamente a base inteira e disparava revetorização total.

3. Cache por conteúdo, não por identificador

O cache é indexado pelo hash do texto, e não pela matrícula de quem o escreveu. Consequência prática: dois currículos com o mesmo conteúdo são processados uma vez só; e um servidor que muda de unidade sem mexer no currículo não gera trabalho nenhum.

4. Manifesto — o pipeline como um make

O manifesto registra, a cada execução, o que cada etapa produziu e sob quais condições. Essas condições formam a assinatura: os arquivos de entrada, os parâmetros, a versão do prompt e o modelo de IA. Se a assinatura de hoje é igual à de ontem, a etapa se anuncia como já feita.

5. Embeddings — texto vira posição no espaço

Um modelo converte cada texto num vetor de números que representa o significado. Textos com sentido próximo ficam próximos nesse espaço, mesmo sem palavra em comum. É o que permite «execução financeira» encontrar quem escreveu «empenho e liquidação».

6. Classificação zero-shot supervisionada por dicionário

«Zero-shot» quer dizer que o modelo classifica sem ter sido treinado naqueles rótulos. A supervisão vem do dicionário: cada rótulo tem uma glosa, o texto é comparado com as glosas, e vence a mais próxima — desde que passe do limiar.

As quatro decisões que o motor toma

7. Glosa — o verbete que define o rótulo

A glosa é o que o rótulo significa para o sistema. Não é documentação: é insumo de produção. Um rótulo sem glosa é comparado pelo próprio nome, que quase sempre é ambíguo — «Gestão» sozinho atrai qualquer coisa.

III.2 · Arquitetura e mapa de pastas

O princípio de organização

Uma etapa nunca fala com outra diretamente: ela lê arquivo e grava arquivo. A única exceção é o resultado da classificação, passado em memória para a descoberta — porque gravar e reler um intermediário que ninguém mais usa seria custo sem benefício.

Objetos caros — o codificador de vetores, o reranker, o manifesto — são criados uma vez no orquestrador e compartilhados por todas as etapas. Carregar o modelo dentro de cada etapa multiplicaria o tempo de carga pelo número de etapas.

Os dois roteadores de IA

O pipeline mantém dois roteadores, e essa duplicidade é uma decisão de privacidade, não de arquitetura:

• roteador — Sempre local. É o que a etapa curriculos usa por padrão, sem exceção e sem variável de ambiente que mude isso — currículo é dado pessoal de gente de verdade.
• roteador_rapido — Pode ser o agente por API. Serve oportunidades, dft e cursos — edital publicado, atividade de unidade e catálogo público, onde não há dado pessoal. Sem agente configurado, ele é o roteador local, e o comportamento não muda.

A opção --curriculos-api é a única ponte entre os dois, e ela é opt-in a cada execução: exige agente por API configurado e faz o texto passar pela anonimização antes de sair. Sem agente configurado, a bandeira é ignorada com aviso explícito no log e o processamento segue local.

III.3 · Etapa extracao — buscar no Data Lake

Para que serve

Traz do Unity Catalog (Databricks) as tabelas que alimentam todo o resto: servidores, currículos, unidades, editais. É a única etapa que fala com fora do pipeline, e a única que exige autenticação.

Como executar

Aba 1 · Pipeline, caixa extracao marcada, ou pelo atalho correspondente. O navegador abrirá para você entrar com a sua conta.

python pipeline.py --etapas extracao --modo-extracao completa

Como funciona por dentro

Watermark incremental. No modo incremental, a etapa lê do manifesto a maior data já extraída de cada tabela marcada como incremental e monta um WHERE <coluna> > <último>, com atualização local por chave natural. É a maior economia isolada do pipeline: a tabela de fato de servidores tem cerca de 90 colunas consultadas com SELECT DISTINCT.

Hash de conteúdo por tabela. Se a tabela extraída é byte a byte igual à da execução anterior, as etapas que dependem dela são puladas em cascata — sem que ninguém precise avisar.

Minimização de colunas na origem. A consulta traz só as colunas que o sistema usa. Menos dado trafegado, menos dado em repouso, menos superfície de exposição.

A ficha financeira, em duas fases. A folha de pagamento por rubrica (ficha-fina, no schema bd_siape_financeiro) não cabe no percurso genérico, porque a consulta dela depende de uma decisão tomada antes. A fase 1 pergunta quais competências existem e quantas linhas cada uma tem — uma consulta barata, que agrega sem trazer as linhas. A fase 2 extrai a competência mais recente cujo volume seja pelo menos 60% do maior mês observado.

O que lê e o que grava

Parâmetros que você pode ajustar

• --modo-extracao completa — Reextrai tudo. Use na primeira execução.
• --modo-extracao incremental — Usa watermark nas tabelas marcadas como incrementais.
• RECRUTA_DATABRICKS_HOST / HTTP_PATH / CATALOG / TENANT — Os quatro parâmetros de conexão, configuráveis na aba 4 · Ambiente.

O que conferir depois

• No log: quantas tabelas vieram e quantas deram erro.
• Na aba 0 · Início: as linhas de arquivos gerados devem virar ✅.
• Se rodou incremental, confira se o número de linhas novas faz sentido — zero linhas novas é possível, mas merece um olhar.

Problemas comuns

A ficha financeira, em detalhe

A folha de pagamento por rubrica é o insumo do custo por unidade no Simulador. Até a versão 6.0 ela entrava por queda manual de arquivo, vinda do projeto irmão; desde a 6.1 é extraída aqui.

A etapa pessoal procura a ficha nesta ordem: RECRUTA_FICHA_FINANCEIRA → o que esta extração gravou → os caminhos legados. Não achando nenhuma, ela roda só a contagem e omite o custo — em vez de exibir R$ 0,00.

III.4 · Etapa classificacao — etiquetar os textos

Para que serve

Percorre cada especificação de classificação e atribui, a cada texto de currículo, um rótulo da taxonomia: área e subárea. É o que permite contar «quantas pessoas desta unidade trabalham com dado».

Como executar

Marque classificacao (e, junto, descoberta).

python pipeline.py --etapas classificacao,descoberta

Como funciona por dentro

A etapa não sabe o que é «experiência» ou «capacitação». Ela percorre o catálogo semantica.especificacoes.ESPECIFICACOES, e cada especificação descreve o que carregar, como montar o texto e em que eixos classificar. Para classificar um campo novo, edita-se o catálogo — este arquivo continua igual.

O ciclo por especificação é sempre o mesmo: carrega as fontes (Parquet interno, com recurso ao CSV legado); monta o texto; classifica em todos os eixos, com cache por hash; grava o CSV compatível com a API mais o Parquet interno; junta os «Indefinido» para a descoberta; e devolve as métricas para o manifesto.

Quando o reranker está ligado, os casos da zona cinzenta passam por um segundo modelo, mais caro e mais preciso, que reordena os candidatos. Com RECRUTA_TOP_N_ROTULOS maior que zero, a coluna de auditoria passa a registrar as alternativas em ordem, com o score de cada uma.

O que lê e o que grava

Parâmetros que você pode ajustar

• RECRUTA_RERANKER=1 — Liga o segundo modelo na zona cinzenta. Baixa ~2 GB na primeira vez.
• RECRUTA_TOP_N_ROTULOS — 0 (padrão), 3, 5 ou 10. Acima de zero, grava o ranking completo na auditoria.
• RECRUTA_MODELO_VETORIAL — Modelo de embeddings. Padrão intfloat/multilingual-e5-large-instruct.
• RECRUTA_BATCH — Tamanho do lote de vetorização. 0 = automático.

O que conferir depois

• A proporção de «Indefinido» — subiu muito? Houve mudança de fonte ou de glosa.
• O relatório de qualidade, na pasta de relatórios.
• Se ligou o top-N: abra a coluna de auditoria e veja se o 2º e o 3º colocados fazem sentido. É a forma mais barata de avaliar a taxonomia.

Problemas comuns

III.5 · Etapa descoberta — o que a taxonomia ainda não cobre

Para que serve

Pega os textos que ficaram sem rótulo, agrupa os que se parecem entre si e devolve sugestões de rótulos novos, prontas para a curadoria humana avaliar. É como o dicionário cresce a partir da realidade.

Como executar

Marque descoberta junto com classificacao.

python pipeline.py --etapas classificacao,descoberta

Como funciona por dentro

A descoberta só roda se a classificação rodou nesta execução e produziu indefinidos. Se a classificação foi pulada porque nada mudou, não há o que descobrir — e a etapa se anuncia como ignorada.

Os indefinidos são agrupados por proximidade semântica; cada agrupamento vira uma sugestão com exemplos reais do que caiu ali.

O que lê e o que grava

Parâmetros que você pode ajustar

• — — A etapa não tem parâmetros próprios; herda o codificador da classificação.

O que conferir depois

• Quantos agrupamentos vieram e se algum deles é grande o bastante para virar rótulo novo.
• Se o mesmo agrupamento reaparece execução após execução, é sinal forte de lacuna real na taxonomia.

Problemas comuns

III.6 · Etapa siape — traduzir os códigos funcionais

Para que serve

Transforma códigos do SIAPE em informação legível: vínculo, cargo, unidade de exercício, situação funcional, faixa etária. É o que permite filtrar por unidade e por cargo nas telas.

Como executar

Marque siape.

python pipeline.py --etapas siape

Como funciona por dentro

A lógica é a mesma do notebook original, reorganizada como uma tabela declarativa de junções — e com três defeitos corrigidos, que vale conhecer porque explicam números que já estiveram errados:

Indicador de estabilidade. Havia três atribuições em sequência em que a terceira sobrescrevia a primeira, com uma linha morta no meio. A regra agora vem da configuração, explícita e auditável. O sentido do campo ainda precisa de confirmação no dicionário do SIAPE — ver Parte VI.

Idade. O arredondamento estourava se houvesse data de nascimento inválida. Agora usa inteiro anulável, e a faixa etária recebe «Não informado» — rótulo que já existia no código e nunca era alcançado.

Junção com currículos. O comentário dizia junção externa (para achar o cidadão sem vínculo), o código fazia junção à esquerda, e o ramo do cidadão estava comentado. Hoje isso é uma decisão explícita de configuração — modo_juncao —, sem código morto.

A hierarquia das unidades é montada aqui. dimunidadeorganizacional é denormalizada: cada unidade é uma linha e traz onze blocos descrevendo seus ancestrais (nivel_00_*_pai até nivel_10_*_pai). A etapa reconstrói dali a hierarquia_completa — as siglas da unidade até a raiz, separadas por | — e a Secretaria, que é o penúltimo elemento dessa cadeia (o nível logo abaixo da raiz). O arquivo sai com o mesmo nome, mesmo lugar e mesmas colunas de quando era colocado à mão, para que nada a jusante precise mudar.

O que lê e o que grava

Parâmetros que você pode ajustar

• --modo-juncao servidores — Junção à esquerda: só quem tem vínculo.
• --modo-juncao todos — Junção externa: inclui quem tem currículo e não é servidor.

O que conferir depois

• Total de vínculos e de pessoas distintas — são números diferentes, e é assim mesmo (ver etapa pessoal).
• Proporção de «Não informado» em faixa etária.

Problemas comuns

A hierarquia de UORG — duas armadilhas que já custaram caro

A unidade de exercício é a chave de quase tudo: filtrar por setor, montar o DFT, contar efetivo e folha. Duas falhas nessa derivação passaram despercebidas por semanas porque nenhuma delas dá erro — os números simplesmente encolhem.

1 · Nível não é código

A escolha da coluna do código da unidade aceitava ni_uorg em primeiro lugar. Mas na dimensão real ni_uorg é o nível hierárquico (profundidade), com apenas 11 valores distintos, de 2 a 12; o código de verdade é co_uorg, com 38.710 valores. O zfill(9) logo abaixo transformava o nível em «código» (000000002…), e o cruzamento com o SISDIP desabava.

ni_uorg foi removida até como alternativa: casar por ela é pior que falhar, porque a perda é silenciosa. O teste que existia mascarava o defeito — usava valores de código numa coluna que, no dado real, guarda nível.

2 · A ordem em que a hierarquia é derivada

A tabela «pais e filhos» era regravada depois do enriquecimento que a consome. O carregamento das dimensões lia a versão da execução anterior, e a hierarquia dos servidores ficava sempre um ciclo atrasada — e, como a assinatura não mudava de uma execução para a outra, a seguinte era pulada e a defasagem nunca era alcançada. Resultado: hierarquia_emissao vazia em 98,6% das linhas, e o nome da unidade aparecendo como nan nas telas.

Hoje ela é gerada antes do carregamento, e VERSAO_HIERARQUIA_UORG entra na assinatura para que a correção alcance o dado. Medido com a tabela correta: a hierarquia passa a preencher 632.406 de 687.099 linhas (92%).

III.7 · Etapa curriculos — o retrato de cada pessoa

Para que serve

Junta tudo o que se sabe de cada servidor num texto único, gera o vetor de significado que a busca usa e — quando pedido — o resumo executivo e a nota fixa nas nove dimensões.

É a etapa mais importante do pipeline para a coerência do sistema: é ela que faz a mesma pessoa ter a mesma nota em todas as telas.

Como executar

Atalho Currículos + IA local, ou marque curriculos e a opção de resumo por IA.

python pipeline.py --etapas curriculos --resumo-ia

Como funciona por dentro

Super texto canônico. O texto que gera o hash é montado por uma função única e versionada. Mudar essa função invalida tudo — por isso ela é versionada explicitamente, e não editada por acidente.

Cache por conteúdo. O vetor é reaproveitado pelo hash do texto: dois currículos idênticos são vetorizados uma vez só.

Vetor pronto para a API. Gravado como lista de float32 nativa, nunca como texto — para a API não pagar uma conversão linha a linha a cada busca. Numa base de 250 mil currículos, essa diferença é o que separa uma busca instantânea de uma busca inviável.

Resumo e nota por IA (opcional): só roda para quem mudou de hash, o que torna viável manter a base atualizada sem reprocessar tudo.

Anonimização (só com --curriculos-api): antes de qualquer texto sair da máquina, nome, CPF, e-mail, telefone e matrícula são removidos. O nome é removido primeiro como expressão completa e depois token a token, ignorando partículas de ligação («de», «da», «dos») para não destruir nomes de órgãos e de lugares no meio do texto.

O que lê e o que grava

Parâmetros que você pode ajustar

• --resumo-ia — Liga o resumo executivo e a pontuação fixa das 9 dimensões.
• --curriculos-api — Opt-in: envia o texto anonimizado ao agente por API. Exige agente configurado.
• --modo-juncao — servidores (padrão) ou todos.
• --teste — Recorte de RECRUTA_LIMITE_TESTE linhas (padrão 1000).

O que conferir depois

• Com a API no ar, o botão Cobertura da nota fixa de currículo (aba 2) mostra quantos currículos já têm nota pronta.
• Nas telas, o selo 🧮 ao lado de um perfil confirma que a nota veio do pipeline.
• Se ligou --curriculos-api, confira no log a linha que confirma a anonimização e o provedor usado.

Problemas comuns

Rodar aos poucos sem perder o que já foi feito

O caso real que desenhou esta parte: gerar a nota para um grupo de pessoas neste mês e para outro grupo no mês que vem, sem que o segundo apague o primeiro. São três mecanismos independentes, e cada um cobre uma falha diferente.

A planilha de conferência (XLSX)

Ao fim da etapa sai Base_Dados_Curriculos_Vetorizada_Visor.xlsx, ao lado do parquet. É um visor, não um espelho: leva identificação, lotação, o super texto e todas as colunas terminadas em _ia — uma dimensão nova de pontuação aparece na planilha sozinha, sem mexer em lista nenhuma.

Por que não a base inteira: medido, as 172 colunas dariam ~610 MB e ~6 minutos a cada execução, e um .xlsx desse tamanho o Excel não abre. O visor sai em ~30 segundos. Para exportar tudo mesmo: RECRUTA_XLSX_CURRICULOS=completo.

• A coluna de vetor é detectada pelo conteúdo e removida — 1.024 números por linha não têm uso em planilha e multiplicam o arquivo.
• Célula acima de 32.767 caracteres é truncada com «…», que é o limite duro do formato: passar dele não gera arquivo ruim, gera arquivo que não abre.
• Falha na planilha nunca derruba a etapa — o parquet já está salvo quando ela é gerada. O caso mais comum é a planilha estar aberta no Excel, e a mensagem diz exatamente isso.

III.8 · Etapa oportunidades — ler os editais

Para que serve

Lê cada edital ou oportunidade e extrai o perfil desejado, também nas nove dimensões, para que vaga e pessoa fiquem na mesma régua.

Como executar

Marque oportunidades. Usa IA.

python pipeline.py --etapas oportunidades

Como funciona por dentro

A correção central desta etapa: o notebook original pulava a vaga se o identificador já constasse do histórico. Uma vaga editada depois de publicada — e existe um campo de data de atualização justamente para isso — nunca tinha o perfil regenerado. O molde da busca ficava desatualizado em silêncio.

Hoje vale o mesmo padrão do DFT: o hash é do conteúdo que alimenta o prompt, somado à versão do prompt e ao modelo. Mudou qualquer um dos três, a análise é refeita.

O produto também mudou. Em vez de um parágrafo solto, a IA devolve um objeto estruturado: resumo executivo, atribuições, requisitos separados entre obrigatórios e desejáveis, perfil ideal, leitura das nove dimensões e palavras-chave — tudo ancorado na fonte, com temperatura zero.

A coluna pontuacao_vaga_ia guarda a nota da vaga nas nove dimensões. É ela que permite ao sistema comparar candidato e edital sem precisar enriquecer nada na hora da consulta.

O que lê e o que grava

Parâmetros que você pode ajustar

• --sem-ia — A etapa se anuncia como ignorada, e não falha.
• Agente por API — Permitido: edital é documento público, sem dado pessoal.

O que conferir depois

• Abra uma vaga no sistema e veja se o perfil faz sentido em relação ao texto do edital.
• Se uma vaga foi editada recentemente, confirme que o perfil acompanhou a edição.

Problemas comuns

Os editais em números, hoje

9.543 oportunidades publicadas em 5.936 editais — 8.542 já traduzidas para a régua das nove dimensões.

III.9 · Etapa dft — retratar as unidades

Para que serve

Lê o dimensionamento da força de trabalho de cada unidade e produz missão, entregas, competências exigidas e a pontuação da unidade nas nove dimensões.

É o lado «demanda» de todas as comparações do sistema: é contra este retrato que candidatos e equipes são medidos.

Como executar

Atalho DFT das unidades. Usa IA e costuma ser a etapa mais longa depois de curriculos.

python pipeline.py --etapas dft

Como funciona por dentro

O controle de hash por unidade já existia e foi preservado. O que mudou:

Unidade que declarou só a categoria não vai ao modelo. A categoria («Ouvidoria», «Orçamento») é um rótulo de lista suspensa, não uma descrição. Quem preencheu apenas ela — sem entrega, atividade ou fluxo — não declarou trabalho: mandá-la ao modelo gastava uma chamada de API e voltava sem competência (a saída vinha «nan»). O corte é por conteúdo substantivo (entrega/atividade/fluxo), não por um número de caracteres inventado — e o log diz quantas saíram (foram 152 de 5.945, 2,6%). Não é corte silencioso: quem lê o log entende por que o total encolheu.

A chave de invalidação passou a incluir a versão do prompt e o modelo. Antes, melhorar o prompt não regenerava as análises antigas — elas ficavam congeladas na versão anterior para sempre.

Saída estruturada (esquema JSON) no lugar de fatiar o texto por marcadores. A versão antiga caía no tratamento de erro e gravava «Erro na extração das tags.» como se fosse a análise — texto que chegava à tela do gestor com aparência de conteúdo.

Falha vai para a fila de retentativas, nunca para a coluna de dados. Esta é a mesma regra que a Parte V chama de «falha não é resultado», aplicada na origem.

A coluna pontuacao_dft_ia é a exigência canônica da unidade. Quando ela existe, o Raio-X e o Gap Analysis a usam como régua e pedem à IA apenas a redação das justificativas — nunca uma nota nova.

O que lê e o que grava

Parâmetros que você pode ajustar

• --sem-ia — Etapa ignorada, com aviso.
• Agente por API — Permitido: atividade de unidade não é dado pessoal.
• Paralelismo em lote — Controlado internamente, para não saturar o provedor.

O que conferir depois

• Abra o Raio-X de uma unidade conhecida e veja se a missão bate com a realidade dela.
• Confirme que aparece o selo 🧮 (nota do pipeline) e não 🧠 (nota gerada na hora) — se aparecer 🧠, a unidade ainda não tem pontuacao_dft_ia.

Problemas comuns

O DFT em números, hoje

5.793 unidades descreveram o próprio trabalho — e 1.544 delas (26,7%) declararam pouco demais para sustentar competências específicas.

III.10 · Etapa cursos — o catálogo da Escola Virtual

Para que serve

Monta o catálogo de cursos da EV.G/Enap e marca quais dimensões cada curso desenvolve. É o que permite ao sistema responder «e agora, o que faço com essa lacuna?» com um curso concreto e um link.

Como executar

Atalho Catálogo de cursos.

python pipeline.py --etapas cursos

Como funciona por dentro

Fonte dupla, de propósito. O CSV oficial de exportação do catálogo — sem login e sem raspagem — é a fonte de verdade da lista de cursos que existem, com nome, eixos temáticos, competências, apresentação, público-alvo e conteúdo programático. A página de cada curso é o único lugar onde aparecem avaliação, idioma, trilha oficial e cursos relacionados.

Isto não é «baixar tudo todo mês». O catálogo tem cerca de mil cursos e cresce aos poucos: a Enap publica cursos novos, não republica os antigos. Buscar de novo a página de um curso que já foi lido e não mudou seria trabalho jogado fora e tráfego desnecessário num site público. Só é buscado o que é novo ou mudou.

O enriquecimento por IA é opcional: com roteador disponível, a etapa marca as dimensões que cada curso desenvolve; com --sem-ia, roda apenas a coleta.

O que lê e o que grava

Parâmetros que você pode ajustar

• --sem-ia — Coleta sem o enriquecimento por dimensão.
• Agente por API — Permitido: curso é informação pública.

O que conferir depois

• Botão Situação do catálogo na aba 2: quantos cursos e de onde.
• Depois de rodar, use Recarregar catálogo de cursos para a API reler o arquivo sem reiniciar.

Problemas comuns

III.11 · Etapa pessoal — contar gente e folha

Para que serve

Apura, para cada unidade e cada situação funcional, quantos vínculos e quantas pessoas distintas existem, separando os ativos do restante — e a folha bruta correspondente. Alimenta o quantitativo e o custo no Simulador.

Como executar

Atalho Contagem de pessoal. Não usa IA e é rápida.

python pipeline.py --etapas pessoal

Como funciona por dentro

Duas métricas, porque a pergunta muda. Um servidor pode ter matrícula em mais de um órgão, às vezes no mesmo. Então:

• Por unidade, a pergunta é «quantos vínculos há aqui» — conta cada matrícula. É vinculos, e é aditivo: pode somar entre grupos.

• Quantas pessoas é contagem distinta de CPF — é pessoas, e não é aditivo: a mesma pessoa em dois órgãos conta uma vez no total e duas nos órgãos.

Por isso as duas convivem na saída, e o total de pessoas distintas é recalculado em cada nível — unidade, órgão, geral —, nunca somado. Somar pessoas entre unidades produz um número maior que o efetivo real, e foi um erro clássico de relatório antes desta etapa existir.

O que lê e o que grava

Parâmetros que você pode ajustar

• — — A etapa não tem parâmetros próprios.

O que conferir depois

• No Simulador, o bloco de quantitativo deve mostrar o efetivo real da unidade — que é maior que o número de currículos analisados, e está certo assim.
• Confira uma unidade cujo efetivo você conheça de cor.

Problemas comuns

III.12 · O manifesto, na prática

O manifesto é o que torna a segunda execução barata. Ele grava, por etapa: a assinatura das condições, o número de linhas produzidas, os detalhes relevantes e o tempo gasto. Ao fim de cada execução, imprime o resumo.

O que entra na assinatura

• os arquivos de entrada (pelo hash do conteúdo, não pela data de modificação);
• os parâmetros da etapa — modo de extração, modo de junção;
• a versão do prompt, para as etapas que usam IA;
• o recorte de pessoas, na etapa curriculos — escolher outras pessoas reexecuta a etapa (antes ela era pulada, e elas nunca ganhavam a nota);
• o mapeamento de UORG e a versão da derivação da hierarquia, na etapa siape;
• as opções de qualidade da classificação (reranker e top-N).

Pontos de salvamento, e o que se perde numa interrupção

As etapas de IA gravam o resultado durante o lote, e não só no fim. Sem isso, uma interrupção descartaria tudo o que estava no buffer — e são chamadas de modelo já pagas e já esperadas.

O intervalo acompanha o tamanho do lote, porque um valor fixo erra nas duas pontas — e as duas doem. Gravar de 25 em 25 num lote de 200 mil currículos são 8.000 reescritas de um arquivo de centenas de MB (o cache é regravado inteiro a cada ponto, e mora no OneDrive). Gravar de 100 em 100 numa cauda de 81 unidades não grava nenhuma vez, e uma queda na quinta hora perde tudo.

Sempre cerca de 100 gravações, seja qual for o lote

core.cache.intervalo_checkpoint(total)   # = max(25, min(2000, total // 100))

lote      81  ->  grava a cada    25 itens   (3 gravações)
lote     500  ->  grava a cada    25 itens   (20 gravações)
lote   5.793  ->  grava a cada    57 itens   (101 gravações)
lote 200.298  ->  grava a cada 2.000 itens   (100 gravações)

Como forçar reexecução

Três caminhos, do mais cirúrgico ao mais amplo: mudar algo que entra na assinatura (o correto, e automático); marcar Reprocessar tudo na aba 1; ou usar --forcar na linha de comando. Não existe caminho para o pipeline «esquecer» uma etapa isolada — e isso é proposital, porque a dependência entre etapas ficaria inconsistente.

III.13 · A camada de IA

Provedores

O roteador abstrai o provedor. Localmente é o Ollama; por API, Google (Gemini/Gemma), OpenAI ou Anthropic (Claude). A escolha é feita na aba 3 · IA / Modelos e gravada em config_ia_rapido.json.

Rate limiting, múltiplas chaves e o pool de modelos

Cabem quantas chaves você quiser, do mesmo provedor. O roteador alterna entre elas e respeita o limite de requisições por minuto de cada uma, com recuo progressivo quando o provedor sinaliza excesso. É isso que torna viável processar dezenas de milhares de registros numa única execução.

Além das chaves, o roteador reparte o lote entre vários modelos ao mesmo tempo. No nível gratuito do Google os limites são por modelo, então as vazões somam: cada par (chave × modelo) vira um trabalhador com seu próprio freio, e todos puxam de uma fila única. Repartição fixa não serviria — as capacidades são desiguais demais, e o modelo mais fraco receberia uma fatia que nunca terminaria. Quando um modelo atinge o teto diário, ele se aposenta e devolve o item à fila; o lote segue nos outros.

Os três tetos, e qual deles morde primeiro

A leitura que importa: o teto que morde não é sempre o mesmo. Nas Gemma é o TPM — o console do Google mostra o uso encostando em 19 mil tokens/minuto com o RPM em 4 de 30, ou seja, a cota de requisições sobrando enquanto a de tokens estoura. Nos flash é o RPD. Nas flash-lite, nenhum dos dois aperta para o tamanho dos nossos prompts, e é por isso que elas carregam o lote.

Para conferir onde está cada modelo, o console do Google mostra uso contra limite por modelo em AI Studio → Limite de taxa da API. Barra vermelha significa teto ultrapassado; RPM baixo com TPM no talo significa que o gargalo são os tokens, não as chamadas — e aí o caminho é encurtar o prompt, não pedir mais requisições.

Os dois caches da classificação

A etapa classificacao guarda duas coisas diferentes, e é por isso que há dois arquivos por bloco. Confundi-los custa horas de GPU.

Sem o segundo, cada ajuste de glosa mandava todos os textos distintos de volta ao E5. Com ele, a reclassificação recalcula só os 305 protótipos e compara.

Os dois caches de IA, e por que eles não se misturam

Existem dois caches de IA, com donos e destinos diferentes. Confundi-los explica quase toda surpresa de «por que isto está reprocessando?».

O modelo saiu da chave — e por que isso importa

Até setembro de 2026 o nome do modelo fazia parte da chave do cache do pipeline. A consequência foi cara e silenciosa: a análise de 5.510 unidades do DFT, feita ao longo de nove dias pelo pool do Google, ficou inalcançável no dia em que a etapa foi apontada para o Ollama local. O pipeline anunciou «5.793 UORG(s) · 0 do cache · 5.793 a analisar» e ia refazer tudo.

A regra vigente: a chave é conteúdo + versão do prompt. Trocar quem responde não invalida o que já foi respondido — o modelo continua gravado na coluna modelo do cache, que é onde a auditoria o procura. O que continua invalidando é o que muda a resposta: o texto de entrada e a versão do prompt (assim, melhorar o prompt segue tendo efeito retroativo).

A chave, em uma linha

# core/cache.py — a chave canônica de qualquer saída de IA
chave_ia(conteudo, versao)          # o modelo NÃO entra

# quem quiser o comportamento antigo declara, expressamente:
RECRUTA_CACHE_POR_MODELO=1          # aí o modelo volta à chave

A leitura ainda aceita as chaves antigas: consultar_ia tenta a chave canônica e, não achando, os rótulos de modelo que execuções anteriores usaram — inclusive os rótulos de pool (google-pool), que não aparecem na coluna modelo porque lá fica quem de fato respondeu. É por isso que uma produção antiga continua sendo aproveitada sem nenhum script de migração.

O teto de caracteres do currículo, e o item que ele corta

O campo Limite de caracteres (aba «5 · IA / Modelos») define quanto do currículo vai ao modelo. Ele já esteve dentro da versão do prompt, e ajustá-lo invalidava a base inteira — embora só mude o texto de quem ele corta.

Medido na base de produção: com teto de 8.000, apenas 15,2% dos currículos (30.403 de 200.298) são truncados. Os outros 84,8% recebem exatamente o mesmo prompt com qualquer teto. Hoje o teto entra na identidade do item, e só de quem ele corta:

Só invalida quem ele corta

identidade = f"{hash}|corte={limite}" if len(texto) > limite else hash

# efeito prático, medido ao mudar o teto de 8.000 para 10.000:
#   antes:  108 de 108 análises descartadas
#   agora:   28 descartadas (as que eram cortadas) · 80 preservadas

Tratamento de erro

Falha de IA vai para a fila de retentativas. Se, esgotadas as tentativas, o resultado não vier, a etapa registra a falha — e não grava a mensagem de erro na coluna de dados. Este manual insiste nesse ponto porque a versão anterior fazia exatamente isso, e o texto do erro chegava à tela do gestor com aparência de análise.

III.14 · O classificador e o reranker

O classificador percorre os eixos de cada especificação. Cada eixo tem a sua taxonomia, o seu limiar e a sua zona cinzenta, e produz uma decisão com: o rótulo escolhido, o score, o motivo da decisão e — quando o top-N está ligado — o ranking completo das alternativas.

O que o reranker corrige

Na zona cinzenta, a diferença de score entre o primeiro e o segundo colocado é pequena demais para confiar. O reranker é um segundo modelo, mais caro, que avalia os candidatos em pares e reordena. A decisão final registra rerank e margem_rerank, para que a auditoria saiba que aquele caso passou pelo segundo julgamento.

III.15 · A anonimização, em detalhe

Só é acionada quando o texto vai sair da máquina — ou seja, com --curriculos-api. O objetivo é enviar o máximo possível da trajetória para a IA analisar, e nada que identifique a pessoa.

O que é removido

• o nome completo, primeiro como expressão inteira;
• depois, cada token distintivo do nome, isoladamente — porque o texto pode citar só o primeiro nome ou só o sobrenome;
• CPF, e-mail, telefone e matrícula, por padrão de formato.

O que é preservado, e por quê

Experiência, formação, idiomas, cursos, competências, órgãos por onde passou, cargos exercidos — tudo permanece. É exatamente esse conteúdo que sustenta a leitura das nove dimensões; removê-lo tornaria a análise inútil.

IV.1 · Entrar no sistema

Com a API e o site no ar (aba 2 · Servidores do assistente), o endereço é http://localhost:9000/index.html. A barra superior tem seis abas, e elas são a espinha dorsal deste capítulo:

IV.2 · Busca de Talentos

É a tela mais usada e a mais longa. O fluxo tem quatro momentos: filtrar a população, descrever o que se procura, analisar com IA e montar o dossiê.

1 · Filtrar — a barra lateral

A barra lateral esquerda restringe a população antes de qualquer análise. Todo filtro é cumulativo, e o botão 🧹 Limpar Todos os Filtros zera tudo.

Três filtros têm seleção rápida (botão ⚡), que abre uma caixa de colagem para adicionar muitos valores de uma vez:

• ⚡ Colar Lista de CPFs — Cole uma lista de CPFs, um por linha, e use Adicionar CPFs à Seleção. Serve para analisar um grupo já definido fora do sistema.
• ⚡ Seleção Rápida (UORG) — Adiciona unidades por código.
• ⚡ Seleção Rápida (Nome) — Adiciona unidades pelo nome, com busca por trecho — «Contendo o texto (ex: SGP)».

Os campos da barra lateral, um a um

As oito abas de gráficos

Cada aba mostra a distribuição da população filtrada e funciona como filtro: clicar numa barra restringe a seleção. Todas têm o botão 🧹 Limpar filtros desta aba.

A tabela e a exportação

Abaixo dos gráficos fica a relação nominal. O campo 🧱 Colunas a exibir e exportar define o que aparece; 🔄 Aplicar Colunas reconstrói a tabela; e 📥 Baixar Relação Nominal em Excel (.xlsx) exporta exatamente o que está na tela, com os filtros aplicados.

Há ainda a 🧠 Busca Semântica Avançada (Opcional): um campo de texto livre que restringe por significado, e não por palavra — «Unidade que lida com análise de dados de saúde» encontra quem escreveu «vigilância epidemiológica» sem que os termos coincidam.

2 · Descrever o que se procura — os três modos

🧭 Preciso de ajuda para descrever o perfil

Abre o Assistente de Descrição do Perfil: um formulário com um campo por dimensão, cada um com exemplo concreto («Ex.: SIASG/Compras.gov.br, Excel avançado, Power BI»). Ao final, ✅ Montar descrição produz o texto do perfil já organizado. É o caminho recomendado para quem escreve o primeiro perfil.

🔍 Extrair Dados do Edital

Aceita o PDF do edital e extrai o perfil. Se o PDF for uma imagem sem texto extraível, a tela recusa com orientação de OCR em vez de devolver um perfil vazio — comportamento que substituiu uma versão anterior em que o erro técnico chegava à tela com aparência de análise.

3 · Analisar

🔍 Executar Busca Inteligente dispara a análise. O botão i ao lado abre o prompt usado — na aba 💡 Como funciona em linguagem corrente, e na aba 📄 Prompt completo o texto integral enviado à IA.

Os resultados vêm ordenados por aderência, com: nome, cargo, órgão, o percentual de similaridade, o Índice de Encaixe, o excedente e o selo de origem da nota. ✅ Selecionar Todos e ❌ Desmarcar Todos operam a lista inteira.

4 · Montar o dossiê

• ⬇️ Mover Selecionados para a Lista Final (Dossiê) — Passa os escolhidos para a lista final.
• 🗑️ Aplicar Descarte — Remove os marcados da lista final.
• 🧹 Esvaziar Lista Completa — Zera a lista final.
• 🧠 Gerar Parecer Profundo e PDF — Produz o dossiê completo, com parecer por pessoa. Roda na hora e você acompanha o progresso.
• 🚀 Gerar e Enviar em 2º Plano — O mesmo, em segundo plano — você pode sair da página. O sistema avisa quando terminar e oferece 📄 Baixar PDF gerado.
• 📄 Baixar Dossiê em PDF — Baixa o arquivo já gerado.

No dossiê, cada pessoa aparece com resumo, aderência, justificativa por dimensão e a teia das nove dimensões. O ranking traz as colunas #, Nome, CPF, Similaridade, Encaixe e Além — com N/A para quem falhou e uma nota de rodapé explicando cada coluna.

✉️ Convites a Talentos

A partir da lista, o botão ＋ Convidar monta uma lista de convites. O painel permite 🗑️ Esvaziar lista, remover um a um pelo ✕, escrever uma mensagem (em branco = texto institucional padrão) e 📨 Enviar convites.

IV.3 · DFT — Dimensionamento da Força de Trabalho

Duas sub-abas: 🔍 Explorador Semântico de Unidades e ⚖️ Gap Analysis (Equipe vs. DFT).

Explorador Semântico de Unidades

Encontra unidades por descrição, não por código. O campo de busca aceita linguagem natural — «Unidade que lida com análise de dados de saúde» — e há ⚡ Seleção Rápida (Hierarquia) para colar códigos. O botão 🔍 Encontrar / Filtrar Unidades executa.

Unidades cujo texto de DFT não é analisável (vazio, «N/I», «informação insuficiente») são omitidas da lista, em vez de aparecerem como opções que não levam a nada.

🧠 Gerar Relatório Estratégico da Unidade (9 Dimensões) — o Raio-X

Produz o retrato da unidade: missão, competências exigidas, a teia das nove dimensões e a justificativa de cada nota.

📄 Exportar Relatório em PDF gera o documento correspondente.

Gap Analysis — Equipe vs. DFT

Compara o que a unidade exige com o que a equipe tem. Selecione as hierarquias de DFT e as lotações reais; 🎲 Sortear N monta uma amostra aleatória quando a equipe é grande; 📥 Carregar Escopo e Gerar Gap Analysis executa.

O resultado traz a teia com as duas linhas — exigência e equipe —, a lacuna por dimensão e o texto de leitura. O cabeçalho informa, em letras miúdas e sem eufemismo, o escopo real: «Agregados de X de Y servidor(es) · N currículo(s) lido(s) na íntegra pela IA · régua: 🧮 pipeline».

📄 Exportar Gap Analysis em PDF gera o documento.

IV.4 · Mapa de Competências

Relatório gerencial de uma unidade: quem está lá, o que a equipe sabe, e como isso se distribui. Filtros próprios, com 🧹 Limpar, ⚡ Seleção Rápida de UORG e 🎲 Sortear 1–20 para amostragem.

• 📊 Gerar Relatório Analítico — Executa a análise da unidade.
• 📄 Exportar Mapa em PDF (com gráficos) — Gera o documento com as teias e as tabelas.
• i — Abre o prompt utilizado, em linguagem corrente e na íntegra.

IV.5 · Comparador

Três modos, escolhidos nos botões do topo: 👤 Currículos, 🏢 Unidades e 🧭 Currículo × Unidade.

👤 Currículos

Compara pessoas entre si. Selecione os currículos (do sistema ou anexando PDFs) e use ⚖️ Comparar Currículos. O resultado traz a teia sobreposta, a matriz de similaridade entre todos os pares, o par mais parecido, o mais distinto, e a síntese.

• 🧹 Limpar seleção — Zera a seleção do modo atual.
• 📄 Exportar Comparativo em PDF — Gera o documento com teia, matriz e síntese.

🏢 Unidades

Compara unidades entre si. ＋ Adicionar unidade de comparação cria um novo campo; cada um tem ⚡ Seleção Rápida (Hierarquia), 🎲 Sortear 1–20 e ✕ Remover. Há também um campo de atribuições informadas pelo gestor, texto livre de alta confiabilidade que entra como fonte.

Cada cartão de unidade informa o escopo real — «escopo: X de Y servidor(es) · Z currículo(s) lido(s) na íntegra» — e, quando a análise daquela unidade falha, ela sai do gráfico de teia e o cartão avisa, em vez de desenhar uma linha zerada que pareceria um perfil.

O PDF traz ainda a convergência das atribuições: a comparação do texto das entregas das duas unidades mais próximas — que é informação diferente da distância entre as notas.

🧭 Currículo × Unidade

Cruza pessoas com unidades: para cada par, o quanto aquela pessoa se encaixa naquela unidade. ＋ Adicionar unidade, 🧭 Cruzar Currículos × Unidades, 📄 Exportar Matriz em PDF.

IV.6 · Simulador de Movimentação

A tela que responde à pergunta mais difícil da gestão de pessoas: o que acontece com as duas unidades se esta pessoa mudar de lugar?

Os três modos

O que a simulação mostra, por lado

• Teia com três linhas: exigência da unidade, equipe antes e equipe depois — mais o perfil de quem se move, sobreposto;
• Nível (média da equipe na dimensão) e cobertura (quantos servidores têm nota 4 ou 5), lado a lado;
• Quantitativo e custo: efetivo real por situação funcional e folha bruta, vindos da etapa pessoal;
• Alertas de cabeça única: competências que ficariam sem detentor;
• Fragilidade estrutural, quando a equipe fica criticamente abaixo da régua;
• Atribuições informadas pelo gestor, quando preenchidas.

Cabeça única

Alerta as competências que ficariam com um único detentor ou com nenhum. Na permuta, o cálculo considera quem chega: se o único detentor sai mas o recém-chegado também domina aquela competência, não há órfã — e a tela marca «(coberta por quem chega)», porque a competência passa a depender de uma pessoa que acabou de entrar.

🧱 Fragilidade estrutural

Aparece quando a equipe, no cenário depois, fica criticamente abaixo da régua em três ou mais dimensões. É a resposta do sistema à pergunta «e se a pontuação média for muito baixa?»: em vez de um número pequeno numa tabela, o gestor recebe leitura e caminhos.

📄 Exportar Simulação em PDF gera o documento completo. 🧹 Limpar tudo reinicia a simulação.

IV.7 · Plano de cursos da EV.G

Onde há lacuna, o sistema oferece 🎓 Sugerir cursos da ENAP para estas lacunas. O plano relaciona, por dimensão e por prioridade, os cursos que cobrem aquela lacuna, com carga horária, eixos, motivo da indicação e — quando a Enap publica — a nota de avaliação e a trilha oficial.

📄 Exportar Plano de Desenvolvimento em PDF gera o documento, agora com o link de cada curso — é por ele que a equipe se matricula.

Quando nenhum curso do catálogo tem aderência suficiente a uma dimensão, o plano diz isso em vez de listar cursos fracos para preencher espaço.

Como um curso é casado com uma lacuna

Em duas camadas, e o motivo de cada indicação aparece no relatório:

As duas camadas textuais existem porque 62% dos cursos não têm a marcação oficial de competência. E há um piso de relevância: sem aderência real, o curso não entra — num documento institucional, sugerir curso irrelevante é pior que não sugerir nada.

IV.8 · Trilha de Capacitação — a aba 🧭

O plano de cursos responde «tenho esta lacuna, o que curso?». A aba Trilha responde as duas perguntas que faltavam no percurso: «o que existe sobre este tema?» e «este curso que eu escolhi, quanto resolve para a minha equipe?».

Buscar no catálogo, por tema livre

Digite um assunto — contratações públicas, análise de dados, LGPD — e o sistema procura em todo o catálogo da EV.G, sem partir de lacuna nenhuma. A busca é semântica e lexical sobre o texto do curso, com o mesmo piso de relevância do plano: tema sem aderência real devolve lista vazia, e não os primeiros cursos de uma ordenação sem sentido.

• Carga máx. (h) filtra antes de ranquear — útil quando há limite de horas.
• Cada resultado traz carga horária, tipo de oferta, nota da EV.G, trilha oficial e o link direto para a página do curso.
• Curso com descrição curta na origem é marcado com ⚠ — a pontuação existe, mas se apoia em pouco texto.

Avaliar os cursos escolhidos — o caminho inverso

Marque os cursos que interessam; eles vão para a cesta. Escolha o alvo e quantas pessoas a lacuna atinge, e o sistema calcula a utilidade de cada um:

A conta, e ela aparece na tela

utilidade = Σ  (ganho do curso na dimensão ÷ 5)  ×  lacuna  ×  pessoas
            d

# exemplo real da tela:
#   Atendimento ao Cidadão   ->  5/5 × lacuna 3 × 4 pessoas  =  12,0
#   Ciência de Dados         ->  1/5 × lacuna 3 × 4 pessoas  =   2,4

Os três fatores respondem a três perguntas distintas — o curso mexe nessa dimensão? o alvo precisa dela? quantas pessoas isso atinge? — e é por isso que um curso que resolve pouco para oito pessoas vence o que resolve muito para uma. A tabela mostra as parcelas separadas, não só o total: quem for questionado sobre a indicação precisa reconstruí-la à mão.

IV.9 · Os PDFs

Todo relatório do sistema tem versão em PDF, e todos seguem o mesmo padrão: capa com escopo, seção de metodologia, gráficos, tabelas e síntese.

IV.10 · O painel «Quem será analisado»

Aparece em toda tela que agrega equipe — Comparador de Unidades, Currículo × Unidade e Simulador — e controla quais currículos a IA lê na íntegra. É o controle que determina o custo, o tempo e a profundidade da análise.

O que fica fora da amostra não é ignorado: entra pelos agregados da equipe — formações, competências, experiências e cargos. A tela informa os dois números, e a Parte V · V.7 explica por que essa distinção importa.

IV.11 · O catálogo de prompts

Toda tela que usa IA tem o botão i, que abre o prompt daquela função em duas abas: 💡 Como funciona, em linguagem corrente, e 📄 Prompt completo, com o texto integral enviado ao modelo. São doze prompts:

IV.12 · Catálogo de mensagens e estados

O que o sistema diz quando algo não é normal, e o que cada mensagem significa.

IV.13 · Roteiros de uso

Quatro situações reais, do começo ao fim. São os caminhos que respondem à maior parte das perguntas que chegam ao sistema.

Roteiro 1 — Preciso encontrar alguém para uma vaga

1. Restrinja a populaçãoBarra lateral: órgão, unidade, carreira. Se já tem uma lista de CPFs, use ⚡ Colar Lista de CPFs.
2. Descreva o perfilSe há edital, use 📄 Selecionar Oportunidade — a régua já vem pronta. Se não há, escreva no modo manual, ou use 🧭 Preciso de ajuda para descrever o perfil.
3. Execute a busca🔍 Executar Busca Inteligente. Leia o ranking pelo Índice de Encaixe, não pela similaridade — encaixe responde «atende ao que pedi?», similaridade responde «tem o mesmo formato?».
4. Confira quem falhouLinhas «N/A — reprocessar» não foram avaliadas. Se forem muitas, o problema é o agente de IA, não os candidatos.
5. Monte o dossiê⬇️ Mover Selecionados para a Lista Final e 🧠 Gerar Parecer Profundo e PDF. Para listas grandes, use a geração em segundo plano.
6. Leia o dossiê com o documento ao ladoA nota é leitura do currículo; divergiu, prevalece o currículo.

Roteiro 2 — Vou mover um servidor e preciso saber o impacto

1. Abra o Simulador e escolha o modoTransferir, Saída sem destino ou Permuta — a escolha muda o cálculo, sobretudo o de cabeça única.
2. Selecione as duas unidades e quem se move
3. Ajuste «Quem será analisado»Se a decisão for relevante e a equipe for pequena, marque Todos. Quem se move entra sempre.
4. Leia nível E coberturaNível pode subir numa saída — é aritmética. A cobertura mostra a perda real.
5. Olhe os alertas de cabeça únicaCompetência que fica sem detentor é o risco que nenhuma média mostra.
6. Se aparecer o painel 🧱A equipe ficou criticamente abaixo da régua. Os três caminhos — desenvolver, recrutar, redistribuir — são informação, não recomendação.
7. Exporte o PDFCom ocultar identificação se o documento for circular além de quem já tem acesso aos dados nominais.

Roteiro 3 — Preciso justificar um plano de capacitação

1. Rode o Gap Analysis da unidadeDFT → ⚖️ Gap Analysis. Selecione as hierarquias e as lotações reais.
2. Leia o escopo declarado«X de Y servidores · N lidos na íntegra». Se a amostra for pequena para o peso da decisão, amplie e rode de novo.
3. Identifique as lacunasDimensões em que a equipe fica abaixo da exigência.
4. Peça os cursos🎓 Sugerir cursos da ENAP para estas lacunas.
5. Exporte o planoO PDF sai com o motivo de cada indicação, a carga horária e o link de matrícula.

Roteiro 4 — Duas unidades vão ser reorganizadas

1. Compare as duas no Comparador de UnidadesModo 🏢 Unidades, com as fontes que fizerem sentido — DFT, mapa da equipe, currículos, e as atribuições que o gestor informar.
2. Leia a convergência das atribuiçõesEla compara o texto das entregas, não as notas — duas unidades podem ter perfis parecidos e entregas completamente distintas.
3. Verifique o escopo de cada uma«escopo: X de Y · Z lidos na íntegra», no cabeçalho de cada cartão.
4. Simule os cenáriosUse o Simulador em modo Permuta para testar trocas concretas antes de decidir.
5. Exporte os dois PDFsO comparativo mostra o retrato; a simulação mostra o efeito. São documentos complementares.

IV.14 · O agente de IA nas telas

O painel 🛠️ Agente de Inteligência Artificial permite trocar o modelo sem reiniciar a API: ⚡ Testar agente faz uma chamada real, e ✅ Usar este agente passa a valer para as próximas análises. O padrão continua sendo o modelo local.

Os agentes por API trazem o selo 🛡️ sai anonimizado e pedem confirmação antes de entrar em uso: com eles, nome, CPF, e-mail, telefone e matrícula são retirados do texto antes do envio, e as pessoas passam a ser citadas como «Servidor 1», «Servidor 2» — os nomes reais voltam ao texto quando a resposta chega. O que continua saindo é o conteúdo profissional do currículo. A mecânica, o motivo de ela ter duas camadas e o que ela não resolve estão em VI.3.

Em toda tela que usa IA há o botão i, com duas abas: 💡 Como funciona, em linguagem corrente, e 📄 Prompt completo, com o texto integral enviado ao modelo. É a forma de auditar o que foi pedido sem depender de ninguém.

V.1 · A régua única

O princípio que organiza o sistema inteiro: a mesma unidade tem o mesmo número em toda tela, e a mesma pessoa também.

Parece óbvio, e não é: cada tela poderia perfeitamente chamar a IA e pedir uma leitura. Foi o que o sistema fazia. O resultado é que a mesma unidade aparecia com exigência 4 no Raio-X e 3 no Gap Analysis, no mesmo dia, e ninguém sabia dizer qual estava certa — porque as duas estavam, cada uma para a sua execução.

As quatro pontuações pré-calculadas

Como a régua se aplica em cada tela

• Raio-X do DFT — Se existe pontuacao_dft_ia, é ela que aparece. A IA recebe as notas e escreve a justificativa de cada uma, proibida de inventar evidência. Sem nota do pipeline, a IA pontua e a tela avisa (🧠).
• Gap Analysis — A exigência é congelada no prompt: a IA pontua apenas a realidade da equipe, nunca a exigência. Assim o lado «demanda» é o mesmo do Raio-X e do Simulador.
• Dossiê de candidatos — Se o currículo tem nota do pipeline, é ela que vale — mesmo que a IA devolva outra. A IA escreve a narrativa.
• Simulador e Comparador — Consomem as mesmas notas pré-calculadas.

V.2 · Similaridade: forma, não intensidade

O percentual de similaridade entre dois perfis é calculado por cosseno: ele mede o ângulo entre os dois vetores de nove dimensões, e não o tamanho deles.

Por isso, sob toda matriz de similaridade do sistema há a nota: «O percentual compara o formato do perfil, não a intensidade. Confira o nível nas teias e nas tabelas por dimensão.» E por isso a similaridade nunca aparece sozinha: ela vem sempre acompanhada do Índice de Encaixe, que mede outra coisa.

V.3 · O Índice de Encaixe

Responde à pergunta que a similaridade não responde: o quanto esta pessoa atende ao que esta vaga exige?

A fórmula

Encaixe = Σ mín(candidato_d , vaga_d)  ÷  Σ vaga_d  × 100

  · apenas sobre as dimensões EXIGIDAS (vaga_d > 0)
  · teto de 100% — exceder a exigência não gera mais que 100
  · o excedente é reportado à parte, como «Além»

• Por que o mínimo — Ter 5 numa dimensão que a vaga pede 3 atende àquela dimensão — e só. O excesso não compensa falta em outra.
• Por que só as dimensões exigidas — Uma vaga que não pede idiomas não deve penalizar nem premiar quem os tem. O que a vaga não pede não entra na conta.
• Por que o excedente aparece separado — É informação real e útil — a pessoa traz mais do que se pediu —, mas não é aderência. Misturar os dois produz um número que ninguém sabe interpretar.

V.4 · Nível, cobertura e massa

Três números diferentes sobre a mesma equipe, e cada um responde a uma pergunta distinta. Confundi-los é o erro de leitura mais comum.

É também o que explica um comportamento que assusta na primeira vez: numa saída, o nível pode subir. Se quem sai estava abaixo da média, a média sobe. É aritmética. A cobertura, que nunca sobe com uma saída, mostra a perda real — e a tela diz isso explicitamente sob a tabela.

V.5 · As matrizes de comparação

As matrizes são, nas palavras do responsável pelo sistema, «parte da essência do Recruta». Três regras governam todas elas.

1. Sem dado não é zero

Quando falta informação de um dos lados, a célula fica vazia («—», em cinza), e não zerada. Uma célula 0% afirma que os dois perfis são completamente diferentes; uma célula vazia afirma que não se sabe. São afirmações distintas, e o sistema não confunde mais as duas.

2. Destaque só sobre pares com dado

«Par mais similar» e «par mais distinto» são calculados apenas sobre os pares que têm dado dos dois lados. Antes, a busca pelo mínimo encontrava as células zeradas por ausência e destacava, como «mais distante», exatamente o par sobre o qual o sistema nada sabia.

3. Falha não entra na média

Perfis cuja análise falhou são excluídos dos agregados da equipe, e o número de falhas é reportado ao lado do número de válidos. Uma falha contabilizada como zero rebaixa a média da unidade inteira e produz uma leitura falsa da equipe.

V.6 · Falha não é resultado

A regra mais repetida do sistema, e a que mais custou a chegar. Ela tem quatro aplicações concretas:

V.7 · Honestidade de amostra

A IA lê na íntegra uma amostra de currículos; o restante da equipe entra pelos agregados — formações, competências, experiências, cargos. As duas coisas são legítimas, e a diferença entre elas importa.

Por isso toda tela que agrega equipe informa os dois números: «escopo: 42 de 60 servidores · 8 currículos lidos na íntegra». E, no Simulador, a nota de rodapé acrescenta sobre quantos servidores a média foi calculada, com o caminho para ampliar a amostra.

V.8 · Cabeça única

Identifica competências que dependem de uma só pessoa — ou que ficariam sem ninguém. É o risco que não aparece em nenhuma média.

• Perdida — Nenhum detentor restaria depois da movimentação.
• Frágil — Restaria exatamente um detentor.
• Coberta por quem chega — O único detentor restante é o recém-chegado. A competência não se perde, mas passa a depender de alguém que acabou de entrar.

V.9 · Fragilidade estrutural

A resposta do sistema à pergunta «e se a pontuação média for muito baixa?». Um número pequeno numa tabela não é acionável; um diagnóstico com caminhos é.

Quando dispara

• Com DFT: dimensões em que a equipe fica 1,0 ponto ou mais abaixo da exigência;
• Sem DFT: dimensões com nível abaixo de 2,5;
• em ambos os casos, é preciso haver três ou mais dimensões críticas;
• e a equipe precisa ter análise válida — sem dado, o painel não aparece.

Os três caminhos

V.10 · A política anti-invenção nos prompts

Todo prompt do sistema é construído sobre seis regras. Elas explicam por que os textos ficaram mais detalhados sem ficarem mais inventados.

1. Ancoragem obrigatóriaCada afirmação precisa apontar o trecho da fonte que a sustenta. Sem trecho, a afirmação não deve existir.
2. Vocabulário da fonteO modelo é instruído a usar os termos do documento lido, e não sinônimos «mais bonitos» — sinônimo é onde a invenção entra.
3. Sentinela declaradaHá um valor explícito para «não encontrei», que o modelo deve usar em vez de preencher com plausibilidade.
4. Proibições nominaisO prompt lista o que é proibido afirmar — inferir senioridade não declarada, supor motivação, atribuir traço de personalidade a partir de cargo.
5. Sinal de insuficiênciaQuando a fonte é pobre demais, o modelo deve dizer que é, e não compensar com generalidade.
6. Saída estruturada e temperatura zeroA resposta segue um esquema fixo, sem criatividade. Fatiar texto por marcadores — o método antigo — caía no tratamento de erro e gravava a mensagem de erro como se fosse a análise.

Transparência

Em toda tela que usa IA, o botão i mostra o prompt completo. Não é documentação: é o texto exato que foi enviado. Qualquer pessoa pode conferir o que foi pedido ao modelo, sem depender de quem construiu o sistema.

V.11 · Limites conhecidos

O que este sistema não consegue afirmar, e que nenhuma tela deve ser lida como afirmando:

• Não mede desempenho. Ele lê o que a pessoa declarou no currículo, e currículo é autodeclaração — mede o que foi registrado, não o que foi feito.
• Não compara pessoas de bases diferentes com a mesma confiança. Quem tem currículo curto tende a pontuar baixo por escassez de texto, não por escassez de competência.
• Não substitui entrevista nem avaliação funcional. É triagem e leitura, não juízo final.
• Não é prova documental. Os PDFs são apoio à decisão; o que vale juridicamente é a documentação oficial de cada servidor.
• Não vale contra o documento. Se a análise divergir do currículo, prevalece o currículo.

VI.1 · Onde os dados ficam

Todo o dado de produção mora numa pasta única, apontada pela variável RECRUTA_RAIZ e configurável na aba 4 · Ambiente. Dentro dela:

VI.2 · O que nunca vai para o Git

São dois repositórios independentes, cada um com o seu .gitignore: a raiz (pipeline) e Recruta_html (API e site), que tem o próprio .git e o próprio remote. As regras de um não valem para o outro.

O botão 🔎 Conferir dado sensível antes do commit (aba 7 · Git) lista o que entraria num commit agora e destaca o que bate com esses padrões. Ele é informativo — não bloqueia, porque bloquear commit por heurística produziria mais problema do que resolve.

Fontes que NÃO vêm do Data Lake

Quase tudo é extraído do Data Lake pela etapa extracao. As exceções são poucas e vale conhecê-las, porque cada uma é um ponto onde dado de produção entra sem passar pelo caminho controlado.

Restou uma: a base de e-mails. Ela é extraível pelo mesmo caminho que a ficha financeira e a hierarquia seguiram.

VI.3 · O que sai da máquina, e quando

A guarda de saída: o que o agente por API recebe, e o que não recebe

Por muito tempo as duas metades do sistema disseram coisas diferentes sobre o mesmo dado. No pipeline, currículo nunca viajava: só saía com --curriculos-api, marcada a cada execução, e com o texto anonimizado antes de sair. Nas telas, o painel 🛠️ Agente de Inteligência Artificial oferecia três provedores externos num menu — e o texto do currículo ia inteiro, com nome, CPF e e-mail. Não era defeito de código: eram duas metades construídas em momentos diferentes, e ninguém tinha notado que discordavam.

A v6.2 reunifica a regra. Agente local continua recebendo o texto completo — nada sai da máquina, e o nome real ajuda o modelo a escrever melhor. Agente por API passa a receber o texto anonimizado, sempre, sem opção de desligar.

Por que a proteção tem duas camadas

A pergunta natural é por que não anonimizar tudo num lugar só, no momento do envio. A resposta veio de uma medição, não de uma opinião.

Nome de pessoa não pode ser apagado no momento do envio, porque nesse ponto ele já se misturou às instruções do prompt. Cruzando os sobrenomes e nomes mais comuns do país com o texto dos prompts do sistema, cinco são também palavras do molde: Campos, Nascimento, Valores, Trabalho e Carla. Um servidor chamado João Campos faria sumir todo «campos» das instruções; o modelo devolveria saída fora do formato, e a tela mostraria erro sem que ninguém entendesse a causa.

• Camada 1 — na origem — Quem monta o trecho de currículo conhece o nome da pessoa e o remove ali, antes de o texto encostar no molde. É a mesma mecânica que montar_prompt_curriculo usa no pipeline desde sempre.
• Camada 2 — no funil — CPF, e-mail, telefone e matrícula são padrões, não palavras: não colidem com molde nenhum. Por isso podem ser removidos no último instante, de qualquer prompt — inclusive dos que forem escritos amanhã, por quem não souber desta regra. É a rede embaixo do trapézio, não o trapézio.

Quem pode chamar a API, e de onde

Desde 02/09, o login deixou de ser decorativo: chamadas que não vêm da própria máquina precisam de sessão. A varredura confirmou o que a auditoria suspeitava — o token criado no login não era exigido por rota nenhuma, e qualquer máquina que alcançasse a porta podia baixar a relação nominal por curl, sem nunca ter feito login (CORS não vale fora do navegador).

• Da própria máquina (127.0.0.1) — Passa como sempre passou. O assistente, os testes e o navegador local não mudam nada.
• De outra máquina — Exige o token de sessão no cabeçalho X-Recruta-Token — o site o envia sozinho depois do login. Sem token válido: 401 antes de tocar em qualquer dado.
• Fora da regra — /api/login (onde o token nasce), /api/status (saúde, sem dado pessoal), /api/sessao (restaura o F5) e o download de PDF por job, cujo endereço já é um identificador aleatório de uso único.

O que a guarda NÃO resolve

Currículo profissional sem identificação ainda pode permitir reidentificação por combinação: uma trajetória incomum — doutorado específico, cargo raro, órgão pequeno — identifica sozinha. A guarda reduz o risco; não o elimina, e não substitui a base legal.

Por isso o painel continua exigindo confirmação a cada troca para agente externo, com o texto do que sai e do que não sai, e continua remetendo à Lei nº 13.709/2018 (LGPD) e ao dever de usar apenas soluções de IA previamente autorizadas e contratadas pelo órgão — o que a Portaria MGI 3.485/2026 reforça ao exigir estudo prévio de risco e garantias contratuais para dado restrito. Anonimizar responde a um problema de dado pessoal; contratação e classificação de acesso são outro problema, e continuam de pé.

VI.4 · Mudar a pasta de dados de lugar

Procedimento para levar as bases para outro local — por exemplo, a pasta compartilhada da equipe no OneDrive. Pode ser feito pela aba 4 · Ambiente ou pela linha de comando.

As três etapas, na ordem — e nesta ordem

python ferramentas/mover_dados.py --destino "<novo caminho>"
python ferramentas/mover_dados.py --destino "<novo caminho>" --copiar
python ferramentas/mover_dados.py --destino "<novo caminho>" --apagar-origem

1. Ver o planoMostra o inventário — quantos arquivos, quanto espaço — e avisa sobre caminhos que ficariam longos demais no destino. Não copia nada.
2. Copiar e conferirCopia e depois confere arquivo por arquivo. A origem permanece intacta. Se a conferência acusar diferença, o processo para aí.
3. Apagar a origemSó depois da conferência limpa, e com confirmação. É a única ação irreversível do procedimento.
4. Apontar o sistema para o novo lugarPreencha RECRUTA_RAIZ na aba 4 · Ambiente e use Conferir o que existe para validar.

VI.5 · Rotina mensal sugerida

Quanto tempo leva pontuar um setor

Ritmo medido na máquina de produção (Ollama local, GPU de 4,3 GB, três análises em paralelo): ~123 segundos por currículo, ou cerca de 29 por hora.

O que acompanhar todo mês

• Proporção de «Indefinido» na classificação — se subir, a realidade mudou e a taxonomia não acompanhou.
• Cobertura da nota fixa — quanto maior, mais telas respondem com a régua única.
• Número de falhas de IA no log — falha crônica indica provedor instável, chave esgotada ou modelo indisponível.
• Tamanho do cache de IA — cresce com o uso; se estiver zerado depois de muita execução, o caminho provavelmente está errado.
• A linha «N do cache · M a analisar» no início de cada etapa de IA. É o termômetro mais direto: um 0 do cache inesperado significa que alguma coisa mudou a chave — o texto de entrada, a versão do prompt, ou o teto de caracteres.
• Nomes de unidade aparecendo como nan nas telas ou no log. É sintoma de hierarquia não derivada; rode o atalho Corrigir hierarquia (UORG).

VI.6 · Os testes

Três baterias, 882 verificações no total, todas rodando em segundos, sem tocar nas bases reais e sem chamar IA.

Rodar pela linha de comando, se necessário:

Sempre com PYTHONIOENCODING=utf-8 no Windows

python testes/test_pipeline.py
python testes/test_integracao.py
python testes/test_api.py

VI.7 · Solução de problemas

O sistema não abre

Os números parecem errados

A IA falha

Extração e dados

VII.1 · Como classificar um campo novo

O motor de classificação não sabe o que é «experiência» ou «capacitação». Ele percorre um catálogo de especificações, e cada especificação descreve o que carregar, como montar o texto e em que eixos classificar. Acrescentar um campo novo é declarar uma especificação — o motor não muda.

Passo 1 — (opcional) criar a taxonomia

Se o campo novo precisa de um dicionário próprio, crie um JSON em dicionarios/ e carregue-o. Se as taxonomias existentes — áreas ou categorias — servirem, pule este passo.

# dicionarios/producao_academica.json
[
  {"eixo": "Publicações", "tipo": "Artigo em periódico revisado por pares"},
  {"eixo": "Publicações", "tipo": "Capítulo de livro"}
]

Passo 2 — escrever o montador do texto

Uma função que recebe os DataFrames de origem e devolve um DataFrame com a coluna TEXTO_CLASSIFICAR preenchida. É aqui que se decide o que entra no texto — e, portanto, o que o classificador vai enxergar.

def montar_publicacoes(fontes):
    df = fontes["principal"].copy()
    df["TEXTO_CLASSIFICAR"] = (canonizar_serie(df["TX_TITULO"])
                               + ". Publicado em: "
                               + canonizar_serie(df["TX_VEICULO"]))
    return df

Passo 3 — declarar a especificação

No catálogo semantica/especificacoes.py, declare: as fontes a carregar, o montador, os eixos de classificação, a taxonomia de cada eixo, os limiares e os nomes das colunas de saída.

Passo 4 — rodar

python pipeline.py --etapas classificacao

O que o motor entrega automaticamente

Sem que você escreva uma linha para isso:

• deduplicação por texto — o mesmo título em dez currículos é processado uma vez;
• cache persistente, com a versão da taxonomia embutida na chave;
• classificação em dois estágios — primeiro o agrupador, depois o rótulo;
• decisão por limiar e por margem, com marcação dos casos ambíguos;
• multirrótulo com top-k, quando declarado;
• reranking na zona cinzenta, se ativado;
• métricas por bloco e coleta dos «Indefinido» para o relatório de descoberta;
• exportação em CSV compatível com a API e em Parquet interno.

Um exemplo já pronto no código

O bloco soft_skills está declarado em especificacoes.py e desativado (ativo=False), à espera de uma taxonomia comportamental dedicada. Serve como modelo de declaração completa.

Há também um teste que prova a extensibilidade: em testes/test_pipeline.py, o caso «campo NOVO classificado sem tocar no motor» declara uma especificação inédita e verifica que ela é processada sem nenhuma alteração no classificador.

VII.2 · A curadoria do dicionário

A qualidade da classificação depende mais do dicionário do que do modelo. Esta seção é o roteiro de quem cura.

O arquivo

dicionarios/dicionario.xlsx — uma planilha, aberta no Excel, sem necessidade de saber nada sobre o sistema. É gerada pela aba 5 · Dicionário do assistente, ou por python ferramentas/dicionario.py exportar.

As colunas

O ciclo de trabalho, passo a passo

1. A equipe técnica gera a planilha (uma única vez)Aba 5 · Dicionário → Exportar (recriar dos JSON). Cria o dicionario.xlsx a partir dos dicionários existentes. Cuidado: reexportar depois pode sobrescrever curadoria já feita — por isso o botão pede confirmação.
2. A curadoria editaO arquivo é entregue a quem cura. As linhas em amarelo são as ainda não revisadas — a fila de trabalho fica visível ao abrir. Para escrever um verbete: use os termos concretos que apareceriam num currículo, diga o que a categoria abrange e o que fica de fora, e não repita o nome da categoria como se fosse definição.
3. A equipe técnica validaAba 5 · Dicionário → Validar a planilha. Confere campos obrigatórios, duplicidade e rótulo sem glosa antes que a planilha entre em produção.
4. Rodar a classificaçãoAba 1 · Pipeline, etapa classificacao. Como a assinatura mudou, o reprocessamento dos blocos afetados acontece sozinho.
5. A descoberta devolve sugestões prontasOs textos que ficaram «Indefinido» voltam agrupados, com exemplos reais — e viram candidatos a categoria nova na próxima rodada de curadoria.

Os rascunhos de verbete por IA

A aba 5 gera rascunhos com o modelo local, a temperatura zero, marcando cada verbete como revisado = NAO e registrando a origem como llm:<modelo>. O prompt instrui o modelo a delimitar a fronteira da categoria — dizer o que fica de fora —, que é a parte difícil e a que mais melhora a classificação.

Criar um dicionário novo

Crie o JSON em dicionarios/, com a estrutura de eixo e tipo mostrada em VIII.1, carregue-o e passe a referenciá-lo na especificação do bloco. A planilha de curadoria passa a incluir a taxonomia nova na coluna taxonomia.

VII.3 · Ferramentas auxiliares

Todas têm botão no assistente. A linha de comando está aqui para quem precisar automatizar ou depurar.

Geração de glosas

python ferramentas/gerar_glosas.py                    # tudo que ainda não tem glosa
python ferramentas/gerar_glosas.py --taxonomia areas  # só uma taxonomia
python ferramentas/gerar_glosas.py --refazer          # regrava inclusive as existentes
python ferramentas/gerar_glosas.py --so-nao-revisadas # relatório do que falta revisar

Calibração de limiares

Dois usos, e a diferença entre eles importa:

# diagnóstico: onde estão as massas de score e de margem
python ferramentas/calibrar_limiares.py --bloco experiencia --amostra 3000

# calibração de verdade: contra um gabarito rotulado à mão
python ferramentas/calibrar_limiares.py --bloco experiencia \
       --gabarito revisao/experiencia_rotulada.csv

O gabarito é um CSV com separador ponto e vírgula e as colunas texto e rotulo_correto. Use «Indefinido» como rótulo correto quando nada do dicionário servir — é assim que a ferramenta aprende a reconhecer a abstenção certa.

A ferramenta varre a grade de limiar por margem e reporta, para cada combinação, cobertura, precisão, erros e abstenções corretas. De 150 a 300 linhas rotuladas à mão já produzem um resultado utilizável.

Regeração das consultas SQL

python ferramentas/migrar_consultas.py <notebook_4.0.ipynb>

Extrai as consultas do notebook original preservando o texto exato, injeta os marcadores de watermark e aplica a lista de minimização de colunas. Para restaurar apenas uma coluna, o caminho direto é editar etapas/consultas.py; o migrador só é necessário para regerar tudo a partir da fonte original.

Mudança da pasta de dados

Documentada na Parte VI · VI.4. Tem interface na aba 4 · Ambiente e recusa-se a rodar com pipeline em execução.

Configuração do agente por API

python ferramentas/configurar_agente_rapido.py

Equivalente em linha de comando à aba 3 · IA / Modelos. Grava em config_ia_rapido.json, que nunca deve ser versionado.

VII.4 · O contrato com a API — nomes que não podem mudar

O pipeline e a API são projetos separados, com repositórios separados. O que os mantém compatíveis é um contrato de nomes: enquanto os nomes abaixo não mudarem, o pipeline pode ser reescrito por dentro sem que a API precise de qualquer ajuste.

Arquivos e separadores

Colunas

Como conferir o contrato depois de mexer no pipeline

1. Rode as três baterias de testeAba 6 · Testes. A bateria da API cobre a leitura de todas as colunas acima.
2. Suba a API e confira a coberturaAba 2 · Servidores, botão Cobertura da nota fixa de currículo. Cobertura zero depois de rodar --resumo-ia indica coluna renomeada ou arquivo em lugar diferente.
3. Abra uma tela de cada famíliaBusca, DFT e Simulador. O selo 🧮 nos três confirma que o contrato está de pé.

VIII.1 · Variáveis de ambiente

Todas podem ser definidas no sistema operacional, num .env, ou — o caminho recomendado — pela aba 4 · Ambiente do assistente, que as aplica apenas ao que ele executa.

Caminhos

Data Lake (etapa extracao)

Modelo vetorial e classificação

Inteligência artificial

Execução

Cache, teto de texto e exportação

As quatro variáveis que mais mudam o custo de uma execução. Nenhuma delas precisa ser mexida na rotina — todas têm padrão sensato.

VIII.2 · A linha de comando do pipeline

python pipeline.py [--etapas LISTA] [--forcar]
                   [--modo-extracao completa|incremental]
                   [--modo-juncao servidores|todos]
                   [--resumo-ia] [--curriculos-api]
                   [--sem-ia] [--teste] [--pre-voo]

VIII.3 · Endpoints da API

A API expõe 60 rotas. As de uso operacional estão na primeira tabela; as demais servem às telas e são chamadas pelo próprio front.

Operação e diagnóstico

Busca e dossiê

DFT, comparação e simulação

VIII.4 · Arquivos que o pipeline gera

VIII.5 · Glossário

• Assinatura — Conjunto de condições que descrevem uma execução de etapa. Igual à anterior, a etapa é pulada.
• Cabeça única — Competência que depende de uma só pessoa.
• Canonicalização — Normalizar o texto antes de calcular o hash, para que diferenças irrelevantes não gerem trabalho.
• Cobertura — Quantos servidores de uma equipe têm nota 4 ou 5 numa dimensão.
• Cosseno — Medida de similaridade que compara o formato de dois perfis, não a intensidade.
• DFT — Dimensionamento da Força de Trabalho — a descrição oficial do que cada unidade faz e do que exige.
• Embedding — Representação numérica do significado de um texto.
• EV.G — Escola Virtual de Governo, da Enap — a fonte do catálogo de cursos.
• Excedente («Além») — O quanto o candidato ultrapassa a exigência da vaga. Reportado à parte, nunca somado ao encaixe.
• Glosa — O verbete que define o que um rótulo da taxonomia abrange.
• Hash — Impressão digital de um texto.
• Índice de Encaixe — Quanto o candidato atende ao que a vaga exige, entre 0 e 100%.
• Manifesto — Registro do que cada etapa produziu e sob quais condições.
• Massa — Soma das notas de uma equipe numa dimensão.
• Multirrótulo — Decisão em que mais de um rótulo se aplica.
• Nível — Média de uma equipe numa dimensão.
• Régua única — O princípio de que a mesma pessoa e a mesma unidade têm o mesmo número em todas as telas.
• Reranker — Segundo modelo, mais preciso, que reordena os candidatos na zona cinzenta da classificação.
• SIAPE — Sistema Integrado de Administração de Pessoal — a origem dos dados funcionais.
• Taxonomia — A lista fechada de rótulos usada na classificação.
• UORG — Unidade organizacional.
• Watermark — Marca-d'água temporal: a maior data já extraída de uma tabela, usada para trazer só o que é novo.
• Zero-shot — Classificar sem treino específico naqueles rótulos, usando as glosas como referência.
• Zona cinzenta — Faixa de score em que a decisão de classificação é duvidosa e merece um segundo olhar.

VIII.6 · Relação de arquivos do código

Raiz do repositório

recruta_pipeline/

Recruta_html/

VIII.7 · O que mudou na versão 6

A versão 5 deste manual descrevia apenas o pipeline. A versão 6 cobre o sistema inteiro — assistente, telas e metodologia — e incorpora o resultado da auditoria de entregas concluída em setembro de 2026.

Revisão 6.1 — setembro de 2026

Além das correções abaixo, o manual ganhou a Parte 0 — O sistema em números: um painel medido nas bases em disco a cada geração, com a distribuição dos currículos por órgão, carreira e cargo, as três coberturas e o tamanho do texto que a IA lê. No site ele é um painel com gráficos; no Word, tabelas. Os painéis equivalentes do DFT e dos editais estão nas seções III.8 e III.9.

Uma semana de correções que têm um fio comum: falhas silenciosas. Nenhuma delas dava erro; todas apenas devolviam menos do que deviam.

Novo no manual

• Parte II — O Assistente: a aplicação de janela única, aba por aba.
• Parte IV — O Sistema Recruta: as cinco telas, botão a botão.
• Parte V — Metodologia: o método por trás de cada número, com os limites declarados.
• Parte VI — Operação, segurança e LGPD: o perímetro dos dados e as pendências de decisão.
• Duas etapas novas do pipeline: cursos (catálogo da EV.G) e pessoal (quantitativo e folha).

O que mudou no sistema

Cobertura de testes

882 verificações ao todo — 598 no pipeline, 40 na integração e 244 na API —, todas rodando em segundos, sem base real e sem chamar IA.

Este manual é gerado por código a partir de manual/, na raiz do repositório. Para atualizá-lo depois de mudar o sistema, edite o capítulo correspondente e rode:

python gerar_manual.py