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
| Mecanismo | Melhor Para | Saída | Interatividade |
|---|---|---|---|
| Plotly | Gráficos ML padrão (histogramas, dispersão, barras) | HTML (interativo) | Sim |
| RAWGraphs | Diagramas de qualidade de publicação (sankey, treemap, chord) | SVG (estático) | Não |
| Highcharts | Sé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.scompem predict/validate/explain/export/serve--output arquivo.csv→ use como--data arquivo.csvno 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
| Erro | Causa | Correção |
|---|---|---|
ValueError: could not convert string to float | Colunas categóricas em modelo numérico | Use a flag --engineer ou pré-processe as categóricas |
FileNotFoundError: artifact not found | Caminho errado para o arquivo .scomp | Verifique se o caminho existe, use caminhos absolutos |
ImportError: torch required | Dependências de NLP/deep learning ausentes | pip install scomp-link inclui todas as dependências |
ArrowInvalid: 1-dimensional array | Dados de imagem/array no pré-processamento | Corrigido na v1.2.0 — atualize o scomp-link |
No module named 'click' | Dependência spaCy ausente | pip install click (dependência transitiva) |
WeasyPrint: cannot load gobject | Bibliotecas de sistema ausentes para PDF | Use 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.