diff --git a/src/memos/api/client.py b/src/memos/api/client.py index 818ce5e0d..aeac47f58 100644 --- a/src/memos/api/client.py +++ b/src/memos/api/client.py @@ -18,6 +18,8 @@ MemOSGetMemoryResponse, MemOSGetMessagesResponse, MemOSGetTaskStatusResponse, + MemOSListKnowledgebaseFileResponse, + MemOSListKnowledgebaseResponse, MemOSSearchResponse, ) from memos.log import get_logger @@ -65,6 +67,14 @@ def _validate_required_params(self, **params): if not param_value: raise ValueError(f"{param_name} is required") + @staticmethod + def _validate_page_size(*, page: int, size: int, max_size: int = 100) -> None: + """Validate 1-based pagination params used by knowledgebase list endpoints.""" + if not isinstance(page, int) or page < 1: + raise ValueError("page must be an integer >= 1") + if not isinstance(size, int) or size < 1 or size > max_size: + raise ValueError(f"size must be an integer in [1, {max_size}]") + def get_message( self, user_id: str, @@ -417,6 +427,96 @@ def get_knowledgebase_file( if retry == MAX_RETRY_COUNT - 1: raise + def list_knowledgebases( + self, page: int = 1, size: int = 10 + ) -> MemOSListKnowledgebaseResponse | None: + """ + List knowledgebases owned by the authenticated caller. + + Issue #1382 — adds the missing list endpoint so callers can enumerate + KB ids without having to remember them out of band. + + Args: + page: 1-based page index. Must be >= 1. + size: Page size. Must be in [1, 100]. + + Returns: + ``MemOSListKnowledgebaseResponse`` on success, or ``None`` if all + retries were exhausted (the underlying exception is re-raised on + the final retry, mirroring the rest of this client). + """ + # Validate pagination + self._validate_page_size(page=page, size=size) + + url = f"{self.base_url}/list/knowledgebase" + payload = { + "page": page, + "size": size, + } + + for retry in range(MAX_RETRY_COUNT): + try: + response = requests.post( + url, data=json.dumps(payload), headers=self.headers, timeout=30 + ) + response.raise_for_status() + response_data = response.json() + + return MemOSListKnowledgebaseResponse(**response_data) + except Exception as e: + logger.error(f"Failed to list knowledgebase (retry {retry + 1}/3): {e}") + if retry == MAX_RETRY_COUNT - 1: + raise + + def list_knowledgebase_documents( + self, + knowledgebase_id: str, + page: int = 1, + size: int = 10, + ) -> MemOSListKnowledgebaseFileResponse | None: + """ + List documents (files) inside a knowledgebase. + + Issue #1382 — many downstream use cases (bulk delete, UI listing, + verifying ingest) need to enumerate the files of a KB without + knowing each ``file_id`` ahead of time. + + Args: + knowledgebase_id: target knowledgebase identifier. + page: 1-based page index. Must be >= 1. + size: Page size. Must be in [1, 100]. + + Returns: + ``MemOSListKnowledgebaseFileResponse`` on success, or ``None`` + if all retries were exhausted (the underlying exception is + re-raised on the final retry). + """ + # Validate required parameters + self._validate_required_params(knowledgebase_id=knowledgebase_id) + # Validate pagination + self._validate_page_size(page=page, size=size) + + url = f"{self.base_url}/list/knowledgebase-file" + payload = { + "knowledgebase_id": knowledgebase_id, + "page": page, + "size": size, + } + + for retry in range(MAX_RETRY_COUNT): + try: + response = requests.post( + url, data=json.dumps(payload), headers=self.headers, timeout=30 + ) + response.raise_for_status() + response_data = response.json() + + return MemOSListKnowledgebaseFileResponse(**response_data) + except Exception as e: + logger.error(f"Failed to list knowledgebase-file (retry {retry + 1}/3): {e}") + if retry == MAX_RETRY_COUNT - 1: + raise + def get_task_status(self, task_id: str) -> MemOSGetTaskStatusResponse | None: """ get task status diff --git a/src/memos/api/product_models.py b/src/memos/api/product_models.py index ff9d94859..3bb6c9934 100644 --- a/src/memos/api/product_models.py +++ b/src/memos/api/product_models.py @@ -1246,6 +1246,72 @@ def files(self) -> list[FileDetail]: return self.data.file_detail_list +class ListKnowledgebaseData(BaseModel): + """Data model for list knowledgebase response based on actual API. + + Schema kept loose (`extra="allow"`) so the SDK does not break if the + server adds new fields. + """ + + model_config = {"extra": "allow"} + + knowledgebase_list: list[dict[str, Any]] = Field( + default_factory=list, + alias="knowledgebase_list", + description="List of knowledgebase summaries", + ) + total: int | None = Field( + None, description="Total knowledgebase count if returned by the server" + ) + page: int | None = Field(None, description="Current page index (1-based) if returned") + size: int | None = Field(None, description="Page size if returned") + + +class MemOSListKnowledgebaseResponse(BaseModel): + """Response model for list knowledgebase operation based on actual API.""" + + code: int = Field(..., description="Response status code") + message: str = Field(..., description="Response message") + data: ListKnowledgebaseData = Field(..., description="List results data") + + @property + def knowledgebases(self) -> list[dict[str, Any]]: + """Convenient access to knowledgebase list.""" + return self.data.knowledgebase_list + + +class ListKnowledgebaseFileData(BaseModel): + """Data model for list knowledgebase-file response based on actual API. + + Reuses the loose `FileDetail` model so the SDK stays compatible with + new server-side fields. + """ + + model_config = {"extra": "allow"} + + file_detail_list: list[FileDetail] = Field( + default_factory=list, + alias="file_detail_list", + description="List of file details inside the knowledgebase", + ) + total: int | None = Field(None, description="Total file count if returned by the server") + page: int | None = Field(None, description="Current page index (1-based) if returned") + size: int | None = Field(None, description="Page size if returned") + + +class MemOSListKnowledgebaseFileResponse(BaseModel): + """Response model for list knowledgebase-file operation based on actual API.""" + + code: int = Field(..., description="Response status code") + message: str = Field(..., description="Response message") + data: ListKnowledgebaseFileData = Field(..., description="List results data") + + @property + def files(self) -> list[FileDetail]: + """Convenient access to file list.""" + return self.data.file_detail_list + + class MemOSAddResponse(BaseModel): """Response model for add message operation based on actual API.""" diff --git a/tests/api/test_client_knowledgebase_list.py b/tests/api/test_client_knowledgebase_list.py new file mode 100644 index 000000000..b030801ad --- /dev/null +++ b/tests/api/test_client_knowledgebase_list.py @@ -0,0 +1,242 @@ +"""Unit tests for `MemOSClient` knowledgebase list APIs (issue #1382).""" + +from __future__ import annotations + +import json + +from unittest.mock import MagicMock, patch + +import pytest +import requests + + +# --------------------------------------------------------------------------- +# Fixtures +# --------------------------------------------------------------------------- + + +@pytest.fixture +def client(): + """Build a `MemOSClient` with a dummy api key (no real network).""" + from memos.api.client import MemOSClient + + return MemOSClient(api_key="test_api_key", base_url="https://example.test/api/openmem/v1") + + +def _ok_response(payload: dict) -> MagicMock: + """Build a mocked `requests.Response` with `payload` as JSON.""" + resp = MagicMock(spec=requests.Response) + resp.status_code = 200 + resp.raise_for_status.return_value = None + resp.json.return_value = payload + return resp + + +# --------------------------------------------------------------------------- +# Response models — TC-1 / TC-2 baseline imports +# --------------------------------------------------------------------------- + + +def test_response_models_exist(): + """The two new response models must be importable from product_models.""" + from memos.api.product_models import ( + ListKnowledgebaseData, + ListKnowledgebaseFileData, + MemOSListKnowledgebaseFileResponse, + MemOSListKnowledgebaseResponse, + ) + + assert MemOSListKnowledgebaseResponse is not None + assert MemOSListKnowledgebaseFileResponse is not None + assert ListKnowledgebaseData is not None + assert ListKnowledgebaseFileData is not None + + +# --------------------------------------------------------------------------- +# TC-1: list_knowledgebases happy path +# --------------------------------------------------------------------------- + + +def test_list_knowledgebases_happy_path(client): + from memos.api.product_models import MemOSListKnowledgebaseResponse + + payload = { + "code": 200, + "message": "ok", + "data": { + "knowledgebase_list": [ + {"id": "kb_1", "name": "alpha"}, + {"id": "kb_2", "name": "beta"}, + ], + "total": 2, + "page": 1, + "size": 10, + }, + } + + with patch("memos.api.client.requests.post", return_value=_ok_response(payload)) as mock_post: + resp = client.list_knowledgebases(page=1, size=10) + + assert isinstance(resp, MemOSListKnowledgebaseResponse) + assert len(resp.knowledgebases) == 2 + assert resp.knowledgebases[0]["id"] == "kb_1" + assert resp.data.total == 2 + + # Verify the HTTP call shape + mock_post.assert_called_once() + call_args, call_kwargs = mock_post.call_args + url = call_args[0] + assert url.endswith("/list/knowledgebase") + body = json.loads(call_kwargs["data"]) + assert body == {"page": 1, "size": 10} + assert call_kwargs["headers"]["Authorization"] == "Token test_api_key" + + +# --------------------------------------------------------------------------- +# TC-2: list_knowledgebase_documents happy path +# --------------------------------------------------------------------------- + + +def test_list_knowledgebase_documents_happy_path(client): + from memos.api.product_models import MemOSListKnowledgebaseFileResponse + + payload = { + "code": 200, + "message": "ok", + "data": { + "file_detail_list": [ + {"file_id": "f_1", "filename": "a.pdf"}, + ], + "total": 1, + "page": 1, + "size": 10, + }, + } + + with patch("memos.api.client.requests.post", return_value=_ok_response(payload)) as mock_post: + resp = client.list_knowledgebase_documents(knowledgebase_id="kb_1") + + assert isinstance(resp, MemOSListKnowledgebaseFileResponse) + assert len(resp.files) == 1 + assert resp.files[0].model_dump()["file_id"] == "f_1" + assert resp.data.total == 1 + + mock_post.assert_called_once() + call_args, call_kwargs = mock_post.call_args + url = call_args[0] + assert url.endswith("/list/knowledgebase-file") + body = json.loads(call_kwargs["data"]) + assert body == {"knowledgebase_id": "kb_1", "page": 1, "size": 10} + + +# --------------------------------------------------------------------------- +# TC-3: missing knowledgebase_id rejected before HTTP +# --------------------------------------------------------------------------- + + +def test_list_knowledgebase_documents_rejects_empty_kb_id(client): + with ( + patch("memos.api.client.requests.post") as mock_post, + pytest.raises(ValueError, match="knowledgebase_id"), + ): + client.list_knowledgebase_documents(knowledgebase_id="") + mock_post.assert_not_called() + + +# --------------------------------------------------------------------------- +# TC-4: page < 1 rejected before HTTP +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize("bad_page", [0, -1, -42]) +def test_list_knowledgebases_rejects_bad_page(client, bad_page): + with ( + patch("memos.api.client.requests.post") as mock_post, + pytest.raises(ValueError, match="page"), + ): + client.list_knowledgebases(page=bad_page) + mock_post.assert_not_called() + + +@pytest.mark.parametrize("bad_page", [0, -1]) +def test_list_knowledgebase_documents_rejects_bad_page(client, bad_page): + with ( + patch("memos.api.client.requests.post") as mock_post, + pytest.raises(ValueError, match="page"), + ): + client.list_knowledgebase_documents(knowledgebase_id="kb_1", page=bad_page) + mock_post.assert_not_called() + + +# --------------------------------------------------------------------------- +# TC-5: size out of [1, 100] rejected before HTTP +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize("bad_size", [0, -5, 101, 1000]) +def test_list_knowledgebases_rejects_bad_size(client, bad_size): + with ( + patch("memos.api.client.requests.post") as mock_post, + pytest.raises(ValueError, match="size"), + ): + client.list_knowledgebases(size=bad_size) + mock_post.assert_not_called() + + +@pytest.mark.parametrize("bad_size", [0, 101]) +def test_list_knowledgebase_documents_rejects_bad_size(client, bad_size): + with ( + patch("memos.api.client.requests.post") as mock_post, + pytest.raises(ValueError, match="size"), + ): + client.list_knowledgebase_documents(knowledgebase_id="kb_1", size=bad_size) + mock_post.assert_not_called() + + +# --------------------------------------------------------------------------- +# TC-6: retry on transient failure recovers +# --------------------------------------------------------------------------- + + +def test_list_knowledgebases_retries_then_succeeds(client): + from memos.api.product_models import MemOSListKnowledgebaseResponse + + payload = { + "code": 200, + "message": "ok", + "data": { + "knowledgebase_list": [], + "total": 0, + "page": 1, + "size": 10, + }, + } + + side_effects = [ + requests.ConnectionError("boom-1"), + requests.ConnectionError("boom-2"), + _ok_response(payload), + ] + + with patch("memos.api.client.requests.post", side_effect=side_effects) as mock_post: + resp = client.list_knowledgebases() + + assert isinstance(resp, MemOSListKnowledgebaseResponse) + assert mock_post.call_count == 3 + + +# --------------------------------------------------------------------------- +# TC-7: retry exhaustion re-raises +# --------------------------------------------------------------------------- + + +def test_list_knowledgebases_retry_exhaustion_raises(client): + with ( + patch( + "memos.api.client.requests.post", + side_effect=requests.ConnectionError("always fails"), + ) as mock_post, + pytest.raises(requests.ConnectionError), + ): + client.list_knowledgebases() + assert mock_post.call_count == 3