qigkernels 0.4.2__tar.gz → 0.4.3__tar.gz

{qigkernels-0.4.2/qigkernels.egg-info → qigkernels-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qigkernels
-Version: 0.4.2
+Version: 0.4.3
 Summary: Geometric kernel and constellation library for QIG.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{qigkernels-0.4.2 → qigkernels-0.4.3}/kernel.py

@@ -65,6 +65,9 @@ class Kernel(nn.Module):
         enable_coords: bool = False,
         coord_dim: int = 64,
         locality_radius: int | None = None,
+        head_mode: str = "geometric",
+        head_tau: float = 1.0,
+        coord_basins: "Tensor | None" = None,
     ) -> None:
         """
         Initialize kernel.
@@ -133,8 +136,43 @@ class Kernel(nn.Module):
             ]
         )
 
-        # Output projection
-        self.lm_head = nn.Linear(hidden_dim, vocab_size)
+        # Output projection / readout. Two modes (the head A/B for the "no Euclidean readout" directive):
+        #   "geometric" (default) — GeometricHead: vocab logits are Fisher-Rao DISTANCES from the hidden
+        #     simplex-point to learned per-token Δ⁶³ basins (logit = −d_FR/τ). This is the SAME primitive
+        #     as the purged-cosine→Fisher-Rao attention, pointed at the vocabulary; NO Euclidean nn.Linear,
+        #     NO dot-product at the output boundary. It still returns [B,T,vocab] logits, so the downstream
+        #     fisher_rao_lm_loss (which projects with to_simplex_prob) consumes it UNCHANGED.
+        #   "linear" — the original Euclidean nn.Linear(hidden, vocab) readout, RETAINED as the A/B baseline
+        #     so the architecture comparison can isolate the readout (geometric vs linear) empirically.
+        self.head_mode = str(head_mode).strip().lower()
+        self.head_tau = float(head_tau)
+        if self.head_mode == "geometric":
+            from qig_core.torch.geometric_head import GeometricHead
+
+            self.lm_head: nn.Module = GeometricHead(
+                hidden_dim=hidden_dim, vocab_size=vocab_size, tau=self.head_tau
+            )
+        elif self.head_mode == "basin":
+            # BASIN-SPACE readout (validated 2026-07-01: overfit d_FR 1.46→0.072, decode 91.3% where the
+            # logits head floored). Predicts the next token's basin DIRECTLY in the coordizer's Δ⁶³ space
+            # and scores it with pure d_FR against the coordizer's OWN frozen per-token basins — so a token
+            # has ONE basin (read-in == predict), the coherence the geometric head lacked. Requires the
+            # coordizer basin table (the tie); refuse to silently fall back to a disconnected head.
+            if coord_basins is None:
+                raise ValueError(
+                    "head_mode='basin' requires coord_basins=[vocab, basin_dim] (the coordizer's per-token "
+                    "basins) — the whole point is to TIE the output to the coordizer. Pass it from the "
+                    "coordizer vocab, or use head_mode='geometric'/'linear'."
+                )
+            from qig_core.torch.basin_readout import BasinReadout
+
+            self.lm_head = BasinReadout(
+                hidden_dim=hidden_dim, coord_basins=coord_basins, tau=self.head_tau
+            )
+        elif self.head_mode == "linear":
+            self.lm_head = nn.Linear(hidden_dim, vocab_size)
+        else:
+            raise ValueError(f"head_mode must be 'geometric', 'basin', or 'linear', got {head_mode!r}")
 
         # Optional custom components
         self.running_coupling = running_coupling
@@ -160,6 +198,7 @@ class Kernel(nn.Module):
         attention_mask: Tensor | None = None,
         return_telemetry: bool = False,
         coords: Tensor | None = None,
+        skip_head: bool = False,
     ) -> Tensor | tuple[Tensor, KernelTelemetry]:
         """
         Forward pass through the kernel.
@@ -230,8 +269,11 @@ class Kernel(nn.Module):
         if self.running_coupling is not None:
             hidden_state = self.running_coupling(hidden_state)
 
