tanml 0.1.6__py3-none-any.whl

tanml/engine/segmentation_agent.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import os
+import joblib
+import importlib
+from tanml.utils.sas_loader import SASLogisticModel
+from tanml.utils.r_loader import RLogisticModel
+from tanml.engine.validation_agent import SegmentValidator
+from tanml.utils.data_loader import load_dataframe
+
+
+def handle_segmentation(segment_config, rule_config, args=None, report_output=None):
+    global_raw_path = rule_config.get("paths", {}).get("raw_data")
+    segment_col = segment_config.get("column")  # ✅ only required for Scenario C
+    report_template = report_output  # e.g., "reports/report_{segment}.docx"
+
+    print("🔍 Detected segmentation setup in rules.yaml. Running each segment run separately...")
+
+    for name, run_cfg in segment_config["runs"].items():
+        print(f"\n🔹 Validating segment: {name}")
+        model_path = run_cfg["model"]
+
+        # CASE 1: Retrain model from cleaned data (model: train)
+        if isinstance(model_path, str) and model_path.lower() == "train":
+            print(f"🛠️ Retraining model from cleaned data for segment: {name}")
+
+            if "cleaned" in run_cfg:
+                cleaned_df_run = load_dataframe(run_cfg["cleaned"])
+            else:
+                full_cleaned = load_dataframe(rule_config["paths"]["cleaned_data"])
+                if segment_col:
+                    cleaned_df_run = full_cleaned[full_cleaned[segment_col] == name]
+                else:
+                    raise ValueError("Missing segment column for slicing cleaned data.")
+
+            X = cleaned_df_run[rule_config["model"]["features"]]
+            y = cleaned_df_run[rule_config["model"]["target"]]
+
+            model_source = rule_config.get("model_source", {})
+            model_type = model_source.get("type")
+            model_module = model_source.get("module")
+            model_params = model_source.get("hyperparameters", {})
+
+            if not model_type or not model_module:
+                raise ValueError("❌ 'model_source.type' and 'model_source.module' must be defined for retraining.")
+
+            model_class = getattr(importlib.import_module(model_module), model_type)
+            model = model_class(**model_params)
+            print(f"📦 Using model: {model}")
+
+            model.fit(X, y)
+            print(f"✅ Retrained {model_type} for segment '{name}'")
+
+        elif isinstance(model_path, str) and "r_logistic" in model_path.lower():
+            model = RLogisticModel(model_path)
+
+        elif isinstance(model_path, str) and model_path.endswith(".pkl"):
+            model = joblib.load(model_path)
+
+        elif isinstance(model_path, str) and model_path.endswith(".csv"):
+            base = os.path.splitext(model_path)[0]
+            model = SASLogisticModel(
+                coeffs_path=model_path,
+                intercept_path=base + "_intercept.txt",
+                feature_order_path=base + "_features.txt"
+            )
+
+        else:
+            raise ValueError(f"❌ Unsupported model format for segment '{name}': {model_path}")
+
+        # Load and optionally slice raw data
+        raw_df_run = None
+        if global_raw_path and os.path.exists(global_raw_path):
+            full_raw = load_dataframe(global_raw_path)
+            if segment_col:
+                raw_df_run = full_raw[full_raw[segment_col] == name]
+            else:
+                raw_df_run = full_raw
+
+        print(f"[DEBUG] raw_df_run for {name}: {type(raw_df_run)}, rows = {len(raw_df_run) if raw_df_run is not None else 'None'}")
+
+        # Load cleaned data
+        if "cleaned" in run_cfg:
+            cleaned_df_run = load_dataframe(run_cfg["cleaned"])
+        else:
+            full_cleaned = load_dataframe(rule_config["paths"]["cleaned_data"])
+            if segment_col:
+                cleaned_df_run = full_cleaned[full_cleaned[segment_col] == name]
+            else:
+                cleaned_df_run = full_cleaned
+
+        # Format output path
+        report_base = report_template.format(segment=name)
+
+        # Run validation
+        validator = SegmentValidator(
+            segment_column=segment_col,
+            segment_values=[name],
+            model=model,
+            raw_df=raw_df_run,
+            cleaned_df=cleaned_df_run,
+            target_col=rule_config.get("model", {}).get("target"),
+            config=rule_config,
+            segment_name=name,
+            report_base=report_base
+        )
+        results = validator.run()
+
+        # Extract report path from SegmentValidator result
+        report_base_path = report_template.format(segment=name)
+        report_path = os.path.join(report_base_path, f"report_{name}.docx")
+
+        print(f"📄 Report saved: {report_path}")
+        print(f"✅ Segment '{name}' validated.")
+
+
+    print("✅ All segment runs completed.")
+    return True

