Skip to content

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

32.4 KB
Raw Blame
# -*- coding: utf-8 -*-
# pylint: disable=protected-access,missing-function-docstring
"""Unit tests for the MongoDBStore class (mocked pymongo backend)."""
from __future__ import annotations

import math
from contextlib import AsyncExitStack
from types import SimpleNamespace
from typing import Any
from unittest.async_case import IsolatedAsyncioTestCase
from unittest.mock import AsyncMock, Mock, patch

from utils import AnyString

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


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,
        ),
    )


def _cosine_similarity(a: list[float], b: list[float]) -> float:
    """Cosine similarity aligned with Qdrant cosine scoring in tests."""
    dot = sum(x * y for x, y in zip(a, b, strict=True))
    norm_a = math.sqrt(sum(x * x for x in a))
    norm_b = math.sqrt(sum(x * x for x in b))
    if norm_a == 0.0 or norm_b == 0.0:
        return 0.0
    return dot / (norm_a * norm_b)


class _FakeAsyncIterator:
    """Minimal async iterator for mocked MongoDB cursors."""

    def __init__(self, items: list[Any]) -> None:
        self._items = items
        self._index = 0

    def __aiter__(self) -> "_FakeAsyncIterator":
        return self

    async def __anext__(self) -> Any:
        if self._index >= len(self._items):
            raise StopAsyncIteration
        item = self._items[self._index]
        self._index += 1
        return item


def _read_dotted(doc: dict[str, Any], path: str) -> Any:
    """Read a dotted path (e.g. ``chunk.chunk_index``) from a dict."""
    value: Any = doc
    for part in path.split("."):
        if not isinstance(value, dict):
            return None
        value = value.get(part)
    return value


class _FakeFindCursor:
    """Chainable find cursor supporting sort / skip / limit."""

    def __init__(self, documents: list[dict[str, Any]]) -> None:
        self._documents = documents

    def sort(self, key: str, direction: int) -> "_FakeFindCursor":
        """Sort documents by a dotted key path."""
        self._documents = sorted(
            self._documents,
            key=lambda doc: _read_dotted(doc, key),
            reverse=direction < 0,
        )
        return self

    def skip(self, count: int) -> "_FakeFindCursor":
        """Skip the first ``count`` documents."""
        self._documents = self._documents[count:]
        return self

    def limit(self, count: int) -> "_FakeFindCursor":
        """Keep at most ``count`` documents."""
        self._documents = self._documents[:count]
        return self

    def __aiter__(self) -> _FakeAsyncIterator:
        return _FakeAsyncIterator(list(self._documents))


