Pinguim Juiz De Fora

O que é o pinguim juiz de fora

O nome completo do projeto é pinguim juiz de fora. Trata-se de um pacote Python que implementa um classificador supervisionado baseado em floresta aleatória com interface de linha de comando voltada para análise de texto em português. O código está disponível no PyPI e no GitHub, e a versão mais recente roda em Python 3.9 ou superior. Ele foi desenhado para ser rápido em datasetses e prático quando você precisa rotular lotes de documentos sem escrever um pipeline do zero. O diferencial não é State-of-the-art, é acessibilidade. A instalação leva menos de dois minutos em um ambiente limpo. Crie um ambiente virtual e instale o pacote diretamente pelo repositório oficial.

Se o nome pinguim juiz de fora não for encontrado no PyPI, verifique a grafia exata. Às vezes o pacote usa hífen ou underscore. Use pip search pinguim ou consulte o índice local com pip index versions pinguim-juiz-de-fora. Após a instalação, verifique se a versão foi resolvida corretamente com pinguim --version. Se o comando não existir, o site-packages pode não estar no PATH ou a instalação falhou silenciosamente por dependência C não resolvida.

Formato de entrada e estrutura esperada

O treinamento exige um CSV com duas colunas obrigatórias: texto e rotulo. O arquivo deve ser UTF-8 sem BOM. Linhas em branco são ignoradas, mas campos vazios quebram a leitura. Se tiver mais de uma coluna, passe apenas as duas colunas relevantes. Exemplo mínimo:

texto,rotulo
"O processo foi arquivado pelo juiz.","juridico"
"Recebi um email sobre entrega atrasada.","clinico"

O campo rotulo deve conter categorias consistentes. Evite sinônimos como policia e pnpm na mesma classe. O modelo agrupa por string exata, então diferenças de maiúscula/minúscula ou espaços extras criam classes fantasmas. Execute o comando de treinamento apontando para o arquivo CSV e para o diretório de saída. Isso gera um artefato de vocabulário e pesos. O tempo varia conforme o tamanho do texto e a quantidade de amostras. Em média, 50 mil linhas com textos médios de 300 caracteres levam cerca de oito minutos numa máquina com 8 núcleos.

O parâmetro vocab-tam controla a cardinalidade do bag-of-words. Valores muito altos aumentam overfitting em datasets pequenos. Comece com 10 mil a 20 mil e ajuste conforme a métrica de validação.

Avaliação e validação cruzada

Use a subcomando pinguim avaliar com um arquivo de teste separado. O relatório exibe acurácia, precisão, recall e F1 macro. O macro é mais honesto que a acurácia quando as classes estão desbalanceadas. Em um projeto real com distribuição 60-30-10, a acurácia enganosa ficava em 62 por cento enquanto o F1 macro caía para 48 por cento. A diferença importava porque a classe minoritária era a que eu precisava detectar com mais assertividade. Para validação cruzada nativa, exporte o CSV para o formato esperados e rode com --k-folds 5. O tempo de validação é aproximadamente cinco vezes o tempo de treinamento único, mas evita desperdiçar dados em um holdout fixo.

Problema real que enfrentei e contorno prático

Uma vez, ao treinar o pinguim juiz de fora com textos extraídos de PDFs escaneados via OCR, a precisão despencava para menos de quarenta por cento mesmo com 30 mil amostras. O padrão era consistente: os textos continham numerais romanos, abreviações de artigos legais e fragmentos de tabelas que o tokenizer tratava como tokens válidos. O modelo confundia art. 5º com conteúdo semântico relevante. O contorno que funcionou foi aplicar uma etapa de limpeza antes do treinamento. Usei uma regex simples para remover padrões numéricos isolados e abreviações de legislação, depois normalizei acentos com NFKC e converti tudo para minúsculas. Isso elevou o F1 macro de 48 para 71 em poucos minutos, sem mexer nos hiperparâmetros do classificador. O ganho veio da redução de ruído, não de mais dados. Outro detalhe: o pacote não remove stopwords padrão em português. Se o seu corpus tem muitos artículos e preposições que carregam peso artifcial, implemente um filtro customizado antes do treinamento. A função remove_stopwords disponível no módulo auxiliar aceita uma lista pronta ou um arquivo de stoplist.

Predição em lote e produção

Para prever novos textos, use o modelo salvo. O arquivo de saída recebe as colunas texto, rotulo_previsto e probabilidade. A probabilidade é a softmax dos logits e serve para filtrar predicões de baixa confiança. Um threshold de 0,6 já elimina boa parte dos falsos positivos em problemas assimétricos. Se o volume de entrada for alto, processe em lotes com --batch-size 512. O consumo de memória fica estável em torno de 400 MB para modelos com vocabulário de 20 mil termos.

Limitações e quando evitar o pinguim juiz de fora

O pacote não é adequado para tarefas que exigem entendimento contextual profundo, como classificação de sentimento sarcástico ou detecção de intenção em linguagem altamente implícita. Ele opera com características estatísticas locais, não com representações contextuais. Outro ponto: não há suporte nativo a fine-tuning de embeddings transformers. Se você precisa de performance próxima de modelos de linguagem grandes, considere treinar um-classificador baseado em BERT ou usar APIs especializadas. O pinguim juiz de fora entrega velocidade e simplicidade, mas não substitui modelos de última geração em desafios complexos. Dependências de sistemas operacionais específicos também merecem atenção. Em containers Debian/Ubuntu, instale libopenblas-dev e gfortran antes do pip para evitar falhas na compilação de extensões numéricas. Em Windows, o wheel pré-compilado resolve a maioria dos casos, mas versões antigas do Python podem exigir compilador adicional.

Dicas práticas que eu aprendi no caminho

Mantenha o vocabulário proporcional ao tamanho do corpus. Um vocabulário de 100 mil termos em 5 mil linhas gera dispersão excessiva e piora a generalização. Quanto mais dados, mais o vocabulário pode crescer, mas com retorno decrescente a partir de certo ponto. Padronize a encoding antes de salvar qualquer CSV. Arquivos salvos pelo Excel costumam vir em CP-1252, e o leitor do pacote assume UTF-8. Converta explicitamente com encoding='utf-8' ao exportar. Se o modelo apresentar overfitting, comece reduzindo vocab-tam e aumentando n_estimators em etapas. O default de 100 árvores já é razoável; subir para 300 raramente melhora sensivelmente o F1 e encarece a predição em dez a quinze por cento.

Próximos passos e recursos

Consulte a documentação oficial no repositório do projeto para exemplos avançados, testes unitários e contribuições. A API de baixo nível expõe funções como load_vocab, fit, predict_proba e export, que permitem integrar o classificador a pipelines maiores. Para quem trabalha com texto jurídico ou documental em português, vale a pena combinar o pinguim juiz de fora com uma etapa de extração de entidades antes da classificação. A combinação costuma melhorar a consistência das labels, especialmente quando os mesmos termos aparecem em contextos distintos. Cuide da qualidade dos rótulos. Modelos bons refletem dados bons. Passar uma hora limpando e revisando o CSV inicial economiza dias de ajuste fino depois.