fix(vector): correct SeekDB adapter semantics (#2536)

tests/integration/vector/test_seekdb.py

@@ -0,0 +1,123 @@
+"""Real embedded SeekDB regression tests.
+
+Install the optional dependency before running these slow tests::
+
+    uv sync --dev --extra seekdb
+    uv run pytest tests/integration/vector/test_seekdb.py -m slow -q
+"""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+import uuid
+
+import pytest
+
+pytest.importorskip('pyseekdb')
+
+from langbot.pkg.vector.vdbs.seekdb import SeekDBVectorDatabase
+
+
+pytestmark = [pytest.mark.integration, pytest.mark.slow]
+
+
+@pytest.fixture
+async def backend(tmp_path):
+    app = SimpleNamespace(
+        instance_config=SimpleNamespace(
+            data={
+                'vdb': {
+                    'runtime_cache_limit': 16,
+                    'seekdb': {
+                        'mode': 'embedded',
+                        'path': str(tmp_path),
+                        'database': 'langbot_test',
+                    },
+                }
+            }
+        ),
+        logger=SimpleNamespace(
+            info=lambda *args, **kwargs: None,
+            warning=lambda *args, **kwargs: None,
+        ),
+    )
+    database = SeekDBVectorDatabase(app)
+    collection = f'test_{uuid.uuid4().hex}'
+    yield database, collection
+
+    await database.delete_collection(collection)
+    await database.close()
+
+
+@pytest.mark.asyncio
+async def test_upsert_and_text_round_trip(backend) -> None:
+    database, collection = backend
+    original = 'He said "hello".\nC:\\notes\\file.txt isn\'t empty. 中文'
+    updated = f'Updated: {original}'
+
+    await database.add_embeddings(
+        collection,
+        ['document-a'],
+        [[1.0, 0.0, 0.0]],
+        [{'file_id': 'file-a', 'text': original}],
+        [original],
+    )
+    await database.add_embeddings(
+        collection,
+        ['document-a'],
+        [[0.0, 1.0, 0.0]],
+        [{'file_id': 'file-a', 'text': updated}],
+        [updated],
+    )
+
+    items, _ = await database.list_by_filter(collection, {'file_id': 'file-a'})
+
+    assert len(items) == 1
+    assert items[0]['id'] == 'document-a'
+    assert items[0]['document'] == updated
+    assert items[0]['metadata']['text'] == updated
+
+
+@pytest.mark.asyncio
+async def test_full_text_and_hybrid_results_keep_relevance_order(backend) -> None:
+    database, collection = backend
+    documents = [
+        'orchid orchid orchid flower',
+        'orchid grows in a garden with many other beautiful plants',
+        'a completely unrelated topic',
+    ]
+
+    await database.add_embeddings(
+        collection,
+        ['best', 'weak', 'noise'],
+        [[1.0, 0.0, 0.0], [0.9, 0.1, 0.0], [0.0, 0.0, 1.0]],
+        [
+            {'file_id': item_id, 'document_id': item_id, 'text': document}
+            for item_id, document in zip(['best', 'weak', 'noise'], documents, strict=True)
+        ],
+        documents,
+    )
+    seekdb_collection = await database.get_or_create_collection(collection)
+    await asyncio.to_thread(seekdb_collection.refresh_index)
+
+    full_text = await database.search(
+        collection,
+        [1.0, 0.0, 0.0],
+        k=3,
+        search_type='full_text',
+        query_text='orchid',
+    )
+    hybrid = await database.search(
+        collection,
+        [1.0, 0.0, 0.0],
+        k=3,
+        search_type='hybrid',
+        query_text='orchid',
+        vector_weight=0.65,
+    )
+
+    assert full_text['ids'][0][:2] == ['best', 'weak']
+    assert full_text['distances'][0] == sorted(full_text['distances'][0])
+    assert hybrid['ids'][0] == ['best', 'weak', 'noise']
+    assert hybrid['distances'][0] == sorted(hybrid['distances'][0])

tests/unit_tests/test_optional_dependencies.py

@@ -12,4 +12,7 @@ def test_seekdb_is_only_declared_as_an_optional_dependency() -> None:
     project = pyproject['project']
     base_dependencies = project['dependencies']
     assert not any(dependency.lower().startswith('pyseekdb') for dependency in base_dependencies)
-    assert project['optional-dependencies']['seekdb'] == ['pyseekdb==1.1.0.post3']
+    assert project['optional-dependencies']['seekdb'] == [
+        'pyseekdb==1.4.0.post1',
+        "pylibseekdb==1.4.0; sys_platform == 'linux' or (sys_platform == 'darwin' and platform_machine == 'arm64')",
+    ]

tests/unit_tests/vector/test_seekdb.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from langbot.pkg.vector.vdbs.seekdb import SeekDBVectorDatabase
+
+
+def _adapter_with_collection(collection: MagicMock) -> SeekDBVectorDatabase:
+    adapter = SeekDBVectorDatabase.__new__(SeekDBVectorDatabase)
+    adapter.ap = SimpleNamespace(logger=MagicMock())
+    adapter.client = MagicMock()
+    adapter.client.has_collection.return_value = True
+    adapter._collections = {'knowledge_base': collection}
+    adapter._runtime_cache_limit = 16
+    return adapter
+
+
+@pytest.mark.asyncio
+async def test_add_embeddings_upserts_and_preserves_text() -> None:
+    collection = MagicMock()
+    adapter = _adapter_with_collection(collection)
+    adapter._get_or_create_collection_internal = AsyncMock(return_value=collection)
+    original = 'He said "hello".\nC:\\notes\\file.txt isn\'t empty. 中文'
+
+    await adapter.add_embeddings(
+        collection='knowledge_base',
+        ids=['document-a'],
+        embeddings_list=[[1.0, 0.0, 0.0]],
+        metadatas=[{'text': original}],
+        documents=[original],
+    )
+
+    collection.upsert.assert_called_once_with(
+        ids=['document-a'],
+        embeddings=[[1.0, 0.0, 0.0]],
+        metadatas=[{'text': original}],
+        documents=[original],
+    )
+    collection.add.assert_not_called()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ('search_type', 'scores', 'expected_distances'),
+    [
+        ('full_text', [0.4508196721, 0.25], [0.5491803279, 0.75]),
+        ('hybrid', [0.0328, 0.0323, 0.0159], [0.9672, 0.9677, 0.9841]),
+    ],
+)
+async def test_search_converts_relevance_scores_to_distances(
+    search_type: str,
+    scores: list[float],
+    expected_distances: list[float],
+) -> None:
+    collection = MagicMock()
+    collection.hybrid_search.return_value = {
+        'ids': [['best', 'weak', 'noise'][: len(scores)]],
+        'metadatas': [[{} for _ in scores]],
+        'distances': [scores],
+    }
+    adapter = _adapter_with_collection(collection)
+
+    results = await adapter.search(
+        collection='knowledge_base',
+        query_embedding=[1.0, 0.0, 0.0],
+        k=len(scores),
+        search_type=search_type,
+        query_text='orchid',
+        vector_weight=0.65,
+    )
+
+    assert results['distances'][0] == pytest.approx(expected_distances)
+    assert results['distances'][0] == sorted(results['distances'][0])
+
+
+@pytest.mark.asyncio
+async def test_vector_search_keeps_seekdb_cosine_distances() -> None:
+    collection = MagicMock()
+    collection.query.return_value = {
+        'ids': [['best', 'weak']],
+        'metadatas': [[{}, {}]],
+        'distances': [[0.1, 0.25]],
+    }
+    adapter = _adapter_with_collection(collection)
+
+    results = await adapter.search(
+        collection='knowledge_base',
+        query_embedding=[1.0, 0.0, 0.0],
+        k=2,
+        search_type='vector',
+    )
+
+    assert results['distances'] == [[0.1, 0.25]]