Skip to content

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

feat(rag): add Milvus Lite vector store (#1969)

Trefoile28707373d71
diff --git a/examples/rag/README.md b/examples/rag/README.md
index 3ea503bf3..1e7e1abde 100644
--- a/examples/rag/README.md
+++ b/examples/rag/README.md
@@ -19,6 +19,23 @@ uv pip install "agentscope[rag]"
uv pip install -e ".[rag]"
```
+To use a local persistent Milvus Lite vector store instead of the
+in-memory Qdrant store, install the optional extra:
+
+```bash
+uv pip install "agentscope[milvuslite]"
+# Or from source (repo root)
+uv pip install -e ".[milvuslite]"
+```
+
+Then replace the vector store construction:
+
+```python
+from agentscope.rag import MilvusLiteStore
+
+store = MilvusLiteStore(uri="./rag_demo.db")
+```
+
`integrate_with_agent.py` additionally uses `DashScopeChatModel`, which is already in the base `agentscope` dependencies.
## Run
diff --git a/pyproject.toml b/pyproject.toml
index b431d424a..c5bbe15c7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -82,6 +82,10 @@ rag = [
"pypdf",
"python-pptx",
]
+milvuslite = [
+ "pymilvus[milvus-lite]>=2.4.0",
+ "milvus-lite>=3.0; sys_platform == 'win32'",
+]
# ------------ S3-compatible blob store ------------
s3 = [
@@ -105,6 +109,7 @@ full = [
"agentscope[workspace]",
"agentscope[tools]",
"agentscope[rag]",
+ "agentscope[milvuslite]",
"agentscope[s3]",
"agentscope[mem0]",
]
diff --git a/src/agentscope/rag/__init__.py b/src/agentscope/rag/__init__.py
index 46fe9b4c0..78697cb40 100644
--- a/src/agentscope/rag/__init__.py
+++ b/src/agentscope/rag/__init__.py
@@ -9,6 +9,7 @@ from ._document import (
from ._parser import ImageParser, ParserBase, PDFParser, PPTParser, TextParser
from ._vdb import (
DocumentSummary,
+ MilvusLiteStore,
VectorStoreBase,
VectorRecord,
VectorSearchResult,
@@ -22,6 +23,7 @@ __all__ = [
"Chunk",
"DocumentSummary",
"ImageParser",
+ "MilvusLiteStore",
"ParserBase",
"PDFParser",
"PPTParser",
diff --git a/src/agentscope/rag/_vdb/__init__.py b/src/agentscope/rag/_vdb/__init__.py
index 95cde6164..58774cfd9 100644
--- a/src/agentscope/rag/_vdb/__init__.py
+++ b/src/agentscope/rag/_vdb/__init__.py
@@ -7,10 +7,12 @@ from ._vector_store import (
VectorSearchResult,
VectorStoreBase,
)
+from ._milvus_lite import MilvusLiteStore
from ._qdrant import QdrantStore
__all__ = [
"DocumentSummary",
+ "MilvusLiteStore",
"VectorStoreBase",
"VectorRecord",
"VectorSearchResult",
diff --git a/src/agentscope/rag/_vdb/_milvus_lite.py b/src/agentscope/rag/_vdb/_milvus_lite.py
new file mode 100644
index 000000000..4126d2117
--- /dev/null
+++ b/src/agentscope/rag/_vdb/_milvus_lite.py
@@ -0,0 +1,452 @@
+# -*- coding: utf-8 -*-
+"""Milvus Lite implementation of the vector store backend.
+
+Built on the official ``pymilvus`` ``MilvusClient`` API. Milvus Lite is
+started automatically when the URI points to a local ``.db`` file, so it
+is convenient for local development, tests, and small RAG workloads.
+"""
+import asyncio
+import json
+import os
+import uuid
+from typing import TYPE_CHECKING, Any, Literal
+
+from ._vector_store import (
+ DocumentSummary,
+ VectorRecord,
+ VectorSearchResult,
+ VectorStoreBase,
+)
+from .._document import Chunk
+
+if TYPE_CHECKING:
+ from pymilvus import MilvusClient
+
+
+class MilvusLiteStore(VectorStoreBase):
+ """Vector store backend backed by Milvus Lite.
+
+ Each knowledge base maps to one Milvus collection. Every entity
+ stores the owning ``document_id``, the serialized
+ :class:`~agentscope.rag.Chunk`, and the chunk metadata in a JSON
+ field used for flat equality filtering.
+
+ .. note:: Install optional dependencies with
+ ``pip install agentscope[milvuslite]``.
+
+ .. code-block:: python
+
+ store = MilvusLiteStore(uri="./rag_demo.db")
+
+ async with store:
+ await store.create_collection("kb_1", dimensions=768)
+ """
+
+ def __init__(
+ self,
+ uri: str = "./agentscope_milvus_lite.db",
+ metric_type: Literal["COSINE", "IP", "L2"] = "COSINE",
+ index_type: str = "AUTOINDEX",
+ client_kwargs: dict[str, Any] | None = None,
+ batch_size: int = 256,
+ ) -> None:
+ """Initialize the Milvus Lite vector store.
+
+ Args:
+ uri (`str`, defaults to ``"./agentscope_milvus_lite.db"``):
+ Local ``.db`` path for Milvus Lite, or a Milvus-compatible
+ endpoint URI.
+ metric_type (`Literal["COSINE", "IP", "L2"]`, defaults to \
+ ``"COSINE"``):
+ The metric used for the vector index and search.
+ index_type (`str`, defaults to ``"AUTOINDEX"``):
+ The Milvus index type used for newly created collections.
+ client_kwargs (`dict[str, Any] | None`, optional):
+ Extra keyword arguments forwarded to
+ :class:`pymilvus.MilvusClient`.
+ batch_size (`int`, defaults to ``256``):
+ Batch size used by inserts and document listing.
+ """
+ self._uri = uri
+ self._metric_type = metric_type
+ self._index_type = index_type
+ self._client_kwargs = client_kwargs or {}
+ self._batch_size = batch_size
+ self._client: "MilvusClient | None" = None
+ self._is_lite_uri = self._is_local_db_uri(uri)
+
+ def get_client(self) -> "MilvusClient":
+ """Lazily create and cache the Milvus client."""
+ if self._client is None:
+ from pymilvus import MilvusClient
+
+ self._client = MilvusClient(uri=self._uri, **self._client_kwargs)
+ return self._client
+
+ async def __aexit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc_val: BaseException | None,
+ exc_tb: Any,
+ ) -> None:
+ """Exit the async context and close the underlying client."""
+ if self._client is None:
+ return
+
+ client = self._client
+ self._client = None
+ close = getattr(client, "close", None)
+ if close is not None:
+ await asyncio.to_thread(close)
+ if self._is_lite_uri:
+ await asyncio.to_thread(self._release_lite_server)
+
+ # ------------------------------------------------------------------
+ # Collection management
+ # ------------------------------------------------------------------
+
+ async def create_collection(
+ self,
+ name: str,
+ dimensions: int,
+ ) -> None:
+ """Create a new Milvus collection.
+
+ No-op if the collection already exists.
+
+ Args:
+ name (`str`):
+ The collection name. Typically, the knowledge base ID.
+ dimensions (`int`):
+ The fixed vector dimensionality for this collection.
+ All vectors inserted later must have this many elements.
+ """
+ client = self.get_client()
+
+ def _create() -> None:
+ from pymilvus import DataType
+
+ if client.has_collection(collection_name=name):
+ client.load_collection(collection_name=name)
+ return
+
+ schema = client.create_schema(
+ auto_id=False,
+ enable_dynamic_field=False,
+ )
+ schema.add_field(
+ field_name="id",
+ datatype=DataType.VARCHAR,
+ is_primary=True,
+ max_length=64,
+ )
+ schema.add_field(
+ field_name="vector",
+ datatype=DataType.FLOAT_VECTOR,
+ dim=dimensions,
+ )
+ schema.add_field(
+ field_name="document_id",
+ datatype=DataType.VARCHAR,
+ max_length=512,
+ )
+ schema.add_field(
+ field_name="chunk",
+ datatype=DataType.JSON,
+ )
+ schema.add_field(
+ field_name="metadata",
+ datatype=DataType.JSON,
+ )
+
+ index_params = client.prepare_index_params()
+ index_params.add_index(
+ field_name="vector",
+ index_type=self._index_type,
+ metric_type=self._metric_type,
+ )
+ client.create_collection(
+ collection_name=name,
+ schema=schema,
+ index_params=index_params,
+ )
+ client.load_collection(collection_name=name)
+
+ await asyncio.to_thread(_create)
+
+ async def delete_collection(self, name: str) -> None:
+ """Delete a collection and all its data."""
+ await asyncio.to_thread(
+ self.get_client().drop_collection,
+ collection_name=name,
+ )
+
+ async def has_collection(self, name: str) -> bool:
+ """Check whether a collection exists."""
+ return await asyncio.to_thread(
+ self.get_client().has_collection,
+ collection_name=name,
+ )
+
+ # ------------------------------------------------------------------
+ # Data operations
+ # ------------------------------------------------------------------
+
+ async def insert(
+ self,
+ collection: str,
+ records: list[VectorRecord],
+ ) -> None:
+ """Insert records into a collection.
+
+ Each entity stores the :attr:`VectorRecord.document_id`, the
+ serialized :class:`Chunk`, and a copy of ``chunk.metadata`` in a
+ JSON field used by :meth:`search` and :meth:`list_documents` for
+ flat equality filtering.
+
+ Args:
+ collection (`str`):
+ The target collection name.
+ records (`list[VectorRecord]`):
+ The records to insert, each carrying a
+ :class:`Chunk` and its embedding vector.
+ """
+ if not records:
+ return
+
+ for start in range(0, len(records), self._batch_size):
+ batch = records[start : start + self._batch_size]
+ await asyncio.to_thread(
+ self.get_client().insert,
+ collection_name=collection,
+ data=[
+ {
+ "id": str(uuid.uuid4()),
+ "vector": record.vector,
+ "document_id": record.document_id,
+ "chunk": record.chunk.model_dump(mode="json"),
+ "metadata": record.chunk.metadata,
+ }
+ for record in batch
+ ],
+ )
+
+ async def delete(
+ self,
+ collection: str,
+ document_id: str,
+ ) -> None:
+ """Delete all records belonging to one source document."""
+ await asyncio.to_thread(
+ self.get_client().delete,
+ collection_name=collection,
+ filter=self._build_document_filter(document_id),
+ )
+
+ # ------------------------------------------------------------------
+ # Search
+ # ------------------------------------------------------------------
+
+ async def search(
+ self,
+ collection: str,
+ query_vector: list[float],
+ top_k: int = 5,
+ metadata_filter: dict[str, Any] | None = None,
+ ) -> list[VectorSearchResult]:
+ """Find the most similar records to a query vector.
+
+ Args:
+ collection (`str`):
+ The collection to search.
+ query_vector (`list[float]`):
+ The query embedding vector.
+ top_k (`int`, defaults to ``5``):
+ Maximum number of results to return.
+ metadata_filter (`dict[str, Any] | None`, optional):
+ If provided, restrict the search to records whose
+ ``chunk.metadata`` matches every ``key == value`` pair
+ in this dict. Milvus Lite stores this metadata in a JSON
+ field and supports flat scalar equality filters.
+
+ Returns:
+ `list[VectorSearchResult]`:
+ Results ordered by descending similarity score for
+ cosine / inner product metrics, or ascending distance
+ semantics for L2 as exposed by Milvus.
+ """
+ response = await asyncio.to_thread(
+ self.get_client().search,
+ collection_name=collection,
+ data=[query_vector],
+ anns_field="vector",
+ limit=top_k,
+ filter=self._build_metadata_filter(metadata_filter),
+ output_fields=["document_id", "chunk"],
+ search_params={"metric_type": self._metric_type},
+ )
+
+ hits = response[0] if response else []
+ return [
+ VectorSearchResult(
+ score=self._extract_score(hit, self._metric_type),
+ document_id=hit["entity"]["document_id"],
+ chunk=Chunk.model_validate(hit["entity"]["chunk"]),
+ )
+ for hit in hits
+ ]
+
+ # ------------------------------------------------------------------
+ # Document listing
+ # ------------------------------------------------------------------
+
+ async def list_documents(
+ self,
+ collection: str,
+ metadata_filter: dict[str, Any] | None = None,
+ ) -> list[DocumentSummary]:
+ """List all distinct source documents indexed in a collection.
+
+ Scans stored entities and aggregates them by ``document_id``.
+ The first chunk encountered for each document supplies the
+ source filename and document-level metadata.
+
+ Args:
+ collection (`str`):
+ The target collection name.
+ metadata_filter (`dict[str, Any] | None`, optional):
+ If provided, restrict aggregation to records whose
+ ``chunk.metadata`` matches every ``key == value`` pair
+ in this dict.
+
+ Returns:
+ `list[DocumentSummary]`:
+ One summary per distinct ``document_id``.
+ """
+ client = self.get_client()
+ rows = await asyncio.to_thread(
+ self._query_all_rows,
+ client,
+ collection,
+ metadata_filter,
+ )
+ summaries: dict[str, DocumentSummary] = {}
+ seen_ids: set[str] = set()
+
+ for row in rows:
+ record_id = row.get("id")
+ if record_id in seen_ids:
+ continue
+ if record_id is not None:
+ seen_ids.add(record_id)
+
+ doc_id = row["document_id"]
+ summary = summaries.get(doc_id)
+ if summary is None:
+ chunk_payload = row["chunk"]
+ summaries[doc_id] = DocumentSummary(
+ document_id=doc_id,
+ source=chunk_payload.get("source", ""),
+ chunk_count=1,
+ metadata=dict(chunk_payload.get("metadata", {})),
+ )
+ else:
+ summary.chunk_count += 1
+
+ return list(summaries.values())
+
+ def _query_all_rows(
+ self,
+ client: "MilvusClient",
+ collection: str,
+ metadata_filter: dict[str, Any] | None,
+ ) -> list[dict[str, Any]]:
+ """Query all rows needed by ``list_documents``."""
+ output_fields = ["id", "document_id", "chunk"]
+ expr = self._build_metadata_filter(metadata_filter)
+
+ if hasattr(client, "query_iterator"):
+ iterator = client.query_iterator(
+ collection_name=collection,
+ filter=expr,
+ output_fields=output_fields,
+ batch_size=self._batch_size,
+ )
+ try:
+ rows = []
+ while True:
+ batch = iterator.next()
+ if not batch:
+ break
+ rows.extend(batch)
+ return rows
+ finally:
+ close = getattr(iterator, "close", None)
+ if close is not None:
+ close()
+
+ rows = []
+ offset = 0
+ while True:
+ batch = client.query(
+ collection_name=collection,
+ filter=expr,
+ output_fields=output_fields,
+ limit=self._batch_size,
+ offset=offset,
+ )
+ if not batch:
+ break
+ rows.extend(batch)
+ if len(batch) < self._batch_size:
+ break
+ offset += self._batch_size
+ return rows
+
+ @staticmethod
+ def _build_document_filter(document_id: str) -> str:
+ """Build a Milvus scalar filter for a document id."""
+ return f"document_id == {json.dumps(document_id)}"
+
+ @staticmethod
+ def _build_metadata_filter(
+ metadata_filter: dict[str, Any] | None,
+ ) -> str:
+ """Translate a flat ``{key: value}`` filter into a Milvus expr."""
+ if not metadata_filter:
+ return ""
+
+ return " and ".join(
+ f"metadata[{json.dumps(key)}] == {json.dumps(value)}"
+ for key, value in metadata_filter.items()
+ )
+
+ @staticmethod
+ def _extract_score(
+ hit: dict[str, Any],
+ metric_type: Literal["COSINE", "IP", "L2"],
+ ) -> float:
+ """Extract a score from Milvus search result shapes."""
+ if "distance" in hit:
+ distance = float(hit["distance"])
+ if metric_type == "COSINE":
+ return 1.0 - distance
+ return distance
+ if "score" in hit:
+ return float(hit["score"])
+ return 0.0
+
+ @staticmethod
+ def _is_local_db_uri(uri: str) -> bool:
+ """Check whether a URI starts an embedded Milvus Lite server."""
+ return not uri.startswith(("http://", "https://")) and (
+ os.path.splitext(uri)[1] == ".db"
+ )
+
+ def _release_lite_server(self) -> None:
+ """Release the embedded Milvus Lite server for local ``.db`` URIs."""
+ try:
+ from milvus_lite import server_manager_instance
+ except ImportError:
+ return
+ server_manager_instance.release_server(self._uri)
diff --git a/tests/rag_vdb_milvus_lite_test.py b/tests/rag_vdb_milvus_lite_test.py
new file mode 100644
index 000000000..a565d302b
--- /dev/null
+++ b/tests/rag_vdb_milvus_lite_test.py
@@ -0,0 +1,358 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for the MilvusLiteStore class."""
+import tempfile
+import unittest
+from contextlib import AsyncExitStack
+from importlib.util import find_spec
+from pathlib import Path
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.message import TextBlock
+from agentscope.rag import (
+ Chunk,
+ MilvusLiteStore,
+ VectorRecord,
+ VectorSearchResult,
+)
+
+
+_MILVUS_LITE_AVAILABLE = (
+ find_spec("pymilvus") is not None and find_spec("milvus_lite") is not None
+)
+
+
+def _dump_results(results: list[VectorSearchResult]) -> list[dict]:
+ """Convert search results into plain dicts for comparison."""
+ 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."""
+ 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,
+ ),
+ )
+
+
+ _MILVUS_LITE_AVAILABLE,
+ "pymilvus and milvus_lite are required for MilvusLiteStore tests",
+)
+class MilvusLiteStoreTest(IsolatedAsyncioTestCase):
+ """The test cases for the MilvusLiteStore class."""
+
+ async def asyncSetUp(self) -> None:
+ """Create a temporary Milvus Lite store before each test."""
+ self._exit_stack = AsyncExitStack()
+ tmpdir = self._exit_stack.enter_context(tempfile.TemporaryDirectory())
+ self._tmpdir = Path(tmpdir)
+ db_path = self._tmpdir / "test.db"
+ self.store = await self._exit_stack.enter_async_context(
+ MilvusLiteStore(uri=str(db_path)),
+ )
+
+ async def asyncTearDown(self) -> None:
+ """Close the store and remove the temporary database."""
+ 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.assertAlmostEqual(results[0].score, 1.0)
+ self.assertAlmostEqual(results[1].score, 0.0)
+ dumped = _dump_results(results)
+ for result in dumped:
+ result["score"] = 0.0
+ self.assertEqual(
+ dumped,
+ [
+ {
+ "score": 0.0,
+ "document_id": "doc-1",
+ "chunk": {
+ "content": {
+ "type": "text",
+ "text": "Hello world!",
+ "id": AnyString(),
+ },
+ "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(),
+ },
+ "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(len(results), 1)
+ self.assertEqual(results[0].document_id, "doc-1")
+
+ 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([r.document_id for r in results], ["doc-2"])
+
+ 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"])
+
+ summaries = await self.store.list_documents(
+ "kb_1",
+ metadata_filter={"kb_scope": "kb-b"},
+ )
+ self.assertEqual([s.document_id for s in summaries], ["doc-2"])
+
+ async def test_persists_records_after_reopen(self) -> None:
+ """Records remain available after closing and reopening the DB."""
+ db_path = self._tmpdir / "persistent.db"
+
+ async with MilvusLiteStore(uri=str(db_path)) as first_store:
+ await first_store.create_collection("kb_persistent", dimensions=3)
+ await first_store.insert(
+ "kb_persistent",
+ [
+ _make_record(
+ "Persisted",
+ [1.0, 0.0, 0.0],
+ document_id="doc-1",
+ ),
+ ],
+ )
+
+ async with MilvusLiteStore(uri=str(db_path)) as second_store:
+ await second_store.create_collection("kb_persistent", dimensions=3)
+ results = await second_store.search(
+ "kb_persistent",
+ query_vector=[1.0, 0.0, 0.0],
+ top_k=1,
+ )
+
+ self.assertEqual([r.document_id for r in results], ["doc-1"])