Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
fix(rag): enforce knowledge base scope during document deletion (#3222)
dafyy321-pixelb2a084799bf8
diff --git a/src/agentscope/rag/_knowledge.py b/src/agentscope/rag/_knowledge.pyindex 8534fadb7..b83338777 100644--- a/src/agentscope/rag/_knowledge.py+++ b/src/agentscope/rag/_knowledge.py@@ -26,7 +26,7 @@ deployment.co-locating multiple logical knowledge bases inside the same physicalcollection — typically multi-tenant deployments where every recordcarries a ``{"tenant_id": "..."}`` payload. It is set once at-construction time and **always** applied: search/list never escape+construction time and **always** applied: search/list/delete never escapeit, and insert forces it onto every chunk's metadata so a malicious orbuggy parser cannot rebind a record into another scope."""@@ -113,6 +113,8 @@ class KnowledgeBase:- :meth:`insert_document` forces these keys onto everyinserted chunk's metadata, overriding caller-suppliedvalues, so records cannot leak into another scope.+ - :meth:`delete_document` removes only records matching+ both the document id and every filter pair.``None`` disables filtering — the default fordeployments where every knowledge base owns its@@ -361,17 +363,30 @@ class KnowledgeBase:return document_idasync def delete_document(self, document_id: str) -> None:- """Remove every record for one source document.+ """Remove every record for one source document within this scope.++ Records must also match :attr:`metadata_filter` when set.+ Custom vector stores must support scoped deletion; an unsupported+ filter raises an error instead of falling back to unscoped deletion.Args:document_id (`str`):The source document id whose records should be removed."""await self.ensure_collection()- await self._vector_store.delete(- self._collection,- document_id,- )+ if self._metadata_filter:+ await self._vector_store.delete(+ self._collection,+ document_id,+ metadata_filter=self._metadata_filter,+ )+ else:+ # Preserve compatibility with custom stores using the original+ # delete signature when no scoping is required.+ await self._vector_store.delete(+ self._collection,+ document_id,+ )async def list_documents(self) -> list["DocumentSummary"]:"""List all distinct source documents in this knowledge base.diff --git a/src/agentscope/rag/_vdb/_elasticsearch.py b/src/agentscope/rag/_vdb/_elasticsearch.pyindex d9fc9b6ee..ab1225c6d 100644--- a/src/agentscope/rag/_vdb/_elasticsearch.py+++ b/src/agentscope/rag/_vdb/_elasticsearch.py@@ -159,11 +159,30 @@ class ElasticsearchStore(VectorStoreBase):"record(s)",)- async def delete(self, collection: str, document_id: str) -> None:- """Delete every chunk belonging to one source document."""+ async def delete(+ self,+ collection: str,+ document_id: str,+ metadata_filter: dict[str, Any] | None = None,+ ) -> None:+ """Delete every chunk belonging to one source document.++ Args:+ collection (`str`):+ The target collection name.+ document_id (`str`):+ The source document ID whose records should be removed.+ metadata_filter (`dict[str, Any] | None`, optional):+ Restrict deletion to records matching every metadata pair+ in addition to the document ID. ``None`` disables filtering.+ """+ query: dict[str, Any] = {"term": {"document_id": document_id}}+ if metadata_filter:+ filters = [query, *self._metadata_filters(metadata_filter)]+ query = {"bool": {"filter": filters}}await self.get_client().delete_by_query(index=collection,- query={"term": {"document_id": document_id}},+ query=query,conflicts="proceed",refresh=self._refresh is not False,)diff --git a/src/agentscope/rag/_vdb/_milvus_lite.py b/src/agentscope/rag/_vdb/_milvus_lite.pyindex fa4170e2c..ea8bacb12 100644--- a/src/agentscope/rag/_vdb/_milvus_lite.py+++ b/src/agentscope/rag/_vdb/_milvus_lite.py@@ -260,12 +260,27 @@ class MilvusLiteStore(VectorStoreBase):self,collection: str,document_id: str,+ metadata_filter: dict[str, Any] | None = None,) -> None:- """Delete all records belonging to one source document."""+ """Delete all records belonging to one source document.++ Args:+ collection (`str`):+ The target collection name.+ document_id (`str`):+ The source document ID whose records should be removed.+ metadata_filter (`dict[str, Any] | None`, optional):+ Restrict deletion to records matching every metadata pair+ in addition to the document ID. ``None`` disables filtering.+ """+ clauses = [self._build_document_filter(document_id)]+ meta_expr = self._build_metadata_filter(metadata_filter)+ if meta_expr:+ clauses.append(meta_expr)await asyncio.to_thread(self.get_client().delete,collection_name=collection,- filter=self._build_document_filter(document_id),+ filter=" and ".join(clauses),)# ------------------------------------------------------------------diff --git a/src/agentscope/rag/_vdb/_mongodb.py b/src/agentscope/rag/_vdb/_mongodb.pyindex f6029b8d6..450b9bc8e 100644--- a/src/agentscope/rag/_vdb/_mongodb.py+++ b/src/agentscope/rag/_vdb/_mongodb.py@@ -293,6 +293,7 @@ class MongoDBStore(VectorStoreBase):self,collection: str,document_id: str,+ metadata_filter: dict[str, Any] | None = None,) -> None:"""Delete all records belonging to one source document.@@ -305,8 +306,13 @@ class MongoDBStore(VectorStoreBase):document_id (`str`):The source document ID whose records should beremoved.+ metadata_filter (`dict[str, Any] | None`, optional):+ Restrict deletion to records matching every metadata pair+ in addition to the document ID. ``None`` disables filtering."""- await self._col(collection).delete_many({"document_id": document_id})+ query = {"document_id": document_id}+ query.update(self._build_metadata_filter(metadata_filter) or {})+ await self._col(collection).delete_many(query)# ------------------------------------------------------------------# Searchdiff --git a/src/agentscope/rag/_vdb/_qdrant.py b/src/agentscope/rag/_vdb/_qdrant.pyindex 09af9a69c..a4a85bcc1 100644--- a/src/agentscope/rag/_vdb/_qdrant.py+++ b/src/agentscope/rag/_vdb/_qdrant.py@@ -248,6 +248,7 @@ class QdrantStore(VectorStoreBase):self,collection: str,document_id: str,+ metadata_filter: dict[str, Any] | None = None,) -> None:"""Delete all records belonging to one source document.@@ -260,20 +261,25 @@ class QdrantStore(VectorStoreBase):document_id (`str`):The source document ID whose records should beremoved.+ metadata_filter (`dict[str, Any] | None`, optional):+ Restrict deletion to records matching every metadata pair+ in addition to the document ID. ``None`` disables filtering."""from qdrant_client import models+ conditions = [+ models.FieldCondition(+ key="document_id",+ match=models.MatchValue(value=document_id),+ ),+ ]+ base_filter = self._build_metadata_filter(metadata_filter)+ if base_filter is not None:+ conditions.extend(base_filter.must)await self.get_client().delete(collection_name=collection,points_selector=models.FilterSelector(- filter=models.Filter(- must=[- models.FieldCondition(- key="document_id",- match=models.MatchValue(value=document_id),- ),- ],- ),+ filter=models.Filter(must=conditions),),)diff --git a/src/agentscope/rag/_vdb/_vector_store.py b/src/agentscope/rag/_vdb/_vector_store.pyindex 060f9507b..ec621a2c3 100644--- a/src/agentscope/rag/_vdb/_vector_store.py+++ b/src/agentscope/rag/_vdb/_vector_store.py@@ -207,6 +207,7 @@ class VectorStoreBase(ABC):self,collection: str,document_id: str,+ metadata_filter: dict[str, Any] | None = None,) -> None:"""Delete all records belonging to one source document.@@ -221,6 +222,11 @@ class VectorStoreBase(ABC):document_id (`str`):The source document ID whose records should beremoved.+ metadata_filter (`dict[str, Any] | None`, optional):+ Restrict deletion to records whose chunk metadata matches+ every ``key == value`` pair in addition to the document ID.+ ``None`` or an empty dict deletes all records of the+ document. Backends must not ignore a non-empty filter."""# ------------------------------------------------------------------diff --git a/tests/rag_vdb_elasticsearch_test.py b/tests/rag_vdb_elasticsearch_test.pyindex 883c4b693..2ffa4c275 100644--- a/tests/rag_vdb_elasticsearch_test.py+++ b/tests/rag_vdb_elasticsearch_test.py@@ -145,6 +145,42 @@ class ElasticsearchStoreTest(IsolatedAsyncioTestCase):with self.assertRaisesRegex(RuntimeError, "1 record"):await self.store.insert("kb-1", [_record("doc-1", 0)])+ async def test_elasticsearch_delete_filter(self) -> None:+ """Elasticsearch uses a conjunction of exact-match filters."""+ await self.store.delete(+ "shared",+ "doc",+ metadata_filter={"tenant": "alpha", "project": 2},+ )+ self.client.delete_by_query.assert_awaited_once_with(+ index="shared",+ query={+ "bool": {+ "filter": [+ {"term": {"document_id": "doc"}},+ {"term": {"metadata.tenant": "alpha"}},+ {"term": {"metadata.project": 2}},+ ],+ },+ },+ conflicts="proceed",+ refresh=True,+ )+ for scope in (None, {}):+ with self.subTest(scope=scope):+ self.client.delete_by_query.reset_mock()+ await self.store.delete(+ "shared",+ "doc",+ metadata_filter=scope,+ )+ self.client.delete_by_query.assert_awaited_once_with(+ index="shared",+ query={"term": {"document_id": "doc"}},+ conflicts="proceed",+ refresh=True,+ )+async def test_delete_by_document_id(self) -> None:await self.store.delete("kb-1", "doc-1")diff --git a/tests/rag_vdb_milvus_lite_test.py b/tests/rag_vdb_milvus_lite_test.pyindex 31d01278d..2f15405f5 100644--- a/tests/rag_vdb_milvus_lite_test.py+++ b/tests/rag_vdb_milvus_lite_test.py@@ -5,7 +5,9 @@ import unittestfrom contextlib import AsyncExitStackfrom importlib.util import find_specfrom pathlib import Path+from types import SimpleNamespacefrom unittest.async_case import IsolatedAsyncioTestCase+from unittest.mock import Mock, patchfrom utils import AnyString@@ -582,3 +584,34 @@ class MilvusLiteStoreTest(IsolatedAsyncioTestCase):[c.content.text for c in chunks],["v2-chunk0", "v2-chunk1"],)+++class MilvusDeleteFilterTest(IsolatedAsyncioTestCase):+ """Check delete predicates without starting a Milvus service."""++ async def test_milvus_delete_filter(self) -> None:+ """Milvus keeps document escaping and ANDs both metadata fields."""+ store = MilvusLiteStore()+ client = SimpleNamespace(delete=Mock())+ with patch.object(store, "get_client", return_value=client):+ await store.delete(+ "shared",+ 'doc"id',+ metadata_filter={"tenant": "alpha", "project": 2},+ )+ client.delete.assert_called_once_with(+ collection_name="shared",+ filter=(+ 'document_id == "doc\\"id" and '+ 'metadata["tenant"] == "alpha" and metadata["project"] == 2'+ ),+ )+ for scope in (None, {}):+ with self.subTest(scope=scope):+ client.delete.reset_mock()+ with patch.object(store, "get_client", return_value=client):+ await store.delete("shared", "doc", metadata_filter=scope)+ client.delete.assert_called_once_with(+ collection_name="shared",+ filter='document_id == "doc"',+ )diff --git a/tests/rag_vdb_mongodb_test.py b/tests/rag_vdb_mongodb_test.pyindex f8b2d7a8d..904726135 100644--- a/tests/rag_vdb_mongodb_test.py+++ b/tests/rag_vdb_mongodb_test.py@@ -5,9 +5,10 @@ from __future__ import annotationsimport mathfrom contextlib import AsyncExitStack+from types import SimpleNamespacefrom typing import Anyfrom unittest.async_case import IsolatedAsyncioTestCase-from unittest.mock import patch+from unittest.mock import AsyncMock, patchfrom utils import AnyString@@ -478,6 +479,34 @@ class MongoDBStoreTest(IsolatedAsyncioTestCase):],)+ 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_search_candidate_limits(self) -> None:"""Search caps candidates while preserving the requested limit."""await self.store.create_collection("kb-1", dimensions=3)diff --git a/tests/rag_vdb_qdrant_test.py b/tests/rag_vdb_qdrant_test.pyindex cc3973071..42730049f 100644--- a/tests/rag_vdb_qdrant_test.py+++ b/tests/rag_vdb_qdrant_test.py@@ -1,19 +1,47 @@# -*- coding: utf-8 -*-"""Unit tests for the QdrantStore class."""from contextlib import AsyncExitStack+from importlib.util import find_spec+from types import SimpleNamespace+from unittest import skipUnlessfrom unittest.async_case import IsolatedAsyncioTestCase+from unittest.mock import AsyncMock, patchfrom utils import AnyStringfrom agentscope.message import TextBlockfrom 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-structurecomparison.@@ -698,3 +726,115 @@ class QdrantStoreTest(IsolatedAsyncioTestCase):[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)