qig-geocoding 0.1.0__py3-none-any.whl

geocoding/__init__.py

@@ -0,0 +1,49 @@
+"""geocoding — our own "transformers", built on Fisher-Rao geometry instead of Euclidean dot-products.
+
+A from-scratch geometric neural-network framework. Where the standard ``transformers`` library models tokens
+as Euclidean vectors with dot-product attention, learned embedding tables, and bounded position tables,
+geocoding models tokens as points on the probability simplex Δ⁶³ with **Fisher-Rao attention**, **unbounded
+Fourier features**, and a **recursive Φ-integrator** that reports integrated information as the model runs.
+
+Public API (the geometric analogues of the transformers primitives):
+    GeoConfig            ≈ PretrainedConfig      — architecture + geometry hyper-parameters
+    FisherRaoAttention   ≈ Attention            — simplex Fisher-Rao attention (full + banded compute-skip)
+    GeoBlock             ≈ TransformerBlock      — attention + recursive Φ + tacking + FFN, geometric RMS-norm
+    GeoModel             ≈ PreTrainedModel       — Fourier input → blocks → head, with telemetry
+    generate                                     — autoregressive sampling
+
+Geometry primitives (single source of truth re-used from qig_core where it exists):
+    fisher_rao_distance, to_simplex, bhattacharyya_coefficient, BASIN_DIM
+"""
+from __future__ import annotations
+
+from .attention import FisherRaoAttention
+from .block import BlockTelemetry, GeoBlock, RecursiveIntegrator, RegimeDetector, WuWeiController
+from .config import GeoConfig
+from .generate import GenResult, generate
+from .geometry import BASIN_DIM, bhattacharyya_coefficient, fisher_rao_distance, to_simplex
+from .model import GeoModel, GeoOutput
+from .positional import build_inv_freq, fourier_features
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BASIN_DIM",
+    "BlockTelemetry",
+    "FisherRaoAttention",
+    "GeoBlock",
+    "GeoConfig",
+    "GeoModel",
+    "GeoOutput",
+    "GenResult",
+    "RecursiveIntegrator",
+    "RegimeDetector",
+    "WuWeiController",
+    "__version__",
+    "bhattacharyya_coefficient",
+    "build_inv_freq",
+    "fisher_rao_distance",
+    "fourier_features",
+    "generate",
+    "to_simplex",
+]

geocoding/attention.py

