fluidlayer 2.0.0__tar.gz → 2.1.0__tar.gz

{fluidlayer-2.0.0 → fluidlayer-2.1.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: fluidlayer
-Version: 2.0.0
-Summary: A research memory layer for language models using cellular-sheaf diffusion
+Version: 2.1.0
+Summary: A research memory layer for language models with optional GPT-2 and Qwen2 adapters
 Author: Kapil Dhinwa
 License: MIT
 Project-URL: Homepage, https://github.com/kapildhinwa2010-dev/fluidtech
@@ -216,14 +216,17 @@ 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.
+Eleven negative or unexpected findings are documented. Most have checked-in
+result files; the archived transformer and real-GPT-2 outputs are now
+checked in. Their original model/script environments are not fully included,
+so those historical runs cannot be independently repeated as-is.
 
 | 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 transformer loses at some scale | The archived run says it **wins**; see `results/train_results.json`. |
 | 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`). |
@@ -235,16 +238,18 @@ Read it: [`docs/NEGATIVE-RESULTS.md`](docs/NEGATIVE-RESULTS.md)
 ## The repository
 
 ```text
-fluidlayer/            the package (pure NumPy; torch only in torch_graft.py)
+fluidlayer/            the package (NumPy core; optional PyTorch adapters)
   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
+  qwen2_model.py       an optional PyTorch Qwen2 forward pass
   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)
+  e15_scale_model.py   the graft on Qwen2.5-0.5B
   e13_knn_baseline.py  the layer vs. the closest prior art (kNN-LM)
 
 tools/                 the artifact checker, bundler, checkpoint downloader,
@@ -253,7 +258,7 @@ 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
+examples/              quickstart.py, graft_demo.py, gate_demo.py, appkit/
 
 docs/                  the design docs, the API, the limits, the theory report
 
@@ -273,28 +278,20 @@ and [limitations](docs/LIMITATION.md).
 
 ---
 
-## Status — and it now includes a REAL pretrained LLM
+## Real-model experiment status
 
-GPT-2 (124M parameters, the real 50,257-token BPE tokenizer), run on CPU with the memory layer attached:
+The E14 GPT-2 experiment script, forward implementation, tokenizer, and
+archived `results/e14_real_gpt2.json` are included. The checkpoint is not;
+rerun E14 to independently reproduce the recorded measurements. See
+[the reproduction guide](docs/REPRODUCING.md) for download and run commands.
 
-| 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.
+E15 adds a from-scratch Qwen2.5-0.5B forward implementation and app-kit
+integration. Its archived run records bit-identical attachment, exact recall
+of a planted fact 1,411 tokens back, and a best gated loss improvement of
+`0.041` nats; the kNN-LM baseline improves loss by `0.274` nats, so this run
+does not show the gate outperforming that baseline. The checkpoint is not
+bundled. Reproduction requires the optional GPU dependencies and local model
+weights; see [E15 instructions](docs/REPRODUCING.md#qwen2-scale-experiment-e15).
 
 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.
 
@@ -314,7 +311,9 @@ 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 core research experiments use small CPU models and character-level or
+512-token subword corpora. E14 and E15 are separate pretrained-model
+experiments; their checkpoints are not included.
 
 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.
@@ -370,7 +369,7 @@ A research memory layer with an operator-level stability bound, a bounded in-mem
 ## 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.
+topological structure. The author describes it as a school project and
+credits AI assistance for implementation and repository organization. The
+research decisions, measurements, and limitations are documented alongside
+the code so the work can be evaluated and reproduced.

{fluidlayer-2.0.0 → fluidlayer-2.1.0}/README.md

@@ -179,14 +179,17 @@ 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.
+Eleven negative or unexpected findings are documented. Most have checked-in
+result files; the archived transformer and real-GPT-2 outputs are now
+checked in. Their original model/script environments are not fully included,
+so those historical runs cannot be independently repeated as-is.
 
 | 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 transformer loses at some scale | The archived run says it **wins**; see `results/train_results.json`. |
 | 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`). |
@@ -198,16 +201,18 @@ Read it: [`docs/NEGATIVE-RESULTS.md`](docs/NEGATIVE-RESULTS.md)
 ## The repository
 
 ```text
-fluidlayer/            the package (pure NumPy; torch only in torch_graft.py)
+fluidlayer/            the package (NumPy core; optional PyTorch adapters)
   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
+  qwen2_model.py       an optional PyTorch Qwen2 forward pass
   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)
