placeborag 0.0.1__py3-none-any.whl

placeborag/__init__.py

@@ -0,0 +1,17 @@
+"""Deterministic test doubles for the retrieval half of a RAG pipeline."""
+
+from placeborag.embedder import (
+    DEFAULT_DIMENSIONS,
+    DEFAULT_MODEL_NAME,
+    FakeEmbedder,
+    cosine_similarity,
+)
+
+__all__ = [
+    "DEFAULT_DIMENSIONS",
+    "DEFAULT_MODEL_NAME",
+    "FakeEmbedder",
+    "cosine_similarity",
+]
+
+__version__ = "0.0.1"

placeborag/embedder.py

@@ -0,0 +1,135 @@
+"""A deterministic embedder built on feature hashing.
+
+No model, no data file, no network. `embed` is a pure function of
+`(text, model_name, dimensions)`, so the same text always produces the same
+vector, and two texts that share tokens land near each other. That is what
+makes a top-k assertion in a test mean something.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from collections.abc import Iterable, Sequence
+
+DEFAULT_MODEL_NAME = "placebo-hash-001"
+DEFAULT_DIMENSIONS = 256
+
+_MIN_DIMENSIONS = 2
+_CHAR_NGRAM_SIZES = (3, 4)
+_WORD_PATTERN = re.compile(r"\w+", re.UNICODE)
+_KEY_SIZE = 32
+_DIGEST_SIZE = 8
+_SIGN_BIT = 1 << (_DIGEST_SIZE * 8 - 1)
+
+
+class FakeEmbedder:
+    """Embeds text into a deterministic unit vector.
+
+    Args:
+        model_name: Salts the hash. A different name yields a different but
+            equally deterministic embedding space, which is what makes the
+            "we swapped the embedding model and have to reindex" code path
+            testable.
+        dimensions: Length of the returned vector.
+    """
+
+    def __init__(
+        self,
+        model_name: str = DEFAULT_MODEL_NAME,
+        dimensions: int = DEFAULT_DIMENSIONS,
+    ) -> None:
+        if not isinstance(model_name, str) or not model_name:
+            raise ValueError("model_name must be a non-empty string")
+        if not isinstance(dimensions, int) or isinstance(dimensions, bool):
+            raise TypeError("dimensions must be an int")
+        if dimensions < _MIN_DIMENSIONS:
+            raise ValueError(f"dimensions must be >= {_MIN_DIMENSIONS}, got {dimensions}")
+
+        self._model_name = model_name
+        self._dimensions = dimensions
+        self._key = hashlib.blake2b(
+            f"{model_name}:{dimensions}".encode(), digest_size=_KEY_SIZE
+        ).digest()
+
+    @property
+    def model_name(self) -> str:
+        return self._model_name
+
+    @property
+    def dimensions(self) -> int:
+        return self._dimensions
+
+    def embed(self, text: str) -> list[float]:
+        """Returns the L2-normalized vector for `text`."""
+        if not isinstance(text, str):
+            raise TypeError(f"text must be a str, got {type(text).__name__}")
+
+        features = _features(text) or [_sentinel(text)]
+        vector = self._accumulate(features)
+        norm = _norm(vector)
+        if norm == 0.0:
+            # Signs cancelled out exactly. Vanishingly unlikely, but a zero
+            # vector cannot be normalized, so fall back to the sentinel.
+            vector = self._accumulate([_sentinel(text)])
+            norm = _norm(vector)
+        return [value / norm for value in vector]
+
+    def embed_batch(self, texts: Iterable[str]) -> list[list[float]]:
+        """Returns one vector per input text, in order."""
+        return [self.embed(text) for text in texts]
+
+    def _accumulate(self, features: Sequence[str]) -> list[float]:
+        vector = [0.0] * self._dimensions
+        for feature in features:
+            index, sign = self._bucket(feature)
+            vector[index] += sign
+        return vector
+
+    def _bucket(self, feature: str) -> tuple[int, float]:
+        digest = hashlib.blake2b(
+            feature.encode("utf-8"), key=self._key, digest_size=_DIGEST_SIZE
+        ).digest()
+        value = int.from_bytes(digest, "big")
+        index = value % self._dimensions
+        sign = -1.0 if value & _SIGN_BIT else 1.0
+        return index, sign
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(model_name={self._model_name!r}, "
+            f"dimensions={self._dimensions})"
+        )
+
+
+def cosine_similarity(left: Sequence[float], right: Sequence[float]) -> float:
+    """Cosine similarity of two vectors of equal length."""
+    if len(left) != len(right):
+        raise ValueError(f"dimension mismatch: {len(left)} != {len(right)}")
+    left_norm = _norm(left)
+    right_norm = _norm(right)
+    if left_norm == 0.0 or right_norm == 0.0:
+        raise ValueError("cosine similarity is undefined for a zero vector")
+    dot = sum(a * b for a, b in zip(left, right))
+    return dot / (left_norm * right_norm)
+
+
+def _features(text: str) -> list[str]:
+    lowered = text.lower()
+    features = [f"w:{token}" for token in _WORD_PATTERN.findall(lowered)]
+    for size in _CHAR_NGRAM_SIZES:
+        features.extend(
+            f"c{size}:{lowered[start : start + size]}"
+            for start in range(len(lowered) - size + 1)
+        )
+    return features
+
+
+def _sentinel(text: str) -> str:
+    """Feature used for inputs that produce no n-grams or word tokens."""
+    return f"\x00empty\x00{text}"
+
+
+def _norm(vector: Sequence[float]) -> float:
+    return math.sqrt(sum(value * value for value in vector))

placeborag-0.0.1.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: placeborag
+Version: 0.0.1
+Summary: Deterministic test doubles for the retrieval half of a RAG pipeline
+Project-URL: Homepage, https://github.com/elaz48/placeborag
+Project-URL: Issues, https://github.com/elaz48/placeborag/issues
+Author: elaz48
+License-Expression: MIT
+License-File: LICENSE
+Keywords: embeddings,mock,pytest,rag,retrieval,testing,vector-store
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Testing :: Mocking
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# placeborag
+
+Deterministic test doubles for the **retrieval** half of a RAG pipeline.
+
+Existing mock LLM tooling stubs the chat completion endpoint and hands back pseudo-random embedding vectors of the correct shape. Correct shape, no semantic structure. Any document can come back at any rank, so every retrieval assertion in your test suite is decorative: you can assert that the pipeline ran, not that it retrieved the right thing.
+
+placeborag gives you an embedder that is a pure function whose output geometry you can reason about — offline, in microseconds, with no model and no network.
+
+## Install
+
+```bash
+pip install placeborag
+```
+
+## Use
+
+```python
+from placeborag import FakeEmbedder, cosine_similarity
+
+embedder = FakeEmbedder()
+
+query = embedder.embed("refund policy")
+related = embedder.embed("what is your refund policy for orders")
+unrelated = embedder.embed("delivery times to remote islands")
+
+assert cosine_similarity(query, related) > cosine_similarity(query, unrelated)
+```
+
+The same text always gives the same vector, so a top-k assertion is stable across runs and across machines:
+
+```python
+assert embedder.embed("refund policy") == embedder.embed("refund policy")
+```
+
+Changing `model_name` changes the embedding space, which is what makes the "we swapped the embedding model and have to reindex" code path testable:
+
+```python
+a = FakeEmbedder(model_name="text-embedding-3-small")
+b = FakeEmbedder(model_name="text-embedding-3-large")
+
+assert a.embed("refund policy") != b.embed("refund policy")
+```
+
+Every vector is L2-normalized, including for the empty string and for non-ASCII input.
+
+## How it works
+
+Character n-grams and word tokens are hashed into `dimensions` buckets with a signed hashing trick, summed, and normalized. Texts sharing tokens land near each other. There is no training data and no model file — the seed is derived from `(text, model_name, dimensions)`.
+
+That makes the ranking explainable to whoever reads the failing test, which is the part random vectors can never give you.
+
+## Status
+
+0.0.1 is deliberately small: the hashing layer of `FakeEmbedder` and nothing else. It exists to prove the release pipeline.
+
+Next up:
+
+- declared clusters, so you can steer which texts are near which
+- a fake vector store reproducing real backend score conventions (distance-lower-is-better vs score-higher-is-better) and pre-filter vs post-filter semantics
+- pytest fixtures as a thin layer over the library
+
+## What this is not
+
+Not an eval framework, not a benchmark, not a production vector store, and not another OpenAI-compatible mock server.
+
+## License
+
+MIT

placeborag-0.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+placeborag/__init__.py,sha256=yhWcPC1U6-9xjrT9cVCI-bTx5RIKrb0_r24aefTia2M,336
+placeborag/embedder.py,sha256=m6gDhXxRdBqu-JEbrqPdp6CLVL6wBAlbtf_oIDdNImw,4717
+placeborag-0.0.1.dist-info/METADATA,sha256=eYPRErRqPMG1FnftTeikpV8ZvVbymZn3pTyF6PM8kgQ,3609
+placeborag-0.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+placeborag-0.0.1.dist-info/licenses/LICENSE,sha256=3ssjZ-LOyHMTRRux78rkd-T98lJAyd4RAiX8q9UHJR0,1063
+placeborag-0.0.1.dist-info/RECORD,,

placeborag-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

placeborag-0.0.1.dist-info/licenses/LICENSE

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