shapeaudit 1.0.0__py3-none-any.whl

modelcheck/cli.py

@@ -0,0 +1,380 @@
+"""
+cli.py — interface de linha de comando (v1.62)
+
+Projetada para dois usos:
+
+  1. pessoa no terminal    → saída legível, cores quando há tty
+  2. pipeline de CI/CD     → saída JSON, código de saída acionável
+
+CÓDIGOS DE SAÍDA
+----------------
+    0   nenhum problema no nível exigido por --fail-on
+    1   problema encontrado no nível exigido
+    2   erro de execução (arquivo ausente, modelos incompatíveis, etc.)
+
+O código 2 é distinto do 1 de propósito: um pipeline deve tratar "o modelo
+tem problema" de forma diferente de "a auditoria não rodou". Confundir os
+dois faz uma falha de infraestrutura passar por aprovação.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Any, Dict, List, Optional
+
+EXIT_OK, EXIT_FOUND, EXIT_ERROR = 0, 1, 2
+
+_SEV = {"APROVADO": 0, "ATENCAO": 1, "REVISAR": 2, "BLOQUEADO": 3,
+        "INDETERMINADO": 2}
+_NIVEL = {"none": 99, "low": 1, "medium": 2, "high": 3}
+
+
+# ── apresentação ──────────────────────────────────────────────────────
+def _cor(txt: str, cor: str) -> str:
+    """Cor só quando a saída é um terminal — pipes recebem texto limpo."""
+    if not sys.stdout.isatty() or os.environ.get("NO_COLOR"):
+        return txt
+    c = {"red": "31", "yellow": "33", "green": "32", "blue": "36",
+         "grey": "90", "bold": "1"}.get(cor, "0")
+    return f"\033[{c}m{txt}\033[0m"
+
+
+def _icone(verdict: str) -> str:
+    return {"APROVADO": _cor("OK", "green"),
+            "ATENCAO": _cor("!", "yellow"),
+            "REVISAR": _cor("?", "yellow"),
+            "BLOQUEADO": _cor("X", "red")}.get(verdict, "-")
+
+
+def _texto(res: Dict[str, Any]) -> str:
+    """Relatório para leitura humana no terminal."""
+    v = res.get("verdict", "INDETERMINADO")
+    L = [""]
+    L.append(f"  {_icone(v)}  {_cor(v, 'bold')}   {res.get('problem_type','')}")
+
+    raiz = res.get("root_cause_features") or []
+    if raiz:
+        L.append("")
+        L.append(f"  {_cor('Comece por:', 'bold')} " +
+                 ", ".join(_cor(f, "red") for f in raiz))
+        L.append(_cor("  estas variaveis deixaram de influenciar o modelo.",
+                      "grey"))
+
+    div = res.get("divergences") or []
+    outras = [d["feature"] for d in div if d["feature"] not in raiz]
+    if outras:
+        L.append("")
+        L.append("  Mudaram de padrao: " + ", ".join(outras[:6]) +
+                 (f" (+{len(outras)-6})" if len(outras) > 6 else ""))
+
+    snap = res.get("snapshot")
+    if snap:
+        L.append("")
+        L.append(_cor(f"  comparado com: {snap.get('label')} "
+                      f"({str(snap.get('created'))[:10]})", "grey"))
+    ne = res.get("not_evaluated") or []
+    if ne:
+        L.append("")
+        L.append(_cor("  nao verificado nesta auditoria:", "yellow"))
+        for it in ne:
+            L.append(_cor(f"    - {it['layer']}: {it['reason']}", "grey"))
+        L.append(_cor("    (o veredito acima nao cobre estes pontos)", "grey"))
+
+    L.append(_cor(f"  {res.get('n_eval','?')} amostras - "
+                  f"atribuicao por {res.get('representation','?')}", "grey"))
+    L.append("")
+    return "\n".join(L)
+
+
+def _html(res: Dict[str, Any]) -> str:
+    """v1.69: delega ao renderizador de laudo (modelcheck/laudo.py)."""
+    from modelcheck.laudo import render
+    return render(res)
+
+
+def _html_legado(res: Dict[str, Any]) -> str:
+    """Relatorio autocontido, para anexar num ticket ou enviar por e-mail."""
+    v = res.get("verdict", "?")
+    cor = {"APROVADO": "#2E7D57", "ATENCAO": "#B8860B",
+           "REVISAR": "#B8860B", "BLOQUEADO": "#B03A2E"}.get(v, "#555")
+    raiz = res.get("root_cause_features") or []
+    linhas = "".join(
+        f"<tr><td><code>{d['feature']}</code></td><td>{d.get('shape_before')}</td>"
+        f"<td>{d.get('shape_after')}</td><td>{d.get('spread','')}</td></tr>"
+        for d in res.get("divergences", []))
+    col = "".join(
+        f"<tr><td><code>{c['feature']}</code></td>"
+        f"<td>{c.get('importance_before')}</td>"
+        f"<td>{c.get('importance_after')}</td><td>{c.get('ratio')}</td></tr>"
+        for c in res.get("collapses", []))
+    bloco_raiz = ""
+    if raiz:
+        nomes = ", ".join(f"<code>{f}</code>" for f in raiz)
+        bloco_raiz = (f'<div class="box"><b>Comece por:</b> {nomes}<br>'
+                      f'<span style="color:#666">estas variaveis deixaram de '
+                      f'influenciar o modelo.</span></div>')
+    t_col = (f'<h2 style="font-size:17px">Colapso de importancia</h2><table>'
+             f'<tr><th>variavel</th><th>antes</th><th>depois</th>'
+             f'<th>razao</th></tr>{col}</table>') if col else ""
+    t_div = (f'<h2 style="font-size:17px">Mudanca de forma</h2><table>'
+             f'<tr><th>variavel</th><th>antes</th><th>depois</th>'
+             f'<th>espalhamento</th></tr>{linhas}</table>') if linhas else ""
+    ne = res.get("not_evaluated") or []
+    t_ne = ""
+    if ne:
+        itens = "".join(f"<li><b>{i['layer']}</b>: {i['reason']}<br>"
+                        f"<span style='color:#777'>{i.get('consequence','')}"
+                        f"</span></li>" for i in ne)
+        t_ne = (f'<div class="warn"><b>Nao verificado nesta auditoria</b>'
+                f'<ul>{itens}</ul>'
+                f'<span style="color:#777">O resultado acima nao cobre estes '
+                f'pontos.</span></div>')
+
+    snap = res.get("snapshot") or {}
+    t_snap = (f" - comparado com <b>{snap.get('label')}</b> de "
+              f"{str(snap.get('created'))[:10]}") if snap else ""
+    return f"""<!DOCTYPE html><html lang="pt-BR"><head><meta charset="utf-8">
+<title>Auditoria de modelo - {v}</title><style>
+body{{font:15px/1.6 system-ui,-apple-system,sans-serif;max-width:860px;
+margin:40px auto;padding:0 20px;color:#1a1a1a}}
+h1{{font-size:26px;margin:0 0 4px}} .v{{color:{cor};font-weight:700}}
+table{{width:100%;border-collapse:collapse;margin:18px 0;font-size:14px}}
+th,td{{text-align:left;padding:9px 10px;border-bottom:1px solid #e4e4e4}}
+th{{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#666;
+font-weight:500}}
+code{{background:#f4f4f4;padding:1px 5px;border-radius:3px;font-size:13px}}
+.meta{{color:#777;font-size:13px;margin-top:26px;padding-top:14px;
+border-top:1px solid #e4e4e4}}
+.box{{background:#faf9f7;border-left:3px solid {cor};padding:14px 18px;
+margin:18px 0}}
+.warn{{background:#fffdf5;border-left:3px solid #C9A227;padding:12px 18px;
+margin:20px 0;font-size:14px}}
+.warn ul{{margin:8px 0 4px;padding-left:20px}} .warn li{{margin:5px 0}}</style></head><body>
+<h1>Auditoria de modelo</h1>
+<p>Resultado: <span class="v">{v}</span> - {res.get('problem_type','')}</p>
+{bloco_raiz}{t_col}{t_div}{t_ne}
+<div class="meta">{res.get('n_eval','?')} amostras - atribuicao por
+{res.get('representation','?')}{t_snap}
+<br>Gerado por modelcheck. Limites conhecidos em LIMITATIONS.md.</div>
+</body></html>"""
+
+
+def _emitir(res: Dict[str, Any], formato: str, saida: Optional[str]) -> None:
+    txt = {"json": lambda: json.dumps(res, indent=2, ensure_ascii=False),
+           "html": lambda: _html(res),
+           "text": lambda: _texto(res)}[formato]()
+    if saida:
+        with open(saida, "w", encoding="utf-8") as fh:
+            fh.write(txt)
+        if formato != "json":
+            print(_cor(f"relatorio salvo em {saida}", "grey"))
+    else:
+        print(txt)
+
+
+# ── carregamento ──────────────────────────────────────────────────────
+def _carregar_modelo(path: str):
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"modelo nao encontrado: {path}")
+    try:
+        import joblib
+        return joblib.load(path)
+    except Exception:
+        import pickle
+        with open(path, "rb") as fh:
+            return pickle.load(fh)
+
+
+def _carregar_dados(path: str, sep: Optional[str], target: Optional[str]):
+    import pandas as pd
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"dados nao encontrados: {path}")
+    df = pd.read_csv(path, sep=sep or None, engine="python")
+    y = df.pop(target) if target and target in df.columns else None
+    return df, y
+
+
+# ── comandos ──────────────────────────────────────────────────────────
+def _cmd_snapshot_save(a) -> int:
+    from modelcheck import snapshot
+    X, _ = _carregar_dados(a.data, a.sep, a.target)
+    m = _carregar_modelo(a.model)
+    s = snapshot.save(m, X, a.output, label=a.label,
+                      representation=a.representation)
+    print(f"{_cor('OK','green')} snapshot gravado: {a.output}")
+    print(_cor(f"  {s['label']} - {len(s['features'])} variaveis - "
+               f"{s['meta']['n_eval']} amostras - "
+               f"{s['meta']['representation']}", "grey"))
+    return EXIT_OK
+
+
+def _cmd_snapshot_list(a) -> int:
+    from modelcheck import snapshot
+    rows = snapshot.listar(a.dir)
+    if not rows:
+        print(_cor(f"nenhum snapshot em {a.dir}", "grey"))
+        return EXIT_OK
+    print(f"\n  {'arquivo':<26}{'rotulo':<20}{'criado':<12}{'vars':>5}{'n':>8}")
+    print("  " + "-" * 70)
+    for r in rows:
+        print(f"  {r['file']:<26}{str(r['label'])[:19]:<20}"
+              f"{str(r['created'])[:10]:<12}{r['features']:>5}{r['n_eval']:>8}")
+    print()
+    return EXIT_OK
+
+
+def _cmd_diff(a) -> int:
+    from modelcheck import snapshot
+    X, _ = _carregar_dados(a.data, a.sep, a.target)
+    m = _carregar_modelo(a.model)
+    mon = [s.strip() for s in a.monitor.split(",")] if a.monitor else None
+    res = snapshot.diff(a.against, m, X, monitored=mon,
+                        strict_eval=not a.allow_different_eval)
+    _emitir(res, a.format, a.output)
+    return EXIT_FOUND if _SEV.get(res["verdict"], 0) >= \
+        _NIVEL.get(a.fail_on, 99) else EXIT_OK
+
+
+def _cmd_compare(a) -> int:
+    """Compara dois modelos carregados - o modo antigo, ainda util."""
+    from modelcheck import Guard
+    X, y = _carregar_dados(a.data, a.sep, a.target)
+    m1, m2 = _carregar_modelo(a.model_a), _carregar_modelo(a.model_b)
+    mon = [s.strip() for s in a.monitor.split(",")] if a.monitor else None
+    r = Guard().audit(m1, m2, X, y, list(X.columns))
+    res = {"verdict": r.verdict, "problem_type": r.problem_type,
+           "root_cause_features": r.root_cause_features,
+           "divergences": [{"feature": d["feature"],
+                            "shape_before": d.get("shape_v1"),
+                            "shape_after": d.get("shape_v2"),
+                            "spread": d.get("spread")}
+                           for d in r.raw.get("layer1", {})
+                           .get("sdd", {}).get("divs", [])],
+           "collapses": [], "n_eval": len(X),
+           "representation": "shap", "monitored": mon,
+           "not_evaluated": r.not_evaluated}
+    _emitir(res, a.format, a.output)
+    return EXIT_FOUND if _SEV.get(r.verdict, 0) >= \
+        _NIVEL.get(a.fail_on, 99) else EXIT_OK
+
+
+def _cmd_check(a) -> int:
+    """Verificacao de integridade de variaveis - o modo de maior F1."""
+    from modelcheck import Guard
+    X, _ = _carregar_dados(a.data, a.sep, a.target)
+    m1, m2 = _carregar_modelo(a.model_a), _carregar_modelo(a.model_b)
+    mon = [s.strip() for s in a.monitor.split(",")]
+    c = Guard().check_features(m1, m2, X, monitored=mon,
+                               feature_names=list(X.columns))
+    res = {"verdict": "BLOQUEADO" if c["alert"] else "APROVADO",
+           "problem_type": "IMPORTANCE_COLLAPSE" if c["alert"] else "NONE",
+           "root_cause_features": c["collapsed"], "divergences": [],
+           "collapses": [], "monitored": mon, "n_eval": len(X),
+           "representation": "shap",
+           "not_evaluated": [
+               {"layer": "shape divergence",
+                "reason": "modo `check` verifica apenas integridade",
+                "consequence": "mudanca de forma nao foi verificada"},
+               {"layer": "train/serving consistency",
+                "reason": "nao executada no modo `check`",
+                "consequence": "skew de dados nao foi verificado"}]}
+    _emitir(res, a.format, a.output)
+    return EXIT_FOUND if c["alert"] and _NIVEL.get(a.fail_on, 99) <= 3 \
+        else EXIT_OK
+
+
+# ── parser ────────────────────────────────────────────────────────────
+def _add_comuns(sp):
+    sp.add_argument("--sep", default=None, help="CSV separator")
+    sp.add_argument("--target", default=None, help="target column, if present")
+    sp.add_argument("--format", choices=["text", "json", "html"],
+                    default="text")
+    sp.add_argument("-o", "--output", default=None, help="output file")
+    sp.add_argument("--fail-on", choices=["none", "low", "medium", "high"],
+                    default="none",
+                    help="exit 1 from this severity upwards")
+    sp.add_argument("--monitor", default=None,
+                    help="critical features, comma-separated")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="modelcheck",
+        description="Audit what changed between two versions of a model.",
+        epilog="exit codes: 0 clean | 1 problem found | 2 execution error")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sn = sub.add_parser("snapshot", help="save and list snapshots")
+    sn_sub = sn.add_subparsers(dest="sub", required=True)
+
+    s1 = sn_sub.add_parser("save", help="save a model's structural state")
+    s1.add_argument("model")
+    s1.add_argument("data")
+    s1.add_argument("-o", "--output", required=True)
+    s1.add_argument("--label", default=None)
+    s1.add_argument("--sep", default=None)
+    s1.add_argument("--target", default=None)
+    s1.add_argument("--representation", choices=["shap", "ale"],
+                    default="shap")
+    s1.set_defaults(func=_cmd_snapshot_save)
+
+    s2 = sn_sub.add_parser("list", help="list snapshots in a directory")
+    s2.add_argument("dir", nargs="?", default=".")
+    s2.set_defaults(func=_cmd_snapshot_list)
+
+    d = sub.add_parser("diff",
+                       help="compare a model against a saved snapshot")
+    d.add_argument("model")
+    d.add_argument("data")
+    d.add_argument("--against", required=True, help="snapshot file")
+    d.add_argument("--allow-different-eval", action="store_true",
+                   help="allow a different evaluation set (not "
+                        "recommended: measures the gap between sets)")
+    _add_comuns(d)
+    d.set_defaults(func=_cmd_diff)
+
+    c = sub.add_parser("compare", help="compare two loaded models")
+    c.add_argument("model_a")
+    c.add_argument("model_b")
+    c.add_argument("data")
+    _add_comuns(c)
+    c.set_defaults(func=_cmd_compare)
+
+    k = sub.add_parser("check",
+                       help="check integrity of critical features")
+    k.add_argument("model_a")
+    k.add_argument("model_b")
+    k.add_argument("data")
+    _add_comuns(k)
+    k.set_defaults(func=_cmd_check)
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.cmd == "check" and not getattr(args, "monitor", None):
+        print(_cor("error: `check` requires --monitor with the critical features",
+                   "red"), file=sys.stderr)
+        return EXIT_ERROR
+    try:
+        return args.func(args)
+    except (FileNotFoundError, ValueError, TypeError) as e:
+        print(f"{_cor('erro:', 'red')} {e}", file=sys.stderr)
+        return EXIT_ERROR
+    except KeyboardInterrupt:
+        print(_cor("\ninterrompido", "grey"), file=sys.stderr)
+        return EXIT_ERROR
+    except Exception as e:
+        print(f"{_cor('erro inesperado:', 'red')} {type(e).__name__}: {e}",
+              file=sys.stderr)
+        print(_cor("  para o traceback completo: MODELCHECK_DEBUG=1",
+                   "grey"), file=sys.stderr)
+        if os.environ.get("MODELCHECK_DEBUG"):
+            raise
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

modelcheck/compare/model_comparator.py

@@ -0,0 +1,47 @@
+"""Compara feature importance entre múltiplos modelos."""
+import pandas as pd
+
+from modelcheck.explainers.shap_explainer import ShapExplainer
+
+
+class ModelComparator:
+    def __init__(self, models: dict, X_background, max_shap_rows=2000):
+        self.models = models
+        self.X_background = X_background
+        self.max_shap_rows = max_shap_rows
+        self.importances = {}
+
+    def compute_all(self, X):
+        for name, model in self.models.items():
+            explainer = ShapExplainer(model, self.X_background,
+                                      max_shap_rows=self.max_shap_rows)
+            self.importances[name] = explainer.feature_importance(X)
+        return self.importances
+
+    def build_comparison_table(self):
+        tables = []
+        for model_name, importance_df in self.importances.items():
+            renamed = importance_df.rename(
+                columns={"mean_abs_shap": model_name}
+            )
+            tables.append(renamed.set_index("feature"))
+
+        comparison = pd.concat(tables, axis=1)
+        return comparison
+
+    def find_divergences(self, threshold=0.3):
+        comparison = self.build_comparison_table()
+        normalized = comparison.div(comparison.max(axis=0), axis=1)
+
+        divergences = []
+        for feature in normalized.index:
+            row = normalized.loc[feature]
+            spread = row.max() - row.min()
+            if spread > threshold:
+                divergences.append({
+                    "feature": feature,
+                    "spread": round(spread, 3),
+                    "values": row.to_dict(),
+                })
+
+        return divergences

modelcheck/confidence.py

@@ -0,0 +1,158 @@
+"""
+confidence.py — Intervalos de confiança para scores do ModelGuard
+
+Motivação (Revisão Crítica, lacuna A):
+  Nenhum score tinha IC. Não era possível afirmar que score 58.2 e 71.8
+  são estatisticamente distintos. Sem isso, o benchmark não é publicável.
+
+Método: bootstrap não-paramétrico sobre X_eval (reamostragem com
+reposição), recalculando o score em cada réplica. Retorna média, mediana,
+IC percentil e desvio.
+
+CALIBRAÇÃO MEDIDA (v1.35) — leia antes de usar o IC em decisão:
+
+Cobertura empírica com nominal de 95%, contra o score da população
+(5.000 amostras), 18 repetições por condição, n_eval=150:
+
+    par divergente:     cobertura 100%   largura média 23.1 pts
+    par de controle:    cobertura 100%   largura média 44.5 pts
+
+O IC é CONSERVADOR (sobre-cobertura), não anticonservador. Não há risco de
+falsa precisão — o risco é o oposto: intervalos largos demais, com pouco
+poder de discriminação.
+
+Causa: o Health Score é DISCRETO (múltiplos de ~5 e ~15 pontos, conforme a
+contagem de alertas). O bootstrap percentil sobre uma estatística discreta
+produz intervalos que saltam de degrau em degrau, sempre englobando o valor
+verdadeiro. Um IC de 44.5 pontos numa escala de 0-100 é quase metade da
+escala.
+
+CONSEQUÊNCIA PRÁTICA: use o IC para afirmar que dois cenários NÃO são
+distinguíveis (a sobreposição é conclusiva). Não o use para afirmar que
+são distinguíveis com 95% de confiança — a sobre-cobertura torna o teste
+excessivamente permissivo nessa direção. Para comparação, prefira
+`compare_scores_ci`, que usa o teste bootstrap da diferença (`boot_p`)
+em vez da sobreposição de intervalos.
+
+Uso:
+    from modelcheck.confidence import score_with_ci, compare_scores_ci
+    r = score_with_ci(audit, model_v1, model_v2, X_eval, n_boot=50)
+    print(r['summary'])
+"""
+import numpy as np
+import pandas as pd
+from typing import Callable, Optional, List
+
+
+def score_with_ci(score_fn: Callable,
+                  model_v1, model_v2,
+                  X_eval: pd.DataFrame,
+                  y_eval: Optional[pd.Series] = None,
+                  feature_names: Optional[List[str]] = None,
+                  n_boot: int = 50,
+                  alpha: float = 0.05,
+                  score_key: str = 'health_score',
+                  seed: int = 0) -> dict:
+    """
+    Calcula IC bootstrap para qualquer função de score.
+
+    score_fn deve aceitar (m1, m2, X, y, feature_names) ou (m1, m2, X)
+    e retornar dict contendo score_key.
+    """
+    if feature_names is None:
+        feature_names = list(X_eval.columns)
+
+    rng = np.random.RandomState(seed)
+    scores, n_fail = [], 0
+
+    for b in range(n_boot):
+        idx = rng.choice(len(X_eval), len(X_eval), replace=True)
+        Xb = X_eval.iloc[idx].reset_index(drop=True)
+        yb = (y_eval.iloc[idx].reset_index(drop=True)
+              if y_eval is not None else None)
+        try:
+            try:
+                out = score_fn(model_v1, model_v2, Xb, yb, feature_names)
+            except TypeError:
+                out = score_fn(model_v1, model_v2, Xb)
+            s = out.get(score_key)
+            scores.append(np.nan if s is None else float(s))
+        except Exception:
+            n_fail += 1
+            scores.append(np.nan)
+
+    arr = np.array(scores, dtype=float)
+    valid = arr[~np.isnan(arr)]
+    if len(valid) == 0:
+        return {'error': 'todas as réplicas falharam', 'n_fail': n_fail}
+
+    lo = float(np.percentile(valid, 100 * alpha / 2))
+    hi = float(np.percentile(valid, 100 * (1 - alpha / 2)))
+    mean = float(valid.mean())
+
+    return {
+        'mean':       round(mean, 2),
+        'median':     round(float(np.median(valid)), 2),
+        'std':        round(float(valid.std()), 2),
+        'ci_low':     round(lo, 2),
+        'ci_high':    round(hi, 2),
+        'ci_width':   round(hi - lo, 2),
+        'n_boot':     n_boot,
+        'n_valid':    int(len(valid)),
+        'n_fail':     n_fail,
+        'alpha':      alpha,
+        'scores':     valid.tolist(),
+        'summary':    (f"{mean:.1f} "
+                       f"[IC{int((1-alpha)*100)}: {lo:.1f}–{hi:.1f}]"),
+    }
+
+
+def compare_scores_ci(ci_a: dict, ci_b: dict,
+                      label_a: str = "A", label_b: str = "B") -> dict:
+    """
+    Testa se dois scores com IC são estatisticamente distintos.
+
+    Dois critérios:
+      overlap      — ICs se sobrepõem? (critério conservador, informal)
+      boot_p       — proporção de réplicas em que a >= b (teste bootstrap)
+    """
+    a = np.array(ci_a.get('scores', []), dtype=float)
+    b = np.array(ci_b.get('scores', []), dtype=float)
+    overlap = not (ci_a['ci_high'] < ci_b['ci_low'] or
+                   ci_b['ci_high'] < ci_a['ci_low'])
+
+    boot_p = None
+    if len(a) > 0 and len(b) > 0:
+        n = min(len(a), len(b))
+        diff = a[:n] - b[:n]
+        m = float(diff.mean())
+        # BUG CORRIGIDO (v1.35): a versão anterior usava
+        #     p = 2 * min(frac(diff>=0), 1-frac(diff>=0))
+        # que devolve p=0 quando TODAS as diferenças são zero — declarando
+        # "altamente significativo" exatamente no caso de nenhuma diferença.
+        # Pego pelo teste de dois controles idênticos.
+        if np.allclose(diff, 0.0):
+            boot_p = 1.0
+        else:
+            # proporção de réplicas com sinal oposto à diferença média,
+            # contando empates como metade; correção de continuidade (+1)
+            oposto = float((np.sign(diff) != np.sign(m)).sum()
+                           - 0.5 * float((diff == 0).sum()))
+            oposto = max(oposto, 0.0)
+            boot_p = round(min(1.0, 2 * (oposto + 1) / (n + 1)), 4)
+
+    return {
+        'label_a':      label_a,
+        'label_b':      label_b,
+        'mean_a':       ci_a['mean'],
+        'mean_b':       ci_b['mean'],
+        'delta':        round(ci_a['mean'] - ci_b['mean'], 2),
+        'ci_overlap':   overlap,
+        'boot_p':       boot_p,
+        'distinct':     bool((not overlap) or
+                             (boot_p is not None and boot_p < 0.05)),
+        'summary':      (f"{label_a}={ci_a['summary']} vs "
+                         f"{label_b}={ci_b['summary']} → "
+                         f"{'DISTINTOS' if ((not overlap) or (boot_p is not None and boot_p < 0.05)) else 'NÃO distinguíveis'}"
+                         + (f" (p={boot_p})" if boot_p is not None else "")),
+    }