chore: import upstream snapshot with attribution

tests/unit_tests/rag/test_file_storage.py

@@ -0,0 +1,190 @@
+"""Unit tests for RuntimeKnowledgeBase file storage behavior."""
+
+from __future__ import annotations
+
+import io
+import zipfile
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+
+from langbot.pkg.rag.knowledge.kbmgr import RuntimeKnowledgeBase
+
+
+def _make_zip_bytes(entries: dict[str, bytes]) -> bytes:
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, 'w') as zf:
+        for name, content in entries.items():
+            zf.writestr(name, content)
+        zf.mkdir('emptydir')
+    return buffer.getvalue()
+
+
+def _make_app() -> Mock:
+    app = Mock()
+    app.logger = Mock()
+    app.task_mgr = Mock()
+    app.storage_mgr = Mock()
+    app.storage_mgr.storage_provider = Mock()
+    app.storage_mgr.storage_provider.exists = AsyncMock(return_value=True)
+    app.storage_mgr.storage_provider.load = AsyncMock()
+    app.storage_mgr.storage_provider.save = AsyncMock()
+    app.storage_mgr.storage_provider.size = AsyncMock(return_value=123)
+    app.storage_mgr.storage_provider.delete = AsyncMock()
+    app.persistence_mgr = Mock()
+    app.persistence_mgr.execute_async = AsyncMock()
+    app.plugin_connector = Mock()
+    return app
+
+
+def _make_kb(plugin_id: str | None = 'author/engine') -> RuntimeKnowledgeBase:
+    kb_entity = Mock()
+    kb_entity.uuid = 'test-kb-uuid'
+    kb_entity.collection_id = 'test-collection'
+    kb_entity.creation_settings = {}
+    kb_entity.knowledge_engine_plugin_id = plugin_id
+    return RuntimeKnowledgeBase(_make_app(), kb_entity)
+
+
+class TestStoreFile:
+    @pytest.mark.asyncio
+    async def test_store_file_creates_pending_record_and_user_task(self):
+        kb = _make_kb()
+
+        def create_user_task(coro, **kwargs):
+            coro.close()
+            return SimpleNamespace(id='task-1', kwargs=kwargs)
+
+        kb.ap.task_mgr.create_user_task = Mock(side_effect=create_user_task)
+
+        task_id = await kb.store_file('documents/test.pdf')
+
+        assert task_id == 'task-1'
+        kb.ap.storage_mgr.storage_provider.exists.assert_awaited_once_with('documents/test.pdf')
+        kb.ap.persistence_mgr.execute_async.assert_awaited_once()
+        call_kwargs = kb.ap.task_mgr.create_user_task.call_args.kwargs
+        assert call_kwargs['kind'] == 'knowledge-operation'
+        assert call_kwargs['name'] == 'knowledge-store-file-documents/test.pdf'
+        assert call_kwargs['label'] == 'Store file documents/test.pdf'
+
+    @pytest.mark.asyncio
+    async def test_store_file_raises_when_source_file_missing(self):
+        kb = _make_kb()
+        kb.ap.storage_mgr.storage_provider.exists = AsyncMock(return_value=False)
+
+        with pytest.raises(Exception, match='File missing.pdf not found'):
+            await kb.store_file('missing.pdf')
+
+        kb.ap.persistence_mgr.execute_async.assert_not_awaited()
+        kb.ap.task_mgr.create_user_task.assert_not_called()
+
+
+class TestStoreZipFile:
+    @pytest.mark.asyncio
+    async def test_store_zip_file_extracts_supported_files_and_skips_noise(self):
+        kb = _make_kb()
+        kb.ap.storage_mgr.storage_provider.load = AsyncMock(
+            return_value=_make_zip_bytes(
+                {
+                    'doc1.pdf': b'pdf',
+                    'doc2.txt': b'text',
+                    'subdir/doc3.md': b'markdown',
+                    'page.html': b'html',
+                    'image.png': b'png',
+                    '.hidden': b'hidden',
+                    '__MACOSX/doc1.pdf': b'metadata',
+                }
+            )
+        )
+        kb.store_file = AsyncMock(side_effect=['task-pdf', 'task-txt', 'task-md', 'task-html'])
+
+        task_id = await kb._store_zip_file('archive.zip', parser_plugin_id='parser/plugin')
+
+        assert task_id == 'task-pdf'
+        assert kb.ap.storage_mgr.storage_provider.save.await_count == 4
+        saved_names = [call.args[0] for call in kb.ap.storage_mgr.storage_provider.save.await_args_list]
+        assert any(name.startswith('doc1_') and name.endswith('.pdf') for name in saved_names)
+        assert any(name.startswith('doc2_') and name.endswith('.txt') for name in saved_names)
+        assert any(name.startswith('subdir_doc3_') and name.endswith('.md') for name in saved_names)
+        assert any(name.startswith('page_') and name.endswith('.html') for name in saved_names)
+        assert not any('image' in name for name in saved_names)
+        assert not any('hidden' in name for name in saved_names)
+        assert not any('__MACOSX' in name for name in saved_names)
+        kb.ap.storage_mgr.storage_provider.delete.assert_awaited_once_with('archive.zip')
+
+    @pytest.mark.asyncio
+    async def test_store_zip_file_raises_when_no_supported_files(self):
+        kb = _make_kb()
+        kb.ap.storage_mgr.storage_provider.load = AsyncMock(
+            return_value=_make_zip_bytes({'image.png': b'png', 'video.mp4': b'video'})
+        )
+        kb.store_file = AsyncMock()
+
+        with pytest.raises(Exception, match='No supported files found'):
+            await kb._store_zip_file('archive.zip')
+
+        kb.store_file.assert_not_awaited()
+        kb.ap.storage_mgr.storage_provider.delete.assert_awaited_once_with('archive.zip')
+
+
+class TestStoreFileTask:
+    @pytest.mark.asyncio
+    async def test_store_file_task_marks_completed_and_cleans_storage(self):
+        kb = _make_kb()
+        kb._ingest_document = AsyncMock(return_value={'status': 'completed'})
+        file_obj = SimpleNamespace(uuid='file-uuid', file_name='test.pdf', extension='pdf')
+        task_context = Mock()
+
+        await kb._store_file_task(file_obj, task_context)
+
+        task_context.set_current_action.assert_called_once_with('Processing file')
+        kb.ap.storage_mgr.storage_provider.size.assert_awaited_once_with('test.pdf')
+        kb._ingest_document.assert_awaited_once()
+        assert kb.ap.persistence_mgr.execute_async.await_count == 2
+        kb.ap.storage_mgr.storage_provider.delete.assert_awaited_once_with('test.pdf')
+
+    @pytest.mark.asyncio
+    async def test_store_file_task_marks_failed_and_cleans_storage(self):
+        kb = _make_kb()
+        kb._ingest_document = AsyncMock(return_value={'status': 'failed', 'error_message': 'parser failed'})
+        file_obj = SimpleNamespace(uuid='file-uuid', file_name='bad.pdf', extension='pdf')
+        task_context = Mock()
+
+        with pytest.raises(Exception, match='parser failed'):
+            await kb._store_file_task(file_obj, task_context)
+
+        assert kb.ap.persistence_mgr.execute_async.await_count == 2
+        kb.ap.storage_mgr.storage_provider.delete.assert_awaited_once_with('bad.pdf')
+
+
+class TestDeleteDocument:
+    @pytest.mark.asyncio
+    async def test_delete_document_returns_false_when_no_plugin_id(self):
+        kb = _make_kb(plugin_id=None)
+
+        result = await kb._delete_document('doc-id')
+
+        assert result is False
+
+    @pytest.mark.asyncio
+    async def test_delete_document_calls_configured_rag_plugin(self):
+        kb = _make_kb()
+        kb.ap.plugin_connector.call_rag_delete_document = AsyncMock(return_value=True)
+
+        result = await kb._delete_document('doc-id')
+
+        assert result is True
+        kb.ap.plugin_connector.call_rag_delete_document.assert_awaited_once_with(
+            'author/engine', 'doc-id', 'test-kb-uuid'
+        )
+
+    @pytest.mark.asyncio
+    async def test_delete_document_returns_false_on_plugin_error(self):
+        kb = _make_kb()
+        kb.ap.plugin_connector.call_rag_delete_document = AsyncMock(side_effect=Exception('plugin error'))
+
+        result = await kb._delete_document('doc-id')
+
+        assert result is False
+        kb.ap.logger.error.assert_called_once()

