SuperModelingFactory 0.3.5__tar.gz → 0.3.6__tar.gz

{supermodelingfactory-0.3.5 → supermodelingfactory-0.3.6}/Modeling_Tool/Pipeline/_common.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import re
 from dataclasses import fields, is_dataclass
 from pathlib import Path
 from typing import Any, Iterable, Mapping
@@ -8,6 +9,36 @@ from typing import Any, Iterable, Mapping
 import numpy as np
 import pandas as pd
 
+_QUERY_COLUMN_RE = re.compile(r"(?<!['\"])\b([A-Za-z_][\w]*)\b(?![\'\"])")
+_QUERY_RESERVED = frozenset(
+    {
+        "and",
+        "or",
+        "not",
+        "True",
+        "False",
+        "None",
+        "in",
+        "is",
+        "where",
+        "if",
+        "else",
+        "lambda",
+        "abs",
+        "all",
+        "any",
+        "max",
+        "min",
+        "sum",
+        "len",
+        "round",
+        "float",
+        "int",
+        "str",
+        "bool",
+    }
+)
+
 
 def make_dirs(*paths: str | os.PathLike | None) -> None:
     for path in paths:
@@ -29,6 +60,83 @@ def merge_dict(base: Mapping[str, Any] | None, override: Mapping[str, Any] | Non
     return merged
 
 
+def query_referenced_columns(expr: str) -> set[str]:
+    """Return identifier-like column names referenced in a pandas query expression."""
+    if not expr or not str(expr).strip():
+        return set()
+    return {
+        match.group(1)
+        for match in _QUERY_COLUMN_RE.finditer(str(expr))
+        if match.group(1) not in _QUERY_RESERVED
+    }
+
+
+def validate_woe_fit_query_syntax(data: pd.DataFrame, query: str) -> None:
+    """Raise ValueError when a woe_fit_query expression is syntactically invalid."""
+    if not query:
+        return
+    sample = data.head(min(100, len(data)))
+    if sample.empty:
+        raise ValueError("woe_fit_query cannot be validated on an empty dataset.")
+    try:
+        sample.query(query, engine="python")
+    except SyntaxError as exc:
+        raise ValueError(f"Invalid woe_fit_query syntax: {query!r}") from exc
+    except Exception as exc:
+        raise ValueError(f"woe_fit_query failed on sample data: {query!r} ({exc})") from exc
+
+
+def validate_woe_fit_query_columns(
+    query: str,
+    available_cols: Iterable[str],
+    *,
+    context: str = "dataset",
+) -> None:
+    """Raise KeyError when query references columns missing from available_cols."""
+    if not query:
+        return
+    available = set(available_cols)
+    missing = sorted(query_referenced_columns(query) - available)
+    if missing:
+        raise KeyError(
+            f"woe_fit_query references missing columns in {context}: {missing}. "
+            "Add them to the input data, batch_base_cols, or population_dims."
+        )
+
+
+def apply_woe_fit_query(
+    train: pd.DataFrame,
+    query: str | None,
+    *,
+    target: str | None = None,
+) -> tuple[pd.DataFrame, dict[str, Any] | None]:
+    """Filter WOE fit rows via pandas query and return an audit row for refine_summary."""
+    if not query:
+        return train, None
+    n_before = len(train)
+    try:
+        filtered = train.query(query, engine="python").copy()
+    except Exception as exc:
+        audit = {
+            "target": target,
+            "step": "fit_filter",
+            "status": "error",
+            "query": query,
+            "n_before": n_before,
+            "error": repr(exc),
+        }
+        return train, audit
+    audit = {
+        "target": target,
+        "step": "fit_filter",
+        "status": "ok",
+        "query": query,
+        "n_before": n_before,
+        "n_after": len(filtered),
+    }
+    return filtered, audit
+
+
 def dataclass_to_dict(obj: Any) -> dict[str, Any]:
     if not is_dataclass(obj):
         return dict(obj)

{supermodelingfactory-0.3.5 → supermodelingfactory-0.3.6}/Modeling_Tool/Pipeline/credit_model.py

@@ -9,11 +9,14 @@ import pandas as pd
 
 from ._common import (
     add_dataset_with_optional_weight,
+    apply_woe_fit_query,
     as_list,
     make_dirs,
     merge_dict,
     predict_positive,
     safe_to_csv,
+    validate_woe_fit_query_columns,
+    validate_woe_fit_query_syntax,
     write_basic_excel,
 )
 
@@ -48,6 +51,8 @@ class CreditModelPipelineConfig:
         }
     )
     woe_engine: str = "equal_freq"
