graph-explain 0.7.1__tar.gz → 0.7.3__tar.gz

{graph_explain-0.7.1/src/graph_explain.egg-info → graph_explain-0.7.3}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: graph-explain
-Version: 0.7.1
+Version: 0.7.3
 Summary: Explainability library for graph-based models (GNN)
 Author: graph-explain contributors
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Tzinny-dev/graph-explain
 Project-URL: Repository, https://github.com/Tzinny-dev/graph-explain
-Project-URL: Documentation, https://github.com/Tzinny-dev/graph-explain#readme
+Project-URL: Documentation, https://tzinny-dev.github.io/graph-explain/
 Keywords: gnn,explainability,xai,graph,neural-networks,interpretability
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
@@ -36,6 +36,7 @@ Requires-Dist: pyvis>=0.3; extra == "interactive"
 Provides-Extra: all
 Requires-Dist: torch>=2.0; extra == "all"
 Requires-Dist: torch-geometric>=2.5; extra == "all"
+Requires-Dist: dgl>=2.0; extra == "all"
 Requires-Dist: plotly>=5.15; extra == "all"
 Requires-Dist: pyvis>=0.3; extra == "all"
 Provides-Extra: dev
@@ -51,6 +52,12 @@ Dynamic: license-file
 
 # graph-explain
 