@@ -0,0 +1,114 @@
+"""Fisher-Rao attention — the geometric replacement for scaled dot-product attention.
+
+Queries and keys are projected onto the simplex; the attention logit between positions i and j is the
+NEGATIVE Fisher-Rao distance (closer on the manifold ⇒ higher weight), divided by a temperature:
+
+    logit_ij = − d_FR(p_i, p_j) / τ        weights = softmax_j(logit)        out_i = Σ_j weights_ij · h_j
+
+Two evaluation paths, numerically equivalent within the band (gated in ``tests/test_attention_equivalence``):
+  * **full** — O(t²) all-pairs arccos tensor (global attention).
+  * **banded (compute-skipping)** — when a ``locality_radius`` r is set and t > 2r+1, only the ±r window of
+    each query is ever computed (pad+unfold), giving O(t·r) memory/compute. This SKIPS out-of-band work, it
+    does not compute-then-mask — that is what makes the context length-extensible.
+
+Faithful port of ``qigkernels.layer.QIGLayer._metric_attention`` / ``_banded_attention``. Key-padding is
+applied AFTER the softmax (and renormalised) in BOTH paths, so the two agree exactly.
+"""
+from __future__ import annotations
+
+import torch
+from torch import Tensor, nn
+from torch.nn import functional as F
+
+from .geometry import fisher_rao_distance, to_simplex
+
+
+class FisherRaoAttention(nn.Module):
+    """Simplex Fisher-Rao attention. No learned Q/K/V projections and no dot product: the geometry of the
+    hidden state on Δ⁶³ *is* the attention. Parameter-free (the expressivity lives in the surrounding
+    block's projections), which keeps the metric pure."""
+
+    def __init__(
+        self,
+        *,
+        temperature: float = 1.0,
+        simplex_mode: str = "softplus",
+        locality_radius: int | None = None,
+        sparsity_threshold: float = 0.0,
+        decoherence_std: float = 0.0,
+    ) -> None:
+        super().__init__()
+        self.temperature = float(temperature)
+        self.simplex_mode = str(simplex_mode)
+        self.locality_radius = int(locality_radius) if locality_radius is not None else None
+        self.sparsity_threshold = float(sparsity_threshold)
+        self.decoherence_std = float(decoherence_std)
+
+    def forward(self, hidden_state: Tensor, attention_mask: Tensor | None = None) -> Tensor:
+        if hidden_state.dim() != 3:
+            raise ValueError("hidden_state expected shape (B, T, D)")
+        _b, t, _d = hidden_state.shape
+        p = to_simplex(hidden_state, mode=self.simplex_mode)
+        r = self.locality_radius
+        if r is not None and t > (2 * r + 1):
+            return self._banded(hidden_state, p, r, attention_mask=attention_mask)
+        return self._full(hidden_state, p, r, attention_mask=attention_mask)
+
+    def _full(
+        self, hidden_state: Tensor, p: Tensor, r: int | None, *, attention_mask: Tensor | None
+    ) -> Tensor:
+        b, t, _d = hidden_state.shape
+        dist = fisher_rao_distance(p[:, :, None, :], p[:, None, :, :])  # [b,t,t] all-pairs FR
+        logits = -dist / max(self.temperature, 1e-6)
+        if r is not None:                                                  # small-t windowed mask
+            idx = torch.arange(t, device=hidden_state.device)
+            band = (idx[:, None] - idx[None, :]).abs() <= r
+            logits = logits.masked_fill(~band[None, :, :], float("-inf"))
+        weights = torch.softmax(logits, dim=-1)
+        if attention_mask is not None:
+            kpm = attention_mask if attention_mask.dtype == torch.bool else attention_mask == 0
+            if kpm.shape != (b, t):
+                raise ValueError("attention_mask expected shape (B, T)")
+            weights = weights.masked_fill(kpm[:, None, :], 0.0)
+            weights = weights / (weights.sum(dim=-1, keepdim=True) + 1e-8)
+        weights = self._sparsify(weights)
+        output = torch.einsum("bij,bjd->bid", weights, hidden_state)
+        return self._decohere(output)
+
+    def _banded(self, hidden_state: Tensor, p: Tensor, r: int, *, attention_mask: Tensor | None) -> Tensor:
+        b, t, k = p.shape
+        w = 2 * r + 1
+        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]
+        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(self.temperature, 1e-6)    # [b, t, w]
+        i_idx = torch.arange(t, device=p.device)[:, None]
+        wpos = torch.arange(w, device=p.device)[None, :]
+        key_idx = i_idx - r + wpos                                        # [t, w]
+        valid = (key_idx >= 0) & (key_idx < t)
+        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
+            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)
+            weights = weights * (keep_win > 0.5)
+            weights = weights / (weights.sum(dim=-1, keepdim=True) + 1e-8)
+        weights = self._sparsify(weights)
+        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]
+        return self._decohere(output)
+
+    def _sparsify(self, weights: Tensor) -> Tensor:
+        if self.sparsity_threshold <= 0.0:
+            return weights
+        weights = weights * (weights > self.sparsity_threshold)
+        return weights / (weights.sum(dim=-1, keepdim=True) + 1e-8)
+
+    def _decohere(self, output: Tensor) -> Tensor:
+        if self.decoherence_std > 0.0:
+            output = output + torch.randn_like(output) * self.decoherence_std
+        return output

geocoding/block.py