+    woe_fit_query: str | None = None
+    extra_eval_datasets: dict[str, pd.DataFrame] | None = None
     woe_params: dict[str, Any] = field(
         default_factory=lambda: {"nbins": 10, "equal_freq": True, "min_bin_prop": 0.05}
     )
@@ -208,7 +213,11 @@ class CreditModelPipeline:
         models = self._train_models(model_inputs)
 
         optuna_results = self._run_optuna(model_inputs)
-        perf_results = self._evaluate_models(model_inputs, models)
+        perf_results = self._evaluate_models(
+            model_inputs,
+            models,
+            woe_artifacts.get("extra_eval"),
+        )
         explain_outputs = self._run_explainability(model_inputs, models)
         model_paths: dict[str, str] = {}
         artifact_paths: dict[str, str] = {}
@@ -310,6 +319,23 @@ class CreditModelPipeline:
                 raise ValueError("warm_start_score_type must be 'probability' or 'log_odds'")
             if cfg.warm_start_on_unsupported not in {"skip", "raise"}:
                 raise ValueError("warm_start_on_unsupported must be 'skip' or 'raise'")
+        if cfg.woe_fit_query:
+            validate_woe_fit_query_columns(cfg.woe_fit_query, data.columns, context="input data")
+            validate_woe_fit_query_syntax(data, cfg.woe_fit_query)
+        if cfg.extra_eval_datasets:
+            reserved = {"ins", "oos", "oot"}
+            conflicts = sorted(set(cfg.extra_eval_datasets) & reserved)
+            if conflicts:
+                raise ValueError(
+                    f"extra_eval_datasets names cannot conflict with split names {sorted(reserved)}: {conflicts}"
+                )
+            for name, extra_df in cfg.extra_eval_datasets.items():
+                if cfg.target_col not in extra_df.columns:
+                    raise KeyError(f"extra_eval_datasets[{name!r}] missing target_col {cfg.target_col!r}")
+                if cfg.warm_start_enabled and cfg.warm_start_score_col and cfg.warm_start_score_col not in extra_df.columns:
+                    raise KeyError(
+                        f"extra_eval_datasets[{name!r}] missing warm_start_score_col {cfg.warm_start_score_col!r}"
+                    )
 
     def _gbm_weight_kwargs(self, train: pd.DataFrame, val: pd.DataFrame) -> dict[str, Any]:
         cfg = self.config
@@ -466,6 +492,24 @@ class CreditModelPipeline:
         summary["final_features"] = list(current)
         return summary, list(current)
 
+    def _transform_extra_eval_datasets(
+        self,
+        transform_fn: Any,
+        feature_cols: list[str],
+        *,
+        woe_suffix: str | None = None,
+    ) -> dict[str, pd.DataFrame]:
+        cfg = self.config
+        if not cfg.extra_eval_datasets:
+            return {}
+        transformed: dict[str, pd.DataFrame] = {}
+        for name, df in cfg.extra_eval_datasets.items():
+            if woe_suffix is not None:
+                transformed[name] = transform_fn(df, varlist=feature_cols, suffix=woe_suffix)
+            else:
+                transformed[name] = transform_fn(df)
+        return transformed
+
     def _fit_woe(self, splits: dict[str, pd.DataFrame], feature_cols: list[str]) -> dict[str, Any]:
         from Modeling_Tool import MonotoneWOEBinner, WOE_Master
         from Modeling_Tool.WOE.WOE_Adapter import as_woe_engine
@@ -475,6 +519,11 @@ class CreditModelPipeline:
         woe_suffix = cfg.woe_params.get("woe_suffix", "_woe")
         graph_dir = str(Path(cfg.output_dir) / "figs" / "woe")
         woe_features = [f"{col}{woe_suffix}" for col in feature_cols]
+        fit_ins, _ = apply_woe_fit_query(
+            splits["ins"],
+            cfg.woe_fit_query,
+            target=cfg.target_col,
+        )
 
         if cfg.woe_engine.lower() == "monotone":
             params = merge_dict(
@@ -486,7 +535,7 @@ class CreditModelPipeline:
                 cfg.monotone_woe_params,
             )
             binner = MonotoneWOEBinner(**params)
