~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""
Tests for semantic search functionality in Notes.
"""
import pytest
from unittest.mock import MagicMock, patch
from local_deep_research.database.models import Document
from tests.notes.helpers import seed_note_documents
class TestSemanticSearchService:
"""Tests for NoteAIService.semantic_search method."""
@pytest.fixture
def sample_notes(self, db_session):
"""Create sample notes for testing."""
import uuid
from datetime import datetime, UTC
notes = [
Document(
id=str(uuid.uuid4()),
title="Machine Learning Basics",
text_content="Introduction to neural networks and deep learning concepts.",
tags=["ml", "ai"],
created_at=datetime.now(UTC),
updated_at=datetime.now(UTC),
),
Document(
id=str(uuid.uuid4()),
title="Python Programming",
text_content="Guide to Python syntax, data structures, and best practices.",
tags=["python", "programming"],
created_at=datetime.now(UTC),
updated_at=datetime.now(UTC),
),
Document(
id=str(uuid.uuid4()),
title="Database Design",
text_content="SQL fundamentals, schema design, and normalization principles.",
tags=["database", "sql"],
created_at=datetime.now(UTC),
updated_at=datetime.now(UTC),
),
]
for note in notes:
db_session.add(note)
db_session.commit()
return notes
def test_semantic_search_empty_query(self):
"""Empty query returns empty list."""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
service = NoteAIService("test_user")
result = service.semantic_search("")
assert result == []
def test_semantic_search_whitespace_query(self):
"""Whitespace-only query returns empty list."""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
service = NoteAIService("test_user")
result = service.semantic_search(" ")
assert result == []
def _mock_faiss_search(self, raw_results):
"""Helper: set up mocks for CollectionSearchEngine-backed semantic_search."""
from contextlib import contextmanager
# Mock get_user_db_session for both collection lookup and enrichment
mock_session_ctx = MagicMock()
# Collection lookup: _get_or_create_notes_collection returns a UUID
mock_collection = MagicMock()
mock_collection.id = "notes-collection-id"
mock_session_ctx.query.return_value.filter_by.return_value.first.return_value = mock_collection
# Enrichment: Document.id.in_() query
mock_session_ctx.query.return_value.filter.return_value.all.return_value = []
@contextmanager
def mock_db_session(username, password=None):
yield mock_session_ctx
return mock_db_session, mock_session_ctx
@staticmethod
def _real_session_env(monkeypatch, db_session):
"""Patch semantic_search's collaborators to run against a real
``db_session`` so the orphan filter resolves against seeded Document
rows. Returns the ``get_user_db_session`` replacement (caller applies
it via ``patch(..., side_effect=...)``)."""
from contextlib import contextmanager
from local_deep_research.research_library.notes.services.note_service import (
NoteService,
)
# Avoid touching the real DB for collection resolution.
monkeypatch.setattr(
NoteService,
"_get_or_create_notes_collection",
lambda self, session: "notes-collection-id",
)
@contextmanager
def real_db_session(username, password=None):
yield db_session
return real_db_session
def test_semantic_search_returns_list(self):
"""Semantic search returns a list (via CollectionSearchEngine)."""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
mock_db_session, _ = self._mock_faiss_search([])
with patch(
"local_deep_research.research_library.notes.services.note_ai_service.get_user_db_session",
side_effect=mock_db_session,
):
with patch(
"local_deep_research.web_search_engines.engines.search_engine_collection.CollectionSearchEngine",
) as MockEngine:
MockEngine.return_value.search.return_value = []
service = NoteAIService("test_user")
result = service.semantic_search("machine learning")
# Exactly empty — zero engine hits must not fabricate
# results (a bare isinstance check passed for ANY list).
assert result == []
def test_semantic_search_result_structure(self):
"""Semantic search results have correct structure."""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
mock_doc = MagicMock()
mock_doc.id = "test-id-123"
mock_doc.tags = ["test", "example"]
mock_doc.created_at = None
mock_doc.favorite = False
mock_db_session, mock_ctx = self._mock_faiss_search([])
# Enrichment query returns our mock doc
mock_ctx.query.return_value.filter.return_value.all.return_value = [
mock_doc
]
with patch(
"local_deep_research.research_library.notes.services.note_ai_service.get_user_db_session",
side_effect=mock_db_session,
):
with patch(
"local_deep_research.web_search_engines.engines.search_engine_collection.CollectionSearchEngine",
) as MockEngine:
MockEngine.return_value.search.return_value = [
{
"title": "Test Note",
"snippet": "This is test content",
"relevance_score": 0.8,
"metadata": {"document_id": "test-id-123"},
}
]
service = NoteAIService("test_user")
results = service.semantic_search("test query")
assert len(results) == 1
result = results[0]
assert "id" in result
assert "title" in result
assert "content_preview" in result
assert "similarity" in result
assert "tags" in result
assert "created_at" in result
assert "pinned" in result
def test_semantic_search_respects_limit(
self, monkeypatch, db_session, note_source_type
):
"""Semantic search respects limit parameter.
Seeds a real Document row for every FAISS hit so the orphan guard
(``if doc_id not in doc_lookup: continue``) doesn't drop every
candidate before the limit-clamp is ever exercised (the previous
version of this test used the plain mock, whose enrichment query
always returned ``[]``, so ``results`` was unconditionally ``[]``
and ``len(results) <= 5`` passed no matter what the limit logic
did).
"""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
raw_results = [
{
"title": f"Note {i}",
"snippet": f"Content {i}",
"relevance_score": 0.8 - i * 0.05,
"metadata": {"document_id": f"note-{i}"},
}
for i in range(10)
]
seed_note_documents(
db_session, note_source_type.id, [f"note-{i}" for i in range(10)]
)
real_db_session = self._real_session_env(monkeypatch, db_session)
with patch(
"local_deep_research.research_library.notes.services.note_ai_service.get_user_db_session",
side_effect=real_db_session,
):
with patch(
"local_deep_research.web_search_engines.engines.search_engine_collection.CollectionSearchEngine",
) as MockEngine:
MockEngine.return_value.search.return_value = raw_results
service = NoteAIService("test_user")
results = service.semantic_search("test", limit=5)
assert len(results) == 5
# raw_results are relevance-ordered (pre-sorted); the
# break-at-limit must keep the first 5 (highest-scoring),
# not an arbitrary 5.
assert [r["id"] for r in results] == [
f"note-{i}" for i in range(5)
]
def test_semantic_search_filters_by_min_similarity(self):
"""Semantic search filters results below min_similarity threshold."""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
mock_db_session, _ = self._mock_faiss_search([])
with patch(
"local_deep_research.research_library.notes.services.note_ai_service.get_user_db_session",
side_effect=mock_db_session,
):
with patch(
"local_deep_research.web_search_engines.engines.search_engine_collection.CollectionSearchEngine",
) as MockEngine:
MockEngine.return_value.search.return_value = [
{
"title": "Low Sim Note",
"snippet": "content",
"relevance_score": 0.2,
"metadata": {"document_id": "low-sim"},
}
]
service = NoteAIService("test_user")
results = service.semantic_search("test", min_similarity=0.5)
assert len(results) == 0
def test_semantic_search_min_similarity_boundary_is_exclusive(
self, monkeypatch, db_session, note_source_type
):
"""A hit scoring EXACTLY at min_similarity is KEPT; only strictly
below is dropped.
The gate at note_ai_service.py:881 is ``if score < min_similarity:
continue`` (strict less-than). The UI sends 0.25 while the default is
0.3, and quantized FAISS scores commonly land exactly on the
threshold, so the == case is load-bearing. The existing
test_semantic_search_filters_by_min_similarity uses a 0.2 hit vs a 0.5
threshold (far below) and would still pass under a broken ``<=``; this
test is what catches that off-by-one.
"""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
threshold = 0.3
raw_results = [
{
"title": "Equal",
"snippet": "content",
"relevance_score": threshold, # == threshold -> KEPT
"metadata": {"document_id": "eq"},
},
{
"title": "Below",
"snippet": "content",
"relevance_score": 0.2999, # < threshold -> DROPPED
"metadata": {"document_id": "below"},
},
{
"title": "Above",
"snippet": "content",
"relevance_score": 0.5, # > threshold -> KEPT
"metadata": {"document_id": "above"},
},
]
# Seed the Document rows for every hit so the orphan filter resolves
# them and the threshold boundary is what's actually under test.
seed_note_documents(
db_session, note_source_type.id, ["eq", "below", "above"]
)
real_db_session = self._real_session_env(monkeypatch, db_session)
with patch(
"local_deep_research.research_library.notes.services.note_ai_service.get_user_db_session",
side_effect=real_db_session,
):
with patch(
"local_deep_research.web_search_engines.engines.search_engine_collection.CollectionSearchEngine",
) as MockEngine:
MockEngine.return_value.search.return_value = raw_results
service = NoteAIService("test_user")
results = service.semantic_search(
"test", min_similarity=threshold
)
ids = {r["id"] for r in results}
assert "eq" in ids # exactly at threshold is inclusive
assert "above" in ids
assert "below" not in ids # 0.2999 < 0.3 dropped
assert len(results) == 2
def test_semantic_search_sorted_by_similarity(
self, monkeypatch, db_session, note_source_type
):
"""Semantic search results are sorted by similarity descending.
Seeds a real Document row for every FAISS hit so the orphan guard
doesn't drop every candidate (the previous version of this test
used the plain mock, whose enrichment query always returned
``[]``, so ``results`` was unconditionally ``[]`` and
``sims == sorted(sims, reverse=True)`` passed trivially on an
empty list regardless of the actual ordering logic).
"""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
# CollectionSearchEngine returns results pre-sorted by FAISS
raw_results = [
{
"title": "B",
"snippet": "b",
"relevance_score": 0.9,
"metadata": {"document_id": "b"},
},
{
"title": "C",
"snippet": "c",
"relevance_score": 0.7,
"metadata": {"document_id": "c"},
},
{
"title": "A",
"snippet": "a",
"relevance_score": 0.5,
"metadata": {"document_id": "a"},
},
]
seed_note_documents(db_session, note_source_type.id, ["b", "c", "a"])
real_db_session = self._real_session_env(monkeypatch, db_session)
with patch(
"local_deep_research.research_library.notes.services.note_ai_service.get_user_db_session",
side_effect=real_db_session,
):
with patch(
"local_deep_research.web_search_engines.engines.search_engine_collection.CollectionSearchEngine",
) as MockEngine:
MockEngine.return_value.search.return_value = raw_results
service = NoteAIService("test_user")
results = service.semantic_search("test", min_similarity=0.1)
assert len(results) == 3
sims = [r["similarity"] for r in results]
# CollectionSearchEngine returns results pre-sorted
assert sims == sorted(sims, reverse=True)
assert sims == [0.9, 0.7, 0.5]
def test_semantic_search_skips_deleted_note_orphan_hit(
self, monkeypatch, db_session, note_source_type
):
"""A FAISS hit for a deleted note (its vector lingers in the index
until reindex, but its Document row is gone) must be dropped, while a
live note's hit is kept.
This pins the orphan guard ``if doc_id not in doc_lookup: continue``
in semantic_search: reverting it would let the deleted-note hit through
and this test fails (two ids returned instead of one).
"""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
# Only the live note gets a Document row; the orphan's vector still
# surfaces from FAISS but has no backing Document.
seed_note_documents(db_session, note_source_type.id, ["live-note"])
real_db_session = self._real_session_env(monkeypatch, db_session)
raw_results = [
{
"title": "Live Note",
"snippet": "live content",
"relevance_score": 0.9,
"metadata": {"document_id": "live-note"},
},
{
"title": "Ghost Note",
"snippet": "stale content from a deleted note",
"relevance_score": 0.85,
"metadata": {"document_id": "deleted-orphan"},
},
]
with patch(
"local_deep_research.research_library.notes.services.note_ai_service.get_user_db_session",
side_effect=real_db_session,
):
with patch(
"local_deep_research.web_search_engines.engines.search_engine_collection.CollectionSearchEngine",
) as MockEngine:
MockEngine.return_value.search.return_value = raw_results
service = NoteAIService("test_user")
results = service.semantic_search("test", min_similarity=0.1)
ids = [r["id"] for r in results]
assert ids == ["live-note"] # orphan dropped, live note kept
assert "deleted-orphan" not in ids
def test_semantic_search_filters_out_non_note_documents(
self, monkeypatch, db_session, note_source_type
):
"""the FAISS index can return documents that are NOT notes (e.g.
a library document in the same per-user DB). The enrichment query is
scoped to source_type='note', so a non-note hit — even though its
Document row exists — must be dropped, not surfaced AS a note.
Reverting the source_type filter lets the non-note document through and
this test fails (two ids returned instead of one).
"""
import uuid as _uuid
from local_deep_research.database.models import Document, SourceType
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
# One genuine note...
seed_note_documents(db_session, note_source_type.id, ["live-note"])
# ...and one NON-note document with a different source_type. Its
# Document row exists, so only the source_type filter (not the orphan
# guard) can keep it out.
other_type = SourceType(
id=str(_uuid.uuid4()),
name="library",
display_name="Library",
description="Non-note document",
icon="book",
)
db_session.add(other_type)
db_session.add(
Document(
id="library-doc",
title="Library Document",
text_content="not a note",
file_type="pdf",
file_size=0,
source_type_id=other_type.id,
document_hash="hash-library-doc",
tags=[],
)
)
db_session.commit()
real_db_session = self._real_session_env(monkeypatch, db_session)
raw_results = [
{
"title": "Live Note",
"snippet": "live content",
"relevance_score": 0.9,
"metadata": {"document_id": "live-note"},
},
{
"title": "Library Document",
"snippet": "content from a non-note document",
"relevance_score": 0.88,
"metadata": {"document_id": "library-doc"},
},
]
with patch(
"local_deep_research.research_library.notes.services.note_ai_service.get_user_db_session",
side_effect=real_db_session,
):
with patch(
"local_deep_research.web_search_engines.engines.search_engine_collection.CollectionSearchEngine",
) as MockEngine:
MockEngine.return_value.search.return_value = raw_results
service = NoteAIService("test_user")
results = service.semantic_search("test", min_similarity=0.1)
ids = [r["id"] for r in results]
assert ids == ["live-note"]
assert "library-doc" not in ids
def test_semantic_search_content_preview_truncation(
self, monkeypatch, db_session, note_source_type
):
"""Long content is truncated in content_preview."""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
# Seed the Document for the hit so the orphan filter keeps it and the
# truncation behaviour can be asserted.
seed_note_documents(db_session, note_source_type.id, ["long-note"])
real_db_session = self._real_session_env(monkeypatch, db_session)
with patch(
"local_deep_research.research_library.notes.services.note_ai_service.get_user_db_session",
side_effect=real_db_session,
):
with patch(
"local_deep_research.web_search_engines.engines.search_engine_collection.CollectionSearchEngine",
) as MockEngine:
MockEngine.return_value.search.return_value = [
{
"title": "Long Note",
"snippet": "A" * 500,
"relevance_score": 0.8,
"metadata": {"document_id": "long-note"},
}
]
service = NoteAIService("test_user")
results = service.semantic_search("test")
assert len(results[0]["content_preview"]) <= 200
class TestSemanticSearchAPI:
"""Tests for the semantic search API logic."""
def test_semantic_search_query_strip(self):
"""Query is stripped of whitespace before processing."""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
service = NoteAIService("test_user")
# Empty after strip returns empty
result = service.semantic_search(" ")
assert result == []
def test_semantic_search_default_parameters(self):
"""Semantic search has sensible default parameters."""
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
import inspect
sig = inspect.signature(NoteAIService.semantic_search)
params = sig.parameters
# Check default values
assert params["limit"].default == 10
assert params["min_similarity"].default == 0.3
def test_semantic_search_propagates_exception(self):
"""Semantic search propagates infrastructure exceptions to the
caller so the route layer can return a real 500 via
handle_api_error. Pre-fix the method swallowed every Exception
and returned [] — masking LLM / DB outages as "no results found"
and confusing both operators (no error trail to alert on) and
users (silent empty UI instead of an actionable toast).
"""
import pytest
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
with patch(
"local_deep_research.research_library.notes.services.note_ai_service.get_user_db_session",
side_effect=Exception("Test error"),
):
service = NoteAIService("test_user")
with pytest.raises(Exception, match="Test error"):
service.semantic_search("test query")
def _run_with_collection_filter(self, faiss_hits, members, collection_id):
"""Run semantic_search with a model-aware session so the
DocumentCollection membership query can be exercised
independently of the Document enrichment query."""
from contextlib import contextmanager
from local_deep_research.database.models.library import (
DocumentCollection,
)
from local_deep_research.research_library.notes.services.note_ai_service import (
NoteAIService,
)
def _doc(did):
m = MagicMock()
m.id = did
m.tags = []
m.created_at = None
m.favorite = False
return m
all_ids = [
h["metadata"]["document_id"]
for h in faiss_hits
if h.get("metadata", {}).get("document_id")
]
def _query(arg):
q = MagicMock()
if arg is DocumentCollection.document_id:
# Membership query → only members, as (id,) rows.
q.filter.return_value.all.return_value = [
(i,) for i in all_ids if i in members
]
else: # Document enrichment
q.filter.return_value.all.return_value = [
_doc(i) for i in all_ids
]
return q
session = MagicMock()
session.query.side_effect = _query
@contextmanager
def mock_db_session(username, password=None):
yield session
with patch(
"local_deep_research.research_library.notes.services.note_ai_service.get_user_db_session",
side_effect=mock_db_session,
):
with patch.object(
NoteAIService,
"_get_llm",
create=True,
):
with patch(
"local_deep_research.research_library.notes.services.note_service.NoteService._get_or_create_notes_collection",
return_value="notes-collection-id",
):
with patch(
"local_deep_research.web_search_engines.engines.search_engine_collection.CollectionSearchEngine",
) as MockEngine:
MockEngine.return_value.search.return_value = faiss_hits
service = NoteAIService("test_user")
return service.semantic_search(
"q", collection_id=collection_id
)
def test_semantic_search_filters_by_collection_membership(self):
"""with a user collection_id, only notes that are members of
that collection are returned, even though the FAISS index covers all
notes."""
hits = [
{
"title": "A",
"snippet": "a",
"relevance_score": 0.9,
"metadata": {"document_id": "doc-A"},
},
{
"title": "B",
"snippet": "b",
"relevance_score": 0.85,
"metadata": {"document_id": "doc-B"},
},
]
results = self._run_with_collection_filter(
hits, members={"doc-A"}, collection_id="user-coll-1"
)
ids = [r["id"] for r in results]
assert ids == ["doc-A"] # doc-B filtered out (not a member)
def test_semantic_search_no_filter_returns_all(self):
"""No collection_id → no membership filter (all FAISS hits kept)."""
hits = [
{
"title": "A",
"snippet": "a",
"relevance_score": 0.9,
"metadata": {"document_id": "doc-A"},
},
{
"title": "B",
"snippet": "b",
"relevance_score": 0.85,
"metadata": {"document_id": "doc-B"},
},
]
results = self._run_with_collection_filter(
hits, members=set(), collection_id=None
)
assert {r["id"] for r in results} == {"doc-A", "doc-B"}
def test_semantic_search_notes_collection_id_is_not_a_filter(self):
"""Passing the system Notes collection id must NOT filter (every note
is a member of it) — otherwise the default view would self-filter."""
hits = [
{
"title": "A",
"snippet": "a",
"relevance_score": 0.9,
"metadata": {"document_id": "doc-A"},
},
]
# members empty: if it incorrectly filtered, doc-A would be dropped.
results = self._run_with_collection_filter(
hits, members=set(), collection_id="notes-collection-id"
)
assert [r["id"] for r in results] == ["doc-A"]
def test_semantic_search_empty_membership_returns_nothing(self):
"""a real (non-system) user collection that contains NONE of the
FAISS candidates drops every hit → empty result, rather than silently
returning the unfiltered notes. (members empty + a user collection_id
that is not the system Notes collection.)"""
hits = [
{
"title": "A",
"snippet": "a",
"relevance_score": 0.9,
"metadata": {"document_id": "doc-A"},
},
{
"title": "B",
"snippet": "b",
"relevance_score": 0.85,
"metadata": {"document_id": "doc-B"},
},
]
results = self._run_with_collection_filter(
hits, members=set(), collection_id="user-coll-1"
)
assert results == []
# Note: cosine-similarity unit tests were removed with the dead
# NoteAIService._cosine_similarity helper — FAISS does the real scoring, so
# those tests only pinned numpy's own math against a method with no callers.