xyberos-faiss 0.1.0__tar.gz

xyberos_faiss-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: xyberos-faiss
+Version: 0.1.0
+Summary: FAISS VectorStore plugin (RFC-0019, M4): local, dependency-free-of-server vector search
+License: Apache-2.0
+Keywords: xyberos,plugin,vector,faiss,rag
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+Provides-Extra: vectors
+Requires-Dist: faiss-cpu; extra == "vectors"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# xyberos-faiss
+
+**FAISS `VectorStore` plugin — RFC-0019, M4.** A purely local, no-server vector
+store backed by [FAISS](https://github.com/facebookresearch/faiss). Passes the
+same parity scenarios as the stdlib `SqliteVectorStore` (the M4 Definition of
+Done).
+
+## Install
+
+```bash
+pip install -e ./faiss
+pip install faiss-cpu             # or: pip install xyberos[vectors]
+```
+
+> `faiss-cpu` wheels are available on PyPI for Linux/macOS; on Windows use a
+> conda env or run the parity tests on a platform with wheels — the tests skip
+> cleanly when the module is absent.
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_faiss import FaissPlugin
+
+app = create_app()
+app.load_plugin(FaissPlugin())
+
+store = app.resolve("vector_store")
+store.upsert("ns", "doc-1", [1.0, 0.0, 0.0, 0.0], {"text": "alpha"})
+hits = store.query("ns", [1.0, 0.0, 0.0, 0.0], top_k=3)
+```
+
+## Design
+
+- Each **namespace** is an in-memory `faiss.IndexFlatIP` over **L2-normalized**
+  vectors, so inner-product scores equal cosine similarity (higher = more
+  relevant, matching the `VectorStore` contract).
+- `dim` is optional and auto-detected from the first upsert (`FAISS_DIM` env
+  honored).
+- `faiss` is imported **lazily**; a clear `ProviderError` is raised when it is
+  missing.
+
+## Tests
+
+```bash
+pip install pytest
+pytest tests/          # unit + parity + plugin tests
+```
+
+Parity tests run the exact scenarios the `SqliteVectorStore` reference passes;
+they skip cleanly when `faiss-cpu` is not importable on the current platform.
+
+## Ship location
+
+`[vectors]` extra (`faiss-cpu` already added to `pyproject.toml`).

xyberos_faiss-0.1.0/README.md

@@ -0,0 +1,55 @@
+# xyberos-faiss
+
+**FAISS `VectorStore` plugin — RFC-0019, M4.** A purely local, no-server vector
+store backed by [FAISS](https://github.com/facebookresearch/faiss). Passes the
+same parity scenarios as the stdlib `SqliteVectorStore` (the M4 Definition of
+Done).
+
+## Install
+
+```bash
+pip install -e ./faiss
+pip install faiss-cpu             # or: pip install xyberos[vectors]
+```
+
+> `faiss-cpu` wheels are available on PyPI for Linux/macOS; on Windows use a
+> conda env or run the parity tests on a platform with wheels — the tests skip
+> cleanly when the module is absent.
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_faiss import FaissPlugin
+
+app = create_app()
+app.load_plugin(FaissPlugin())
+
+store = app.resolve("vector_store")
+store.upsert("ns", "doc-1", [1.0, 0.0, 0.0, 0.0], {"text": "alpha"})
+hits = store.query("ns", [1.0, 0.0, 0.0, 0.0], top_k=3)
+```
+
+## Design
+
+- Each **namespace** is an in-memory `faiss.IndexFlatIP` over **L2-normalized**
+  vectors, so inner-product scores equal cosine similarity (higher = more
+  relevant, matching the `VectorStore` contract).
+- `dim` is optional and auto-detected from the first upsert (`FAISS_DIM` env
+  honored).
+- `faiss` is imported **lazily**; a clear `ProviderError` is raised when it is
+  missing.
+
+## Tests
+
+```bash
+pip install pytest
+pytest tests/          # unit + parity + plugin tests
+```
+
+Parity tests run the exact scenarios the `SqliteVectorStore` reference passes;
+they skip cleanly when `faiss-cpu` is not importable on the current platform.
+
+## Ship location
+
+`[vectors]` extra (`faiss-cpu` already added to `pyproject.toml`).

xyberos_faiss-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xyberos-faiss"
+version = "0.1.0"
+description = "FAISS VectorStore plugin (RFC-0019, M4): local, dependency-free-of-server vector search"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+dependencies = ["xyberos>=1.0"]
+keywords = ["xyberos", "plugin", "vector", "faiss", "rag"]
+
+[project.optional-dependencies]
+vectors = ["faiss-cpu"]
+test = ["pytest"]
+
+[project.entry-points."xyberos.plugins"]
+faiss = "xyberos_faiss.plugin:plugin"
+
+[tool.setuptools]
+packages = ["xyberos_faiss"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

xyberos_faiss-0.1.0/setup.cfg

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

xyberos_faiss-0.1.0/tests/test_fake_faiss.py

@@ -0,0 +1,125 @@
+"""Exercise the FaissVectorStore logic against a numpy-backed fake faiss.
+
+faiss-cpu has no wheels on every platform (e.g. Windows), so this module runs
+the store's full logic — including the M4 parity scenarios — against a faithful
+``IndexFlatIP`` stand-in. It gives real coverage wherever pytest runs; the
+``test_parity.py`` module covers the real ``faiss-cpu`` when it is present.
+"""
+
+from __future__ import annotations
+
+import sys
+import types
+
+import numpy as np
+import pytest
+
+
+class _IndexFlatIP:
+    """An in-memory inner-product index matching the faiss API subset used."""
+
+    def __init__(self, dim: int) -> None:
+        self._dim = int(dim)
+        self._rows = np.empty((0, self._dim), dtype="float32")
+
+    def add(self, x: object) -> None:
+        self._rows = np.vstack([self._rows, np.asarray(x, dtype="float32")])
+
+    @property
+    def ntotal(self) -> int:
+        return self._rows.shape[0]
+
+    def search(self, x: object, k: int) -> tuple[np.ndarray, np.ndarray]:
+        matrix = np.asarray(x, dtype="float32")
+        if matrix.ndim == 1:
+            matrix = matrix[None, :]
+        scores = self._rows @ matrix.T
+        n_queries = matrix.shape[0]
+        k = min(int(k), self.ntotal)
+        distances = np.zeros((n_queries, k), dtype="float32")
+        indices = np.full((n_queries, k), -1, dtype="int64")
+        for query in range(n_queries):
+            order = np.argsort(scores[:, query])[::-1][:k]
+            distances[query] = scores[order, query]
+            indices[query] = order
+        return distances, indices
+
+
+@pytest.fixture(autouse=True)
+def fake_faiss():
+    """Inject a fake ``faiss`` module unless the real one is already present."""
+    if sys.modules.get("faiss") is None:
+        module = types.ModuleType("faiss")
+        module.IndexFlatIP = _IndexFlatIP
+        sys.modules["faiss"] = module
+    yield
+
+
+QUERY = [1.0, 0.0, 0.0, 0.0]
+
+
+def run_parity_scenarios(store) -> None:
+    """The full VectorStore contract; every adapter must pass these."""
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0], {"text": "alpha"})
+    store.upsert("ns", "b", [0.8, 0.2, 0.0, 0.0], {"text": "beta"})
+    store.upsert("ns", "c", [0.5, 0.5, 0.0, 0.0], {"text": "gamma"})
+    store.upsert("other", "x", [1.0, 1.0, 1.0, 1.0], {"text": "other ns"})
+
+    hits = store.query("ns", QUERY, top_k=3)
+    assert [h.id for h in hits] == ["a", "b", "c"]
+    assert hits[0].payload["text"] == "alpha"
+    assert hits[0].score > hits[1].score > hits[2].score
+    assert len(store.query("ns", QUERY, top_k=1)) == 1
+
+    strict = store.query("ns", QUERY, top_k=3, threshold=0.99)
+    assert [h.id for h in strict] == ["a"]
+
+    store.delete("ns", "b")
+    assert [h.id for h in store.query("ns", QUERY, top_k=3)] == ["a", "c"]
+    assert [h.id for h in store.query("other", [1.0, 1.0, 1.0, 1.0], top_k=2)] == ["x"]
+    assert all(abs(h.score) < 1e-6 for h in store.query("ns", [0.0, 0.0, 0.0, 1.0], top_k=2))
+
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0], {"text": "alpha-v2"})
+    assert store.query("ns", QUERY, top_k=1)[0].payload["text"] == "alpha-v2"
+
+    store.clear("ns")
+    assert store.query("ns", QUERY, top_k=3) == []
+    assert [h.id for h in store.query("other", [1.0, 1.0, 1.0, 1.0], top_k=1)] == ["x"]
+
+
+def test_parity_with_fake_faiss():
+    from xyberos_faiss import FaissVectorStore
+
+    run_parity_scenarios(FaissVectorStore())
+
+
+def test_upsert_and_query_order():
+    from xyberos_faiss import FaissVectorStore
+
+    store = FaissVectorStore()
+    store.upsert("ns", "a", [1.0, 0.0, 0.0], {"text": "alpha"})
+    store.upsert("ns", "b", [0.0, 1.0, 0.0], {"text": "beta"})
+    hits = store.query("ns", [1.0, 0.0, 0.0], top_k=2)
+    assert hits[0].id == "a"
+    assert hits[0].payload["text"] == "alpha"
+
+
+def test_delete_and_clear():
+    from xyberos_faiss import FaissVectorStore
+
+    store = FaissVectorStore()
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0])
+    store.upsert("ns", "b", [0.0, 1.0, 0.0, 0.0])
+    store.delete("ns", "a")
+    assert [h.id for h in store.query("ns", [1.0, 0.0, 0.0, 0.0], top_k=2)] == ["b"]
+    store.clear("ns")
+    assert store.query("ns", [1.0, 0.0, 0.0, 0.0]) == []
+
+
+def test_dimension_mismatch_raises():
+    from xyberos_faiss import FaissVectorStore
+
+    store = FaissVectorStore()
+    store.upsert("ns", "a", [1.0, 0.0, 0.0])
+    with pytest.raises(ValueError, match="dimension"):
+        store.query("ns", [1.0, 0.0, 0.0, 0.0])

