morph-hrr v0.1.0: compositional HRR morpheme tokenizer

.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

.pytest_cache/v/cache/lastfailed

@@ -0,0 +1 @@
+{}

.pytest_cache/v/cache/nodeids

@@ -0,0 +1,29 @@
+[
+  "tests/test_compositionality.py::test_oov_root_family",
+  "tests/test_compositionality.py::test_prefix_recovery_beats_control",
+  "tests/test_compositionality.py::test_roles_are_near_orthogonal",
+  "tests/test_compositionality.py::test_shared_root_clusters",
+  "tests/test_compositionality.py::test_shared_suffix_clusters",
+  "tests/test_hrr_math.py::test_bind_unbind_supports_batch",
+  "tests/test_hrr_math.py::test_bundle_recovery_beats_distractors",
+  "tests/test_hrr_math.py::test_determinism_same_seed",
+  "tests/test_hrr_math.py::test_empty_bundle_raises",
+  "tests/test_hrr_math.py::test_normalize_yields_unit_norm",
+  "tests/test_hrr_math.py::test_unitary_bind_unbind_recovers_value",
+  "tests/test_hrr_math.py::test_unitary_keys_have_unit_fft_magnitude",
+  "tests/test_hrr_math.py::test_update_context_stays_normalized_and_finite",
+  "tests/test_segmentation.py::test_empty",
+  "tests/test_segmentation.py::test_non_alpha_passthrough",
+  "tests/test_segmentation.py::test_segment[KING-expected10]",
+  "tests/test_segmentation.py::test_segment[a-expected11]",
+  "tests/test_segmentation.py::test_segment[disconnected-expected8]",
+  "tests/test_segmentation.py::test_segment[happiness-expected4]",
+  "tests/test_segmentation.py::test_segment[happy-expected9]",
+  "tests/test_segmentation.py::test_segment[kingdom-expected5]",
+  "tests/test_segmentation.py::test_segment[preorder-expected7]",
+  "tests/test_segmentation.py::test_segment[running-expected2]",
+  "tests/test_segmentation.py::test_segment[unhappy-expected0]",
+  "tests/test_segmentation.py::test_segment[unkind-expected1]",
+  "tests/test_segmentation.py::test_segment[walking-expected3]",
+  "tests/test_segmentation.py::test_segment[walks-expected6]"
+]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BB Claude
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,99 @@
+# morph-hrr
+
+A **compositional morpheme tokenizer built on Holographic Reduced Representations (HRR)**, for Apple MLX.
+
+Each word becomes one fixed-width dense vector by *binding* its morphemes (prefix ⊗ root ⊗ suffix) into a single "holistic" superposition. Because the binding is circular convolution with **unitary role vectors**, you can algebraically pull a morpheme back out: `unbind(word_vec, prefix_role)` recovers the prefix. Words that share morphology land near each other in vector space, and an out-of-vocabulary word built from its pieces still neighbors its root family.
+
+## What this is — and isn't
+
+**It is:** an **input representation / embedding layer** for HRR-native or experimental models. It emits dense vectors, one per word, and exposes the HRR algebra (`bind`, `unbind`, `bundle`, `make_unitary`) behind them.
+
+**It is not:** a HuggingFace text↔ID tokenizer. It does not produce token IDs, has no vocabulary, and will not drop into `transformers`. Think of it as an alternative to a learned embedding table — one whose vectors are *compositional by construction* rather than arbitrary.
+
+**It is not:** a way to make a pretrained Qwen/Gemma smaller or faster. HRR input is a different representation than what pretrained weights expect; you cannot swap it into an existing model without retraining from scratch. (See *Scope & honesty* below.)
+
+## Install
+
+```bash
+pip install morph-hrr        # Apple Silicon (mlx is the only dependency)
+```
+
+Development:
+
+```bash
+git clone <repo> && cd morph-hrr
+pip install -e ".[test]"
+pytest -q
+```
+
+## Quickstart
+
+```python
+from morph_hrr import MorphemeTokenizer, unbind, cosine_similarity
+
+tok = MorphemeTokenizer(dim=2048)        # deterministic given seed
+
+# A word is one fixed-width vector, composed from its morphemes by role.
+v = tok.word_vector("unhappy")           # mx.array, shape (2048,)
+print(tok.segment("unhappy"))            # ('un', 'happy', '')
+
+# Composition is algebraic: recover the prefix filler by unbinding its role.
+recovered = unbind(v, tok.prefix_role)
+print(cosine_similarity(recovered, tok.bytes_vector("un")))   # ~0.6 (vs ~0 control)
+
+# Shared morphology => shared neighborhood.
+print(cosine_similarity(tok.word_vector("unhappy"),
+                        tok.word_vector("happy")))            # > 0.2 (vs ~0 unrelated)
+
+# Encode a sentence: one float16 vector per word.
+mat = tok.encode("the quick brown fox")   # mx.array, shape (4, 2048), float16
+```
+
+## The math (one paragraph)
+
+`bind(a, b)` is circular convolution, computed in the Fourier domain as `real(IFFT(FFT(a) * FFT(b)))`. `unbind(bind(a,b), b)` is the convolution inverse, `real(IFFT(FFT(bound) * conj(FFT(b))))`. A **unitary** vector has all FFT magnitudes equal to 1, so binding with it is a perfect, lossless rotation — unbinding recovers the original to >0.99 cosine. A word vector bundles three role⊗filler pairs — `prefix_role ⊗ bytes(prefix)`, `root_role ⊗ bytes(root)`, `suffix_role ⊗ bytes(suffix)` — into one normalized superposition; unbinding a role pulls its filler back out of the superposition (the other two act as noise, which is why longer dims recover more cleanly).
+
+## Compositionality demo (regression-tested, dim=2048)
+
+| Property | HRR cosine | Random control | Test |
+|---|---|---|---|
+| Prefix recovery (`unbind(unhappy, prefix_role)` ≈ `bytes("un")`) | > 0.50 | ≈ 0 | `test_prefix_recovery_beats_control` |
+| Shared-root clustering (`unhappy` ~ `happy`) | > 0.20 | ≈ 0 | `test_shared_root_clusters` |
+| Shared-suffix clustering (`running` ~ `walking`) | > 0.15 | ≈ 0 | `test_shared_suffix_clusters` |
+| OOV root family (`unbind(unkind, root_role)` ≈ `bytes("kind")`) | > 0.50 | ≈ 0 | `test_oov_root_family` |
+| Role vectors near-orthogonal | < 0.10 | — | `test_roles_are_near_orthogonal` |
+
+Each HRR measurement is paired against a random-vector control of the same dimension, asserting the structured signal is meaningfully stronger than noise.
+
+## Public API
+
+| Name | What |
+|---|---|
+| `MorphemeTokenizer(dim=2048, seed=0)` | Map text → HRR morpheme vectors |
+| `.segment(word)` | `(prefix, root, suffix)` |
+| `.word_vector(word)` / `.bytes_vector(text)` | Holistic / byte-fold word vector |
+| `.encode(text)` / `.iter_vectors(text)` | Stacked `(n, dim)` float16 / lazy yield |
+| `.prefix_role` / `.root_role` / `.suffix_role` | Exposed unitary role vectors (for `unbind`) |
+| `bind`, `unbind`, `bundle`, `normalize`, `make_unitary`, `cosine_similarity`, `update_context` | HRR primitives |
+| `segment`, `PREFIXES`, `SUFFIXES` | Standalone morphological segmentation |
+
+`HolographicMorphemeTokenizer` is kept as a backwards-compatible alias for `MorphemeTokenizer`.
+
+## Segmentation: deliberately simple
+
+`morphemes.segment` is dependency-free, longest-match affix stripping over curated prefix/suffix lists, with a minimum-root guard. It is **imperfect by design**: it does not undo consonant doubling (`running → runn + ing`, not `run + ing`) and cannot tell a real root from a suffixable tail (`preorder → pre + ord + er`). No dictionary, no learned model, no `nltk`. This keeps the package lightweight; better segmentation is future work and is orthogonal to the HRR representation itself.
+
+## Scope & honesty
+
+- **mlx-only.** Apple Silicon target audience; a numpy/JAX backend is a documented future option, not this release.
+- **Representation, not a drop-in tokenizer.** No token IDs, no HF integration.
+- **Can't retrofit pretrained models.** Swapping HRR input into a real model throws away its pretrained weights — you must train from scratch. On consumer hardware (e.g. 16 GB) that means small research-scale models, not deployable ones. The value of this package is the *compositional input representation* and the HRR algebra, demonstrated on small models.
+- v0.1 ships the tokenizer + primitives + tests. A demo Space, a trained reference model, and a portable backend are future work.
+
+## License
+
+MIT. See `LICENSE`.
+
+## Cite / priority
+
+If you build on this representation in published work, please cite this repository. The compositional HRR morpheme representation (role⊗filler binding of prefix/root/suffix via circular convolution, with unitary roles enabling algebraic morpheme manipulation) is, to our knowledge, novel as a tokenization scheme; we'd appreciate attribution.

pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "morph-hrr"
+version = "0.1.0"
+description = "Compositional HRR morpheme tokenizer/embeddings: circular-convolution prefix (x) root (x) suffix, for Apple MLX."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "BB Claude" }]
+keywords = ["hrr", "vsa", "hyperdimensional", "tokenizer", "morphology", "mlx", "embeddings", "circular-convolution"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+]
+dependencies = ["mlx"]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.urls]
+Repository = "https://huggingface.co/<user>/morph-hrr"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/morph_hrr"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

src/morph_hrr/__init__.py

@@ -0,0 +1,37 @@
+"""morph-hrr: compositional HRR morpheme tokenizer for Apple MLX.
+
+A word becomes one fixed-width vector via circular-convolution composition of its
+morphemes (prefix (x) root (x) suffix), giving algebraically manipulable,
+out-of-vocabulary-friendly token representations.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .hrr import (
+    bind,
+    bundle,
+    cosine_similarity,
+    make_unitary,
+    normalize,
+    unbind,
+    update_context,
+)
+from .morphemes import PREFIXES, SUFFIXES, segment
+from .tokenizer import HolographicMorphemeTokenizer, MorphemeTokenizer
+
+__all__ = [
+    "MorphemeTokenizer",
+    "HolographicMorphemeTokenizer",
+    "segment",
+    "PREFIXES",
+    "SUFFIXES",
+    "bind",
+    "unbind",
+    "bundle",
+    "normalize",
+    "make_unitary",
+    "cosine_similarity",
+    "update_context",
+    "__version__",
+]

src/morph_hrr/hrr.py

@@ -0,0 +1,64 @@
+"""Holographic Reduced Representation (HRR) primitives on Apple MLX.
+
+Binding/unbinding are circular (de)convolution in the FFT domain (Plate, 1995).
+These are the building blocks the morpheme tokenizer uses to compose
+``prefix (x) root (x) suffix`` into a single fixed-width "holistic" token vector.
+"""
+from __future__ import annotations
+
+import mlx.core as mx
+import numpy as np
+
+
+def normalize(x: mx.array, eps: float = 1e-6) -> mx.array:
+    """L2-normalize along the last axis; upcast to float32 for stable math."""
+    x = x.astype(mx.float32)
+    return x / mx.sqrt(mx.sum(x * x, axis=-1, keepdims=True) + eps)
+
+
+def _bind(a: mx.array, b: mx.array) -> mx.array:
+    """Circular convolution: real(IFFT(FFT(a) * FFT(b)))."""
+    return mx.real(mx.fft.ifft(mx.fft.fft(a.astype(mx.float32)) * mx.fft.fft(b.astype(mx.float32))))
+
+
+def _unbind(bound: mx.array, key: mx.array) -> mx.array:
+    """Circular correlation (approx inverse of bind): real(IFFT(FFT(bound) * conj(FFT(key))))."""
+    return mx.real(
+        mx.fft.ifft(mx.fft.fft(bound.astype(mx.float32)) * mx.conj(mx.fft.fft(key.astype(mx.float32))))
+    )
+
+
+# Compiled hot paths.
+bind = mx.compile(_bind)
+unbind = mx.compile(_unbind)
+
+
+def bundle(*vectors: mx.array) -> mx.array:
+    """Superpose vectors by normalized sum (the VSA "add")."""
+    if not vectors:
+        raise ValueError("bundle requires at least one vector")
+    return normalize(sum(v.astype(mx.float32) for v in vectors))
+
+
+def cosine_similarity(a: mx.array, b: mx.array) -> mx.array:
+    """Cosine similarity along the last axis (vectors are normalized first)."""
+    return mx.sum(normalize(a) * normalize(b), axis=-1)
+
+
+def make_unitary(dim: int, seed: int = 0) -> mx.array:
+    """Deterministic unitary vector: its FFT has all-ones magnitude, so binding with
+    it is exactly invertible (unbind perfectly recovers the bound value)."""
+    rng = np.random.default_rng(seed)
+    spectrum = np.ones(dim, dtype=np.complex64)
+    half = dim // 2
+    phases = rng.uniform(0, 2 * np.pi, max(0, half - 1))
+    spectrum[1:half] = np.exp(1j * phases)
+    spectrum[half + 1 :] = np.conj(spectrum[1:half][::-1])
+    if dim % 2 == 0:
+        spectrum[half] = 1.0
+    return mx.array(np.fft.ifft(spectrum).real.astype(np.float32))
+
+
+def update_context(context: mx.array, token: mx.array, position_key: mx.array) -> mx.array:
+    """Incrementally fold a token into a running context: normalize(context + token (x) pos)."""
+    return normalize(context.astype(mx.float32) + bind(token, position_key))

src/morph_hrr/morphemes.py

@@ -0,0 +1,64 @@
+"""Dependency-free English morphological segmentation.
+
+Splits a word into ``(prefix, root, suffix)`` using curated affix lists with
+longest-match and minimum-root guards. Deliberately simple and predictable:
+no dictionary, no learned model, no external deps. Imperfect (it won't undo
+consonant doubling like ``running -> run``) — documented as future work — but it
+handles the common derivational/inflectional cases the tokenizer relies on.
+"""
+from __future__ import annotations
+
+# Conservative, high-precision derivational prefixes (min root kept >= MIN_ROOT).
+PREFIXES: tuple[str, ...] = (
+    "anti", "auto", "circum", "contra", "counter", "dis", "extra", "fore",
+    "hyper", "hypo", "in", "im", "il", "ir", "inter", "intra", "mal", "mid",
+    "mis", "multi", "non", "out", "over", "poly", "post", "pre", "proto",
+    "pseudo", "re", "retro", "semi", "sub", "super", "supra", "sur", "trans",
+    "tri", "ultra", "un", "under",
+)
+
+# Inflectional + common derivational suffixes, tried longest-first.
+SUFFIXES: tuple[str, ...] = (
+    # 5+ chars
+    "ation", "ation", "ically", "iosity", "itious", "aceous", "acious",
+    "ality", "ative", "ator", "fully", "ially", "ables", "ibles", "iness",
+    # 4 chars
+    "able", "ably", "ance", "ence", "ency", "hood", "ible", "ical", "iest",
+    "isms", "ists", "ment", "ness", "ship", "tion", "wise",
+    # 3 chars
+    "acy", "age", "al", "ant", "ate", "dom", "ees", "ers", "est", "ful",
+    "ial", "ies", "ily", "ing", "ion", "ish", "ism", "ist", "ity", "ive",
+    "ize", "ity", "less", "ous", "ity",
+    # 2 chars
+    "al", "ed", "en", "er", "es", "ic", "ly", "or", "ty",
+    # 1 char (high-precision only)
+    "s",
+)
+
+# Keep roots at least this long after affix removal (avoids eating short words).
+MIN_ROOT = 3
+
+_SUFFIXES_BY_LEN = tuple(sorted({s for s in SUFFIXES if s}, key=len, reverse=True))
+
+
+def segment(word: str) -> tuple[str, str, str]:
+    """Return ``(prefix, root, suffix)`` for ``word``; affixes are "" when absent."""
+    w = (word or "").strip().lower()
+    if not w.isalpha():
+        return ("", w, "")
+
+    prefix = ""
+    for p in PREFIXES:
+        if w.startswith(p) and len(w) - len(p) >= MIN_ROOT:
+            prefix = p
+            break
+    root = w[len(prefix):]
+
+    suffix = ""
+    for s in _SUFFIXES_BY_LEN:
+        if root.endswith(s) and len(root) - len(s) >= MIN_ROOT:
+            suffix = s
+            root = root[: len(root) - len(s)]
+            break
+
+    return (prefix, root, suffix)

src/morph_hrr/tokenizer.py

@@ -0,0 +1,97 @@
+"""Compositional HRR morpheme tokenizer.
+
+Each word is represented as a single fixed-width "holistic" vector:
+
+    word_vec(word) = bundle(
+        prefix_role (x) bytes(prefix),
+        root_role   (x) bytes(root),
+        suffix_role (x) bytes(suffix),
+    )
+
+where ``(x)`` is circular convolution (``hrr.bind``) and ``bundle`` is normalized
+superposition. Because the roles are unitary, ``unbind(word_vec, role)`` recovers
+that role's filler — enabling algebraic morpheme manipulation (strip a prefix,
+swap a suffix, build a vector for an out-of-vocabulary word from its pieces).
+
+NOTE: this is an input **representation / embedding**, not a HuggingFace
+text<->ID tokenizer. It emits dense vectors (one per word), intended to feed
+HRR-native or experimental models.
+"""
+from __future__ import annotations
+
+import re
+
+import mlx.core as mx
+import numpy as np
+
+from .hrr import bind, bundle, make_unitary, normalize
+from .morphemes import segment as _segment
+
+_WORD_RE = re.compile(r"[A-Za-z]+|\S")
+
+
+class MorphemeTokenizer:
+    """Map text -> HRR morpheme vectors of width ``dim`` (deterministic given ``seed``)."""
+
+    def __init__(self, dim: int = 2048, seed: int = 0):
+        self.dim = dim
+        self.seed = seed
+        # Fixed random base vectors for each byte value; the "filler" alphabet.
+        rng = np.random.default_rng(seed)
+        byte_vectors = rng.normal(size=(256, dim)).astype(np.float32)
+        self.byte_vectors = normalize(mx.array(byte_vectors))
+        # Unitary role vectors for prefix / root / suffix slots.
+        self.prefix_role = make_unitary(dim, seed=seed + 1_001)
+        self.root_role = make_unitary(dim, seed=seed + 1_002)
+        self.suffix_role = make_unitary(dim, seed=seed + 1_003)
+
+    # -- morphemes ---------------------------------------------------------
+
+    def segment(self, word: str) -> tuple[str, str, str]:
+        """Return ``(prefix, root, suffix)`` for ``word``."""
+        return _segment(word)
+
+    def bytes_vector(self, text: str) -> mx.array:
+        """Fixed vector for a string: normalized fold-bind of its byte vectors."""
+        if not text:
+            return mx.zeros((self.dim,), dtype=mx.float32)
+        acc = self.byte_vectors[ord(text[0]) % 256]
+        for ch in text[1:]:
+            acc = bind(acc, self.byte_vectors[ord(ch) % 256])
+        return normalize(acc)
+
+    # -- composition -------------------------------------------------------
+
+    def word_vector(self, word: str) -> mx.array:
+        """Holistic HRR vector for ``word`` (composes its morphemes by role)."""
+        prefix, root, suffix = _segment(word)
+        pieces: list[mx.array] = []
+        if prefix:
+            pieces.append(bind(self.prefix_role, self.bytes_vector(prefix)))
+        if root:
+            pieces.append(bind(self.root_role, self.bytes_vector(root)))
+        if suffix:
+            pieces.append(bind(self.suffix_role, self.bytes_vector(suffix)))
+        if not pieces:
+            return self.bytes_vector(word)
+        return bundle(*pieces)
+
+    # -- text -> vectors ---------------------------------------------------
+
+    def iter_vectors(self, text: str):
+        """Yield one ``float16`` word vector per token in ``text`` (word or punct)."""
+        for word in _WORD_RE.findall(text):
+            vector = self.word_vector(word).astype(mx.float16)
+            mx.eval(vector)
+            yield mx.stop_gradient(vector)
+
+    def encode(self, text: str) -> mx.array:
+        """Stacked word vectors, shape ``(n_words, dim)`` in ``float16``."""
+        vectors = list(self.iter_vectors(text))
+        if not vectors:
+            return mx.zeros((0, self.dim), dtype=mx.float16)
+        return mx.stack(vectors)
+
+
+# Backwards-compatible alias.
+HolographicMorphemeTokenizer = MorphemeTokenizer

tests/test_compositionality.py

@@ -0,0 +1,108 @@
+"""Compositionality regression suite (ported from the Phase 1 checks).
+
+These are the headline properties that make the HRR morpheme representation
+useful. Each HRR measurement is paired against a random-vector control of the
+same dimension, asserting the HRR signal is meaningfully stronger.
+"""
+import numpy as np
+
+import mlx.core as mx
+
+from morph_hrr import MorphemeTokenizer, unbind, cosine_similarity
+
+DIM = 2048
+# A tokenizer is reused across tests; construction is cheap and deterministic.
+TOK = MorphemeTokenizer(dim=DIM, seed=0)
+
+# Random-vector control: a fresh tokenizer whose "word vectors" are i.i.d. random
+# unit vectors (no composition at all). Expected to show ~0 structure.
+
+
+def _control():
+    rng = np.random.default_rng(99)
+    return normalize(mx.array(rng.normal(size=(DIM,)).astype(np.float32)))
+
+
+def normalize(v):
+    n = mx.sqrt(mx.sum(v * v) + 1e-12)
+    return v / n
+
+
+def _rand_vec(tag: str) -> mx.array:
+    """Deterministic random unit vector keyed by tag (for the control family)."""
+    rng = np.random.default_rng(abs(hash(tag)) % (2**32))
+    return normalize(mx.array(rng.normal(size=(DIM,)).astype(np.float32)))
+
+
+# -- 1. Prefix recovery: unbind recovers the prefix filler from the holistic vec -
+
+def test_prefix_recovery_beats_control():
+    word = TOK.word_vector("unhappy")
+    recovered = unbind(word, TOK.prefix_role)
+    target = TOK.bytes_vector("un")
+    hrr_cos = float(cosine_similarity(target, recovered))
+
+    # Control: unbinding a random vector with the prefix role gives noise.
+    ctrl = unbind(_rand_vec("control-prefix"), TOK.prefix_role)
+    ctrl_cos = abs(float(cosine_similarity(target, ctrl)))
+
+    assert hrr_cos > 0.50, f"prefix recovery cosine {hrr_cos} too low"
+    assert hrr_cos > ctrl_cos + 0.40, (
+        f"HRR prefix recovery {hrr_cos} not clearly above control {ctrl_cos}"
+    )
+
+
+# -- 2. Shared-root clustering: unhappy ~ happy (same root "happy") ------------
+
+def test_shared_root_clusters():
+    unhappy = TOK.word_vector("unhappy")
+    happy = TOK.word_vector("happy")
+    hrr_cos = float(cosine_similarity(unhappy, happy))
+
+    # Control: two unrelated random words should be ~orthogonal.
+    ctrl_cos = abs(float(cosine_similarity(_rand_vec("a"), _rand_vec("b"))))
+
+    assert hrr_cos > 0.20, f"shared-root cosine {hrr_cos} too low"
+    assert hrr_cos > ctrl_cos + 0.15
+
+
+# -- 3. Shared-suffix clustering: running ~ walking (same suffix "ing") --------
+
+def test_shared_suffix_clusters():
+    running = TOK.word_vector("running")
+    walking = TOK.word_vector("walking")
+    hrr_cos = float(cosine_similarity(running, walking))
+
+    ctrl_cos = abs(float(cosine_similarity(_rand_vec("c"), _rand_vec("d"))))
+
+    assert hrr_cos > 0.15, f"shared-suffix cosine {hrr_cos} too low"
+    assert hrr_cos > ctrl_cos + 0.10
+
+
+# -- 4. OOV root family: a built-from-pieces vector still neighbors its root ---
+
+def test_oov_root_family():
+    # "unkind" is in-vocab via segmentation; its root filler is "kind".
+    unkind = TOK.word_vector("unkind")
+    kind = TOK.word_vector("kind")
+    recovered_root = unbind(unkind, TOK.root_role)
+    hrr_cos = float(cosine_similarity(TOK.bytes_vector("kind"), recovered_root))
+
+    ctrl = unbind(_rand_vec("control-root"), TOK.root_role)
+    ctrl_cos = abs(float(cosine_similarity(TOK.bytes_vector("kind"), ctrl)))
+
+    assert hrr_cos > 0.50, f"OOV root recovery cosine {hrr_cos} too low"
+    assert hrr_cos > ctrl_cos + 0.40
+
+
+# -- 5. Roles are near-orthogonal (composition uses distinct slots) -----------
+
+def test_roles_are_near_orthogonal():
+    pairs = [
+        (TOK.prefix_role, TOK.root_role),
+        (TOK.prefix_role, TOK.suffix_role),
+        (TOK.root_role, TOK.suffix_role),
+    ]
+    for a, b in pairs:
+        cos = abs(float(cosine_similarity(a, b)))
+        assert cos < 0.10, f"roles not orthogonal: cosine {cos}"

tests/test_hrr_math.py

@@ -0,0 +1,77 @@
+import mlx.core as mx
+
+from morph_hrr import (
+    bind,
+    bundle,
+    cosine_similarity,
+    make_unitary,
+    normalize,
+    unbind,
+    update_context,
+)
+
+DIM = 4096
+
+
+def _close(actual, expected, tol):
+    assert abs(float(actual) - float(expected)) <= tol, f"{actual} !~= {expected} (tol {tol})"
+
+
+def test_unitary_keys_have_unit_fft_magnitude():
+    key = make_unitary(DIM, seed=10)
+    mags = mx.abs(mx.fft.fft(key))
+    _close(mx.min(mags), 1.0, 1e-4)
+    _close(mx.max(mags), 1.0, 1e-4)
+
+
+def test_unitary_bind_unbind_recovers_value():
+    key = make_unitary(DIM, seed=11)
+    value = normalize(mx.random.normal((DIM,)))
+    recovered = unbind(bind(key, value), key)
+    assert float(cosine_similarity(value, recovered)) > 0.995
+
+
+def test_bind_unbind_supports_batch():
+    key = make_unitary(DIM, seed=12)
+    values = normalize(mx.random.normal((3, DIM)))
+    recovered = unbind(bind(key, values), key)
+    assert recovered.shape == values.shape
+    assert float(mx.min(cosine_similarity(values, recovered))) > 0.995
+
+
+def test_bundle_recovery_beats_distractors():
+    roles = [make_unitary(DIM, seed=13 + i) for i in range(3)]
+    vals = [normalize(mx.random.normal((DIM,))) for _ in range(3)]
+    memory = bundle(*(bind(r, v) for r, v in zip(roles, vals)))
+    recovered = unbind(memory, roles[1])
+    assert float(cosine_similarity(vals[1], recovered)) > 0.50
+    assert abs(float(cosine_similarity(vals[0], recovered))) < 0.10
+    assert abs(float(cosine_similarity(vals[2], recovered))) < 0.10
+
+
+def test_normalize_yields_unit_norm():
+    v = normalize(mx.random.normal((DIM,)))
+    _close(mx.sum(v * v), 1.0, 1e-4)
+
+
+def test_update_context_stays_normalized_and_finite():
+    context = mx.zeros((DIM,), dtype=mx.float32)
+    for i in range(128):
+        token = normalize(mx.random.normal((DIM,)))
+        context = update_context(context, token, make_unitary(DIM, seed=1_000 + i))
+    _close(mx.sum(context * context), 1.0, 1e-4)
+    assert bool(mx.all(mx.isfinite(context)))
+
+
+def test_empty_bundle_raises():
+    try:
+        bundle()
+    except ValueError:
+        return
+    raise AssertionError("empty bundle must raise ValueError")
+
+
+def test_determinism_same_seed():
+    a = make_unitary(DIM, seed=42)
+    b = make_unitary(DIM, seed=42)
+    assert bool(mx.allclose(a, b))

tests/test_segmentation.py

@@ -0,0 +1,34 @@
+import pytest
+
+from morph_hrr import segment
+
+cases = [
+    ("unhappy", ("un", "happy", "")),
+    ("unkind", ("un", "kind", "")),
+    ("running", ("", "runn", "ing")),      # no undoubling (documented)
+    ("walking", ("", "walk", "ing")),
+    ("happiness", ("", "happ", "iness")),   # longest suffix "iness"
+    ("kingdom", ("", "king", "dom")),
+    ("walks", ("", "walk", "s")),
+    # Rule-based longest-match can't know "order" is a root: after "pre" it
+    # strips "er" too. Documents the (deliberate) imperfectness.
+    ("preorder", ("pre", "ord", "er")),
+    ("disconnected", ("dis", "connect", "ed")),
+    ("happy", ("", "happy", "")),           # no bare-"y" suffix
+    ("KING", ("", "king", "")),             # case-insensitive
+    ("a", ("", "a", "")),                   # too short -> root only
+]
+
+
+@pytest.mark.parametrize("word,expected", cases)
+def test_segment(word, expected):
+    assert segment(word) == expected
+
+
+def test_non_alpha_passthrough():
+    p, r, s = segment("123")
+    assert r == "123" and p == "" and s == ""
+
+
+def test_empty():
+    assert segment("") == ("", "", "")