gcn-python 1.0.0__py3-none-any.whl

gcn_python/verbalizer/trainable.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+import json
+import re
+import numpy as np
+
+from ..layer2.reference import _LinearLayer, _relu, _relu_grad
+
+
+class SurfaceVocabulary:
+    """Word-level vocabulary built from gold surface texts."""
+
+    PAD = "<pad>"
+    UNK = "<unk>"
+
+    def __init__(self) -> None:
+        self._t2i: dict[str, int] = {self.PAD: 0, self.UNK: 1}
+        self._i2t: list[str] = [self.PAD, self.UNK]
+
+    @staticmethod
+    def _tokenize(text: str) -> list[str]:
+        return re.findall(r"\w+|[^\w\s]", text.lower())
+
+    def build(self, surfaces: list[str]) -> None:
+        for text in surfaces:
+            for tok in self._tokenize(text):
+                if tok not in self._t2i:
+                    self._t2i[tok] = len(self._i2t)
+                    self._i2t.append(tok)
+
+    def encode(self, text: str) -> list[int]:
+        return [self._t2i.get(tok, 1) for tok in self._tokenize(text)]
+
+    def decode(self, indices: list[int] | np.ndarray) -> str:
+        return " ".join(self._i2t[int(i)] for i in indices if 0 <= int(i) < len(self._i2t))
+
+    def __len__(self) -> int:
+        return len(self._i2t)
+
+    def to_json(self) -> str:
+        return json.dumps(self._i2t)
+
+    @classmethod
+    def from_json(cls, s: str) -> "SurfaceVocabulary":
+        v = cls()
+        tokens: list[str] = json.loads(s)
+        v._i2t = tokens
+        v._t2i = {t: i for i, t in enumerate(tokens)}
+        return v
+
+
+class TrainableDecoder:
+    """
+    Reference NumPy decoder — node embeddings (N, D_in) → surface token logits (|V|,).
+
+    Architecture: mean-pool → fc(D_in → d_hidden) + ReLU → fc(d_hidden → |V|)
+
+    Implements VerbalizerDecoder (inference via decode()) AND the training interface:
+    forward_decode / loss_decode / backward_decode / parameters / update.
+
+    Layers are lazily initialized at the first forward_decode call.
+    Pass d_in to pre-initialize (required for checkpoint restore).
+    """
+
+    def __init__(
+        self,
+        vocab: SurfaceVocabulary,
+        d_hidden: int = 64,
+        d_in: int | None = None,
+        seed: int = 0,
+    ) -> None:
+        self.vocab = vocab
+        self.d_hidden = d_hidden
+        self._rng = np.random.default_rng(seed)
+        self._layers: list[_LinearLayer] | None = None
+        self._cache: list[tuple[np.ndarray, np.ndarray]] = []
+        self._last_d_in: int | None = None
+        if d_in is not None:
+            self._init_layers(d_in)
+
+    def _init_layers(self, d_in: int) -> None:
+        if self._layers is None:
+            self._layers = [
+                _LinearLayer(d_in, self.d_hidden, self._rng),
+                _LinearLayer(self.d_hidden, len(self.vocab), self._rng),
+            ]
+            self._last_d_in = d_in
+
+    @staticmethod
+    def _node_type_embeddings_from_ir(ir_json: str) -> np.ndarray:
+        from ..constants import NODE_TYPES
+        ir = json.loads(ir_json)
+        nodes = ir.get("nodes", [])
+        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)
+
+    def forward_decode(self, node_embeddings: np.ndarray) -> np.ndarray:
+        """(N, D_in) → (|V|,) logits."""
+        if len(node_embeddings) == 0:
+            return np.zeros(len(self.vocab), dtype=np.float32)
+        d_in = node_embeddings.shape[1]
+        self._init_layers(d_in)
+        assert self._layers is not None
+        mean = node_embeddings.mean(axis=0)  # (D_in,)
+        self._cache = []
+        h = mean
+        for i, layer in enumerate(self._layers):
+            z = layer.forward(h)
+            if i < len(self._layers) - 1:
+                h = _relu(z)
+                self._cache.append((z, h))
+            else:
+                h = z
+                self._cache.append((z, z))
+        return h  # (|V|,)
+
+    def loss_decode(
+        self, logits: np.ndarray, gold_tokens: np.ndarray
+    ) -> tuple[float, np.ndarray]:
+        """Average cross-entropy over gold tokens. Returns (loss, d_logits)."""
+        if len(gold_tokens) == 0 or len(logits) == 0:
+            return 0.0, np.zeros_like(logits)
+        V = len(logits)
+        e = np.exp(logits - logits.max())
+        probs = e / (e.sum() + 1e-9)
+        total_loss = 0.0
+        d_logits = np.zeros(V, dtype=np.float32)
+        valid = [int(t) for t in gold_tokens if 0 <= int(t) < V]
+        if not valid:
+            return 0.0, d_logits
+        for t in valid:
+            total_loss -= float(np.log(probs[t] + 1e-9))
+            d_t = probs.copy()
+            d_t[t] -= 1.0
+            d_logits += d_t
+        N = len(valid)
+        return total_loss / N, d_logits / N
+
+    def backward_decode(
+        self, d_logits: np.ndarray
+    ) -> tuple[np.ndarray, list[tuple[np.ndarray, np.ndarray]]]:
+        """Backward through MLP. Returns (d_mean, param_grads).
+
+        d_mean has shape (D_in,) — gradient w.r.t. the mean-pooled node embedding.
+        Caller must divide by N and broadcast to each node when propagating upstream.
+        """
+        assert self._layers is not None, "backward_decode called before forward_decode"
+        grads: list[tuple[np.ndarray, np.ndarray]] = []
+        d = d_logits.copy()
+        for i in reversed(range(len(self._layers))):
+            z, _ = self._cache[i]
+            if i < len(self._layers) - 1:
+                d = d * _relu_grad(z)
+            dx, dW, db = self._layers[i].backward(d)
+            grads.insert(0, (dW, db))
+            d = dx
+        return d, grads  # d: (D_in,)
+
+    def parameters(self) -> list[np.ndarray]:
+        if self._layers is None:
+            return []
+        params: list[np.ndarray] = []
+        for layer in self._layers:
+            params.extend([layer.W, layer.b])
+        return params
+
+    def update(self, grads: list[tuple[np.ndarray, np.ndarray]], lr: float) -> None:
+        assert self._layers is not None
+        for layer, (dW, db) in zip(self._layers, grads):
+            layer.W -= lr * dW
+            layer.b -= lr * db
+
+    # ── VerbalizerDecoder inference interface ─────────────────────────────────
+
+    def decode(self, ir_json: str) -> str:
+        """CausalIR JSON → surface string (inference)."""
+        node_embs = self._node_type_embeddings_from_ir(ir_json)
+        logits = self.forward_decode(node_embs)
+        top_indices = np.argsort(logits)[-10:][::-1]
+        filtered = [int(i) for i in top_indices if int(i) >= 2][:5]
+        return self.vocab.decode(filtered)
+
+    # ── Checkpoint serialization ──────────────────────────────────────────────
+
+    def to_json(self) -> str:
+        d_in = self._layers[0].W.shape[1] if self._layers else None
+        return json.dumps({
+            "vocab": self.vocab.to_json(),
+            "d_hidden": self.d_hidden,
+            "d_in": d_in,
+        })
+
+    @classmethod
+    def from_json(cls, s: str) -> "TrainableDecoder":
+        data = json.loads(s)
+        vocab = SurfaceVocabulary.from_json(data["vocab"])
+        return cls(vocab, d_hidden=data["d_hidden"], d_in=data.get("d_in"))

