tanml 0.1.6__py3-none-any.whl

tanml/config_templates/rules_multiple_models_datasets.yaml

@@ -0,0 +1,144 @@
+# ============================================================
+# TanML Validation Configuration File: Scenario B
+# ------------------------------------------------------------
+# 🧪 Scenario: One model and one cleaned dataset per segment
+#
+# ✅ Required:
+#   - Define segment-wise cleaned data and model path (or retrain)
+#   - Choose ONE model source strategy (Option A or Option B)
+#   - Set input features and target column
+#   - Optional: provide global raw data
+#   - Adjust thresholds and check options as needed
+# ============================================================
+
+# ------------------------------------------
+# REQUIRED: Model Input Schema
+# ------------------------------------------
+model:
+  features:
+    - feature_0    # 👉 replace with actual feature names used in all segment models
+    - feature_1    # 👉 remove or add more lines if needed
+    - feature_2
+  target: default_flag   # 👉 replace with your actual target column
+
+# ------------------------------------------
+# OPTIONAL: Raw Data Path
+# ------------------------------------------
+paths:
+  raw_data: data/raw.csv                # 👉 optional – provide full path if you have original raw dataset otherwise use null
+
+output:
+  report_path_template: /absolute/path/to/output/{segment} # 👉 Output path template – {segment} will be replaced dynamically, it is folder path
+
+# ------------------------------------------
+# ✅ OPTION A — Pretrained Model per Segment (.pkl)
+# ------------------------------------------
+# Use this option when each segment has its own trained model and cleaned dataset.
+# You must provide:
+#   - model: path to the pretrained `.pkl` file
+#   - cleaned: path to the cleaned CSV used for that segment
+#
+# 👉 Comment out the OPTION B block below if using this
+# ------------------------------------------
+segment:
+  runs:
+    segment_A:                           # 👉 rename (e.g., high_risk, bronze, tier_1)
+      model: models/logistic/model_b_segment1.pkl
+      cleaned: data/scenario_b_segment1.csv
+
+    segment_B:
+      model: models/logistic/model_b_segment1.pkl
+      cleaned: data/scenario_b_segment2.csv
+
+# ------------------------------------------
+# 🔁 OPTION B — Retrain Model from Cleaned Data (Per Segment)
+# ------------------------------------------
+# Use this when you want to retrain a model for each segment
+# using the corresponding cleaned dataset and shared model config.
+#
+# 👉 If using this, comment out OPTION A (i.e., segment.runs[].model lines)
+# 👉 Each segment must still have its own cleaned dataset
+# ------------------------------------------
+
+# segment:
+#   runs:
+#     segment_A:
+#       cleaned: data/cleaned_a.csv
+#     segment_B:
+#       cleaned: data/cleaned_b.csv
+
+# ------------------------------------------
+# MODEL SOURCE CONFIG
+# ------------------------------------------
+# This tells TanML how to load or build the model(s) for each segment.
+#
+# 👉 If using pretrained models (Option A): set `from_pickle: true`
+# 👉 If retraining per segment (Option B): set `from_pickle: false`
+# ------------------------------------------
+model_source:
+  from_pickle: true     # 👉 change to false if using retraining (Option B)
+  type: LogisticRegression
+  module: sklearn.linear_model
+  hyperparameters:
+    penalty: "l2"
+    solver: "liblinear"
+    random_state: 42
+    class_weight: "balanced"
+    max_iter: 100
+
+# ------------------------------------------
+# PERFORMANCE THRESHOLDS
+# ------------------------------------------
+auc_roc:
+  min: 0.60
+
+f1:
+  min: 0.60
+
+ks:
+  min: 0.20
+
+# ------------------------------------------
+# VALIDATION CHECKS
+# ------------------------------------------
+
+EDACheck:
+  enabled: true
+  max_plots: -1             # -1 = all numeric; or set number of columns
+
+correlation:
+  enabled: true
+
+VIFCheck:
+  enabled: true
+  
+raw_data_check:
+  enabled: true
+
+model_meta:
+  enabled: true
+
+# ------------------------------------------
+# STRESS TESTING (Robustness Check)
+# ------------------------------------------
+StressTestCheck:
+  enabled: true
+  epsilon: 0.01             # ➜ 1% noise
+  perturb_fraction: 0.2     # ➜ 20% of rows
+
+# ------------------------------------------
+# INPUT CLUSTER COVERAGE
+# ------------------------------------------
+InputClusterCoverageCheck:
+  enabled: true
+  n_clusters: 5             # ➜ fixed clusters for coverage bar chart
+  max_k: 10                 # ➜ elbow method search (if needed)
+
+# ------------------------------------------
+# EXPLAINABILITY
+# ------------------------------------------
+explainability:
+  shap:
+    enabled: true
+    background_sample_size: 100   # ➜ SHAP explainer training background
+    test_sample_size: 200         # ➜ test rows to explain

