gcn-python 1.0.0__py3-none-any.whl

gcn_python/pipeline/cgnp.py

@@ -0,0 +1,419 @@
+from __future__ import annotations
+import numpy as np
+
+from ..layer1.features import FeatureVocabulary, vectorize_clause, vectorize_edge
+from ..layer2.interface import CausalEncoder
+from ..layer3.interface import CausalGraph
+from ..constants import NODE_TYPES, RELATION_TYPES
+from .label_builder import build_label
+from .ir_emitter import emit
+
+
+class CGNPipeline:
+    """
+    Pipeline complet des couches 1-3 de l'architecture CGNP.
+
+    Le data scientist instancie ce pipeline avec ses implémentations de
+    CausalEncoder (Couche 2) et CausalGraph (Couche 3).
+
+    - forward(reps, text, ...)                → CausalIR dict (prêt pour serde_json Rust)
+    - loss(node_logits, edge_logits, ...)     → (float, d_node, d_edge)
+    - backward(d_node, d_edge, lr)            → rétropropagation + mise à jour SGD
+
+    Précondition à la construction : si graph expose d_out, il doit être égal à
+    vocabulary.d_clause — vérifié immédiatement, ValueError sinon.
+
+    decoder (optionnel) : TrainableDecoder ou tout objet implémentant
+    forward_decode / loss_decode / backward_decode / update. Si None, le pipeline
+    se comporte exactement comme avant (rétro-compatible).
+    """
+
+    def __init__(
+        self,
+        encoder: CausalEncoder,
+        graph: CausalGraph,
+        lang: str,
+        vocabulary: FeatureVocabulary,
+        *,
+        decoder=None,
+    ):
+        if hasattr(graph, 'd_out') and graph.d_out != vocabulary.d_clause:
+            raise ValueError(
+                f"RGCNLayer.d_out={graph.d_out} ≠ vocabulary.d_clause="
+                f"{vocabulary.d_clause} : instanciez RGCNLayer avec "
+                f"d_out=vocabulary.d_clause pour alimenter le MLP nœud "
+                f"depuis les représentations enrichies."
+            )
+        self.encoder = encoder
+        self.graph = graph
+        self.lang = lang
+        self.vocabulary = vocabulary
+        self.decoder = decoder
+
+        # Cache rempli par forward() — utilisé par loss() et backward()
+        self._cached_clause_vecs: np.ndarray | None = None
+        self._cached_enriched_vecs: np.ndarray | None = None
+        self._cached_edge_vecs: np.ndarray | None = None
+        self._cached_node_logits: np.ndarray | None = None
+        self._cached_edge_logits: np.ndarray | None = None
+        self._cached_edge_index: np.ndarray | None = None
+        self._cached_edge_type_idxs: np.ndarray | None = None
+        # Snapshots des activations MLP par nœud/arête — évitent de re-exécuter
+        # forward_node au backward (pas de re-run, pas de fragilitié de cache)
+        self._cached_node_snapshots: list | None = None
+        self._cached_edge_snapshots: list | None = None
+        # Cache décodeur — rempli par forward() si decoder présent
+        self._cached_decode_logits: np.ndarray | None = None
+        self._cached_decode_gradient: np.ndarray | None = None
+
+    def forward(
+        self,
+        reps: list,
+        text: str = "",
+        clause_positions: list[int] | None = None,
+        n_total_clauses: int | None = None,
+        connector_reps: list | None = None,
+    ) -> dict:
+        """UDRepresentation list → CausalIR dict (JSON-serializable, conforme schéma serde Rust).
+
+        clause_positions : indices originaux des reps dans la phrase complète — utilisés
+          pour calculer les features de position dans vectorize_edge.
+          Doit avoir exactement len(reps) éléments si fourni, ValueError sinon.
+        n_total_clauses : nombre total de clauses dans la phrase (dénominateur de la distance).
+          Comparé via `is not None` — la valeur 0 est traitée comme zéro clause, pas comme absent.
+        connector_reps : UDRepresentation|None par paire consécutive (len = len(reps)-1).
+        """
+        return self._forward_from_reps(reps, text, clause_positions, n_total_clauses, connector_reps)
+
+    def _forward_from_reps(
+        self,
+        reps: list,
+        text: str,
+        clause_positions: list[int] | None = None,
+        n_total_clauses: int | None = None,
+        connector_reps: list | None = None,
+    ) -> dict:
+        if clause_positions is not None and len(clause_positions) != len(reps):
+            raise ValueError(
+                f"clause_positions a {len(clause_positions)} éléments pour {len(reps)} reps."
+            )
+
+        # Réinitialiser le cache
+        self._cached_clause_vecs = None
+        self._cached_enriched_vecs = None
+        self._cached_edge_vecs = None
+        self._cached_node_logits = None
+        self._cached_edge_logits = None
+        self._cached_edge_index = None
+        self._cached_edge_type_idxs = None
+        self._cached_node_snapshots = None
+        self._cached_edge_snapshots = None
+        self._cached_decode_logits = None
+        self._cached_decode_gradient = None
+        _snap = hasattr(self.encoder, 'snapshot_node_cache')
+
+        if not reps:
+            return emit(text, self.lang, [], [], [], [], [])
+
+        # Couche 1 — vectorisation
+        clause_vecs = np.stack([
+            vectorize_clause(r, self.vocabulary) for r in reps
+        ])  # (N, D_clause)
+        self._cached_clause_vecs = clause_vecs
+
+        # Couche 2 — prédiction des types de nœuds (snapshot par nœud pour backward)
+        node_logits_list: list[np.ndarray] = []
+        node_snapshots: list = []
+        for v in clause_vecs:
+            node_logits_list.append(self.encoder.forward_node(v))
+            if _snap:
+                node_snapshots.append(self.encoder.snapshot_node_cache())
+        node_logits = np.stack(node_logits_list)
+        node_type_idxs = np.argmax(node_logits, axis=1)
+        node_types = [NODE_TYPES[i] for i in node_type_idxs]
+
+        # Prédiction des arêtes entre clauses adjacentes
+        edge_triples: list[tuple[int, int, str, float, bool, int | None]] = []
+        edge_vecs: list[np.ndarray] = []
+        all_edge_logits: list[np.ndarray] = []
+        edge_snapshots: list = []
+        if len(reps) >= 2:
+            real_n = n_total_clauses if n_total_clauses is not None else len(reps)
+            for src_i in range(len(reps) - 1):
+                dst_i = src_i + 1
+                real_src = clause_positions[src_i] if clause_positions else src_i
+                real_dst = clause_positions[dst_i] if clause_positions else dst_i
+                connector = (connector_reps[src_i]
+                             if connector_reps and src_i < len(connector_reps) else None)
+                edge_vec = vectorize_edge(
+                    reps[src_i], reps[dst_i], connector,
+                    real_src, real_dst, real_n,
+                    self.vocabulary,
+                )
+                edge_vecs.append(edge_vec)
+                edge_logit = self.encoder.forward_edge(edge_vec)
+                all_edge_logits.append(edge_logit)
+                if _snap:
+                    edge_snapshots.append(self.encoder.snapshot_edge_cache())
+                rel_idx = int(np.argmax(edge_logit))
+                rel_conf = float(_softmax(edge_logit.reshape(1, -1))[0, rel_idx])
+                edge_triples.append((src_i, dst_i, RELATION_TYPES[rel_idx], rel_conf, False, None))
+
+        if edge_vecs:
+            self._cached_edge_vecs = np.stack(edge_vecs)
+            self._cached_edge_logits = np.stack(all_edge_logits)
+            if _snap:
+                self._cached_edge_snapshots = edge_snapshots
+
+        # Couche 3 — R-GCN message passing
+        if len(reps) > 1 and edge_triples:
+            edge_index = np.array(
+                [[e[0] for e in edge_triples], [e[1] for e in edge_triples]], dtype=np.int64
+            )
+            edge_type_idxs = np.array(
+                [RELATION_TYPES.index(e[2]) if e[2] in RELATION_TYPES else 0
+                 for e in edge_triples],
+                dtype=np.int64,
+            )
+            self._cached_edge_index = edge_index
+            self._cached_edge_type_idxs = edge_type_idxs
+            enriched = self.graph.message_pass(clause_vecs, edge_index, edge_type_idxs)
+            node_logits2_list: list[np.ndarray] = []
+            node_snapshots = []
+            for v in enriched:
+                node_logits2_list.append(self.encoder.forward_node(v))
+                if _snap:
+                    node_snapshots.append(self.encoder.snapshot_node_cache())
+            node_logits2 = np.stack(node_logits2_list)
+            node_type_idxs = np.argmax(node_logits2, axis=1)
+            node_types = [NODE_TYPES[i] for i in node_type_idxs]
+            node_logits = node_logits2
+            self._cached_enriched_vecs = enriched
+
+        self._cached_node_logits = node_logits
+        if _snap:
+            self._cached_node_snapshots = node_snapshots
+
+        node_labels = [
+            build_label(r, nt)
+            for r, nt in zip(reps, node_types)
+        ]
+        token_spans = [r.token_span for r in reps]
+        scopes = ["specific"] * len(reps)
+
+        # Décodeur (optionnel) — utilise les embeddings R-GCN enrichis si disponibles
+        if self.decoder is not None:
+            _vecs = (self._cached_enriched_vecs
+                     if self._cached_enriched_vecs is not None
+                     else self._cached_clause_vecs)
+            if _vecs is not None and len(_vecs) > 0:
+                self._cached_decode_logits = self.decoder.forward_decode(_vecs)
+
+        return emit(text, self.lang, node_types, node_labels, token_spans,
+                    scopes, edge_triples)
+
+    def filter_edge_cache(self, valid_idxs: np.ndarray) -> None:
+        """Filtre les caches MLP d'arêtes aux seuls indices valides.
+
+        Appelé après forward() pour aligner edge_logits ↔ gold_edge avant loss/backward.
+        _cached_edge_index/_cached_edge_type_idxs ne sont PAS filtrés : le R-GCN
+        a utilisé toutes les arêtes dans son forward et a besoin de toutes pour backward.
+        """
+        if self._cached_edge_vecs is not None:
+            self._cached_edge_vecs = self._cached_edge_vecs[valid_idxs]
+        if self._cached_edge_logits is not None:
+            self._cached_edge_logits = self._cached_edge_logits[valid_idxs]
+        if self._cached_edge_snapshots is not None:
+            self._cached_edge_snapshots = [self._cached_edge_snapshots[i] for i in valid_idxs]
+
+    def loss(
+        self,
+        node_logits: np.ndarray,    # (N, 7)  — logits nœuds du forward
+        edge_logits: np.ndarray | None,  # (E, 11) — logits arêtes du forward, ou None
+        gold_node: np.ndarray,      # (N,) int — indices dans NODE_TYPES
+        gold_edge: np.ndarray | None = None,  # (E,) int — indices dans RELATION_TYPES
+        edge_loss_weight: float = 1.0,  # pondération relative edge_loss / node_loss
+        gold_surface: np.ndarray | None = None,  # (T,) int — tokens gold pour le décodeur
+    ) -> tuple[float, np.ndarray, np.ndarray]:
+        """
+        Cross-entropie NumPy sur nœuds + arêtes + décodeur (optionnel).
+
+        Retourne (total_loss, d_node_logits, d_edge_logits).
+        Gradients normalisés par le nombre d'exemples.
+        edge_loss_weight permet d'équilibrer la contribution des arêtes dans la loss totale.
+        Si gold_surface est fourni et que le décodeur a produit des logits (forward()),
+        la loss décodeur est ajoutée au total et son gradient est caché pour backward().
+        """
+        if len(node_logits) != len(gold_node):
+            raise ValueError(
+                f"Désalignement node_logits/gold_node : {len(node_logits)} logits vs {len(gold_node)} labels"
+            )
+        node_loss, d_node = _cross_entropy(node_logits, gold_node)
+
+        if edge_logits is not None and gold_edge is not None and len(edge_logits) > 0:
+            if len(edge_logits) != len(gold_edge):
+                raise ValueError(
+                    f"Désalignement edge_logits/gold_edge : {len(edge_logits)} logits vs {len(gold_edge)} labels"
+                )
+            edge_loss, d_edge = _cross_entropy(edge_logits, gold_edge)
+        else:
+            edge_loss = 0.0
+            d_edge = np.zeros((0, len(RELATION_TYPES)), dtype=np.float32)
+
+        total_loss = node_loss + edge_loss_weight * edge_loss
+
+        # Decoder loss (optionnel — uniquement si gold_surface fourni et decoder actif)
+        self._cached_decode_gradient = None
+        if (self.decoder is not None
+                and gold_surface is not None
+                and self._cached_decode_logits is not None
+                and len(gold_surface) > 0):
+            dec_loss, d_dec = self.decoder.loss_decode(self._cached_decode_logits, gold_surface)
+            total_loss += dec_loss
+            self._cached_decode_gradient = d_dec
+
+        return total_loss, d_node, d_edge
+
+    def backward(
+        self,
+        d_node_logits: np.ndarray,  # (N, 7)
+        d_edge_logits: np.ndarray,  # (E, 11)
+        lr: float = 0.01,
+    ) -> None:
+        """
+        Rétropropagation + SGD sur l'implémentation de référence NumPy.
+
+        Opère sur MLPEncoder (backward_node_dx / backward_edge) et
+        RGCNLayer (backward_message_pass). Le DS PyTorch override cette méthode.
+        Les appels à update_node/update_edge sont gardés par hasattr — un encodeur
+        tiers sans ces méthodes est silencieusement ignoré (ses poids ne sont pas
+        mis à jour par ce backward).
+        """
+        if not hasattr(self.encoder, 'backward_node_dx'):
+            return  # implémentation non-référence, le DS gère son propre backward
+
+        vecs = (self._cached_enriched_vecs
+                if self._cached_enriched_vecs is not None
+                else self._cached_clause_vecs)
+        if vecs is None or len(vecs) == 0:
+            return
+
+        n = min(len(d_node_logits), len(vecs))
+        _has_node_snap = (
+            hasattr(self.encoder, 'restore_node_cache')
+            and self._cached_node_snapshots is not None
+            and len(self._cached_node_snapshots) >= n
+        )
+        _has_edge_snap = (
+            hasattr(self.encoder, 'restore_edge_cache')
+            and self._cached_edge_snapshots is not None
+        )
+
+        # --- Rétropropagation nœuds ---
+        all_node_grads: list[tuple[np.ndarray, np.ndarray]] | None = None
+        d_enriched = np.zeros((n, vecs.shape[1]), dtype=np.float32)
+
+        for i in range(n):
+            if _has_node_snap:
+                self.encoder.restore_node_cache(self._cached_node_snapshots[i])
+            else:
+                self.encoder.forward_node(vecs[i])  # fallback sans snapshot
+            grads_i, dx_i = self.encoder.backward_node_dx(d_node_logits[i])
+            d_enriched[i] = dx_i
+            if all_node_grads is None:
+                all_node_grads = [(dW.copy(), db.copy()) for dW, db in grads_i]
+            else:
+                for j, (dW_i, db_i) in enumerate(grads_i):
+                    all_node_grads[j] = (
+                        all_node_grads[j][0] + dW_i,
+                        all_node_grads[j][1] + db_i,
+                    )
+
+        # _cross_entropy normalise déjà par N — pas de renormalisation ici
+
+        # --- Rétropropagation arêtes ---
+        all_edge_grads: list[tuple[np.ndarray, np.ndarray]] | None = None
+        if (d_edge_logits is not None and len(d_edge_logits) > 0
+                and self._cached_edge_vecs is not None):
+            e = min(len(d_edge_logits), len(self._cached_edge_vecs))
+            for i in range(e):
+                if _has_edge_snap and i < len(self._cached_edge_snapshots):
+                    self.encoder.restore_edge_cache(self._cached_edge_snapshots[i])
+                else:
+                    self.encoder.forward_edge(self._cached_edge_vecs[i])
+                grads_i = self.encoder.backward_edge(d_edge_logits[i])
+                if all_edge_grads is None:
+                    all_edge_grads = [(dW.copy(), db.copy()) for dW, db in grads_i]
+                else:
+                    for j, (dW_i, db_i) in enumerate(grads_i):
+                        all_edge_grads[j] = (
+                            all_edge_grads[j][0] + dW_i,
+                            all_edge_grads[j][1] + db_i,
+                        )
+            # _cross_entropy normalise déjà par E — pas de renormalisation ici
+
+        # --- Mise à jour encodeur ---
+        if all_node_grads is not None and hasattr(self.encoder, 'update_node'):
+            self.encoder.update_node(all_node_grads, lr)
+        if all_edge_grads is not None and hasattr(self.encoder, 'update_edge'):
+            self.encoder.update_edge(all_edge_grads, lr)
+
+        # --- Gradient décodeur → R-GCN (joint training) ---
+        if (self.decoder is not None
+                and self._cached_decode_gradient is not None
+                and hasattr(self.decoder, 'backward_decode')):
+            d_mean, dec_grads = self.decoder.backward_decode(self._cached_decode_gradient)
+            self.decoder.update(dec_grads, lr)
+            # Propager d_mean vers d_enriched si les dimensions correspondent
+            if (d_mean.shape[0] == d_enriched.shape[1]
+                    and self._cached_enriched_vecs is not None):
+                N_dec = len(self._cached_enriched_vecs)
+                d_enriched[:min(n, N_dec)] += d_mean[np.newaxis, :] / max(N_dec, 1)
+
+        # --- Rétropropagation R-GCN ---
+        if (self._cached_edge_index is not None
+                and self._cached_enriched_vecs is not None
+                and hasattr(self.graph, 'backward_message_pass')):
+            N_full = len(self._cached_enriched_vecs)
+            if d_enriched.shape[0] < N_full:
+                pad = np.zeros((N_full - d_enriched.shape[0], d_enriched.shape[1]), dtype=np.float32)
+                d_enriched_full = np.concatenate([d_enriched, pad], axis=0)
+            else:
+                d_enriched_full = d_enriched
+            _, graph_grads = self.graph.backward_message_pass(d_enriched_full)
+            self.graph.update(graph_grads, lr)
+
+
+def _softmax(x: np.ndarray) -> np.ndarray:
+    e = np.exp(x - x.max(axis=-1, keepdims=True))
+    return e / e.sum(axis=-1, keepdims=True)
+
+
+def _cross_entropy(
+    logits: np.ndarray,   # (N, C)
+    labels: np.ndarray,   # (N,) int
+) -> tuple[float, np.ndarray]:
+    """Cross-entropie NumPy. Retourne (loss, d_logits) normalisés par N.
+
+    Lève ValueError si labels contient des valeurs négatives (sentinelle -1 non filtrée)
+    ou hors-bornes (>= n_classes).
+    """
+    if len(logits) == 0:
+        return 0.0, np.zeros_like(logits)
+    if len(labels) > 0 and int(labels.min()) < 0:
+        raise ValueError(
+            f"Label négatif dans _cross_entropy : min={labels.min()} "
+            f"(sentinelle -1 non filtrée ?)"
+        )
+    if len(labels) > 0 and int(labels.max()) >= logits.shape[1]:
+        raise ValueError(
+            f"Label hors-bornes dans _cross_entropy : "
+            f"max={labels.max()} >= n_classes={logits.shape[1]}"
+        )
+    N = len(logits)
+    probs = _softmax(logits)                               # (N, C)
+    loss = float(-np.log(probs[np.arange(N), labels] + 1e-9).mean())
+    d_logits = probs.copy()
+    d_logits[np.arange(N), labels] -= 1.0
+    d_logits /= N
+    return loss, d_logits