tanml/engine/validation_agent.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+from importlib.resources import files 
+from datetime import datetime
+import tzlocal
+import json
+from pathlib import Path
+
+from tanml.engine.core_engine_agent import ValidationEngine
+from tanml.report.report_builder import ReportBuilder
+from tanml.engine.check_agent_registry import CHECK_RUNNER_REGISTRY
+
+
+class SegmentValidator:
+    def __init__(
+        self,
+        model,
+        raw_df,
+        cleaned_df,
+        config,
+        target_col=None,
+        segment_column=None,
+        segment_values=None,
+        segment_name=None,
+        report_base="reports"
+    ):
+        self.model = model
+        self.raw_df = raw_df
+        self.cleaned_df = cleaned_df
+        self.config = config
+        self.target_col = target_col
+        self.segment_column = segment_column
+        self.segment_values = segment_values
+        self.segment_name = segment_name
+        self.report_base = report_base
+
+    def run(self):
+        if self.segment_name:
+            return self._run_single(self.cleaned_df, self.segment_name)
+
+        if not self.segment_column:
+            raise ValueError("Segmentation column not specified in rules.yaml")
+
+        results = {}
+        for segment in self.segment_values:
+            segment_df = self.cleaned_df[self.cleaned_df[self.segment_column] == segment]
+            print(f"🔹 Running validation for segment value: {segment}")
+            result = self._run_single(segment_df, segment)
+            results[segment] = result
+
+        return results
+
+    def _run_single(self, segment_df, segment_name):
+        if self.target_col is None or self.target_col not in segment_df.columns:
+            raise ValueError(f"❌ Target column '{self.target_col}' missing in cleaned data for segment '{segment_name}'")
+
+        y = segment_df[self.target_col]
+        cols_to_drop = [c for c in (self.target_col, self.segment_column) if c in segment_df.columns]
+        X = segment_df.drop(columns=cols_to_drop)
+
+        # Pass raw_df to ValidationEngine so CleaningReproCheck works
+        engine = ValidationEngine(self.model, X, X, y, y, self.config, segment_df, self.raw_df)
+        results = engine.run_all_checks()
+
+        local_tz = tzlocal.get_localzone()
+        now = datetime.now(local_tz)
+        results["validation_date"] = now.strftime("%Y-%m-%d %H:%M:%S %Z (UTC%z)")
+        results["model_path"] = self.model.__class__.__name__
+        results["validated_by"] = "TanML Automated Validator"
+        results["rules"] = self.config
+
+        report_base_formatted = self.report_base.format(segment=segment_name) if "{segment}" in self.report_base else self.report_base
+        output_dir = Path(report_base_formatted)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        tpl_cfg = self.config.get("output", {}).get("template_path")     # may be None
+        template_path = (
+            Path(tpl_cfg).expanduser() if tpl_cfg
+            else files("tanml.report.templates").joinpath("report_template.docx")
+        )
+
+        output_path = output_dir / f"report_{segment_name}.docx"
+
+        builder = ReportBuilder(results, template_path, output_path)
+        builder.build()
+
+        print(f"📄 Report saved for segment '{segment_name}': {output_path}")
+        print(json.dumps(results, indent=2, default=str))
+        return results
+
+
+__all__ = ["SegmentValidator", "CHECK_RUNNER_REGISTRY"]