tanml/config_templates/rules_one_dataset_segment_column.yaml

@@ -0,0 +1,140 @@
+# ============================================================
+# TanML Validation Configuration File: Scenario C
+# ------------------------------------------------------------
+# 🧪 Scenario: One dataset with a segment column, one model per segment
+#
+# ✅ Required:
+#   - Provide cleaned data (includes all segments)
+#   - Define the segment column used to split the data
+#   - Choose ONE model source strategy (Option A or Option B)
+#   - Set input features and target column
+#   - Optional: provide global raw data
+#   - Adjust thresholds and check options as needed
+# ============================================================
+
+# ------------------------------------------
+# REQUIRED: Model Input Schema
+# ------------------------------------------
+model:
+  features:
+    - feature_0    # 👉 replace with actual feature names used across all segment models
+    - feature_1
+    - feature_2
+  target: default_flag   # 👉 replace with your actual target column
+
+# ------------------------------------------
+# REQUIRED: File Paths
+# ------------------------------------------
+paths:
+  cleaned_data: data/cleaned.csv          # 👉 path to full cleaned dataset (includes all segments)
+  raw_data: data/raw.csv                  # 👉 optional — use null if raw data not available
+
+# ------------------------------------------
+# OUTPUT CONFIGURATION
+# ------------------------------------------
+# Path template where validation reports will be saved.
+# 👉 Use `{segment}` as a placeholder for the segment name.
+# ------------------------------------------
+output:
+  report_path_template: reports/scenario_c/{segment}_report.docx  # 👉 customize this path as needed
+
+# ------------------------------------------
+# ✅ OPTION A — Pretrained Models per Segment (.pkl)
+# ------------------------------------------
+# Provide one model per segment (already trained)
+# This is the default option.
+# 👉 Comment out the OPTION B block below if using this
+# ------------------------------------------
+segment:
+  column: customer_segment                # 👉 column used to split segments
+
+  runs:
+    segment_A:
+      model: models/logistic/model_a.pkl
+    segment_B:
+      model: models/logistic/model_b.pkl
+
+# ------------------------------------------
+# 🔁 OPTION B — Retrain Models per Segment from Cleaned Data
+# ------------------------------------------
+# Use this if you want TanML to retrain a model for each segment
+# from the common cleaned dataset.
+# 👉 Comment out the OPTION A block above if using this
+# 👉 `segment.runs` must list segment values (no model paths needed)
+# ------------------------------------------
+# segment:
+#   column: customer_segment
+#   runs:
+#     segment_A: {}
+#     segment_B: {}
+
+# ------------------------------------------
+# MODEL SOURCE CONFIGURATION
+# ------------------------------------------
+# 👉 If using pretrained models: set `from_pickle: true`
+# 👉 If retraining per segment: set `from_pickle: false`
+# ------------------------------------------
+model_source:
+  from_pickle: true
+  type: LogisticRegression
+  module: sklearn.linear_model
+  hyperparameters:
+    penalty: "l2"
+    solver: "liblinear"
+    random_state: 42
+    class_weight: "balanced"
+    max_iter: 100
+
+# ------------------------------------------
+# PERFORMANCE THRESHOLDS
+# ------------------------------------------
+auc_roc:
+  min: 0.60
+f1:
+  min: 0.60
+ks:
+  min: 0.20
+
+# ------------------------------------------
+# VALIDATION CHECKS
+# ------------------------------------------
+EDACheck:
+  enabled: true
+  max_plots: -1
+
+correlation:
+  enabled: true
+
+VIFCheck:
+  enabled: true
+
+raw_data_check:
+  enabled: true
+
+model_meta:
+  enabled: true
+
+# ------------------------------------------
+# STRESS TESTING (Robustness Check)
+# ------------------------------------------
+StressTestCheck:
+  enabled: true
+  epsilon: 0.01
+  perturb_fraction: 0.2
+
+# ------------------------------------------
+# INPUT CLUSTER COVERAGE
+# ------------------------------------------
+InputClusterCoverageCheck:
+  enabled: true
+  n_clusters: 5
+  max_k: 10
+
+# ------------------------------------------
+# EXPLAINABILITY
+# ------------------------------------------
+explainability:
+  shap:
+    enabled: true
+    background_sample_size: 100
+    test_sample_size: 200

