内容
# scomp-link：适用于Python项目的Astromech机械臂
## 代码力量与你同在
[](https://github.com/GiacomoSaccaggi/scomp_link/actions/workflows/ci.yml)
[](https://codecov.io/gh/GiacomoSaccaggi/scomp_link)
[](https://pypi.org/project/scomp-link/)
[](https://pypi.org/project/scomp-link/)
[](https://pypi.org/project/scomp-link/)
[](https://github.com/GiacomoSaccaggi/scomp_link/blob/main/LICENSE)
[](https://github.com/astral-sh/ruff)
[](https://peps.python.org/pep-0561/)
<!-- mcp-name: io.github.giacomosaccaggi/scomp-link -->
---
## 概述
**scomp-link** 是一个端到端的机器学习工具包，自动完成整个ML工作流程 — 从数据剖析和预处理到模型选择、训练、验证、可解释性、监控和部署。
它包括一个**全功能的CLI**，用于零代码ML工作流程和一个Python API，用于编程使用。
---
## 安装
```bash
pip install scomp-link
```
需要Python 3.10+。导入几乎是瞬间的 (~6ms)，得益于延迟加载 — 只有需要时才会加载重依赖。Python 3.14实验性支持（TensorFlow在3.14上尚不可用）。
---
## 主要功能
| 类别 | 功能 |
|----------|----------|
| **管道** | 自动模型选择、训练、验证、HTML报告 |
| **CLI** | 24个命令 — `run`、`predict`、`text`、`cluster`、`tune`、`validate`、`explain`、`engineer`、`forecast`、`anomaly`、`drift`、`fairness`、`quality`、`describe`、`report`、`compare`、`monitor`、`serve`、`export`、`pipeline`、`info`、`init`、`list-models`、`check-deps` |
| **预处理** | 数据清理、特征工程（交互、日志、日期、目标编码、分组）、数据质量分析 |
| **模型** | 回归、分类、聚类、时间序列预测、异常检测、文本（BERT对比学习）、图像（CNN） |
| **调优** | Optuna（贝叶斯）、Halving 网格搜索、早期停止交叉验证 |
| **验证** | K-Fold、LOOCV、Bootstrap、集成（投票/堆叠） |
| **可解释性** | SHAP值、LIME解释 |
| **监控** | 数据漂移检测（PSI + KS测试） |
| **公平性** | 人口统计公平性、差异影响（4/5规则）、均衡奇偶性 |
| **持久性** | 自定义 `.scomp` 格式（模型 + 预处理器 + 配置 + 指标 + 示例数据） |
| **可视化** | 31个RAWGraphs SVG图表、Plotly交互式图表、高级图表、集中式颜色系统 |
| **报告** | 交互式HTML报告，嵌入图表、数据质量报告 |
---
## CLI快速入门
```bash
# 创建新项目
scomp-link init my_project
# 快速数据集剖析
scomp-link describe --data data.csv --format table
# 完整数据质量报告
scomp-link quality --data data.csv --output report.html
# 特征工程
scomp-link engineer --data data.csv --target y --interactions --log-transform --output features.csv
# 训练模型
scomp-link run --data features.csv --target y --task regression --save-artifact model.scomp
# 训练文本数据
scomp-link text --data tickets.csv --text-col message --target category --method tfidf
# 聚类
scomp-link cluster --data customers.csv --n-clusters 5 --plot clusters.html
# 超参数调优
scomp-link tune --data train.csv --target y --task regression --method optuna --n-trials 100
# 预测
scomp-link predict --artifact model.scomp --data new_data.csv --output predictions.csv
# 验证测试数据
scomp-link validate --artifact model.scomp --data test.csv --target y --report report.html
# 解释
scomp-link explain --artifact model.scomp --data test.csv
# 检测漂移
scomp-link drift --reference train.csv --current production.csv --plot drift.html
# 生产环境监控（漂移 + 质量 + 性能）
scomp-link monitor --reference train.csv --current prod.csv --artifact model.scomp --target y
# 时间序列预测
scomp-link forecast --data series.csv --column value --horizon 30 --plot forecast.html
# 异常检测
scomp-link anomaly --data data.csv --methods iforest,lof,tabnet,transformer
# 公平性检查
scomp-link fairness --data preds.csv --target y_true --predicted y_pred --sensitive gender
# 比较模型
scomp-link compare --artifacts v1.scomp v2.scomp --plot comparison.html
# 从YAML配置运行完整管道
scomp-link pipeline --config pipeline.yaml
# 以REST API形式提供模型服务
scomp-link serve --artifact model.scomp --port 8080
# 将模型导出为标准格式
scomp-link export --artifact model.scomp --format onnx
# 生成报告
scomp-link report --data data.csv --output eda_report.html
scomp-link report --artifact model.scomp --data test.csv --output model_report.html
# 实用工具
scomp-link list-models
scomp-link check-deps
```
---
## Python API快速入门
```python
from scomp_link import ScompLinkPipeline, ScompArtifact, set_verbosity
import pandas as pd
# 控制输出
set_verbosity("info") # "silent" | "warning" | "info" | "debug"
# 构建管道
pipe = ScompLinkPipeline("My Project")
pipe.set_objectives(["Minimize RMSE"])
pipe.import_and_clean_data(df)
pipe.select_variables(target_col='target')
pipe.choose_model("numerical_prediction")
results = pipe.run_pipeline(task_type="regression")
# 保存为工件
artifact = ScompArtifact()
artifact.set_model(pipe.model)
artifact.set_config(task_type='regression', target_col='target')
artifact.set_metrics(results['metrics'])
artifact.save('model.scomp')
# 加载和预测
loaded = ScompArtifact.load('model.scomp')
predictions = loaded.predict(new_data)
```
---
## 特征工程
```python
from scomp_link import FeatureEngineer
fe = FeatureEngineer(
interactions=True, # 多项式交互
log_transform=True, # 对偏态特征取对数
date_features=True, # 提取年/月/周末
target_encode=True, # 编码高基数分类变量
auto_bin=True, # 分位数分组
)
X_train_eng = fe.fit_transform(X_train, y_train)
X_test_eng = fe.transform(X_test)
```
---
## 高级超参数调优
```python
from scomp_link.models.advanced_tuning import OptunaOptimizer
def param_space(trial):
return {
'n_estimators': trial.suggest_int('n_estimators', 50, 500),
'max_depth': trial.suggest_int('max_depth', 3, 20),
'learning_rate': trial.suggest_float('learning_rate', 0.01, 0.3, log=True),
}
optimizer = OptunaOptimizer(GradientBoostingRegressor, param_space, scoring='r2', n_trials=100)
best_model = optimizer.optimize(X_train, y_train)
```
---
## 可解释性
```python
from scomp_link import ShapExplainer, LimeExplainer
# SHAP
shap_exp = ShapExplainer(model, X_train[:100])
shap_exp.explain(X_test)
importance = shap_exp.feature_importance()
fig = shap_exp.plot_importance()
# LIME
lime_exp = LimeExplainer(model, X_train, task='regression')
exp = lime_exp.explain_instance(X_test.iloc[0])
fig = lime_exp.plot_explanation(exp)
```
---
## 数据漂移检测
```python
from scomp_link import DriftDetector
detector = DriftDetector(X_train, psi_threshold=0.2)
report = detector.detect(X_production)
summary = detector.summary(report)
fig = detector.plot_drift_report(report)
```
---
## 公平性和偏差指标
```python
from scomp_link import FairnessMetrics
fm = FairnessMetrics(y_true, y_pred, sensitive_feature=df['gender'])
report = fm.compute_all()
print(fm.summary(report))
fig = fm.plot_fairness_report(report)
```
---
## 时间序列预测
```python
from scomp_link import TimeSeriesForecaster
fc = TimeSeriesForecaster(method='auto', horizon=30)
fc.fit(series)
forecast = fc.predict_with_ci()
cv_results = fc.walk_forward_cv(series, n_splits=5)
fig = fc.plot_forecast()
```
---
## 数据质量报告
```python
from scomp_link import DataQualityReport
dqr = DataQualityReport(df)
report = dqr.generate() # 缺失、基数、常量、重复、相关性
dqr.save_html('quality_report.html')
```
---
## 异常检测
```python
from scomp_link import AnomalyDetector
detector = AnomalyDetector(
contamination=0.05,
methods=['iforest', 'lof', 'tabnet', 'transformer'],
consensus_threshold=2,
)
results = detector.fit_predict(df, features=['col1', 'col2', 'col3'])
```
---
## 项目结构
```
scomp_link/
├── cli.py # CLI（24个命令）
├── core.py # ScompLinkPipeline编排器
├── preprocessing/
│ ├── data_processor.py # 预处理器（polars后端）
│ ├── feature_engineer.py # 特征工程师（sklearn兼容）
│ └── data_quality.py # 数据质量报告
├── models/
│ ├── model_factory.py # 决策树模型选择
│ ├── regressor_optimizer.py
│ ├── classifier_optimizer.py
│ ├── ensemble_optimizer.py
│ ├── advanced_tuning.py # Optuna、Halving、EarlyStopping
│ ├── forecaster.py # TimeSeriesForecaster
│ ├── anomaly_detector.py
│ ├── ts_anomaly_detector.py
│ ├── contrastive_text.py # BERT对比学习
│ ├── supervised_text.py
│ └── supervised_img.py
├── validation/
│ ├── model_validator.py # 指标 + HTML报告
│ ├── advanced_cv.py # LOOCV、Bootstrap
│ └── fairness.py # FairnessMetrics
├── explainability/
│ └── explainer.py # ShapExplainer、LimeExplainer
├── monitoring/
│ └── drift_detector.py # DriftDetector（PSI + KS）
├── persistence/
│ └── artifact.py # ScompArtifact（.scomp格式）
└── utils/
├── colors.py # 集中式颜色调色板
├── logger.py # 可配置日志记录
├── report_html.py # HTML报告构建器
├── plotly_utils.py # Plotly图表实用工具
├── highcharts.py # Highcharts可视化
└── rawgraphs/ # 31个SVG图表函数（服务端）
```
---
---
## AI代理集成
scomp-link通过**MCP（模型上下文协议）**和**代理技能**与AI代理原生集成。
### MCP服务器（15种结构化代理调用的工具）
```bash
pip install scomp-link[mcp]
scomp-link mcp # 启动MCP服务器（stdio传输）
```
**Claude Desktop** (`claude_desktop_config.json`)：
```json
{"mcpServers": {"scomp-link": {"command": "scomp-link", "args": ["mcp"]}}}
```
**Kiro** (`.kiro/mcp.json`)：
```json
{"mcpServers": {"scomp-link": {"command": "scomp-link", "args": ["mcp"]}}}
```
**可用工具：** `describe_data`、`train_model`、`predict`、`validate_model`、`detect_drift`、`detect_anomalies`、`check_fairness`、`forecast_series`、`engineer_features`、`cluster_data`、`generate_report`、`create_visualization`、`compare_models`、`export_model`
### 代理技能（零依赖文档）
```bash
# For Kiro
cp -r skills/scomp-link ~/.kiro/skills/
# For Claude Code
cp -r skills/scomp-link .claude/skills/
```
查看 [AGENT_INTEGRATION.md](AGENT_INTEGRATION.md) 以获取完整设置指南。
## 测试
```bash
# 运行所有测试
pytest tests/ -v
# 使用覆盖率
pytest tests/ --cov=scomp_link --cov-report=html
```
---
## 文档
完整文档，包括API引用和CLI指南：
```bash
pip install mkdocs mkdocs-material "mkdocstrings[python]"
mkdocs serve # http://localhost:8000
```
---
## 贡献
```bash
git clone https://github.com/GiacomoSaccaggi/scomp-link.git
cd scomp_link
pip install -e ".[dev]"
pytest tests/ -v
```
---
## 许可证
MIT许可证
---
**愿代码与你同在。** 🚀
📦 [scomp-link on PyPI](https://pypi.org/project/scomp-link/)
