FrankS-IntelLab/agentic-kaggle-skill

Skill de Kaggle Agentic

Loop de Operação

Trate cada competição como um problema de validação primeiro e um problema de modelagem depois. A plataforma alvo padrão é o Kaggle, portanto, prefira notebooks/scripts nativos do Kaggle, datasets, artefatos de modelo, submissões de competição e recibos de pontuação. Para competições de código, assuma que o notebook/kernel final será reexecutado pelo Kaggle contra dados ocultos, a menos que a documentação da competição prove o contrário.

1. Leia a página da competição, classifique o modo de submissão como submissão clássica de arquivo ou pontuação de código/notebook, depois inspecione as regras, termos de uso de dados, política de compartilhamento, dicionário de dados, métrica, formato de submissão, dicas de construção treino/teste e avisos de vazamento.
2. Se ferramentas de inteligência de competições ao vivo estiverem disponíveis, inspecione as principais soluções de notebooks públicos abertos e atividades relevantes de discussão antes de grandes escolhas de arquitetura; trate-os como pistas, não como autoridade.
3. Identifique o tipo de tarefa: binária, multiclasse, multirrótulo, regressão, ranking, imagem, segmentação, texto, série temporal, entidades agrupadas ou um híbrido.
4. Projete as dobras antes da engenharia de features ou modelagem. Prefira uma coluna de dobra salva nos dados de treino para que cada experimento use a mesma superfície de comparação.
5. Construa a linha de base mais simples e correta da métrica e produza previsões out-of-fold (OOF) mais uma submissão válida.
6. Planeje proativamente uma arquitetura mais forte assim que a linha de base for confiável: famílias diversificadas de modelos, produtores de features/embeddings, estágios de aumento/pseudo-rótulo/destilação, calibração/pós-processamento e um ensemble ou stacker.
7. Itere com portões de validação: teste uma mudança significativa de cada vez quando possível, mas lance vários notebooks produtores independentes em paralelo quando eles criarem artefatos diversos que podem ser comparados por pontuação OOF ou diversidade do ensemble.
8. Descarregue treinamento pesado, inferência, geração de embeddings, experimentos de imagem/texto ou tarefas arriscadas de memória para notebooks/scripts do Kaggle quando o computador local puder ficar sem memória ou demorar muito.
9. Para arquiteturas sofisticadas, divida o trabalho em um pequeno pipeline do Kaggle: execute vários notebooks/scripts produtores independentes primeiro, salve cada saída útil do produtor como um dataset privado do Kaggle, depois execute um notebook/script consumidor que anexa esses datasets e cria as saídas finais de OOF/teste/submissão. Quando um produtor treina um modelo, seu checkpoint, tokenizer/config, metadados das dobras, previsões OOF/teste e manifesto devem ser exportados como um dataset do Kaggle; notebooks downstream carregam o modelo de /kaggle/input/....
10. Submeta o artefato final de produção de submissão para o Kaggle para pontuação e recupere o status/pontuação da submissão resultante.
11. Se o Kaggle retornar um erro de competição de código ou falha vaga de pontuação, entre no loop de depuração: recupere os logs disponíveis, classifique o modo provável de falha, corrija defensivamente, reexecute o kernel final, reenvie e repita até ser pontuado ou bloqueado concretamente.
12. Acompanhe o CV local, o status de execução remota no Kaggle, a pontuação da submissão Kaggle, o LB público, as notas de risco privado, a semente, a versão do código, a versão dos dados e os caminhos dos artefatos para cada execução.
13. Faça ensemble apenas com previsões OOF geradas sem vazamento dentro da dobra.

Mapa de Recursos