xyberos_faiss-0.1.0/tests/test_parity.py

@@ -0,0 +1,54 @@
+"""M4 parity: FaissVectorStore must behave like SqliteVectorStore."""
+
+from __future__ import annotations
+
+import importlib.util
+
+import pytest
+from xyberos.vector import SqliteVectorStore
+
+from xyberos_faiss import FaissVectorStore
+
+QUERY = [1.0, 0.0, 0.0, 0.0]
+
+
+def run_parity_scenarios(store) -> None:
+    """The full VectorStore contract; every adapter must pass these."""
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0], {"text": "alpha"})
+    store.upsert("ns", "b", [0.8, 0.2, 0.0, 0.0], {"text": "beta"})
+    store.upsert("ns", "c", [0.5, 0.5, 0.0, 0.0], {"text": "gamma"})
+    store.upsert("other", "x", [1.0, 1.0, 1.0, 1.0], {"text": "other ns"})
+
+    hits = store.query("ns", QUERY, top_k=3)
+    assert [h.id for h in hits] == ["a", "b", "c"]
+    assert hits[0].payload["text"] == "alpha"
+    assert hits[0].score > hits[1].score > hits[2].score
+    assert len(store.query("ns", QUERY, top_k=1)) == 1
+
+    strict = store.query("ns", QUERY, top_k=3, threshold=0.99)
+    assert [h.id for h in strict] == ["a"]
+
+    store.delete("ns", "b")
+    assert [h.id for h in store.query("ns", QUERY, top_k=3)] == ["a", "c"]
+    assert [h.id for h in store.query("other", [1.0, 1.0, 1.0, 1.0], top_k=2)] == ["x"]
+    assert all(abs(h.score) < 1e-6 for h in store.query("ns", [0.0, 0.0, 0.0, 1.0], top_k=2))
+
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0], {"text": "alpha-v2"})
+    assert store.query("ns", QUERY, top_k=1)[0].payload["text"] == "alpha-v2"
+
+    store.clear("ns")
+    assert store.query("ns", QUERY, top_k=3) == []
+    assert [h.id for h in store.query("other", [1.0, 1.0, 1.0, 1.0], top_k=1)] == ["x"]
+
+
+def test_sqlite_reference() -> None:
+    """The stdlib reference passes the same scenarios the adapters must match."""
+    run_parity_scenarios(SqliteVectorStore(":memory:"))
+
+
+@pytest.mark.skipif(
+    importlib.util.find_spec("faiss") is None,
+    reason="faiss-cpu is not installed on this platform",
+)
+def test_faiss_parity():
+    run_parity_scenarios(FaissVectorStore())

