Skip to content

Build and run agents you can see, understand and trust.

35.8 KB
Raw Blame
# -*- coding: utf-8 -*-
"""Unit tests for the QdrantStore class."""
from contextlib import AsyncExitStack
from importlib.util import find_spec
from tempfile import TemporaryDirectory
from types import SimpleNamespace
from unittest import skipUnless
from unittest.async_case import IsolatedAsyncioTestCase
from unittest.mock import AsyncMock, patch

from utils import AnyString

from agentscope.message import TextBlock
from agentscope.rag import (
    Chunk,
    KnowledgeBase,
    QdrantStore,
    VectorRecord,
    VectorSearchResult,
)


def _knowledge_base(
    store: QdrantStore,
    metadata_filter: dict | None,
) -> KnowledgeBase:
    """Bind a handle without needing an embedding request for deletion."""
    return KnowledgeBase(
        name="test",
        description="Test knowledge base",
        embedding_model=SimpleNamespace(dimensions=3),
        vector_store=store,
        collection="shared",
        metadata_filter=metadata_filter,
    )


class _LegacyStore(QdrantStore):
    """Custom backend using the original, unscoped delete signature."""

    async def delete(self, collection: str, document_id: str) -> None:
        """Record deletions so a rejected scoped call cannot mutate data."""
        await self.get_client().delete(collection, document_id)


def _dump_results(results: list[VectorSearchResult]) -> list[dict]:
    """Convert search results into plain dicts for whole-structure
    comparison.

    Args:
        results (`list[VectorSearchResult]`):
            The search results to convert.

    Returns:
        `list[dict]`:
            The results as plain dicts.
    """
    return [result.model_dump() for result in results]


def _make_record(
    text: str,
    vector: list[float],
    document_id: str,
    chunk_index: int = 0,
    total_chunks: int = 1,
) -> VectorRecord:
    """Build a VectorRecord for testing.

    Args:
        text (`str`):
            The chunk text content.
        vector (`list[float]`):
            The embedding vector.
        document_id (`str`):
            The ID of the source document the record belongs to.
        chunk_index (`int`, defaults to ``0``):
            The chunk index within the document.
        total_chunks (`int`, defaults to ``1``):
            The total number of chunks in the document.

    Returns:
        `VectorRecord`:
            The constructed record.
    """
    return VectorRecord(
        vector=vector,
        document_id=document_id,
        chunk=Chunk(
            content=TextBlock(text=text),
            source=f"{document_id}.txt",
            chunk_index=chunk_index,
            total_chunks=total_chunks,
        ),
    )