gcn_python/pipeline/cli.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+import json
+import sys
+from pathlib import Path
+import click
+
+from ..layer1.features import FeatureVocabulary
+from ..layer2.reference import MLPEncoder
+from ..layer3.reference import RGCNLayer
+from .cgnp import CGNPipeline
+from ..data.json_reader import load_sentences
+from ..data.loader import reps_from_sentence
+
+
+@click.command("gcn-forward")
+@click.argument("dataset_path", type=click.Path(path_type=Path, exists=True))
+@click.option("--sentence-id", default=None,
+              help="ID de la sentence dans le fichier (défaut : première)")
+@click.option("--lang", default="fr", show_default=True, help="Code langue (fr, en, …)")
+@click.option("--pretty/--compact", default=True, help="JSON indenté ou compact")
+@click.option(
+    "--model-path", type=click.Path(path_type=Path), default=None,
+    help="Checkpoint .npz (produit par gcn-train). Sans ce flag : poids aléatoires.",
+)
+def forward_cmd(
+    dataset_path: Path,
+    sentence_id: str | None,
+    lang: str,
+    pretty: bool,
+    model_path: Path | None,
+) -> None:
+    """
+    Run the CGNP forward pass: dataset JSON annoté → CausalIR JSON → stdout.
+
+    DATASET_PATH doit être un fichier au format dataset GCN-NL (tokens + cir).
+    """
+    records = load_sentences(dataset_path, lang)
+    if not records:
+        raise click.ClickException(f"Aucune sentence chargée depuis {dataset_path}")
+
+    if sentence_id:
+        rec = next((r for r in records if r.id == sentence_id), None)
+        if rec is None:
+            raise click.ClickException(
+                f"Sentence {sentence_id!r} introuvable dans {dataset_path}. "
+                f"IDs disponibles : {[r.id for r in records]}"
+            )
+    else:
+        rec = records[0]
+
+    reps, valid_clause_idxs, connector_reps = reps_from_sentence(rec)
+    if not reps:
+        raise click.ClickException(
+            f"La sentence {rec.id!r} ne contient pas de tokens annotés "
+            f"(format paper_examples non supporté ici — utiliser un fichier dataset avec tokens)."
+        )
+
+    vocab = FeatureVocabulary()
+    encoder = MLPEncoder(d_clause=vocab.d_clause, d_edge=vocab.d_edge)
+    graph = RGCNLayer(d_in=vocab.d_clause, d_out=vocab.d_clause)
+    pipeline = CGNPipeline(encoder=encoder, graph=graph, lang=lang, vocabulary=vocab)
+
+    if model_path is not None:
+        from ..training.checkpoint import load_checkpoint
+        if not model_path.exists():
+            raise click.ClickException(f"Checkpoint introuvable : {model_path}")
+        load_checkpoint(pipeline, model_path)
+    else:
+        click.echo("Avertissement : poids aléatoires (pas de --model-path)", file=sys.stderr)
+
+    result = pipeline.forward(
+        reps, rec.text,
+        clause_positions=valid_clause_idxs,
+        n_total_clauses=len(rec.clauses),
+        connector_reps=connector_reps,
+    )
+    click.echo(json.dumps(result, ensure_ascii=False, indent=2 if pretty else None))