tests/unit_tests/rag/test_i18n_conversion.py

@@ -0,0 +1,64 @@
+"""Unit tests for RAG i18n name conversion.
+
+Tests cover:
+- _to_i18n_name() static method
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+
+
+def get_kbmgr_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.rag.knowledge.kbmgr')
+
+
+class TestToI18nName:
+    """Tests for _to_i18n_name static method."""
+
+    def test_string_input_wrapped(self):
+        """Test that string input is wrapped into i18n dict."""
+        kbmgr = get_kbmgr_module()
+        result = kbmgr.RAGManager._to_i18n_name('Test Engine')
+        assert result == {'en_US': 'Test Engine', 'zh_Hans': 'Test Engine'}
+
+    def test_dict_input_preserved(self):
+        """Test that dict input is returned as-is."""
+        kbmgr = get_kbmgr_module()
+        input_dict = {'en_US': 'English Name', 'zh_Hans': '中文名', 'ja_JP': '日本語名'}
+        result = kbmgr.RAGManager._to_i18n_name(input_dict)
+        assert result == input_dict
+        assert result is input_dict  # Should return the same object
+
+    def test_empty_string_handling(self):
+        """Test that empty string is handled correctly."""
+        kbmgr = get_kbmgr_module()
+        result = kbmgr.RAGManager._to_i18n_name('')
+        assert result == {'en_US': '', 'zh_Hans': ''}
+
+    def test_none_input_handling(self):
+        """Test that None is converted to string 'None'."""
+        kbmgr = get_kbmgr_module()
+        result = kbmgr.RAGManager._to_i18n_name(None)
+        assert result == {'en_US': 'None', 'zh_Hans': 'None'}
+
+    def test_number_input_converted_to_string(self):
+        """Test that numbers are converted to strings."""
+        kbmgr = get_kbmgr_module()
+        result = kbmgr.RAGManager._to_i18n_name(123)
+        assert result == {'en_US': '123', 'zh_Hans': '123'}
+
+    def test_dict_with_partial_keys_preserved(self):
+        """Test that dict with only some i18n keys is preserved."""
+        kbmgr = get_kbmgr_module()
+        input_dict = {'en_US': 'Only English'}
+        result = kbmgr.RAGManager._to_i18n_name(input_dict)
+        assert result == {'en_US': 'Only English'}
+
+    def test_dict_with_extra_keys_preserved(self):
+        """Test that dict with extra non-i18n keys is preserved."""
+        kbmgr = get_kbmgr_module()
+        input_dict = {'en_US': 'English', 'extra_key': 'extra_value'}
+        result = kbmgr.RAGManager._to_i18n_name(input_dict)
+        assert result == {'en_US': 'English', 'extra_key': 'extra_value'}

tests/unit_tests/rag/test_kbmgr.py

@@ -0,0 +1,771 @@
+"""Unit tests for RAG knowledge base manager.
+
+Tests cover:
+- RAGManager CRUD operations
+- RuntimeKnowledgeBase getters
+- Knowledge engine enrichment
+- KB loading and removal
+"""
+
+from __future__ import annotations
+
+import pytest
+import uuid
+from unittest.mock import Mock, AsyncMock
+from importlib import import_module
+
+
+def get_rag_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.rag.knowledge.kbmgr')
+
+
+def create_mock_app():
+    """Create mock Application for testing."""
+    mock_app = Mock()
+    mock_app.logger = Mock()
+    mock_app.persistence_mgr = AsyncMock()
+    mock_app.persistence_mgr.execute_async = AsyncMock()
+    mock_app.persistence_mgr.serialize_model = Mock(return_value={})
+    mock_app.plugin_connector = AsyncMock()
+    mock_app.plugin_connector.is_enable_plugin = True
+    mock_app.storage_mgr = Mock()
+    mock_app.storage_mgr.storage_provider = AsyncMock()
+    mock_app.task_mgr = AsyncMock()
+    mock_app.task_mgr.create_user_task = Mock(return_value=Mock(id=1))
+    return mock_app
+
+
+def create_mock_kb_entity():
+    """Create mock KnowledgeBase entity."""
+    mock_kb = Mock()
+    mock_kb.uuid = str(uuid.uuid4())
+    mock_kb.name = 'Test KB'
+    mock_kb.description = 'Test description'
+    mock_kb.knowledge_engine_plugin_id = 'author/engine'
+    mock_kb.collection_id = mock_kb.uuid
+    mock_kb.creation_settings = {}
+    mock_kb.retrieval_settings = {}
+    return mock_kb
+
+
+class TestRAGManagerCreateKnowledgeBase:
+    """Tests for create_knowledge_base method."""
+
+    @pytest.mark.asyncio
+    async def test_creates_kb_with_valid_engine(self):
+        """Test creates KB when engine plugin exists."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        # Mock valid engine list
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(
+            return_value=[{'plugin_id': 'author/engine', 'name': 'Engine'}]
+        )
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb = await manager.create_knowledge_base(
+            name='Test KB',
+            knowledge_engine_plugin_id='author/engine',
+            creation_settings={'model': 'test'},
+        )
+
+        assert kb.name == 'Test KB'
+        assert kb.knowledge_engine_plugin_id == 'author/engine'
+
+    @pytest.mark.asyncio
+    async def test_raises_when_engine_not_found(self):
+        """Test raises ValueError when engine plugin not found."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        # Mock empty engine list
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(return_value=[])
+
+        manager = rag_module.RAGManager(mock_app)
+
+        with pytest.raises(ValueError) as exc_info:
+            await manager.create_knowledge_base(
+                name='Test KB',
+                knowledge_engine_plugin_id='unknown/engine',
+                creation_settings={},
+            )
+
+        assert 'not found' in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_rollback_on_plugin_create_failure(self):
+        """Test that DB entry is rolled back when plugin create fails."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(return_value=[{'plugin_id': 'author/engine'}])
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock(side_effect=Exception('Plugin error'))
+
+        manager = rag_module.RAGManager(mock_app)
+
+        with pytest.raises(Exception):
+            await manager.create_knowledge_base(
+                name='Test KB',
+                knowledge_engine_plugin_id='author/engine',
+                creation_settings={},
+            )
+
+        # Should have called delete to rollback
+        # Check that delete was called (for rollback)
+        assert len(manager.knowledge_bases) == 0
+
+    @pytest.mark.asyncio
+    async def test_sets_default_retrieval_settings(self):
+        """Test that empty retrieval_settings defaults to {}."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(return_value=[{'plugin_id': 'author/engine'}])
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb = await manager.create_knowledge_base(
+            name='Test KB',
+            knowledge_engine_plugin_id='author/engine',
+            creation_settings={},
+            retrieval_settings=None,
+        )
+
+        assert kb.retrieval_settings == {}
+
+    @pytest.mark.asyncio
+    async def test_skips_validation_when_plugin_disabled(self):
+        """Test that engine validation is skipped when plugin disabled."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_app.plugin_connector.is_enable_plugin = False
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        # Should not raise even though engine list would be empty
+        kb = await manager.create_knowledge_base(
+            name='Test KB',
+            knowledge_engine_plugin_id='any/engine',
+            creation_settings={},
+        )
+
+        assert kb.knowledge_engine_plugin_id == 'any/engine'
+
+
+class TestRuntimeKnowledgeBaseOnKBCreate:
+    """Tests for _on_kb_create method."""
+
+    @pytest.mark.asyncio
+    async def test_calls_plugin_on_create(self):
+        """Test that plugin is notified on KB create."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.creation_settings = {'model': 'test'}
+
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock()
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        await runtime_kb._on_kb_create()
+
+        mock_app.plugin_connector.rag_on_kb_create.assert_called_once_with(
+            'author/engine', mock_kb.uuid, {'model': 'test'}
+        )
+
+    @pytest.mark.asyncio
+    async def test_skips_when_no_plugin_id(self):
+        """Test that create notification is skipped when no plugin."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.knowledge_engine_plugin_id = None
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        await runtime_kb._on_kb_create()
+
+        mock_app.plugin_connector.rag_on_kb_create.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_raises_on_plugin_error(self):
+        """Test that exception is raised when plugin fails."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock(side_effect=Exception('Plugin failed'))
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        with pytest.raises(Exception):
+            await runtime_kb._on_kb_create()
+
+
+class TestRuntimeKnowledgeBaseDeleteFile:
+    """Tests for delete_file method."""
+
+    @pytest.mark.asyncio
+    async def test_delete_file_calls_plugin_and_db(self):
+        """Test that delete_file calls plugin and removes DB record."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        mock_app.plugin_connector.call_rag_delete_document = AsyncMock(return_value=True)
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        await runtime_kb.delete_file('file-uuid')
+
+        mock_app.plugin_connector.call_rag_delete_document.assert_called_once()
+        mock_app.persistence_mgr.execute_async.assert_called()
+
+
+class TestRuntimeKnowledgeBaseIngestDocument:
+    """Tests for _ingest_document method."""
+
+    @pytest.mark.asyncio
+    async def test_ingest_calls_plugin(self):
+        """Test that ingest calls plugin connector."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        mock_app.plugin_connector.call_rag_ingest = AsyncMock(return_value={'status': 'success'})
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        result = await runtime_kb._ingest_document(
+            {'filename': 'test.pdf'},
+            'storage/path',
+        )
+
+        assert result['status'] == 'success'
+        mock_app.plugin_connector.call_rag_ingest.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_ingest_raises_when_no_plugin_id(self):
+        """Test that ValueError is raised when no plugin ID."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.knowledge_engine_plugin_id = None
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        with pytest.raises(ValueError) as exc_info:
+            await runtime_kb._ingest_document({'filename': 'test.pdf'}, 'path')
+
+        assert 'Plugin ID required' in str(exc_info.value)
+
+
+class TestRAGManagerLoadKnowledgeBasesFromDB:
+    """Tests for load_knowledge_bases_from_db method."""
+
+    @pytest.mark.asyncio
+    async def test_loads_all_kbs_from_db(self):
+        """Test that all KBs are loaded from database."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        mock_kb1 = create_mock_kb_entity()
+        mock_kb2 = create_mock_kb_entity()
+        mock_app.persistence_mgr.execute_async = AsyncMock(
+            return_value=Mock(all=Mock(return_value=[mock_kb1, mock_kb2]))
+        )
+
+        manager = rag_module.RAGManager(mock_app)
+        await manager.load_knowledge_bases_from_db()
+
+        assert len(manager.knowledge_bases) == 2
+
+    @pytest.mark.asyncio
+    async def test_handles_load_error_gracefully(self):
+        """Test that load errors are logged but not raised."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        # KB that will cause initialize to fail
+        mock_kb = create_mock_kb_entity()
+
+        mock_app.persistence_mgr.execute_async = AsyncMock(return_value=Mock(all=Mock(return_value=[mock_kb])))
+
+        # Make initialize fail by having plugin_connector throw error
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock(side_effect=Exception('Init failed'))
+
+        manager = rag_module.RAGManager(mock_app)
+        # Should not raise - errors are caught
+        await manager.load_knowledge_bases_from_db()
+
+        # KB should still be loaded (initialize just passes)
+        # The error would come from runtime_kb.initialize which we can't easily mock
+        # So we just verify it doesn't crash
+
+
+class TestRuntimeKnowledgeBaseGetters:
+    """Tests for RuntimeKnowledgeBase getter methods."""
+
+    def test_get_uuid_returns_entity_uuid(self):
+        """Test get_uuid returns KB entity UUID."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        assert runtime_kb.get_uuid() == mock_kb.uuid
+
+    def test_get_name_returns_entity_name(self):
+        """Test get_name returns KB entity name."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        assert runtime_kb.get_name() == mock_kb.name
+
+    def test_get_knowledge_engine_plugin_id_returns_plugin_id(self):
+        """Test get_knowledge_engine_plugin_id returns plugin ID."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        assert runtime_kb.get_knowledge_engine_plugin_id() == 'author/engine'
+
+    def test_get_knowledge_engine_plugin_id_returns_empty_when_none(self):
+        """Test returns empty string when plugin_id is None."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.knowledge_engine_plugin_id = None
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        assert runtime_kb.get_knowledge_engine_plugin_id() == ''
+
+
+class TestRuntimeKnowledgeBaseRetrieve:
+    """Tests for RuntimeKnowledgeBase retrieve method."""
+
+    @pytest.mark.asyncio
+    async def test_retrieve_merges_settings(self):
+        """Test that retrieve merges stored and request settings."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.retrieval_settings = {'top_k': 10, 'model': 'default'}
+
+        # Mock plugin connector response with valid RetrievalResultEntry fields
+        # content must be list of ContentElement dicts
+        mock_app.plugin_connector.call_rag_retrieve = AsyncMock(
+            return_value={
+                'results': [
+                    {
+                        'id': 'doc1',
+                        'content': [{'type': 'text', 'text': 'test content'}],
+                        'metadata': {},
+                        'distance': 0.1,
+                    }
+                ]
+            }
+        )
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        # Override top_k in request
+        results = await runtime_kb.retrieve('query text', settings={'top_k': 20})
+
+        assert len(results) == 1
+        # Check that merged settings were passed (top_k overridden)
+        call_args = mock_app.plugin_connector.call_rag_retrieve.call_args
+        assert call_args[0][1]['retrieval_settings']['top_k'] == 20
+
+    @pytest.mark.asyncio
+    async def test_retrieve_adds_default_top_k(self):
+        """Test that default top_k=5 is added when not specified."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.retrieval_settings = {}
+
+        mock_app.plugin_connector.call_rag_retrieve = AsyncMock(return_value={'results': []})
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        await runtime_kb.retrieve('query text')
+
+        call_args = mock_app.plugin_connector.call_rag_retrieve.call_args
+        assert call_args[0][1]['retrieval_settings']['top_k'] == 5
+
+    @pytest.mark.asyncio
+    async def test_retrieve_converts_dict_to_entry(self):
+        """Test that dict results are converted to RetrievalResultEntry."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        # Mock response with valid RetrievalResultEntry fields
+        # content must be list of ContentElement dicts
+        mock_app.plugin_connector.call_rag_retrieve = AsyncMock(
+            return_value={
+                'results': [
+                    {
+                        'id': 'doc1',
+                        'content': [{'type': 'text', 'text': 'test content'}],
+                        'metadata': {'source': 'file.pdf'},
+                        'distance': 0.15,
+                    }
+                ]
+            }
+        )
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        results = await runtime_kb.retrieve('query')
+
+        assert len(results) == 1
+        # Result should be RetrievalResultEntry
+        assert hasattr(results[0], 'content')
+        assert results[0].id == 'doc1'
+
+
+class TestRuntimeKnowledgeBaseDispose:
+    """Tests for RuntimeKnowledgeBase dispose method."""
+
+    @pytest.mark.asyncio
+    async def test_dispose_calls_on_kb_delete(self):
+        """Test that dispose calls _on_kb_delete."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        mock_app.plugin_connector.rag_on_kb_delete = AsyncMock()
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        await runtime_kb.dispose()
+
+        mock_app.plugin_connector.rag_on_kb_delete.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_dispose_skips_when_no_plugin_id(self):
+        """Test that dispose skips when no plugin ID."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.knowledge_engine_plugin_id = None
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        await runtime_kb.dispose()
+
+        # Should not call plugin connector
+        mock_app.plugin_connector.rag_on_kb_delete.assert_not_called()
+
+
+class TestRAGManagerInit:
+    """Tests for RAGManager initialization."""
+
+    def test_init_stores_app_reference(self):
+        """Test that __init__ stores Application reference."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        assert manager.ap is mock_app
+
+    def test_init_creates_empty_knowledge_bases_dict(self):
+        """Test that knowledge_bases starts as empty dict."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        assert manager.knowledge_bases == {}
+
+
+class TestRAGManagerGetKnowledgeBase:
+    """Tests for RAGManager get methods."""
+
+    @pytest.mark.asyncio
+    async def test_get_knowledge_base_by_uuid_returns_runtime_kb(self):
+        """Test get_knowledge_base_by_uuid returns loaded KB."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+        mock_kb = create_mock_kb_entity()
+
+        # Manually add to knowledge_bases
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        manager.knowledge_bases[mock_kb.uuid] = runtime_kb
+
+        result = await manager.get_knowledge_base_by_uuid(mock_kb.uuid)
+
+        assert result is runtime_kb
+
+    @pytest.mark.asyncio
+    async def test_get_knowledge_base_by_uuid_returns_none_when_not_found(self):
+        """Test returns None when KB not in runtime."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        result = await manager.get_knowledge_base_by_uuid('nonexistent-uuid')
+
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_remove_knowledge_base_from_runtime(self):
+        """Test remove_knowledge_base_from_runtime removes KB."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+        mock_kb = create_mock_kb_entity()
+
+        # Add to knowledge_bases
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        manager.knowledge_bases[mock_kb.uuid] = runtime_kb
+
+        await manager.remove_knowledge_base_from_runtime(mock_kb.uuid)
+
+        assert mock_kb.uuid not in manager.knowledge_bases
+
+
+class TestRAGManagerEnrichKB:
+    """Tests for _enrich_kb_dict method."""
+
+    def test_enrich_adds_engine_info_from_map(self):
+        """Test that engine info is added from engine_map."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb_dict = {'knowledge_engine_plugin_id': 'author/engine'}
+        engine_map = {
+            'author/engine': {
+                'plugin_id': 'author/engine',
+                'name': 'Test Engine',
+                'capabilities': ['doc_ingestion', 'search'],
+            }
+        }
+
+        manager._enrich_kb_dict(kb_dict, engine_map)
+
+        assert 'knowledge_engine' in kb_dict
+        assert kb_dict['knowledge_engine']['plugin_id'] == 'author/engine'
+        assert kb_dict['knowledge_engine']['capabilities'] == ['doc_ingestion', 'search']
+
+    def test_enrich_uses_fallback_when_engine_not_in_map(self):
+        """Test that fallback info is used when engine not found."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb_dict = {'knowledge_engine_plugin_id': 'unknown/engine'}
+        engine_map = {}
+
+        manager._enrich_kb_dict(kb_dict, engine_map)
+
+        assert 'knowledge_engine' in kb_dict
+        assert kb_dict['knowledge_engine']['plugin_id'] == 'unknown/engine'
+        assert kb_dict['knowledge_engine']['capabilities'] == []
+
+    def test_enrich_uses_fallback_when_no_plugin_id(self):
+        """Test that fallback is used when no plugin ID."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb_dict = {}
+        engine_map = {}
+
+        manager._enrich_kb_dict(kb_dict, engine_map)
+
+        assert 'knowledge_engine' in kb_dict
+        # Should have Internal (Legacy) name
+        assert 'en_US' in kb_dict['knowledge_engine']['name']
+
+    def test_enrich_converts_string_name_to_i18n(self):
+        """Test that engine name is converted to i18n dict."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb_dict = {'knowledge_engine_plugin_id': 'author/engine'}
+        engine_map = {
+            'author/engine': {
+                'plugin_id': 'author/engine',
+                'name': 'Simple Name',  # String, not dict
+                'capabilities': [],
+            }
+        }
+
+        manager._enrich_kb_dict(kb_dict, engine_map)
+
+        # Name should be converted to i18n dict
+        engine_name = kb_dict['knowledge_engine']['name']
+        assert isinstance(engine_name, dict)
+        assert engine_name['en_US'] == 'Simple Name'
+
+
+class TestRAGManagerDeleteKnowledgeBase:
+    """Tests for delete_knowledge_base method."""
+
+    @pytest.mark.asyncio
+    async def test_delete_removes_from_runtime_and_disposes(self):
+        """Test that delete removes KB and calls dispose."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+        mock_kb = create_mock_kb_entity()
+
+        # Add to knowledge_bases
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        manager.knowledge_bases[mock_kb.uuid] = runtime_kb
+
+        await manager.delete_knowledge_base(mock_kb.uuid)
+
+        assert mock_kb.uuid not in manager.knowledge_bases
+
+    @pytest.mark.asyncio
+    async def test_delete_logs_warning_when_not_in_runtime(self):
+        """Test that warning is logged when KB not in runtime."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        await manager.delete_knowledge_base('nonexistent-uuid')
+
+        mock_app.logger.warning.assert_called_once()
+
+
+class TestRAGManagerGetAllDetails:
+    """Tests for get_all_knowledge_base_details method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_list_when_no_kbs(self):
+        """Test returns empty list when no knowledge bases."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_app.persistence_mgr.execute_async = AsyncMock(return_value=Mock(all=Mock(return_value=[])))
+
+        manager = rag_module.RAGManager(mock_app)
+        result = await manager.get_all_knowledge_base_details()
+
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_enriches_each_kb_with_engine_info(self):
+        """Test that each KB is enriched with engine info."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        # Mock DB result
+        mock_kb_row = Mock()
+        mock_app.persistence_mgr.execute_async = AsyncMock(return_value=Mock(all=Mock(return_value=[mock_kb_row])))
+        mock_app.persistence_mgr.serialize_model = Mock(
+            return_value={'uuid': 'kb1', 'knowledge_engine_plugin_id': 'author/engine'}
+        )
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(
+            return_value=[{'plugin_id': 'author/engine', 'name': 'Engine', 'capabilities': ['search']}]
+        )
+
+        manager = rag_module.RAGManager(mock_app)
+        result = await manager.get_all_knowledge_base_details()
+
+        assert len(result) == 1
+        assert 'knowledge_engine' in result[0]
+
+
+class TestRAGManagerGetDetails:
+    """Tests for get_knowledge_base_details method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_none_when_kb_not_found(self):
+        """Test returns None when KB doesn't exist."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_app.persistence_mgr.execute_async = AsyncMock(return_value=Mock(first=Mock(return_value=None)))
+
+        manager = rag_module.RAGManager(mock_app)
+        result = await manager.get_knowledge_base_details('nonexistent')
+
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_returns_enriched_kb_dict(self):
+        """Test returns enriched KB dict when found."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        mock_kb_row = Mock()
+        mock_app.persistence_mgr.execute_async = AsyncMock(return_value=Mock(first=Mock(return_value=mock_kb_row)))
+        mock_app.persistence_mgr.serialize_model = Mock(
+            return_value={'uuid': 'kb1', 'knowledge_engine_plugin_id': 'author/engine'}
+        )
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(
+            return_value=[{'plugin_id': 'author/engine', 'name': 'Engine', 'capabilities': []}]
+        )
+
+        manager = rag_module.RAGManager(mock_app)
+        result = await manager.get_knowledge_base_details('kb1')
+
+        assert result is not None
+        assert 'knowledge_engine' in result
+
+
+class TestRAGManagerLoadKnowledgeBase:
+    """Tests for load_knowledge_base method."""
+
+    @pytest.mark.asyncio
+    async def test_loads_kb_entity_into_runtime(self):
+        """Test that KB entity is loaded into runtime."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+        mock_kb = create_mock_kb_entity()
+
+        result = await manager.load_knowledge_base(mock_kb)
+
+        assert mock_kb.uuid in manager.knowledge_bases
+        assert result.get_uuid() == mock_kb.uuid
+
+    @pytest.mark.asyncio
+    async def test_load_handles_dict_entity(self):
+        """Test that dict entity is converted to KB object."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb_dict = {
+            'uuid': 'kb-uuid',
+            'name': 'Test',
+            'knowledge_engine_plugin_id': 'author/engine',
+            'knowledge_engine': {'name': 'should_be_filtered'},  # non-db field
+        }
+
+        await manager.load_knowledge_base(kb_dict)
+
+        assert 'kb-uuid' in manager.knowledge_bases