-            binner.fit(splits["ins"], chi2_binning=bool(cfg.monotone_woe_params.get("chi2_binning", False)))
+            binner.fit(fit_ins, chi2_binning=bool(cfg.monotone_woe_params.get("chi2_binning", False)))
             if cfg.write_outputs and cfg.plot_outputs:
                 binner.plot_woe_graph(graph_path=str(Path(cfg.output_dir) / "figs" / "mono_woe"))
             adapter = as_woe_engine(binner, woe_suffix=woe_suffix)
@@ -496,9 +545,14 @@ class CreditModelPipeline:
             }
             woe_table = adapter.get_woe_table(varlist=feature_cols)
             engine = adapter
+            extra_eval = self._transform_extra_eval_datasets(
+                adapter.transform,
+                feature_cols,
+                woe_suffix=woe_suffix,
+            )
         else:
             master = WOE_Master(
-                train_data=splits["ins"],
+                train_data=fit_ins,
                 varlist=feature_cols,
                 dep=cfg.target_col,
                 graph_save_dir=graph_dir,
@@ -518,13 +572,18 @@ class CreditModelPipeline:
                     dirname="overall",
                     varlist=feature_cols,
                 )
-            woe_table = get_overall_woe_table(master, splits["ins"], varlist=feature_cols)
+            woe_table = get_overall_woe_table(master, fit_ins, varlist=feature_cols)
             engine = master
+            extra_eval = self._transform_extra_eval_datasets(master.transform, feature_cols)
 
         if cfg.warm_start_enabled and cfg.warm_start_score_col:
             for name, df in woe_splits.items():
                 if cfg.warm_start_score_col not in df.columns:
                     df[cfg.warm_start_score_col] = splits[name][cfg.warm_start_score_col].to_numpy()
+            for name, df in extra_eval.items():
+                if cfg.warm_start_score_col not in df.columns:
+                    source = cfg.extra_eval_datasets[name]
+                    df[cfg.warm_start_score_col] = source[cfg.warm_start_score_col].to_numpy()
 
         return {
             "engine": engine,
@@ -533,6 +592,7 @@ class CreditModelPipeline:
             "woe_features": woe_features,
             "woe_suffix": woe_suffix,
             "splits": woe_splits,
+            "extra_eval": extra_eval,
             "woe_table": woe_table,
         }
 
@@ -873,13 +933,20 @@ class CreditModelPipeline:
         self,
         model_inputs: dict[str, dict[str, Any]],
         models: dict[str, tuple[Any, Any, list[str]]],
+        extra_eval_splits: dict[str, pd.DataFrame] | None = None,
     ) -> dict[str, pd.DataFrame]:
         from Modeling_Tool import PerformanceEvaluator
 
         cfg = self.config
         results = {}
+        extra_eval_splits = extra_eval_splits or {}
         for name, (wrapper, _, feature_cols) in models.items():
             splits = model_inputs[name]["splits"]
+            source = str(model_inputs[name].get("source", "woe")).lower()
+            if source == "raw" and cfg.extra_eval_datasets:
+                model_extra = {key: df.copy() for key, df in cfg.extra_eval_datasets.items()}
+            else:
+                model_extra = extra_eval_splits
             evaluator = PerformanceEvaluator(
                 tgt_name=cfg.target_col,
                 scr_name=f"pred_{name}",
@@ -887,7 +954,8 @@ class CreditModelPipeline:
                 min_bin_prop=cfg.perf_min_bin_prop,
                 equal_freq=True,
             )
-            for ds_name, df in splits.items():
+            eval_splits = {**splits, **model_extra}
+            for ds_name, df in eval_splits.items():
                 scored = df.copy()
                 scored[f"pred_{name}"] = self._predict_model_positive(name, wrapper, scored, feature_cols)
                 add_dataset_with_optional_weight(evaluator, ds_name, scored, weight_col=cfg.weight_col)

{supermodelingfactory-0.3.5 → supermodelingfactory-0.3.6}/Modeling_Tool/Pipeline/feature_validation.py

@@ -8,7 +8,14 @@ from typing import Any, Literal
 import numpy as np
 import pandas as pd
 
-from ._common import as_list, make_dirs, safe_to_csv
+from ._common import (
+    apply_woe_fit_query,
+    as_list,
+    make_dirs,
+    safe_to_csv,
+    validate_woe_fit_query_columns,
+    validate_woe_fit_query_syntax,
+)
 
 
 @dataclass
