SuperModelingFactory 0.2.0__py3-none-any.whl

Report/Report_Tool.py

@@ -0,0 +1,380 @@
+from ExcelMaster.ExcelMaster import ExcelMaster
+import logging
+
+def single_model_perf(em, ws, fig_path, res_path, model_name, image_size, text = None):
+    """ Put Single Model Performance Summary. """
+    
+    em.gap_number = 0
+    if text is not None:
+        em.write_text_content(ws, input_text = text)
+    em._resize_image(imgPath = fig_path, resize = image_size, outPath = fig_path)
+    img_loc = em.insert_image(ws, figPath = fig_path, retCellRange = "value")
+
+    em.gap_number = 1
+    perf_res = pd.read_csv(res_path)
+    perf_res["Top10%_Lift"] = perf_res["Top10%_TargetRate"]/perf_res["avgTrue"]
+    perf_res["AUC_Shift"] = perf_res["AUC"].shift(1)/perf_res["AUC"] - 1
+    df_loc = em.write_dataframe(ws, df = perf_res.round(3), title=f"Performance for {model_name}", 
+                       index=False, header=True, retCellRange="value")
+    
+    return img_loc, df_loc
+
+def write_var_info(em, ws, var, var_name, data_dict, var_info_title = "", skipby = "row"):
+    """ Write Var Information Table. """
+    description = data_dict.loc[data_dict[var_name] == f"{var}", "description"].values[0]
+    
+    em.gap_number = 0
+    single_var_info = data_dict.loc[data_dict[var_name] == var, :]
+    info_loc = em.write_dataframe(ws, df = single_var_info, index = False,
+                                   title=var_info_title, skipby=skipby,
+                                   retCellRange="value")
+    
+    return description, info_loc
+
+
+def plot_woe(em, ws, var, woe_bins, x_col, spec_missing_value = -99999, chart_size = (20, 5), var_name = "var_name", description = "", skipby = "row"):
+    """ Plot WOE Table. """
+    
+    pd.options.mode.chained_assignment = None
+
+    em.gap_number = 1
+    single_var_bin = woe_bins[woe_bins[var_name] == var]
+    if single_var_bin.shape[0] > 0:
+        single_var_bin.loc[:,"mean"] = single_var_bin.loc[:, "tr"].mean()
+        single_var_bin.loc[:,"mean_wo_nan"] = single_var_bin.loc[~single_var_bin["bin_value"].str.startswith(f"[{str(spec_missing_value)}"),"tr"].mean()
+    iv = round(single_var_bin["iv"].sum(), 4)
+    
+    chart_loc = em.write_duo_chart(worksheet=ws, 
+                                   df = single_var_bin, 
+                                   y1_list=["n1", "n0"], y2_list=["tr"], 
+                                   x = x_col,
+                                   c1_type="stacked_column", c2_type="line",
+                                   y1_axis_range = None, y2_axis_range=None,
+                                   title=f"{var} \n (iv: {iv})", 
+                                   chart_size=chart_size,
+                                   xy_axes_name=(description, "N", "Bad Rate"),
+                                   major_gridlines=False,
+                                   retChart=True if single_var_bin.shape[0] > 0 else False,
+                                   y2_num_format = "0.00%",
+                                   y2_line_type=None,
+                                   skipby=skipby,
+                                   retCellRange='value')
+    
+    if single_var_bin.shape[0] > 0:
+        column_chart = chart_loc[0]
+        line_chart = chart_loc[1]
+        fnl_line_chart = em.write_chart(worksheet = ws, 
+                                        df = single_var_bin, 
+                                        y_list = ['mean', 'mean_wo_nan'], 
+                                        x = x_col,
+                                        chart_type = "line", 
+                                        chart_size = chart_size,
+                                        y_num_format = "0.00%", 
+                                        line_type = "long_dash",
+                                        line_marker = "triangle",
+                                        xy_axes_name = (description, "Bad Rate"),
+                                        major_gridlines=False,
+                                        retChart = True,
+                                        y2_axis = True,
+                                        append_to_chart = line_chart)
+
+        chart_loc = em.write_combined_chart(ws, 
+                                            chart1 = column_chart, 
+                                            chart2 = fnl_line_chart, 
+                                            chart_size = chart_size, 
+                                            skipby = skipby, 
+                                            retCellRange="value")
+    return chart_loc
+
+
+def get_woe_plot_report(em, ws, analysis_dir, varlist, means_rpt = None):
+    """ Generate Plots for WOE BINS in Excel."""
+    
+    train_image_dir = f"{analysis_dir}/woe_plot/"
+
+    group_woe_bins = pd.read_csv(f"{analysis_dir}/numvars_woe_group.csv").rename(columns={"Unnamed: 0":"VAR"})
+    woe_bins = pd.read_csv(f"{analysis_dir}/numvars_woe.csv").rename(columns={"Unnamed: 0":"VAR"})
+
+    woe_bins.columns = [x.lower() for x in woe_bins]
+    group_woe_bins.columns = [x.lower() for x in group_woe_bins]
+
+    valid_varlist = []
+    for var in varlist:
+        train_fig_path = f"{train_image_dir}/{var}_woe_group.png"
+        if os.path.isfile(train_fig_path):
+            valid_varlist.append(var)
+
+    logging.info(f"Valid Number of Vars: {len(valid_varlist)}")
+
+    em.merge_col(ws, ncols=5, text = "Bivar Table")
+
+    varlist = valid_varlist
+
+    image_size = (30, 9)
+    em.reset_curr_loc(loc = (3, 1))
+    info_loc_list = {"train":[], "train_group":[]}
+    image_loc_list = {"train":[], "train_group":[]}
+    for var in varlist:
+
+        train_fig_path = f"{train_image_dir}/{var}_woe.png"
+        train_group_fig_path = f"{train_image_dir}/{var}_woe_group.png"
+
+        ### Column 1 ###
+        em._resize_image(imgPath=train_fig_path, resize = image_size, outPath = train_fig_path)
+        train_image_loc = em.insert_image(ws, figPath=train_fig_path, retCellRange="value")
+        image_loc_list["train"].append(train_image_loc)
+
+        ### Column 2 ###
+        start_row = train_image_loc[0]
+        start_col = train_image_loc[3] + 1
+        em.reset_curr_loc(loc = (start_row, start_col))
+
+        em._resize_image(imgPath=train_group_fig_path, resize = image_size, outPath = train_group_fig_path)
+        train_group_image_loc = em.insert_image(ws, figPath=train_group_fig_path, retCellRange="value")
+        image_loc_list["train_group"].append(train_group_image_loc)
+
+        ### Column 3 ###
+        start_row = train_group_image_loc[0]
+        start_col = train_group_image_loc[3] + 1
+        em.reset_curr_loc(loc = (start_row, start_col))
+        
+        if means_rpt is not None:
+            
+            means_rpt_var = means_rpt.loc[means_rpt['attribute'] == var, :].round(2).drop(columns = ['attribute']).T
+            means_rpt_loc = em.write_dataframe(ws, df = means_rpt_var, title=f"Means for {var}", index=True, header=False, retCellRange="value")
+
+            for i in range(means_rpt_loc[2], means_rpt_loc[2] + 1):
+                cell_range = [i,                     # Start Row
+                              means_rpt_loc[1] + 1,  # Start Col
+                              i,                     # End Row
+                              means_rpt_loc[3]       # End Col
+                              ]
+                em.set_color_scale(ws, cell_range=cell_range, colors = ("#FFFFFF", "#F8696B")) 
+                em.set_cell_format(ws, cell_range=cell_range, cformat = "NUM%.2")
+
+        ### Next Row ###
+        start_row = train_image_loc[2] + 3
+        start_col = train_image_loc[1]
+        em.reset_curr_loc(loc = (start_row, start_col))
+
+    em.reset_curr_loc(loc = (3, 0))
+    for i, var in enumerate(varlist):
+
+        em.gap_number = 0
+        c_len = image_size[0]
+        repeat_num = c_len + 3
+        var_name_df = pd.DataFrame([var] * repeat_num)
+        var_df_loc = em.write_dataframe(ws, df = var_name_df, title=None, index=False, header=False, retCellRange="value")
+        
+    return 0
+
+
+def get_woe_plot_report_new(em, ws, woe_plot_dir, grp_name, varlist, means_rpt = None):
+    """ Generate Plots for WOE BINS in Excel."""
+    
+    train_image_dir = woe_plot_dir
+
+    valid_varlist = []
+    for var in varlist:
+        train_fig_path = f"{train_image_dir}/{var}_{grp_name}.png"
+        if os.path.isfile(train_fig_path):
+            valid_varlist.append(var)
+
+    logging.info(f"Valid Number of Vars: {len(valid_varlist)}")
+
+    em.merge_col(ws, ncols=5, text = "Bivar Table")
+
+    varlist = valid_varlist
+
+    image_size = (40, 9)
+    em.reset_curr_loc(loc = (3, 1))
+    info_loc_list = {"train":[], f"train_{grp_name}":[]}
+    image_loc_list = {"train":[], f"train_{grp_name}":[]}
+    for var in varlist:
+
+        train_fig_path = f"{train_image_dir}/{var}.png"
+        train_group_fig_path = f"{train_image_dir}/{var}_{grp_name}.png"
+
+        ### Column 1 ###
+        em._resize_image(imgPath=train_fig_path, resize = image_size, outPath = train_fig_path)
+        train_image_loc = em.insert_image(ws, figPath=train_fig_path, retCellRange="value")
+        image_loc_list["train"].append(train_image_loc)
+
+        ### Column 2 ###
+        start_row = train_image_loc[0]
+        start_col = train_image_loc[3] + 1
+        em.reset_curr_loc(loc = (start_row, start_col))
+
+        em._resize_image(imgPath=train_group_fig_path, resize = image_size, outPath = train_group_fig_path)
+        train_group_image_loc = em.insert_image(ws, figPath=train_group_fig_path, retCellRange="value")
+        image_loc_list[f"train_{grp_name}"].append(train_group_image_loc)
+
+        ### Column 3 ###
+        start_row = train_group_image_loc[0]
+        start_col = train_group_image_loc[3] + 1
+        em.reset_curr_loc(loc = (start_row, start_col))
+        
+        if means_rpt is not None:
+            
+            means_rpt_var = means_rpt.loc[means_rpt['attribute'] == var, :].round(2).drop(columns = ['attribute']).T
+            means_rpt_loc = em.write_dataframe(ws, df = means_rpt_var, title=f"Means for {var}", index=True, header=False, retCellRange="value")
+
+            for i in range(means_rpt_loc[2], means_rpt_loc[2] + 1):
+                cell_range = [i,                     # Start Row
+                              means_rpt_loc[1] + 1,  # Start Col
+                              i,                     # End Row
+                              means_rpt_loc[3]       # End Col
+                              ]
+                em.set_color_scale(ws, cell_range=cell_range, colors = ("#FFFFFF", "#F8696B")) 
+                em.set_cell_format(ws, cell_range=cell_range, cformat = "NUM%.2")
+
+        ### Next Row ###
+        start_row = train_image_loc[2] + 3
+        start_col = train_image_loc[1]
+        em.reset_curr_loc(loc = (start_row, start_col))
+
+    em.reset_curr_loc(loc = (3, 0))
+    for i, var in enumerate(varlist):
+
+        em.gap_number = 0
+        c_len = image_size[0]
+        repeat_num = c_len + 3
+        var_name_df = pd.DataFrame([var] * repeat_num)
+        var_df_loc = em.write_dataframe(ws, df = var_name_df, title=None, index=False, header=False, retCellRange="value")
+        
+    return 0
+
+
+def get_multi_model_perf_report(em, ws, eval_img_path, eval_res_path):
+    """ Create Multi-models Evaluation Report. """
+    
+    image_size = (39, 13)
+    init_format = {
+        'bold': True,
+        'underline': False,            
+        'font_name': 'Arial',
+        'font_size': 18,
+        'font_color': '#000000',
+        'align': 'left'
+    }
+
+    em.add_new_format(format_dict = init_format, format_name="CUS_#")
+
+    init_format.update({"font_size": 14, "bg_color": "#FFD966"})
+    em.add_new_format(format_dict = init_format, format_name="CUS_##")
+
+    em.write_text_content(worksheet=ws, input_text="{CUS_#} 多模型评估（未调参版) \n \n")
+    h2_loc = em.write_text_content(worksheet=ws, input_text="{CUS_##} 直接使用三方特征 \n", retCellRange="value")
+    
+    em.set_cell_format(ws, cell_range=[h2_loc[0], h2_loc[1], h2_loc[2] - 2, h2_loc[3] + 5], cformat = "CUS_##")
+
+    img_loc1, df_loc1 = single_model_perf(em, ws, 
+                                          fig_path = f"{eval_img_path}/xgb_original_perf.jpg", 
+                                          res_path = f"{eval_res_path}/xgb_original_perf.csv", 
+                                          model_name = "XGBoost",
+                                          image_size = image_size)
+    
+    em.reset_curr_loc(loc=(img_loc1[0], df_loc1[3] + 3))
+    img_loc2, df_loc2 = single_model_perf(em, ws, 
+                                          fig_path = f"{eval_img_path}/lgb_original_perf.jpg", 
+                                          res_path = f"{eval_res_path}/lgb_original_perf.csv", 
+                                          model_name = "LightGBM",
+                                          image_size = image_size)
+
+    ################################## Division Line ###############################
+    tmp_color = em.add_new_format({'bg_color': '#D6DCE4'}, "bg_tmp")
+    div_line_loc = [df_loc2[2] + 2, 0, df_loc2[2] + 2, 200]
+    em.set_cell_format(ws, cell_range=div_line_loc, cformat = "bg_tmp")
+    ################################## Division Line ###############################
+
+    em.reset_curr_loc(loc=(div_line_loc[0] + 2, df_loc1[1]))
+    h2_loc = em.write_text_content(worksheet=ws, input_text="{CUS_##} 特征WOE处理后建模 \n", retCellRange="value")
+    em.set_cell_format(ws, cell_range=[h2_loc[0], h2_loc[1], h2_loc[2] - 2, h2_loc[3] + 5], cformat = "CUS_##")
+
+    img_loc, df_loc = single_model_perf(em, ws, 
+                                        fig_path = f"{eval_img_path}/lr_woe_perf.jpg", 
+                                        res_path = f"{eval_res_path}/lr_woe_perf.csv", 
+                                        model_name = "Logistic Regression",
+                                        image_size = image_size)
+
+    em.reset_curr_loc(loc=(img_loc[0], df_loc[3] + 3))
+    img_loc, df_loc = single_model_perf(em, ws, 
+                                        fig_path = f"{eval_img_path}/xgb_woe_perf.jpg", 
+                                        res_path = f"{eval_res_path}/xgb_woe_perf.csv", 
+                                        model_name = "XGBoost",
+                                        image_size = image_size)
+
+    em.reset_curr_loc(loc=(img_loc[0], df_loc[3] + 3))
+    img_loc, df_loc = single_model_perf(em, ws, 
+                                        fig_path = f"{eval_img_path}/lgb_woe_perf.jpg", 
+                                        res_path = f"{eval_res_path}/lgb_woe_perf.csv", 
+                                        model_name = "LightGBM",
+                                        image_size = image_size)
+    
+    return None
+
+def get_multi_model_varimp(em, ws, raw_varimp = None, woe_varimp = None):
+    """ Varimp for Multi Model Evaluation. """
+    
+    ################################# Varimp Worksheet ##################################
+    em.write_text_content(worksheet=ws, input_text="{CUS_#} 特征重要性评估 \n \n")
+
+    em.gap_number = 1
+    
+    if raw_varimp is not None:
+        raw_varimp = raw_varimp[['variable', 'xgb_rank', 'xgb_varimp', 'lgb_rank', 'lgb_varimp']]
+        df1_loc = em.write_dataframe(ws, df = raw_varimp.round(4), title=f"Variable Importance (Original Feature)", 
+                                    index=False, header=True, retCellRange="value", skipby = 'col')
+    
+    if woe_varimp is not None:
+        woe_varimp = woe_varimp[['variable', 'lr_rank', 'coefficient', 'xgb_rank', 'xgb_varimp', 'lgb_rank', 'lgb_varimp']]
+        df2_loc = em.write_dataframe(ws, df = woe_varimp.round(4), title=f"Variable Importance (WOE-ed Feature)", 
+                                    index=False, header=True, retCellRange="value")
+
+    return 0
+
+def get_fnl_model_report(em, ws, result_dir):
+    """ Create Final Model Performance Report. """
+    
+    image_size = (39, 13)
+    init_format = {
+        'bold': True,
+        'underline': False,            
+        'font_name': 'Arial',
+        'font_size': 18,
+        'font_color': '#000000',
+        'align': 'left'
+    }
+
+    em.add_new_format(format_dict = init_format, format_name="CUS_#")
+
+    init_format.update({"font_size": 14, "bg_color": "#FFD966"})
+    em.add_new_format(format_dict = init_format, format_name="CUS_##")
+
+    em.write_text_content(worksheet=ws, input_text="{CUS_#} 终版模型评估 \n \n")
+
+    h2_loc = em.write_text_content(worksheet=ws, input_text="{CUS_##} 原始特征建模 \n", retCellRange="value")
+    em.set_cell_format(ws, cell_range=[h2_loc[0], h2_loc[1], h2_loc[2] - 2, h2_loc[3] + 5], cformat = "CUS_##")
+
+    img_loc, df_loc = single_model_perf(em, ws, 
+                                        fig_path = f"{result_dir}/xgb_fnl_model_perf.jpg", 
+                                        res_path = f"{result_dir}/xgb_fnl_model_perf.csv", 
+                                        model_name = "XGBoost (Without MC)",
+                                        text = "{###} XGBoost (Without Monotonic Constraints) \n",
+                                        image_size = image_size)
+    
+    return 0
+
+
+def get_model_varimp(em, ws, varimp):
+    """ Varimp for Multi Model Evaluation. """
+    
+    ################################# Varimp Worksheet ##################################
+    em.write_text_content(worksheet=ws, input_text="{CUS_#} 特征重要性评估 \n \n")
+
+    em.gap_number = 1
+
+    df1_loc = em.write_dataframe(ws, df = varimp.round(4), title=f"Variable Importance", 
+                                index=False, header=True, retCellRange="value", skipby = 'col')
+
+    return 0