gcn_python-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,41 @@
+gcn_python/__init__.py,sha256=e1n_4-5SiHTOmrcwNyG7-r29xNg9sZvg3I3Ien2cUPM,88
+gcn_python/constants.py,sha256=U33hF8DHpvHJQyBXJ2TtG5-jEcFTSRYHP7mteQ5Ej-8,1735
+gcn_python/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gcn_python/data/json_reader.py,sha256=YGl49CXBmYcOsfrabrypPwJd5Eu3zi-3njymPgdCqjk,4321
+gcn_python/data/loader.py,sha256=hgt97szcoFSUURBHHQj8Iir4BSoP1hQUrUrsLHcOVW0,8053
+gcn_python/data/schema.py,sha256=d0vFZe8cK5QVQ12975El9dGHZOBb9lnr3aSeL4PdCmw,1192
+gcn_python/data/verbalize_loader.py,sha256=wjn8OiBoYwV2oSn-HpfVS5OA14fIaumCUFAKZ4CrdG0,3428
+gcn_python/evaluation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gcn_python/evaluation/eval_runner.py,sha256=SbYQ-BTrzkjs8dLjOmcPyhPEoehIDbdOXpaHMotKfas,4729
+gcn_python/evaluation/metrics.py,sha256=1qKErCDqN6VKuTeUYxhMxPlFHy-C8xuH-PYjLD9J0YI,9348
+gcn_python/evaluation/recorder.py,sha256=j-uiX6kj7zl5BLI9Ky9e4SlgtFejKZYgF75r50kvmeY,5298
+gcn_python/layer1/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gcn_python/layer1/features.py,sha256=vxlW8C9hMQc2WtpwpMMOssemu_U0G18QhYx24U_WbS8,4146
+gcn_python/layer1/representation.py,sha256=6XtLtHlRsS4WsmvKXfkm3EgX_ZOxzP_obMf1FMOpQFI,1239
+gcn_python/layer2/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gcn_python/layer2/interface.py,sha256=E-UzWA2TyOyPc8UE2TaAkYiuoAkyarLwP8XjIbn62Vo,1786
+gcn_python/layer2/reference.py,sha256=wH4oY4Gil1SHyAQRPWDtBPr0qUrpj1jX5T-kbhe3txo,5859
+gcn_python/layer3/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gcn_python/layer3/interface.py,sha256=4b0wMLI1wS9GHUBUugb6lRD51iY3WV9NU0lYRXquKbk,941
+gcn_python/layer3/pytorch_rgcn.py,sha256=IiUvyB6mI_dDg8TC0SLUnbN8Yj6NeI42uSsmsRc941A,7322
+gcn_python/layer3/reference.py,sha256=-u0grfeEfenr25fY8gOhylysgq8twyr-dQS9dfNGqm0,4167
+gcn_python/pipeline/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gcn_python/pipeline/cgnp.py,sha256=j3IaGzEd9R7tX-01pv1j1jespZRVbrjwmqFiNFOo9ig,19153
+gcn_python/pipeline/cli.py,sha256=8eDpbDyImyBXwTUQeIYfve32G-ZgiK_G0MgY_w0H658,2944
+gcn_python/pipeline/ir_emitter.py,sha256=m05HuzBB6kRMbSNAM-ijhtRylDNr_BiSWCZgjgWrSiw,2154
+gcn_python/pipeline/label_builder.py,sha256=SMt_wYnJDTm5oZc5Vc7FExQ6I1HtRHIPt4pPKk7v-OI,2966
+gcn_python/taxonomy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gcn_python/taxonomy/loader.py,sha256=ZZgCmeoFUgyTTQSDrClym63v8a_n7bG0FG_REo6jC7Q,2799
+gcn_python/training/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gcn_python/training/bootstrap.py,sha256=P4-d5gsn4HdzHoQxa-x0IB1MALvR9mABUlYKLY4d_r0,4167
+gcn_python/training/checkpoint.py,sha256=RyUTStaTvOyJyl3cGUrGbMHIVIDZzHfsyEpYo70eqHY,3503
+gcn_python/training/train.py,sha256=EmyHCWPBiHwZZJGiFuLjbrzwNM8P7XOC9xRY4fpaM8k,10538
+gcn_python/verbalizer/__init__.py,sha256=_Ts92AbQBv3oFPU9Mnzh0GkDSTtnH_2v8Vz-IsAJxxA,132
+gcn_python/verbalizer/cli.py,sha256=ZqV-HXtO8XSJwlHzjjcMxyfPL5gHaDG_WOMFNFWjQ9M,679
+gcn_python/verbalizer/decoder.py,sha256=6z0jzJ9hIOpTOKxOqeKZnwd0FeMsS_yOW8iVJXVUMT4,1394
+gcn_python/verbalizer/interface.py,sha256=GlIGVsTCUacAR-s14D1uvhY48F1nhupyXpXUP5I8UB4,671
+gcn_python/verbalizer/trainable.py,sha256=-1LKHJwCclabzGgkPagGr-V8V9texwkdbYdgiFCFn3E,7442
+gcn_python-1.0.0.dist-info/METADATA,sha256=NlAFpdWFyWwLr8qU6gwnnhj5UulAcKSaQZQ_xja9_bA,366
+gcn_python-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+gcn_python-1.0.0.dist-info/entry_points.txt,sha256=u-IEGUYNkfJFnCIvVGpYTK8ac7uLSqeftWwQoHLsLHE,286
+gcn_python-1.0.0.dist-info/RECORD,,

gcn_python-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gcn_python-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+gcn-bootstrap = gcn_python.training.bootstrap:bootstrap_cmd
+gcn-eval = gcn_python.evaluation.eval_runner:eval_cmd
+gcn-forward = gcn_python.pipeline.cli:forward_cmd
+gcn-train = gcn_python.training.train:train_cmd
+gcn-verbalize = gcn_python.verbalizer.cli:verbalize_cmd