@@ -47,6 +54,7 @@ class FeatureValidationPipelineConfig:
     )
 
     woe_enabled: bool = True
+    woe_fit_query: str | None = None
     woe_engine: str = "monotone"
     woe_params: dict[str, Any] = field(
         default_factory=lambda: {"nbins": 10, "equal_freq": True, "min_bin_prop": 0.05}
@@ -257,6 +265,8 @@ class FeatureValidationPipeline:
         self._validate_batch_config(new_features)
         feature_batches = self._make_feature_batches(new_features)
         base_cols = self._resolve_batch_base_cols(header, incumbent_features, target_cols)
+        if cfg.woe_fit_query:
+            validate_woe_fit_query_columns(cfg.woe_fit_query, base_cols, context="CSV batch base columns")
 
         base_df = self._read_csv(csv_path, usecols=base_cols).copy()
         base_df["_smf_batch_row_id"] = np.arange(len(base_df))
@@ -777,6 +787,9 @@ class FeatureValidationPipeline:
             raise ValueError("psi_reference_dataset must be one of ins/oos/oot/external")
         if cfg.psi_reference_dataset == "external" and cfg.psi_reference_data is None:
             raise ValueError("psi_reference_data is required when psi_reference_dataset='external'")
+        if cfg.woe_fit_query:
+            validate_woe_fit_query_columns(cfg.woe_fit_query, data.columns, context="input data")
+            validate_woe_fit_query_syntax(data, cfg.woe_fit_query)
 
     def _resolve_new_features(self, data: pd.DataFrame) -> list[str]:
         cfg = self.config
@@ -979,6 +992,9 @@ class FeatureValidationPipeline:
         refine_rows = []
         for target in target_cols:
             train = splits["ins"][splits["ins"][target].notna()].copy()
+            train, fit_filter_row = apply_woe_fit_query(train, cfg.woe_fit_query, target=target)
+            if fit_filter_row is not None:
+                refine_rows.append(fit_filter_row)
             if len(train) < max(10, cfg.min_group_size):
                 refine_rows.append({"target": target, "step": "fit", "status": "skipped_min_group_size", "n": len(train)})
                 continue

{supermodelingfactory-0.3.5 → supermodelingfactory-0.3.6}/Modeling_Tool/__init__.py

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 __author__ = "Jingkai Sun"
-__version__ = "0.3.5"
+__version__ = "0.3.6"
 
 # Core module - base data structures
 from .Core import (

{supermodelingfactory-0.3.5 → supermodelingfactory-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SuperModelingFactory
-Version: 0.3.5
+Version: 0.3.6
 Summary: Credit risk modeling factory: WOE binning, scorecards, LightGBM, Excel reporting.
 Home-page: https://github.com/Kyle-J-Sun/SuperModelingFactory
 Author: Kyle Sun
@@ -114,7 +114,10 @@ SuperModelingFactory/
 │   ├── Feature/            #   特征分析：分布偏移、PSI、相关性过滤
 │   ├── Model/              #   模型训练：LR、LightGBM、XGBoost、变量选择
 │   ├── Eval/               #   模型评估：Gains 表、ROC/KS、性能汇总
-│   └── Sample/             #   样本管理：切分、分层、拒绝推断、分布适配
+│   ├── Sample/             #   样本管理：切分、分层、拒绝推断、分布适配
+│   ├── Explainability/     #   模型解释：SHAP、LIME、PDP、ICE、ALE、Owen
+│   ├── Pipeline/           #   一键流水线：特征验收、信用建模、拒绝推断等
+│   └── UAT/                #   线上线下分数一致性校验
 ├── ExcelMaster/            # Excel 报告引擎
 │   ├── ExcelFormatTool.py  #   格式定义（50+ 预设单元格格式）
 │   ├── ExcelMaster.py      #   核心引擎（光标流式写入、图表、条件格式）
@@ -262,9 +265,9 @@ em.close_workbook()
 
 ## 版本
 
-- **Version**: 0.3.5
+- **Version**: 0.3.6
 - **Author**: Jingkai Sun
 
 ## 许可证
 
-内部项目，仅供团队使用。
+本项目采用 **Business Source License 1.1**（Change Date **2030-06-24**）。详见文首 [许可证](#许可证) 一节与 [LICENSE](LICENSE) 全文。

{supermodelingfactory-0.3.5 → supermodelingfactory-0.3.6}/README.md

@@ -57,7 +57,10 @@ SuperModelingFactory/
 │   ├── Feature/            #   特征分析：分布偏移、PSI、相关性过滤
 │   ├── Model/              #   模型训练：LR、LightGBM、XGBoost、变量选择
 │   ├── Eval/               #   模型评估：Gains 表、ROC/KS、性能汇总
-│   └── Sample/             #   样本管理：切分、分层、拒绝推断、分布适配
+│   ├── Sample/             #   样本管理：切分、分层、拒绝推断、分布适配
+│   ├── Explainability/     #   模型解释：SHAP、LIME、PDP、ICE、ALE、Owen
+│   ├── Pipeline/           #   一键流水线：特征验收、信用建模、拒绝推断等
+│   └── UAT/                #   线上线下分数一致性校验
 ├── ExcelMaster/            # Excel 报告引擎
 │   ├── ExcelFormatTool.py  #   格式定义（50+ 预设单元格格式）
 │   ├── ExcelMaster.py      #   核心引擎（光标流式写入、图表、条件格式）
@@ -205,9 +208,9 @@ em.close_workbook()
 
 ## 版本
 
-- **Version**: 0.3.5
+- **Version**: 0.3.6
 - **Author**: Jingkai Sun
 
 ## 许可证
 
-内部项目，仅供团队使用。
+本项目采用 **Business Source License 1.1**（Change Date **2030-06-24**）。详见文首 [许可证](#许可证) 一节与 [LICENSE](LICENSE) 全文。

{supermodelingfactory-0.3.5 → supermodelingfactory-0.3.6}/SuperModelingFactory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SuperModelingFactory
-Version: 0.3.5
+Version: 0.3.6
 Summary: Credit risk modeling factory: WOE binning, scorecards, LightGBM, Excel reporting.
 Home-page: https://github.com/Kyle-J-Sun/SuperModelingFactory
 Author: Kyle Sun
@@ -114,7 +114,10 @@ SuperModelingFactory/
 │   ├── Feature/            #   特征分析：分布偏移、PSI、相关性过滤
 │   ├── Model/              #   模型训练：LR、LightGBM、XGBoost、变量选择
 │   ├── Eval/               #   模型评估：Gains 表、ROC/KS、性能汇总
-│   └── Sample/             #   样本管理：切分、分层、拒绝推断、分布适配
+│   ├── Sample/             #   样本管理：切分、分层、拒绝推断、分布适配
+│   ├── Explainability/     #   模型解释：SHAP、LIME、PDP、ICE、ALE、Owen
+│   ├── Pipeline/           #   一键流水线：特征验收、信用建模、拒绝推断等
+│   └── UAT/                #   线上线下分数一致性校验
 ├── ExcelMaster/            # Excel 报告引擎
 │   ├── ExcelFormatTool.py  #   格式定义（50+ 预设单元格格式）
 │   ├── ExcelMaster.py      #   核心引擎（光标流式写入、图表、条件格式）
@@ -262,9 +265,9 @@ em.close_workbook()
 
 ## 版本
 
-- **Version**: 0.3.5
+- **Version**: 0.3.6
 - **Author**: Jingkai Sun
 
 ## 许可证
 
-内部项目，仅供团队使用。
+本项目采用 **Business Source License 1.1**（Change Date **2030-06-24**）。详见文首 [许可证](#许可证) 一节与 [LICENSE](LICENSE) 全文。

{supermodelingfactory-0.3.5 → supermodelingfactory-0.3.6}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "SuperModelingFactory"
-version = "0.3.5"
+version = "0.3.6"
 description = "Credit risk modeling factory: WOE binning, scorecards, LightGBM, Excel reporting."
 readme = "README.md"
 requires-python = ">=3.10"

{supermodelingfactory-0.3.5 → supermodelingfactory-0.3.6}/setup.py

@@ -15,7 +15,7 @@ def _read(path: str) -> str:
 
 setup(
     name="SuperModelingFactory",
-    version=os.environ.get("SMF_VERSION", "0.3.5"),
+    version=os.environ.get("SMF_VERSION", "0.3.6"),
     description="Credit risk modeling factory: WOE binning, scorecards, LightGBM, Excel reporting.",
     long_description=_read("README.md"),
     long_description_content_type="text/markdown",