tanml/config_templates/rules_one_model_one_dataset.yaml

@@ -0,0 +1,143 @@
+# ============================================================
+# TanML Validation Configuration File: Scenario A
+# ------------------------------------------------------------
+# 🧪 Scenario: One model, one cleaned dataset (no segmentation)
+#
+# ✅ Required:
+#   - Choose ONE set of paths (Option A or Option B)
+#   - Choose ONE model source block (Option A or Option B)
+#   - Fill in your feature names and target column
+#   - Adjust any thresholds or check options as needed
+# ============================================================
+
+
+# ------------------------------------------
+# REQUIRED: Model Input Schema
+# ------------------------------------------
+model:
+  features:
+    - feature_0     # 👉 replace with actual feature names used in your model
+    - feature_1
+    - feature_2
+    - feature_3
+    - feature_4
+  target: default_flag             # 👉 replace with actual target column
+
+# ------------------------------------------
+# OUTPUT: Report Path
+# ------------------------------------------
+output:
+  report_path: /mnt/c/Users/you/Desktop/tanml_output/scenario_a_report.docx  # 👉 customize as needed
+
+
+# ------------------------------------------
+# ✅ OPTION A — Use a Pretrained Model (.pkl)
+# ------------------------------------------
+# Use this option when you already have a trained model saved as a `.pkl` file.
+# You must provide the path to:
+#   - The cleaned dataset used during training
+#   - The raw dataset (optional, but recommended)
+#   - The trained model file via `paths.model`
+#
+# Be sure to:
+#   - Keep `from_pickle: true` in `model_source`
+#   - Match the `path` in `model_source` and `paths.model`
+#   - Comment out OPTION B block if using this
+# ------------------------------------------
+paths:
+  raw_data: /mnt/c/Users/your_name/Desktop/data/raw.csv      # 👉 optional — use null if raw data is not available
+  cleaned_data: data/cleaned_a.csv
+  model: models/logistic/model_a.pkl
+
+model_source:
+  from_pickle: true
+  
+
+# ------------------------------------------
+# 🔁 OPTION B — Retrain Model from Scratch
+# ------------------------------------------
+# Use this option if you want TanML to retrain the model for you
+# using the cleaned dataset and the specified algorithm + hyperparameters.
+#
+# You must provide:
+#   - Path to the raw dataset (optional)
+#   - Path to the cleaned dataset (required)
+#   - The full model definition: type, module, and hyperparameters
+#
+# Be sure to:
+#   - Set `from_pickle: false`
+#   - Omit or comment out the `paths.model` line
+#   - Comment out the OPTION A block above
+# ------------------------------------------
+# paths:
+#   raw_data: /mnt/c/Users/your_name/Desktop/data/raw.csv
+#   cleaned_data: data/cleaned_a.csv
+
+# model_source:
+#   from_pickle: false
+#   type: LogisticRegression
+#   module: sklearn.linear_model
+#   hyperparameters:
+#     penalty: "l2"
+#     C: 1.0
+#     solver: "liblinear"
+#     class_weight: "balanced"
+#     max_iter: 100
+#     random_state: 42
+
+# ------------------------------------------
+# PERFORMANCE THRESHOLDS
+# ------------------------------------------
+auc_roc:
+  min: 0.60
+
+f1:
+  min: 0.60
+
+ks:
+  min: 0.20
+
+# ------------------------------------------
+# VALIDATION CHECKS
+# ------------------------------------------
+
+EDACheck:
+  enabled: true
+  max_plots: -1             # -1 = all numeric; or set number of columns
+
+correlation:
+  enabled: true
+
+VIFCheck:
+  enabled: true
+  
+raw_data_check:
+  enabled: true
+
+model_meta:
+  enabled: true
+
+# ------------------------------------------
+# STRESS TESTING (Robustness Check)
+# ------------------------------------------
+StressTestCheck:
+  enabled: true
+  epsilon: 0.01             # ➜ 1% noise
+  perturb_fraction: 0.2     # ➜ 20% of rows
+
+# ------------------------------------------
+# INPUT CLUSTER COVERAGE
+# ------------------------------------------
+InputClusterCoverageCheck:
+  enabled: true
+  n_clusters: 5             # ➜ fixed clusters for coverage bar chart
+  max_k: 10                 # ➜ elbow method search (if needed)
+
+# ------------------------------------------
+# EXPLAINABILITY
+# ------------------------------------------
+explainability:
+  shap:
+    enabled: true
+    background_sample_size: 100   # ➜ SHAP explainer training background
+    test_sample_size: 200         # ➜ test rows to explain