gcn_python/pipeline/ir_emitter.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+
+def emit(
+    text: str,
+    lang: str,
+    node_types: list[str],
+    node_labels: list[str],
+    token_spans: list[tuple[int, int]],
+    scopes: list[str],
+    edge_triples: list[tuple[int, int, str, float, bool, int | None]],
+    node_origins: list[str] | None = None,
+) -> dict:
+    """
+    Produit un dict CausalIR conforme au schéma serde Rust de gcn-ir.
+    JSON-serializable. Tous les noms en snake_case.
+
+    edge_triples : (src_idx, dst_idx, relation, confidence, negated, marker_token)
+    """
+    if node_origins is None:
+        node_origins = ["explicit"] * len(node_types)
+
+    nodes = []
+    for i, (nt, label, span, scope, origin) in enumerate(
+        zip(node_types, node_labels, token_spans, scopes, node_origins)
+    ):
+        nodes.append({
+            "id": i,
+            "node_type": nt,
+            "label": label,
+            "source_span": {"token_span": {"start": span[0], "end": span[1]}},
+            "scope": scope,
+            "modifiers": [],
+            "temporal_ref": "unresolved",
+            "temporal_index": i,
+            "origin": origin,
+            "attributes": {
+                "entity": None,
+                "quality": None,
+                "agent": None,
+                "patient": None,
+                "agent_type": None,
+                "reversible": None,
+            },
+        })
+
+    edges = []
+    for src, dst, relation, confidence, negated, marker_token in edge_triples:
+        edges.append([src, dst, {
+            "relation": relation,
+            "confidence": float(confidence),
+            "temporal_gap": None,
+            "explicit": marker_token is not None,
+            "negated": negated,
+            "marker_token": marker_token,
+            "in_cycle": None,
+        }])
+
+    return {
+        "source_lang": {"natural": {"lang": lang}},
+        "source_text": text,
+        "nodes": nodes,
+        "edges": edges,
+        "cycles": [],
+        "unresolved": [],
+        "metadata": {
+            "schema_version": "1.0",
+            "pipeline": ["cgnp-layer1", "cgnp-layer2", "cgnp-layer3"],
+            "created_at": None,
+        },
+    }