tanml/report/report_builder.py

@@ -0,0 +1,230 @@
+# tanml/report/report_builder.py
+from docxtpl import DocxTemplate, InlineImage
+from docx.shared import Inches, Mm
+from docx import Document
+from pathlib import Path
+import os, imgkit, copy as pycopy
+from importlib.resources import files
+
+TMP_DIR = Path(__file__).resolve().parents[1] / "tmp_report_assets"
+TMP_DIR.mkdir(exist_ok=True)
+
+
+class AttrDict(dict):
+    def __getattr__(self, item):
+        try:
+            return self[item]
+        except KeyError:
+            raise AttributeError(item)
+
+
+class ReportBuilder:
+    """Build a Word report from validation results."""
+
+    def __init__(self, results, template_path, output_path):
+        self.results = results
+        self.template_path = template_path or files("tanml.report.templates").joinpath("report_template.docx")
+
+        self.output_path = output_path
+
+        corr = results.get("CorrelationCheck", {})
+        self.corr_heatmap_path = corr.get("heatmap_path")
+        self.corr_pearson_path = corr.get("pearson_csv", "N/A")
+        self.corr_spearman_path = corr.get("spearman_csv", "N/A")
+
+    def _grab(self, name, default=None):
+        return (
+            self.results.get(name)
+            or self.results.get("check_results", {}).get(name)
+            or default
+        )
+
+    def build(self):
+        doc = DocxTemplate(str(self.template_path))
+
+
+        # Ensure RuleEngineCheck exists so template never crashes
+        self.results.setdefault(
+            "RuleEngineCheck", AttrDict({"rules": {}, "overall_pass": True})
+        )
+
+        # Jinja context
+        ctx = pycopy.deepcopy(self.results)
+        ctx.update(self.results.get("check_results", {}))  # 1st-level flatten
+
+        for k, v in list(ctx.items()):
+            if isinstance(v, dict) and k in v and len(v) == 1:
+                ctx[k] = v[k]
+
+        for k, note in [
+            ("RawDataCheck", "Raw-data check skipped"),
+            ("CleaningReproCheck", "Cleaning-repro check skipped"),
+        ]:
+            ctx.setdefault(k, AttrDict({"note": note}))
+
+        if "ModelMetaCheck" not in ctx or "model_type" not in ctx["ModelMetaCheck"]:
+            meta_fields = [
+                "model_type",
+                "model_class",
+                "module",
+                "n_features",
+                "feature_names",
+                "n_train_rows",
+                "target_balance",
+                "hyperparam_table",
+                "attributes",
+            ]
+            meta = {f: self.results.get(f) for f in meta_fields if self.results.get(f) is not None}
+            ctx["ModelMetaCheck"] = AttrDict(meta or {"note": "Model metadata not available"})
+
+        # SHAP image
+        shap_path = self._grab("SHAPCheck", {}).get("shap_plot_path")
+        ctx["shap_plot"] = (
+            InlineImage(doc, shap_path, width=Inches(5))
+            if shap_path and os.path.exists(shap_path)
+            else "SHAP plot not available"
+        )
+
+        #  EDA
+        eda = self._grab("EDACheck", {})
+        ctx["eda_summary_path"] = eda.get("summary_stats", "N/A")
+        ctx["eda_missing_path"] = eda.get("missing_values", "N/A")
+        ctx["eda_images"] = [
+            InlineImage(doc, os.path.join("reports/eda", fn), width=Inches(4.5))
+            if os.path.exists(os.path.join("reports/eda", fn))
+            else f"Missing: {fn}"
+            for fn in eda.get("visualizations", [])
+        ]
+
+        # Correlation visuals
+        if self.corr_heatmap_path and os.path.exists(self.corr_heatmap_path):
+            ctx["correlation_heatmap"] = InlineImage(
+                doc, self.corr_heatmap_path, width=Inches(5)
+            )
+        else:
+            ctx["correlation_heatmap"] = "Heatmap not available"
+        ctx["correlation_pearson_path"] = self.corr_pearson_path
+        ctx["correlation_spearman_path"] = self.corr_spearman_path
+
+        # Performance
+        perf = self._grab("PerformanceCheck", {})
+        if not perf:
+            perf = {
+                "accuracy": "N/A",
+                "auc": "N/A",
+                "ks": "N/A",
+                "f1": "N/A",
+                "confusion_matrix": [],
+            }
+        ctx.setdefault("check_results", {})["PerformanceCheck"] = perf
+        ctx["PerformanceCheck"] = perf
+
+        # Logistic summary image
+        if "LogisticStatsCheck_obj" in self.results:
+            try:
+                add_logit_summary_image(
+                    doc, self.results["LogisticStatsCheck_obj"], ctx, "LogitSummaryImg"
+                )
+            except Exception as e:
+                print("⚠️  logistic summary image failed:", e)
+
+        # VIF
+        vif = self._grab("VIFCheck", {})
+        ctx["VIFCheck"] = AttrDict(
+            vif
+            if isinstance(vif, dict) and "vif_table" in vif
+            else {"vif_table": [], "high_vif_features": [], "error": "Invalid VIFCheck"}
+        )
+
+        # Stress / cluster
+        if isinstance(self.results.get("StressTestCheck"), list):
+            ctx["StressTestCheck"] = {"table": self.results["StressTestCheck"]}
+
+        cluster_rows = self._grab("InputClusterCheck", {}).get("cluster_table", [])
+        ctx.setdefault("InputClusterCheck", {})["cluster_table"] = [
+            {
+                "Cluster": r.get("Cluster") or r.get("cluster"),
+                "Count": r.get("Count") or r.get("count"),
+                "Percent": r.get("Percent") or r.get("percent"),
+            }
+            for r in cluster_rows
+            if isinstance(r, dict)
+        ]
+        plot_path = self._grab("InputClusterCheck", {}).get("cluster_plot_img")
+        ctx["InputClusterCheck"]["cluster_plot_img"] = (
+            InlineImage(doc, plot_path, width=Inches(5))
+            if plot_path and os.path.exists(plot_path)
+            else "Plot not available"
+        )
+
+        # Render DOCX template
+        print("🟢 ctx top-level keys:", list(ctx.keys()))
+        print("🔍 RawDataCheck value:", ctx.get("RawDataCheck"))
+
+        doc.render(ctx)
+        doc.save(self.output_path)
+
+        # Auto-insert tables after anchors
+        tbl_specs = [
+            {
+                "anchor": "Stress Testing Results",
+                "headers": [
+                    "feature",
+                    "perturbation",
+                    "accuracy",
+                    "auc",
+                    "delta_accuracy",
+                    "delta_auc",
+                ],
+                "rows": ctx.get("StressTestCheck", {}).get("table", []),
+            },
+            {
+                "anchor": "Cluster Summary Table:",
+                "headers": ["Cluster", "Count", "Percent"],
+                "rows": ctx.get("InputClusterCheck", {}).get("cluster_table", []),
+            },
+            {
+                "anchor": "Variance Inflation Factor (VIF) Check",
+                "headers": ["Feature", "VIF"],
+                "rows": ctx.get("VIFCheck", {}).get("vif_table", []),
+            },
+        ]
+
+        docx = Document(self.output_path)
+        for spec in tbl_specs:
+            if spec["rows"]:
+                tbl = build_table(docx, spec["headers"], spec["rows"])
+                insert_after(docx, spec["anchor"], tbl)
+                print(f"✅ added table after «{spec['anchor']}»")
+        docx.save(self.output_path)
+
+
+def build_table(doc, headers, rows):
+    tbl = doc.add_table(rows=1, cols=len(headers))
+    tbl.style = "Table Grid"
+    for i, h in enumerate(headers):
+        tbl.rows[0].cells[i].text = str(h)
+    for r in rows:
+        vals = [r.get(h, "") for h in headers] if isinstance(r, dict) else list(r)
+        vals += [""] * (len(headers) - len(vals))
+        row = tbl.add_row().cells
+        for i, v in enumerate(vals):
+            row[i].text = str(v)
+    return tbl
+
+
+def insert_after(doc, anchor, tbl):
+    for p in doc.paragraphs:
+        if anchor.lower() in p.text.lower():
+            parent = p._p.getparent()
+            parent.insert(parent.index(p._p) + 1, tbl._tbl)
+            return
+    print(f"⚠️ anchor «{anchor}» not found")
+
+
+def add_logit_summary_image(tpl_doc, sm_results, ctx, key):
+    html = TMP_DIR / "logit_summary.html"
+    html.write_text(sm_results.summary().as_html(), encoding="utf8")
+    png = TMP_DIR / "logit_summary.png"
+    imgkit.from_file(str(html), str(png), options={"quiet": ""})
+    ctx[key] = InlineImage(tpl_doc, str(png), width=Mm(160))