• Leia references/method-map.md para o mapa de fluxo de trabalho neutro por trás da skill.
• Leia references/information-sharing-policy.md antes de publicar código de competição, notebooks, datasets, modelos, artefatos ou relatórios fora da equipe ativa ou do espaço de trabalho.
• Leia references/competition-intel.md quando um slug, URL, título, contexto do leaderboard público, soluções abertas ou atividade de discussão de uma competição Kaggle puderem informar a abordagem.
• Leia references/cross-validation-and-metrics.md ao escolher dobras, métricas, limiares ou verificações de vazamento.
• Leia references/tabular-workflow.md para variáveis categóricas, engenharia de features, seleção e ajuste de hiperparâmetros.
• Leia references/image-text-workflow.md para abordagens de competição de imagem, segmentação e NLP.
• Leia references/kaggle-code-competition-pipeline.md quando o alvo for uma competição de código Kaggle, reexecução oculta, fluxo de pontuação de notebook final ou transferência de artefatos de modelo entre notebooks produtor e consumidor.
• Leia references/advanced-notebook-architecture.md quando uma solução mais forte puder exigir múltiplas famílias de modelos, produtores de features/embedding em estágios, pseudo-rótulo, destilação, pós-processamento, blending, stacking ou notebooks GPU paralelos no Kaggle.
• Leia references/kaggle-offload.md quando as execuções locais forem pesadas, a GPU for útil, o acesso a dados do Kaggle for necessário ou os resultados de notebooks remotos precisarem ser coletados.
• Leia references/kaggle-pipeline-datasets.md ao usar vários notebooks Kaggle, datasets intermediários, fontes de saída de notebook ou kagglehub.
• Leia references/submission-endgame.md antes de parar o trabalho; esta skill não está concluída até que a pontuação do Kaggle tenha sido tentada e o resultado tenha sido coletado ou um bloqueador concreto esteja documentado.
• Leia references/code-competition-debugging.md quando uma submissão de competição de código Kaggle falhar, expirar, estourar a memória, não produzir pontuação ou relatar um erro vago de execução/pontuação oculta.
• Leia references/ensembling-and-reproducibility.md para layout do projeto, artefatos OOF, stacking, blending e repetibilidade.
• Leia references/research/ ou examples/ apenas quando o usuário pedir estudos de caso históricos, padrões da era Hermes ou lições concretas de competições deste repositório.
• Execute scripts/scaffold_competition.py para criar um espaço de trabalho de competição.
• Execute scripts/make_folds.py para adicionar uma coluna de dobra a um CSV de treino.
• Execute scripts/prepare_kaggle_kernel.py para criar uma pasta de kernel Kaggle com metadados e logs de experimento recuperáveis.
• Execute scripts/prepare_kaggle_dataset.py para criar metadados e comandos para datasets de artefatos intermediários versionados.

Procedimento Padrão Kaggle

Comece com a métrica e a validação:

• Reproduza a métrica da competição localmente, incluindo clipping, transformações, modo de média, limiares e pesos de amostra.
• Verifique se a competição permite código público, dados externos, pesos pré-treinados, artefatos gerados e repositórios públicos antes de compartilhar qualquer coisa fora da equipe.
• Classifique o caminho de submissão Kaggle cedo. Se for uma competição de código ou fluxo de trabalho pontuado por notebook, projete o notebook consumidor final como o artefato de pontuação desde o início.
• Use ferramentas MCP kaggle-competition-intel quando disponíveis: top_open_solutions para notebooks ordenados por pontuação e mais votados recentemente, e competition_discussions para tópicos de discussão mais votados e ativos recentemente antes de escolher linhas de base caras.
• Escolha dobras para corresponder à distribuição oculta do teste. Use estratificação para classificação, estratificação em intervalos para regressão, divisões de grupo para entidades repetidas, divisões cientes de tempo para dados temporais e divisões cientes de multirrótulo quando a co-ocorrência de rótulos for importante.
• Salve previsões OOF para cada modelo. Arquivos OOF são a moeda para análise de erros, ajuste de limiares, blending e stacking.
• Compare a pontuação média da dobra e a variância das dobras, não apenas a melhor dobra.
• Trate um salto no LB público que discorda do CV como uma questão de validação antes de tratá-lo como uma vitória de modelagem.