gcn_python/pipeline/label_builder.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+from pathlib import Path
+import yaml
+
+from ..layer1.representation import UDRepresentation
+
+_nom_cache: dict[tuple[str, str], dict[str, str]] = {}
+
+
+def build_label(
+    rep: UDRepresentation,
+    node_type: str,
+    taxonomies_dir: Path | None = None,
+) -> str:
+    """
+    (UDRepresentation, node_type, TaxonomyIndex) → str label CIR.
+
+    Format selon node_type :
+      action               → "{verb_lemma}({subject_lemma})"
+      etat/transition/     → "{nominalization}({entity})" ou "{verb}({subject})"
+      processus
+      entite/etat_system.  → "{entity_lemma}"
+      condition            → "cause_cachée(?)"
+    """
+    subject = _find_subject_lemma(rep)
+    entity = _find_entity_lemma(rep)
+    nom = _nominalize(rep.root_lemma, rep.lang, taxonomies_dir)
+
+    if node_type == "condition":
+        return "hidden_cause(?)" if rep.lang == "en" else "cause_cachée(?)"
+    if node_type in ("entite", "etat_systemique"):
+        return entity or rep.root_lemma
+    if node_type == "action":
+        return f"{rep.root_lemma}({subject})" if subject else rep.root_lemma
+    # etat, transition, processus
+    if entity:
+        return f"{nom}({entity})"
+    if subject:
+        return f"{rep.root_lemma}({subject})"
+    return nom
+
+
+def _find_subject_lemma(rep: UDRepresentation) -> str | None:
+    for t in rep.tokens:
+        if t.get("dep_rel") in {"nsubj", "nsubj:pass"}:
+            return t["lemma"]
+    return None
+
+
+def _find_entity_lemma(rep: UDRepresentation) -> str | None:
+    for t in rep.tokens:
+        if t.get("dep_rel") in {"nsubj", "nsubj:pass"} and t.get("pos") in {"NOUN", "PROPN"}:
+            return t["lemma"]
+    for t in rep.tokens:
+        if t.get("pos") in {"NOUN", "PROPN"} and t.get("dep_rel") != "punct":
+            return t["lemma"]
+    return None
+
+
+def _nominalize(lemma: str, lang: str, taxonomies_dir: Path | None) -> str:
+    if taxonomies_dir is None:
+        return lemma
+    cache_key = (str(taxonomies_dir), lang)
+    if cache_key not in _nom_cache:
+        _nom_cache[cache_key] = _load_nominalizations(taxonomies_dir, lang)
+    return _nom_cache[cache_key].get(lemma, lemma)
+
+
+def _load_nominalizations(taxonomies_dir: Path, lang: str) -> dict[str, str]:
+    table: dict[str, str] = {}
+    for search_dir in [taxonomies_dir / lang, taxonomies_dir]:
+        nom_path = search_dir / "nominalizations.yaml"
+        if nom_path.exists():
+            doc = yaml.safe_load(nom_path.read_text(encoding="utf-8"))
+            if isinstance(doc, dict):
+                examples_key = "examples_fr" if lang == "fr" else "examples"
+                for _cls, cls_data in (doc.get("classes") or {}).items():
+                    for entry in (cls_data or {}).get(examples_key) or []:
+                        if isinstance(entry, dict) and "lemma" in entry and "note" in entry:
+                            table[entry["lemma"].lower()] = entry["note"]
+            break
+    return table