metta-faiss 0.9.0__py3-none-any.whl

metta_faiss-0.9.0.dist-info/METADATA

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: metta-faiss
+Version: 0.9.0
+Summary: faiss as a nearest-neighbour backend for a MeTTa embedding store
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pymetta==0.8.0
+Requires-Dist: faiss-cpu
+Requires-Dist: numpy
+
+# metta-faiss
+
+faiss as a nearest-neighbour backend for a MeTTa embedding store.
+
+`pymetta` names no third-party library. This package is one row against the `index` point, and the seat
+finds it exactly as it finds a package written by somebody else: through the
+`metta.extensions` entry point, loaded at the first dispatch that has no answer
+without it, or through `import metta_faiss`, whose module body registers the same
+rows.
+
+```sh
+pip install metta-faiss          # or: pip install 'pymetta[arrays]'
+```
+
+Its tests are in `tests/`, and they run in the workspace suite:
+
+```sh
+sh extensions/python/test.sh ext/metta-faiss
+```

metta_faiss-0.9.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+metta_faiss.py,sha256=FeiZpH0fmb9SRYwEEBsf6x1LCLp75E9wR8GO62zbFfU,3083
+metta_faiss-0.9.0.dist-info/METADATA,sha256=s0oNkR9k-VqcUu4feX6oa6XKgc4hiud16KrwQ8fAmXk,1068
+metta_faiss-0.9.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+metta_faiss-0.9.0.dist-info/entry_points.txt,sha256=ahP6XClBTPiBWg6Mbx8bsxg6CXRcAB9sCXBtgGKh3OA,45
+metta_faiss-0.9.0.dist-info/top_level.txt,sha256=tM7Yb1N2mt3vDHsqEMiUG4kM4gxcl-Cw6W7pTX7Bi3M,12
+metta_faiss-0.9.0.dist-info/RECORD,,

metta_faiss-0.9.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

metta_faiss-0.9.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[metta.extensions]
+metta-faiss = metta_faiss

metta_faiss-0.9.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+metta_faiss

metta_faiss.py

@@ -0,0 +1,86 @@
+"""Purpose: faiss as a nearest-neighbour backend of the MeTTa Python seat.
+
+One row against the seat's `index` point, so an embedding store searches
+through faiss when this package is installed. The row is NOT a fallback, which
+is what makes `backend="auto"` prefer it over the generic Array API path
+whatever order the two distributions loaded in; entry-point order is not
+something a package can arrange.
+
+NumPy is a dependency here and is not an integration: faiss' own interface
+takes contiguous float32 NumPy arrays for `add` and `search`, so staging one is
+part of calling faiss at all, and faiss-cpu depends on NumPy itself.
+
+Assumes:
+  - a normalized matrix, which is the `index` point's contract: the backend
+    searches inner products and the store normalizes before it gets here
+Guarantees:
+  - `available()` answers False rather than raising when faiss is absent, so
+    an embedding store falls through to the next backend instead of failing
+    [tested: tests/test_faiss.py::test_an_absent_faiss_declines_rather_than_raising;
+    commit=94057a0f073c0fab0a35c42beff2c324d8a0addd]
+  - faiss wins `backend="auto"` over the Array API fallback in either load
+    order [tested: tests/test_faiss.py::test_faiss_wins_auto_over_the_array_api_fallback;
+    commit=94057a0f073c0fab0a35c42beff2c324d8a0addd]
+Open Obligations:
+  To Do: None
+  Hacks: None
+  Future Enhancements: None
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+from metta import seam
+
+_MISSING: Final = (
+    "the faiss embedding backend needs faiss-cpu; install pymetta[arrays]"
+)
+_NUMPY_MISSING: Final = (
+    "the faiss embedding backend stages its matrix as a contiguous float32 "
+    "NumPy array, which is faiss' own interface, and NumPy is not installed; "
+    "install pymetta[arrays]"
+)
+
+require_module = seam.at("module").call()
+optional_module = seam.at("optional-module").call()
+
+
+def _available() -> bool:
+    """Whether faiss can run here."""
+    return optional_module("faiss") is not None
+
+
+def _build(matrix: Any) -> Any:
+    """An exact inner-product index over the normalized matrix."""
+    faiss = require_module("faiss", _MISSING)
+    numpy = require_module("numpy", _NUMPY_MISSING)
+    staged = numpy.ascontiguousarray(numpy.asarray(matrix, dtype=numpy.float32))
+    index = faiss.IndexFlatIP(staged.shape[1])
+    index.add(staged)
+    return index
+
+
+def _search(index: Any, query: Any, count: int) -> list[tuple[int, float]]:
+    """(row, score) pairs best first, from the built index."""
+    numpy = require_module("numpy", _NUMPY_MISSING)
+    probe = numpy.ascontiguousarray(numpy.asarray(query, dtype=numpy.float32).reshape(1, -1))
+    scores, indexes = index.search(probe, count)
+    return [
+        (int(index), float(score))
+        for score, index in zip(scores[0], indexes[0], strict=True)
+    ]
+
+
+def register() -> None:
+    """This package's one row, against the seat's `index` point."""
+    seam.index.register(
+        "faiss",
+        available=_available,
+        build=_build,
+        search=_search,
+        missing=_MISSING,
+    )
+
+
+register()