shapeaudit 1.0.2__tar.gz

shapeaudit-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 modelcheck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shapeaudit-1.0.2/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: shapeaudit
+Version: 1.0.2
+Summary: Descubra se o modelo novo aprendeu a mesma coisa que o antigo — auditoria entre duas versões, com laudo em HTML
+Author-email: Riviane Maria Albuquerque Donha <riviane.donha@ufpr.br>
+License: MIT
+Project-URL: Homepage, https://github.com/Rivianee/shapeaudit
+Keywords: machine-learning,mlops,model-monitoring,explainability,shap,model-audit,ci-cd
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: shap<0.53,>=0.44
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: scikit-learn>=1.3
+Provides-Extra: mlflow
+Requires-Dist: mlflow-skinny>=2.10; extra == "mlflow"
+Provides-Extra: xgboost
+Requires-Dist: xgboost<3,>=1.7; extra == "xgboost"
+Provides-Extra: lightgbm
+Requires-Dist: lightgbm>=4.0; extra == "lightgbm"
+Provides-Extra: evidently
+Requires-Dist: evidently>=0.7; extra == "evidently"
+Provides-Extra: fairlearn
+Requires-Dist: fairlearn>=0.10; extra == "fairlearn"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# ShapeAudit
+
+**Seu modelo novo tem a mesma acurácia do antigo. Mas será que ele aprendeu a
+mesma coisa?**
+
+Toda vez que um modelo é retreinado, alguém precisa decidir se promove a versão
+nova. Na prática, a decisão costuma ser uma só: *a acurácia caiu?* Se não caiu,
+sobe.
+
+O problema é que essa pergunta não cobre tudo. Duas versões podem acertar na
+mesma proporção e **usar as variáveis de um jeito diferente** — inclusive uma
+delas ter perdido uma coluna no caminho, sem que a métrica acuse.
+
+Um exemplo real, com dados públicos de churn de telecom:
+
+```
+versão em produção:  0.815
+versão candidata:    0.807
+diferença:           0.008     ← praticamente nada
+
+ShapeAudit:  NÃO PROMOVA — a variável `Contract` deixou de
+             influenciar a previsão e chega constante no treino
+```
+
+Uma coluna virou constante depois de uma mudança no pipeline. **Um gate por
+métrica aprovaria essa versão.**
+
+## Instalar
+
+```bash
+pip install shapeaudit
+```
+
+## Usar
+
+```python
+from shapeaudit import Guard
+
+r = Guard().audit(modelo_antigo, modelo_novo, X_avaliacao, y_avaliacao,
+                  X_train=dados_de_treino_do_modelo_novo)
+
+print(r.verdict)               # APROVADO | REVISAR | ATENCAO | BLOQUEADO
+print(r.root_cause_features)   # ['Contract']
+open('laudo.html', 'w').write(r.to_html())      # laudo para abrir no navegador
+```
+
+`X_train` é o treino do **modelo novo**. É esse argumento que separa "a coluna
+sumiu do pipeline" de "o modelo deixou de usar a coluna". Sem ele a auditoria
+roda, mas avisa que não verificou isso.
+
+## O que você recebe
+
+| veredito | o que aconteceu | o que fazer |
+|---|---|---|
+| **BLOQUEADO** | uma variável sumiu do modelo e está constante no treino | não promova: verifique o pipeline |
+| **ATENÇÃO** | os dados chegam diferentes do treino, ou uma variável quase idêntica assumiu o lugar de outra | promova com monitoramento, recalibre |
+| **REVISAR** | com os mesmos dados, o modelo novo responde de outro jeito | olhe as curvas antes de promover |
+| **APROVADO** | nenhuma verificação encontrou mudança | pode promover |
+
+E um laudo HTML que responde, nesta ordem: o que aconteceu, o que mudou de
+peso e de comportamento, onde exatamente mudou, se isso muda decisões, por onde
+começar a investigar, e **o que não foi verificado**.
+
+## Experimentar em dois minutos
+
+- **No Colab**, sem instalar nada: abra `ShapeAudit_Colab.ipynb` e rode tudo.
+- **Com uma planilha sua**: `python demo_excel.py meus_dados.xlsx nome_do_alvo`
+
+Os dois terminam com o laudo aberto e um caso de pipeline quebrado, para você
+ver os dois extremos.
+
+## Três perguntas, três camadas
+
+1. **Alguma variável sumiu do modelo?** Compara o peso de cada variável nas
+   duas versões e distingue "a coluna sumiu" de "o modelo deixou de usar".
+2. **Os dados chegam como no treino?** Compara o treino do modelo novo com os
+   dados que ele vai pontuar.
+3. **O modelo passou a reagir de outro jeito?** Compara a curva de efeito de
+   cada variável entre as duas versões. Uma distância detecta a mudança e uma
+   classificação em cinco formas a nomeia.
+
+O veredito usa só essas três. Extremos, subgrupos e impacto em grupos de
+pessoas aparecem como verificações adicionais.
+
+## Calibrar no seu caso
+
+O limiar padrão veio de uma bancada sintética. Calibre com retreinos que você
+**teria promovido** — não precisa de rótulo nem de falha conhecida:
+
+```python
+from shapeaudit.frechet import calibrar_limiar
+print(calibrar_limiar([(modelo_jan, modelo_fev), ...], X_avaliacao)['limiar'])
+```
+
+Medido: de 0,12 a 0,47 em seis conjuntos de dados, e o limiar de modelos de
+boosting é cinco a seis vezes o de florestas nos mesmos dados. Calibre por
+domínio **e** por família de modelo.
+
+## O que ele não faz
+
+- **Não bloqueia degradação parcial:** com até 80% das linhas de uma variável
+  corrompidas, o modelo perde 4 pontos de R² e nada dispara.
+- **Em bases pequenas** (menos de ~400 linhas de avaliação) pede revisão em
+  cerca de um terço dos retreinos saudáveis.
+- **Fora de árvores** (MLP, ridge) é experimental: bloqueia falha de pipeline,
+  mas alarma mais e é cerca de dez vezes mais lento.
+- **Não distingue sazonalidade de mudança real.**
+- **Não diz qual das duas versões está certa** — só que elas discordam.
+
+`LIMITATIONS.md` traz cada limite com o número medido.
+
+## Confiança no veredito
+
+Em 240 controles saudáveis de benchmark, 161 retreinos reais de séries públicas
+do setor elétrico brasileiro e 12 conjuntos públicos, **nenhum retreino saudável
+foi bloqueado**. Quando o pipeline quebrou de verdade, bloqueou 16 de 18 casos
+nomeando a variável.
+
+A recíproca não vale: não bloquear não garante que está tudo bem.
+
+## Nomes
+
+A distribuição é `shapeaudit`. Três nomes de import funcionam, e apontam para
+a mesma implementação:
+
+```python
+import shapeaudit      # nome atual
+import modelguard      # nome anterior (pacote `modelguard-ml`), mantido
+import modelcheck      # nome original, mantido por compatibilidade
+```
+
+Quem já usava `modelguard-ml` não precisa mudar código: troque a instalação
+para `shapeaudit` e os imports antigos continuam funcionando.
+
+## Licença
+
+MIT. README em português; a documentação de limites também.