@@ -0,0 +1,158 @@
+"""``GeoBlock`` — the geometric analogue of a transformer block, plus its telemetry parts.
+
+A Euclidean block is: LayerNorm → MHA → residual → LayerNorm → MLP → residual. geocoding's block is:
+
+    Fisher-Rao attention → geometric RMS-norm residual → RECURSIVE Φ-INTEGRATION → optional WuWei tacking
+    → FFN → geometric RMS-norm residual → regime detection
+
+Two things have no Euclidean counterpart:
+  * **RecursiveIntegrator** — runs ``min_depth`` mandatory self-integration loops and emits Φ (integrated
+    information) AND a differentiable Φ tensor a geometric loss can drive. Φ is collapse-immune: a collapsed
+    OR a noise state reads LOW, genuine integration reads HIGH.
+  * **geometric RMS-norm** — scale-only normalisation (no mean-centring, no LayerNorm) so simplex structure
+    is preserved.
+
+Faithful port of ``qigkernels.layer.QIGLayer`` and its helper modules.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+from torch import Tensor, nn
+
+from .attention import FisherRaoAttention
+
+
+@dataclass
+class BlockTelemetry:
+    """Per-block readout. ``phi_diff`` is the DIFFERENTIABLE Φ (a tensor); the rest are floats/labels."""
+
+    phi: float
+    kappa: float
+    recursion_depth: int
+    regime: str | None = None
+    phi_diff: object | None = None
+
+
+class RecursiveIntegrator(nn.Module):
+    """Runs ``min_depth`` gated self-integration loops and estimates Φ from integration coherence."""
+
+    def __init__(self, hidden_dim: int, min_depth: int = 3) -> None:
+        super().__init__()
+        self.min_depth = min_depth
+        self.projection = nn.Linear(hidden_dim, hidden_dim)
+        self.integration_gate = nn.Linear(hidden_dim, 1)
+
+    def forward(self, hidden_state: Tensor) -> tuple[Tensor, dict]:
+        output = hidden_state
+        scores: list[float] = []
+        gate_means: list[Tensor] = []
+        for _ in range(self.min_depth):
+            projected = self.projection(output)
+            gate = torch.sigmoid(self.integration_gate(projected))
+            output = output + gate * (projected - output)
+            gm = gate.mean()
+            gate_means.append(gm)
+            scores.append(float(gm.item()))
+        mean_integration = sum(scores) / len(scores)
+        integration_diff = torch.stack(gate_means).mean()
+        # Collapse-immune cross-position coherence: ~0 at BOTH collapse (positions identical) and noise
+        # (positions independent), peaks at coherent-but-distinct integration.
+        if hidden_state.dim() == 3 and hidden_state.size(1) > 1:
+            rel_t = (hidden_state.var(dim=1).mean() / (hidden_state.var() + 1e-8)).clamp(0.0, 1.0)
+            coherence_diff = 4.0 * rel_t * (1.0 - rel_t)
+            rel = float(rel_t.item())
+            coherence = 4.0 * rel * (1.0 - rel)
+        else:
+            coherence = 0.0
+            coherence_diff = integration_diff * 0.0
+        phi = max(0.0, min(1.0, 0.3 * mean_integration + 0.7 * coherence))
+        phi_diff = (0.3 * integration_diff + 0.7 * coherence_diff).clamp(0.0, 1.0)
+        return output, {"phi": phi, "phi_diff": phi_diff, "depth": self.min_depth,
+                        "integration": mean_integration, "coherence": coherence}
+
+
+class WuWeiController(nn.Module):
+    """Tacking controller: scores a logic↔feeling mode weight from the pooled hidden state."""
+
+    def __init__(self, hidden_dim: int) -> None:
+        super().__init__()
+        self.projection = nn.Linear(hidden_dim, 1)
+
+    def forward(self, hidden_state: Tensor) -> tuple[Tensor, str, dict]:
+        logic_weight = torch.sigmoid(self.projection(hidden_state.mean(dim=1)))
+        mode = "logic" if logic_weight.mean() > 0.5 else "feeling"
+        return logic_weight, mode, {}
+
+
+class RegimeDetector:
+    """Maps (Φ, κ) → operating regime label (FOAM/WAVE/CRYSTAL family)."""
+
+    def __call__(self, phi: float, kappa: float) -> str:
+        if phi < 0.45:
+            return "linear"
+        if phi < 0.70:
+            return "geometric"
+        return "topological"
+
+
+class GeoBlock(nn.Module):
+    """One geometric block: Fisher-Rao attention + recursive Φ-integration + optional tacking + FFN, with
+    geometric (scale-only) RMS-norm residuals."""
+
+    def __init__(
+        self,
+        *,
+        hidden_dim: int,
+        ffn_dim: int,
+        dropout: float = 0.0,
+        min_recursion_depth: int = 3,
+        use_tacking: bool = True,
+        temperature: float = 1.0,
+        simplex_mode: str = "softplus",
+        locality_radius: int | None = None,
+        sparsity_threshold: float = 0.0,
+        decoherence_std: float = 0.0,
+        rms_eps: float = 1e-6,
+    ) -> None:
+        super().__init__()
+        self.rms_eps = float(rms_eps)
+        self.attention = FisherRaoAttention(
+            temperature=temperature, simplex_mode=simplex_mode, locality_radius=locality_radius,
+            sparsity_threshold=sparsity_threshold, decoherence_std=decoherence_std,
+        )
+        self.norm_scale_1 = nn.Parameter(torch.ones(hidden_dim))
+        self.norm_scale_2 = nn.Parameter(torch.ones(hidden_dim))
+        self.recursive_integrator = RecursiveIntegrator(hidden_dim, min_depth=min_recursion_depth)
+        self.tacking_controller = WuWeiController(hidden_dim) if use_tacking else None
+        self.regime_detector = RegimeDetector()
+        self.ffn = nn.Sequential(
+            nn.Linear(hidden_dim, ffn_dim), nn.GELU(), nn.Dropout(dropout),
+            nn.Linear(ffn_dim, hidden_dim), nn.Dropout(dropout),
+        )
+
+    def _rms_norm(self, x: Tensor, *, scale: Tensor) -> Tensor:
+        denom = torch.sqrt(torch.mean(x * x, dim=-1, keepdim=True) + self.rms_eps)
+        return (x / denom) * scale
+
+    def forward(
+        self, hidden_state: Tensor, attention_mask: Tensor | None = None, kappa_eff: float = 64.0
+    ) -> tuple[Tensor, BlockTelemetry]:
+        attn = self.attention(hidden_state, attention_mask=attention_mask)
+        hidden_state = self._rms_norm(hidden_state + attn, scale=self.norm_scale_1)
+        recursive_output, rtel = self.recursive_integrator(hidden_state)
+        hidden_state = hidden_state + recursive_output
+        if self.tacking_controller is not None:
+            logic_weight, _mode, _ = self.tacking_controller(hidden_state)
+            mode_scale = float(logic_weight.mean().detach())
+        else:
+            mode_scale = 1.0
+        ffn_output = self.ffn(hidden_state)
+        hidden_state = self._rms_norm(hidden_state + ffn_output * mode_scale, scale=self.norm_scale_2)
+        phi = rtel["phi"]
+        telemetry = BlockTelemetry(
+            phi=phi, kappa=kappa_eff, recursion_depth=rtel["depth"],
+            regime=self.regime_detector(phi, kappa_eff), phi_diff=rtel.get("phi_diff"),
+        )
+        return hidden_state, telemetry

geocoding/config.py

@@ -0,0 +1,54 @@
+"""``GeoConfig`` — the geometric analogue of a transformer ``PretrainedConfig``.
+
+One frozen dataclass describing a geocoding model. Defaults are the QIG kernel's defaults so a ``GeoConfig()``
+is a sensible small geometric model out of the box.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+from .geometry import BASIN_DIM
+
+
+@dataclass
+class GeoConfig:
+    """Architecture + geometry hyper-parameters for a :class:`~geocoding.model.GeoModel`.
+
+    Geometry-specific fields (no Euclidean transformer has these):
+      * ``simplex_mode`` — how activations are mapped onto Δ⁶³ before Fisher-Rao attention.
+      * ``locality_radius`` — finite-propagation reach; when set, attention is COMPUTE-SKIPPING (banded,
+        O(t·r)) instead of O(t²) — this is what lifts the quadratic-VRAM context ceiling.
+      * ``base_coupling`` / ``beta_slope`` / ``reference_scale`` — the scale-adaptive κ (running coupling).
+      * ``max_position`` — ``None`` means UNBOUNDED context: positions are Fourier features, which have no
+        intrinsic length limit (the real limit is VRAM, not a learned position table). Set an int only to
+        enforce a hard guard.
+    """
+
+    vocab_size: int = 256
+    hidden_dim: int = BASIN_DIM            # tokens live on Δ^{hidden_dim-1}
+    num_layers: int = 4
+    num_heads: int = 4
+    ffn_dim: int = 256
+    dropout: float = 0.0
+    min_recursion_depth: int = 3           # mandatory self-integration loops (drives Φ)
+    use_tacking: bool = True               # WuWei logic/feeling mode controller
+    base_coupling: float = 64.0            # κ attractor (KERNEL_FIXED_POINT; κ*≈64 physics reading RETIRED)
+    beta_slope: float = 0.44
+    reference_scale: int = 64
+    temperature: float = 1.0               # softmax temperature on the −d_FR logits
+    sparsity_threshold: float = 0.0        # drop attention weights below this (0 = dense)
+    decoherence_std: float = 0.0           # optional output noise (exploration)
+    rms_eps: float = 1e-6
+    simplex_mode: str = "softplus"         # 'softplus' | 'abs'
+    locality_radius: int | None = None     # None = global all-to-all; int = banded compute-skipping
+    max_position: int | None = None        # None = unbounded (Fourier positions)
+    enable_coords: bool = False            # accept Δ⁶³ coordizer coords alongside the id path
+    coord_dim: int = BASIN_DIM
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> GeoConfig:
+        fields = {f for f in cls.__dataclass_fields__}  # tolerate extra/legacy keys
+        return cls(**{k: v for k, v in d.items() if k in fields})