tests/unit_tests/rag/test_runtime_service.py

@@ -0,0 +1,521 @@
+"""Tests for RAGRuntimeService.
+
+Tests the service that handles RAG-related requests from plugins,
+using mocked vector_db_mgr and storage_mgr.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+import pytest
+
+from tests.utils.import_isolation import isolated_sys_modules
+
+
+class TestRAGRuntimeServiceVectorUpsert:
+    """Tests for vector_upsert method."""
+
+    def _create_mock_app(self):
+        """Create mock app with vector_db_mgr and storage_mgr."""
+        mock_app = MagicMock()
+        mock_app.vector_db_mgr = MagicMock()
+        mock_app.vector_db_mgr.upsert = AsyncMock()
+        mock_app.storage_mgr = MagicMock()
+        mock_app.storage_mgr.storage_provider = MagicMock()
+        mock_app.storage_mgr.storage_provider.load = AsyncMock(return_value=b'content')
+        return mock_app
+
+    def _make_rag_import_mocks(self):
+        """Create mocks needed for importing RAG service."""
+        return {
+            'langbot.pkg.core.app': MagicMock(),
+            'langbot_plugin.api.entities.builtin.rag': MagicMock(),
+        }
+
+    @pytest.mark.asyncio
+    async def test_vector_upsert_basic(self):
+        """Basic vector upsert delegates to vector_db_mgr."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            vectors = [[0.1, 0.2], [0.3, 0.4]]
+            ids = ['id1', 'id2']
+
+            await service.vector_upsert(
+                collection_id='test_collection',
+                vectors=vectors,
+                ids=ids,
+            )
+
+            mock_app.vector_db_mgr.upsert.assert_called_once()
+            call_args = mock_app.vector_db_mgr.upsert.call_args
+            assert call_args.kwargs['collection_name'] == 'test_collection'
+            assert call_args.kwargs['vectors'] == vectors
+            assert call_args.kwargs['ids'] == ids
+            # Default metadata is empty dicts
+            assert call_args.kwargs['metadata'] == [{} for _ in vectors]
+
+    @pytest.mark.asyncio
+    async def test_vector_upsert_with_metadata(self):
+        """Vector upsert with provided metadata."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            vectors = [[0.1, 0.2]]
+            ids = ['id1']
+            metadata = [{'file_id': 'abc', 'page': 1}]
+
+            await service.vector_upsert(
+                collection_id='test',
+                vectors=vectors,
+                ids=ids,
+                metadata=metadata,
+            )
+
+            call_args = mock_app.vector_db_mgr.upsert.call_args
+            assert call_args.kwargs['metadata'] == metadata
+
+    @pytest.mark.asyncio
+    async def test_vector_upsert_with_documents(self):
+        """Vector upsert with documents for full-text search."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            vectors = [[0.1, 0.2]]
+            ids = ['id1']
+            documents = ['This is a test document']
+
+            await service.vector_upsert(
+                collection_id='test',
+                vectors=vectors,
+                ids=ids,
+                documents=documents,
+            )
+
+            call_args = mock_app.vector_db_mgr.upsert.call_args
+            assert call_args.kwargs['documents'] == documents
+
+
+class TestRAGRuntimeServiceVectorSearch:
+    """Tests for vector_search method."""
+
+    def _create_mock_app(self):
+        """Create mock app."""
+        mock_app = MagicMock()
+        mock_app.vector_db_mgr = MagicMock()
+        mock_app.vector_db_mgr.search = AsyncMock(
+            return_value=[
+                {'id': 'id1', 'distance': 0.1, 'metadata': {'file_id': 'abc'}},
+                {'id': 'id2', 'distance': 0.2, 'metadata': {'file_id': 'def'}},
+            ]
+        )
+        return mock_app
+
+    def _make_rag_import_mocks(self):
+        return {
+            'langbot.pkg.core.app': MagicMock(),
+            'langbot_plugin.api.entities.builtin.rag': MagicMock(),
+        }
+
+    @pytest.mark.asyncio
+    async def test_vector_search_basic(self):
+        """Basic vector search delegates to vector_db_mgr."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            query_vector = [0.1, 0.2, 0.3]
+
+            result = await service.vector_search(
+                collection_id='test',
+                query_vector=query_vector,
+                top_k=5,
+            )
+
+            assert len(result) == 2
+            mock_app.vector_db_mgr.search.assert_called_once()
+            call_args = mock_app.vector_db_mgr.search.call_args
+            assert call_args.kwargs['collection_name'] == 'test'
+            assert call_args.kwargs['query_vector'] == query_vector
+            assert call_args.kwargs['limit'] == 5
+
+    @pytest.mark.asyncio
+    async def test_vector_search_with_filters(self):
+        """Vector search with metadata filters."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            filters = {'file_id': 'abc'}
+
+            await service.vector_search(
+                collection_id='test',
+                query_vector=[0.1, 0.2],
+                top_k=10,
+                filters=filters,
+            )
+
+            call_args = mock_app.vector_db_mgr.search.call_args
+            assert call_args.kwargs['filter'] == filters
+
+    @pytest.mark.asyncio
+    async def test_vector_search_hybrid_mode(self):
+        """Vector search with hybrid search type."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            await service.vector_search(
+                collection_id='test',
+                query_vector=[0.1, 0.2],
+                top_k=10,
+                search_type='hybrid',
+                query_text='search query',
+                vector_weight=0.7,
+            )
+
+            call_args = mock_app.vector_db_mgr.search.call_args
+            assert call_args.kwargs['search_type'] == 'hybrid'
+            assert call_args.kwargs['query_text'] == 'search query'
+            assert call_args.kwargs['vector_weight'] == 0.7
+
+
+class TestRAGRuntimeServiceVectorDelete:
+    """Tests for vector_delete method."""
+
+    def _create_mock_app(self):
+        mock_app = MagicMock()
+        mock_app.vector_db_mgr = MagicMock()
+        mock_app.vector_db_mgr.delete_by_file_id = AsyncMock()
+        mock_app.vector_db_mgr.delete_by_filter = AsyncMock(return_value=5)
+        return mock_app
+
+    def _make_rag_import_mocks(self):
+        return {
+            'langbot.pkg.core.app': MagicMock(),
+            'langbot_plugin.api.entities.builtin.rag': MagicMock(),
+        }
+
+    @pytest.mark.asyncio
+    async def test_vector_delete_by_file_ids(self):
+        """Delete by file_ids delegates to delete_by_file_id."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            result = await service.vector_delete(
+                collection_id='test',
+                file_ids=['file1', 'file2', 'file3'],
+            )
+
+            assert result == 3  # Returns count of file_ids
+            mock_app.vector_db_mgr.delete_by_file_id.assert_called_once()
+            call_args = mock_app.vector_db_mgr.delete_by_file_id.call_args
+            assert call_args.kwargs['collection_name'] == 'test'
+            assert call_args.kwargs['file_ids'] == ['file1', 'file2', 'file3']
+
+    @pytest.mark.asyncio
+    async def test_vector_delete_by_filters(self):
+        """Delete by filters delegates to delete_by_filter."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            filters = {'status': 'deleted'}
+
+            result = await service.vector_delete(
+                collection_id='test',
+                filters=filters,
+            )
+
+            assert result == 5  # Returns count from delete_by_filter
+            mock_app.vector_db_mgr.delete_by_filter.assert_called_once()
+            call_args = mock_app.vector_db_mgr.delete_by_filter.call_args
+            assert call_args.kwargs['collection_name'] == 'test'
+            assert call_args.kwargs['filter'] == filters
+
+    @pytest.mark.asyncio
+    async def test_vector_delete_no_params(self):
+        """Delete with no params returns 0."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            result = await service.vector_delete(collection_id='test')
+
+            assert result == 0
+            mock_app.vector_db_mgr.delete_by_file_id.assert_not_called()
+            mock_app.vector_db_mgr.delete_by_filter.assert_not_called()
+
+
+class TestRAGRuntimeServiceVectorList:
+    """Tests for vector_list method."""
+
+    def _create_mock_app(self):
+        mock_app = MagicMock()
+        mock_app.vector_db_mgr = MagicMock()
+        mock_app.vector_db_mgr.list_by_filter = AsyncMock(
+            return_value=([{'id': 'id1', 'metadata': {'file_id': 'abc'}}], 10)
+        )
+        return mock_app
+
+    def _make_rag_import_mocks(self):
+        return {
+            'langbot.pkg.core.app': MagicMock(),
+            'langbot_plugin.api.entities.builtin.rag': MagicMock(),
+        }
+
+    @pytest.mark.asyncio
+    async def test_vector_list_basic(self):
+        """Basic vector list delegates to vector_db_mgr."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            items, total = await service.vector_list(
+                collection_id='test',
+            )
+
+            assert len(items) == 1
+            assert total == 10
+            mock_app.vector_db_mgr.list_by_filter.assert_called_once()
+            call_args = mock_app.vector_db_mgr.list_by_filter.call_args
+            assert call_args.kwargs['collection_name'] == 'test'
+            assert call_args.kwargs['limit'] == 20  # Default
+            assert call_args.kwargs['offset'] == 0  # Default
+
+    @pytest.mark.asyncio
+    async def test_vector_list_with_pagination(self):
+        """Vector list with custom pagination."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            await service.vector_list(
+                collection_id='test',
+                limit=50,
+                offset=100,
+            )
+
+            call_args = mock_app.vector_db_mgr.list_by_filter.call_args
+            assert call_args.kwargs['limit'] == 50
+            assert call_args.kwargs['offset'] == 100
+
+    @pytest.mark.asyncio
+    async def test_vector_list_with_filters(self):
+        """Vector list with metadata filters."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            filters = {'file_id': 'abc'}
+
+            await service.vector_list(
+                collection_id='test',
+                filters=filters,
+            )
+
+            call_args = mock_app.vector_db_mgr.list_by_filter.call_args
+            assert call_args.kwargs['filter'] == filters
+
+
+class TestRAGRuntimeServiceGetFileStream:
+    """Tests for get_file_stream method."""
+
+    def _create_mock_app(self):
+        mock_app = MagicMock()
+        mock_app.vector_db_mgr = MagicMock()
+        mock_app.storage_mgr = MagicMock()
+        mock_app.storage_mgr.storage_provider = MagicMock()
+        mock_app.storage_mgr.storage_provider.load = AsyncMock(return_value=b'file content')
+        return mock_app
+
+    def _make_rag_import_mocks(self):
+        return {
+            'langbot.pkg.core.app': MagicMock(),
+            'langbot_plugin.api.entities.builtin.rag': MagicMock(),
+        }
+
+    @pytest.mark.asyncio
+    async def test_get_file_stream_basic(self):
+        """Get file stream loads from storage."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            result = await service.get_file_stream('knowledge/files/doc.pdf')
+
+            assert result == b'file content'
+            mock_app.storage_mgr.storage_provider.load.assert_called_once_with('knowledge/files/doc.pdf')
+
+    @pytest.mark.asyncio
+    async def test_get_file_stream_empty_result(self):
+        """Empty file returns empty bytes."""
+        mock_app = self._create_mock_app()
+        mock_app.storage_mgr.storage_provider.load = AsyncMock(return_value=None)
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            result = await service.get_file_stream('nonexistent.pdf')
+
+            assert result == b''
+
+    @pytest.mark.asyncio
+    async def test_get_file_stream_normalizes_safe_path(self):
+        """Safe relative paths are normalized before loading."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            result = await service.get_file_stream('knowledge/./files/doc.pdf')
+
+            assert result == b'file content'
+            mock_app.storage_mgr.storage_provider.load.assert_called_once_with('knowledge/files/doc.pdf')
+
+    @pytest.mark.asyncio
+    async def test_get_file_stream_path_traversal_blocked(self):
+        """Path traversal attacks are blocked."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            # Absolute path should raise ValueError
+            with pytest.raises(ValueError, match='Invalid storage path'):
+                await service.get_file_stream('/etc/passwd')
+
+            # Path traversal should raise ValueError
+            with pytest.raises(ValueError, match='Invalid storage path'):
+                await service.get_file_stream('knowledge/../../../etc/passwd')
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        'storage_path',
+        [
+            '',
+            '../secret.txt',
+            '/absolute/path.txt',
+            '..\\secret.txt',
+            'nested\\..\\secret.txt',
+            '%2e%2e/secret.txt',
+            'nested/%2e%2e/secret.txt',
+            'C:\\secret.txt',
+            'safe/\x00file.txt',
+        ],
+    )
+    async def test_get_file_stream_rejects_unsafe_paths(self, storage_path: str):
+        """Unsafe runtime file paths are rejected before storage load."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            with pytest.raises(ValueError, match='Invalid storage path'):
+                await service.get_file_stream(storage_path)
+
+            mock_app.storage_mgr.storage_provider.load.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_get_file_stream_normalizes_path(self):
+        """Valid paths with .. in filename (not traversal) should work."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            # Path that contains '..' as part of filename (not traversal)
+            # This should NOT raise - posixpath.normpath handles this
+            # But the current implementation checks '..' in split('/')
+            # Let's test a simple valid path
+            await service.get_file_stream('knowledge/files/test.pdf')
+            mock_app.storage_mgr.storage_provider.load.assert_called()