+[![CI](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml/badge.svg)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![docs](https://github.com/Tzinny-dev/graph-explain/actions/workflows/docs.yml/badge.svg)](https://tzinny-dev.github.io/graph-explain/)
+[![PyPI](https://img.shields.io/pypi/v/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![Python](https://img.shields.io/pypi/pyversions/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Tzinny-dev/graph-explain/blob/main/LICENSE)
+
 Explainability library for graph-based models (Graph Neural Networks).
 Explains a GNN's predictions in terms of **important nodes, edges and subgraphs**,
 with built-in metrics and visualization.
@@ -119,6 +126,9 @@ pip install -e .[all]
 Optional extras: `pyg` (PyTorch Geometric), `dgl` (DGL backend),
 `interactive` (plotly/pyvis).
 
+> 📚 **Documentation**: full API reference and guides at
+> https://tzinny-dev.github.io/graph-explain/
+
 ## Quick start
 
 ```python
@@ -319,19 +329,9 @@ Node-only methods (`GraphLIME`, `NodeMask`, `Attention`, `GNNGatedLRP`,
 
 ## Roadmap
 
-- [x] Phase 2: PGExplainer, SubgraphX, Integrated Gradients
-- [x] Phase 2: interactive visualization (pyvis → HTML)
-- [x] Phase 3: full metrics (fidelity±, stability, GEA)
-- [x] Phase 3: DGL backend (adapter; integration validated with DGL 2.1 + torch 2.2.1)
-- [x] Phase 4: GNN-LRP (layer-wise relevance for GCNs; validates the house motif in BA-Shapes)
-- [x] Phase 4: counterfactual explanations (minimal edge/feature removal that changes the class)
-- [x] Phase 4: LLM narration (`describe` deterministic + pluggable `narrate` LLM)
-- [x] Phase 5: full CLI (all methods, metrics, narration and JSON export)
-- [x] Phase 6: more methods (DeepLIFT rescale, Attention/GAT, Gradient×Input)
-- [x] Phase 7: comparative benchmark (`compare` + CLI `bench` subcommand, table and JSON/HTML reports)
-- [x] Phase 8: more methods (GraphLIME, NodeMask, GuidedBackprop and Random baseline)
-- [x] Phase 10: graph-level explanations (graph-classification dataset with house
-  motif, graph-level GEA, CLI/bench without `--node` and `graph_level` flag)
+Planned ideas (real-world Datasets, more methods, robustness metrics) are
+tracked as issues in the repository — see
+https://github.com/Tzinny-dev/graph-explain/issues
 
 ## License
 

{graph_explain-0.7.1 → graph_explain-0.7.3}/README.md

@@ -1,5 +1,11 @@
 # graph-explain
 
+[![CI](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml/badge.svg)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![docs](https://github.com/Tzinny-dev/graph-explain/actions/workflows/docs.yml/badge.svg)](https://tzinny-dev.github.io/graph-explain/)
+[![PyPI](https://img.shields.io/pypi/v/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![Python](https://img.shields.io/pypi/pyversions/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Tzinny-dev/graph-explain/blob/main/LICENSE)
+
 Explainability library for graph-based models (Graph Neural Networks).
 Explains a GNN's predictions in terms of **important nodes, edges and subgraphs**,
 with built-in metrics and visualization.
@@ -68,6 +74,9 @@ pip install -e .[all]
 Optional extras: `pyg` (PyTorch Geometric), `dgl` (DGL backend),
 `interactive` (plotly/pyvis).
 
+> 📚 **Documentation**: full API reference and guides at
+> https://tzinny-dev.github.io/graph-explain/
+
 ## Quick start
 
 ```python
@@ -268,19 +277,9 @@ Node-only methods (`GraphLIME`, `NodeMask`, `Attention`, `GNNGatedLRP`,
 
 ## Roadmap
 
-- [x] Phase 2: PGExplainer, SubgraphX, Integrated Gradients
-- [x] Phase 2: interactive visualization (pyvis → HTML)
-- [x] Phase 3: full metrics (fidelity±, stability, GEA)
-- [x] Phase 3: DGL backend (adapter; integration validated with DGL 2.1 + torch 2.2.1)
-- [x] Phase 4: GNN-LRP (layer-wise relevance for GCNs; validates the house motif in BA-Shapes)
-- [x] Phase 4: counterfactual explanations (minimal edge/feature removal that changes the class)
-- [x] Phase 4: LLM narration (`describe` deterministic + pluggable `narrate` LLM)
-- [x] Phase 5: full CLI (all methods, metrics, narration and JSON export)
-- [x] Phase 6: more methods (DeepLIFT rescale, Attention/GAT, Gradient×Input)
-- [x] Phase 7: comparative benchmark (`compare` + CLI `bench` subcommand, table and JSON/HTML reports)
-- [x] Phase 8: more methods (GraphLIME, NodeMask, GuidedBackprop and Random baseline)
-- [x] Phase 10: graph-level explanations (graph-classification dataset with house
-  motif, graph-level GEA, CLI/bench without `--node` and `graph_level` flag)
+Planned ideas (real-world Datasets, more methods, robustness metrics) are
+tracked as issues in the repository — see
+https://github.com/Tzinny-dev/graph-explain/issues
 
 ## License
 

{graph_explain-0.7.1 → graph_explain-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graph-explain"
-version = "0.7.1"
+version = "0.7.3"
 description = "Explainability library for graph-based models (GNN)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -41,13 +41,13 @@ dependencies = [
 [project.urls]
 Homepage = "https://github.com/Tzinny-dev/graph-explain"
 Repository = "https://github.com/Tzinny-dev/graph-explain"
-Documentation = "https://github.com/Tzinny-dev/graph-explain#readme"
+Documentation = "https://tzinny-dev.github.io/graph-explain/"
 
 [project.optional-dependencies]
 pyg = ["torch>=2.0", "torch-geometric>=2.5"]
 dgl = ["torch>=2.0", "dgl>=2.0"]
 interactive = ["plotly>=5.15", "pyvis>=0.3"]
-all = ["torch>=2.0", "torch-geometric>=2.5", "plotly>=5.15", "pyvis>=0.3"]
+all = ["torch>=2.0", "torch-geometric>=2.5", "dgl>=2.0", "plotly>=5.15", "pyvis>=0.3"]
 dev = ["pytest>=7.0", "ruff>=0.5", "build>=1.0"]
 docs = ["sphinx>=7.2", "sphinx-rtd-theme>=2.0"]
 publish = ["twine>=5.0"]

{graph_explain-0.7.1 → graph_explain-0.7.3}/src/graph_explain/__init__.py

@@ -35,7 +35,7 @@ from .methods import (
 from .narration import Narrator, describe, narrate, summarize
 from .visualization import show, visualize_interactive, visualize_static
 
-__version__ = "0.7.1"
+__version__ = "0.7.3"
 
 __all__ = [
     "AttentionExplainer",

graph_explain-0.7.3/src/graph_explain/narration/narrator.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+import torch
+
+
+def _top_values(importance, k: int) -> list[tuple[int, float]]:
+    imp = importance.detach().reshape(-1)
+    n = int(imp.numel())
+    k = max(1, min(int(k), n))
+    idx = imp.argsort(descending=True)[:k]
+    return [(int(i), float(imp[i])) for i in idx.tolist()]
+
+
+def _data_context(explanation, data: Any | None):
+    if data is None:
+        data = explanation.metadata.get("backing_data")
+    backend = explanation.metadata.get("backend")
+    return backend, data
+
+
+def _labels(explanation, data: Any | None) -> Any | None:
+    backend, data = _data_context(explanation, data)
+    if backend is None or data is None:
+        return None
+    try:
+        return backend.node_labels(data)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _edge_index(data, backend) -> Any | None:
+    if backend is not None and data is not None:
+        try:
+            return backend.edge_index(data)
+        except Exception:  # noqa: BLE001
+            return None
+    return None
+
+
+_SUPPORTED_LANGS = ("es", "en")
+
+_TEMPLATES: dict[str, dict[str, str]] = {
+    "es": {
+        "graph_head": "Explicación a nivel de grafo.",
+        "node_head": "Explicación del nodo {node}.",
+        "target": " La clase objetivo es {target}.",
+        "correct": " La predicción del modelo es correcta.",
+        "incorrect": " La predicción del modelo difiere de la etiqueta real.",
+        "nodes": "Los nodos más relevantes son {nodes}.",
+        "edges": " Las aristas más relevantes son {edges}.",
+        "node_item": "nodo {i} (importancia {v:.3f})",
+        "edge_item": "arista {u}-{v} ({w:.3f})",
+        "edge_item_float": "arista con relevancia {v:.3f}",
+        "cf_intro": " Se necesitaron {n} cambios (aristas/features eliminadas) "
+        "para cambiar la predicción de {change}.",
+        "cf_change": "la clase {orig} a la clase {new}",
+        "cf_change_solo": "la clase {orig}",
+        "nodata": "Sin datos suficientes para describir la explicación.",
+        "prompt": "Eres un asistente que explica predicciones de GNNs en lenguaje "
+        "natural. Dado este resumen de una explicación (JSON), escribe un párrafo "
+        "breve en español (2-4 oraciones) describiendo qué hace el modelo y qué "
+        "evidencia respalda su predicción. Resumen:\n",
+        "llm_fallback": "[LLM no disponible: {exc}]",
+    },
+    "en": {
+        "graph_head": "Graph-level explanation.",
+        "node_head": "Explanation of node {node}.",
+        "target": " The target class is {target}.",
+        "correct": " The model prediction is correct.",
+        "incorrect": " The model prediction differs from the true label.",
+        "nodes": "The most relevant nodes are {nodes}.",
+        "edges": " The most relevant edges are {edges}.",
+        "node_item": "node {i} (importance {v:.3f})",
+        "edge_item": "edge {u}-{v} ({w:.3f})",
+        "edge_item_float": "edge with relevance {v:.3f}",
+        "cf_intro": " {n} changes (removed edges/features) were needed to change the "
+        "prediction from {change}.",
+        "cf_change": "class {orig} to class {new}",
+        "cf_change_solo": "class {orig}",
+        "nodata": "Not enough data to describe the explanation.",
+        "prompt": "You are an assistant that explains GNN predictions in natural "
+        "language. Given this JSON summary of an explanation, write a brief "
+        "paragraph (2-4 sentences) in English describing what the model does and "
+        "what evidence supports its prediction. Summary:\n",
+        "llm_fallback": "[LLM unavailable: {exc}]",
+    },
+}
+
+
+def _templates(lang: str) -> dict[str, str]:
+    if lang not in _SUPPORTED_LANGS:
+        raise ValueError(f"lang must be one of {_SUPPORTED_LANGS}, got {lang!r}")
+    return _TEMPLATES[lang]
+
+
+def summarize(explanation, data: Any | None = None, top_k: int = 5) -> dict[str, Any]:
+    """Structured summary of an explanation (for narration or JSON)."""
+    backend, data = _data_context(explanation, data)
+    node = explanation.node_idx
+    target = explanation.target_class
+    pred = None
+    if explanation.prediction_original is not None:
+        p = explanation.prediction_original
+        if torch.is_tensor(p):
+            pred = int(p.reshape(-1).argmax().item())
+    labels = _labels(explanation, data)
+
+    true_label = None
+    if labels is not None and node is not None:
+        try:
+            true_label = int(labels[node].item())
+        except Exception:  # noqa: BLE001
+            true_label = None
+
+    summary: dict[str, Any] = {
+        "node": None if node is None else int(node),
+        "target_class": target,
+        "predicted_class": pred,
+        "true_class": true_label,
+        "correct": (
+            None if pred is None or true_label is None else bool(pred == true_label)
+        ),
+        "important_nodes": (
+            _top_values(explanation.node_importance, top_k)
+            if explanation.node_importance is not None
+            else []
+        ),
+        "important_edges": [],
+        "counterfactual": bool(explanation.metadata.get("counterfactual", False)),
+    }
+    if explanation.edge_importance is not None:
+        ei = _edge_index(data, backend)
+        top = _top_values(explanation.edge_importance, top_k)
+        if ei is None:
+            summary["important_edges"] = [v for _, v in top]
+        else:
+            summary["important_edges"] = [
+                (int(ei[0, i]), int(ei[1, i]), v) for i, v in top
+            ]
+    if summary["counterfactual"]:
+        summary["original_class"] = explanation.metadata.get("original_class")
+    return summary
+
+
+def describe(
+    explanation, data: Any | None = None, top_k: int = 5, lang: str = "es"
+) -> str:
+    """Deterministic template-based narration of an explanation.
+
+    Args:
+        lang: Template language, ``"es"`` (default) or ``"en"``.
+    """
+    _T = _templates(lang)
+    s = summarize(explanation, data, top_k)
+    node = s["node"]
+    target = (
+        s["target_class"] if s["target_class"] is not None else s["predicted_class"]
+    )
+
+    if node is None:
+        head = _T["graph_head"]
+    else:
+        head = _T["node_head"].format(node=node)
+    if target is not None:
+        head += _T["target"].format(target=target)
+    if s["correct"] is True:
+        head += _T["correct"]
+    elif s["correct"] is False:
+        head += _T["incorrect"]
+
+    nodes_txt = ", ".join(
+        _T["node_item"].format(i=i, v=v) for i, v in s["important_nodes"]
+    )
+    tail = _T["nodes"].format(nodes=nodes_txt) if nodes_txt else ""
+
+    if s["important_edges"]:
+        pieces = []
+        for e in s["important_edges"]:
+            if len(e) == 3:
+                u, v, w = e
+                pieces.append(_T["edge_item"].format(u=u, v=v, w=w))
+            else:
+                pieces.append(_T["edge_item_float"].format(v=float(e)))
+        tail += _T["edges"].format(edges=", ".join(pieces))
+
+    if s["counterfactual"]:
+        n = len(s["important_edges"])
+        new_class = s["predicted_class"]
+        if new_class is not None:
+            change = _T["cf_change"].format(orig=s["original_class"], new=new_class)
+        else:
+            change = _T["cf_change_solo"].format(orig=s["original_class"])
+        tail += _T["cf_intro"].format(n=n, change=change)
+    if tail:
+        head += " " + tail.strip()
+    return head.strip() or _T["nodata"]
+
+
+def _prompt(summary: dict[str, Any], lang: str = "es") -> str:
+    _T = _templates(lang)
+    return _T["prompt"] + json.dumps(summary, ensure_ascii=False, indent=2)
+
+
+def narrate(
+    explanation,
+    llm: Callable[[str], str] | None = None,
+    data: Any | None = None,
+    top_k: int = 5,
+    lang: str = "es",
+) -> str:
+    """Narrates an explanation. With `llm` (a `prompt -> text` callable) it uses the
+    generative model's output; otherwise it falls back to deterministic
+    template-based narration."""
+    _T = _templates(lang)
+    summary = summarize(explanation, data, top_k)
+    deterministic = describe(explanation, data, top_k, lang=lang)
+    if llm is None:
+        return deterministic
+    try:
+        return llm(_prompt(summary, lang)).strip()
+    except Exception as exc:  # noqa: BLE001
+        return f"{deterministic}\n\n{_T['llm_fallback'].format(exc=exc)}"
+
+
+class Narrator:
+    """Reusable narrator; lets you inject the LLM just once."""
+
+    def __init__(
+        self,
+        llm: Callable[[str], str] | None = None,
+        top_k: int = 5,
+        lang: str = "es",
+    ):
+        self.llm = llm
+        self.top_k = top_k
+        self.lang = lang
+
+    def describe(self, explanation, data: Any | None = None) -> str:
+        return describe(explanation, data, self.top_k, lang=self.lang)
+
+    def narrate(self, explanation, data: Any | None = None) -> str:
+        return narrate(explanation, self.llm, data, self.top_k, lang=self.lang)

{graph_explain-0.7.1 → graph_explain-0.7.3/src/graph_explain.egg-info}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: graph-explain
-Version: 0.7.1
+Version: 0.7.3
 Summary: Explainability library for graph-based models (GNN)
 Author: graph-explain contributors
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Tzinny-dev/graph-explain
 Project-URL: Repository, https://github.com/Tzinny-dev/graph-explain
-Project-URL: Documentation, https://github.com/Tzinny-dev/graph-explain#readme
+Project-URL: Documentation, https://tzinny-dev.github.io/graph-explain/
 Keywords: gnn,explainability,xai,graph,neural-networks,interpretability
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
@@ -36,6 +36,7 @@ Requires-Dist: pyvis>=0.3; extra == "interactive"
 Provides-Extra: all
 Requires-Dist: torch>=2.0; extra == "all"
 Requires-Dist: torch-geometric>=2.5; extra == "all"
+Requires-Dist: dgl>=2.0; extra == "all"
 Requires-Dist: plotly>=5.15; extra == "all"
 Requires-Dist: pyvis>=0.3; extra == "all"
 Provides-Extra: dev
@@ -51,6 +52,12 @@ Dynamic: license-file
 
 # graph-explain
 
+[![CI](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml/badge.svg)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![docs](https://github.com/Tzinny-dev/graph-explain/actions/workflows/docs.yml/badge.svg)](https://tzinny-dev.github.io/graph-explain/)
+[![PyPI](https://img.shields.io/pypi/v/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![Python](https://img.shields.io/pypi/pyversions/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Tzinny-dev/graph-explain/blob/main/LICENSE)
+
 Explainability library for graph-based models (Graph Neural Networks).
 Explains a GNN's predictions in terms of **important nodes, edges and subgraphs**,
 with built-in metrics and visualization.
@@ -119,6 +126,9 @@ pip install -e .[all]
 Optional extras: `pyg` (PyTorch Geometric), `dgl` (DGL backend),
 `interactive` (plotly/pyvis).
 
+> 📚 **Documentation**: full API reference and guides at
+> https://tzinny-dev.github.io/graph-explain/
+
 ## Quick start
 
 ```python
@@ -319,19 +329,9 @@ Node-only methods (`GraphLIME`, `NodeMask`, `Attention`, `GNNGatedLRP`,
 
 ## Roadmap
 
-- [x] Phase 2: PGExplainer, SubgraphX, Integrated Gradients
-- [x] Phase 2: interactive visualization (pyvis → HTML)
-- [x] Phase 3: full metrics (fidelity±, stability, GEA)
-- [x] Phase 3: DGL backend (adapter; integration validated with DGL 2.1 + torch 2.2.1)
-- [x] Phase 4: GNN-LRP (layer-wise relevance for GCNs; validates the house motif in BA-Shapes)
-- [x] Phase 4: counterfactual explanations (minimal edge/feature removal that changes the class)
-- [x] Phase 4: LLM narration (`describe` deterministic + pluggable `narrate` LLM)
-- [x] Phase 5: full CLI (all methods, metrics, narration and JSON export)
-- [x] Phase 6: more methods (DeepLIFT rescale, Attention/GAT, Gradient×Input)
-- [x] Phase 7: comparative benchmark (`compare` + CLI `bench` subcommand, table and JSON/HTML reports)
-- [x] Phase 8: more methods (GraphLIME, NodeMask, GuidedBackprop and Random baseline)
-- [x] Phase 10: graph-level explanations (graph-classification dataset with house
-  motif, graph-level GEA, CLI/bench without `--node` and `graph_level` flag)
+Planned ideas (real-world Datasets, more methods, robustness metrics) are
+tracked as issues in the repository — see
+https://github.com/Tzinny-dev/graph-explain/issues
 
 ## License
 

{graph_explain-0.7.1 → graph_explain-0.7.3}/src/graph_explain.egg-info/requires.txt

@@ -6,6 +6,7 @@ torch>=2.0
 [all]
 torch>=2.0
 torch-geometric>=2.5
+dgl>=2.0
 plotly>=5.15
 pyvis>=0.3
 

{graph_explain-0.7.1 → graph_explain-0.7.3}/tests/test_narration.py

@@ -74,3 +74,49 @@ class TestNarration:
         _, expl = self._setup()
         narrator = Narrator(llm=None)
         assert narrator.describe(expl) == describe(expl)
+
+    def test_describe_english(self):
+        data, expl = self._setup()
+        text = describe(expl, data=data, lang="en")
+        assert "node" in text
+        assert "class" in text
+        assert "most relevant" in text
+        assert text == describe(expl, data=data, lang="en")  # determinista
+
+    def test_english_vs_spanish(self):
+        data, expl = self._setup()
+        es = describe(expl, data=data, lang="es")
+        en = describe(expl, data=data, lang="en")
+        assert es != en
+        assert "nodo" in es and "node" in en
+
+    def test_narrate_with_llm_english(self):
+        _, expl = self._setup()
+
+        def fake_llm(prompt):
+            return "CUSTOM NARRATION"
+
+        text = narrate(expl, llm=fake_llm, lang="en")
+        assert text == "CUSTOM NARRATION"
+
+    def test_narrate_fallback_english(self):
+        _, expl = self._setup()
+
+        def broken_llm(_prompt):
+            raise RuntimeError("no api")
+
+        text = narrate(expl, llm=broken_llm, lang="en")
+        assert "LLM unavailable" in text
+        assert "Explanation of node" in text
+
+    def test_invalid_lang(self):
+        import pytest
+
+        _, expl = self._setup()
+        with pytest.raises(ValueError):
+            describe(expl, lang="fr")
+
+    def test_narrator_class_english(self):
+        _, expl = self._setup()
+        narrator = Narrator(llm=None, lang="en")
+        assert narrator.describe(expl) == describe(expl, lang="en")

graph_explain-0.7.1/src/graph_explain/narration/narrator.py

@@ -1,185 +0,0 @@
-from __future__ import annotations
-
-import json
-from collections.abc import Callable
-from typing import Any
-
-import torch
-
-
-def _top_values(importance, k: int) -> list[tuple[int, float]]:
-    imp = importance.detach().reshape(-1)
-    n = int(imp.numel())
-    k = max(1, min(int(k), n))
-    idx = imp.argsort(descending=True)[:k]
-    return [(int(i), float(imp[i])) for i in idx.tolist()]
-
-
-def _data_context(explanation, data: Any | None):
-    if data is None:
-        data = explanation.metadata.get("backing_data")
-    backend = explanation.metadata.get("backend")
-    return backend, data
-
-
-def _labels(explanation, data: Any | None) -> Any | None:
-    backend, data = _data_context(explanation, data)
-    if backend is None or data is None:
-        return None
-    try:
-        return backend.node_labels(data)
-    except Exception:  # noqa: BLE001
-        return None
-
-
-def _edge_index(data, backend) -> Any | None:
-    if backend is not None and data is not None:
-        try:
-            return backend.edge_index(data)
-        except Exception:  # noqa: BLE001
-            return None
-    return None
-
-
-def summarize(explanation, data: Any | None = None, top_k: int = 5) -> dict[str, Any]:
-    """Structured summary of an explanation (for narration or JSON)."""
-    backend, data = _data_context(explanation, data)
-    node = explanation.node_idx
-    target = explanation.target_class
-    pred = None
-    if explanation.prediction_original is not None:
-        p = explanation.prediction_original
-        if torch.is_tensor(p):
-            pred = int(p.reshape(-1).argmax().item())
-    labels = _labels(explanation, data)
-
-    true_label = None
-    if labels is not None and node is not None:
-        try:
-            true_label = int(labels[node].item())
-        except Exception:  # noqa: BLE001
-            true_label = None
-
-    summary: dict[str, Any] = {
-        "node": None if node is None else int(node),
-        "target_class": target,
-        "predicted_class": pred,
-        "true_class": true_label,
-        "correct": (
-            None if pred is None or true_label is None else bool(pred == true_label)
-        ),
-        "important_nodes": (
-            _top_values(explanation.node_importance, top_k)
-            if explanation.node_importance is not None
-            else []
-        ),
-        "important_edges": [],
-        "counterfactual": bool(explanation.metadata.get("counterfactual", False)),
-    }
-    if explanation.edge_importance is not None:
-        ei = _edge_index(data, backend)
-        top = _top_values(explanation.edge_importance, top_k)
-        if ei is None:
-            summary["important_edges"] = [v for _, v in top]
-        else:
-            summary["important_edges"] = [
-                (int(ei[0, i]), int(ei[1, i]), v) for i, v in top
-            ]
-    if summary["counterfactual"]:
-        summary["original_class"] = explanation.metadata.get("original_class")
-    return summary
-
-
-def describe(explanation, data: Any | None = None, top_k: int = 5) -> str:
-    """Deterministic template-based narration of an explanation (Spanish by default)."""
-    s = summarize(explanation, data, top_k)
-    node = s["node"]
-    target = (
-        s["target_class"] if s["target_class"] is not None else s["predicted_class"]
-    )
-
-    if node is None:
-        head = "Explicación a nivel de grafo."
-    else:
-        head = f"Explicación del nodo {node}."
-    if target is not None:
-        head += f" La clase objetivo es {target}."
-    if s["correct"] is True:
-        head += " La predicción del modelo es correcta."
-    elif s["correct"] is False:
-        head += " La predicción del modelo difiere de la etiqueta real."
-
-    nodes_txt = ", ".join(
-        f"nodo {i} (importancia {v:.3f})" for i, v in s["important_nodes"]
-    )
-    tail = f"Los nodos más relevantes son {nodes_txt}." if nodes_txt else ""
-
-    if s["important_edges"]:
-        pieces = []
-        for e in s["important_edges"]:
-            if len(e) == 3:
-                u, v, w = e
-                pieces.append(f"arista {u}-{v} ({w:.3f})")
-            else:
-                pieces.append(f"arista con relevancia {float(e):.3f}")
-        tail += " Las aristas más relevantes son " + ", ".join(pieces) + "."
-
-    if s["counterfactual"]:
-        n = len(s["important_edges"])
-        new_class = s["predicted_class"]
-        change = (
-            f"la clase {s['original_class']} a la clase {new_class}"
-            if new_class is not None
-            else f"la clase {s['original_class']}"
-        )
-        tail += (
-            f" Se necesitaron {n} cambios"
-            f" (aristas/features eliminadas) para cambiar la predicción de"
-            f" {change}."
-        )
-    if tail:
-        head += " " + tail.strip()
-    return head.strip() or "Sin datos suficientes para describir la explicación."
-
-
-def _prompt(summary: dict[str, Any]) -> str:
-    return (
-        "Eres un asistente que explica predicciones de GNNs en lenguaje natural. "
-        "Dado este resumen de una explicación (JSON), escribe un párrafo breve "
-        "en español (2-4 oraciones) describiendo qué hace el modelo y qué "
-        "evidencia respalda su predicción. Resumen:\n"
-        + json.dumps(summary, ensure_ascii=False, indent=2)
-    )
-
-
-def narrate(
-    explanation,
-    llm: Callable[[str], str] | None = None,
-    data: Any | None = None,
-    top_k: int = 5,
-) -> str:
-    """Narrates an explanation. With `llm` (a `prompt -> text` callable) it uses the
-    generative model's output; otherwise it falls back to deterministic
-    template-based narration."""
-    summary = summarize(explanation, data, top_k)
-    deterministic = describe(explanation, data, top_k)
-    if llm is None:
-        return deterministic
-    try:
-        return llm(_prompt(summary)).strip()
-    except Exception as exc:  # noqa: BLE001
-        return f"{deterministic}\n\n[LLM no disponible: {exc}]"
-
-
-class Narrator:
-    """Reusable narrator; lets you inject the LLM just once."""
-
-    def __init__(self, llm: Callable[[str], str] | None = None, top_k: int = 5):
-        self.llm = llm
-        self.top_k = top_k
-
-    def describe(self, explanation, data: Any | None = None) -> str:
-        return describe(explanation, data, self.top_k)
-
-    def narrate(self, explanation, data: Any | None = None) -> str:
-        return narrate(explanation, self.llm, data, self.top_k)