shapeaudit 1.0.0__py3-none-any.whl

modelcheck/__init__.py

@@ -0,0 +1,59 @@
+try:
+    from importlib.metadata import version as _v
+    try:
+        __version__ = _v("shapeaudit")
+    except Exception:                      # instalado pelo nome anterior
+        __version__ = _v("modelguard-ml")
+except Exception:
+    __version__ = "0.0.0+dev"
+
+
+from .ale_detector import ALEShapeDetector, ale_shape_profile
+
+from .audit import audit
+from .geometry import GeometryDivergenceDetector
+
+from .paired import PairedDivergenceAnalyzer
+
+from .rhale import RHALEDetector, rhale_profile
+from .zest import ArchitectureAgnosticComparator
+
+from .trending import ShapeTrendingDetector
+from .ood import OODBehavioralDetector
+
+from .canary import GeometricCanaryDetector
+from .explorer import InteractiveDivergenceExplorer
+
+from .topology import TopologicalDriftDetector
+from .stability import SupervisedStabilityAnalyzer
+from .gtsf import GTSF
+
+from .orchestrator import ModelGuardOrchestrator
+
+from .importance import ImportanceCollapseDetector
+
+from .confidence import score_with_ci, compare_scores_ci
+
+from .baselines import run_all_baselines
+
+from .shapedist import shape_cost, severity, profile_distance
+
+from .ale_fast import ale_curve_fast, model_embedding_ale, feature_kind
+
+from .universal import UniversalCanaryDetector, TopologicalDriftGudhi
+
+
+from .ale_selective import SelectiveALEDetector
+
+from .validation import TrainServingValidator
+
+from .guard import ModelGuard
+from .api import Guard, AuditResult
+
+from .leakage_temporal import TemporalLeakageDetector
+
+from .psi_shap import PSIShapDetector
+
+from .backends import importance as feature_importance, BACKENDS
+
+from modelcheck import snapshot  # noqa: E402,F401

modelcheck/_validate.py

