gcn-python 1.0.0__tar.gz

gcn_python-1.0.0/.gitignore

@@ -0,0 +1,20 @@
+# Rust
+gcn-core/target/
+
+# Python
+gcn-python/__pycache__/
+gcn-python/src/**/__pycache__/
+gcn-python/tests/__pycache__/
+gcn-python/*.egg-info/
+gcn-python/src/*.egg-info/
+gcn-python/.pytest_cache/
+gcn-python/dist/
+gcn-python/build/
+gcn-python/models/
+
+# General
+.env
+*.pyc
+*.pyo
+*.so
+*.DS_Store

gcn_python-1.0.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.5
+Name: gcn-python
+Version: 1.0.0
+Summary: CGNP ML layers — Causal Graph Neural Parser architecture
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: numpy<3.0,>=1.24
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: spacy<4.0,>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'

gcn_python-1.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gcn-python"
+version = "1.0.0"
+description = "CGNP ML layers — Causal Graph Neural Parser architecture"
+requires-python = ">=3.10"
+dependencies = [
+    "spacy>=3.7,<4.0",
+    "numpy>=1.24,<3.0",
+    "pyyaml>=6.0",
+    "click>=8.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4", "ruff>=0.1"]
+
+[project.scripts]
+gcn-forward = "gcn_python.pipeline.cli:forward_cmd"
+gcn-verbalize = "gcn_python.verbalizer.cli:verbalize_cmd"
+gcn-train = "gcn_python.training.train:train_cmd"
+gcn-bootstrap = "gcn_python.training.bootstrap:bootstrap_cmd"
+gcn-eval = "gcn_python.evaluation.eval_runner:eval_cmd"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gcn_python"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gcn_python-1.0.0/src/gcn_python/__init__.py

@@ -0,0 +1,2 @@
+"""gcn-python — CGNP ML layers (Causal Graph Neural Parser)."""
+__version__ = "0.1.0"

gcn_python-1.0.0/src/gcn_python/constants.py

@@ -0,0 +1,28 @@
+# Sync avec gcn-core/crates/gcn-ir/src/{ir,node,edge}.rs
+NODE_TYPES = ["etat", "action", "transition", "processus", "condition", "entite", "etat_systemique"]
+RELATION_TYPES = ["cause", "enable", "prevent", "condition", "concession", "sequence",
+                  "motivation", "filter", "opposition", "data_dependency", "control_dependency"]
+SCOPE_VALUES = ["universal", "existential", "partial", "null", "specific", "unknown"]
+NODE_ORIGIN_VALUES = ["explicit", "inferred", "hypothetical"]
+AGENT_TYPE_VALUES = ["human", "collective", "institutional", "natural"]
+
+# Universal Dependencies constants
+UPOS_TAGS = ["ADJ", "ADP", "ADV", "AUX", "CCONJ", "DET", "INTJ", "NOUN", "NUM",
+             "PART", "PRON", "PROPN", "PUNCT", "SCONJ", "SYM", "VERB", "X", "_unk"]  # 18 + _unk = 19
+
+UD_DEP_RELS = ["acl", "advcl", "advmod", "amod", "appos", "aux", "case", "cc", "ccomp", "clf",
+               "compound", "conj", "cop", "csubj", "dep", "det", "discourse", "dislocated",
+               "expl", "fixed", "flat", "goeswith", "iobj", "list", "mark", "nmod", "nsubj",
+               "nummod", "obj", "obl", "orphan", "parataxis", "punct", "reparandum", "root",
+               "vocative", "xcomp", "_unk"]  # 37 + _unk = 38
+
+UD_TENSE_VALUES = ["Pres", "Past", "Fut", "Imp", "_absent"]      # 5
+UD_ASPECT_VALUES = ["Perf", "Imp", "Prog", "_absent"]             # 4
+UD_MOOD_VALUES = ["Ind", "Sub", "Cond", "Imp", "_absent"]         # 5
+UD_POLARITY_VALUES = ["Neg"]                                       # 1 binaire
+
+# D_clause = 19 + 38 + 5(subject_pos) + 5 + 4 + 5 + 1 + 3(flags) + N_taxonomy
+# D_conn = 19(marker_upos) + N_taxonomy + 2(position)
+
+# Subject POS categories
+SUBJECT_POS_CATS = ["PRON", "NOUN", "PROPN", "_other", "_absent"]  # 5

gcn_python-1.0.0/src/gcn_python/data/json_reader.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+from pathlib import Path
+import json
+import warnings
+from .schema import SentenceRecord, TokenRecord, ClauseRecord, EdgeRecord
+
+
+def load_sentences(path: Path, lang: str = "fr") -> list[SentenceRecord]:
+    """Charge un fichier JSON GCN-NL → List[SentenceRecord]."""
+    doc = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(doc, dict):
+        return []
+
+    # Format paper_examples.json
+    if "examples" in doc:
+        return [_parse_paper_example(ex, lang) for ex in doc["examples"] if "expected_cir" in ex]
+
+    # Format dataset (document.sentences)
+    if "document" in doc:
+        doc_lang = doc["document"].get("lang", lang)
+        sentences = doc["document"].get("sentences") or []
+        return [_parse_dataset_sentence(s, doc_lang) for s in sentences if "cir" in s]
+
+    return []
+
+
+def load_all_sentences(data_dir: Path, lang: str = "fr") -> list[SentenceRecord]:
+    """Charge tous les fichiers JSON d'un répertoire."""
+    records = []
+    for p in sorted(data_dir.glob("*.json")):
+        records.extend(load_sentences(p, lang))
+    return records
+
+
+def _parse_paper_example(ex: dict, lang: str) -> SentenceRecord:
+    cir = ex.get("expected_cir", {})
+    clauses = [_parse_clause_node(n) for n in cir.get("nodes", [])]
+    edges = [_parse_edge(e) for e in cir.get("edges", [])]
+    return SentenceRecord(
+        id=ex.get("id", ""),
+        text=ex.get("text", ""),
+        lang=lang,
+        tokens=[],
+        clauses=clauses,
+        edges=edges,
+    )
+
+
+def _parse_dataset_sentence(s: dict, lang: str) -> SentenceRecord:
+    tokens = [_parse_token(t) for t in s.get("tokens", [])]
+    cir = s.get("cir", {})
+    clauses = [_parse_clause_node(n) for n in cir.get("nodes", [])]
+    edges = [_parse_edge(e) for e in cir.get("edges", [])]
+    return SentenceRecord(
+        id=s.get("id", ""),
+        text=s.get("text", ""),
+        lang=lang,
+        tokens=tokens,
+        clauses=clauses,
+        edges=edges,
+    )
+
+
+def _parse_token(t: dict) -> TokenRecord:
+    gcn = t.get("gcn", {}) or {}
+    morph_raw = t.get("morph") or {}
+    return TokenRecord(
+        id=int(t.get("id", 0)),
+        form=t.get("form", ""),
+        lemma=t.get("lemma", ""),
+        pos=t.get("pos", ""),
+        dep_rel=t.get("dep_rel", ""),
+        dep_head=int(t.get("dep_head", 0)),
+        morph=morph_raw if isinstance(morph_raw, dict) else {},
+        gcn_causal_type=gcn.get("causal_type"),
+        gcn_causal_class=gcn.get("causal_class"),
+    )
+
+
+def _parse_clause_node(n: dict) -> ClauseRecord:
+    span = n.get("token_span", [0, 0])
+    attrs = dict(n.get("attributes", {}) or {})
+    for f in ("entity", "quality", "agent", "patient", "agent_type", "temporal_index", "scope"):
+        if f in n and f not in attrs:
+            attrs[f] = n[f]
+    node_type = n.get("type") or ""
+    if not node_type:
+        warnings.warn(
+            f"Nœud {n.get('id', '?')} sans champ 'type' — défaut 'action' appliqué.",
+            UserWarning, stacklevel=3,
+        )
+        node_type = "action"
+    return ClauseRecord(
+        node_id=n.get("id", ""),
+        node_type=node_type,
+        label=n.get("label", ""),
+        token_span=(span[0], span[1]) if len(span) >= 2 else (0, 0),
+        scope=n.get("scope", attrs.get("scope", "specific")),
+        temporal_index=int(n.get("temporal_index", attrs.get("temporal_index", 0))),
+        origin=n.get("origin", "explicit"),
+        attributes=attrs,
+        modifiers=n.get("modifiers", []) or [],
+    )
+
+
+def _parse_edge(e: dict) -> EdgeRecord:
+    attrs = e.get("attributes") or {}
+    relation = e.get("relation") or ""
+    if not relation:
+        warnings.warn(
+            f"Arête {e.get('source', '?')}→{e.get('target', '?')} sans champ 'relation' "
+            f"— défaut 'cause' appliqué.",
+            UserWarning, stacklevel=3,
+        )
+        relation = "cause"
+    return EdgeRecord(
+        source=e.get("source", ""),
+        target=e.get("target", ""),
+        relation=relation,
+        confidence=float(attrs.get("confidence", e.get("confidence", 1.0))),
+        explicit=bool(attrs.get("explicit", e.get("explicit", True))),
+        negated=bool(attrs.get("negated", e.get("negated", False))),
+        marker_token=attrs.get("marker_token", e.get("marker_token")),
+    )

gcn_python-1.0.0/src/gcn_python/data/loader.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+import warnings
+import numpy as np
+
+from .json_reader import load_all_sentences
+from .schema import SentenceRecord, TokenRecord, ClauseRecord
+from ..constants import NODE_TYPES, RELATION_TYPES
+from ..layer1.representation import UDRepresentation
+
+
+def _node_type_idx(node_type: str, sentence_id: str) -> int:
+    if node_type not in NODE_TYPES:
+        raise ValueError(
+            f"[sentence {sentence_id}] node_type inconnu : {node_type!r}. "
+            f"Valeurs autorisées : {NODE_TYPES}"
+        )
+    return NODE_TYPES.index(node_type)
+
+
+def _relation_idx(relation: str, sentence_id: str) -> int:
+    if relation not in RELATION_TYPES:
+        raise ValueError(
+            f"[sentence {sentence_id}] relation inconnue : {relation!r}. "
+            f"Valeurs autorisées : {RELATION_TYPES}"
+        )
+    return RELATION_TYPES.index(relation)
+
+
+@dataclass
+class TrainingSample:
+    sentence: SentenceRecord
+    gold_node_labels: np.ndarray  # (N,) int — indices dans NODE_TYPES
+    edge_map: dict  # {(src_clause_idx, tgt_clause_idx): rel_idx} — seule source de vérité pour les arêtes
+
+
+class GCNDataLoader:
+    """Itère sur les sentences YAML d'un répertoire et produit des TrainingSample."""
+
+    def __init__(self, data_dir: Path, lang: str = "fr", repeat: bool = False):
+        self.data_dir = data_dir
+        self.lang = lang
+        self.repeat = repeat
+        self._records = load_all_sentences(data_dir, lang)
+
+    def __len__(self) -> int:
+        return len(self._records)
+
+    def __iter__(self):
+        while True:
+            for rec in self._records:
+                try:
+                    yield self._to_sample(rec)
+                except ValueError as exc:
+                    warnings.warn(f"[{rec.id}] sample ignoré : {exc}", UserWarning, stacklevel=2)
+            if not self.repeat:
+                break
+
+    def _to_sample(self, rec: SentenceRecord) -> TrainingSample:
+        # _relation_idx est appelé après les guards gap>1 et backward (src>tgt)
+        # pour éviter de rejeter toute la phrase sur une arête non-supervisable
+        # dont la relation serait inconnue.
+        node_id_to_idx = {c.node_id: i for i, c in enumerate(rec.clauses)}
+        node_labels = np.array(
+            [_node_type_idx(c.node_type, rec.id) for c in rec.clauses],
+            dtype=np.int64,
+        )
+        edge_map: dict[tuple[int, int], int] = {}
+        n_backward = 0
+        for e in rec.edges:
+            src_idx = node_id_to_idx.get(e.source)
+            tgt_idx = node_id_to_idx.get(e.target)
+            if src_idx is None or tgt_idx is None:
+                warnings.warn(
+                    f"[{rec.id}] arête {e.source}→{e.target} : node_id inconnu — arête ignorée.",
+                    UserWarning, stacklevel=2,
+                )
+                continue
+            gap = abs(tgt_idx - src_idx)
+            if gap > 1:
+                warnings.warn(
+                    f"[{rec.id}] arête longue distance {e.source}→{e.target} "
+                    f"(gap={gap}) : aucune supervision d'arête possible (forward prédit "
+                    f"uniquement les paires consécutives).",
+                    UserWarning, stacklevel=2,
+                )
+                continue  # arête non-supervisable, ne pas insérer dans edge_map
+            if src_idx > tgt_idx:
+                n_backward += 1
+                continue  # arête backward non-supervisable, ne pas insérer dans edge_map
+            rel_idx = _relation_idx(e.relation, rec.id)
+            edge_map[(src_idx, tgt_idx)] = rel_idx
+        if n_backward:
+            warnings.warn(
+                f"[{rec.id}] {n_backward} arête(s) gold en direction inverse "
+                f"(src > tgt) — non supervisées (le forward prédit uniquement la "
+                f"direction consécutive croissante).",
+                UserWarning, stacklevel=2,
+            )
+        return TrainingSample(rec, node_labels, edge_map)
+
+
+def reps_from_sentence(
+    rec: SentenceRecord,
+) -> tuple[list[UDRepresentation], list[int], list[UDRepresentation | None]]:
+    """Une UDRepresentation par ClauseRecord non-vide, construite depuis les tokens YAML.
+
+    Bypass spaCy : garantit l'alignement exact features ↔ gold labels.
+    Retourne ([], [], []) si le SentenceRecord n'a pas de tokens annotés.
+
+    Retourne un triplet :
+    - reps : UDRepresentation par clause valide
+    - valid_indices : indices des clauses converties dans rec.clauses
+    - connector_reps : UDRepresentation du connecteur entre reps[k] et reps[k+1],
+      ou None si aucun connecteur trouvé (longueur = len(reps) - 1)
+    """
+    if not rec.tokens or not rec.clauses:
+        return [], [], []
+    result: list[UDRepresentation] = []
+    valid_indices: list[int] = []
+    for i, clause in enumerate(rec.clauses):
+        rep = _rep_from_clause(clause, rec.tokens, rec.lang)
+        if rep is not None:
+            result.append(rep)
+            valid_indices.append(i)
+    connector_reps: list[UDRepresentation | None] = [
+        _connector_between(
+            rec.clauses[valid_indices[k]],
+            rec.clauses[valid_indices[k + 1]],
+            rec.tokens,
+            rec.lang,
+        )
+        for k in range(len(result) - 1)
+    ]
+    return result, valid_indices, connector_reps
+
+
+def _connector_between(
+    clause_a: ClauseRecord,
+    clause_b: ClauseRecord,
+    all_tokens: list[TokenRecord],
+    lang: str,
+) -> UDRepresentation | None:
+    """Retourne une UDRepresentation pour le token connecteur entre deux spans consécutives."""
+    end_a = clause_a.token_span[1]
+    start_b = clause_b.token_span[0]
+    gap_toks = [t for t in all_tokens if end_a < t.id < start_b]
+    if not gap_toks:
+        return None
+    tok = (
+        next((t for t in gap_toks if t.gcn_causal_type == "conjonction"), None)
+        or next((t for t in gap_toks if t.pos in {"SCONJ", "CCONJ", "ADP"}), None)
+    )
+    if tok is None:
+        return None
+    return UDRepresentation(
+        tokens=[{"lemma": tok.lemma, "pos": tok.pos, "dep_rel": tok.dep_rel, "morph": tok.morph}],
+        root_lemma=tok.lemma,
+        root_pos=tok.pos,
+        root_dep_rel=tok.dep_rel,
+        root_morph=tok.morph,
+        subject_pos=None,
+        has_object=False,
+        has_advcl=False,
+        has_temporal_obl=False,
+        token_span=(tok.id, tok.id),
+        lang=lang,
+    )
+
+
+def _rep_from_clause(
+    clause: ClauseRecord,
+    all_tokens: list[TokenRecord],
+    lang: str,
+) -> UDRepresentation | None:
+    span_start, span_end = clause.token_span
+    if span_start > span_end:
+        warnings.warn(
+            f"Span inversée dans {clause.node_id} : ({span_start}, {span_end}) — clause ignorée.",
+            UserWarning, stacklevel=3,
+        )
+        return None
+    span_toks = [t for t in all_tokens if span_start <= t.id <= span_end]
+    if not span_toks:
+        return None
+
+    # Priorité : VERB annoté gcn_causal_type="verbe", sinon premier VERB/AUX, sinon premier token
+    root_tok = (
+        next((t for t in span_toks
+              if t.gcn_causal_type == "verbe" and t.pos in {"VERB", "AUX"}), None)
+        or next((t for t in span_toks if t.pos in {"VERB", "AUX"}), span_toks[0])
+    )
+
+    subject = next((t for t in span_toks if t.dep_rel in {"nsubj", "nsubj:pass"}), None)
+
+    return UDRepresentation(
+        tokens=[
+            {"lemma": t.lemma, "pos": t.pos, "dep_rel": t.dep_rel, "morph": t.morph}
+            for t in span_toks
+        ],
+        root_lemma=root_tok.lemma,
+        root_pos=root_tok.pos,
+        root_dep_rel=root_tok.dep_rel,
+        root_morph=root_tok.morph,
+        subject_pos=subject.pos if subject else None,
+        has_object=any(t.dep_rel in {"obj", "iobj", "nobj"} for t in span_toks),
+        has_advcl=any(t.dep_rel == "advcl" for t in span_toks),
+        has_temporal_obl=any(t.dep_rel in {"obl", "obl:tmod"} for t in span_toks),
+        token_span=clause.token_span,
+        lang=lang,
+    )

gcn_python-1.0.0/src/gcn_python/data/schema.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class TokenRecord:
+    id: int           # 1-based
+    form: str
+    lemma: str
+    pos: str          # UPOS
+    dep_rel: str      # UD dep relation
+    dep_head: int     # 0 = root
+    morph: dict[str, str] = field(default_factory=dict)
+    gcn_causal_type: Optional[str] = None
+    gcn_causal_class: Optional[str] = None
+
+
+@dataclass
+class ClauseRecord:
+    node_id: str           # "n001"
+    node_type: str         # NodeType snake_case
+    label: str
+    token_span: tuple[int, int]
+    scope: str
+    temporal_index: int
+    origin: str
+    attributes: dict[str, object] = field(default_factory=dict)
+    modifiers: list[dict] = field(default_factory=list)
+
+
+@dataclass
+class EdgeRecord:
+    source: str            # "n001"
+    target: str            # "n002"
+    relation: str          # RelationType snake_case
+    confidence: float
+    explicit: bool
+    negated: bool
+    marker_token: Optional[int]
+
+
+@dataclass
+class SentenceRecord:
+    id: str
+    text: str
+    lang: str
+    tokens: list[TokenRecord]
+    clauses: list[ClauseRecord]
+    edges: list[EdgeRecord]

gcn_python-1.0.0/src/gcn_python/data/verbalize_loader.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+from ..verbalizer.trainable import SurfaceVocabulary
+from ..constants import NODE_TYPES
+
+
+def _node_type_embeddings(nodes: list[dict]) -> np.ndarray:
+    """Build one-hot node_type embeddings from a list of CausalIR node dicts."""
+    if not nodes:
+        return np.zeros((1, len(NODE_TYPES)), dtype=np.float32)
+    embs = []
+    for node in nodes:
+        nt = node.get("node_type", "")
+        idx = NODE_TYPES.index(nt) if nt in NODE_TYPES else 0
+        onehot = np.zeros(len(NODE_TYPES), dtype=np.float32)
+        onehot[idx] = 1.0
+        embs.append(onehot)
+    return np.stack(embs)  # (N, 7)
+
+
+@dataclass
+class VerbalizeSample:
+    ir_json: str                      # CausalIR JSON (for inference)
+    node_type_embeddings: np.ndarray  # (N, 7) one-hot — fallback when R-GCN not available
+    gold_tokens: np.ndarray           # (T,) int indices in SurfaceVocabulary
+    source_text: str                  # used to match encoding dataset samples
+
+
+class VerbalizerDataLoader:
+    """Loads verbalize JSON files and produces VerbalizeSample per (CausalIR, surface) pair.
+
+    Reads files matching verbalize_*.json in data_dir.
+    Each cross-modal example with N surfaces produces N VerbalizeSamples.
+    Only gold and silver quality surfaces are used for training.
+    gcn-verbalize.schema.yaml is documentation for annotators — never read here.
+    """
+
+    def __init__(
+        self,
+        data_dir: Path,
+        vocab: SurfaceVocabulary | None = None,
+    ) -> None:
+        raw = self._load_raw(data_dir)
+
+        if vocab is None:
+            vocab = SurfaceVocabulary()
+            surfaces = [
+                surf["text"]
+                for ex in raw
+                for surf in ex.get("surfaces", [])
+                if surf.get("quality") in ("gold", "silver")
+            ]
+            vocab.build(surfaces)
+        self.vocab = vocab
+
+        self._samples: list[VerbalizeSample] = []
+        for ex in raw:
+            ir = ex["causal_ir"]
+            ir_json = json.dumps(ir)
+            source_text: str = ir.get("source_text", "")
+            nodes: list[dict] = ir.get("nodes", [])
+            node_embs = _node_type_embeddings(nodes)
+            for surf in ex.get("surfaces", []):
+                if surf.get("quality") not in ("gold", "silver"):
+                    continue
+                gold_tokens = np.array(vocab.encode(surf["text"]), dtype=np.int64)
+                self._samples.append(
+                    VerbalizeSample(ir_json, node_embs, gold_tokens, source_text)
+                )
+
+    @staticmethod
+    def _load_raw(data_dir: Path) -> list[dict]:
+        examples: list[dict] = []
+        for p in sorted(data_dir.glob("verbalize_*.json")):
+            with p.open(encoding="utf-8") as f:
+                data = json.load(f)
+            examples.extend(data.get("examples", []))
+        return examples
+
+    def source_text_map(self) -> dict[str, list[np.ndarray]]:
+        """Returns {source_text: [gold_tokens, ...]} for joint training lookup."""
+        result: dict[str, list[np.ndarray]] = {}
+        for s in self._samples:
+            result.setdefault(s.source_text, []).append(s.gold_tokens)
+        return result
+
+    def __len__(self) -> int:
+        return len(self._samples)
+
+    def __iter__(self):
+        yield from self._samples