shapeaudit-1.0.2/README.md

@@ -0,0 +1,137 @@
+# ShapeAudit
+
+**Seu modelo novo tem a mesma acurácia do antigo. Mas será que ele aprendeu a
+mesma coisa?**
+
+Toda vez que um modelo é retreinado, alguém precisa decidir se promove a versão
+nova. Na prática, a decisão costuma ser uma só: *a acurácia caiu?* Se não caiu,
+sobe.
+
+O problema é que essa pergunta não cobre tudo. Duas versões podem acertar na
+mesma proporção e **usar as variáveis de um jeito diferente** — inclusive uma
+delas ter perdido uma coluna no caminho, sem que a métrica acuse.
+
+Um exemplo real, com dados públicos de churn de telecom:
+
+```
+versão em produção:  0.815
+versão candidata:    0.807
+diferença:           0.008     ← praticamente nada
+
+ShapeAudit:  NÃO PROMOVA — a variável `Contract` deixou de
+             influenciar a previsão e chega constante no treino
+```
+
+Uma coluna virou constante depois de uma mudança no pipeline. **Um gate por
+métrica aprovaria essa versão.**
+
+## Instalar
+
+```bash
+pip install shapeaudit
+```
+
+## Usar
+
+```python
+from shapeaudit import Guard
+
+r = Guard().audit(modelo_antigo, modelo_novo, X_avaliacao, y_avaliacao,
+                  X_train=dados_de_treino_do_modelo_novo)
+
+print(r.verdict)               # APROVADO | REVISAR | ATENCAO | BLOQUEADO
+print(r.root_cause_features)   # ['Contract']
+open('laudo.html', 'w').write(r.to_html())      # laudo para abrir no navegador
+```
+
+`X_train` é o treino do **modelo novo**. É esse argumento que separa "a coluna
+sumiu do pipeline" de "o modelo deixou de usar a coluna". Sem ele a auditoria
+roda, mas avisa que não verificou isso.
+
+## O que você recebe
+
+| veredito | o que aconteceu | o que fazer |
+|---|---|---|
+| **BLOQUEADO** | uma variável sumiu do modelo e está constante no treino | não promova: verifique o pipeline |
+| **ATENÇÃO** | os dados chegam diferentes do treino, ou uma variável quase idêntica assumiu o lugar de outra | promova com monitoramento, recalibre |
+| **REVISAR** | com os mesmos dados, o modelo novo responde de outro jeito | olhe as curvas antes de promover |
+| **APROVADO** | nenhuma verificação encontrou mudança | pode promover |
+
+E um laudo HTML que responde, nesta ordem: o que aconteceu, o que mudou de
+peso e de comportamento, onde exatamente mudou, se isso muda decisões, por onde
+começar a investigar, e **o que não foi verificado**.
+
+## Experimentar em dois minutos
+
+- **No Colab**, sem instalar nada: abra `ShapeAudit_Colab.ipynb` e rode tudo.
+- **Com uma planilha sua**: `python demo_excel.py meus_dados.xlsx nome_do_alvo`
+
+Os dois terminam com o laudo aberto e um caso de pipeline quebrado, para você
+ver os dois extremos.
+
+## Três perguntas, três camadas
+
+1. **Alguma variável sumiu do modelo?** Compara o peso de cada variável nas
+   duas versões e distingue "a coluna sumiu" de "o modelo deixou de usar".
+2. **Os dados chegam como no treino?** Compara o treino do modelo novo com os
+   dados que ele vai pontuar.
+3. **O modelo passou a reagir de outro jeito?** Compara a curva de efeito de
+   cada variável entre as duas versões. Uma distância detecta a mudança e uma
+   classificação em cinco formas a nomeia.
+
+O veredito usa só essas três. Extremos, subgrupos e impacto em grupos de
+pessoas aparecem como verificações adicionais.
+
+## Calibrar no seu caso
+
+O limiar padrão veio de uma bancada sintética. Calibre com retreinos que você
+**teria promovido** — não precisa de rótulo nem de falha conhecida:
+
+```python
+from shapeaudit.frechet import calibrar_limiar
+print(calibrar_limiar([(modelo_jan, modelo_fev), ...], X_avaliacao)['limiar'])
+```
+
+Medido: de 0,12 a 0,47 em seis conjuntos de dados, e o limiar de modelos de
+boosting é cinco a seis vezes o de florestas nos mesmos dados. Calibre por
+domínio **e** por família de modelo.
+
+## O que ele não faz
+
+- **Não bloqueia degradação parcial:** com até 80% das linhas de uma variável
+  corrompidas, o modelo perde 4 pontos de R² e nada dispara.
+- **Em bases pequenas** (menos de ~400 linhas de avaliação) pede revisão em
+  cerca de um terço dos retreinos saudáveis.
+- **Fora de árvores** (MLP, ridge) é experimental: bloqueia falha de pipeline,
+  mas alarma mais e é cerca de dez vezes mais lento.
+- **Não distingue sazonalidade de mudança real.**
+- **Não diz qual das duas versões está certa** — só que elas discordam.
+
+`LIMITATIONS.md` traz cada limite com o número medido.
+
+## Confiança no veredito
+
+Em 240 controles saudáveis de benchmark, 161 retreinos reais de séries públicas
+do setor elétrico brasileiro e 12 conjuntos públicos, **nenhum retreino saudável
+foi bloqueado**. Quando o pipeline quebrou de verdade, bloqueou 16 de 18 casos
+nomeando a variável.
+
+A recíproca não vale: não bloquear não garante que está tudo bem.
+
+## Nomes
+
+A distribuição é `shapeaudit`. Três nomes de import funcionam, e apontam para
+a mesma implementação:
+
+```python
+import shapeaudit      # nome atual
+import modelguard      # nome anterior (pacote `modelguard-ml`), mantido
+import modelcheck      # nome original, mantido por compatibilidade
+```
+
+Quem já usava `modelguard-ml` não precisa mudar código: troque a instalação
+para `shapeaudit` e os imports antigos continuam funcionando.
+
+## Licença
+
+MIT. README em português; a documentação de limites também.

shapeaudit-1.0.2/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

shapeaudit-1.0.2/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

shapeaudit-1.0.2/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)