+  e15_scale_model.py   the graft on Qwen2.5-0.5B
   e13_knn_baseline.py  the layer vs. the closest prior art (kNN-LM)
 
 tools/                 the artifact checker, bundler, checkpoint downloader,
@@ -216,7 +221,7 @@ 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
+examples/              quickstart.py, graft_demo.py, gate_demo.py, appkit/
 
 docs/                  the design docs, the API, the limits, the theory report
 
@@ -236,28 +241,20 @@ and [limitations](docs/LIMITATION.md).
 
 ---
 
-## Status — and it now includes a REAL pretrained LLM
+## Real-model experiment status
 
-GPT-2 (124M parameters, the real 50,257-token BPE tokenizer), run on CPU with the memory layer attached:
+The E14 GPT-2 experiment script, forward implementation, tokenizer, and
+archived `results/e14_real_gpt2.json` are included. The checkpoint is not;
+rerun E14 to independently reproduce the recorded measurements. See
+[the reproduction guide](docs/REPRODUCING.md) for download and run commands.
 
-| 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.
+E15 adds a from-scratch Qwen2.5-0.5B forward implementation and app-kit
+integration. Its archived run records bit-identical attachment, exact recall
+of a planted fact 1,411 tokens back, and a best gated loss improvement of
+`0.041` nats; the kNN-LM baseline improves loss by `0.274` nats, so this run
+does not show the gate outperforming that baseline. The checkpoint is not
+bundled. Reproduction requires the optional GPU dependencies and local model
+weights; see [E15 instructions](docs/REPRODUCING.md#qwen2-scale-experiment-e15).
 
 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.
 
@@ -277,7 +274,9 @@ 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 core research experiments use small CPU models and character-level or
+512-token subword corpora. E14 and E15 are separate pretrained-model
+experiments; their checkpoints are not included.
 
 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.
@@ -333,7 +332,7 @@ A research memory layer with an operator-level stability bound, a bounded in-mem
 ## 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.
+topological structure. The author describes it as a school project and
+credits AI assistance for implementation and repository organization. The
+research decisions, measurements, and limitations are documented alongside
+the code so the work can be evaluated and reproduced.

{fluidlayer-2.0.0 → fluidlayer-2.1.0}/docs/BLOG.md

@@ -85,10 +85,9 @@ suite.
 λ₂ does not predict quality (pearson 0.20). The certificate is true
 about the operator; it says nothing about the task. The claim was
 weakened, not the data massaged.
-A transformer beats the fluid at every scale I could train
-(2.6331 vs 2.7397 nats). The fluid only wins against fixed-receptive-field
-aggregators (97.3 % vs 65.6 % / 71.0 %) — and it loses to full attention,
-which is the honest summary of the entire architecture.
+Archived results record a transformer beating the fluid (2.6331 vs 2.7397
+nats) and a 97.3 % mechanism result. The historical source scripts are not
+included, so see N4 in `docs/NEGATIVE-RESULTS.md` for the reproduction caveat.
 Grafted onto a frozen model, my own diffusion tier made the model
 worse — +0.81 nats (ppl 13.3 -> 29.9) on real English. The cause is
 structural: the persistent state sits outside the autodiff graph, so the

{fluidlayer-2.0.0 → fluidlayer-2.1.0}/docs/CHANGELOG.md

@@ -6,6 +6,15 @@ uses [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-11-03
+
+### Added
+
+- Added the optional PyTorch Qwen2 adapter, E15 scale-model experiment,
+  archived measurements, and a runnable app-kit example.
+- Categorized the new project-process, app-kit, experiment, and result files
+  into `docs/`, `examples/`, `experiments/`, and `results/`.
+
 ### Changed
 
 - Improved the Markdown documentation structure, added a documentation

{fluidlayer-2.0.0 → fluidlayer-2.1.0}/docs/COMPARISON.md

@@ -205,7 +205,7 @@ what makes per-user persistent memory economically possible at all.
 | ---|---|---|---|---|---|---|---|---|---|
 | exact needle at a position|✅|✅ recent|✅|❌|❌|❌|❌|✅|✅ pinned / L3|
 | exact  specific  fact|✅|✅ recent|✅|❌|❌|❌|❌|✅|✅ pinned (20 B)|
-| global gist / aggregate|✅|❌|✅|✅|✅|✅|❌|❌|✅ 97.3 % meas.|
+| global gist / aggregate|✅|❌|✅|✅|✅|✅|❌|❌|✅ archived 97.3 % result (`results/mechanism.json`)|
 | positional recall ( "3rd paragraph ")|✅|✅|✅|✅|❌|❌|❌|❌|❌|
 | infinite stream / never re-encode|❌|✅|❌|❌|✅|✅|n/a|✅|✅|
 | no  "lost in the middle "|❌|❌|❌|❌|~ (no positions)|~|n/a|~|✅ (no positional decay)|
@@ -266,12 +266,12 @@ the measured semantic/local-geometric policy performed better.
 KV bytes/token, KV @ctx, sessions that fit in VRAM, prefill FLOPs, crossover point
 fluid read cost 16 KB = 0.009 µs; fluid compute = 384 flops/token/layer
 our `selftest.py` → 50/50
-mechanism test: fluid 97.3 % sign acc vs local R=4 65.6 %, R=8 71.0 %
-LM A/B: transformer wins — 2.6331 vs 2.7397 final val (fewer params on our side)
+mechanism test: archived result records 97.3 % sign accuracy; original source unavailable
+LM A/B: archived result records transformer 2.6331 vs FluidLayer 2.7397; original training source unavailable
 param-matched FLOPs: 1.10× cheaper @8K → 2.54× @128K
 ⚠️ PROJECTED — needs E1/E5 to become fact
 that the 16 KB fluid carries long-range information at usable quality
-that a real LLM actually routes to the fluid (the 97.3 % was a synthetic task)
+that a real LLM actually routes to the fluid (the archived 97.3 % synthetic-task result does not establish real-model routing)
 that topology picks the right facts to freeze
 that pinned facts survive a real model's distribution shift
 Every table above is a CONDITIONAL: "IF the fluid is usable, THEN this".

{fluidlayer-2.0.0 → fluidlayer-2.1.0}/docs/DESIGN_pinned_memory.md

@@ -45,10 +45,9 @@ This is the entire design in one move:
 FluidLayer stops being a memory. It becomes an index.
 The memory moves to a write-once register; the fluid answers where, and
 the register answers what.
-And the reason this is not a retreat: the 97.3 % mechanism result was always a
-routing result. In the mechanism test the fluid predicted the right global
-aggregate to 97.3 % sign accuracy. It was already an excellent addresser.
-We just gave it an exact value to point at.
+The archived `results/mechanism.json` records a 97.3 % global-aggregation
+result. Its original experiment source is not present, so the historical run
+cannot be independently regenerated (see N4 in `docs/NEGATIVE-RESULTS.md`).
 
 ## 1. The impossibility, stated precisely
 
@@ -89,7 +88,7 @@ keep.
          └──────────────────────────────────────────────────┘
 Slot layout (20 B, as implemented):`key uint64 | val int32 | sig uint32 | anchor uint16 | meta uint16`.
 The read path is three clean steps, each with a guarantee:
-query h  ──▶  L2 routes h → anchor a   (approx: 97.3 % measured)
+query h  ──▶  L2 routes h → anchor a   (approximate; archived score in results/mechanism.json)
               anchor a → slot id s       (exact: 1 byte)
               L1[s] = (key, token_id)    (exact: 4 bytes)
               verify key matches h's context hash   (fail-loud)
@@ -174,12 +173,12 @@ This is a testable prediction, and it is falsifiable.
 Which tokens to freeze? The longest bars = the structural landmarks =
 the tokens that carry the document's skeleton. Freeze those and you get
 exact extraction of the load-bearing facts, not random trivia.
-Why the fluid wins global aggregation (explains the 97.3 %). The
+The theory suggests why diffusion can carry global aggregation: the
 harmonic branch of `L` (its kernel) is the globally dominant H₀ mode —
-and the global mean is the longest bar. The fluid preserves the kernel
-component exactly; that is precisely why it beat local aggregators
-(65.6 % / 71.0 %) on the global-mean task and lost on position-sensitive
-tasks. The v0.1 theory report and the mechanism experiment now have one
+and the global mean is the longest bar. The archived mechanism output records
+a 97.3 % score, beating local aggregators (65.6 % / 71.0 %); its original
+source is unavailable, so the run cannot be independently regenerated. The
+v0.1 theory report and the mechanism experiment now have one
 unified explanation. That is a real, publishable narrative.
 
 ## 5. Budget: the 3-D trade-off
@@ -366,8 +365,8 @@ P4 needs one GPU for a few hours.
 
 Attention remembers by position. We remember by geometry. But geometry alone
 smears: diffusion destroys exactness by construction. So we split the
-memory. A 16 KB sheaf routes — 97.3 % accurate at picking the right
-landmark — and an append-only frozen register stores the exact token id
+memory. A 16 KB sheaf routes to an approximate landmark (the archived
+mechanism result records 97.3 % sign accuracy) — and an append-only frozen register stores the exact token id
 at 14 bytes per fact, 196,234× cheaper than a KV cache. Topology decides
 which landmarks get exact storage, using the document's own persistence
 diagram, at zero per-token cost. The model can promote a fact or recall one

{fluidlayer-2.0.0 → fluidlayer-2.1.0}/docs/FRAMEWORK.md

@@ -3,6 +3,10 @@
 > **Historical design note:** this is not a current implementation contract.
 > For current behavior and limitations, see [the API reference](API.md) and
 > [limitations](LIMITATION.md).
+> Archived LM-comparison and mechanism-test JSON outputs are included under
+> `results/`, but their original experiment source files are unavailable.
+> Treat the numbers as historical snapshots, not independently rerunnable
+> measurements.
 
 A topological fluid architecture for sequence models: replace the
 transformer's quadratic attention with a cellular-sheaf diffusion whose
@@ -345,8 +349,8 @@ fluidlayer/
   losses.py      CE (+ tensor variant), sheaf energy, band decorrelation
   optim.py       Adam (decoupled WD, clipping, cosine schedule)
   data.py        Gutenberg corpus + char tokenizer + synthetic fallback
-selftest.py      15 numerical checks of the mathematics   -> results/selftest.json
-train.py         LM A/B + global-aggregation demo             -> results/train_results.json
+selftest.py      historical numerical checks
+train.py         historical LM A/B + global-aggregation demo (source unavailable; see archived results/)
 
 ### Run it
 

{fluidlayer-2.0.0 → fluidlayer-2.1.0}/docs/GETTING_STARTED.md

@@ -106,6 +106,23 @@ integration must handle the model's positional embeddings, attention masks,
 device placement, session boundaries, and task-specific gain calibration.
 Call `branch.reset()` when starting a new independent session.
 
+## Run the GPT-2/Qwen2 app kit
+
+The repository includes a standalone app kit that loads a local GPT-2 or
+Qwen2 checkpoint and demonstrates attachment and recall:
+
+```bash
+python -m pip install "fluidlayer[gpu]"
+hf download Qwen/Qwen2.5-0.5B --local-dir models/qwen05b
+python examples/appkit/attach_layer.py --model models/qwen05b
+```
+
+The Qwen2 forward implementation is in the published `fluidlayer` package;
+the Qwen tokenizer is provided by the optional Transformers dependency.
+Model weights are not bundled. This app kit is a research example, not a
+production serving wrapper. See [the E15 result](../results/e15_scale_model.json)
+and [reproduction guide](REPRODUCING.md#qwen2-scale-experiment-e15).
+
 ## Memory behavior and safety
 
 The attachable store is bounded. Its reported 20-byte slot cost is a logical

{fluidlayer-2.0.0 → fluidlayer-2.1.0}/docs/GRAFT.md

@@ -516,56 +516,21 @@ size is decisive, and the honest reading is sharper than "we beat kNN-LM":
 
 ---
 
-## ON A REAL PRETRAINED LLM (E14) — GPT-2, 124M, the real tokenizer
+## ON A REAL PRETRAINED LLM (E14) — archived result
 
-Everything above was measured on a 131,392-parameter model trained in this
-repository.  **This is the same experiment on a genuine pretrained
-checkpoint** — GPT-2 (124M parameters, the real GPT-2 BPE tokenizer with
-50,257 tokens), run on CPU with a from-scratch forward pass
-(`fluidlayer/gpt2_model.py`, verified by generation).
+The E14 script, GPT-2 forward implementation, tokenizer, and archived
+`results/e14_real_gpt2.json` are present. The checkpoint must be downloaded
+separately, so rerun E14 to reproduce the recorded measurements; see N11 in
+[`NEGATIVE-RESULTS.md`](NEGATIVE-RESULTS.md).
 
-### The three measurements
+To reproduce the run, install the optional dependencies, download GPT-2,
+then run the experiment on the committed corpus:
 
-| | the result |
-|---|---|
-| **E14a -- attach safety** | **bit-identical** (max abs diff `0.000e+00`) on the real model too |
-| **E14c -- the capability** | a fact planted **2,947 tokens** before the query: the base GPT-2 predicts 464, **the layer predicts the fact** |
-| **E14b -- the perplexity** | the base GPT-2: 4.0289 (ppl 56.20); the layer at its best gain: **4.0019 (ppl 54.70, −0.027 nats)** |
-
-### And the kNN-LM baseline, on the real model
-
-| | val loss | ppl | Δ | token accuracy |
-|---|---|---|---|---|
-| the base GPT-2 | 4.0289 | 56.20 | – | 0.3073 |
-| **kNN-LM, λ=0.9** | **3.8030** | **44.84** | **−0.2259** | 0.3029 |
-| kNN-LM, λ=0.95 | 3.8052 | 44.94 | −0.2237 | 0.3091 |
-| the layer (gated), gain 0.5 | 4.0019 | 54.70 | −0.0271 | 0.3104 |
-| the layer (gated), gain 2 | 4.1965 | 66.46 | +0.1676 | 0.2982 |
-
-> **The result that changes the claim.**  On the *tiny* model the gate beat
-> the kNN-LM interpolation by **7.4×**.  On the **real** model the
-> interpolation wins by **8×**.  The reason is structural, not a bug: the
-> interpolation is **bounded** — it can only shift probability mass by
-> (1−λ), so a wrong retrieval can never take over — whereas the gate
-> *can* take over, and on a strong model the base's own guess is usually
-> better than the datastore's answer.
->
-> **The gate wins where the base model is weak; the interpolation wins
-> where the base model is strong.**  The capability (E14c) works on both.
-
-### One thing that had to be fixed to make it work on a real model
-
-The gate was first formulated in probability space, `u = 1 − max p`.  On
-GPT-2 that needed a gain of 50+ and it wrecked the perplexity: GPT-2's
-logits span ±20, while the tiny model's span ±2, so the same "gain" meant
-something completely different.  **The gate is now in logit space**,
-`u = −log p_max` (how many nats the model is from being sure), which is
-**scale-free**: the same gain works on both models.
-
-→ `experiments/e14_real_gpt2.py`, `results/e14_real_gpt2.json`
-(measured with torch 2.4.1+cpu; `python tools/download_gpt2.py --out models/gpt2`
-fetches the checkpoint, and the forward pass + tokenizer are in this
-repository — no `transformers` needed)
+```bash
+python -m pip install -e ".[gpu]"
+python tools/download_gpt2.py --out models/gpt2
+python experiments/e14_real_gpt2.py --corpus corpus.txt
+```
 
 ---
 

{fluidlayer-2.0.0 → fluidlayer-2.1.0}/docs/MILESTONES.md

@@ -157,26 +157,19 @@ is the contribution under a hard memory budget** — which is a narrower
 claim than the project started with, and a defensible one.
 → `experiments/e13_knn_baseline.py`, `results/e13_knn.json`
 
-## 16. A pretrained LLM
+## 16. A pretrained LLM — unverified
 
-The network came up, torch installed, and **GPT-2 (124M, the real 50,257
-token BPE) ran with the layer attached**: the attach is **bit-identical**,
-and a fact planted **2,947 tokens** before the query is recalled (the base
-predicts 464, the layer predicts the fact).  The checkpoint, the forward
-pass and the tokenizer are all in this repository — no `transformers`
-dependency, and the generation is verified coherent.
-
-The honest caveat it forced: **the gate's advantage over the kNN-LM
-interpolation reverses on a strong model** (the tiny model: the gate won by
-7.4×; GPT-2: the interpolation wins by 8×).  The gate wins where the base
-model is weak.  The capability works on both.
-→ `experiments/e14_real_gpt2.py`, `results/e14_real_gpt2.json`
+The E14 script, GPT-2 forward/tokenizer implementation, and archived
+`results/e14_real_gpt2.json` are present. The checkpoint is not; rerun E14
+to independently reproduce the recorded measurements.
+→ `experiments/e14_real_gpt2.py`; see [reproduction instructions](REPRODUCING.md)
 
 ## 17. A repository a stranger can run in one minute
 
-Unzip → `python selftest.py` → **50/50**.  `pip install .` → the public API
-imports from an installed wheel.  Every result in `results/` regenerates
-with `python experiments/run_all.py --full`.
+Fresh clone → `python selftest.py` → **50/50**.  `pip install .` → the public API
+imports from an installed wheel. Reproducible experiments can be rerun with
+`python experiments/run_all.py --full`; archived N4 results are preserved,
+though their historical source script is unavailable.
 → `scripts/check_artifacts.sh` (the one-command audit)
 
 ## 18. The credibility milestone