Em seguida, construa as linhas de base nesta ordem:

1. Linha de base apenas de métrica ou constante para verificar a pontuação e o formato de submissão.
2. Linha de base clássica rápida: LightGBM/CatBoost/XGBoost para dados tabulares, TF-IDF mais modelo linear para texto, backbone pré-treinado para imagens.
3. Linha de base forte com dobras estáveis, artefatos limpos e previsões OOF.
4. Experimentos de features/modelos com logs de execução e uma métrica principal.
5. Ensemble ou stacking depois que vários modelos diversos e validados individualmente existirem.

Não espere que o usuário peça explicitamente sofisticação quando a competição a justificar. Após uma linha de base estável, proponha e execute uma arquitetura em estágios mais forte se soluções públicas, inteligência de discussão, modalidade de dados, pressão da métrica ou platô do CV sugerirem que um único notebook/modelo terá desempenho inferior. Mantenha a arquitetura controlada por evidências OOF, manifestos de artefatos e pontuação final do Kaggle.

Quando uma execução provavelmente exceder a RAM/VRAM local, exigir uma GPU/TPU ou precisar de montagens de dados exclusivas do Kaggle, prepare uma execução de kernel Kaggle em vez de forçá-la localmente. A execução remota deve emitir experiment_log.json, metrics.jsonl e um manifesto de artefato para que os resultados possam ser recuperados e interpretados após kaggle kernels output.

Quando a solução tiver vários estágios pesados, mantenha o gráfico remoto raso e inspecionável:

• Use menos de cinco notebooks/scripts produtores independentes por onda.
• Dê a cada produtor uma única responsabilidade, como geração de features, extração de embeddings, treinamento de dobras, treinamento de checkpoint, destilação de modelo ou inferência.
• Para competições de código, prefira notebooks produtores que treinam modelos/checkpoints e os exportam como datasets privados do Kaggle; o consumidor final deve anexar esses datasets, carregar modelos de /kaggle/input/... e realizar inferência segura para teste oculto.
• Salve as saídas dos notebooks produtores como datasets privados versionados do Kaggle para reutilização durável e como entradas estáveis para notebooks downstream; use kernel_sources direto apenas para cadeias curtas onde durabilidade/versionamento não são necessários.
• Execute um notebook/script consumidor final que anexe os datasets produzidos, leia seus artefatos, escreva as previsões OOF finais, previsões de teste, relatório de blend/stack e submissão, então envie esse artefato/kernel final para o Kaggle para pontuação.
• Use kagglehub dentro do Python quando for mais conveniente baixar datasets, arquivos de competição, saídas de notebook ou fazer upload de versões de dataset programaticamente.

Definição de Concluído

Não pare em um plano, esqueleto, modelo treinado, execução de notebook, saída baixada ou pontuação de validação local. Continue até que uma destas condições seja verdadeira:

• Uma submissão de competição foi enviada ao Kaggle, o Kaggle a processou, e a pontuação pública ou o status da submissão foi recuperado e registrado.
• Um notebook/kernel final de competição de código consumiu todos os artefatos produtores necessários, foi submetido com sua referência de kernel/versão, e o status/pontuação da submissão resultante foi recuperado e registrado.
• Um bloqueador externo concreto impede a pontuação: credenciais Kaggle ausentes, regras não aceitas, cota esgotada após tentativas de repetição, competição encerrada, pontuação desabilitada, ação manual necessária apenas na interface, versão de kernel indisponível ou falha de serviço do Kaggle. Registre o bloqueador exato e o próximo comando/ação necessária.

Escolhas de Validação

Use este mapeamento rápido:

• Classificação balanceada: StratifiedKFold.
• Classificação desbalanceada: dobras estratificadas mais ajuste de limiar sensível à métrica ou pesos de classe.
• Regressão: KFold para alvos comuns, dobras estratificadas em intervalos para alvos assimétricos ou multimodais.
• Mesmo usuário, paciente, produto, sessão, documento ou fonte de imagem aparece várias vezes: GroupKFold ou divisão de grupo estratificada.
• Eventos ordenados ou previsão: divisão temporal, validação com janela expansível ou divisão de período específico da competição.
• Imagens do mesmo sujeito ou cena: agrupe por sujeito/cena antes da augmentação.
• Texto com fontes, autores, perguntas, produtos ou prompts duplicados: agrupe por chave de fonte.
• Dados pequenos: dobras repetidas ou mais dobras, mas mantenha a disciplina de seleção final do modelo estrita.

Prioridades de Modelagem

• Para competições tabulares, prefira boosting de árvores primeiro, a menos que os dados sejam principalmente texto esparso ou interações categóricas de alta cardinalidade. Adicione CatBoost quando colunas categóricas forem centrais.
• Para modelos lineares e redes neurais, dimensione features numéricas e codifique categóricas com cuidado.
• Para modelos de árvore, comece com codificações de rótulo/contagem/frequência e valores ausentes sensatos; dimensionar geralmente é desnecessário.
• Para codificação de alvo, sempre calcule as codificações out-of-fold, com suavização e sem visibilidade do alvo da linha de validação.
• Para tarefas de imagem, acerte o dataset, transformações, rótulos, máscaras e métrica antes de mudar a arquitetura.
• Para tarefas de texto, mantenha uma linha de base TF-IDF mesmo ao usar transformers; é rápida, interpretável e geralmente se combina bem.
• Para busca de hiperparâmetros, ajuste apenas depois que as dobras e linhas de base forem confiáveis. Busque taxa de aprendizado, profundidade/folhas, regularização, amostragem e número de estimadores com parada antecipada.

Higiene da Competição

• Mantenha os dados brutos somente leitura.
• Mantenha dados de competição, datasets privados, checkpoints de modelo, saídas baixadas, submissões, credenciais e artefatos derivados de dados fora de repositórios Git públicos, a menos que as regras da competição e as licenças dos artefatos permitam explicitamente a redistribuição pública.
• Coloque todos os valores que mudam experimentos em configuração ou argumentos de linha de comando.
• Semeie Python, NumPy, framework e bibliotecas de modelo quando possível.
• Salve arquivos de modelo, previsões OOF, previsões de teste, pontuações de dobras, listas de features e arquivos de submissão com IDs de execução.
• Para trabalhos descarregados no Kaggle, escreva logs e artefatos recuperáveis no diretório de trabalho do notebook, incluindo ID de execução, commit git, configuração, dobra, métrica, hardware, tempo decorrido, notas de OOM e caminhos de arquivos de saída.
• Para pipelines multi-notebook, mantenha um manifesto de pipeline com referências de kernels produtores, referências de datasets produzidos, versões de datasets, esquemas de artefatos, métricas e o ID de execução do consumidor final.
• Mantenha datasets produtores, kernels e artefatos de modelo privados por padrão. Torne-os públicos apenas após verificar as regras da competição alvo, licença de dados, IP de terceiros e intenção do usuário.
• Registre a mensagem de submissão, o comando de submissão ou kernel/versão, o timestamp da submissão no Kaggle, o status, a pontuação pública se disponível e qualquer erro retornado pelo Kaggle.
• Para falhas vagas de competição de código, registre o status observado, os logs disponíveis, a classe suspeita de falha, o patch tentado e o próximo comando de repetição.
• Nunca treine um stacker em previsões base da amostra.
• Nunca selecione features, codificadores de alvo, scalers, limiares ou augmentações usando alvos de validação fora do limite da dobra.
• Prefira scripts para treinamento repetível e notebooks para exploração e gráficos.

Comandos Úteis

Cria

…

[truncado para tradução]