@@ -0,0 +1,214 @@
+"""
+_validate.py — Validação de entrada compartilhada (v1.47)
+
+BUG 17: sondando a API pública com entradas inválidas, vários detectores
+devolviam resultado NORMAL em vez de erro:
+  - `features=[]`  -> resultado como se tudo estivesse bem
+  - `X` vazio      -> frechet_distance = nan, score 100
+  - `X` com 1 linha-> score 100
+  - `X` como numpy -> AttributeError cru
+  - modelo None    -> AttributeError cru
+
+Um resultado plausível para entrada inválida é a pior falha possível: o
+usuário confia num número que não significa nada.
+"""
+import numpy as np
+import pandas as pd
+from typing import List, Optional
+
+MIN_ROWS = 10
+
+
+def validate_inputs(model_v1, model_v2,
+                    X, feature_names: Optional[List[str]] = None,
+                    min_rows: int = MIN_ROWS,
+                    caller: str = "detector"):
+    """
+    Normaliza e valida. Devolve (X_df, feature_names).
+    Levanta ValueError/TypeError com instrução acionável.
+    """
+    if model_v1 is None or model_v2 is None:
+        qual = "model_v1" if model_v1 is None else "model_v2"
+        raise ValueError(
+            f"{caller}: {qual} é None. Passe dois modelos treinados com "
+            f"método predict().")
+    for nome, m in (("model_v1", model_v1), ("model_v2", model_v2)):
+        if not hasattr(m, "predict"):
+            raise TypeError(
+                f"{caller}: {nome} ({type(m).__name__}) não tem método "
+                f"predict(). Passe um modelo treinado.")
+
+    if X is None:
+        raise ValueError(
+            f"{caller}: X é None. Passe um DataFrame com as features de "
+            f"avaliação.")
+    if not isinstance(X, pd.DataFrame):
+        arr = np.asarray(X)
+        if arr.ndim != 2:
+            raise ValueError(
+                f"{caller}: X deve ser 2D, recebido ndim={arr.ndim}.")
+        X = pd.DataFrame(arr, columns=[f"f{i}" for i in range(arr.shape[1])])
+
+    if len(X) == 0:
+        raise ValueError(
+            f"{caller}: X está vazio (0 linhas). Não é possível avaliar.")
+    if len(X) < min_rows:
+        raise ValueError(
+            f"{caller}: X tem apenas {len(X)} linhas (mínimo {min_rows}). "
+            f"Resultados com n menor não são interpretáveis.")
+
+    if feature_names is None:
+        feature_names = list(X.columns)
+    if isinstance(feature_names, str):
+        feature_names = [feature_names]
+    feature_names = list(feature_names)
+    if not feature_names:
+        raise ValueError(
+            f"{caller}: feature_names está vazio. Passe ao menos uma "
+            f"feature, ou None para usar todas as colunas de X.")
+    faltando = [f for f in feature_names if f not in X.columns]
+    if faltando:
+        raise ValueError(
+            f"{caller}: features ausentes em X: {faltando[:5]}. "
+            f"Colunas disponíveis: {list(X.columns)[:8]}.")
+    return X, feature_names
+
+
+# ══ Condições que invalidam ou enfraquecem a comparação (v1.71) ══════
+#
+# Encontradas por varredura sistemática depois do caso da imputação. A
+# classe é sempre a mesma: a ferramenta produz um veredito num caso onde
+# o veredito não significa o que o leitor supõe.
+#
+#   recusa   a comparação não é válida — nenhum número salva
+#   aviso    é válida mas frágil; o resultado sai com a ressalva
+
+N_MINIMO_CONFIAVEL = 60     # abaixo disto a classificação de forma oscila
+N_MINIMO_CLASSE = 20        # abaixo disto nada se conclui sobre a classe
+
+
+def natureza_da_saida(model, X):
+    """'classe', 'continuo' ou None se não for possível determinar."""
+    import numpy as np
+    try:
+        p = np.asarray(model.predict(X[:200]), dtype=float)
+    except Exception:
+        return None
+    if p.ndim > 1:
+        p = p.ravel()
+    p = p[np.isfinite(p)]
+    if len(p) == 0:
+        return None
+    unicos = np.unique(p)
+    if len(unicos) <= max(2, len(p) * 0.02) and np.all(unicos == unicos.astype(int)):
+        return 'classe'
+    return 'continuo'
+
+
+def checar_comparabilidade(model_v1, model_v2, X, feature_names=None,
+                           caller='audit', y_eval=None):
+    """
+    Levanta ValueError quando a comparação não é válida; devolve a lista de
+    ressalvas quando é válida mas frágil.
+    """
+    import numpy as np
+    ressalvas = []
+
+    # ── recusa: ordem de colunas diferente da vista no treino ────────
+    # BUG 32 (v1.73): o sklearn recusa `X[colunas_reordenadas]` com
+    # "Feature names must be in the same order as they were in fit". Alguma
+    # camada engolia esse erro e o veredito saía mesmo assim — apontando a
+    # variável ERRADA (corrompemos x0, o laudo dizia x3).
+    #
+    # Reordenar colunas é acidente comum: um `select` diferente, um join
+    # que muda a ordem, um CSV regravado.
+    for rotulo, m in (('v1', model_v1), ('v2', model_v2)):
+        esperado = getattr(m, 'feature_names_in_', None)
+        if esperado is None:
+            continue
+        recebido = list(X.columns)
+        esperado = [str(f) for f in esperado]
+        if recebido == esperado:
+            continue
+        if sorted(recebido) == sorted(esperado):
+            raise ValueError(
+                f"{caller}: as colunas de X estão em ordem diferente da "
+                f"usada no treino do modelo {rotulo}. O modelo casa colunas "
+                f"por posição, então isto entrega valores trocados e o "
+                f"diagnóstico apontaria a variável errada. Reordene com "
+                f"X[list(model.feature_names_in_)].")
+        faltando = [f for f in esperado if f not in recebido]
+        sobrando = [f for f in recebido if f not in esperado]
+        raise ValueError(
+            f"{caller}: as colunas de X não correspondem às do treino do "
+            f"modelo {rotulo}. Faltando: {faltando[:4] or '—'}. "
+            f"Sobrando: {sobrando[:4] or '—'}.")
+
+    # ── recusa: naturezas de saída diferentes ────────────────────────
+    n1, n2 = natureza_da_saida(model_v1, X), natureza_da_saida(model_v2, X)
+    if n1 and n2 and n1 != n2:
+        raise ValueError(
+            f"{caller}: os dois modelos produzem saídas de naturezas "
+            f"diferentes ({n1} e {n2}). Um regressor e um classificador não "
+            f"são comparáveis — as atribuições estão em unidades distintas e "
+            f"qualquer veredito seria sobre a diferença de unidade, não sobre "
+            f"o modelo. Compare modelos do mesmo tipo.")
+
+    # ── aviso: conjunto de avaliação pequeno ─────────────────────────
+    if len(X) < N_MINIMO_CONFIAVEL:
+        ressalvas.append({
+            'layer': 'evaluation size',
+            'reason': f'apenas {len(X)} amostras de avaliação',
+            'consequence': (f'abaixo de {N_MINIMO_CONFIAVEL} a classificação '
+                            f'de forma não é estável; o veredito pode mudar '
+                            f'com outra amostra'),
+            'severity': 'alta',
+        })
+
+    # ── aviso: classe rara demais para sustentar conclusão ───────────
+    # v1.73: um classificador avaliado com 2 exemplos de uma das classes
+    # produzia APROVADO sem ressalva. Com 2 amostras nada pode ser
+    # concluído sobre o comportamento naquela classe — e o leitor de um
+    # APROVADO supõe que houve verificação.
+    if y_eval is not None:
+        try:
+            vc = pd.Series(y_eval).value_counts()
+            if 1 < len(vc) <= 20:                # parece classificação
+                # o repr de um np.int64 polui a mensagem do usuário
+                _r = vc.index[-1]
+                rara = _r.item() if hasattr(_r, 'item') else _r
+                n_rara = int(vc.iloc[-1])
+                if n_rara < N_MINIMO_CLASSE:
+                    ressalvas.append({
+                        'layer': 'class representation',
+                        'reason': (f'a classe {rara!r} tem apenas {n_rara} '
+                                   f'exemplos na avaliação'),
+                        'consequence': ('nada pode ser concluído sobre o '
+                                        'comportamento do modelo nessa '
+                                        'classe'),
+                        'severity': 'alta',
+                    })
+        except Exception:
+            pass     # noqa: lacuna-nao-aplicavel — heurística de aviso
+
+    # ── aviso: avaliação fora da faixa vista no treino ───────────────
+    fora = []
+    for m in (model_v1, model_v2):
+        faixa = getattr(m, '_modelcheck_train_range', None)
+        if faixa:
+            for col, (lo, hi) in faixa.items():
+                if col in X.columns:
+                    v = X[col].to_numpy(dtype=float)
+                    v = v[np.isfinite(v)]
+                    if len(v) and (v.min() > hi or v.max() < lo):
+                        fora.append(col)
+    if fora:
+        ressalvas.append({
+            'layer': 'evaluation range',
+            'reason': f'avaliação fora da faixa de treino em {sorted(set(fora))[:3]}',
+            'consequence': ('os dois modelos estão extrapolando; a "concordância" '
+                            'entre eles não diz nada sobre o comportamento na '
+                            'faixa de operação'),
+            'severity': 'alta',
+        })
+    return ressalvas

