Skip to content

~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.

29.2 KB
Raw Blame
"""
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.