tanml/utils/data_loader.py

@@ -0,0 +1,17 @@
+import os
+import pandas as pd
+
+def load_dataframe(filepath):
+    ext = os.path.splitext(filepath)[1].lower()
+    if ext == ".csv":
+        return pd.read_csv(filepath)
+    elif ext in [".xls", ".xlsx"]:
+        return pd.read_excel(filepath)
+    elif ext == ".parquet":
+        return pd.read_parquet(filepath)
+    elif ext == ".sas7bdat":
+        return pd.read_sas(filepath)
+    elif ext in [".txt", ".tsv"]:
+        return pd.read_csv(filepath, sep="\t")
+    else:
+        raise ValueError(f"Unsupported file format: {ext}")

tanml/utils/model_loader.py

@@ -0,0 +1,35 @@
+# tanml/utils/model_loader.py
+
+import os
+import joblib
+from tanml.utils.sas_loader import SASLogisticModel
+from tanml.utils.r_loader import RLogisticModel
+
+def load_model(model_path):
+    """
+    Load a model from path. Supports:
+    - sklearn/xgboost .pkl
+    - SAS .csv with _intercept.txt and _features.txt
+    - R exported logistic CSV
+    """
+    if not model_path:
+        raise ValueError("❌ No model path provided.")
+
+    if "r_logistic" in model_path.lower():
+        print("✅ Detected R Logistic Regression model")
+        return RLogisticModel(model_path)
+
+    elif model_path.endswith(".pkl"):
+        print(f"✅ Loading sklearn/XGB model from {model_path}")
+        return joblib.load(model_path)
+
+    elif model_path.endswith(".csv"):
+        base = os.path.splitext(model_path)[0]
+        return SASLogisticModel(
+            coeffs_path=model_path,
+            intercept_path=base + "_intercept.txt",
+            feature_order_path=base + "_features.txt"
+        )
+
+    else:
+        raise ValueError("❌ Unsupported model format. Use .pkl, .csv, or R model CSV")