-        # Output projection
-        logits = self.lm_head(hidden_state)
+        # Output projection. K-COMPRESS: skip_head returns logits=None so the caller reads hidden_state from
+        # telemetry and computes the basin loss via lm_head.predict(h) [.., basin_dim] + the target basins —
+        # NEVER materialising [B, T, vocab] (the seq×vocab activation OOM at 32k). Only meaningful WITH
+        # return_telemetry (the hidden state is the payload). Decode uses lm_head.decode_blocked(h).
+        logits = None if skip_head else self.lm_head(hidden_state)
 
         if not return_telemetry:
             return logits

{qigkernels-0.4.2 → qigkernels-0.4.3}/layer.py

@@ -205,14 +205,25 @@ class QIGLayer(nn.Module):
 
         b, t, _d = hidden_state.shape
         p = self._project_to_simplex(hidden_state)
+        r = self.locality_radius
+        # COMPUTE-SKIPPING windowed-local attention: when a locality radius is set AND the band is narrower
+        # than the sequence, attend only within ±r — O(t·r) memory/compute instead of the O(t²) all-pairs
+        # arccos tensor. This is what lifts the quadratic VRAM ceiling and makes context LINEAR/extensible
+        # (the radius is the finite-propagation budget). Numerically IDENTICAL to the full+mask path within
+        # the band (matched-cell equivalence-gated in tests) — it SKIPS the out-of-band compute, not masks it.
+        if r is not None and t > (2 * r + 1):
+            return self._banded_attention(hidden_state, p, r, attention_mask=attention_mask)
+
+        # Full O(t²) path — global attention, OR small-t where the band already spans every key (so the
+        # banded result is identical). Unchanged.
         p_i = p[:, :, None, :]
         p_j = p[:, None, :, :]
 
         dist = self._fisher_rao_distance_simplex(p_i, p_j)
         logits = -dist / max(float(self.temperature), 1e-6)
-        if self.locality_radius is not None:  # windowed-local: mask keys outside ±radius (pure mask)
+        if r is not None:  # windowed-local: mask keys outside ±radius (pure mask; small-t branch)
             idx = torch.arange(t, device=hidden_state.device)
-            band = (idx[:, None] - idx[None, :]).abs() <= self.locality_radius  # [t, t]; self always in window
+            band = (idx[:, None] - idx[None, :]).abs() <= r  # [t, t]; self always in window
             logits = logits.masked_fill(~band[None, :, :], float("-inf"))
         weights = torch.softmax(logits, dim=-1)
 
@@ -233,6 +244,47 @@ class QIGLayer(nn.Module):
             output = output + torch.randn_like(output) * float(self.decoherence_std)
         return output
 