class _FakeMongoCollection:
    """In-memory collection that implements the async API MongoDBStore uses."""

    def __init__(self, database: "_FakeMongoDatabase", name: str) -> None:
        self._database = database
        self._name = name
        self._docs: dict[str, dict[str, Any]] = {}
        self._index_queryable = False

    def find(
        self,
        filter_doc: dict[str, Any],
        projection: dict[str, Any] | None = None,
    ) -> "_FakeFindCursor":
        """Return a chainable cursor over matching documents."""
        del projection  # the fake returns whole documents regardless
        matched = [
            doc
            for doc in self._docs.values()
            if all(
                _read_dotted(doc, key)
                == (
                    value["$eq"]
                    if isinstance(value, dict) and "$eq" in value
                    else value
                )
                for key, value in filter_doc.items()
            )
        ]
        return _FakeFindCursor(matched)

    async def bulk_write(
        self,
        operations: list[Any],
        ordered: bool = False,
    ) -> None:
        del ordered
        for operation in operations:
            self._docs[operation._doc["_id"]] = dict(operation._doc)

    async def delete_many(self, filter_doc: dict[str, Any]) -> None:
        document_id = filter_doc["document_id"]
        to_remove = [
            doc_id
            for doc_id, doc in self._docs.items()
            if doc.get("document_id") == document_id
        ]
        for doc_id in to_remove:
            del self._docs[doc_id]

    async def create_search_index(self, model: Any) -> None:
        del model
        self._index_queryable = True

    async def list_search_indexes(self, name: str) -> _FakeAsyncIterator:
        del name
        return _FakeAsyncIterator([{"queryable": self._index_queryable}])

    async def aggregate(
        self,
        pipeline: list[dict[str, Any]],
    ) -> _FakeAsyncIterator:
        return _FakeAsyncIterator(self._run_aggregate(pipeline))

    async def drop(self) -> None:
        self._database._collections.pop(self._name, None)

    def _run_aggregate(
        self,
        pipeline: list[dict[str, Any]],
    ) -> list[dict[str, Any]]:
        if pipeline and "$vectorSearch" in pipeline[0]:
            return self._vector_search(pipeline[0]["$vectorSearch"])
        return self._list_documents(pipeline)

    def _vector_search(self, stage: dict[str, Any]) -> list[dict[str, Any]]:
        query_vector = stage["queryVector"]
        top_k = stage["limit"]
        metadata_filter = stage.get("filter")

        scored: list[dict[str, Any]] = []
        for doc in self._docs.values():
            if not self._matches_metadata_filter(doc, metadata_filter):
                continue
            scored.append(
                {
                    "document_id": doc["document_id"],
                    "chunk": doc["chunk"],
                    "score": _cosine_similarity(query_vector, doc["vector"]),
                },
            )

        scored.sort(key=lambda item: item["score"], reverse=True)
        return scored[:top_k]

    def _list_documents(
        self,
        pipeline: list[dict[str, Any]],
    ) -> list[dict[str, Any]]:
        docs = list(self._docs.values())
        for stage in pipeline:
            if "$match" in stage:
                docs = [
                    doc
                    for doc in docs
                    if self._matches_match_stage(doc, stage["$match"])
                ]
            elif "$group" in stage:
                return self._group_documents(docs, stage["$group"])
        return []

    @staticmethod
    def _matches_match_stage(
        doc: dict[str, Any],
        match: dict[str, Any],
    ) -> bool:
        for key, expected in match.items():
            if isinstance(expected, dict) and "$eq" in expected:
                expected = expected["$eq"]
            value = doc
            for part in key.split("."):
                value = value[part]
            if value != expected:
                return False
        return True

    @staticmethod
    def _matches_metadata_filter(
        doc: dict[str, Any],
        metadata_filter: dict[str, Any] | None,
    ) -> bool:
        if not metadata_filter:
            return True

        for clause in metadata_filter.get("$and", []):
            for key, condition in clause.items():
                expected = condition["$eq"]
                value = doc
                for part in key.split("."):
                    value = value[part]
                if value != expected:
                    return False
        return True

    @staticmethod
    def _group_documents(
        docs: list[dict[str, Any]],
        group_stage: dict[str, Any],
    ) -> list[dict[str, Any]]:
        del group_stage
        grouped: dict[str, dict[str, Any]] = {}
        for doc in docs:
            document_id = doc["document_id"]
            if document_id not in grouped:
                grouped[document_id] = {
                    "_id": document_id,
                    "source": doc["chunk"]["source"],
                    "metadata": doc["chunk"].get("metadata") or {},
                    "chunk_count": 0,
                }
            grouped[document_id]["chunk_count"] += 1
        return list(grouped.values())


class _FakeMongoDatabase:
    """In-memory database handle."""

    def __init__(self) -> None:
        self._collections: dict[str, _FakeMongoCollection] = {}

    async def list_collection_names(self) -> list[str]:
        return list(self._collections.keys())

    async def create_collection(self, name: str) -> _FakeMongoCollection:
        collection = _FakeMongoCollection(self, name)
        self._collections[name] = collection
        return collection

    def __getitem__(self, name: str) -> _FakeMongoCollection:
        if name not in self._collections:
            self._collections[name] = _FakeMongoCollection(self, name)
        return self._collections[name]