tanml/utils/r_loader.py

@@ -0,0 +1,30 @@
+import pandas as pd
+import numpy as np
+
+class RLogisticModel:
+    """
+    Wrapper for logistic regression models exported from R.
+    Assumes CSV with columns: ID, y_true, y_pred_proba
+    """
+
+    def __init__(self, model_path: str):
+        self.model_path = model_path
+        self.df = pd.read_csv(model_path)
+
+        # Check required columns exist
+        expected_cols = {'y_true', 'y_pred_proba'}
+        if not expected_cols.issubset(set(self.df.columns)):
+            raise ValueError(f"R model CSV must contain columns: {expected_cols}")
+
+        self.y_true = self.df['y_true'].values
+        self.y_pred_proba = self.df['y_pred_proba'].values
+
+    def predict_proba(self, X=None):
+        """
+        Mimics sklearn’s predict_proba format: n_samples x 2
+        """
+        proba = self.y_pred_proba.reshape(-1, 1)
+        return np.hstack([1 - proba, proba])
+
+    def get_true_labels(self):
+        return self.y_true

tanml/utils/sas_loader.py

@@ -0,0 +1,50 @@
+# File: tanml/utils/sas_loader.py
+
+import pandas as pd
+import numpy as np         
+
+
+class SASLogisticModel:
+    def __init__(self, coeffs_path, intercept_path, feature_order_path):
+        self.coeffs_path = coeffs_path
+        self.intercept_path = intercept_path
+        self.feature_order_path = feature_order_path
+
+        self.coefficients = self._load_coefficients()
+        self.intercept = self._load_intercept()
+        self.feature_order = self._load_feature_order()
+
+    def _load_coefficients(self):
+        return pd.read_csv(self.coeffs_path, index_col=0).squeeze("columns")
+
+    def _load_intercept(self):
+        with open(self.intercept_path) as f:
+            return float(f.read().strip())
+
+    def _load_feature_order(self):
+        with open(self.feature_order_path) as f:
+            return [line.strip() for line in f.readlines()]
+
+    def predict_proba(self, X):
+        """
+        Return a NumPy array shaped (n_samples, 2) like sklearn:
+        [:, 0] = P(class 0), [:, 1] = P(class 1)
+        """
+        X = X[self.feature_order]
+        logits = X.dot(self.coefficients) + self.intercept
+
+        # numeric stability clamp
+        logits = logits.clip(-700, 700)
+
+        proba_1 = 1 / (1 + np.exp(-logits))
+        proba_0 = 1 - proba_1
+        return np.vstack([proba_0, proba_1]).T  # shape (n, 2)
+
+    def predict(self, X):
+        """
+        Return class labels (0/1) based on 0.5 threshold.
+        Works with the NumPy array returned by predict_proba().
+        """
+        proba_1 = self.predict_proba(X)[:, 1]   # probability of class 1
+        return (proba_1 >= 0.5).astype(int)
+

