bloom-torch 1.0.0__tar.gz

bloom_torch-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bloom-torch contributors
+
+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.

bloom_torch-1.0.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: bloom-torch
+Version: 1.0.0
+Summary: Bloom-filter–accelerated clustering and set structures in PyTorch (not related to the BLOOM language model).
+Author: bloom-torch contributors
+License: MIT
+Project-URL: Homepage, https://github.com/your-org/bloom-torch
+Project-URL: Documentation, https://github.com/your-org/bloom-torch#readme
+Project-URL: Repository, https://github.com/your-org/bloom-torch
+Project-URL: Issues, https://github.com/your-org/bloom-torch/issues
+Keywords: bloom-filter,pytorch,clustering,k-means,bloom-matrix
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# bloom-torch
+
+**bloom-torch** is a small PyTorch library for **Bloom filters**, **Bloom matrices** (bitwise set encodings), and **BloomKMeans** — K-means with Bloom-based candidate pruning when the number of clusters is large.
+
+> **Note:** This package is **not** related to the [**BLOOM**](https://huggingface.co/bigscience/bloom) multilingual language model or other “BLOOM” model names in the Hugging Face ecosystem. The name refers to [**Bloom filters**](https://en.wikipedia.org/wiki/Bloom_filter) (probabilistic set membership, 1970).
+
+## Install
+
+```bash
+pip install bloom-torch
+```
+
+(After the first release; for now, from a clone: `pip install -e .`)
+
+## Requirements
+
+- Python ≥ 3.10  
+- PyTorch ≥ 2.0  
+
+## Quick start (v0.1)
+
+```python
+import torch
+from bloom_torch import BloomKMeans
+
+# X: [n, d] float32 — e.g. token or item embeddings (cluster on raw or normalised data as you prefer)
+X = torch.randn(10_000, 128, dtype=torch.float32)
+
+km = BloomKMeans(n_clusters=256, topk_cache=16, bm_fp_rate=0.01, routing_fp_rate=0.01, seed=0)
+km.fit(X, max_iters=20, use_bm_after=1, allow_bm_assign_small_k=False)
+
+# Optional: build a cluster → element Bloom matrix for routing / masking
+routing = km.build_routing_bloom(vocab_size=X.shape[0])
+```
+
+Public API in **v0.1**: `BloomHasher`, `TorchBloomMatrix`, `BloomKMeans`.  
+Routing hooks, logits processors, and LLM-specific helpers may be added in later versions or live in application code.
+
+## Relationship to research code
+
+This repository was split out from the **PyBloomFilter** research prototype (`torch_bloom` package) so the core tensor algorithms can be versioned and published independently.
+
+## License
+
+MIT — see `LICENSE`.

bloom_torch-1.0.0/README.md

@@ -0,0 +1,45 @@
+# bloom-torch
+
+**bloom-torch** is a small PyTorch library for **Bloom filters**, **Bloom matrices** (bitwise set encodings), and **BloomKMeans** — K-means with Bloom-based candidate pruning when the number of clusters is large.
+
+> **Note:** This package is **not** related to the [**BLOOM**](https://huggingface.co/bigscience/bloom) multilingual language model or other “BLOOM” model names in the Hugging Face ecosystem. The name refers to [**Bloom filters**](https://en.wikipedia.org/wiki/Bloom_filter) (probabilistic set membership, 1970).
+
+## Install
+
+```bash
+pip install bloom-torch
+```
+
+(After the first release; for now, from a clone: `pip install -e .`)
+
+## Requirements
+
+- Python ≥ 3.10  
+- PyTorch ≥ 2.0  
+
+## Quick start (v0.1)
+
+```python
+import torch
+from bloom_torch import BloomKMeans
+
+# X: [n, d] float32 — e.g. token or item embeddings (cluster on raw or normalised data as you prefer)
+X = torch.randn(10_000, 128, dtype=torch.float32)
+
+km = BloomKMeans(n_clusters=256, topk_cache=16, bm_fp_rate=0.01, routing_fp_rate=0.01, seed=0)
+km.fit(X, max_iters=20, use_bm_after=1, allow_bm_assign_small_k=False)
+
+# Optional: build a cluster → element Bloom matrix for routing / masking
+routing = km.build_routing_bloom(vocab_size=X.shape[0])
+```
+
+Public API in **v0.1**: `BloomHasher`, `TorchBloomMatrix`, `BloomKMeans`.  
+Routing hooks, logits processors, and LLM-specific helpers may be added in later versions or live in application code.
+
+## Relationship to research code
+
+This repository was split out from the **PyBloomFilter** research prototype (`torch_bloom` package) so the core tensor algorithms can be versioned and published independently.
+
+## License
+
+MIT — see `LICENSE`.

bloom_torch-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bloom-torch"
+version = "1.0.0"
+description = "Bloom-filter–accelerated clustering and set structures in PyTorch (not related to the BLOOM language model)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "bloom-torch contributors" },
+]
+keywords = [
+  "bloom-filter",
+  "pytorch",
+  "clustering",
+  "k-means",
+  "bloom-matrix",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "torch>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/your-org/bloom-torch"
+Documentation = "https://github.com/your-org/bloom-torch#readme"
+Repository = "https://github.com/your-org/bloom-torch"
+Issues = "https://github.com/your-org/bloom-torch/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+bloom_torch = ["py.typed"]

bloom_torch-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bloom_torch-1.0.0/src/bloom_torch/__init__.py

@@ -0,0 +1,25 @@
+"""
+bloom-torch — Bloom-filter–accelerated structures and clustering in PyTorch.
+
+This package implements **Bloom filters** and **Bloom matrices** (Concas-style
+multi-filters) in pure PyTorch for GPU/CPU/MPS, plus **BloomKMeans**, K-means
+with Bloom-based candidate pruning on large cluster counts.
+
+**Not related to** the `BLOOM`_ large language model or Hugging Face ``transformers``
+model namesakes; the name refers to **Bloom filters** (Burton Howard Bloom, 1970).
+
+.. _BLOOM: https://huggingface.co/bigscience/bloom
+"""
+
+from .bloom_hash import BloomHasher
+from .bloom_matrix import TorchBloomMatrix
+from .bloom_kmeans import BloomKMeans
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "BloomHasher",
+    "TorchBloomMatrix",
+    "BloomKMeans",
+    "__version__",
+]

bloom_torch-1.0.0/src/bloom_torch/bloom_hash.py

@@ -0,0 +1,145 @@
+"""
+BloomHasher — GPU-friendly universal hash family for integer labels.
+
+IMPROVEMENT: Replaces mmh3 with a polynomial hash family that runs entirely
+on PyTorch tensors (CPU / CUDA / MPS), enabling batched hashing via matmul.
+No C extension; same code path on all devices.
+
+Hash family
+-----------
+    h_i(x) = ((a_i * x + b_i) % P) % m
+
+where P = 2^31 − 1 (Mersenne prime) and (a_i, b_i) are randomly drawn
+coefficient pairs.  The Mersenne prime modulus ensures near-uniform distribution
+without costly modular reduction — % P is cheap in int64.
+
+Shapes
+------
+    hash_ids(ids)    : ids [N]     → positions [k, N]
+    hash_single(id)  : scalar id   → positions [k]
+
+Both return int64 values in [0, m).  All ops are device-agnostic.
+
+Compatibility note
+------------------
+Hash values differ from mmh3 (MurmurHash3 on string labels).  The Torch hasher
+is self-consistent: TorchBloomMatrix built and queried with the *same*
+BloomHasher instance will produce zero false negatives, matching the invariant
+of BloolMultifilters.BloomMatrix.  The two implementations are *not*
+interchangeable at the bit level.
+"""
+
+from __future__ import annotations
+
+import math
+
+import torch
+from torch import Tensor
+
+# Mersenne prime as modulus — cheap mod and good mixing
+_P: int = (1 << 31) - 1
+
+
+class BloomHasher:
+    """
+    Family of k universal hash functions h_i : int → [0, m).
+
+    Parameters
+    ----------
+    k    : number of hash functions
+    m    : output range (= number of rows in TorchBloomMatrix)
+    seed : RNG seed for reproducibility
+    """
+
+    def __init__(self, k: int, m: int, seed: int = 42) -> None:
+        self.k = k
+        self.m = m
+        self._seed = seed
+        rng = torch.Generator()
+        rng.manual_seed(seed)
+        # Odd multipliers keep the full-period property; offsets are arbitrary.
+        a = torch.randint(1, _P, (k,), generator=rng, dtype=torch.int64)
+        a = a | 1  # force odd
+        b = torch.randint(0, _P, (k,), generator=rng, dtype=torch.int64)
+        # Store as plain tensors (not nn.Parameter); moved with .to().
+        self._a: Tensor = a
+        self._b: Tensor = b
+
+    # ------------------------------------------------------------------
+    # Device management
+    # ------------------------------------------------------------------
+
+    def to(self, device: torch.device | str) -> "BloomHasher":
+        """Move coefficient tensors to *device* in-place; returns self."""
+        self._a = self._a.to(device)
+        self._b = self._b.to(device)
+        return self
+
+    @property
+    def device(self) -> torch.device:
+        return self._a.device
+
+    # ------------------------------------------------------------------
+    # Hashing — hot-path ops
+    # ------------------------------------------------------------------
+
+    def hash_ids(self, ids: Tensor) -> Tensor:
+        """
+        Compute k hash positions for a batch of integer ids.
+
+        Parameters
+        ----------
+        ids : [N] int64  (label ids, e.g. token indices or cluster indices)
+
+        Returns
+        -------
+        positions : [k, N] int64  (values in [0, m))
+        """
+        ids = ids.to(dtype=torch.int64, device=self._a.device)
+        # [k, 1] * [1, N] + [k, 1]  →  [k, N]
+        raw = self._a[:, None] * ids[None, :] + self._b[:, None]
+        return raw % _P % self.m
+
+    def hash_single(self, label_id: int) -> Tensor:
+        """
+        Compute k hash positions for a single integer label_id.
+
+        Returns
+        -------
+        positions : [k] int64  (values in [0, m))
+        """
+        x = torch.tensor(label_id, dtype=torch.int64, device=self._a.device)
+        return (self._a * x + self._b) % _P % self.m
+
+    # ------------------------------------------------------------------
+    # Optimal sizing helpers (mirror BloolMultifilters.BFAux)
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def optimal_m(n: int, p: float) -> int:
+        """
+        Optimal filter row count for *n* elements at false-positive rate *p*.
+
+        Formula: m = ceil(n · ln(1/p) / ln(2)²)
+        """
+        if n <= 0 or p <= 0 or p >= 1:
+            return 1
+        return max(round(n * -math.log(p) / (math.log(2) ** 2)), 1)
+
+    @staticmethod
+    def optimal_k(p: float) -> int:
+        """
+        Optimal number of hash functions for false-positive rate *p*.
+
+        Formula: k = round(ln(2) · m/n) = round(-ln(p) / ln(2))
+        """
+        if p <= 0 or p >= 1:
+            return 1
+        return max(round(-math.log(p) / math.log(2)), 1)
+
+    # ------------------------------------------------------------------
+    # Repr
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        return f"BloomHasher(k={self.k}, m={self.m}, device={self.device})"