faiss-haystack 1.0.0__py3-none-any.whl

faiss_haystack-1.0.0.dist-info/METADATA

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: faiss-haystack
+Version: 1.0.0
+Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/faiss#readme
+Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
+Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/faiss
+Author-email: Deepset <info@deepset.ai>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: faiss-cpu>=1.8.0
+Requires-Dist: haystack-ai>=2.24.0
+Requires-Dist: numpy<2,>=1.22; python_version < '3.13'
+Description-Content-Type: text/markdown
+
+# faiss-haystack
+
+This package provides a [FAISS](https://github.com/facebookresearch/faiss) document store for [Haystack](https://github.com/deepset-ai/haystack).
+
+## Installation
+
+```bash
+pip install faiss-haystack
+```
+
+## Usage
+
+```python
+from haystack_integrations.document_stores.faiss import FAISSDocumentStore
+
+document_store = FAISSDocumentStore(index_path="my_index")
+```

faiss_haystack-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+haystack_integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/components/__init__.py,sha256=6GZ8Y3Lw0rLOsOAqi6Tu5mZC977UzQvgDxKpOWr8IQw,110
+haystack_integrations/components/retrievers/__init__.py,sha256=6GZ8Y3Lw0rLOsOAqi6Tu5mZC977UzQvgDxKpOWr8IQw,110
+haystack_integrations/components/retrievers/faiss/__init__.py,sha256=4kZDoOkRRxRaXjgJi9ZEz6ckHsORzVLbIz6-gdons_Q,206
+haystack_integrations/components/retrievers/faiss/embedding_retriever.py,sha256=dCrbxeT31o7dLZbLVtEDud9ceSrsd3oKOeFK921BhB8,6784
+haystack_integrations/components/retrievers/faiss/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/document_stores/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/document_stores/faiss/__init__.py,sha256=JkdbPAs4g1LnUaAPpws8qS4DCGZkFYjfoOuQltUZOYQ,81
+haystack_integrations/document_stores/faiss/document_store.py,sha256=Mz7GvPVTZsKkn7tLA4xEH9-BUCBnVrSTACIXg45-CMc,22432
+haystack_integrations/document_stores/faiss/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+faiss_haystack-1.0.0.dist-info/METADATA,sha256=7SngrnIUiikeQAYTG6Ap_EZJK4i53jLLpX6l6N9vVhY,1453
+faiss_haystack-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+faiss_haystack-1.0.0.dist-info/RECORD,,

faiss_haystack-1.0.0.dist-info/WHEEL

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

haystack_integrations/components/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0

haystack_integrations/components/retrievers/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0

haystack_integrations/components/retrievers/faiss/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+from .embedding_retriever import FAISSEmbeddingRetriever
+
+__all__ = ["FAISSEmbeddingRetriever"]

haystack_integrations/components/retrievers/faiss/embedding_retriever.py

@@ -0,0 +1,153 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from haystack import component, default_from_dict, default_to_dict
+from haystack.dataclasses import Document
+from haystack.document_stores.types import FilterPolicy
+from haystack.document_stores.types.filter_policy import apply_filter_policy
+
+from haystack_integrations.document_stores.faiss import FAISSDocumentStore
+
+
+@component
+class FAISSEmbeddingRetriever:
+    """
+    Retrieves documents from the `FAISSDocumentStore`, based on their dense embeddings.
+
+    Example usage:
+    ```python
+    from haystack import Document, Pipeline
+    from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+    from haystack.document_stores.types import DuplicatePolicy
+
+    from haystack_integrations.document_stores.faiss import FAISSDocumentStore
+    from haystack_integrations.components.retrievers.faiss import FAISSEmbeddingRetriever
+
+    document_store = FAISSDocumentStore(embedding_dim=768)
+
+    documents = [
+        Document(content="There are over 7,000 languages spoken around the world today."),
+        Document(content="Elephants have been observed to behave in a way that indicates a high level of intelligence."),
+        Document(content="In certain places, you can witness the phenomenon of bioluminescent waves."),
+    ]
+
+    document_embedder = SentenceTransformersDocumentEmbedder()
+    document_embedder.warm_up()
+    documents_with_embeddings = document_embedder.run(documents)["documents"]
+
+    document_store.write_documents(documents_with_embeddings, policy=DuplicatePolicy.OVERWRITE)
+
+    query_pipeline = Pipeline()
+    query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+    query_pipeline.add_component("retriever", FAISSEmbeddingRetriever(document_store=document_store))
+    query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+    query = "How many languages are there?"
+    res = query_pipeline.run({"text_embedder": {"text": query}})
+
+    assert res["retriever"]["documents"][0].content == "There are over 7,000 languages spoken around the world today."
+    ```
+    """  # noqa: E501
+
+    def __init__(
+        self,
+        *,
+        document_store: FAISSDocumentStore,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+        filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+    ):
+        """
+        :param document_store: An instance of `FAISSDocumentStore`.
+        :param filters: Filters applied to the retrieved Documents at initialisation time. At runtime, these are merged
+            with any runtime filters according to the `filter_policy`.
+        :param top_k: Maximum number of Documents to return.
+        :param filter_policy: Policy to determine how init-time and runtime filters are combined.
+            See `FilterPolicy` for details. Defaults to `FilterPolicy.REPLACE`.
+        :raises ValueError: If `document_store` is not an instance of `FAISSDocumentStore`.
+        """
+        if not isinstance(document_store, FAISSDocumentStore):
+            msg = "document_store must be an instance of FAISSDocumentStore"
+            raise ValueError(msg)
+
+        self.document_store = document_store
+        self.filters = filters or {}
+        self.top_k = top_k
+        self.filter_policy = (
+            filter_policy if isinstance(filter_policy, FilterPolicy) else FilterPolicy.from_str(filter_policy)
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serializes the component to a dictionary.
+
+        :returns: Dictionary with serialized data.
+        """
+        return default_to_dict(
+            self,
+            filters=self.filters,
+            top_k=self.top_k,
+            filter_policy=self.filter_policy.value,
+            document_store=self.document_store.to_dict(),
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "FAISSEmbeddingRetriever":
+        """
+        Deserializes the component from a dictionary.
+
+        :param data: Dictionary to deserialize from.
+        :returns: Deserialized component.
+        """
+        doc_store_params = data["init_parameters"]["document_store"]
+        data["init_parameters"]["document_store"] = FAISSDocumentStore.from_dict(doc_store_params)
+        return default_from_dict(cls, data)
+
+    @component.output_types(documents=list[Document])
+    def run(
+        self,
+        query_embedding: list[float],
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[Document]]:
+        """
+        Retrieve documents from the `FAISSDocumentStore`, based on their embeddings.
+
+        :param query_embedding: Embedding of the query.
+        :param filters: Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+                        the `filter_policy` chosen at retriever initialization. See init method docstring for more
+                        details.
+        :param top_k: Maximum number of Documents to return. Overrides the value set at initialization.
+        :returns: A dictionary with the following keys:
+            - `documents`: List of `Document`s that are similar to `query_embedding`.
+        """
+        filters = apply_filter_policy(self.filter_policy, self.filters, filters)
+        top_k = top_k or self.top_k
+        docs = self.document_store.search(query_embedding=query_embedding, top_k=top_k, filters=filters)
+        return {"documents": docs}
+
+    @component.output_types(documents=list[Document])
+    async def run_async(
+        self,
+        query_embedding: list[float],
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[Document]]:
+        """
+        Asynchronously retrieve documents from the `FAISSDocumentStore`, based on their embeddings.
+
+        Since FAISS search is CPU-bound and fully in-memory, this delegates directly to the synchronous
+        `run()` method. No I/O or network calls are involved.
+
+        :param query_embedding: Embedding of the query.
+        :param filters: Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+                        the `filter_policy` chosen at retriever initialization. See init method docstring for more
+                        details.
+        :param top_k: Maximum number of Documents to return. Overrides the value set at initialization.
+        :returns: A dictionary with the following keys:
+            - `documents`: List of `Document`s that are similar to `query_embedding`.
+        """
+        return self.run(query_embedding=query_embedding, filters=filters, top_k=top_k)

haystack_integrations/document_stores/faiss/__init__.py

@@ -0,0 +1,3 @@
+from .document_store import FAISSDocumentStore
+
+__all__ = ["FAISSDocumentStore"]

haystack_integrations/document_stores/faiss/document_store.py

@@ -0,0 +1,578 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+import logging
+from collections.abc import Iterable
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+import faiss  # type: ignore[import-untyped]
+import numpy as np
+from haystack import default_from_dict, default_to_dict
+from haystack.dataclasses import Document
+from haystack.document_stores.errors import DocumentStoreError, DuplicateDocumentError
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.errors import FilterError
+
+logger = logging.getLogger(__name__)
+
+
+class FAISSDocumentStore:
+    """
+    A Document Store using FAISS for vector search and a simple JSON file for metadata storage.
+
+    This Document Store is suitable for small to medium-sized datasets where simplicity is preferred over scalability.
+    It supports basic persistence by saving the FAISS index to a `.faiss` file and documents to a `.json` file.
+    """
+
+    def __init__(
+        self,
+        index_path: str | None = None,
+        index_string: str = "Flat",
+        embedding_dim: int = 768,
+    ):
+        """
+        Initializes the FAISSDocumentStore.
+
+        :param index_path: Path to save/load the index and documents. If None, the store is in-memory only.
+        :param index_string: The FAISS index factory string. Default is "Flat".
+        :param embedding_dim: The dimension of the embeddings. Default is 768.
+        :raises DocumentStoreError: If the FAISS index cannot be initialized.
+        :raises ValueError: If `index_path` points to a missing `.faiss` file when loading persisted data.
+        """
+        self.index_path = index_path
+        self.embedding_dim = embedding_dim
+        self.index_string = index_string
+
+        # Initialize in-memory storage
+        self.documents: dict[str, Document] = {}
+        self.id_map: dict[int, str] = {}  # Map integer IDs (FAISS) to string IDs (Documents)
+        self.inverse_id_map: dict[str, int] = {}  # Map string IDs to integer IDs
+        self._next_id = 0
+
+        # Initialize FAISS index
+        self.index: faiss.Index | None = None
+        if self.index_path and Path(self.index_path).with_suffix(".faiss").exists():
+            self.load(self.index_path)
+        else:
+            self._create_new_index()
+
+    def _create_new_index(self):
+        """Creates a new FAISS index."""
+        try:
+            # We use IndexIDMap to support add_with_ids
+            base_index = faiss.index_factory(self.embedding_dim, self.index_string)
+            self.index = faiss.IndexIDMap(base_index)
+        except RuntimeError as e:
+            msg = f"Could not create FAISS index with factory string '{self.index_string}': {e}"
+            raise DocumentStoreError(msg) from e
+
+    def _get_index_or_raise(self) -> Any:
+        """Return the FAISS index or raise if it is unexpectedly missing."""
+        if self.index is None:
+            msg = "FAISS index has not been initialized."
+            raise DocumentStoreError(msg)
+        return self.index
+
+    def count_documents(self) -> int:
+        """
+        Returns the number of documents in the store.
+        """
+        return len(self.documents)
+
+    def filter_documents(self, filters: dict[str, Any] | None = None) -> list[Document]:
+        """
+        Returns documents that match the provided filters.
+
+        :param filters: A dictionary of filters to apply.
+        :return: A list of matching Documents.
+        :raises FilterError: If the filter structure is invalid.
+        """
+        if not filters:
+            return list(self.documents.values())
+
+        filtered_docs = []
+        for doc in self.documents.values():
+            if self._matches_filters(doc, filters):
+                filtered_docs.append(doc)
+        return filtered_docs
+
+    def _matches_filters(self, doc: Document, filters: dict[str, Any]) -> bool:
+        """
+        Checks if a document matches the given filters.
+
+        Currently, supports simple equality and comparison checks.
+        """
+        return self._check_condition(doc, filters)
+
+    @staticmethod
+    def _get_doc_value(doc: Document, field: str) -> Any:
+        """Helper to get value from doc, handling 'meta.' prefix."""
+        if field == "content":
+            return doc.content
+        if field == "id":
+            return doc.id
+        if field.startswith("meta."):
+            key = field[5:]
+            return doc.meta.get(key)
+        # Fallback: check top level attributes then meta
+        if hasattr(doc, field):
+            return getattr(doc, field)
+        return doc.meta.get(field)
+
+    def write_documents(self, documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.FAIL) -> int:
+        """
+        Writes documents to the store.
+
+        :param documents: The list of documents to write.
+        :param policy: The policy to handle duplicate documents.
+        :return: The number of documents written.
+        :raises ValueError: If `documents` is not an iterable of `Document` objects.
+        :raises DuplicateDocumentError: If a duplicate document is found and `policy` is `DuplicatePolicy.FAIL`.
+        :raises DocumentStoreError: If the FAISS index is unexpectedly unavailable when adding embeddings.
+        """
+        if not isinstance(documents, Iterable) or isinstance(documents, (str, bytes)):
+            msg = "param 'documents' must contain an iterable of objects of type Document."
+            raise ValueError(msg)
+
+        if any(not isinstance(doc, Document) for doc in documents):
+            msg = "param 'documents' must contain an iterable of objects of type Document."
+            raise ValueError(msg)
+
+        if not documents:
+            return 0
+
+        # Check for duplicates first if policy is FAIL
+        if policy == DuplicatePolicy.FAIL:
+            for doc in documents:
+                if doc.id in self.documents:
+                    msg = f"Document with id '{doc.id}' already exists."
+                    raise DuplicateDocumentError(msg)
+
+        # Process documents
+        ids_to_add_to_index = []
+        vectors_to_add = []
+
+        docs_written = 0
+
+        for doc in documents:
+            if policy == DuplicatePolicy.SKIP and doc.id in self.documents:
+                continue
+
+            # Handle overwrite or new
+            if doc.id in self.documents:
+                # If overwriting, we need to remove the old vector from index first?
+                # FAISS doesn't support easy update. We'd have to remove and add.
+                # For MVP, let's implement remove then add for overwrite.
+                self.delete_documents([doc.id])
+
+            self.documents[doc.id] = doc
+
+            if doc.embedding is not None:
+                # Assign a new integer ID
+                int_id = self._next_id
+                self._next_id += 1
+
+                self.id_map[int_id] = doc.id
+                self.inverse_id_map[doc.id] = int_id
+
+                ids_to_add_to_index.append(int_id)
+                vectors_to_add.append(doc.embedding)
+
+            docs_written += 1
+
+        # Add to FAISS
+        if vectors_to_add:
+            vectors = np.array(vectors_to_add, dtype="float32")
+            ids = np.array(ids_to_add_to_index, dtype="int64")
+            index = self._get_index_or_raise()
+            index.add_with_ids(vectors, ids)
+
+        return docs_written
+
+    def delete_documents(self, document_ids: list[str]) -> None:
+        """
+        Deletes documents from the store.
+
+        :raises DocumentStoreError: If the FAISS index is unexpectedly unavailable when removing embeddings.
+        """
+        if not document_ids:
+            return
+
+        ids_to_remove_from_index = []
+
+        for doc_id in document_ids:
+            if doc_id in self.documents:
+                del self.documents[doc_id]
+
+                if doc_id in self.inverse_id_map:
+                    int_id = self.inverse_id_map.pop(doc_id)
+                    del self.id_map[int_id]
+                    ids_to_remove_from_index.append(int_id)
+
+        index = self._get_index_or_raise()
+        if ids_to_remove_from_index and index.ntotal > 0:
+            ids_array = np.array(ids_to_remove_from_index, dtype="int64")
+            index.remove_ids(ids_array)
+
+    def delete_all_documents(self) -> None:
+        """
+        Deletes all documents from the store.
+        """
+        self.documents = {}
+        self.id_map = {}
+        self.inverse_id_map = {}
+        self._next_id = 0
+        self._create_new_index()
+
+    def search(
+        self, query_embedding: list[float], top_k: int = 10, filters: dict[str, Any] | None = None
+    ) -> list[Document]:
+        """
+        Performs a vector search.
+
+        :param query_embedding: The query embedding.
+        :param top_k: The number of results to return.
+        :param filters: Filters to apply.
+        :return: A list of matching Documents.
+        :raises FilterError: If the filter structure is invalid.
+        """
+        if not self.index or self.index.ntotal == 0:
+            return []
+
+        # Ensure embedding format
+        query_vec = np.array([query_embedding], dtype="float32")
+
+        # Search in FAISS
+        # Valid strategy for pre-filtering vs post-filtering:
+        # Since FAISS `IndexIDMap` doesn't support pre-filtering natively comfortably
+        # without `RangeSearch` or specialized impls, we fetch more and filter post-retrieval.
+
+        fetch_k = top_k
+        if filters:
+            fetch_k = min(self.index.ntotal, top_k * 10)  # Simple heuristic
+
+        distances, indices = self.index.search(query_vec, fetch_k)
+
+        results = []
+        for dist, int_id in zip(distances[0], indices[0], strict=False):
+            if int_id == -1:
+                continue
+
+            doc_id = self.id_map.get(int_id)
+            if not doc_id or doc_id not in self.documents:
+                continue
+
+            doc = self.documents[doc_id]
+
+            if filters and not self._matches_filters(doc, filters):
+                continue
+
+            # Build a new instance instead of mutating score in place.
+            score = float(1 / (1 + dist)) if self.index_string == "Flat" else float(dist)
+            result_doc = replace(doc, score=score)
+
+            results.append(result_doc)
+
+            if len(results) >= top_k:
+                break
+
+        return results
+
+    def _check_condition(self, doc: Document, condition: dict[str, Any]) -> bool:
+        if "operator" not in condition and "conditions" not in condition:
+            # This might be a legacy or malformed filter from tests like test_missing_top_level_operator_key
+            # The standard Haystack filter structure enforces keys.
+            # On failure to parse standard structure, we should raise FilterError as per tests?
+            # Actually, looking at the tests (e.g. TestFAISSDocumentStore.test_missing_top_level_operator_key),
+            # they expect FilterError if "operator" is missing from a condition block.
+            msg = "Filter condition missing 'operator'"
+            raise FilterError(msg)
+
+        operator = condition.get("operator", "==")
+
+        if operator == "AND":
+            if "conditions" not in condition:
+                msg = "Missing 'conditions' for AND operator"
+                raise FilterError(msg)
+            return all(self._check_condition(doc, cond) for cond in condition.get("conditions", []))
+        elif operator == "OR":
+            if "conditions" not in condition:
+                msg = "Missing 'conditions' for OR operator"
+                raise FilterError(msg)
+            return any(self._check_condition(doc, cond) for cond in condition.get("conditions", []))
+        elif operator == "NOT":
+            if "conditions" not in condition:
+                msg = "Missing 'conditions' for NOT operator"
+                raise FilterError(msg)
+            conditions = condition.get("conditions")
+            if not isinstance(conditions, list) or not conditions:
+                msg = "NOT operator expects at least one condition"
+                raise FilterError(msg)
+            return not all(self._check_condition(doc, cond) for cond in conditions)
+
+        # Leaf condition
+        if "field" not in condition:
+            msg = "Missing 'field' in filter condition"
+            raise FilterError(msg)
+        field = condition.get("field")
+        if not isinstance(field, str):
+            msg = "'field' in filter condition must be a string"
+            raise FilterError(msg)
+        if "value" not in condition:
+            msg = "Missing 'value' in filter condition"
+            raise FilterError(msg)
+        value = condition.get("value")
+
+        doc_val = FAISSDocumentStore._get_doc_value(doc, field)
+
+        # Type check for comparison operators
+        if operator in [">", ">=", "<", "<="]:
+            if doc_val is None:
+                # Haystack specific: if field is missing/None, and we compare, it generally shouldn't match.
+                return False
+
+            if value is None:
+                # Comparing anything with None using inequalities is invalid,
+                # but tests expect efficient handling (no match)
+                return False
+
+            # Check for compatibility
+            # We allow int/float comparison
+            is_number_doc = isinstance(doc_val, (int, float))
+            is_number_val = isinstance(value, (int, float))
+
+            if is_number_doc and is_number_val:
+                # Compatible
+                pass
+            elif type(doc_val) is not type(value):
+                # Incompatible types for inequality implementation (like str vs int, or list vs int)
+                msg = f"Type mismatch: cannot compare {type(doc_val)} with {type(value)}"
+                raise FilterError(msg)
+
+            try:
+                if operator == ">":
+                    return doc_val > value
+                if operator == ">=":
+                    return doc_val >= value
+                if operator == "<":
+                    return doc_val < value
+                if operator == "<=":
+                    return doc_val <= value
+            except TypeError as e:
+                msg = f"Type mismatch in filter: {e}"
+                raise FilterError(msg) from e
+
+        if operator == "==":
+            return doc_val == value
+        elif operator == "!=":
+            return doc_val != value
+        elif operator == "in":
+            if not isinstance(value, list):
+                msg = "Value for 'in' must be a list"
+                raise FilterError(msg)
+            return doc_val in value
+        elif operator == "not in":
+            if not isinstance(value, list):
+                msg = "Value for 'not in' must be a list"
+                raise FilterError(msg)
+            return doc_val not in value
+
+        return False
+
+    # Mixin implementations
+
+    def delete_by_filter(self, filters: dict[str, Any]) -> int:
+        """
+        Deletes documents that match the provided filters from the store.
+
+        :param filters: A dictionary of filters to apply to find documents to delete.
+        :returns: The number of documents deleted.
+        :raises FilterError: If the filter structure is invalid.
+        :raises DocumentStoreError: If the FAISS index is unexpectedly unavailable when removing embeddings.
+        """
+        docs_to_delete = self.filter_documents(filters)
+        ids = [doc.id for doc in docs_to_delete]
+        self.delete_documents(ids)
+        return len(ids)
+
+    def count_documents_by_filter(self, filters: dict[str, Any]) -> int:
+        """
+        Returns the number of documents that match the provided filters.
+
+        :param filters: A dictionary of filters to apply.
+        :returns: The number of matching documents.
+        :raises FilterError: If the filter structure is invalid.
+        """
+        return len(self.filter_documents(filters))
+
+    def update_by_filter(self, filters: dict[str, Any], meta: dict[str, Any]) -> int:
+        """
+        Updates documents that match the provided filters with the new metadata.
+
+        Note: Updates are performed in-memory only. To persist these changes,
+        you must explicitly call `save()` after updating.
+
+        :param filters: A dictionary of filters to apply to find documents to update.
+        :param meta: A dictionary of metadata key-value pairs to update in the matching documents.
+        :returns: The number of documents updated.
+        :raises FilterError: If the filter structure is invalid.
+        """
+        docs_to_update = self.filter_documents(filters)
+        for doc in docs_to_update:
+            doc.meta.update(meta)
+            # In this dict implementation, it's updated in place in memory.
+        return len(docs_to_update)
+
+    def get_metadata_fields_info(self) -> dict[str, dict[str, Any]]:
+        """
+        Infers and returns the types of all metadata fields from the stored documents.
+
+        :returns: A dictionary mapping field names to dictionaries with a "type" key
+            (e.g. `{"field": {"type": "long"}}`).
+        """
+        fields_idx = {}
+        for doc in self.documents.values():
+            for key, value in doc.meta.items():
+                if key not in fields_idx:
+                    type_name = type(value).__name__
+                    if type_name == "str":
+                        type_name = "keyword"
+                    elif type_name == "int":
+                        type_name = "long"
+                    elif type_name == "bool":
+                        type_name = "boolean"
+                    fields_idx[key] = {"type": type_name}
+        return fields_idx
+
+    def get_metadata_field_min_max(self, field_name: str) -> dict[str, Any]:
+        """
+        Returns the minimum and maximum values for a specific metadata field.
+
+        :param field_name: The name of the metadata field.
+        :returns: A dictionary with keys "min" and "max" containing the respective min and max values.
+        """
+        values = []
+        for doc in self.documents.values():
+            val = (
+                FAISSDocumentStore._get_doc_value(doc, field_name)
+                if not field_name.startswith("meta.")
+                else doc.meta.get(field_name[5:])
+            )
+            if val is not None:
+                values.append(val)
+
+        if not values:
+            return {"min": None, "max": None}
+
+        return {"min": min(values), "max": max(values)}
+
+    def get_metadata_field_unique_values(self, field_name: str) -> list[Any]:
+        """
+        Returns all unique values for a specific metadata field.
+
+        :param field_name: The name of the metadata field.
+        :returns: A list of unique values for the specified field.
+        """
+        values = set()
+        for doc in self.documents.values():
+            val = (
+                FAISSDocumentStore._get_doc_value(doc, field_name)
+                if not field_name.startswith("meta.")
+                else doc.meta.get(field_name[5:])
+            )
+            if val is not None:
+                values.add(val)
+        return list(values)
+
+    def count_unique_metadata_by_filter(self, filters: dict[str, Any], fields: list[str]) -> dict[str, int]:
+        """
+        Returns a count of unique values for multiple metadata fields, optionally scoped by a filter.
+
+        :param filters: A dictionary of filters to apply.
+        :param fields: A list of metadata field names to count unique values for.
+        :returns: A dictionary mapping each field name to the count of its unique values.
+        """
+        filtered_docs = self.filter_documents(filters)
+        counts = {}
+
+        for field in fields:
+            unique_vals = set()
+            for doc in filtered_docs:
+                val = FAISSDocumentStore._get_doc_value(doc, field)
+                if val is not None:
+                    unique_vals.add(val)
+            counts[field] = len(unique_vals)
+
+        return dict(counts)
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serializes the store to a dictionary.
+        """
+        return default_to_dict(
+            self,
+            index_path=self.index_path,
+            index_string=self.index_string,
+            embedding_dim=self.embedding_dim,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "FAISSDocumentStore":
+        """
+        Deserializes the store from a dictionary.
+        """
+        return default_from_dict(cls, data)
+
+    def save(self, index_path: str | Path) -> None:
+        """
+        Saves the index and documents to disk.
+
+        :raises DocumentStoreError: If the FAISS index is unexpectedly unavailable.
+        """
+        path = Path(index_path)
+        faiss.write_index(self._get_index_or_raise(), str(path.with_suffix(".faiss")))
+
+        # Save documents and ID mapping
+        data = {
+            "documents": [doc.to_dict() for doc in self.documents.values()],
+            "id_map": self.id_map,
+            "inverse_id_map": self.inverse_id_map,
+            "next_id": self._next_id,
+        }
+
+        with open(path.with_suffix(".json"), "w", encoding="utf-8") as f:
+            json.dump(data, f)
+
+    def load(self, index_path: str | Path) -> None:
+        """
+        Loads the index and documents from disk.
+
+        :raises ValueError: If the `.faiss` file does not exist.
+        """
+        path = Path(index_path)
+        if not path.with_suffix(".faiss").exists():
+            msg = f"File not found: {path.with_suffix('.faiss')}"
+            raise ValueError(msg)
+
+        self.index = faiss.read_index(str(path.with_suffix(".faiss")))
+
+        with open(path.with_suffix(".json"), encoding="utf-8") as f:
+            data = json.load(f)
+
+        self.documents = {doc_dict["id"]: Document.from_dict(doc_dict) for doc_dict in data["documents"]}
+        self.id_map = {int(k): v for k, v in data["id_map"].items()}
+        # inverse_id_map keys are strings, values are ints. JSON keys are strings.
+        self.inverse_id_map = data["inverse_id_map"]
+        self._next_id = data["next_id"]
+
+        # Verify sync
+        if len(self.documents) != len(self.id_map):
+            logger.warning(
+                "Loaded %d documents but %d ID mappings. Index might be out of sync.",
+                len(self.documents),
+                len(self.id_map),
+            )