Report/__init__.py

@@ -0,0 +1,3 @@
+# encoding: utf-8
+"""Report composition helpers bundled with SuperModelingFactory."""
+

supermodelingfactory-0.2.0.dist-info/METADATA

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: SuperModelingFactory
+Version: 0.2.0
+Summary: Credit risk modeling factory: WOE binning, scorecards, LightGBM, Excel reporting.
+Home-page: https://github.com/Kyle-J-Sun/SuperModelingFactory
+Author: Kyle Sun
+Author-email: Kyle Sun <jingkai.sun20@alumni.imperial.ac.uk>
+License: BUSL-1.1
+Project-URL: Homepage, https://github.com/Kyle-J-Sun/SuperModelingFactory
+Project-URL: Documentation, https://kyle-j-sun.github.io/SuperModelingFactory_doc
+Project-URL: Source, https://github.com/Kyle-J-Sun/SuperModelingFactory
+Keywords: credit-risk,scorecard,woe,lightgbm,psi,iv,modeling,fintech
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: License :: Other/Proprietary License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas<3,>=1.5.0
+Requires-Dist: numpy>=1.23.0
+Requires-Dist: scipy>=1.9.0
+Requires-Dist: scikit-learn>=1.1.0
+Requires-Dist: joblib>=1.2.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: lightgbm>=3.3.0
+Requires-Dist: xgboost>=1.7.0
+Requires-Dist: catboost>=1.2.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: seaborn>=0.12.0
+Requires-Dist: xlsxwriter>=3.0.0
+Requires-Dist: openpyxl>=3.0.0
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: tqdm>=4.64.0
+Provides-Extra: optuna
+Requires-Dist: optuna>=4.0.0; extra == "optuna"
+Provides-Extra: stats
+Requires-Dist: statsmodels>=0.13.0; extra == "stats"
+Provides-Extra: imblearn
+Requires-Dist: imbalanced-learn>=0.10.0; extra == "imblearn"
+Provides-Extra: explain
+Requires-Dist: shap>=0.44.0; extra == "explain"
+Requires-Dist: lime>=0.2.0.1; extra == "explain"
+Provides-Extra: odps
+Requires-Dist: pyodps>=0.11.0; extra == "odps"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# SuperModelingFactory
+
+[![PyPI](https://img.shields.io/pypi/v/supermodelingfactory.svg)](https://pypi.org/project/supermodelingfactory/)
+[![Python](https://img.shields.io/pypi/pyversions/supermodelingfactory.svg)](https://pypi.org/project/supermodelingfactory/)
+[![License: BSL 1.1](https://img.shields.io/badge/license-BSL%201.1-blue.svg)](LICENSE)
+[![Build wheels](https://github.com/Kyle-J-Sun/SuperModelingFactory/actions/workflows/build.yml/badge.svg)](https://github.com/Kyle-J-Sun/SuperModelingFactory/actions/workflows/build.yml)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://kyle-j-sun.github.io/SuperModelingFactory_doc/)
+
+风控建模工厂 —— 一套面向信用评分卡开发与模型管理的完整 Python 工具链。
+
+📖 **[在线文档](https://kyle-j-sun.github.io/SuperModelingFactory_doc/)** · 安装、快速上手、API 参考、用户指南一应俱全。
+
+## 安装
+
+```bash
+pip install supermodelingfactory
+```
+
+macOS 用户额外需要安装 OpenMP 运行时（lightgbm 依赖）：
+
+```bash
+brew install libomp
+```
+
+支持的环境：Python 3.10 / 3.11 / 3.12 / 3.13，平台 macOS arm64 / Linux x86_64 / Windows x86_64。
+
+详见 [INSTALL.md](INSTALL.md)。
+
+## 许可证
+
+本项目采用 **Business Source License 1.1**，Change Date 为 **2030-06-24**。之前：
+
+- ✅ 允许：个人学习、学术研究、内部评估、原型、教学
+- ❌ 不允许：任何生产 / 商业 / 营收性使用
+
+2030-06-24 后自动转为 Apache 2.0。商业授权请联系作者。
+
+项目现在以源码形式打包和分发；wheel 与 sdist 均包含 Python 源码，不再通过 Cython 隐藏核心模块实现。
+
+## 项目概述
+
+SuperModelingFactory 整合了信贷风控建模全流程所需的三大能力：
+
+| 子项目 | 功能定位 | 核心能力 |
+|--------|---------|---------| 
+| **[Modeling_Tool](Modeling_Tool/)** | 建模引擎 | 数据分箱、WOE 编码、特征分析、模型训练与评估、样本管理 |
+| **[ExcelMaster](ExcelMaster/)** | 报告引擎 | 程序化 Excel 工作簿生成，支持图表、条件格式、光标流式写入 |
+| **[Report](Report/)** | 报告模板 | 模型性能报告、WOE 图批量导出、多模型对比报告 |
+
+## 项目结构
+
+```
+SuperModelingFactory/
+├── Modeling_Tool/          # 核心建模工具包
+│   ├── Core/               #   基础设施：分箱、ODPS、工具函数、加密
+│   ├── WOE/                #   WOE 编码：分箱、变换、映射、可视化
+│   ├── Feature/            #   特征分析：分布偏移、PSI、相关性过滤
+│   ├── Model/              #   模型训练：LR、LightGBM、XGBoost、变量选择
+│   ├── Eval/               #   模型评估：Gains 表、ROC/KS、性能汇总
+│   └── Sample/             #   样本管理：切分、分层、拒绝推断、分布适配
+├── ExcelMaster/            # Excel 报告引擎
+│   ├── ExcelFormatTool.py  #   格式定义（50+ 预设单元格格式）
+│   ├── ExcelMaster.py      #   核心引擎（光标流式写入、图表、条件格式）
+│   ├── Template.py         #   分析报告模板（PVA、Bivar、GridSearch 等）
+│   └── Utility.py          #   工具函数（颜色、路径、PSI 报表处理等）
+└── Report/                 # 模型评估报告模板
+    └── Report_Tool.py      #   性能报告、WOE 绘图、多模型对比
+```
+
+## 安装
+
+### 依赖
+
+```bash
+# 核心依赖
+pip install pandas numpy scipy scikit-learn
+
+# 建模引擎
+pip install lightgbm xgboost joblib
+
+# Excel 报告
+pip install xlsxwriter openpyxl Pillow matplotlib seaborn
+
+# 可选
+pip install pyodps          # 阿里云 MaxCompute 连接
+pip install imbalanced-learn # SMOTE 采样
+pip install tqdm             # 进度条
+```
+
+### 使用
+
+```bash
+git clone <repo-url>
+cd SuperModelingFactory
+export PYTHONPATH="${PYTHONPATH}:$(pwd)"
+```
+
+## 快速开始
+
+### 典型风控建模流程
+
+```python
+from Modeling_Tool import (
+    # 分箱
+    Binning, super_binning,
+    # WOE 编码
+    WOE_Master,
+    # 特征分析
+    VarExtractionInsights, CorrelationFilter, PSICalculator,
+    # 模型训练
+    GradientBoostingModel, LRMaster,
+    # 模型评估
+    GainsTableCalculator, PerformanceEvaluator,
+    # 样本管理
+    SampleSplitter, RejectInferrer
+)
+
+# 1. 样本切分
+splitter = SampleSplitter(test_size=0.3, random_state=42, stratify=True)
+train_df, test_df = splitter.split_df(data, target='is_bad')
+
+# 2. WOE 分箱与编码
+woe_master = WOE_Master(train_data=train_df, varlist=feature_cols, dep='is_bad')
+woe_master.fit(nbins=10, equal_freq=True)
+train_woe = woe_master.transform(train_df)
+test_woe = woe_master.transform(test_df)
+
+# 3. 特征筛选
+psi_calc = PSICalculator(buckets=10)
+psi_result = psi_calc.calculate(expected_df=train_df, current_data=test_df, varlist=feature_cols)
+
+corr_filter = CorrelationFilter(data=train_woe, dep='is_bad')
+keep_vars = corr_filter.remove_highly_correlated(feature_cols)
+
+# 4. 模型训练
+model = GradientBoostingModel('lgb', params={'n_estimators': 100, 'learning_rate': 0.1})
+model.fit(train_woe[keep_vars], train_woe['is_bad'], test_woe[keep_vars], test_woe['is_bad'])
+
+# 5. 模型评估
+evaluator = PerformanceEvaluator(tgt_name='is_bad', model=model.model, feature_cols=keep_vars)
+evaluator.add_dataset('train', train_woe).add_dataset('test', test_woe)
+perf_result = evaluator.evaluate()
+```
+
+### 使用 ExcelMaster 生成报告
+
+```python
+from ExcelMaster.ExcelMaster import ExcelMaster
+
+em = ExcelMaster('model_report.xlsx')
+ws = em.add_worksheet('Performance')
+
+# 流式写入 DataFrame
+em.write_dataframe(ws, perf_result, title='模型性能汇总', titleformat='BLUE_H2')
+em.insert_image(ws, 'roc_curve.png', figScale=(600, 400))
+
+em.close_workbook()
+```
+
+## 架构设计
+
+### 依赖方向
+
+```
+                    ┌─────────┐
+                    │  Core   │  (基础设施，无跨包依赖)
+                    └────┬────┘
+           ┌─────────┬───┼───────┬─────────┐
+           ▼         ▼   ▼       ▼         ▼
+         WOE      Model  Eval  Feature   Sample
+           │         │              │        │
+           └─────────┴──────────────┴────────
+                (均单向依赖 Core，模块间延迟导入)
+```
+
+- **Core** 是所有子包的基础，不依赖任何其他子包
+- 其他子包之间通过**延迟导入**（函数体内 import）避免循环依赖
+- 顶层 `Modeling_Tool/__init__.py` 提供精选的统一 API
+
+### 命名规范
+
+- 所有公开 API 通过 `__init__.py` 导出，使用方只需 `from Modeling_Tool import ...`
+- 类名采用 PascalCase，函数名采用 snake_case
+- 以 `_` 开头的函数/方法为内部实现，不对外暴露
+
+## 持续集成
+
+本仓库的 GitHub Actions(`.github/workflows/tests.yml`)会在 push 到 `main` 与 PR 上自动跑 pytest,矩阵为:
+
+- **Python**:`3.11`、`3.12`
+- **依赖矩阵**:
+  - `legacy` — `numpy<2` + `scipy<1.13` + `lightgbm<4`
+  - `modern` — `numpy>=2` + `scipy>=1.13` + `lightgbm>=4`
+- **共同约束**:`pandas>=2.0,<2.3`(等 [issue #2](https://github.com/Kyle-J-Sun/SuperModelingFactory/issues/2) 修复后放宽)
+
+测试用例托管在独立仓库 [`SuperModelingFactory_pytest`](https://github.com/Kyle-J-Sun/SuperModelingFactory_pytest)(私有),workflow 通过 `secrets.PYTEST_REPO_TOKEN` 跨仓 clone。
+
+### 配置 PAT(只需做一次)
+
+1. 进入 [GitHub Settings · Tokens (classic)](https://github.com/settings/tokens) 生成新 token,scope 勾选 `repo`(只读访问私有仓库即可)
+2. 进入本仓库 **Settings → Secrets and variables → Actions → New repository secret**
+3. Name: `PYTEST_REPO_TOKEN`,Value: 粘贴 token
+
+如改用 Fine-grained PAT,需将其授权访问 `SuperModelingFactory_pytest` 仓库的 *Contents: Read* 权限。
+
+## 版本
+
+- **Version**: 0.2.0
+- **Author**: Jingkai Sun
+
+## 许可证
+
+内部项目，仅供团队使用。