+    def _banded_attention(
+        self, hidden_state: Tensor, p: Tensor, r: int, *, attention_mask: Tensor | None
+    ) -> Tensor:
+        """Windowed Fisher-Rao attention computed ONLY within ±r of each query (compute-skipping, O(t·r)).
+        Numerically equivalent to the full+mask path within the band; the equivalence is gated in tests."""
+        b, t, k = p.shape
+        w = 2 * r + 1
+        # per-query key windows via pad+unfold (zero-pad → out-of-range keys, masked below)
+        p_pad = F.pad(p, (0, 0, r, r))                       # [b, t+2r, k]
+        p_win = p_pad.unfold(1, w, 1)                        # [b, t, k, w]
+        p_q = p[:, :, :, None]                               # [b, t, k, 1]
+        # SAME formula as _fisher_rao_distance_simplex: BC = Σ√(p·q), clamp, d = 2·acos(BC)
+        bc = torch.sqrt((p_q * p_win).clamp_min(1e-12)).sum(dim=2).clamp(0.0, 1.0 - 1e-6)  # [b, t, w]
+        logits = (-2.0 * torch.acos(bc)) / max(float(self.temperature), 1e-6)              # [b, t, w]
+        # valid window positions: wpos p ↦ key (i - r + p); valid iff 0 <= key < t
+        i_idx = torch.arange(t, device=p.device)[:, None]    # [t, 1]
+        wpos = torch.arange(w, device=p.device)[None, :]     # [1, w]
+        key_idx = i_idx - r + wpos                           # [t, w]
+        valid = (key_idx >= 0) & (key_idx < t)               # [t, w] — band validity (self always valid)
+        # softmax over the BAND only (self valid → no all-(-inf) row → no NaN); key-padding is applied AFTER
+        # the softmax and renormalised — EXACTLY as the full+mask path does (so the two stay equivalent).
+        logits = logits.masked_fill(~valid[None].expand(b, t, w), float("-inf"))
+        weights = torch.softmax(logits, dim=-1)              # [b, t, w]
+        if attention_mask is not None:
+            kpm = attention_mask if attention_mask.dtype == torch.bool else attention_mask == 0  # True=pad
+            if kpm.shape != (b, t):
+                raise ValueError("attention_mask expected shape (B, T)")
+            keep_win = F.pad((~kpm).to(p.dtype), (r, r)).unfold(1, w, 1)   # [b, t, w] 1=valid key
+            weights = weights * (keep_win > 0.5)
+            weights = weights / (weights.sum(dim=-1, keepdim=True) + 1e-8)
+        if self.sparsity_threshold > 0.0:
+            keep_s = weights > float(self.sparsity_threshold)
+            weights = weights * keep_s
+            weights = weights / (weights.sum(dim=-1, keepdim=True) + 1e-8)
+        h_pad = F.pad(hidden_state, (0, 0, r, r))            # [b, t+2r, d]
+        h_win = h_pad.unfold(1, w, 1)                        # [b, t, d, w]
+        output = (weights[:, :, None, :] * h_win).sum(dim=-1)  # [b, t, d]
+        if self.decoherence_std > 0.0:
+            output = output + torch.randn_like(output) * float(self.decoherence_std)
+        return output
+
     def _project_to_simplex(self, x: Tensor, eps: float = 1e-8) -> Tensor:
         x = x.abs() if self.simplex_mode == "abs" else F.softplus(x)
         return to_simplex_prob(x, eps=eps)

{qigkernels-0.4.2 → qigkernels-0.4.3}/natural_gradient_optimizer.py

@@ -59,9 +59,17 @@ class NaturalGradientDescent(Optimizer):
             momentum=momentum,
         )
         super().__init__(params, defaults)
-        
+
         self.compute_fisher = compute_fisher