class QdrantMetricTest(IsolatedAsyncioTestCase):
    """Real collection metadata determines search score semantics."""

    async def asyncSetUp(self) -> None:
        """Create an in-memory Qdrant store before each test."""
        self._exit_stack = AsyncExitStack()
        self.store = await self._exit_stack.enter_async_context(
            QdrantStore(location=":memory:"),
        )

    async def asyncTearDown(self) -> None:
        """Close the store after each test."""
        await self._exit_stack.aclose()

    async def test_existing_collection_metric_controls_ranking(self) -> None:
        """Reopened collections retain distance ranking and thresholds."""

        class QueryEmbedding:
            """Return the fixed query vector without a model service."""

            dimensions = 3
            supports_multimodal = False

            async def __call__(self, queries: list) -> SimpleNamespace:
                return SimpleNamespace(
                    embeddings=[[1.0, 0.0, 0.0] for _ in queries],
                )

        for metric in ("Euclid", "Manhattan"):
            with self.subTest(metric=metric), TemporaryDirectory() as path:
                async with QdrantStore(path=path, distance=metric) as writer:
                    await writer.create_collection("existing", dimensions=3)
                    await writer.insert(
                        "existing",
                        [
                            _make_record(name, [value, 0.0, 0.0], name)
                            for name, value in (
                                ("exact", 1.0),
                                ("near", 2.0),
                                ("far", 11.0),
                            )
                        ],
                    )
                # The default is a creation option, not the existing metric.
                async with QdrantStore(path=path) as reader:
                    kb = KnowledgeBase(
                        name="existing",
                        description="Existing distance collection",
                        embedding_model=QueryEmbedding(),
                        vector_store=reader,
                        collection="existing",
                    )
                    hits = await kb.search(["query"], top_k=3)
                    self.assertEqual(
                        [(hit.document_id, hit.score) for hit in hits],
                        [("exact", 0.0), ("near", -1.0), ("far", -10.0)],
                    )
                    filtered = await kb.search(
                        ["query"],
                        top_k=3,
                        score_threshold=-1.0,
                    )
                    self.assertEqual(
                        [hit.document_id for hit in filtered],
                        ["exact", "near"],
                    )

    async def test_metric_tracks_external_collection_recreation(self) -> None:
        """A live store does not retain a deleted collection's old metric."""
        from qdrant_client import models

        client = self.store.get_client()
        for metric, expected in (("Euclid", -1.0), ("Dot", 2.0)):
            with self.subTest(metric=metric):
                await client.create_collection(
                    "recreated",
                    vectors_config=models.VectorParams(
                        size=3,
                        distance=metric,
                    ),
                )
                try:
                    await self.store.insert(
                        "recreated",
                        [_make_record("near", [2.0, 0.0, 0.0], "near")],
                    )
                    hits = await self.store.search(
                        "recreated",
                        [1.0, 0.0, 0.0],
                    )
                    self.assertEqual(hits[0].score, expected)
                finally:
                    await client.delete_collection("recreated")

    async def test_default_dense_vector_in_named_config(self) -> None:
        """The empty vector name is Qdrant's default query target."""
        from qdrant_client import models

        client = self.store.get_client()
        await client.create_collection(
            "default-named",
            vectors_config={
                "": models.VectorParams(size=3, distance="Euclid"),
                "named": models.VectorParams(size=3, distance="Dot"),
            },
        )
        record = _make_record("near", [2.0, 0.0, 0.0], "near")
        await client.upsert(
            "default-named",
            points=[
                models.PointStruct(
                    id=1,
                    vector={"": record.vector},
                    payload={
                        "document_id": record.document_id,
                        "chunk": record.chunk.model_dump(mode="json"),
                    },
                ),
            ],
        )
        hits = await self.store.search("default-named", [1.0, 0.0, 0.0])
        self.assertEqual(hits[0].score, -1.0)