class _FakeMongoClient:
    """In-memory async MongoDB client."""

    def __init__(self, database_name: str) -> None:
        self._database_name = database_name
        self._databases: dict[str, _FakeMongoDatabase] = {}

    def __getitem__(self, database_name: str) -> _FakeMongoDatabase:
        if database_name not in self._databases:
            self._databases[database_name] = _FakeMongoDatabase()
        return self._databases[database_name]

    async def close(self) -> None:
        self._databases.clear()


class MongoDBStoreTest(IsolatedAsyncioTestCase):
    """The test cases for the MongoDBStore class."""

    async def asyncSetUp(self) -> None:
        """Create a MongoDB store with a mocked pymongo client."""
        self._fake_client = _FakeMongoClient("test-db")
        self._client_patcher = patch.object(
            MongoDBStore,
            "get_client",
            return_value=self._fake_client,
        )
        self._client_patcher.start()

        self._exit_stack = AsyncExitStack()
        self.store = MongoDBStore(uri="mongodb://mock", database="test-db")
        await self._exit_stack.enter_async_context(self.store)

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

    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_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_mongodb_delete_filter(self) -> None:
        """MongoDB combines the source document with metadata equality."""
        store = self.store
        collection = SimpleNamespace(delete_many=AsyncMock())
        with patch.object(store, "_col", return_value=collection):
            await store.delete(
                "shared",
                "doc",
                metadata_filter={"tenant": "alpha", "project": 2},
            )
        collection.delete_many.assert_awaited_once_with(
            {
                "document_id": "doc",
                "$and": [
                    {"chunk.metadata.tenant": {"$eq": "alpha"}},
                    {"chunk.metadata.project": {"$eq": 2}},
                ],
            },
        )
        for scope in (None, {}):
            with self.subTest(scope=scope):
                collection.delete_many.reset_mock()
                with patch.object(store, "_col", return_value=collection):
                    await store.delete("shared", "doc", metadata_filter=scope)
                collection.delete_many.assert_awaited_once_with(
                    {"document_id": "doc"},
                )

    async def test_list_documents_uses_literal_metadata_values(self) -> None:
        """Operator-shaped values must remain equality operands."""
        collection = SimpleNamespace(
            aggregate=AsyncMock(return_value=_FakeAsyncIterator([])),
        )
        with patch.object(self.store, "_col", return_value=collection):
            await self.store.list_documents(
                "shared",
                metadata_filter={
                    "scope": {"$ne": "alpha"},
                    "label": {"$regex": "^private"},
                    "archived": None,
                },
            )
        pipeline = collection.aggregate.call_args.args[0]
        self.assertEqual(
            pipeline[0],
            {
                "$match": {
                    "chunk.metadata.scope": {"$eq": {"$ne": "alpha"}},
                    "chunk.metadata.label": {"$eq": {"$regex": "^private"}},
                    "chunk.metadata.archived": {"$eq": None},
                },
            },
        )

    async def test_list_chunks_uses_literal_metadata_values(self) -> None:
        """Listing keeps literal equality alongside the document fence."""
        collection = SimpleNamespace(
            find=Mock(return_value=_FakeFindCursor([])),
        )
        with patch.object(self.store, "_col", return_value=collection):
            await self.store.list_chunks(
                "shared",
                "doc",
                metadata_filter={
                    "scope": {"$ne": "alpha"},
                    "label": {"$regex": "^private"},
                    "archived": None,
                },
            )
        self.assertEqual(
            collection.find.call_args.args[0],
            {
                "document_id": "doc",
                "chunk.metadata.scope": {"$eq": {"$ne": "alpha"}},
                "chunk.metadata.label": {"$eq": {"$regex": "^private"}},
                "chunk.metadata.archived": {"$eq": None},
            },
        )

    async def test_search_candidate_limits(self) -> None:
        """Search caps candidates while preserving the requested limit."""
        await self.store.create_collection("kb-1", dimensions=3)
        record = _make_record("A", [1.0, 0.0, 0.0], document_id="doc-1")
        record.chunk.metadata["kb_scope"] = "kb-a"
        await self.store.insert("kb-1", [record])
        col = self._fake_client["test-db"]["kb-1"]

        for top_k, num_candidates, metadata_filter in [
            (None, 100, None),
            (500, 10_000, None),
            (501, 10_000, {"kb_scope": "kb-a"}),
            (10_000, 10_000, None),
        ]:
            with self.subTest(top_k=top_k):
                search_kwargs: dict[str, Any] = {}
                if top_k is not None:
                    search_kwargs["top_k"] = top_k
                if metadata_filter is not None:
                    search_kwargs["metadata_filter"] = metadata_filter

                with patch.object(
                    col,
                    "aggregate",
                    wraps=col.aggregate,
                ) as aggregate:
                    results = await self.store.search(
                        "kb-1",
                        query_vector=[1.0, 0.0, 0.0],
                        **search_kwargs,
                    )

                vector_search: dict[str, Any] = {
                    "index": "vector_index",
                    "path": "vector",
                    "queryVector": [1.0, 0.0, 0.0],
                    "numCandidates": num_candidates,
                    "limit": 5 if top_k is None else top_k,
                }
                if metadata_filter is not None:
                    vector_search["filter"] = {
                        "$and": [{"chunk.metadata.kb_scope": {"$eq": "kb-a"}}],
                    }
                aggregate.assert_awaited_once_with(
                    [
                        {"$vectorSearch": vector_search},
                        {
                            "$project": {
                                "document_id": 1,
                                "chunk": 1,
                                "score": {"$meta": "vectorSearchScore"},
                            },
                        },
                    ],
                )
                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": {"kb_scope": "kb-a"},
                            },
                        },
                    ],
                )

    async def test_search_top_k_exceeds_limit(self) -> None:
        """An oversized search is rejected before accessing MongoDB."""
        store = MongoDBStore(uri="mongodb://mock", database="test-db")
        with (
            patch.object(store, "_ensure_index_ready") as ensure_index_ready,
            patch.object(
                store,
                "get_client",
                return_value=self._fake_client,
            ) as get_client,
        ):
            with self.assertRaisesRegex(ValueError, "top_k.*10000"):
                await store.search(
                    "kb-1",
                    query_vector=[1.0, 0.0, 0.0],
                    top_k=10_001,
                )
            ensure_index_ready.assert_not_awaited()
            get_client.assert_not_called()

    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 = sorted(
            await self.store.list_documents("kb-1"),
            key=lambda summary: summary.document_id,
        )
        self.assertEqual(
            [summary.model_dump() for summary in summaries],
            [
                {
                    "document_id": "doc-1",
                    "source": "alpha.txt",
                    "chunk_count": 2,
                    "metadata": {
                        "filename": "alpha.txt",
                        "media_type": "text/plain",
                    },
                },
                {
                    "document_id": "doc-2",
                    "source": "beta.md",
                    "chunk_count": 1,
                    "metadata": {
                        "filename": "beta.md",
                        "media_type": "text/markdown",
                    },
                },
            ],
        )

    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(
            _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": {"kb_scope": "kb-a"},
                    },
                },
            ],
        )

        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(
            _dump_results(results),
            [
                {
                    "score": 1.0,
                    "document_id": "doc-2",
                    "chunk": {
                        "content": {
                            "type": "text",
                            "text": "B",
                            "id": AnyString(),
                            "created_at": AnyString(),
                            "finished_at": None,
                        },
                        "source": "doc-2.txt",
                        "chunk_index": 0,
                        "total_chunks": 1,
                        "metadata": {"kb_scope": "kb-b"},
                    },
                },
            ],
        )

    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, [])