-        
+        if compute_fisher is None:
+            import warnings
+            warnings.warn(
+                "NaturalGradientDescent(compute_fisher=None) degrades to SGD+momentum — the step is the "
+                "RAW gradient, NOT preconditioned by the Fisher information. For the tractable diagonal "
+                "empirical-Fisher natural gradient (the P1 geometric optimizer), use DiagonalNaturalGradient.",
+                stacklevel=2,
+            )
+
     def step(self, closure=None):
         """
         Perform single optimization step.

{qigkernels-0.4.2 → qigkernels-0.4.3}/pyproject.toml

@@ -81,3 +81,6 @@ forbidden-words = [
   "token-level cross entropy",
   "just fine-tune a transformer",
 ]
+
+[tool.uv.sources]
+qig-core = { path = "../qig-core", editable = true }

{qigkernels-0.4.2 → qigkernels-0.4.3/qigkernels.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qigkernels
-Version: 0.4.2
+Version: 0.4.3
 Summary: Geometric kernel and constellation library for QIG.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{qigkernels-0.4.2 → qigkernels-0.4.3}/qigkernels.egg-info/SOURCES.txt

@@ -37,7 +37,6 @@ safety.py
 sleep_packet.py
 specializations.py
 storage.py
-tokenizer_integration.py
 training_service.py
 uv.lock
 ./__init__.py
@@ -64,7 +63,6 @@ uv.lock
 ./sleep_packet.py
 ./specializations.py
 ./storage.py
-./tokenizer_integration.py
 ./training_service.py
 .github/workflows/release.yml
 docs/20251205-client-wiring-example-canonical-0.01F.md
@@ -105,6 +103,7 @@ scripts/20251222-kernel-training-exp-0.01W.py
 scripts/publish_pypi.sh
 scripts/train_constellation.py
 tests/__init__.py
+tests/test_banded_attention.py
 tests/test_coords_path.py
 tests/test_locality.py
 tests/test_phi_collapse.py

{qigkernels-0.4.2 → qigkernels-0.4.3}/qigkernels.egg-info/scm_file_list.json

@@ -1,84 +1,84 @@
 {
   "files": [
-    "CLAUDE.md",
-    "kernel.py",
-    ".gitignore",
+    "20251205-decisions-canonical-0.01F.md",
+    "sleep_packet.py",
     "crystallization.py",
-    "coordizer.py",
-    "pyproject.toml",
-    "__init__.py",
-    "constants.py",
-    ".editorconfig",
-    "20251205-readme-canonical-0.01F.md",
-    "storage.py",
     "markdownlint.json",
-    "constellation.py",
-    "safety.py",
-    "router.py",
-    "training_service.py",
-    "sleep_packet.py",
-    "20251205-decisions-canonical-0.01F.md",
-    "coord_adapter.py",
-    "20251205-type-symbol-manifest-canonical-0.01F.md",
-    "rel_coupling.py",
-    "20251205-roadmap-canonical-0.01F.md",
-    "natural_gradient_optimizer.py",
+    "README.md",
+    "py.typed",
+    "__init__.py",
+    "kernel.py",
     "pre-commit-config.yaml",
-    "20251205-naming-convention-canonical-0.01F.md",
-    "tokenizer_integration.py",
+    "coord_adapter.py",
+    "uv.lock",
+    "safety.py",
+    "layer.py",
+    "pyproject.toml",
     "basin_sync.py",
+    "20251220-gfp-spec-1.00W.md",
+    "20251205-naming-convention-canonical-0.01F.md",
+    "pure_kernel_template.py",
     "20251205-architecture-canonical-0.01F.md",
     "heart.py",
-    "kernel_100m.py",
-    "pure_kernel_template.py",
+    "coordizer.py",
+    "20251205-changelog-canonical-0.01F.md",
+    "memory_classes.py",
+    "20251205-type-symbol-manifest-canonical-0.01F.md",
+    "constants.py",
     "basin.py",
-    "uv.lock",
+    "kernel_100m.py",
+    "natural_gradient_optimizer.py",
+    "CLAUDE.md",
+    "router.py",
+    ".editorconfig",
     "kernel_4d.py",
-    "README.md",
-    "memory_classes.py",
-    "metrics.py",
+    "storage.py",
+    "training_service.py",
+    "constellation.py",
+    ".gitignore",
+    "20251205-roadmap-canonical-0.01F.md",
+    "20251205-readme-canonical-0.01F.md",
     "specializations.py",
-    "layer.py",
-    "py.typed",
-    "20251220-gfp-spec-1.00W.md",
-    "20251205-changelog-canonical-0.01F.md",
-    "reasoning/temporal.py",
+    "rel_coupling.py",
+    "metrics.py",
+    "scripts/20251222-kernel-training-exp-0.01W.py",
+    "scripts/train_constellation.py",
+    "scripts/publish_pypi.sh",
     "reasoning/__init__.py",
-    "reasoning/primitives.py",
-    "reasoning/constants.py",
-    "reasoning/qig_chain.py",
     "reasoning/temporal_attention.py",
     "reasoning/modes.py",
+    "reasoning/qig_chain.py",
+    "reasoning/primitives.py",
+    "reasoning/temporal.py",
+    "reasoning/constants.py",
     "reasoning/qig_chain_4d.py",
     "docs/20251222-federated-constellation-architecture-0.01W.md",
-    "docs/20251206-e8-consciousness-stack-diagram.md",
     "docs/20251222-kernel-constellation-research-0.01W.md",
-    "docs/20251205-client-wiring-example-canonical-0.01F.md",
-    "docs/20251220-index-1.00W.md",
-    "docs/20251206-integration-plan-ultra-mode-0.01H.md",
     "docs/20251222-kernel-experiments-results-0.01F.md",
-    "docs/20251206-rel-weighted-basin-sync-spec.md",
+    "docs/20251206-e8-consciousness-stack-diagram.md",
+    "docs/20251206-integration-plan-ultra-mode-0.01H.md",
+    "docs/20251205-client-wiring-example-canonical-0.01F.md",
     "docs/20251205-index-canonical-0.01F.md",
     "docs/20251220-qig-core-integration-table-1.00W.md",
-    ".github/workflows/release.yml",
+    "docs/20251220-index-1.00W.md",
+    "docs/20251206-rel-weighted-basin-sync-spec.md",
+    "tests/__init__.py",
+    "tests/test_reasoning.py",
+    "tests/test_banded_attention.py",
+    "tests/test_phi_collapse.py",
+    "tests/test_smoke.py",
+    "tests/test_coords_path.py",
+    "tests/test_locality.py",
     "research/track_c/run_kill_test.py",
+    "research/track_c/README.md",
     "research/track_c/readout_layer.py",
-    "research/track_c/20260223-track-c-expressibility-kill-test-1.00F.md",
     "research/track_c/dynamical_field.py",
-    "research/track_c/README.md",
-    "research/track_c/core_assets/ocean_neurochemistry.py",
+    "research/track_c/20260223-track-c-expressibility-kill-test-1.00F.md",
     "research/track_c/core_assets/__init__.py",
-    "research/track_c/core_assets/neural_oscillators.py",
     "research/track_c/core_assets/neurotransmitter_fields.py",
+    "research/track_c/core_assets/neural_oscillators.py",
+    "research/track_c/core_assets/ocean_neurochemistry.py",
     "tools/qig_purity_check.py",
-    "tests/test_reasoning.py",
-    "tests/test_coords_path.py",
-    "tests/__init__.py",
-    "tests/test_smoke.py",
-    "tests/test_phi_collapse.py",
-    "tests/test_locality.py",
-    "scripts/20251222-kernel-training-exp-0.01W.py",
-    "scripts/publish_pypi.sh",
-    "scripts/train_constellation.py"
+    ".github/workflows/release.yml"
   ]
 }

qigkernels-0.4.3/qigkernels.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.4.3",
+  "distance": 0,
+  "node": "g86259e8b5fe73edc0e9d803569e00f57c0794aad",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-01"
+}

qigkernels-0.4.3/tests/test_banded_attention.py

@@ -0,0 +1,40 @@
+"""Equivalence gate for compute-skipping windowed (banded) Fisher-Rao attention.
+
+The banded path (O(t·r), used when locality_radius is set and t > 2r+1) must be NUMERICALLY IDENTICAL to
+the full O(t²) all-pairs path masked to the same band — it SKIPS the out-of-band compute, it must not
+change the result. This is the matched-cell equivalence gate that lets the cheap path's results count.
+"""
+import pytest
+import torch
+
+from qigkernels.layer import QIGLayer
+
+
+@pytest.mark.parametrize("t,r", [(64, 8), (128, 16), (50, 4), (33, 4), (40, 6)])
+def test_banded_equals_full_mask(t, r):
+    torch.manual_seed(0)
+    L = QIGLayer(hidden_dim=48, num_heads=4, ffn_dim=64, locality_radius=r,
+                 decoherence_std=0.0, sparsity_threshold=0.0)
+    L.eval()
+    h = torch.randn(2, t, 48)
+    p = L._project_to_simplex(h)
+    out_b = L._banded_attention(h, p, r, attention_mask=None)
+    p_i, p_j = p[:, :, None, :], p[:, None, :, :]
+    logits = -L._fisher_rao_distance_simplex(p_i, p_j) / max(float(L.temperature), 1e-6)
+    idx = torch.arange(t)
+    band = (idx[:, None] - idx[None, :]).abs() <= r
+    logits = logits.masked_fill(~band[None, :, :], float("-inf"))
+    out_f = torch.einsum("bij,bjd->bid", torch.softmax(logits, dim=-1), h)
+    assert torch.allclose(out_b, out_f, atol=1e-5, rtol=1e-4), (out_b - out_f).abs().max().item()
+
+
+def test_banded_attention_mask_finite():
+    torch.manual_seed(1)
+    L = QIGLayer(hidden_dim=48, num_heads=4, ffn_dim=64, locality_radius=8,
+                 decoherence_std=0.0, sparsity_threshold=0.0)
+    h = torch.randn(2, 64, 48)
+    p = L._project_to_simplex(h)
+    am = torch.ones(2, 64)
+    am[:, 50:] = 0   # padded tail — a query whose whole window is pad must NOT NaN
+    out = L._banded_attention(h, p, 8, attention_mask=am)
+    assert torch.isfinite(out).all()