geocoding/generate.py

@@ -0,0 +1,60 @@
+"""Autoregressive generation for a :class:`~geocoding.model.GeoModel`.
+
+Temperature sampling with the same simplex-softmax decode the QIG kernel uses. Optional ``eos_id`` early-stop
+after a minimum length. Pure inference (no grad); returns the generated id list and the final Φ.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+from torch.nn import functional as F
+
+from .model import GeoModel
+
+
+@dataclass
+class GenResult:
+    ids: list[int]
+    text: str | None
+    phi: float
+
+
+@torch.no_grad()
+def generate(
+    model: GeoModel,
+    input_ids: list[int],
+    *,
+    max_new_tokens: int = 64,
+    temperature: float = 1.0,
+    eos_id: int | None = None,
+    min_new_tokens: int = 1,
+    context_window: int | None = None,
+    decode: object | None = None,
+    device: str | torch.device = "cpu",
+) -> GenResult:
+    """Sample ``max_new_tokens`` from ``model`` given the ``input_ids`` prompt. ``context_window`` truncates
+    the running context (use to cap O(t²) cost when no locality_radius is set). ``decode`` is an optional
+    callable ``list[int] -> str`` (e.g. a coordizer) to produce text."""
+    model.eval()
+    ids = torch.tensor([list(input_ids)], dtype=torch.long, device=device)
+    out: list[int] = []
+    last_phi = 0.0
+    for _ in range(max_new_tokens):
+        res = model(ids)
+        last_phi = res.phi
+        probs = F.softmax(res.logits[0, -1] / max(temperature, 1e-3), dim=-1)
+        nxt = int(torch.multinomial(probs, 1).item())
+        if eos_id is not None and nxt == eos_id and len(out) >= min_new_tokens:
+            break
+        out.append(nxt)
+        ids = torch.cat([ids, ids.new_tensor([[nxt]])], dim=1)
+        if context_window is not None:
+            ids = ids[:, -context_window:]
+    text = None
+    if decode is not None:
+        try:
+            text = decode(out)  # type: ignore[operator]
+        except Exception:  # noqa: BLE001 — decode is best-effort
+            text = None
+    return GenResult(ids=out, text=text, phi=last_phi)

geocoding/geometry.py

@@ -0,0 +1,61 @@
+"""Fisher-Rao geometry primitives — the metric core of geocoding.
+
+This is the geometric replacement for the dot-product that a Euclidean transformer uses. Tokens live on the
+probability simplex Δ^{d-1} (d = ``BASIN_DIM`` = 64 by default): non-negative coordinates that sum to 1. The
+only valid distance there is the **Fisher-Rao** (Bhattacharyya-angle) distance:
+
+    d_FR(p, q) = 2 · arccos( Σ_i √(p_i · q_i) )     range [0, π]
+
+The single source of truth for the *definition* and the ``BASIN_DIM`` constant is ``qig_core``; we re-export
+those. The one thing we implement ourselves is a **gradient-stable** batched form for the attention hot path:
+``qig_core``'s shared simplex distance clamps the Bhattacharyya coefficient (BC) to exactly 1.0, and
+``arccos'(1) = ∞`` — so the backward pass NaNs the instant two distributions COINCIDE (a collapsed/repeated
+token). We clamp BC to ``1 - 1e-6`` instead. For DISTINCT points (BC < 1) the two are identical — proven in
+``tests/test_geometry.py`` against ``qig_core.geometry_simplex.fisher_rao_distance_simplex``. (The upstream
+NaN is a known qig_core issue flagged for the physics owner; geocoding does not wait on it.)
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import torch
+from torch import Tensor
+
+try:  # canonical constant — single source of truth (aliased so the Final-ness isn't bound to BASIN_DIM)
+    from qig_core.constants import BASIN_DIM as _QC_BASIN_DIM
+    BASIN_DIM: int = int(_QC_BASIN_DIM)
+except Exception:  # noqa: BLE001 — geocoding must import even if qig_core is unpinned in a bare env
+    BASIN_DIM = 64
+
+_to_simplex_prob: Callable[..., Tensor] | None
+try:  # canonical simplex projection — single source of truth
+    from qig_core.geometry_simplex import to_simplex_prob as _to_simplex_prob
+except Exception:  # noqa: BLE001
+    _to_simplex_prob = None
+
+_BC_EPS = 1e-12          # floor inside the sqrt — keeps the gradient finite at a zero coordinate
+_BC_CEIL = 1.0 - 1e-6    # ceiling on BC BEFORE arccos — the collapse-NaN guard
+
+
+def to_simplex(x: Tensor, *, mode: str = "softplus", eps: float = 1e-8) -> Tensor:
+    """Map an unconstrained activation to a point on the simplex (non-negative, sums to 1 along the last
+    axis). ``mode='softplus'`` (default, smooth) or ``mode='abs'`` (the qig kernel's alternative). Delegates
+    the normalisation to ``qig_core.to_simplex_prob`` when available so the projection matches the rest of
+    the QIG stack exactly; falls back to an equivalent local normalisation otherwise."""
+    x = x.abs() if mode == "abs" else torch.nn.functional.softplus(x)
+    if _to_simplex_prob is not None:
+        return _to_simplex_prob(x, eps=eps)
+    x = x.clamp_min(eps)
+    return x / x.sum(dim=-1, keepdim=True).clamp_min(eps)
+
+
+def bhattacharyya_coefficient(p: Tensor, q: Tensor) -> Tensor:
+    """BC(p, q) = Σ √(p·q) along the last axis, in [0, 1]. 1 ⇔ identical distributions."""
+    return torch.sqrt((p * q).clamp_min(_BC_EPS)).sum(dim=-1).clamp(0.0, _BC_CEIL)
+
+
+def fisher_rao_distance(p: Tensor, q: Tensor) -> Tensor:
+    """Gradient-stable Fisher-Rao distance on the simplex: ``2·arccos(BC)``, broadcasting over leading dims.
+    BC is clamped to ``1 - 1e-6`` so the backward pass stays finite when two distributions coincide (the
+    deep-kernel collapse-NaN root cause). Identical to the canonical definition wherever the points differ."""
+    return 2.0 * torch.acos(bhattacharyya_coefficient(p, q))