modelcheck/ale.py

@@ -0,0 +1,60 @@
+"""ALE (Accumulated Local Effects) como alternativa ao SHAP no SDD."""
+import numpy as np
+import pandas as pd
+
+
+class ALEProfile:
+    """Resultado de perfil ALE — mesma interface que SHAP values."""
+    def __init__(self, values):
+        self.values = values  # shape (n, p) — compatível com ShapExplainer
+
+
+def ale_explain(model, X: pd.DataFrame, n_bins: int = 5) -> ALEProfile:
+    """Calcula ALE 1D para todas as features numéricas.
+
+    ALE mede o efeito local médio da feature em cada bin,
+    acumulando para obter o efeito total — robusto a correlações.
+    Retorna matriz (n_rows, n_features) compatível com ShapeDivergenceDetector.
+    """
+    n, p = X.shape
+    ale_matrix = np.zeros((n, p))
+
+    for j, col in enumerate(X.columns):
+        if not pd.api.types.is_numeric_dtype(X[col]):
+            continue
+        vals = X[col].to_numpy(dtype=float)
+        if np.std(vals) == 0:
+            continue
+        try:
+            _, edges = pd.qcut(vals, n_bins, duplicates="drop", retbins=True)
+        except ValueError:
+            continue
+
+        # efeito local em cada bin
+        bin_effects = []
+        bin_centers = []
+        for i in range(len(edges) - 1):
+            lo, hi = edges[i], edges[i + 1]
+            mask = (vals >= lo) & (vals <= hi)
+            if mask.sum() < 3:
+                bin_effects.append(0.0)
+            else:
+                X_lo = X.copy(); X_lo.iloc[:, j] = lo
+                X_hi = X.copy(); X_hi.iloc[:, j] = hi
+                eff = (model.predict(X_hi[mask]) -
+                       model.predict(X_lo[mask])).mean()
+                bin_effects.append(float(eff))
+            bin_centers.append((lo + hi) / 2)
+
+        # acumular e centrar
+        cumulative = np.cumsum(bin_effects)
+        cumulative -= cumulative.mean()
+
+        # interpolar para cada linha
+        for idx in range(n):
+            v = vals[idx]
+            bin_idx = np.searchsorted(edges[1:-1], v)
+            bin_idx = int(np.clip(bin_idx, 0, len(cumulative) - 1))
+            ale_matrix[idx, j] = cumulative[bin_idx]
+
+    return ALEProfile(ale_matrix)