tanml/engine/check_agent_registry.py

@@ -0,0 +1,42 @@
+from tanml.check_runners.performance_runner import run_performance_check
+from tanml.check_runners.data_quality_runner import run_data_quality_check
+from tanml.check_runners.stress_test_runner import run_stress_test_check
+from tanml.check_runners.input_cluster_runner import run_input_cluster_check
+from tanml.check_runners.logistic_stats_runner import run_logistic_stats_check
+from tanml.check_runners.raw_data_runner import run_raw_data_check
+#from tanml.check_runners.cleaning_repro_runner import run_cleaning_repro_check
+from tanml.check_runners.model_meta_runner import ModelMetaCheckRunner
+from tanml.check_runners.correlation_runner import CorrelationCheckRunner
+from tanml.check_runners.eda_runner import EDACheckRunner
+from tanml.check_runners.explainability_runner import run_shap_check
+from tanml.check_runners.vif_runner import VIFCheckRunner
+from tanml.check_runners.rule_engine_runner import RuleEngineCheckRunner
+
+
+# Wrapper for InputClusterCheck to inject expected_features from model
+def input_cluster_wrapper(model, X_train, X_test, y_train, y_test, rule_config, cleaned_df, *args, **kwargs):
+    if hasattr(model, "feature_names_in_"):
+        expected_features = list(model.feature_names_in_)
+    else:
+        raise ValueError("Model does not have 'feature_names_in_' attribute required for InputClusterCheck.")
+    
+    return run_input_cluster_check(
+        model, X_train, X_test, y_train, y_test, rule_config, cleaned_df, expected_features
+    )
+
+CHECK_RUNNER_REGISTRY = {
+    "PerformanceCheck": run_performance_check,
+    "DataQualityCheck": run_data_quality_check,
+    "StressTestCheck": run_stress_test_check,
+    "InputClusterCheck": input_cluster_wrapper,  
+    "LogisticStatsCheck": run_logistic_stats_check,
+    "RawDataCheck": run_raw_data_check,
+    #"CleaningReproCheck": run_cleaning_repro_check,
+    "ModelMetaCheck": ModelMetaCheckRunner,  
+    "CorrelationCheck": CorrelationCheckRunner, 
+    "EDACheck": EDACheckRunner,  
+    "SHAPCheck": run_shap_check,
+    "VIFCheck": VIFCheckRunner,
+    "RuleEngineCheck": RuleEngineCheckRunner, 
+
+}

