¿Qué hace scomp-link — Toolkit ML de Extremo a Extremo?
Descripción General
scomp-link automatiza el flujo de trabajo completo de ML: perfilado de datos → preprocesamiento → ingeniería de características → selección de modelos → entrenamiento → validación → explicabilidad → monitoreo → despliegue.
Usa scomp-link en lugar de sklearn crudo cuando necesites:
- ML sin código mediante CLI (24 comandos)
- Selección automatizada de modelos basada en características de los datos
- Artefactos persistentes (formato
.scomp: modelo + preprocesador + configuración + métricas) - Informes HTML con gráficos interactivos integrados
- Monitoreo en producción (deriva + anomalías + equidad)
- Ajuste de hiperparámetros con un solo comando (Optuna/Halving)
Usa sklearn crudo cuando necesites:
- Arquitecturas de modelos personalizadas no incluidas en la fábrica
- Control detallado sobre cada paso de preprocesamiento
- Flujos de trabajo de investigación que requieren flexibilidad total
Instalación
pip install scomp-link
Árbol de Decisiones: Qué Comando Usar
Tengo datos y quiero...
├─ Entenderlos rápidamente → scomp-link describe --data archivo.csv
├─ Un informe de calidad completo (HTML) → scomp-link quality --data archivo.csv --output reporte.html
├─ Ingeniería de características → scomp-link engineer --data archivo.csv --target y --interactions --log-transform
├─ Entrenar un modelo
│ ├─ Regresión → scomp-link run --data archivo.csv --target y --task regression
│ ├─ Clasificación → scomp-link run --data archivo.csv --target y --task classification
│ ├─ Clasificación de texto → scomp-link text --data archivo.csv --text-col msg --target label
│ ├─ Clustering → scomp-link cluster --data archivo.csv --n-clusters 5
│ └─ Pipeline completo desde YAML → scomp-link pipeline --config pipeline.yaml
├─ Ajustar hiperparámetros → scomp-link tune --data archivo.csv --target y --task regression --method optuna
├─ Predecir con modelo guardado → scomp-link predict --artifact modelo.scomp --data nuevos.csv
├─ Validar con datos de prueba → scomp-link validate --artifact modelo.scomp --data test.csv --target y
├─ Explicar decisiones del modelo → scomp-link explain --artifact modelo.scomp --data test.csv
├─ Monitorear producción
│ ├─ Solo deriva → scomp-link drift --reference train.csv --current prod.csv
│ ├─ Monitoreo completo → scomp-link monitor --reference train.csv --current prod.csv --artifact modelo.scomp
│ └─ Detección de anomalías → scomp-link anomaly --data prod.csv --methods iforest,lof,tabnet,transformer
├─ Verificar equidad/sesgo → scomp-link fairness --data preds.csv --target y_true --predicted y_pred --sensitive genero
├─ Pronosticar series temporales → scomp-link forecast --data serie.csv --column valor --horizon 30
├─ Comparar modelos → scomp-link compare --artifacts v1.scomp v2.scomp
├─ Generar informe HTML → scomp-link report --data archivo.csv --output reporte.html
├─ Servir como API REST → scomp-link serve --artifact modelo.scomp --port 8080
├─ Exportar a ONNX/pickle → scomp-link export --artifact modelo.scomp --format onnx
└─ Crear un nuevo proyecto → scomp-link init mi_proyecto
Flujo de Trabajo Recomendado
Pipeline ML Estándar
# 1. Perfilar los datos
scomp-link describe --data train.csv --format table
# 2. Verificar calidad de datos
scomp-link quality --data train.csv --output quality_report.html
# 3. Ingeniería de características
scomp-link engineer --data train.csv --target precio --interactions --log-transform --output engineered.csv
# 4. Ajustar hiperparámetros
scomp-link tune --data engineered.csv --target precio --task regression --method optuna --n-trials 100 --save-artifact best_model.scomp
# 5. Validar con datos de prueba reservados
scomp-link validate --artifact best_model.scomp --data test.csv --target precio --report validation.html
# 6. Explicar
scomp-link explain --artifact best_model.scomp --data test.csv
# 7. Desplegar
scomp-link serve --artifact best_model.scomp --port 8080
Pipeline YAML (todo en uno)
# pipeline.yaml
data: train.csv
target: precio
task: regression
engineer:
interactions: true
log_transform: true
tune:
method: optuna
n_trials: 50
validate:
test_data: test.csv
report: validation_report.html
save: models/precio_model.scomp
scomp-link pipeline --config pipeline.yaml
Visualización e Informes
scomp-link tiene tres motores de visualización. Consulta guía-de-visualización.md para más detalles.
Referencia Rápida
| Motor | Mejor Para | Salida | Interactividad |
|---|---|---|---|
| Plotly | Gráficos ML estándar (histogramas, dispersión, barras) | HTML (interactivo) | Sí |
| RAWGraphs | Diagramas de calidad de publicación (sankey, treemap, chord) | SVG (estático) | No |
| Highcharts | Series temporales (streamgraph, mapa de calor, gantt) | HTML (interactivo) | Sí |
Crear un Informe HTML (API de 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
report = ScompLinkHTMLReport(title='Mi Informe de Análisis')
# 2. Agregar secciones con contenido
report.open_section("Resumen de Datos")
report.add_title("Estadísticas del Conjunto de Datos")
report.add_text("Análisis de 10,000 registros de clientes.")
report.add_dataframe(summary_df, "Estadísticas Resumidas")
report.close_section()
# 3. Agregar gráficos
report.open_section("Distribuciones")
fig = histogram(df['edad'].values, "Distribución de Edad")
report.add_graph_to_report(fig, "Histograma de Edad")
report.close_section()
# 4. Agregar SVG de RAWGraphs
report.open_section("Vista Jerárquica")
svg = treemap(labels, parents, values, "Ingresos por Categoría")
report.add_rawgraphs_to_report(svg, "Treemap de Ingresos")
report.close_section()
# 5. Agregar Highcharts
report.open_section("Tendencias Temporales")
html_stream = streamgraphs("Tendencia de Ventas", fechas, series_dict, area=True)
report.html_report += html_stream # Anexar HTML directo para Highcharts
report.close_section()
# 6. Guardar
report.save_html('informe_analisis.html')
report.save_pdf('informe_analisis.pdf') # requiere Playwright
Gráficos Disponibles (31 RAWGraphs + 5 Plotly + 3 Highcharts)
Comparaciones: barchart, barchartmultiset, barchartstacked, piechart, radarchart, voronoidiagram Distribuciones: beeswarm, boxplot, violinplot Series Temporales: bumpchart, gantt_chart, horizongraph, linechart, slopechart, streamgraph Correlaciones: bubblechart, contour_plot, convex_hull, hexagonal_binning, matrixplot, parallelcoordinates Jerarquías: 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
Patrones de Encadenamiento
Los comandos están diseñados para encadenarse: la salida de uno es la entrada del siguiente:
describe → (entender columnas) → engineer → (engineered.csv) → tune → (modelo.scomp) → validate → (métricas)
↓
predict (nuevos datos)
↓
serve (API REST)
Patrones clave:
--save-artifact modelo.scomp→ usar con--artifact modelo.scompen predict/validate/explain/export/serve--output archivo.csv→ usar como--data archivo.csven el siguiente comando--report archivo.html→ salida HTML independiente (visible en el navegador)--plot archivo.html→ salida de gráfico para forecast/drift/anomaly/cluster/compare
Errores Comunes y Soluciones
| Error | Causa | Solución |
|---|---|---|
ValueError: could not convert string to float | Columnas categóricas en modelo numérico | Usar la bandera --engineer o preprocesar categóricas |
FileNotFoundError: artifact not found | Ruta incorrecta al archivo .scomp | Verificar que la ruta existe, usar rutas absolutas |
ImportError: torch required | Dependencias de NLP/deep learning faltantes | pip install scomp-link incluye todas las dependencias |
ArrowInvalid: 1-dimensional array | Datos de imagen/array en preprocesamiento | Corregido en v1.2.0 — actualizar scomp-link |
No module named 'click' | Dependencia faltante de spaCy | pip install click (dependencia transitiva) |
WeasyPrint: cannot load gobject | Bibliotecas del sistema faltantes para PDF | Usar save_pdf() (Playwright) en lugar de WeasyPrint |
Servidor MCP
scomp-link incluye un servidor MCP para integración con agentes:
# Iniciar el servidor MCP (modo stdio para Claude Desktop / Kiro / Cursor)
scomp-link mcp
# O ejecutar directamente
python -m scomp_link.mcp_server
Consulta patrones-de-flujo-de-trabajo.md para ejemplos completos de flujo de trabajo.