gcn-python 1.0.0__py3-none-any.whl

gcn_python/evaluation/metrics.py

@@ -0,0 +1,257 @@
+"""
+Métriques d'évaluation CGNP — NumPy pur, framework-agnostique.
+
+Le data scientist appelle ces fonctions après chaque epoch pour
+mesurer la qualité des prédictions. Aucune dépendance à PyTorch/sklearn.
+"""
+from __future__ import annotations
+import numpy as np
+from ..constants import NODE_TYPES, RELATION_TYPES
+
+
+# ---------------------------------------------------------------------------
+# Types de base
+# ---------------------------------------------------------------------------
+
+Predictions = list[str]   # valeurs snake_case ex: ["action", "processus"]
+GoldLabels = list[str]
+
+
+# ---------------------------------------------------------------------------
+# Métriques nœuds
+# ---------------------------------------------------------------------------
+
+def node_accuracy(pred: Predictions, gold: GoldLabels) -> float:
+    """Exactitude globale sur la prédiction des NodeType."""
+    if not gold:
+        return 0.0
+    correct = sum(p == g for p, g in zip(pred, gold))
+    return correct / len(gold)
+
+
+def node_f1_per_class(
+    pred: Predictions, gold: GoldLabels
+) -> dict[str, dict[str, float]]:
+    """
+    F1, précision, rappel par NodeType.
+
+    Retourne :
+      {"action": {"precision": 0.9, "recall": 0.8, "f1": 0.85, "support": 12}, …}
+    """
+    return _f1_per_class(pred, gold, NODE_TYPES)
+
+
+def node_macro_f1(pred: Predictions, gold: GoldLabels) -> float:
+    """F1 macro-moyenné sur tous les NodeType présents dans gold."""
+    per_class = node_f1_per_class(pred, gold)
+    scores = [v["f1"] for v in per_class.values() if v["support"] > 0]
+    return float(np.mean(scores)) if scores else 0.0
+
+
+# ---------------------------------------------------------------------------
+# Métriques arêtes
+# ---------------------------------------------------------------------------
+
+def edge_accuracy(pred: Predictions, gold: GoldLabels) -> float:
+    """Exactitude globale sur la prédiction des RelationType."""
+    if not gold:
+        return 0.0
+    correct = sum(p == g for p, g in zip(pred, gold))
+    return correct / len(gold)
+
+
+def edge_f1_per_class(
+    pred: Predictions, gold: GoldLabels
+) -> dict[str, dict[str, float]]:
+    """F1, précision, rappel par RelationType."""
+    return _f1_per_class(pred, gold, RELATION_TYPES)
+
+
+def edge_macro_f1(pred: Predictions, gold: GoldLabels) -> float:
+    per_class = edge_f1_per_class(pred, gold)
+    scores = [v["f1"] for v in per_class.values() if v["support"] > 0]
+    return float(np.mean(scores)) if scores else 0.0
+
+
+# ---------------------------------------------------------------------------
+# Similarité de graphe causal
+# ---------------------------------------------------------------------------
+
+def causal_graph_similarity(pred_ir: dict, gold_ir: dict) -> dict[str, float]:
+    """
+    Mesure la similarité entre deux CausalIR (dicts JSON).
+
+    Retourne :
+      {
+        "node_count_ratio": float,      # |pred_nodes| / |gold_nodes|
+        "node_type_accuracy": float,    # % de nœuds avec le bon type (par position)
+        "edge_count_ratio": float,
+        "edge_relation_accuracy": float,
+        "overall": float,               # moyenne des 4 mesures
+      }
+    """
+    pred_nodes = pred_ir.get("nodes", [])
+    gold_nodes = gold_ir.get("nodes", [])
+    pred_edges = pred_ir.get("edges", [])
+    gold_edges = gold_ir.get("edges", [])
+
+    # Node count ratio (capped at 1.0)
+    node_count_ratio = (
+        min(len(pred_nodes), len(gold_nodes)) / max(len(gold_nodes), 1)
+    )
+
+    # Node type accuracy (align by position)
+    n = min(len(pred_nodes), len(gold_nodes))
+    node_type_acc = (
+        sum(pred_nodes[i]["node_type"] == gold_nodes[i]["node_type"] for i in range(n)) / max(n, 1)
+    )
+
+    # Edge count ratio
+    edge_count_ratio = (
+        min(len(pred_edges), len(gold_edges)) / max(len(gold_edges), 1)
+    )
+
+    # Edge relation accuracy (align by position)
+    e = min(len(pred_edges), len(gold_edges))
+    edge_rel_acc = (
+        sum(pred_edges[i][2]["relation"] == gold_edges[i][2]["relation"] for i in range(e))
+        / max(e, 1)
+    )
+
+    overall = float(np.mean([node_count_ratio, node_type_acc,
+                              edge_count_ratio, edge_rel_acc]))
+
+    return {
+        "node_count_ratio": round(node_count_ratio, 4),
+        "node_type_accuracy": round(node_type_acc, 4),
+        "edge_count_ratio": round(edge_count_ratio, 4),
+        "edge_relation_accuracy": round(edge_rel_acc, 4),
+        "overall": round(overall, 4),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Métriques décodeur (CausalIR → texte)
+# ---------------------------------------------------------------------------
+
+def decoder_causal_fidelity(decoded_ir: dict, gold_ir: dict) -> dict[str, float]:
+    """
+    Fidélité causale du décodeur : compare le CausalIR obtenu en re-parsant
+    la sortie du décodeur avec le CausalIR gold d'origine.
+
+    Le data scientist appelle cette fonction après avoir re-parsé la surface
+    générée par le décodeur. Utilise causal_graph_similarity en interne.
+
+    Retourne les mêmes clés que causal_graph_similarity + "causal_fidelity"
+    (alias de "overall" pour clarté sémantique).
+    """
+    sim = causal_graph_similarity(decoded_ir, gold_ir)
+    sim["causal_fidelity"] = sim["overall"]
+    return sim
+
+
+def cross_modal_consistency(ir_a: dict, ir_b: dict) -> dict[str, float]:
+    """
+    Cohérence cross-modale : mesure si deux CausalIR issus de surfaces
+    différentes (ex: fr + python) encodent la même structure causale.
+
+    Les deux IR doivent avoir été produits depuis le même graphe causal.
+    Un score "consistency" proche de 1.0 indique que les deux surfaces
+    encodent fidèlement la même structure.
+
+    Retourne les mêmes clés que causal_graph_similarity + "consistency".
+    """
+    sim = causal_graph_similarity(ir_a, ir_b)
+    sim["consistency"] = sim["overall"]
+    return sim
+
+
+def roundtrip_similarity(source_ir: dict, decoded_ir: dict) -> dict[str, float]:
+    """
+    Similarité round-trip : mesure la fidélité du cycle complet
+    texte → CausalIR → texte → CausalIR.
+
+    source_ir  : CausalIR produit par l'encodeur depuis le texte original
+    decoded_ir : CausalIR produit par l'encodeur depuis le texte généré
+                 par le décodeur
+
+    Un score "roundtrip" proche de 1.0 indique que l'architecture
+    encodeur-décodeur préserve la structure causale.
+    """
+    sim = causal_graph_similarity(decoded_ir, source_ir)
+    sim["roundtrip"] = sim["overall"]
+    return sim
+
+
+def generation_bleu(hypothesis: str, references: list[str], max_n: int = 4) -> float:
+    """
+    BLEU score simplifié — NumPy pur, sans dépendance externe.
+
+    Mesure la qualité de surface de la sortie du décodeur par rapport
+    aux surfaces gold du dataset. Utile pour les surfaces en langage naturel.
+    Pour le code source, préférer decoder_causal_fidelity.
+    """
+    import math
+    from collections import Counter
+
+    hyp = hypothesis.split()
+    refs = [r.split() for r in references]
+
+    if not hyp or not refs:
+        return 0.0
+
+    hyp_len = len(hyp)
+    ref_len = min((len(r) for r in refs), key=lambda rl: (abs(rl - hyp_len), rl))
+    bp = 1.0 if hyp_len >= ref_len else math.exp(1 - ref_len / hyp_len)
+
+    # Note : on itère jusqu'à min(max_n, len(hyp)) — pas jusqu'à max_n.
+    # Comportement intentionnel : BLEU tronqué aux n-grammes disponibles pour
+    # les courtes hypothèses NLP (labels causaux, clauses). Standard BLEU-4
+    # retournerait 0 pour toute hypothèse < 4 tokens ; ce n'est pas utile ici.
+    precisions: list[float] = []
+    for n in range(1, min(max_n, len(hyp)) + 1):
+        hyp_ng = Counter(_ngrams(hyp, n))
+        clipped_total = 0
+        for ng, cnt in hyp_ng.items():
+            max_ref = max(Counter(_ngrams(r, n))[ng] for r in refs)
+            clipped_total += min(cnt, max_ref)
+        total = sum(hyp_ng.values())
+        precisions.append(clipped_total / total if total > 0 else 0.0)
+
+    if not precisions or min(precisions) == 0.0:
+        return 0.0
+
+    log_avg = sum(math.log(p) for p in precisions) / len(precisions)
+    return round(bp * math.exp(log_avg), 4)
+
+
+def _ngrams(tokens: list[str], n: int) -> list[tuple]:
+    return [tuple(tokens[i: i + n]) for i in range(len(tokens) - n + 1)]
+
+
+# ---------------------------------------------------------------------------
+# Helpers internes
+# ---------------------------------------------------------------------------
+
+def _f1_per_class(
+    pred: Predictions, gold: GoldLabels, classes: list[str]
+) -> dict[str, dict[str, float]]:
+    result = {}
+    for cls in classes:
+        tp = sum(p == cls and g == cls for p, g in zip(pred, gold))
+        fp = sum(p == cls and g != cls for p, g in zip(pred, gold))
+        fn = sum(p != cls and g == cls for p, g in zip(pred, gold))
+        support = sum(g == cls for g in gold)
+
+        precision = tp / (tp + fp) if (tp + fp) > 0 else 0.0
+        recall = tp / (tp + fn) if (tp + fn) > 0 else 0.0
+        f1 = (2 * precision * recall / (precision + recall)
+              if (precision + recall) > 0 else 0.0)
+
+        result[cls] = {
+            "precision": round(precision, 4),
+            "recall": round(recall, 4),
+            "f1": round(f1, 4),
+            "support": support,
+        }
+    return result

gcn_python/evaluation/recorder.py

@@ -0,0 +1,158 @@
+"""
+TrainingRecorder — suivi des métriques et courbes d'apprentissage par epoch.
+
+Framework-agnostique (NumPy pur). Le data scientist appelle .record() dans
+sa boucle d'entraînement. Le recorder stocke l'historique et permet
+l'export CSV pour visualisation externe (matplotlib, Excel, etc.).
+"""
+from __future__ import annotations
+import csv
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class EpochRecord:
+    epoch: int
+    loss: float
+    metrics: dict[str, float]   # {"node_accuracy": 0.87, "edge_macro_f1": 0.72, …}
+
+
+class TrainingRecorder:
+    """
+    Enregistre loss et métriques CGNP par epoch.
+
+    Usage typique dans la boucle du DS :
+
+        recorder = TrainingRecorder()
+        for epoch in range(n_epochs):
+            pipeline.forward(reps, text)
+            node_logits = pipeline._cached_node_logits
+            edge_logits = pipeline._cached_edge_logits
+            loss_val, d_node, d_edge = pipeline.loss(
+                node_logits, edge_logits, gold_node, gold_edge
+            )
+            pipeline.backward(d_node, d_edge, lr=0.001)
+            metrics = {
+                "node_accuracy": node_accuracy(pred_types, gold_types),
+                "edge_macro_f1": edge_macro_f1(pred_rels, gold_rels),
+            }
+            recorder.record(epoch, loss_val, metrics)
+
+        recorder.to_csv("training_history.csv")
+        curve = recorder.learning_curve()
+    """
+
+    def __init__(self) -> None:
+        self._history: list[EpochRecord] = []
+
+    def record(self, epoch: int, loss: float, metrics: dict[str, float]) -> None:
+        """Enregistre une epoch."""
+        self._history.append(EpochRecord(epoch=epoch, loss=loss, metrics=dict(metrics)))
+
+    def learning_curve(self) -> dict[str, list]:
+        """
+        Retourne les séries temporelles pour tracer les courbes d'apprentissage.
+
+        Exemple de retour :
+          {
+            "epoch": [0, 1, 2, …],
+            "loss": [2.1, 1.8, 1.5, …],
+            "node_accuracy": [0.3, 0.55, 0.72, …],
+            "node_macro_f1": […],
+            "edge_accuracy": […],
+            "edge_macro_f1": […],
+          }
+        """
+        if not self._history:
+            return {}
+
+        curve: dict[str, list] = {
+            "epoch": [r.epoch for r in self._history],
+            "loss": [r.loss for r in self._history],
+        }
+        # Collect all metric keys that appear across epochs
+        all_keys: set[str] = set()
+        for r in self._history:
+            all_keys.update(r.metrics.keys())
+
+        for key in sorted(all_keys):
+            curve[key] = [r.metrics.get(key, float("nan")) for r in self._history]
+
+        return curve
+
+    def best_epoch(self, metric: str = "loss", mode: str = "min") -> EpochRecord | None:
+        """
+        Retourne l'epoch avec la meilleure valeur d'une métrique.
+
+        mode="min" → minimize (pour loss)
+        mode="max" → maximize (pour accuracy, f1)
+        """
+        if not self._history:
+            return None
+
+        def get_val(r: EpochRecord) -> float:
+            if metric == "loss":
+                return r.loss
+            return r.metrics.get(metric, float("nan"))
+
+        valid = [r for r in self._history if not _is_nan(get_val(r))]
+        if not valid:
+            return None
+
+        if mode == "min":
+            return min(valid, key=get_val)
+        return max(valid, key=get_val)
+
+    def summary(self) -> dict:
+        """Résumé : première epoch, dernière epoch, meilleure loss."""
+        if not self._history:
+            return {}
+        first = self._history[0]
+        last = self._history[-1]
+        best = self.best_epoch("loss", "min")
+        return {
+            "n_epochs": len(self._history),
+            "first_loss": first.loss,
+            "last_loss": last.loss,
+            "best_loss": best.loss if best else None,
+            "best_epoch": best.epoch if best else None,
+            "last_metrics": last.metrics,
+        }
+
+    def to_csv(self, path: Path | str) -> None:
+        """Export CSV — une ligne par epoch, toutes les métriques en colonnes."""
+        curve = self.learning_curve()
+        if not curve:
+            return
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        keys = list(curve.keys())
+        with path.open("w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+            writer.writerow(keys)
+            n = len(curve["epoch"])
+            for i in range(n):
+                writer.writerow([curve[k][i] for k in keys])
+
+    def to_json(self, path: Path | str) -> None:
+        """Export JSON — liste d'objets {epoch, loss, …metrics}."""
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        records = []
+        for r in self._history:
+            row = {"epoch": r.epoch, "loss": r.loss}
+            row.update(r.metrics)
+            records.append(row)
+        path.write_text(json.dumps(records, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def __len__(self) -> int:
+        return len(self._history)
+
+    def __repr__(self) -> str:
+        return f"TrainingRecorder(epochs={len(self._history)})"
+
+
+def _is_nan(v: float) -> bool:
+    return v != v  # NaN check without math import

gcn_python/layer1/features.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+import json
+import numpy as np
+
+from ..constants import (
+    UPOS_TAGS, UD_DEP_RELS, UD_TENSE_VALUES, UD_ASPECT_VALUES,
+    UD_MOOD_VALUES, SUBJECT_POS_CATS,
+)
+from .representation import UDRepresentation
+
+
+@dataclass
+class FeatureVocabulary:
+    """
+    Schéma ordonné des features de la Couche 1.
+    Sérialisable JSON — partagé entre entraînement et inférence.
+    Le data scientist sérialise cette instance avec son checkpoint.
+    Features purement syntaxiques : UPOS, DEP_REL, tense/aspect/mood, polarity, flags structurels.
+    """
+    upos_tags: list[str] = field(default_factory=lambda: list(UPOS_TAGS))
+    dep_rels: list[str] = field(default_factory=lambda: list(UD_DEP_RELS))
+    tense_values: list[str] = field(default_factory=lambda: list(UD_TENSE_VALUES))
+    aspect_values: list[str] = field(default_factory=lambda: list(UD_ASPECT_VALUES))
+    mood_values: list[str] = field(default_factory=lambda: list(UD_MOOD_VALUES))
+    subject_pos_cats: list[str] = field(default_factory=lambda: list(SUBJECT_POS_CATS))
+
+    @property
+    def d_clause(self) -> int:
+        return (
+            len(self.upos_tags)
+            + len(self.dep_rels)
+            + len(self.subject_pos_cats)
+            + len(self.tense_values)
+            + len(self.aspect_values)
+            + len(self.mood_values)
+            + 1   # Polarity
+            + 3   # structural flags
+        )
+
+    @property
+    def d_conn(self) -> int:
+        return len(self.upos_tags) + 2
+
+    @property
+    def d_edge(self) -> int:
+        return 2 * self.d_clause + self.d_conn
+
+    def to_json(self) -> str:
+        return json.dumps({
+            "upos_tags": self.upos_tags,
+            "dep_rels": self.dep_rels,
+            "tense_values": self.tense_values,
+            "aspect_values": self.aspect_values,
+            "mood_values": self.mood_values,
+            "subject_pos_cats": self.subject_pos_cats,
+        }, ensure_ascii=False)
+
+    @classmethod
+    def from_json(cls, s: str) -> "FeatureVocabulary":
+        return cls(**json.loads(s))
+
+
+def _one_hot(value: str, vocab: list[str]) -> np.ndarray:
+    v = np.zeros(len(vocab), dtype=np.float32)
+    if value in vocab:
+        v[vocab.index(value)] = 1.0
+    elif "_unk" in vocab:
+        v[vocab.index("_unk")] = 1.0
+    return v
+
+
+def vectorize_clause(
+    rep: UDRepresentation,
+    vocab: FeatureVocabulary,
+) -> np.ndarray:
+    """UDRepresentation → np.ndarray[d_clause]"""
+    parts = [
+        _one_hot(rep.root_pos, vocab.upos_tags),
+        _one_hot(rep.root_dep_rel, vocab.dep_rels),
+        _one_hot(rep.subject_pos or "_absent", vocab.subject_pos_cats),
+        _one_hot(rep.tense, vocab.tense_values),
+        _one_hot(rep.aspect, vocab.aspect_values),
+        _one_hot(rep.mood, vocab.mood_values),
+        np.array([1.0 if rep.is_negative else 0.0], dtype=np.float32),
+        np.array([float(rep.has_object), float(rep.has_advcl), float(rep.has_temporal_obl)],
+                 dtype=np.float32),
+    ]
+    return np.concatenate(parts)
+
+
+def vectorize_connector(
+    marker_rep: UDRepresentation | None,
+    src_idx: int,
+    dst_idx: int,
+    n_clauses: int,
+    vocab: FeatureVocabulary,
+) -> np.ndarray:
+    """Connector features between two clauses → np.ndarray[d_conn]"""
+    if marker_rep is not None:
+        upos_vec = _one_hot(marker_rep.root_pos, vocab.upos_tags)
+    else:
+        upos_vec = np.zeros(len(vocab.upos_tags), dtype=np.float32)
+
+    pos_vec = np.array(
+        [float(src_idx < dst_idx), abs(dst_idx - src_idx) / max(n_clauses, 1)],
+        dtype=np.float32,
+    )
+    return np.concatenate([upos_vec, pos_vec])
+
+
+def vectorize_edge(
+    src: UDRepresentation,
+    dst: UDRepresentation,
+    connector: UDRepresentation | None,
+    src_idx: int,
+    dst_idx: int,
+    n_clauses: int,
+    vocab: FeatureVocabulary,
+) -> np.ndarray:
+    """Two clauses + connector → np.ndarray[d_edge]"""
+    return np.concatenate([
+        vectorize_clause(src, vocab),
+        vectorize_clause(dst, vocab),
+        vectorize_connector(connector, src_idx, dst_idx, n_clauses, vocab),
+    ])

gcn_python/layer1/representation.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+
+@dataclass
+class UDRepresentation:
+    """
+    Abstraction UD-agnostique d'une clause construite depuis des tokens YAML annotés.
+    Aucune heuristique linguistique — uniquement des features UD universelles.
+    """
+    tokens: list[dict]          # [{lemma, pos(UPOS), dep_rel(UD), morph: dict}]
+    root_lemma: str
+    root_pos: str               # UPOS
+    root_dep_rel: str           # UD dep_rel
+    root_morph: dict[str, str]  # {Tense: "Past", Aspect: "Imp", Mood: "Ind", …}
+    subject_pos: str | None     # UPOS du nsubj, ou None
+    has_object: bool            # dep obj/iobj existe
+    has_advcl: bool             # dep advcl existe
+    has_temporal_obl: bool      # dep obl avec morph temporel
+    token_span: tuple[int, int]
+    lang: str
+
+    @property
+    def tense(self) -> str:
+        return self.root_morph.get("Tense", "_absent")
+
+    @property
+    def aspect(self) -> str:
+        return self.root_morph.get("Aspect", "_absent")
+
+    @property
+    def mood(self) -> str:
+        return self.root_morph.get("Mood", "_absent")
+
+    @property
+    def is_negative(self) -> bool:
+        return self.root_morph.get("Polarity", "") == "Neg"

gcn_python/layer2/interface.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+from typing import Protocol, runtime_checkable
+import numpy as np
+
+
+@runtime_checkable
+class CausalEncoder(Protocol):
+    """
+    Contrat d'interface de la Couche 2 — Encodage causal.
+
+    Le data scientist implémente ce protocol avec le framework de son choix
+    (NumPy, PyTorch, JAX, sklearn, …).
+
+    Entrée  : vecteur de features Couche 1 (UDRepresentation vectorisé)
+    Sortie  : logits sur les types causaux GCN
+    """
+
+    def forward_node(self, x: np.ndarray) -> np.ndarray:
+        """
+        x      : shape (D_clause,)  — features d'une clause
+        retour : shape (7,)         — logits sur NODE_TYPES (non normalisés)
+        """
+        ...
+
+    def forward_edge(self, x: np.ndarray) -> np.ndarray:
+        """
+        x      : shape (D_edge,)    — features d'une paire de clauses
+        retour : shape (11,)        — logits sur RELATION_TYPES (non normalisés)
+        """
+        ...
+
+    def parameters(self) -> list[np.ndarray]:
+        """Retourne tous les paramètres apprenables (utilisé par le checkpoint)."""
+        ...
+
+    def update_node(self, grads: list[tuple[np.ndarray, np.ndarray]], lr: float) -> None:
+        """
+        Applique les gradients du MLP nœud.
+        grads : liste de (dW, db) par couche, dans l'ordre des couches du node MLP.
+        """
+        ...
+
+    def update_edge(self, grads: list[tuple[np.ndarray, np.ndarray]], lr: float) -> None:
+        """
+        Applique les gradients du MLP arête.
+        grads : liste de (dW, db) par couche, dans l'ordre des couches du edge MLP.
+        """
+        ...
+
+    def update(self, grads: list[np.ndarray], lr: float) -> None:
+        """Applique une liste plate de gradients (conservé pour compatibilité externe)."""
+        ...