modelcheck/ale_detector.py

@@ -0,0 +1,277 @@
+"""ALE-based Shape Instability Detector.
+
+Contribuição nova em relação ao SDD original (baseado em SHAP):
+
+Problema com SHAP:
+    1. Depende de background dataset — a forma muda com background diferente
+    2. Features correlacionadas — SHAP distribui efeito entre features
+    3. KernelSHAP para MLP/SVM é lento (O(n*d)) e ruidoso com n pequeno
+    4. Modelos proprietários via API — não dá extrair pesos para SHAP
+
+Solução ALE:
+    ALE (Accumulated Local Effects, Apley & Zhu 2020) computa o efeito
+    local de cada feature condicionando nos vizinhos — robusto a correlações.
+    Usa apenas model.predict() — funciona para qualquer arquitetura.
+
+    Algoritmo:
+    1. Para cada bin k da feature j:
+       a. Seleciona amostras dentro do bin
+       b. Prediz com feature no limite inferior e superior do bin
+       c. Delta médio = efeito local do bin
+    2. Acumula os deltas → perfil ALE cumulativo
+    3. Centraliza (subtrai a média)
+    4. Classifica a forma do perfil com _shape_profile_small_n
+
+Resultado experimental (benchmark controlado, n=2000, 6 cenários):
+    SHAP: Recall=100%, Precision=67%, F1=0.80, FP=3
+    ALE:  Recall=83%,  Precision=45%, F1=0.59, FP=6
+
+    SHAP é superior para modelos de árvore onde é exato.
+    ALE é a ÚNICA opção para:
+    - MLP, SVM, redes neurais (KernelSHAP lento/ruidoso)
+    - Modelos via API (sem acesso aos pesos)
+    - LLMs via behavioral probing (LLMGuard)
+
+Uso:
+    from modelcheck.ale_detector import ALEShapeDetector
+
+    detector = ALEShapeDetector(n_bins=6, n_boot=40, min_confidence=0.65)
+    results  = detector.compare(model_v1, model_v2, X_eval, feature_names)
+    print(detector.report(results))
+"""
+import numpy as np
+import pandas as pd
+from typing import List, Optional, Union
+from collections import Counter
+
+from .shape import _shape_profile_small_n
+
+
+def ale_shape_profile(model,
+                      X:       pd.DataFrame,
+                      feature: str,
+                      n_bins:  int = 6,
+                      min_bin_n: int = 5) -> Optional[dict]:
+    """Calcula o perfil de forma ALE para uma feature.
+
+    Parâmetros:
+        model     : modelo com interface predict(X) → array 1D
+        X         : DataFrame de avaliação
+        feature   : nome da feature
+        n_bins    : número de bins quantílicos (padrão 6)
+        min_bin_n : mínimo de amostras por bin (padrão 5)
+
+    Retorna dict com:
+        shape     : classificação ('crescente', 'decrescente', 'u',
+                                   'u_invertido', 'irregular')
+        confidence: confiança do classificador (0–1)
+        ale_cum   : array do perfil ALE cumulativo
+        centers   : centros dos bins
+        n_bins_ok : número de bins com amostras suficientes
+
+    Retorna None se não há amostras suficientes.
+
+    Notas técnicas:
+        O perfil ALE mede o efeito ACUMULADO da feature — análogo à
+        integral do efeito local. Isso torna a classificação de forma
+        diretamente comparável ao SHAP profile: crescente significa
+        que a feature tem efeito positivo crescente ao longo do seu range.
+    """
+    X = X.copy()
+    x = np.asarray(X[feature].values, dtype=float)
+
+    if np.std(x) < 1e-8:
+        return None
+
+    # Bins quantílicos
+    bins = np.unique(np.percentile(x, np.linspace(0, 100, n_bins + 1)))
+    if len(bins) < 4:
+        return None
+
+    ale_means = []
+    centers   = []
+
+    for i in range(len(bins) - 1):
+        mask = (x >= bins[i]) & (x <= bins[i + 1])
+        if mask.sum() < min_bin_n:
+            continue
+
+        Xlo = X[mask].copy()
+        Xhi = X[mask].copy()
+        Xlo[feature] = bins[i]
+        Xhi[feature] = bins[i + 1]
+
+        # Efeito local médio do bin
+        delta = model.predict(Xhi.values) - model.predict(Xlo.values)
+        ale_means.append(float(delta.mean()))
+        centers.append((bins[i] + bins[i + 1]) / 2)
+
+    if len(ale_means) < 3:
+        return None
+
+    # Perfil cumulativo centralizado
+    ale_cum  = np.cumsum(ale_means)
+    ale_cum -= ale_cum.mean()
+
+    # Classifica a forma usando _shape_profile_small_n
+    # (min_n=3 porque temos n_bins centros, não n amostras)
+    p = _shape_profile_small_n(
+        np.array(centers, dtype=float),
+        ale_cum,
+        min_n=3
+    )
+    if not p:
+        return None
+
+    return {
+        'shape':      p['shape'],
+        'confidence': p.get('confidence', 1.0),
+        'ale_cum':    ale_cum.tolist(),
+        'centers':    centers,
+        'n_bins_ok':  len(ale_means),
+    }
+
+
+class ALEShapeDetector:
+    """Detecta Shape Instability entre dois modelos usando ALE.
+
+    Funciona com qualquer model.predict() — RF, GB, MLP, SVM, API.
+
+    Parâmetros:
+        n_bins        : bins quantílicos para o ALE (padrão 6)
+        min_bin_n     : amostras mínimas por bin (padrão 5)
+        n_boot        : iterações bootstrap para estabilidade (padrão 40)
+        min_confidence: confiança mínima para alertar (padrão 0.65)
+                        Valor mais alto → menos FPs, mais FNs
+
+    Uso com modelos de árvore (RF, GB):
+        Quando TreeSHAP está disponível, prefira o SDD original.
+        Use ALEShapeDetector quando:
+        - O modelo não é árvore (MLP, SVM, NN)
+        - Não tem background dataset
+        - Quer resultado comparável entre arquiteturas diferentes
+
+    Uso com modelos via API:
+        def my_api_model(X):
+            # chama a API e retorna array de predições
+            return np.array([api_predict(row) for row in X])
+
+        detector = ALEShapeDetector()
+        results  = detector.compare(my_api_model, my_api_model_v2,
+                                    X_eval, features)
+    """
+
+    def __init__(self,
+                 n_bins:         int   = 6,
+                 min_bin_n:      int   = 5,
+                 n_boot:         int   = 40,
+                 min_confidence: float = 0.65):
+        self.n_bins         = n_bins
+        self.min_bin_n      = min_bin_n
+        self.n_boot         = n_boot
+        self.min_confidence = min_confidence
+
+    def _profile_bootstrap(self, model, X: pd.DataFrame,
+                           feature: str) -> tuple:
+        """Classifica a forma com bootstrap — retorna (shape, confidence)."""
+        shapes = []
+        n = len(X)
+        for seed in range(self.n_boot):
+            np.random.seed(seed)
+            idx = np.random.choice(n, n, replace=True)
+            Xb  = X.iloc[idx].reset_index(drop=True)
+            p   = ale_shape_profile(model, Xb, feature,
+                                    self.n_bins, self.min_bin_n)
+            if p:
+                shapes.append(p['shape'])
+
+        if not shapes:
+            return 'n/a', 0.0
+
+        sh, c = Counter(shapes).most_common(1)[0]
+        return sh, round(c / len(shapes), 2)
+
+    def compare(self,
+                model1,
+                model2,
+                X_eval:        pd.DataFrame,
+                feature_names: Optional[List[str]] = None) -> list:
+        """Compara formas ALE entre dois modelos.
+
+        Parâmetros:
+            model1, model2 : modelos com interface predict(array) → array
+            X_eval         : DataFrame de avaliação
+            feature_names  : lista de features (default: todas)
+
+        Retorna lista de dicts por feature:
+            feature     : nome
+            shape1      : forma do modelo 1
+            shape2      : forma do modelo 2
+            conf1, conf2: confiança bootstrap de cada classificação
+            divergence  : True se shapes divergem com confiança >= min_confidence
+            alert       : descrição da divergência ou None
+        """
+        if feature_names is None:
+            feature_names = list(X_eval.columns)
+
+        results = []
+        for f in feature_names:
+            sh1, c1 = self._profile_bootstrap(model1, X_eval, f)
+            sh2, c2 = self._profile_bootstrap(model2, X_eval, f)
+
+            div = (sh1 != sh2
+                   and sh1 not in ('n/a', 'irregular')
+                   and sh2 not in ('n/a', 'irregular')
+                   and c1 >= self.min_confidence
+                   and c2 >= self.min_confidence)
+
+            alert = (f"ALE_SHAPE_DIV: '{f}' {sh1}→{sh2} "
+                     f"(conf: {c1:.0%}/{c2:.0%})") if div else None
+
+            results.append({
+                'feature':   f,
+                'shape1':    sh1, 'conf1': c1,
+                'shape2':    sh2, 'conf2': c2,
+                'divergence': div,
+                'alert':     alert,
+            })
+
+        return results
+
+    def report(self, results: list) -> str:
+        """Relatório textual dos resultados."""
+        divs = [r for r in results if r['divergence']]
+        n    = len(results)
+
+        lines = [f"ALEShapeDetector (n_boot={self.n_boot}, "
+                 f"min_conf={self.min_confidence:.0%}):"]
+
+        if not divs:
+            lines.append(f"  ✅ Nenhuma divergência de forma detectada ({n} features)")
+        else:
+            lines.append(f"  ⚠ {len(divs)}/{n} feature(s) com Shape Instability:")
+            for r in divs:
+                lines.append(f"    '{r['feature']}': "
+                             f"{r['shape1']} (conf={r['conf1']:.0%}) → "
+                             f"{r['shape2']} (conf={r['conf2']:.0%})")
+
+        stable = [r for r in results
+                  if not r['divergence'] and r['shape1'] != 'n/a']
+        if stable:
+            lines.append(f"  ✅ {len(stable)} feature(s) estáveis: "
+                         f"{[r['feature'] for r in stable]}")
+
+        na = [r for r in results if r['shape1'] == 'n/a']
+        if na:
+            lines.append(f"  → {len(na)} feature(s) sem amostras suficientes "
+                         f"(aumentar n_eval ou reduzir n_bins)")
+
+        return "\n".join(lines)
+
+    def health_score(self, results: list) -> dict:
+        """Health Score 0–100 baseado nas divergências ALE."""
+        n_div = sum(1 for r in results if r['divergence'])
+        score = max(0, 100 - n_div * 15)
+        status = ("HEALTHY"   if score >= 85 else
+                  "ATTENTION" if score >= 65 else "CRITICAL")
+        return {'score': score, 'status': status, 'n_divergences': n_div}