metta-faiss 0.9.1__tar.gz

metta_faiss-0.9.1/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: metta-faiss
+Version: 0.9.1
+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.9.1
+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.1/README.md

@@ -0,0 +1,19 @@
+# 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.1/metta_faiss.egg-info/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: metta-faiss
+Version: 0.9.1
+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.9.1
+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.1/metta_faiss.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+metta_faiss.py
+pyproject.toml
+metta_faiss.egg-info/PKG-INFO
+metta_faiss.egg-info/SOURCES.txt
+metta_faiss.egg-info/dependency_links.txt
+metta_faiss.egg-info/entry_points.txt
+metta_faiss.egg-info/requires.txt
+metta_faiss.egg-info/top_level.txt
+tests/test_faiss.py

metta_faiss-0.9.1/metta_faiss.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

metta_faiss-0.9.1/metta_faiss.egg-info/entry_points.txt

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

metta_faiss-0.9.1/metta_faiss.egg-info/requires.txt

@@ -0,0 +1,3 @@
+pymetta==0.9.1
+faiss-cpu
+numpy

metta_faiss-0.9.1/metta_faiss.egg-info/top_level.txt

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

metta_faiss-0.9.1/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()

metta_faiss-0.9.1/pyproject.toml

@@ -0,0 +1,41 @@
+# Purpose: package metta-faiss, one distribution for one library.
+# Assumes: pymetta of the same version is installed; this is a workspace member
+#   released with it and pinned to it exactly.
+# Guarantees: importing metta_faiss registers this package's rows, and so does the
+#   `metta.extensions` entry point below when a dispatch discovers it.
+# Decides: the dependency set is this library and nothing else, which is what
+#   makes "the core names no library" hold without an allowlist.
+[build-system]
+requires = ["setuptools>=83"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "metta-faiss"
+version = "0.9.1"
+description = "faiss as a nearest-neighbour backend for a MeTTa embedding store"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+dependencies = [
+    #: pymetta of exactly this version. A member is released with the core and
+    #: reads its seam, so a floating pin would let a row meet a seam that no
+    #: longer declares its point.
+    "pymetta==0.9.1",
+    "faiss-cpu",
+    "numpy",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Science/Research",
+]
+
+#: How a seat that never heard of this package finds it: one entry in the
+#: group `metta.seam` reads, loaded at the first dispatch that has no answer
+#: without it. The target is the MODULE, whose body registers on import, which
+#: is the same door `import metta_faiss` opens.
+[project.entry-points."metta.extensions"]
+metta-faiss = "metta_faiss"
+
+[tool.setuptools]
+py-modules = ["metta_faiss"]

metta_faiss-0.9.1/setup.cfg

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

metta_faiss-0.9.1/tests/test_faiss.py

@@ -0,0 +1,51 @@
+"""Purpose: prove the faiss row searches, and wins `backend="auto"`.
+
+The second assertion is the load-bearing one. The Array API backend the array
+layer registers is always available, so with both rows present the ORDER
+decides `auto`, and order across distributions is not something a package can
+arrange: the fallback flag is what makes the specific row win either way.
+Open Obligations:
+  To Do: None
+  Hacks: None
+  Future Enhancements: None
+"""
+
+from __future__ import annotations
+
+import metta_arrays
+import metta_faiss
+import metta_numpy  # noqa: F401  -- the default array library the store needs
+import pytest
+
+from metta import S, seam
+
+pytest.importorskip("faiss")
+
+
+def test_the_row_is_registered_against_the_index_point():
+    """One row, named for the library, and NOT a fallback."""
+    row = seam.index.find("faiss")
+    assert row is not None
+    assert row.available() is True
+    assert not row.fallback
+
+
+def test_faiss_wins_auto_over_the_array_api_fallback():
+    """Every non-fallback row is consulted before every fallback one."""
+    names = [row.name for row in seam.index.rows()]
+    assert names.index("faiss") < names.index("argsort")
+    assert seam.index.find("argsort").fallback is True
+
+
+def test_an_embedding_store_searches_through_faiss(scratch_space):
+    """The store takes the backend by name and answers what faiss ranked."""
+    store = metta_arrays.EmbeddingStore(scratch_space, name="faiss_emb", backend="faiss")
+    store.add(S.dog, [1.0, 0.0])
+    store.add(S.cat, [0.0, 1.0])
+    assert [str(key) for key, _score in store.ranked([1.0, 0.0], 1)] == ["dog"]
+
+
+def test_an_absent_faiss_declines_rather_than_raising(monkeypatch):
+    """available() answers False, so the store falls through to the next row."""
+    monkeypatch.setattr(metta_faiss, "optional_module", lambda _name: None)
+    assert seam.index.find("faiss").available() is False