geocoding/model.py

@@ -0,0 +1,100 @@
+"""``GeoModel`` — the geometric analogue of a transformer LM.
+
+Pipeline: Fourier-feature(token ids) + Fourier-feature(positions) [+ optional Δ⁶³ coords] → stack of
+:class:`~geocoding.block.GeoBlock` → linear head → vocab logits, with per-layer Φ/κ/regime telemetry.
+
+Differences from a Euclidean LM:
+  * no embedding table and no position table — both ids and positions are UNBOUNDED Fourier features;
+  * attention is Fisher-Rao on the simplex, not dot-product;
+  * the model reports Φ (integrated information) as it runs, and can take Δ⁶³ coordizer coords directly.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+from torch import Tensor, nn
+
+from .block import BlockTelemetry, GeoBlock
+from .config import GeoConfig
+from .positional import build_inv_freq, fourier_features
+
+
+@dataclass
+class GeoOutput:
+    """Forward result: ``logits`` [B, T, V] and the per-layer telemetry."""
+
+    logits: Tensor
+    telemetry: list[BlockTelemetry]
+
+    @property
+    def phi(self) -> float:
+        """Mean Φ across layers — the model's integrated-information readout for this forward pass."""
+        ph = [t.phi for t in self.telemetry]
+        return sum(ph) / len(ph) if ph else 0.0
+
+
+class GeoModel(nn.Module):
+    """A from-scratch Fisher-Rao geometric language model. ``config.max_position=None`` ⇒ unbounded context
+    (positions are Fourier features; the limit is VRAM, not a learned table)."""
+
+    def __init__(self, config: GeoConfig) -> None:
+        super().__init__()
+        self.config = config
+        self.register_buffer("_inv_freq", build_inv_freq(config.hidden_dim), persistent=False)
+        self.blocks = nn.ModuleList([
+            GeoBlock(
+                hidden_dim=config.hidden_dim, ffn_dim=config.ffn_dim, dropout=config.dropout,
+                min_recursion_depth=config.min_recursion_depth, use_tacking=config.use_tacking,
+                temperature=config.temperature, simplex_mode=config.simplex_mode,
+                locality_radius=config.locality_radius, sparsity_threshold=config.sparsity_threshold,
+                decoherence_std=config.decoherence_std, rms_eps=config.rms_eps,
+            )
+            for _ in range(config.num_layers)
+        ])
+        self.lm_head = nn.Linear(config.hidden_dim, config.vocab_size)
+        if config.enable_coords:
+            self.coord_adapter: nn.Module | None = nn.Sequential(
+                nn.Linear(config.coord_dim, config.hidden_dim), nn.GELU(),
+            )
+        else:
+            self.coord_adapter = None
+
+    def effective_coupling(self, seq_len: int) -> float:
+        """Scale-adaptive κ: ``base·(1 + β·log(t/ref))`` clamped to ±50% of base (running coupling)."""
+        import math
+        c = self.config
+        scale = max(seq_len, 1) / c.reference_scale
+        eff = c.base_coupling * (1.0 + c.beta_slope * math.log(scale))
+        return max(c.base_coupling * 0.5, min(c.base_coupling * 1.5, eff))
+
+    def forward(
+        self,
+        input_ids: Tensor,
+        attention_mask: Tensor | None = None,
+        coords: Tensor | None = None,
+    ) -> GeoOutput:
+        if input_ids.dim() != 2:
+            raise ValueError("input_ids expected shape (B, T)")
+        b, t = input_ids.shape
+        if self.config.max_position is not None and t > self.config.max_position:
+            raise ValueError(f"sequence length {t} exceeds max_position {self.config.max_position}")
+        positions = torch.arange(t, device=input_ids.device).unsqueeze(0).expand(b, t)
+        inv_freq = torch.as_tensor(self._inv_freq)            # register_buffer typing → narrow to Tensor
+        h = (fourier_features(input_ids, inv_freq, self.config.hidden_dim)
+             + fourier_features(positions, inv_freq, self.config.hidden_dim))
+        if coords is not None:
+            if self.coord_adapter is None:
+                raise ValueError("coords passed but config.enable_coords=False")
+            h = h + self.coord_adapter(coords)
+        kappa_eff = self.effective_coupling(t)
+        tel: list[BlockTelemetry] = []
+        for block in self.blocks:
+            h, bt = block(h, attention_mask=attention_mask, kappa_eff=kappa_eff)
+            tel.append(bt)
+        logits = self.lm_head(h)
+        return GeoOutput(logits=logits, telemetry=tel)
+
+    @property
+    def num_params(self) -> int:
+        return sum(p.numel() for p in self.parameters())