class QdrantStoreTest(IsolatedAsyncioTestCase):
    """The test cases for the QdrantStore class."""

    async def asyncSetUp(self) -> None:
        """Create an in-memory Qdrant store before each test."""
        self._exit_stack = AsyncExitStack()
        self.store = await self._exit_stack.enter_async_context(
            QdrantStore(location=":memory:"),
        )

    async def asyncTearDown(self) -> None:
        """Close the store after each test."""
        await self._exit_stack.aclose()

    async def test_collection_lifecycle(self) -> None:
        """Collections can be created, checked, and deleted."""
        self.assertEqual(await self.store.has_collection("kb-1"), False)

        await self.store.create_collection("kb-1", dimensions=3)
        self.assertEqual(await self.store.has_collection("kb-1"), True)

        # Creating an existing collection is a no-op
        await self.store.create_collection("kb-1", dimensions=3)
        self.assertEqual(await self.store.has_collection("kb-1"), True)

        await self.store.delete_collection("kb-1")
        self.assertEqual(await self.store.has_collection("kb-1"), False)

    async def test_insert_and_search(self) -> None:
        """Inserted records are searchable, ordered by similarity."""
        await self.store.create_collection("kb-1", dimensions=3)
        await self.store.insert(
            "kb-1",
            [
                _make_record(
                    "Hello world!",
                    [1.0, 0.0, 0.0],
                    document_id="doc-1",
                    chunk_index=0,
                    total_chunks=2,
                ),
                _make_record(
                    "Goodbye world!",
                    [0.0, 1.0, 0.0],
                    document_id="doc-1",
                    chunk_index=1,
                    total_chunks=2,
                ),
            ],
        )

        results = await self.store.search(
            "kb-1",
            query_vector=[1.0, 0.0, 0.0],
            top_k=2,
        )

        self.assertEqual(
            _dump_results(results),
            [
                {
                    "score": 1.0,
                    "document_id": "doc-1",
                    "chunk": {
                        "content": {
                            "type": "text",
                            "text": "Hello world!",
                            "id": AnyString(),
                            "created_at": AnyString(),
                            "finished_at": None,
                        },
                        "source": "doc-1.txt",
                        "chunk_index": 0,
                        "total_chunks": 2,
                        "metadata": {},
                    },
                },
                {
                    "score": 0.0,
                    "document_id": "doc-1",
                    "chunk": {
                        "content": {
                            "type": "text",
                            "text": "Goodbye world!",
                            "id": AnyString(),
                            "created_at": AnyString(),
                            "finished_at": None,
                        },
                        "source": "doc-1.txt",
                        "chunk_index": 1,
                        "total_chunks": 2,
                        "metadata": {},
                    },
                },
            ],
        )

    async def test_search_negates_distance_metric_scores(self) -> None:
        """A distance metric yields higher-is-better scores too."""
        store = await self._exit_stack.enter_async_context(
            QdrantStore(location=":memory:", distance="Euclid"),
        )
        await store.create_collection("kb-1", dimensions=3)
        await store.insert(
            "kb-1",
            [
                _make_record("Near!", [1.0, 0.0, 0.0], document_id="doc-1"),
                _make_record("Far!", [10.0, 0.0, 0.0], document_id="doc-2"),
            ],
        )

        results = await store.search(
            "kb-1",
            query_vector=[0.0, 0.0, 0.0],
            top_k=2,
        )

        # Negated distances, so the nearest record still ranks first
        self.assertEqual(
            _dump_results(results),
            [
                {
                    "score": -1.0,
                    "document_id": "doc-1",
                    "chunk": {
                        "content": {
                            "type": "text",
                            "text": "Near!",
                            "id": AnyString(),
                            "created_at": AnyString(),
                            "finished_at": None,
                        },
                        "source": "doc-1.txt",
                        "chunk_index": 0,
                        "total_chunks": 1,
                        "metadata": {},
                    },
                },
                {
                    "score": -10.0,
                    "document_id": "doc-2",
                    "chunk": {
                        "content": {
                            "type": "text",
                            "text": "Far!",
                            "id": AnyString(),
                            "created_at": AnyString(),
                            "finished_at": None,
                        },
                        "source": "doc-2.txt",
                        "chunk_index": 0,
                        "total_chunks": 1,
                        "metadata": {},
                    },
                },
            ],
        )

    async def test_search_top_k(self) -> None:
        """top_k limits the number of returned results."""
        await self.store.create_collection("kb-1", dimensions=3)
        await self.store.insert(
            "kb-1",
            [
                _make_record("A", [1.0, 0.0, 0.0], document_id="doc-1"),
                _make_record("B", [0.9, 0.1, 0.0], document_id="doc-2"),
                _make_record("C", [0.0, 0.0, 1.0], document_id="doc-3"),
            ],
        )

        results = await self.store.search(
            "kb-1",
            query_vector=[1.0, 0.0, 0.0],
            top_k=1,
        )

        self.assertEqual(
            _dump_results(results),
            [
                {
                    "score": 1.0,
                    "document_id": "doc-1",
                    "chunk": {
                        "content": {
                            "type": "text",
                            "text": "A",
                            "id": AnyString(),
                            "created_at": AnyString(),
                            "finished_at": None,
                        },
                        "source": "doc-1.txt",
                        "chunk_index": 0,
                        "total_chunks": 1,
                        "metadata": {},
                    },
                },
            ],
        )

    async def test_delete_by_document_id(self) -> None:
        """delete removes all records of one document only."""
        await self.store.create_collection("kb-1", dimensions=3)
        await self.store.insert(
            "kb-1",
            [
                _make_record(
                    "doc1-chunk0",
                    [1.0, 0.0, 0.0],
                    document_id="doc-1",
                    chunk_index=0,
                    total_chunks=2,
                ),
                _make_record(
                    "doc1-chunk1",
                    [0.9, 0.1, 0.0],
                    document_id="doc-1",
                    chunk_index=1,
                    total_chunks=2,
                ),
                _make_record(
                    "doc2-chunk0",
                    [0.0, 1.0, 0.0],
                    document_id="doc-2",
                ),
            ],
        )

        await self.store.delete("kb-1", document_id="doc-1")

        results = await self.store.search(
            "kb-1",
            query_vector=[1.0, 0.0, 0.0],
            top_k=5,
        )

        self.assertEqual(
            _dump_results(results),
            [
                {
                    "score": 0.0,
                    "document_id": "doc-2",
                    "chunk": {
                        "content": {
                            "type": "text",
                            "text": "doc2-chunk0",
                            "id": AnyString(),
                            "created_at": AnyString(),
                            "finished_at": None,
                        },
                        "source": "doc-2.txt",
                        "chunk_index": 0,
                        "total_chunks": 1,
                        "metadata": {},
                    },
                },
            ],
        )

    async def test_insert_empty_records(self) -> None:
        """Inserting an empty record list is a no-op."""
        await self.store.create_collection("kb-1", dimensions=3)
        await self.store.insert("kb-1", [])

        results = await self.store.search(
            "kb-1",
            query_vector=[1.0, 0.0, 0.0],
        )

        self.assertEqual(_dump_results(results), [])

    async def test_list_documents_aggregates_by_document_id(self) -> None:
        """list_documents groups chunks by document_id."""
        await self.store.create_collection("kb-1", dimensions=3)

        def _record_with_metadata(
            text: str,
            document_id: str,
            metadata: dict,
            chunk_index: int = 0,
            total_chunks: int = 1,
        ) -> VectorRecord:
            return VectorRecord(
                vector=[1.0, 0.0, 0.0],
                document_id=document_id,
                chunk=Chunk(
                    content=TextBlock(text=text),
                    source=metadata.get("filename", f"{document_id}.txt"),
                    chunk_index=chunk_index,
                    total_chunks=total_chunks,
                    metadata=metadata,
                ),
            )

        await self.store.insert(
            "kb-1",
            [
                _record_with_metadata(
                    "A",
                    "doc-1",
                    {"filename": "alpha.txt", "media_type": "text/plain"},
                    0,
                    2,
                ),
                _record_with_metadata(
                    "B",
                    "doc-1",
                    {"filename": "alpha.txt", "media_type": "text/plain"},
                    1,
                    2,
                ),
                _record_with_metadata(
                    "C",
                    "doc-2",
                    {"filename": "beta.md", "media_type": "text/markdown"},
                    0,
                    1,
                ),
            ],
        )

        summaries = await self.store.list_documents("kb-1")
        summaries_by_id = {s.document_id: s for s in summaries}

        self.assertEqual(set(summaries_by_id), {"doc-1", "doc-2"})
        self.assertEqual(summaries_by_id["doc-1"].chunk_count, 2)
        self.assertEqual(summaries_by_id["doc-1"].source, "alpha.txt")
        self.assertEqual(
            summaries_by_id["doc-1"].metadata,
            {"filename": "alpha.txt", "media_type": "text/plain"},
        )
        self.assertEqual(summaries_by_id["doc-2"].chunk_count, 1)
        self.assertEqual(summaries_by_id["doc-2"].source, "beta.md")

    async def test_search_metadata_filter(self) -> None:
        """search applies the metadata_filter as a payload predicate."""
        await self.store.create_collection("kb-1", dimensions=3)

        def _record(
            text: str,
            document_id: str,
            kb_scope: str,
        ) -> VectorRecord:
            return VectorRecord(
                vector=[1.0, 0.0, 0.0],
                document_id=document_id,
                chunk=Chunk(
                    content=TextBlock(text=text),
                    source=f"{document_id}.txt",
                    chunk_index=0,
                    total_chunks=1,
                    metadata={"kb_scope": kb_scope},
                ),
            )

        await self.store.insert(
            "kb-1",
            [
                _record("A", "doc-1", "kb-a"),
                _record("B", "doc-2", "kb-b"),
            ],
        )

        results = await self.store.search(
            "kb-1",
            query_vector=[1.0, 0.0, 0.0],
            top_k=5,
            metadata_filter={"kb_scope": "kb-a"},
        )
        self.assertEqual([r.document_id for r in results], ["doc-1"])

        results = await self.store.search(
            "kb-1",
            query_vector=[1.0, 0.0, 0.0],
            top_k=5,
            metadata_filter={"kb_scope": "kb-b"},
        )
        self.assertEqual([r.document_id for r in results], ["doc-2"])

    async def test_null_metadata_filters(self) -> None:
        """Null means an explicit null, and composes with other predicates."""
        await self.store.create_collection("kb-null", dimensions=3)
        records = []
        for index, metadata in enumerate(
            [
                {"reviewer": None, "scope": "a"},
                {"scope": "a"},
                {"reviewer": "", "scope": "a"},
                {"reviewer": False, "scope": "a"},
                {"reviewer": 0, "scope": "a"},
                {"reviewer": "None", "scope": "a"},
                {"reviewer": None, "scope": "b"},
            ],
        ):
            record = _make_record("text", [1.0, 0.0, 0.0], f"doc-{index}")
            record.chunk.metadata = metadata
            records.append(record)
        await self.store.insert("kb-null", records)
        metadata_filter = {"reviewer": None, "scope": "a"}
        results = await self.store.search(
            "kb-null",
            [1.0, 0.0, 0.0],
            top_k=10,
            metadata_filter=metadata_filter,
        )
        self.assertEqual(
            _dump_results(results),
            [
                {
                    "score": 1.0,
                    "document_id": "doc-0",
                    "chunk": records[0].chunk.model_dump(),
                },
            ],
        )
        documents = await self.store.list_documents(
            "kb-null",
            metadata_filter=metadata_filter,
        )
        self.assertEqual(
            [document.model_dump() for document in documents],
            [
                {
                    "document_id": "doc-0",
                    "source": "doc-0.txt",
                    "chunk_count": 1,
                    "metadata": metadata_filter,
                },
            ],
        )
        for index, record in enumerate(records):
            with self.subTest(document_id=record.document_id):
                chunks = await self.store.list_chunks(
                    "kb-null",
                    record.document_id,
                    metadata_filter=metadata_filter,
                )
                self.assertEqual(
                    [chunk.model_dump() for chunk in chunks],
                    [record.chunk.model_dump()] if index == 0 else [],
                )

    async def test_float_metadata_filters(self) -> None:
        """Every read operation matches finite floats without rounding."""
        await self.store.create_collection("kb-1", dimensions=3)
        values = [-0.75, 0.0, 0.75]
        records = []
        for index, value in enumerate(values):
            record = _make_record(
                f"note-{index}",
                [1.0, 0.0, 0.0],
                "doc-1",
                chunk_index=index,
                total_chunks=len(values),
            )
            record.chunk.metadata["confidence"] = value
            records.append(record)
        await self.store.insert("kb-1", records)

        for index, value in enumerate(values):
            metadata_filter = {"confidence": value}
            with self.subTest(operation="search", value=value):
                results = await self.store.search(
                    "kb-1",
                    [1.0, 0.0, 0.0],
                    metadata_filter=metadata_filter,
                )
                self.assertEqual(
                    [result.chunk.chunk_index for result in results],
                    [index],
                )
            with self.subTest(operation="list_documents", value=value):
                documents = await self.store.list_documents(
                    "kb-1",
                    metadata_filter=metadata_filter,
                )
                self.assertEqual(
                    [(doc.document_id, doc.chunk_count) for doc in documents],
                    [("doc-1", 1)],
                )
                self.assertEqual(documents[0].metadata, metadata_filter)
            with self.subTest(operation="list_chunks", value=value):
                chunks = await self.store.list_chunks(
                    "kb-1",
                    "doc-1",
                    metadata_filter=metadata_filter,
                )
                self.assertEqual(
                    [chunk.chunk_index for chunk in chunks],
                    [index],
                )

    async def test_mixed_scalar_metadata_filter(self) -> None:
        """Combine float equality with the existing scalar match types."""
        await self.store.create_collection("kb-1", dimensions=3)
        metadata_filter = {
            "confidence": 0.75,
            "category": "notes",
            "version": 2,
            "active": True,
        }
        records = []
        for index, metadata in enumerate(
            [
                metadata_filter,
                {**metadata_filter, "confidence": 0.5},
                {**metadata_filter, "category": "other"},
                {**metadata_filter, "version": 3},
                {**metadata_filter, "active": False},
            ],
        ):
            record = _make_record(
                f"note-{index}",
                [1.0, 0.0, 0.0],
                f"doc-{index}",
            )
            record.chunk.metadata.update(metadata)
            records.append(record)
        await self.store.insert("kb-1", records)

        results = await self.store.search(
            "kb-1",
            [1.0, 0.0, 0.0],
            metadata_filter=metadata_filter,
        )
        self.assertEqual([result.document_id for result in results], ["doc-0"])

    async def test_nonfinite_metadata_filter(self) -> None:
        """Reject non-finite floats instead of widening a query."""
        await self.store.create_collection("kb-1", dimensions=3)
        for value in [float("nan"), float("inf"), float("-inf")]:
            with self.subTest(value=value):
                with self.assertRaisesRegex(ValueError, "finite"):
                    await self.store.search(
                        "kb-1",
                        [1.0, 0.0, 0.0],
                        metadata_filter={"confidence": value},
                    )

    async def test_list_chunks_pagination_and_isolation(self) -> None:
        """list_chunks pages by chunk_index and isolates documents."""
        await self.store.create_collection("kb-1", dimensions=3)
        records = [
            _make_record(
                f"doc1-chunk{i}",
                [1.0, 0.0, 0.0],
                document_id="doc-1",
                chunk_index=i,
                total_chunks=5,
            )
            # Insert out of order to prove ordering is restored.
            for i in (3, 0, 4, 1, 2)
        ] + [
            _make_record(
                f"doc2-chunk{i}",
                [0.0, 1.0, 0.0],
                document_id="doc-2",
                chunk_index=i,
                total_chunks=2,
            )
            for i in (1, 0)
        ]
        await self.store.insert("kb-1", records)

        page = await self.store.list_chunks(
            "kb-1",
            "doc-1",
            offset=0,
            limit=3,
        )
        self.assertEqual([c.chunk_index for c in page], [0, 1, 2])
        self.assertEqual(
            [c.content.text for c in page],
            ["doc1-chunk0", "doc1-chunk1", "doc1-chunk2"],
        )

        tail = await self.store.list_chunks(
            "kb-1",
            "doc-1",
            offset=3,
            limit=30,
        )
        self.assertEqual([c.chunk_index for c in tail], [3, 4])

        self.assertEqual(
            await self.store.list_chunks("kb-1", "doc-1", offset=5, limit=3),
            [],
        )
        self.assertEqual(
            await self.store.list_chunks("kb-1", "doc-1", limit=0),
            [],
        )

        other = await self.store.list_chunks("kb-1", "doc-2", limit=30)
        self.assertEqual([c.chunk_index for c in other], [0, 1])
        self.assertTrue(
            all(c.content.text.startswith("doc2") for c in other),
        )

    async def test_list_chunks_metadata_filter(self) -> None:
        """list_chunks applies the metadata_filter tenant scoping."""
        await self.store.create_collection("kb-1", dimensions=3)
        record = _make_record(
            "scoped",
            [1.0, 0.0, 0.0],
            document_id="doc-1",
        )
        record.chunk.metadata["kb_scope"] = "kb-a"
        await self.store.insert("kb-1", [record])

        hit = await self.store.list_chunks(
            "kb-1",
            "doc-1",
            metadata_filter={"kb_scope": "kb-a"},
        )
        self.assertEqual(len(hit), 1)

        miss = await self.store.list_chunks(
            "kb-1",
            "doc-1",
            metadata_filter={"kb_scope": "kb-b"},
        )
        self.assertEqual(miss, [])

    async def test_list_chunks_deduplicates_reindex_duplicates(self) -> None:
        """Re-indexing the same document never duplicates or drops chunks.

        Stable record IDs make the second insert an in-place upsert; and
        even against legacy duplicate rows the listing deduplicates by
        ``chunk_index``, so a page is never ``[1, 2, 3, 3, 4]``.
        """
        await self.store.create_collection("kb-1", dimensions=3)
        records = [
            _make_record(
                f"chunk{i}",
                [1.0, 0.0, 0.0],
                document_id="doc-1",
                chunk_index=i,
                total_chunks=5,
            )
            for i in range(5)
        ]
        # Simulate the index worker crashing after the vector insert
        # and retrying the whole pipeline.
        await self.store.insert("kb-1", records)
        await self.store.insert("kb-1", records)

        page = await self.store.list_chunks(
            "kb-1",
            "doc-1",
            offset=0,
            limit=5,
        )
        self.assertEqual([c.chunk_index for c in page], [0, 1, 2, 3, 4])

        window = await self.store.list_chunks(
            "kb-1",
            "doc-1",
            offset=1,
            limit=3,
        )
        self.assertEqual([c.chunk_index for c in window], [1, 2, 3])

    async def test_list_chunks_after_reindexing_into_fewer_chunks(
        self,
    ) -> None:
        """A shorter re-index leaves no tail from the previous run.

        The worker deletes a document's vectors before re-inserting, so
        even though upserts alone would keep the old high indices, the
        listing reflects only the latest run.
        """
        await self.store.create_collection("kb-1", dimensions=3)

        def _records(count: int) -> list:
            return [
                _make_record(
                    f"v{count}-chunk{i}",
                    [1.0, 0.0, 0.0],
                    document_id="doc-1",
                    chunk_index=i,
                    total_chunks=count,
                )
                for i in range(count)
            ]

        await self.store.insert("kb-1", _records(5))
        await self.store.delete("kb-1", "doc-1")
        await self.store.insert("kb-1", _records(2))

        chunks = await self.store.list_chunks("kb-1", "doc-1", limit=30)
        self.assertEqual([c.chunk_index for c in chunks], [0, 1])
        self.assertEqual(
            [c.content.text for c in chunks],
            ["v2-chunk0", "v2-chunk1"],
        )