xyberos_faiss-0.1.0/tests/test_plugin.py

@@ -0,0 +1,31 @@
+"""Tests for loading the faiss plugin into a Xyberos app."""
+
+from __future__ import annotations
+
+import importlib.util
+
+import pytest
+from xyberos import create_app
+
+pytestmark = pytest.mark.skipif(
+    importlib.util.find_spec("faiss") is None,
+    reason="faiss-cpu is not installed on this platform",
+)
+
+from xyberos_faiss import FaissPlugin  # noqa: E402
+
+
+def test_plugin_conforms_to_contract():
+    plugin = FaissPlugin()
+    assert plugin.name == "faiss"
+    assert callable(plugin.register) and callable(plugin.unregister)
+    assert plugin.vector_store() is plugin.vector_store()
+
+
+def test_plugin_registers_vector_store():
+    app = create_app()
+    app.load_plugin(FaissPlugin())
+    store = app.resolve("vector_store")
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0], {"text": "alpha"})
+    assert store.query("ns", [1.0, 0.0, 0.0, 0.0], top_k=1)[0].payload["text"] == "alpha"
+    app.unload_plugin("faiss")

xyberos_faiss-0.1.0/tests/test_vector.py

@@ -0,0 +1,44 @@
+"""Unit tests for the FaissVectorStore (skip cleanly when faiss is missing)."""
+
+from __future__ import annotations
+
+import importlib.util
+
+import pytest
+
+pytestmark = pytest.mark.skipif(
+    importlib.util.find_spec("faiss") is None,
+    reason="faiss-cpu is not installed on this platform",
+)
+
+from xyberos_faiss import FaissVectorStore  # noqa: E402
+
+
+@pytest.fixture()
+def store():
+    return FaissVectorStore()
+
+
+def test_upsert_and_query(store):
+    store.upsert("ns", "a", [1.0, 0.0, 0.0], {"text": "alpha"})
+    store.upsert("ns", "b", [0.0, 1.0, 0.0], {"text": "beta"})
+    hits = store.query("ns", [1.0, 0.0, 0.0], top_k=2)
+    assert hits[0].id == "a"
+    assert hits[0].payload["text"] == "alpha"
+
+
+def test_delete(store):
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0])
+    store.upsert("ns", "b", [0.0, 1.0, 0.0, 0.0])
+    store.delete("ns", "a")
+    assert [h.id for h in store.query("ns", [1.0, 0.0, 0.0, 0.0], top_k=2)] == ["b"]
+
+
+def test_clear(store):
+    store.upsert("ns", "a", [1.0, 0.0, 0.0, 0.0])
+    store.clear("ns")
+    assert store.query("ns", [1.0, 0.0, 0.0, 0.0]) == []
+
+
+def test_missing_namespace_returns_empty(store):
+    assert store.query("missing", [1.0, 0.0, 0.0, 0.0]) == []