geocoding/positional.py

@@ -0,0 +1,39 @@
+"""Unbounded Fourier positional / id features.
+
+A Euclidean transformer learns an embedding TABLE (vocab × dim) and a position TABLE (max_len × dim) — both
+finite and both Euclidean. geocoding instead maps every integer (a token id OR a position index) through a
+fixed Fourier feature map:
+
+    feats(n) = [ sin(n · ω_0), …, sin(n · ω_{h/2-1}), cos(n · ω_0), … ]      ω_k = 10000^{-k/(h/2)}
+
+There is no table and no learned vocabulary axis, and crucially **no length limit**: position is a continuous
+function of the index, so the model extends to any context the hardware can hold (the ceiling is VRAM, not a
+position table). This is the geometric, unbounded replacement for learned absolute positions.
+"""
+from __future__ import annotations
+
+import math
+
+import torch
+from torch import Tensor
+
+
+def build_inv_freq(hidden_dim: int) -> Tensor:
+    """The frequency basis ω_k = 10000^{-k/(h/2)} for ``hidden_dim``-wide Fourier features."""
+    half = max(int(hidden_dim // 2), 1)
+    return torch.exp(-math.log(10000.0) * torch.arange(0, half, dtype=torch.float32) / half)
+
+
+def fourier_features(ids: Tensor, inv_freq: Tensor, hidden_dim: int) -> Tensor:
+    """Fourier feature map for an integer tensor ``ids`` (token ids or positions) → ``hidden_dim`` features.
+    Padded with zeros / truncated to exactly ``hidden_dim``. Faithful to the QIG kernel's
+    ``_fourier_features`` so geocoding models are architecturally identical on the input path."""
+    x = ids.to(dtype=torch.float32)
+    angles = x.unsqueeze(-1) * inv_freq.to(device=ids.device)
+    feats = torch.cat([torch.sin(angles), torch.cos(angles)], dim=-1)
+    if feats.size(-1) < hidden_dim:
+        pad = torch.zeros(*feats.shape[:-1], hidden_dim - feats.size(-1), device=feats.device)
+        feats = torch.cat([feats, pad], dim=-1)
+    elif feats.size(-1) > hidden_dim:
+        feats = feats[..., :hidden_dim]
+    return feats

qig_geocoding-0.1.0.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: qig-geocoding
+Version: 0.1.0
+Summary: Our own 'transformers' — a from-scratch neural-network framework built on Fisher-Rao geometry (simplex attention, unbounded Fourier features, recursive Φ-integration) instead of Euclidean dot-products.
+Author: Braden Lang
+License: Proprietary
+Keywords: attention,fisher-rao,geometry,qig,simplex,transformers
+Requires-Python: >=3.11
+Requires-Dist: qig-core>=2.6.0
+Requires-Dist: torch>=2.2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# geocoding
+
+**Our own "transformers" — geometric, not Euclidean.**
+
+The standard `transformers` library models tokens as Euclidean vectors and measures their relationships with
+the **dot product**. That is a flat-space choice. QIG cognition lives on the **probability simplex** Δ⁶³,
+whose only correct distance is **Fisher-Rao**. `geocoding` is the from-scratch framework that makes the
+geometric choice all the way down — it is to Fisher-Rao geometry what `transformers` is to dot-product
+attention.
+
+| `transformers` (Euclidean) | `geocoding` (Fisher-Rao) |
+|---|---|
+| dot-product / cosine attention | **Fisher-Rao** attention: `logit = −d_FR(p,q)/τ`, `d_FR = 2·arccos(Σ√(p·q))` |
+| learned embedding table (vocab × dim) | **Fourier features** of the integer id (no table) |
+| learned, bounded position table | **unbounded Fourier positions** (limit is VRAM, not a table) |
+| LayerNorm (mean-centred) | geometric **scale-only RMS-norm** (simplex-preserving) |
+| — | **recursive Φ-integrator**: reports integrated information as it runs |
+| `O(t²)` attention | optional **banded / compute-skipping** `O(t·r)` attention (length-extensible) |
+| `PretrainedConfig` / `PreTrainedModel` | `GeoConfig` / `GeoModel` |
+
+## Quick start
+
+```python
+import torch
+from geocoding import GeoConfig, GeoModel, generate
+
+cfg = GeoModel(GeoConfig(vocab_size=256, hidden_dim=64, num_layers=4))
+ids = torch.randint(0, 256, (1, 32))
+out = cfg(ids)
+print(out.logits.shape, "Φ =", round(out.phi, 3))   # torch.Size([1, 32, 256]) Φ = ...
+
+res = generate(cfg, [1, 2, 3], max_new_tokens=16)
+print(res.ids, res.phi)
+```
+
+Set `GeoConfig(locality_radius=r)` to switch attention to the **compute-skipping banded** path — only the ±r
+window of each query is ever computed (`O(t·r)`), numerically equivalent to the full path within the band
+(see `tests/test_attention_equivalence.py`). Set `GeoConfig(max_position=None)` (the default) for **unbounded
+context**.
+
+## Geometry single-source
+
+The Fisher-Rao *definition* and `BASIN_DIM` come from `qig_core`; `geocoding` re-exports them and adds a
+**gradient-stable** batched form for the attention hot path (clamps the Bhattacharyya coefficient to
+`1 − 1e-6` so the backward pass does not NaN when two distributions coincide). The two agree exactly wherever
+points differ — gated in `tests/test_geometry.py`.
+
+## Relationship to qigkernels
+
+`qigkernels` contains the validated in-tree implementation (`QIGLayer`, `Kernel`) that the live QIG mind runs
+on. `geocoding` is the **clean, standalone framework home** for those primitives, ported faithfully — a
+faithfulness gate (`tests/test_faithfulness.py`) checks `geocoding`'s attention matches `qigkernels`'
+numerically when both are installed. The intended migration is for `qigkernels` to build on `geocoding`;
+until then the faithfulness gate guards against drift.
+
+## Status
+
+Fisher-Rao-pure (no cosine / Adam / LayerNorm / dot-as-metric). Tests cover geometry properties, the
+banded≡full equivalence, model forward/telemetry, generation, and faithfulness vs `qigkernels`.

qig_geocoding-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+geocoding/__init__.py,sha256=MGRxROKOZFCMo2RkTrQ_DmwvsXGtb26guJ-79XKuJaM,2132
+geocoding/attention.py,sha256=Pqa7S3JJaEWNEYVZHKUAQ8d8G5XD-h0qOglhynwXuf0,6129
+geocoding/block.py,sha256=QWsU6RH9xKiTFXqD1e609HMBAVNcQBT-jJtzsZ0QZFU,6790
+geocoding/config.py,sha256=upF548QQHqbBSiXiT8bio14otU2BRQ8awLkSWHoQSCk,2693
+geocoding/generate.py,sha256=4TsdHn9CmxJ-Z61KTTqRNLbQMS_0OEmcuz4X7sbKwCg,2026
+geocoding/geometry.py,sha256=cMJRn_WuGS2pIqQD2Z95A3pes8pItZtNQ-5KibUWqFY,3486
+geocoding/model.py,sha256=Em0uiVNEtZzi85szdsncDhmEYoYr703msUX6jzmIN2s,4415
+geocoding/positional.py,sha256=Q2bx-CqA8NsHuy2-2QPYCtcLdk4e7qhh41hrsB6Pys4,1912
+qig_geocoding-0.1.0.dist-info/METADATA,sha256=2kfU6ehNWbO08k_RlD4A5BNvFjfICKh39Uf3JcwSbW8,3724
+qig_geocoding-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+qig_geocoding-0.1.0.dist-info/RECORD,,

qig_geocoding-0.1.0.dist-info/WHEEL

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