fluidlayer 2.0.0__py3-none-any.whl

fluidlayer/torch_graft.py

@@ -0,0 +1,283 @@
+"""
+fluidlayer.torch_graft — the same memory layer, in PyTorch, for a REAL LLM.
+This is the GPU-scale twin of `fluidlayer/graft.py`.  It exists because the
+numpy implementation cannot be attached to a pretrained transformer: it
+needs a tied embedding table to turn a stored token id back into a
+vector, and it needs the model's own scales.
+WHAT IS THE SAME AS THE NUMPY VERSION
+the two tiers: a lossy (diffusion) state and an exact, content-keyed
+store of token ids;
+the attach-is-a-no-op property: `Wo_exact` and `Wo_lossy` start at ZERO,
+so attaching the branch leaves the logits bit-identical;
+the read gain and the contrast transform (`pc1`), because with a tied
+readout a raw embedding injection boosts the token's embedding-space
+neighbours too;
+causality: the store is written from the pair (context ending at t-1,
+token at t), so a token is never read back before it was written.
+the exact store uses majority tracking and least-corroborated eviction,
+matching the NumPy reference.
+WHAT IS DIFFERENT
+the state lives in a torch tensor (it can be a parameter, a buffer, or
+just an attribute);
+the writes are done under `no_grad` -- the layer is a MEMORY, and the
+exactness of the tier does not depend on differentiating through it;
+the contrast transform is computed once from the model's embedding table
+(on the right device) and can be refreshed after the model is trained.
+The optional PyTorch parity test runs in CI. `experiments/gpu_graft.py`
+is the driver for GPU-scale experiments.
+"""
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+from .graft import _ModeStore
+
+__all__ = ["SAABranchTorch", "ctx_hash"]
+
+
+def ctx_hash(tokens) -> int:
+    """FNV-1a 64-bit hash of a token sequence (the content key)."""
+    h = 0xCBF29CE484222325
+    for t in tokens:
+        h ^= int(t) & 0xFFFFFFFFFFFFFFFF
+        h = (h * 0x100000001B3) & 0xFFFFFFFFFFFFFFFF
+    return h
+
+
+class SAABranchTorch(nn.Module):
+    """The attachable memory layer (torch).
+
+    Parameters
+     ----------
+     M, r, d   : anchors, rank, model width
+     emb       : the model's input embedding matrix (tied or not).  Used to
+                 turn a stored token id back into a vector.
+     ctx_len   : how many trailing tokens form the content key
+     capacity  : max entries in the exact store
+     read_gain : the scalar gain of the exact injection (CALIBRATE it; see
+                 the gain sweep in results/e6_graft.json)
+     transform : "raw" | "center" | "pc1" -- the selectivity of the injection
+     """
+
+    def __init__(self, M: int = 64, r: int = 8, d: int = 64, emb=None,
+                 ctx_len: int = 1, capacity: int = 4096, read_gain: float = 300.0,
+                 transform: str = "pc1", use_exact: bool = True,
+                 use_lossy: bool = False, seed: int = 0,
+                 use_router: bool = True):
+        super().__init__()
+        for name, value in (("M", M), ("r", r), ("capacity", capacity)):
+            if int(value) <= 0:
+                raise ValueError(f"{name} must be positive, got {value}")
+        g = torch.Generator().manual_seed(seed)
+        self.M, self.r, self.d = int(M), int(r), int(d)
+        self.ctx_len = int(ctx_len)
+        self.capacity = int(capacity)
+        self.read_gain = float(read_gain)
+        self.transform = str(transform)
+        self.use_exact, self.use_lossy = bool(use_exact), bool(use_lossy)
+        self.use_router = bool(use_router)
+        self.protos = nn.Parameter(torch.randn(M, d, generator=g) * d ** -0.5)
+        self.Wq = nn.Parameter(torch.randn(d, d, generator=g) * d ** -0.5)
+        self.Wk = nn.Parameter(torch.randn(d, d, generator=g) * d ** -0.5)
+        self.Wv = nn.Parameter(torch.randn(d, r, generator=g) * d ** -0.5)
+        self.Wr = nn.Parameter(torch.randn(r, d, generator=g) * d ** -0.5)
+        # ZERO => attaching the branch is an EXACT identity
+        self.Wo_exact = nn.Parameter(torch.zeros(d, d))
+        self.Wo_lossy = nn.Parameter(torch.zeros(d, d))
+        self.emb = emb          # NOT a parameter: it belongs to the model
+        self.state = torch.zeros(M, r)
+        self.store = _ModeStore(capacity=self.capacity)
+        self.anchor_store = _ModeStore(capacity=self.M)
+        self._buf: list[int] = []
+        self._contrast = None
+
+    # ------------------------------------------------------------- lifecycle
+    def reset(self):
+        self.state = torch.zeros_like(self.state)
+        self.store.clear()
+        self.anchor_store.clear()
+        self._buf.clear()
+
+    def refresh_contrast(self):
+        """Recompute the (optionally transformed) embedding table."""
+        self._contrast = None
+
+    def _contrast_table(self, device, dtype):
+        if self._contrast is None:
+            E = self.emb.weight if hasattr(self.emb, "weight") else self.emb
+            E = E.detach().to(device=device, dtype=torch.float32)
+            t = self.transform
+            if t == "center":
+                E = E - E.mean(0, keepdim=True)
+            elif t.startswith("pc"):
+                k = int(t[2:] or 1)
+                # the SVD is done ONCE, on the right device
+                _, _, Vt = torch.linalg.svd(E, full_matrices=False)
+                for j in range(min(k, Vt.shape[0])):
+                    p = Vt[j]
+                    E = E - torch.outer(E @ p, p)
+            self._contrast = E.to(dtype=dtype)
+        return self._contrast
+
+    def state_bytes(self) -> int:
+        """Logical packed-payload estimate; excludes Python/allocator overhead."""
+        return (self.state.numel() * 4 + len(self.store) * 20
+                + len(self.anchor_store) * 20)
+
+    # ----------------------------------------------------------------- maths
+    def _route(self, content: torch.Tensor):
+        """content (T, d) -> soft top-k weights (T, M) and the argmax (T,)."""
+        q = content @ self.Wq
+        kk = self.protos @ self.Wk
+        sc = (q @ kk.T) / (self.d ** 0.5)
+        k = min(4, self.M)
+        top = sc.topk(k, dim=-1).indices
+        w = torch.zeros_like(sc)
+        s = sc.gather(1, top)
+        s = s - s.max(dim=-1, keepdim=True).values
+        e = torch.softmax(s, dim=-1)
+        w.scatter_(1, top, e)
+        return w, top[:, 0]
+
+    def _key(self, buf):
+        if len(buf) < self.ctx_len:
+            return None
+        if self.ctx_len == 1:
+            return int(buf[-1])
+        return ctx_hash(buf[-self.ctx_len:])
+
+    def _put(self, key: int, value: int):
+        self.store.put(key, value)
+
+    def gated_logits(self, logits, info, gain: float = 8.0,
+                     use_support: bool = False, support_scale: float = 1.0,
+                     tau: float | None = None, c_min: float = 2.0,
+                     big: float = 20.0, router_weight: float = 0.3,
+                     gate_space: str = "logit"):
+        """Apply the NumPy reference's uncertainty-gated retrieval boost."""
+        retrieved = info.get("retrieved")
+        if retrieved is None:
+            return logits
+        z = logits
+        retrieved = torch.as_tensor(retrieved, device=z.device, dtype=torch.long)
+        T = z.shape[0]
+        fallback = torch.zeros(T, device=z.device, dtype=torch.bool)
+        rr = info.get("router_retrieved")
+        rconf = info.get("router_confidence")
+        if rr is not None:
+            rr = torch.as_tensor(rr, device=z.device, dtype=torch.long)
+            fallback = (retrieved < 0) & (rr >= 0)
+            retrieved = torch.where(fallback, rr, retrieved)
+
+        probs = torch.softmax(z, dim=1)
+        p_max = probs.max(dim=1).values
+        if str(gate_space) == "logit":
+            uncertainty = -torch.log(p_max.clamp_min(1e-12))
+        else:
+            uncertainty = 1.0 - p_max
+        if tau is None:
+            tau = 20.0 if str(gate_space) == "logit" else 2.0
+        boost = float(gain) * uncertainty
+
+        if rconf is not None:
+            rc = torch.as_tensor(rconf, device=z.device, dtype=z.dtype)
+            boost = torch.where(
+                fallback,
+                boost * float(router_weight) * rc.clamp(0.0, 1.0),
+                boost,
+            )
+        if use_support:
+            support = info.get("support")
+            if support is not None:
+                sup = torch.as_tensor(support, device=z.device, dtype=z.dtype)
+                boost = boost * (sup / float(support_scale)).clamp(max=1.0)
+
+        confidence = info.get("confidence")
+        if confidence is None:
+            conf = torch.zeros(T, device=z.device, dtype=z.dtype)
+        else:
+            conf = torch.as_tensor(confidence, device=z.device, dtype=z.dtype)
+        if rconf is not None:
+            rc = torch.as_tensor(rconf, device=z.device, dtype=z.dtype)
+            conf = torch.where(fallback, rc, conf)
+        decide = (uncertainty >= float(tau)) | (conf >= float(c_min))
+        boost = torch.where(decide, torch.full_like(boost, float(big)), boost)
+
+        out = z.clone()
+        rows = torch.nonzero(retrieved >= 0, as_tuple=False).flatten()
+        if rows.numel():
+            out[rows, retrieved[rows]] += boost[rows]
+        return out
+
+    # ---------------------------------------------------------------- forward
+    def forward(self, h: torch.Tensor, content: torch.Tensor,
+                token_ids: torch.Tensor):
+        """h, content: (T, d);  token_ids: (T,) int64."""
+        T = token_ids.shape[0]
+        ids = token_ids.detach().cpu().tolist()
+        w, am = self._route(content.detach())
+        out_e = None
+        hits = 0
+        retrieved = torch.full((T,), -1, dtype=torch.long)
+        confidence = torch.zeros(T, dtype=torch.float32)
+        router_retrieved = torch.full((T,), -1, dtype=torch.long)
+        router_confidence = torch.zeros(T, dtype=torch.float32)
+        if self.use_exact and self.emb is not None:
+            C = self._contrast_table(h.device, h.dtype)
+            rows = torch.zeros(T, self.d, device=h.device, dtype=h.dtype)
+            buf = list(self._buf)
+            for t in range(T):
+                prev_key = self._key(buf)
+                buf.append(int(ids[t]))
+                if len(buf) > self.ctx_len:
+                    buf = buf[-self.ctx_len:]
+                key = self._key(buf)
+                if self.use_router:
+                    anchor = int(am[t])
+                    value = self.anchor_store.get(anchor, -1)
+                    if value >= 0:
+                        router_retrieved[t] = value
+                        router_confidence[t] = self.anchor_store.confidence(anchor)
+                v = self.store.get(key, -1)
+                if v >= 0:
+                    rows[t] = C[v] * self.read_gain
+                    retrieved[t] = v
+                    confidence[t] = self.store.confidence(key)
+                    hits += 1
+                if prev_key is not None:
+                    self._put(prev_key, int(ids[t]))
+                if t > 0 and self.use_router:
+                    self.anchor_store.put(int(am[t - 1]), int(ids[t]))
+            self._buf = buf
+            out_e = rows
+
+        if self.use_lossy:
+            with torch.no_grad():
+                self.state = self.state + w.T @ (h.detach() @ self.Wv.detach())
+                self.state = 0.9 * self.state        # a simple decay
+            out_l = (w @ self.state) @ self.Wr
+        else:
+            out_l = None
+
+        h_out = h
+        if out_e is not None:
+            h_out = h_out + out_e @ self.Wo_exact
+        if out_l is not None:
+            h_out = h_out + out_l @ self.Wo_lossy
+        support = torch.tensor(
+            [self.store.support.get(int(v), 0) if v >= 0 else 0
+             for v in retrieved],
+            dtype=torch.long,
+        )
+        return h_out, {
+            "route": w,
+            "anchor": am,
+            "hits": hits,
+            "emb_read": out_e,
+            "retrieved": retrieved,
+            "support": support,
+            "confidence": confidence,
+            "router_retrieved": router_retrieved,
+            "router_confidence": router_confidence,
+        }

