feat: Implement binary shield as a library

README.md

@@ -0,0 +1,3 @@
+Implementation of the paper "Cross-Service Threat Intelligence in LLM Services using Privacy-Preserving Fingerprints".
+
+https://arxiv.org/abs/2509.05608v1

pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "binary-shield"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Gokul Soumya", email = "gokul@cyvia.ai" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "numpy>=2.4.0",
+    "sentence-transformers>=5.2.0",
+    "torch>=2.9.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.12,<0.10.0"]
+build-backend = "uv_build"

src/binary_shield/__init__.py

@@ -0,0 +1,3 @@
+from binary_shield.shield import BinaryShield, BinaryFingerprint, ComparisonResult
+
+__all__ = ["BinaryShield", "BinaryFingerprint", "ComparisonResult"]

src/binary_shield/comparison.py

@@ -0,0 +1,9 @@
+import numpy as np
+
+
+def hamming_distance(bits1: np.ndarray, bits2: np.ndarray) -> int:
+    return int(np.count_nonzero(bits1 != bits2))
+
+
+def compute_similarity(bits1: np.ndarray, bits2: np.ndarray) -> float:
+    raise NotImplementedError

src/binary_shield/embedding.py

@@ -0,0 +1,6 @@
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+
+def extract_embedding(text: str, model: SentenceTransformer) -> np.ndarray:
+    return model.encode(text, convert_to_numpy=True)

src/binary_shield/privacy.py

@@ -0,0 +1,13 @@
+import numpy as np
+
+
+def apply_randomized_response(bits: np.ndarray, epsilon: float) -> np.ndarray:
+    keep_prob = np.exp(epsilon) / (1 + np.exp(epsilon))  # sigmoid fn
+
+    # Generate random decisions for each bit
+    keep_mask = np.random.random(bits.shape) < keep_prob
+
+    # For bits we don't keep, flip them
+    noisy_bits = np.where(keep_mask, bits, 1 - bits)
+
+    return noisy_bits

src/binary_shield/quantization.py

@@ -0,0 +1,12 @@
+import numpy as np
+
+type BinaryPackedEmbedding = np.ndarray[tuple[int], np.dtype[np.uint8]]
+
+
+def binary_quantize(embedding: np.ndarray) -> np.ndarray:
+    # TODO: [1] mentions that quantization can also be done by the model
+    # during encoding. Need to test whether that is faster.
+    # [1]: https://www.sbert.net/examples/sentence_transformer/applications/embedding-quantization/README.html#binary-quantization-in-sentence-transformers
+    binary_embedding = embedding > 0
+    return binary_embedding
+    # return np.packbits(binary_embedding)

src/binary_shield/shield.py

@@ -0,0 +1,54 @@
+from sentence_transformers import SentenceTransformer
+from dataclasses import dataclass
+
+from binary_shield.comparison import compute_similarity, hamming_distance
+from binary_shield.embedding import extract_embedding
+from binary_shield.privacy import apply_randomized_response
+from binary_shield.quantization import BinaryPackedEmbedding, binary_quantize
+
+
+@dataclass
+class BinaryFingerprint:
+    fingerprint: BinaryPackedEmbedding
+    epsilon: float | None
+
+
+@dataclass
+class ComparisonResult:
+    hamming_distance: int
+    similarity: float
+    is_match: bool
+
+
+class BinaryShield:
+    def __init__(
+        self,
+        model_name: str = "all-MiniLM-L6-v2",
+        epsilon: float | None = None,
+    ) -> None:
+        self.model = SentenceTransformer(model_name)
+        self.epsilon = epsilon
+
+    def generate_fingerprint(self, text: str) -> BinaryFingerprint:
+        embedding = extract_embedding(text, self.model)
+        bin_embedding = binary_quantize(embedding)
+        if self.epsilon is not None:
+            bin_embedding = apply_randomized_response(bin_embedding, self.epsilon)
+        return BinaryFingerprint(
+            fingerprint=bin_embedding,
+            epsilon=self.epsilon,
+        )
+
+    @staticmethod
+    def compare(
+        fp1: BinaryFingerprint,
+        fp2: BinaryFingerprint,
+        threshold: float = 0.8,
+    ) -> ComparisonResult:
+        dist = hamming_distance(fp1.fingerprint, fp2.fingerprint)
+        sim = compute_similarity(fp1.fingerprint, fp2.fingerprint)
+        return ComparisonResult(
+            hamming_distance=dist,
+            similarity=sim,
+            is_match=sim >= threshold,
+        )