Communitygithub.com

GiacomoSaccaggi/scomp_link

Kit ML ponta a ponta que automatiza todo o fluxo de trabalho — perfilhamento de dados, pré-processamento, engenharia de atributos, seleção de modelos, treinamento, validação, explicabilidade, monitoramento de deriva, verificações de justiça e relatórios HTML interativos. Inclui uma CLI completa para pipelines de ML sem código. Python 3.10+.

O que é scomp_link?

O scomp-link é um kit de ferramentas de Machine Learning abrangente que automatiza todo o ciclo de vida do ML, desde o perfilhamento inicial dos dados até a implantação e monitoramento em produção. Diferente de bibliotecas como sklearn, que exigem código para cada etapa, o scomp-link oferece uma CLI com 24 comandos que permitem executar tarefas complexas como engenharia de atributos, seleção automática de modelos, ajuste de hiperparâmetros (Optuna/Halving), validação, explicabilidade e detecção de anomalias sem escrever uma única linha de código. A ferramenta gera artefatos persistentes no formato `.scomp`, que encapsulam modelo, pré-processador, configuração e métricas, facilitando o versionamento e a reprodução. Além disso, produz relatórios HTML ricos com gráficos interativos (Plotly, Highcharts, RAWGraphs), suporta monitoramento de deriva e justiça, e inclui um servidor MCP para integração com agentes como Claude Desktop, Cursor e Codex. Ideal para engenheiros de ML que buscam produtividade e reprodutibilidade em pipelines de ponta a ponta.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add GiacomoSaccaggi/scomp_link

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

scomp-link — Kit ML Ponta a Ponta

Visão Geral

O scomp-link automatiza todo o fluxo de trabalho de ML: perfilhamento de dados → pré-processamento → engenharia de atributos → seleção de modelo → treinamento → validação → explicabilidade → monitoramento → implantação.

Use scomp-link em vez de sklearn puro quando precisar de:

  • ML sem código via CLI (24 comandos)
  • Seleção automática de modelo com base nas características dos dados
  • Artefatos persistentes (formato .scomp: modelo + pré-processador + configuração + métricas)
  • Relatórios HTML com gráficos interativos embutidos
  • Monitoramento de produção (deriva + anomalia + justiça)
  • Ajuste de hiperparâmetros com um comando (Optuna/Halving)

Use sklearn puro quando precisar de:

  • Arquiteturas de modelo personalizadas não disponíveis na fábrica
  • Controle refinado sobre cada etapa de pré-processamento
  • Fluxos de pesquisa que exigem total flexibilidade

Instalação

pip install scomp-link

Árvore de Decisão: Qual Comando Usar

Tenho dados e quero...
├─ Entendê-los rapidamente          → scomp-link describe --data arquivo.csv
├─ Relatório completo de qualidade (HTML) → scomp-link quality --data arquivo.csv --output relatorio.html
├─ Engenheirar atributos             → scomp-link engineer --data arquivo.csv --target y --interactions --log-transform
├─ Treinar um modelo
│  ├─ Regressão                      → scomp-link run --data arquivo.csv --target y --task regression
│  ├─ Classificação                  → scomp-link run --data arquivo.csv --target y --task classification
│  ├─ Classificação de texto         → scomp-link text --data arquivo.csv --text-col msg --target label
│  ├─ Agrupamento (clustering)       → scomp-link cluster --data arquivo.csv --n-clusters 5
│  └─ Pipeline completo via YAML     → scomp-link pipeline --config pipeline.yaml
├─ Ajustar hiperparâmetros           → scomp-link tune --data arquivo.csv --target y --task regression --method optuna
├─ Prever com modelo salvo           → scomp-link predict --artifact modelo.scomp --data novos.csv
├─ Validar em dados de teste         → scomp-link validate --artifact modelo.scomp --data teste.csv --target y
├─ Explicar decisões do modelo       → scomp-link explain --artifact modelo.scomp --data teste.csv
├─ Monitorar produção
│  ├─ Apenas deriva                  → scomp-link drift --reference treino.csv --current prod.csv
│  ├─ Monitoramento completo         → scomp-link monitor --reference treino.csv --current prod.csv --artifact modelo.scomp
│  └─ Detecção de anomalias          → scomp-link anomaly --data prod.csv --methods iforest,lof,tabnet,transformer
├─ Verificar justiça/viés            → scomp-link fairness --data predicoes.csv --target y_real --predicted y_pred --sensitive genero
├─ Prever séries temporais           → scomp-link forecast --data serie.csv --column valor --horizon 30
├─ Comparar modelos                  → scomp-link compare --artifacts v1.scomp v2.scomp
├─ Gerar relatório HTML              → scomp-link report --data arquivo.csv --output relatorio.html
├─ Servir como API REST              → scomp-link serve --artifact modelo.scomp --port 8080
├─ Exportar para ONNX/pickle         → scomp-link export --artifact modelo.scomp --format onnx
└─ Escalar um novo projeto           → scomp-link init meu_projeto

Fluxo de Trabalho Recomendado

Pipeline ML Padrão

# 1. Perfilar os dados
scomp-link describe --data treino.csv --format table

# 2. Verificar qualidade dos dados
scomp-link quality --data treino.csv --output relatorio_qualidade.html

# 3. Engenheirar atributos
scomp-link engineer --data treino.csv --target preco --interactions --log-transform --output engenheirados.csv

# 4. Ajustar hiperparâmetros
scomp-link tune --data engenheirados.csv --target preco --task regression --method optuna --n-trials 100 --save-artifact melhor_modelo.scomp