fluidlayer-2.0.0.dist-info/METADATA

@@ -0,0 +1,376 @@
+Metadata-Version: 2.4
+Name: fluidlayer
+Version: 2.0.0
+Summary: A research memory layer for language models using cellular-sheaf diffusion
+Author: Kapil Dhinwa
+License: MIT
+Project-URL: Homepage, https://github.com/kapildhinwa2010-dev/fluidtech
+Project-URL: Repository, https://github.com/kapildhinwa2010-dev/fluidtech
+Project-URL: Issues, https://github.com/kapildhinwa2010-dev/fluidtech/issues
+Project-URL: Changelog, https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/docs/CHANGELOG.md
+Keywords: llm,memory,long-context,kv-cache,retrieval,cellular-sheaves,persistent-homology
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.23
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Provides-Extra: gpu
+Requires-Dist: torch>=2.1; extra == "gpu"
+Requires-Dist: transformers>=4.40; extra == "gpu"
+Requires-Dist: accelerate>=0.30; extra == "gpu"
+Requires-Dist: safetensors>=0.4; extra == "gpu"
+Dynamic: license-file
+
+# FluidLayer
+
+**A research memory layer for LLMs — attachable with one residual-stream insertion.**
+
+`16 KB` research-scale fluid state as a compact long-range channel ·<br>
+exact recall of retained token IDs from outside the attention window ·<br>
+pure NumPy core, with optional PyTorch support ·<br>
+eleven measured negative results, published on purpose
+
+[![CI](https://github.com/kapildhinwa2010-dev/fluidtech/actions/workflows/ci.yml/badge.svg)](https://github.com/kapildhinwa2010-dev/fluidtech/actions/workflows/ci.yml)
+![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)
+![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)
+![Self-verification](https://img.shields.io/badge/self--verification-50%2F50-brightgreen.svg)
+
+---
+
+## The problem, in one number
+
+A 70B model on 2×H100 80GB cannot hold a single 128K-token session.
+
+The weights take **131.5 GB**; the KV cache for 128K tokens needs another **40 GB**, and only **28.5 GB** is left.
+This is a memory-budget illustration, not a claim that this prototype
+replaces a KV cache or is a drop-in serving optimization.
+
+The usual answer is to quantise it, compress it, or make the model smaller.
+This project asks a different question:
+
+> What if a compact, constant-size memory channel sat beside attention and
+> could be addressed by content instead of position?
+
+---
+
+## What this is
+
+A research memory layer designed to attach to a causal LM:
+
+```text
+h' = h + W_e · E(h)  +  W_l · S(h)
+         ^^^^^^         ^^^^^
+         exact tier     lossy tier (the constant-size fluid state)
+```
+
+- The **exact tier** is a bounded, content-keyed store of token IDs.
+  **20 bytes per packed slot.** A recalled value is an `int32` — bit-exact, not approximate.
+  The attachable store tracks majority continuations and evicts the
+  least-corroborated entries. Bit-exactness describes the stored token ID,
+  not its truth or provenance. The Python reference's memory estimate
+  excludes Python object overhead.
+
+- The **lossy tier** is a sheaf-diffusion aggregate over `M` anchors — `M × r` floats, constant size, whatever you stream through it.
+
+The two tiers exist because a diffusion smears. If the exact value of a token lives only inside the fluid, it is mixed with its neighbours and is provably no longer exact.
+
+So:
+
+> **The fluid answers WHERE. The register answers WHAT.**
+
+---
+
+## The three numbers
+
+| Claim | Measured result |
+|---|---|
+| Attaching the layer changes nothing | The logits are **bit-identical** (max diff `0.000e+00`). The output projections start at zero, so the branch is a **provable no-op** until someone trains it. |
+| It adds a capability the model did not have | Cross-window verbatim recall: **`0.050 → 0.800`** (chance `0.125`) — **16× the base model** — for a fact planted 400 tokens outside the attention window. |
+| The stored token ID is exact | A retained token ID is returned bit-exactly. This does not verify whether the token is true, safe, or authenticated. |
+| The model gets better | Gated retrieval improves the base model’s perplexity by **`−0.176 nats`** (`ppl 13.61 → 11.42`) — the model’s own confidence decides when the memory speaks. |
+| It beats its closest prior art in the regime it targets | Against a **kNN-LM** (the standard way to use a datastore), with a **16 KB** store the gated layer wins by **7.4×** on loss (`−0.1134 vs −0.0154`). With a 1 MB store the kNN-LM wins by 6.4×, so the claim is precise: **the gate is the contribution under a hard memory budget.** |
+| The fluid tier earns its place | Used as the **router** (the geometry as an address space), it rescues recall when the exact store is too small (`0.100 → 0.625`) and fixes hard contexts where the base model has no idea (`+0.053 → −0.071 nats`) — at **0.0005%** of a layer’s compute. |
+| The diffusion tier delivers none of it | With the lossy tier alone: **`0.050`**, i.e. the base model’s own number. The exact tier delivers **all** of it. |
+
+Measured on a frozen base model, in [`results/e6_graft.json`](results/e6_graft.json).
+The recipe is in [`docs/GRAFT.md`](docs/GRAFT.md).
+
+---
+
+## Try it, in 60 seconds
+
+```bash
+git clone https://github.com/kapildhinwa2010-dev/fluidtech.git
+cd fluidtech
+pip install -r requirements.txt
+
+python selftest.py              # 50 machine-checked claims
+python examples/quickstart.py   # the tour
+python examples/graft_demo.py   # the capability, end to end
+python examples/gate_demo.py    # the gate: recall AND a better perplexity
+python experiments/e11_exact.py # the exact memory (the full benchmark)
+```
+
+To install the published package instead of cloning the repository:
+
+```bash
+python -m pip install fluidlayer
+```
+
+Expected output:
+
+```text
+base model        : 1/20 correct  (it never saw the fact)
+base + the layer  : 20/20 correct  (the layer retrieved it)
+```
+
+---
+
+## Using it
+
+```python
+import torch
+from fluidlayer.torch_graft import SAABranchTorch
+
+# Assume `model` is a loaded causal LM and `windows` contains 1-D token-ID tensors.
+embedding = model.get_input_embeddings()
+branch = SAABranchTorch(
+    M=64,
+    r=8,
+    d=embedding.weight.shape[1],
+    emb=embedding,
+    ctx_len=1,
+    read_gain=300.0,
+    transform="pc1",
+    use_exact=True,
+    use_lossy=False,
+).to(embedding.weight.device)
+
+branch.reset()                       # a new session
+
+with torch.no_grad():
+    for input_ids in windows:        # one 1-D token-ID window at a time
+        content = embedding(input_ids)
+        residual = content
+        h, info = branch(residual, content, input_ids)
+        logits = model(inputs_embeds=h.unsqueeze(0)).logits[0]
+        logits = branch.gated_logits(logits, info)
+```
+
+- **4 KB** of fluid state for `M=64, r=8`, plus a logical **20 B per populated context or anchor slot**; the Python reference has additional object overhead.
+- The base model is frozen the whole time.
+- The output projections start at zero, so attachment initially preserves
+  the model output. Enabling retrieval is a separate, calibrated operation.
+- This sketch omits model-specific positional embeddings, attention masks,
+  session lifecycle, and gain calibration. See the [integration notes](docs/GETTING_STARTED.md#attach-the-optional-pytorch-adapter).
+- The NumPy reference implementation is [`fluidlayer/graft.py`](fluidlayer/graft.py), and the Torch one mirrors it exactly.
+
+Start with the [documentation guide](docs/README.md), then read
+[Getting started](docs/GETTING_STARTED.md) and the [API reference](docs/API.md).
+
+---
+
+## What it does not do
+
+Being explicit, because this is where grafts usually oversell:
+
+- It does **not** make the model better at language — it makes it better at remembering what it has already seen.
+- It does **not** extend the attention window — the window is still 128 tokens; the layer can quote from outside it, not reason over it.
+- It does **not** compose, infer, or answer questions about what it holds.
+- The diffusion tier has **no measurable upside** on real text and used to damage the model it was attached to (`+0.81 nats`) until its training signal was fixed — keep it off.
+
+The full list, with numbers: [`docs/LIMITATION.md`](docs/LIMITATION.md)
+
+---
+
+## At ten million tokens
+
+Give a model 10M tokens with the layer attached, and:
+
+- The state is still **16 KB**.
+  The same tokens as a KV cache would require **1.31 TB** for an 8B model, **3.28 TB** for a 70B one.
+- Filling it costs **80 seconds** and **no model forward at all** — the exact tier is model-free.
+- With distinctive keys it recalls **6/6** facts planted from 100K to 9M tokens deep.
+  With realistic 12-gram keys and a 16 KB budget it recalls **0/6** — its reach is the last ~10,000 tokens.
+- The perplexity delta is **`−0.0057 nats`** at the right injection gain, and **`+1.08 nats`** at the gain that maximises recall — the two knobs are three orders of magnitude apart.
+  The gate closes that gap: scaling the override by the model’s own uncertainty keeps recall at **`1.000`** and improves perplexity to **`11.42`**.
+
+Details: [`docs/TEN-MILLION.md`](docs/TEN-MILLION.md)
+
+---
+
+## The negative results
+
+This is the part that makes the rest believable.
+Eleven results came out negative or against expectation, and all eleven are measured, reproducible, and published.
+
+| What we expected | What happened |
+|---|---|
+| The **topological** selection criterion picks the right facts | It does **not** — `0.000` precision vs `0.970` for plain geometric affinity. |
+| `‖L·1‖∞` detects the frozen state | It does **not** — the frustration index does; the old claim is now a test case. |
+| `λ₂` predicts long-context quality | Barely — Pearson `0.20`. |
+| A transformer loses at some scale | It **wins** at every scale we could train. |
+| A domain prior beats a frequency table | It helps (`−0.006 nats`) but a **unigram table wins 6× more**. |
+| The diffusion tier is neutral on a frozen model | It **degrades** the model by **`+0.81 nats`** (fixed → `+0.0000`, but no upside either). |
+| Training the layer helps | It **hurts** — the training-free identity map is better (`0.800 vs 0.650`). |
+
+Read it: [`docs/NEGATIVE-RESULTS.md`](docs/NEGATIVE-RESULTS.md)
+
+---
+
+## The repository
+
+```text
+fluidlayer/            the package (pure NumPy; torch only in torch_graft.py)
+  graft.py             the attachable memory layer
+  memory.py            the frozen register (20 B per fact, bit-exact)
+  torch_graft.py       the same layer in PyTorch, for a real LLM
+  gpt2_model.py        a GPT-2 forward pass in PyTorch (no transformers needed)
+  gpt2_tokenizer.py    the GPT-2 byte-level BPE, in pure Python
+  sheaf.py topology.py diffusion.py blocks.py autodiff.py ...
+
+experiments/           every measurement; each writes a JSON into results/
+  e14_real_gpt2.py     the graft on a REAL pretrained GPT-2 (124M)
+  e13_knn_baseline.py  the layer vs. the closest prior art (kNN-LM)
+
+tools/                 the artifact checker, bundler, checkpoint downloader,
+                       and PyPI fetcher
+fluidlayer/bpe.py      the byte-level BPE tokenizer
+
+tests/                 the unit tests (pytest, or run them without it)
+
+examples/              quickstart.py, graft_demo.py, gate_demo.py
+
+docs/                  the design docs, the API, the limits, the theory report
+
+results/               every number in the README, as JSON
+```
+
+---
+
+## Documentation
+
+Browse the [documentation guide](docs/README.md) for a topic-based index.
+The [getting-started tutorial](docs/GETTING_STARTED.md) and
+[API reference](docs/API.md) are the recommended entry points. Research
+claims and their limits are explained in the
+[graft report](docs/GRAFT.md), [negative results](docs/NEGATIVE-RESULTS.md),
+and [limitations](docs/LIMITATION.md).
+
+---
+
+## Status — and it now includes a REAL pretrained LLM
+
+GPT-2 (124M parameters, the real 50,257-token BPE tokenizer), run on CPU with the memory layer attached:
+
+| Test | Result |
+|---|---|
+| Attaching the layer | The logits are **bit-identical** (max diff `0.000e+00`). |
+| A fact planted **2,947 tokens** before the query | The base GPT-2 predicts `464`; **the layer predicts the fact**. |
+| The base model’s perplexity | `4.0289` (`ppl 56.20`) → **`4.0019` (`ppl 54.70`)** with the layer. |
+
+And one result that narrows the claim honestly:
+
+On the real model, the classic kNN-LM interpolation beats the gated override by **8×** on perplexity — the opposite of the 131k-parameter model, where the gate won by **7.4×**.
+The gate wins where the base model is weak; interpolation wins where it is strong.
+The capability works on both.
+
+The checkpoint, the forward pass and the tokenizer are all in this repository:
+
+- [`fluidlayer/gpt2_model.py`](fluidlayer/gpt2_model.py)
+- [`fluidlayer/gpt2_tokenizer.py`](fluidlayer/gpt2_tokenizer.py)
+
+No `transformers` dependency, and the generation is verified coherent.
+
+The Torch twin is now tested against the NumPy reference in [`tests/test_torch_parity.py`](tests/test_torch_parity.py): the two implementations must agree on the router, the store and the gated override.
+
+That test found **four real port bugs**:
+
+1. A different route scale.
+2. The wrong routing content — the residual stream instead of the position-free embedding.
+3. A different confidence formula.
+4. A read/write order that broke the snapshot semantics.
+
+Four bugs that would have shipped silently.
+
+The checks cover the tested behaviors; they do not prove every research
+claim or validate production-scale operation.
+
+---
+
+## A research prototype, honestly labelled
+
+Everything above was measured on CPU, at small scale, on a character-level or 512-token subword corpus, with a **131,392-parameter model**.
+
+The subword repeat is the closest thing to a realistic tokenizer in this repository.
+The GPU run, [`experiments/gpu_graft.py`](experiments/gpu_graft.py), is written and has not been executed here.
+
+---
+
+## Reproducing
+
+```bash
+python selftest.py                    # 50 checks
+python experiments/run_all.py --full  # every measurement (~40 min, CPU)
+```
+
+Everything is pure NumPy, CPU-only, and needs no network.
+
+The details and expected outputs: [`docs/REPRODUCING.md`](docs/REPRODUCING.md)
+
+---
+
+---
+
+## 🤝 Contributions & corrections
+
+Suggestions, bug reports, and corrections are welcome, especially measurement
+disagreements. Please open an issue or submit a pull request.
+
+If a number in the docs does not match what you get, that is a bug in the code or in the documentation, and it is the most valuable report you can file.
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+If you use this, please cite it: [`CITATION.cff`](CITATION.cff).
+
+---
+
+## Confession
+
+The project began as:
+
+> “Replace attention with a sheaf diffusion.”
+
+The measurements have said three times that this is not the way.
+
+What is left is smaller and much more defensible:
+
+A research memory layer with an operator-level stability bound, a bounded in-memory register that returns retained token IDs bit-exactly, 50 machine-checked claims, and published measurements of its limitations. The register is not tamper-evident, encrypted, or tenant-isolated by default.
+
+## Origin and acknowledgments
+
+The project began with the author's idea of flowing information through a
+topological structure. The implementation and repository organization were
+developed with AI assistance. The measurements, limitations, and research
+decisions are documented alongside the code so the work can be evaluated and
+reproduced.

fluidlayer-2.0.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+fluidlayer/__init__.py,sha256=HxMH5kFeBicWQHwNKsZzffn6_GoeMSsYW6SfaazBZ2Q,3892
+fluidlayer/autodiff.py,sha256=Zu0pLZf-C1UWfPinzHlnulwy0hZOPF_vWUVbZTl97Gc,15442
+fluidlayer/blocks.py,sha256=ftPkYT8ER55ySJlCJ6e-Q-r3-Ji_6s2UjifQ_DAKaPY,11835
+fluidlayer/bpe.py,sha256=Hsg59XJEBCnQ7zh-ZJpxo4HJ-oxQ5Qj1A4TjJRZSS7o,6265
+fluidlayer/data.py,sha256=E4SwzCUgoOYOm0yNsEL71Tb4Z1F4iCI0cozEqOCPaZU,3198
+fluidlayer/diffusion.py,sha256=iUkBy6WNA9LuAZFgoHgGL1_GK6y7D0oSGF1944yls6o,9844
+fluidlayer/gpt2_model.py,sha256=SI1igbJx-yDto8uQH6EYUmpimN7nhYG95mfKcFumw0M,5435
+fluidlayer/gpt2_tokenizer.py,sha256=ZRVGknRje03Hv6KmjNjIZjxcq_ushsS_EZMYqO5CxPE,4287
+fluidlayer/graft.py,sha256=vKDmFSQ3hjz6S8F4XW0SsoG0GWz95ytkXNxjESO9eBo,33068
+fluidlayer/losses.py,sha256=38CbAAa86hxxO4LS-UONI6mnVr9oqZfMAXPO-1S713Y,2764
+fluidlayer/memory.py,sha256=yasTGNw6MQfLJHyGDixMAw9VN24kT4iWhj8sl61It_Q,22126
+fluidlayer/model.py,sha256=sZDy4mhlIjFj-2Gs490MQQe6gnZuTUYdBk3wdGa8XcU,5339
+fluidlayer/optim.py,sha256=b2VxtVagwaFuGE5pFA32AbwNyLYxZJOj-2LgWgyBJhI,2033
+fluidlayer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fluidlayer/sheaf.py,sha256=qrRB-PTr0uqyVXY-arYpa5Z80PAsXh5LlbxuCEidpXo,4851
+fluidlayer/topology.py,sha256=lw2OIp_5_LYY-Y4zxbjVazDsxOHWLS689B-34PsGEjE,10400
+fluidlayer/torch_graft.py,sha256=ys_vYL47Y5C30FibIn2wlrpalDxxD-O614QN0y6iYW0,11997
+fluidlayer-2.0.0.dist-info/licenses/LICENSE,sha256=fA16TuGQSfXe_xwf-IKXk_8CmaRRpZ9nrk-XRas0yc4,1080
+fluidlayer-2.0.0.dist-info/METADATA,sha256=YCDBoRHMpTKPxQHHgcqJtBTP0-iTuL7xF_JGOc5dGVY,16163
+fluidlayer-2.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+fluidlayer-2.0.0.dist-info/top_level.txt,sha256=BpmQMo4rA0HmYCInycdfRk6DF2P0IgIJ3p5XQqNEj3I,11
+fluidlayer-2.0.0.dist-info/RECORD,,

fluidlayer-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+