xyberos_faiss-0.1.0/xyberos_faiss/__init__.py

@@ -0,0 +1,6 @@
+"""FAISS VectorStore plugin (RFC-0019, M4)."""
+
+from .plugin import FaissPlugin
+from .vector import FaissVectorStore
+
+__all__ = ["FaissPlugin", "FaissVectorStore"]

xyberos_faiss-0.1.0/xyberos_faiss/plugin.py

@@ -0,0 +1,42 @@
+"""FAISS plugin entry point (RFC-0019, M4)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from xyberos.contracts import Plugin, VectorStore
+
+from .vector import FaissVectorStore
+
+
+class FaissPlugin(Plugin):
+    """Registers a :class:`FaissVectorStore` as the app's ``vector_store``.
+
+    ``dim`` is optional and auto-detected from the first upsert. ``FAISS_DIM``
+    env var is honored as a fallback.
+    """
+
+    def __init__(self, *, dim: int | None = None) -> None:
+        raw_dim = dim if dim is not None else os.getenv("FAISS_DIM")
+        self._dim = int(raw_dim) if raw_dim else None
+        self._store: FaissVectorStore | None = None
+
+    @property
+    def name(self) -> str:
+        return "faiss"
+
+    def vector_store(self) -> FaissVectorStore:
+        if self._store is None:
+            self._store = FaissVectorStore(dim=self._dim)
+        return self._store
+
+    def register(self, kernel: object) -> None:
+        kernel.register("vector_store", self.vector_store(), replace=True)
+
+    def unregister(self, kernel: object) -> None:
+        pass
+
+
+#: Auto-discovered by ``app.load_entry_points()``.
+plugin = FaissPlugin()

xyberos_faiss-0.1.0/xyberos_faiss/vector.py

@@ -0,0 +1,142 @@
+"""FAISS-backed :class:`~xyberos.contracts.VectorStore` (lazy ``faiss-cpu``).
+
+A purely local, no-server vector store. Each namespace is an in-memory
+``faiss.IndexFlatIP`` over **L2-normalized** vectors, so inner-product scores
+equal cosine similarity — matching the ``VectorStore`` contract where a higher
+score means more relevant (and matching ``SqliteVectorStore`` / Qdrant
+behavior).
+
+The ``faiss`` module is imported lazily on first use and a clear
+:class:`~xyberos.exceptions.provider.ProviderError` is raised when it is
+missing (``pip install xyberos[vectors]``).
+"""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from xyberos.contracts.vector import ScoredHit, VectorStore
+from xyberos.exceptions.provider import ProviderError
+
+
+def _require_faiss() -> Any:
+    try:
+        faiss = importlib.import_module("faiss")
+    except ImportError as exc:
+        raise ProviderError(
+            "the 'faiss-cpu' package is required; install it with "
+            "'pip install xyberos[vectors]'"
+        ) from exc
+    return faiss
+
+
+def _normalize(vector: Sequence[float]) -> list[float]:
+    norm = sum(value * value for value in vector) ** 0.5
+    if norm == 0.0:
+        return [float(value) for value in vector]
+    return [float(value) / norm for value in vector]
+
+
+class FaissVectorStore(VectorStore):
+    """A :class:`VectorStore` backed by an in-memory FAISS index per namespace."""
+
+    def __init__(self, dim: int | None = None, *, normalize: bool = True) -> None:
+        if dim is not None and dim <= 0:
+            raise ValueError("dim must be a positive integer")
+        self._dim = dim
+        self._normalize = normalize
+        # namespace -> ordered {id: (vector, payload)}
+        self._data: dict[str, dict[str, tuple[list[float], dict[str, Any] | None]]] = {}
+        # namespace -> faiss index
+        self._indexes: dict[str, Any] = {}
+
+    def upsert(
+        self,
+        namespace: str,
+        id: str,
+        vector: Sequence[float],
+        payload: Mapping[str, Any] | None = None,
+    ) -> None:
+        faiss = _require_faiss()
+        vectors = [float(value) for value in vector]
+        if self._dim is None:
+            self._dim = len(vectors)
+        elif len(vectors) != self._dim:
+            raise ValueError(
+                f"vector dimension {len(vectors)} != store dimension {self._dim}"
+            )
+        bucket = self._data.setdefault(namespace, {})
+        bucket[str(id)] = (vectors, dict(payload or {}))
+        self._rebuild(namespace, faiss)
+
+    def query(
+        self,
+        namespace: str,
+        vector: Sequence[float],
+        *,
+        top_k: int = 5,
+        threshold: float | None = None,
+    ) -> list[ScoredHit]:
+        faiss = _require_faiss()
+        bucket = self._data.get(namespace)
+        if not bucket:
+            return []
+        if len(vector) != self._dim:
+            raise ValueError(
+                f"query dimension {len(vector)} != store dimension {self._dim}"
+            )
+        index = self._indexes.get(namespace)
+        if index is None or index.ntotal != len(bucket):
+            self._rebuild(namespace, faiss)
+            index = self._indexes[namespace]
+        if index.ntotal == 0:
+            return []
+
+        numpy = importlib.import_module("numpy")
+
+        query_vector = _normalize(list(vector)) if self._normalize else list(vector)
+        k = min(max(top_k, 1), index.ntotal)
+        distances, indices = index.search(numpy.array([query_vector], dtype="float32"), k)
+
+        ids = list(bucket.keys())
+        hits: list[ScoredHit] = []
+        for distance, position in zip(distances[0], indices[0]):
+            if position < 0 or position >= len(ids):
+                continue
+            item_id = ids[int(position)]
+            score = float(distance)
+            if threshold is not None and score < threshold:
+                continue
+            _, payload = bucket[item_id]
+            hits.append(ScoredHit(id=item_id, score=score, payload=payload))
+        return hits
+
+    def delete(self, namespace: str, id: str) -> None:
+        faiss = _require_faiss()
+        bucket = self._data.get(namespace)
+        if bucket is None:
+            return
+        bucket.pop(str(id), None)
+        self._rebuild(namespace, faiss)
+
+    def clear(self, namespace: str) -> None:
+        self._data.pop(namespace, None)
+        self._indexes.pop(namespace, None)
+
+    # -- internals ----------------------------------------------------------
+
+    def _rebuild(self, namespace: str, faiss: Any) -> None:
+        bucket = self._data.get(namespace, {})
+        if not bucket:
+            self._indexes.pop(namespace, None)
+            return
+        numpy = importlib.import_module("numpy")
+
+        vectors = [v for v, _ in bucket.values()]
+        if self._normalize:
+            vectors = [_normalize(v) for v in vectors]
+        index = faiss.IndexFlatIP(self._dim or len(vectors))
+        index.add(numpy.array(vectors, dtype="float32"))
+        self._indexes[namespace] = index

xyberos_faiss-0.1.0/xyberos_faiss.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: xyberos-faiss
+Version: 0.1.0
+Summary: FAISS VectorStore plugin (RFC-0019, M4): local, dependency-free-of-server vector search
+License: Apache-2.0
+Keywords: xyberos,plugin,vector,faiss,rag
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+Provides-Extra: vectors
+Requires-Dist: faiss-cpu; extra == "vectors"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# xyberos-faiss
+
+**FAISS `VectorStore` plugin — RFC-0019, M4.** A purely local, no-server vector
+store backed by [FAISS](https://github.com/facebookresearch/faiss). Passes the
+same parity scenarios as the stdlib `SqliteVectorStore` (the M4 Definition of
+Done).
+
+## Install
+
+```bash
+pip install -e ./faiss
+pip install faiss-cpu             # or: pip install xyberos[vectors]
+```
+
+> `faiss-cpu` wheels are available on PyPI for Linux/macOS; on Windows use a
+> conda env or run the parity tests on a platform with wheels — the tests skip
+> cleanly when the module is absent.
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_faiss import FaissPlugin
+
+app = create_app()
+app.load_plugin(FaissPlugin())
+
+store = app.resolve("vector_store")
+store.upsert("ns", "doc-1", [1.0, 0.0, 0.0, 0.0], {"text": "alpha"})
+hits = store.query("ns", [1.0, 0.0, 0.0, 0.0], top_k=3)
+```
+
+## Design
+
+- Each **namespace** is an in-memory `faiss.IndexFlatIP` over **L2-normalized**
+  vectors, so inner-product scores equal cosine similarity (higher = more
+  relevant, matching the `VectorStore` contract).
+- `dim` is optional and auto-detected from the first upsert (`FAISS_DIM` env
+  honored).
+- `faiss` is imported **lazily**; a clear `ProviderError` is raised when it is
+  missing.
+
+## Tests
+
+```bash
+pip install pytest
+pytest tests/          # unit + parity + plugin tests
+```
+
+Parity tests run the exact scenarios the `SqliteVectorStore` reference passes;
+they skip cleanly when `faiss-cpu` is not importable on the current platform.
+
+## Ship location
+
+`[vectors]` extra (`faiss-cpu` already added to `pyproject.toml`).

xyberos_faiss-0.1.0/xyberos_faiss.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+tests/test_fake_faiss.py
+tests/test_parity.py
+tests/test_plugin.py
+tests/test_vector.py
+xyberos_faiss/__init__.py
+xyberos_faiss/plugin.py
+xyberos_faiss/vector.py
+xyberos_faiss.egg-info/PKG-INFO
+xyberos_faiss.egg-info/SOURCES.txt
+xyberos_faiss.egg-info/dependency_links.txt
+xyberos_faiss.egg-info/entry_points.txt
+xyberos_faiss.egg-info/requires.txt
+xyberos_faiss.egg-info/top_level.txt

xyberos_faiss-0.1.0/xyberos_faiss.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xyberos_faiss-0.1.0/xyberos_faiss.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xyberos.plugins]
+faiss = xyberos_faiss.plugin:plugin

xyberos_faiss-0.1.0/xyberos_faiss.egg-info/requires.txt

@@ -0,0 +1,7 @@
+xyberos>=1.0
+
+[test]
+pytest
+
+[vectors]
+faiss-cpu

xyberos_faiss-0.1.0/xyberos_faiss.egg-info/top_level.txt

@@ -0,0 +1 @@
+xyberos_faiss