tanml/utils/yaml_generator.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+import shutil
+
+def generate_rules_yaml(
+    scenario: str = "A",
+    dest_path: str = "rules.yaml",
+    overwrite: bool = False
+):
+
+    scenario = scenario.upper()
+    template_map = {
+        "A": "rules_one_model_one_dataset.yaml",
+        "B": "rules_multiple_models_datasets.yaml",
+        "C": "rules_one_dataset_segment_column.yaml"
+    }
+
+    if scenario not in template_map:
+        raise ValueError("Invalid scenario. Must be 'A', 'B', or 'C'.")
+
+    src = Path(__file__).parent.parent / "config_templates" / template_map[scenario]
+    if not src.exists():
+        raise FileNotFoundError(f"Template not found at {src}")
+
+    dst = Path(dest_path)
+    if dst.exists() and not overwrite:
+        raise FileExistsError(f"{dst} already exists. Use --overwrite to replace it.")
+
+    if dst.parent and not dst.parent.exists():
+        dst.parent.mkdir(parents=True, exist_ok=True)
+
+    shutil.copyfile(src, dst)
+
+    print(f"✅ Created: {dst.resolve()} for Scenario {scenario}")
+    print("👉 Now edit this YAML to fill in your model, data, and feature details.")

tanml/utils/yaml_loader.py

@@ -0,0 +1,5 @@
+import yaml
+
+def load_yaml_config(path):
+    with open(path, "r") as f:
+        return yaml.safe_load(f)