class LegacyDeleteTest(IsolatedAsyncioTestCase):
    """Old custom backends still work without a scope and fail closed."""

    async def test_legacy_backend_without_scope(self) -> None:
        """No metadata keyword is sent when the handle has no scope."""
        for scope in (None, {}):
            with self.subTest(scope=scope):
                store = _LegacyStore()
                client = SimpleNamespace(delete=AsyncMock())
                with (
                    patch.object(store, "has_collection", return_value=True),
                    patch.object(store, "get_client", return_value=client),
                ):
                    await _knowledge_base(store, scope).delete_document("doc")
                client.delete.assert_awaited_once_with("shared", "doc")

    async def test_legacy_backend_with_scope(self) -> None:
        """An unsupported scope is rejected before deleting anything."""
        store = _LegacyStore()
        client = SimpleNamespace(delete=AsyncMock())
        with (
            patch.object(store, "has_collection", return_value=True),
            patch.object(store, "get_client", return_value=client),
        ):
            with self.assertRaises(TypeError):
                await _knowledge_base(
                    store,
                    {"tenant": "alpha"},
                ).delete_document("doc")
        client.delete.assert_not_awaited()


@skipUnless(find_spec("qdrant_client"), "qdrant-client is required")
class QdrantScopedDeleteTest(IsolatedAsyncioTestCase):
    """Verify isolation against the real, in-memory Qdrant backend."""

    async def asyncSetUp(self) -> None:
        """Insert chunks spanning documents and two independent scope keys."""
        self._exit_stack = AsyncExitStack()
        self.store = await self._exit_stack.enter_async_context(
            QdrantStore(location=":memory:"),
        )
        await self.store.create_collection("shared", dimensions=3)
        self.scope = {"tenant": "alpha", "project": 2}
        records = []
        for document_id, index, metadata in (
            ("shared-doc", 0, self.scope),
            ("shared-doc", 1, {"tenant": "beta", "project": 2}),
            ("shared-doc", 2, {"tenant": "alpha", "project": 3}),
            ("alpha-doc", 0, self.scope),
            ("beta-doc", 0, {"tenant": "beta", "project": 2}),
        ):
            records.append(
                VectorRecord(
                    vector=[1.0, 0.0, 0.0],
                    document_id=document_id,
                    chunk=Chunk(
                        content=TextBlock(text=f"{document_id}-{index}"),
                        source=f"{document_id}.txt",
                        chunk_index=index,
                        total_chunks=3,
                        metadata=metadata,
                    ),
                ),
            )
        await self.store.insert("shared", records)

    async def asyncTearDown(self) -> None:
        """Release the ephemeral client."""
        await self._exit_stack.aclose()

    async def test_foreign_document_is_unchanged(self) -> None:
        """A scoped handle cannot remove an invisible foreign document."""
        before = await self.store.list_chunks("shared", "beta-doc")
        await _knowledge_base(self.store, self.scope).delete_document(
            "beta-doc",
        )
        after = await self.store.list_chunks("shared", "beta-doc")
        self.assertEqual(before, after)
        self.assertEqual(len(after), 1)

    async def test_delete_requires_document_and_every_scope_field(
        self,
    ) -> None:
        """Delete only chunks matching both the document and all scope keys."""
        await _knowledge_base(self.store, self.scope).delete_document(
            "shared-doc",
        )
        chunks = await self.store.list_chunks("shared", "shared-doc")
        self.assertEqual([chunk.chunk_index for chunk in chunks], [1, 2])
        self.assertEqual(
            len(await self.store.list_chunks("shared", "alpha-doc")),
            1,
        )
        await _knowledge_base(self.store, self.scope).delete_document(
            "alpha-doc",
        )
        self.assertEqual(
            await self.store.list_chunks("shared", "alpha-doc"),
            [],
        )

    async def test_unscoped_handle_deletes_all_document_chunks(self) -> None:
        """The default handle deletes documents across the whole collection."""
        await _knowledge_base(self.store, None).delete_document("shared-doc")
        self.assertEqual(
            await self.store.list_chunks("shared", "shared-doc"),
            [],
        )
        self.assertEqual(len(await self.store.list_documents("shared")), 2)