tanml/engine/core_engine_agent.py

@@ -0,0 +1,115 @@
+"""
+ValidationEngine – runs all registered check-runners and assembles a
+single results dictionary that the ReportBuilder / Jinja template expects.
+"""
+
+from tanml.engine.check_agent_registry import CHECK_RUNNER_REGISTRY
+#from tanml.checks.cleaning_repro import CleaningReproCheck 
+
+
+KEEP_AS_NESTED = {
+    "DataQualityCheck",
+    "StressTestCheck",
+    "InputClusterCheck",
+    "RawDataCheck",
+    #"CleaningReproCheck",
+    "SHAPCheck",
+    "VIFCheck",
+    "CorrelationCheck",
+    "EDACheck",
+}
+
+
+class ValidationEngine:
+    def __init__(
+        self,
+        model,
+        X_train,
+        X_test,
+        y_train,
+        y_test,
+        config,
+        cleaned_data,
+        raw_df=None ,
+        ctx=None 
+    ):
+        self.model = model
+        self.X_train = X_train
+        self.X_test = X_test
+        self.y_train = y_train
+        self.y_test = y_test
+        self.config = config
+        self.cleaned_data = cleaned_data
+        self.raw_df = raw_df 
+
+        self.results = dict(config.get("check_results", {}))
+        self.ctx = ctx or {}
+    def run_all_checks(self):
+        for check_name, runner_func in CHECK_RUNNER_REGISTRY.items():
+            if check_name in self.config.get("skip_checks", []):
+                continue
+
+            print(f"✅ Running {check_name}")
+            try:
+                result = runner_func(
+                    self.model,
+                    self.X_train,
+                    self.X_test,
+                    self.y_train,
+                    self.y_test,
+                    self.config,
+                    self.cleaned_data,
+                    raw_df=self.raw_df 
+                )
+
+                self._integrate(check_name, result)
+
+            except Exception as e:
+                print(f"⚠️  {check_name} failed: {e}")
+                self.results[check_name] = {"error": str(e)}
+
+        # Add CleaningReproCheck manually
+        # if self.raw_df is not None:
+        #     print("✅ Running CleaningReproCheck")
+        #     try:
+        #         check = CleaningReproCheck(self.raw_df, self.cleaned_data)
+
+        #         self.results["CleaningReproCheck"] = check.run()
+        #     except Exception as e:
+        #         print(f"⚠️ CleaningReproCheck failed: {e}")
+        #         self.results["CleaningReproCheck"] = {"error": str(e)}
+        # else:
+        #     print("⚠️ Skipping CleaningReproCheck — raw_df not provided")
+        #     self.results["CleaningReproCheck"] = {"error": "raw_data not available"}
+
+        # convenience copy for template
+        self.results["check_results"] = dict(self.results)
+        return self.results
+
+    def _integrate(self, check_name: str, result):
+        """Merge a check result into self.results respecting the template layout."""
+        if not result:
+            return
+
+        # Special flatten for LogisticStatsCheck
+        if check_name == "LogisticStatsCheck":
+            self.results.update(result)
+            return
+
+        # If it's a simple object (rare), store as-is
+        if not isinstance(result, dict):
+            self.results[check_name] = result
+            return
+
+        # Keep entire dict nested
+        if check_name in KEEP_AS_NESTED:
+            self.results[check_name] = result
+            return
+
+        # If runner returns {"CheckName": {...}}, unwrap
+        if set(result.keys()) == {check_name}:
+            self.results[check_name] = result[check_name]
+            return
+
+        # Default: merge into root
+        self.results.update(result)