# 5. Validar em dados de teste retidos
scomp-link validate --artifact melhor_modelo.scomp --data teste.csv --target preco --report validacao.html

# 6. Explicar
scomp-link explain --artifact melhor_modelo.scomp --data teste.csv

# 7. Implantar
scomp-link serve --artifact melhor_modelo.scomp --port 8080

Pipeline YAML (tudo-em-um)

# pipeline.yaml
data: treino.csv
target: preco
task: regression
engineer:
  interactions: true
  log_transform: true
tune:
  method: optuna
  n_trials: 50
validate:
  test_data: teste.csv
  report: relatorio_validacao.html
save: models/modelo_preco.scomp
scomp-link pipeline --config pipeline.yaml

Visualização e Relatórios

O scomp-link possui três mecanismos de visualização. Consulte visualization-guide.md para detalhes completos.

Referência Rápida

MecanismoMelhor ParaSaídaInteratividade
PlotlyGráficos ML padrão (histogramas, dispersão, barras)HTML (interativo)Sim
RAWGraphsDiagramas de qualidade de publicação (sankey, treemap, chord)SVG (estático)Não
HighchartsSéries temporais (streamgraph, mapa de calor, gantt)HTML (interativo)Sim

Criando um Relatório HTML (API Python)

from scomp_link.utils.report_html import ScompLinkHTMLReport
from scomp_link.utils.plotly_utils import histogram, barchart, linechart, area_chart
from scomp_link.utils.highcharts import streamgraphs, calendar_heatmap, calendar_gantt
from scomp_link.utils.rawgraphs import treemap, sankey_diagram, sunburst

# 1. Inicializar
relatorio = ScompLinkHTMLReport(title='Meu Relatório de Análise')

# 2. Adicionar seções com conteúdo
relatorio.open_section("Visão Geral dos Dados")
relatorio.add_title("Estatísticas do Dataset")
relatorio.add_text("Análise de 10.000 registros de clientes.")
relatorio.add_dataframe(resumo_df, "Estatísticas Resumidas")
relatorio.close_section()

# 3. Adicionar gráficos
relatorio.open_section("Distribuições")
fig = histogram(df['idade'].values, "Distribuição de Idade")
relatorio.add_graph_to_report(fig, "Histograma de Idade")
relatorio.close_section()

# 4. Adicionar SVG RAWGraphs
relatorio.open_section("Visão Hierárquica")
svg = treemap(rotulos, pais, valores, "Receita por Categoria")
relatorio.add_rawgraphs_to_report(svg, "Treemap de Receita")
relatorio.close_section()

# 5. Adicionar Highcharts
relatorio.open_section("Tendências Temporais")
html_stream = streamgraphs("Tendência de Vendas", datas, series_dict, area=True)
relatorio.html_report += html_stream  # Anexo HTML direto para Highcharts
relatorio.close_section()

# 6. Salvar
relatorio.save_html('relatorio_analise.html')
relatorio.save_pdf('relatorio_analise.pdf')  # requer Playwright

Gráficos Disponíveis (31 RAWGraphs + 5 Plotly + 3 Highcharts)

Comparações: barchart, barchartmultiset, barchartstacked, piechart, radarchart, voronoidiagram Distribuições: beeswarm, boxplot, violinplot Séries Temporais: bumpchart, gantt_chart, horizongraph, linechart, slopechart, streamgraph Correlações: bubblechart, contour_plot, convex_hull, hexagonal_binning, matrixplot, parallelcoordinates Hierarquias: circlepacking, circular_dendrogram, dendrogram, sunburst, treemap, voronoi_treemap Redes: alluvial_diagram, arc_diagram, chord_diagram, sankey_diagram Plotly: histogram, multiple_histograms, barchart, linechart, area_chart Highcharts: streamgraphs, calendar_heatmap, calendar_gantt

Padrões de Encadeamento

Os comandos foram projetados para serem encadeados — a saída de um é a entrada do próximo:

describe → (entender colunas) → engineer → (engenheirados.csv) → tune → (modelo.scomp) → validate → (métricas)
                                                                                      ↓
                                                                               predict (novos dados)
                                                                                      ↓
                                                                               serve (API REST)

Padrões principais:

  • --save-artifact modelo.scomp → use com --artifact modelo.scomp em predict/validate/explain/export/serve
  • --output arquivo.csv → use como --data arquivo.csv no próximo comando
  • --report arquivo.html → saída HTML independente (visualizável no navegador)
  • --plot arquivo.html → saída de gráfico para forecast/drift/anomaly/cluster/compare

Erros Comuns e Correções

ErroCausaCorreção
ValueError: could not convert string to floatColunas categóricas em modelo numéricoUse a flag --engineer ou pré-processe as categóricas
FileNotFoundError: artifact not foundCaminho errado para o arquivo .scompVerifique se o caminho existe, use caminhos absolutos
ImportError: torch requiredDependências de NLP/deep learning ausentespip install scomp-link inclui todas as dependências
ArrowInvalid: 1-dimensional arrayDados de imagem/array no pré-processamentoCorrigido na v1.2.0 — atualize o scomp-link
No module named 'click'Dependência spaCy ausentepip install click (dependência transitiva)
WeasyPrint: cannot load gobjectBibliotecas de sistema ausentes para PDFUse save_pdf() (Playwright) em vez de WeasyPrint

Servidor MCP

O scomp-link inclui um servidor MCP para integração com agentes:

# Iniciar o servidor MCP (modo stdio para Claude Desktop / Kiro / Cursor)
scomp-link mcp

# Ou executar diretamente
python -m scomp_link.mcp_server

Consulte workflow-patterns.md para exemplos completos de fluxo de trabalho.

Habilidades Relacionadas