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.

20.3 KB
Raw Blame
"""Ported from ``tests/notes/test_research_notes_routes.py`` on main
(deleted by the FastAPI migration).

Route tests for the research -> notes and document -> notes endpoints
(results-page Notes panel):

    GET    /notes/api/research/{id}/notes             -- list linked notes
    POST   /notes/api/research/{id}/notes             -- create a pre-linked note
    POST   /notes/api/research/{id}/save-as-note      -- copy the report into a note
    GET    /notes/api/research/{id}/annotations
    POST   /notes/api/research/{id}/annotations
    DELETE /notes/api/research/{id}/annotations/{note_id}
    GET    /notes/api/documents/{id}/notes
    POST   /notes/api/documents/{id}/notes
    POST   /notes/api/documents/{id}/annotations
    DELETE /notes/api/documents/{id}/annotations/{note_id}

Successor audit
---------------
``tests/notes/test_notes_router_fastapi.py`` drives some of these endpoints
over HTTP, but only for the *not-found* arms
(``test_get_research_notes_unknown_research_404``,
``..._annotations_unknown_research_404``,
``test_create_research_annotation_missing_comment_400``,
``test_get_document_notes_unknown_document_404``,
``..._document_annotations_unknown_document_404``). Every SUCCESS path here
is unpinned by it, and the success paths are where the interesting content is
built: the provenance header, the comment-note title/body/anchor, the
``has_annotation`` scoping kwarg, the service-call kwargs, and the auto-index
trigger. ``tests/notes/test_note_service.py`` covers the service layer, not
this route glue.

Plumbing translation
--------------------
Flask ``test_request_context`` + ``flask_session["username"]`` becomes a
direct call on the unwrapped FastAPI handler with a dummy ``Request`` (whose
scope carries a ``session`` dict, which ``_trigger_note_auto_index``'s
``request.session.get("session_id")`` reads) and explicit ``username`` /
``body`` arguments. ``_handler`` now peels the slowapi rate-limit wrapper
instead of ``@login_required``. The handlers return either a plain dict (200)
or a ``JSONResponse``; ``_unpack`` normalises both to ``(payload, status)``
exactly as main's tuple-unpacking helper did.

One signature difference is carried through: ``_trigger_note_auto_index``
gained a fourth ``session_id`` parameter in the port (the Flask version read
``session.get("session_id")`` itself, which is unavailable in the sync
threadpool context). The stub below accepts it.
"""

import json
from contextlib import contextmanager
from unittest.mock import MagicMock, patch

from fastapi.responses import JSONResponse
from starlette.requests import Request

from local_deep_research.web.routers import notes as notes_routes

USERNAME = "testuser"


def _handler(fn):
    """Peel every decorator wrapper (the slowapi rate limiters) off a route."""
    while hasattr(fn, "__wrapped__"):
        fn = fn.__wrapped__
    return fn


def _unpack(response):
    """Normalise a handler return to ``(payload, status)``."""
    if isinstance(response, JSONResponse):
        return json.loads(response.body), response.status_code
    return response, 200


def _request(path="/", method="GET"):
    return Request(
        {
            "type": "http",
            "method": method,
            "path": path,
            "headers": [],
            "session": {"session_id": "sess-1"},
        }
    )


class TestGetResearchNotes:
    def _call(self, service_result):
        with patch.object(notes_routes, "NoteService") as svc_cls:
            svc = MagicMock()
            svc.get_notes_for_research.return_value = service_result
            svc_cls.return_value = svc
            response = _handler(notes_routes.get_research_notes)(
                _request("/notes/api/research/res-1/notes"),
                "res-1",
                username=USERNAME,
            )
        return _unpack(response)

    def test_unknown_research_maps_to_404(self):
        payload, status = self._call(None)
        assert status == 404
        assert payload["success"] is False
        assert "not found" in payload["error"].lower()

    def test_returns_linked_notes(self):
        notes = [{"id": "n1", "title": "T", "content_preview": "p"}]
        payload, status = self._call(notes)
        assert status == 200
        assert payload["success"] is True
        assert payload["notes"] == notes


class TestCreateResearchNote:
    def _call(self, side_effect=None, return_value="note-1", body=None):
        with (
            patch.object(notes_routes, "NoteService") as svc_cls,
            patch.object(
                notes_routes,
                "_trigger_note_auto_index",
                lambda *a, **k: None,
            ),
        ):
            svc = MagicMock()
            if side_effect is not None:
                svc.create_note_for_research.side_effect = side_effect
            else:
                svc.create_note_for_research.return_value = return_value
            svc_cls.return_value = svc
            response = _handler(notes_routes.create_research_note)(
                _request("/notes/api/research/res-1/notes", "POST"),
                "res-1",
                username=USERNAME,
                body=body if body is not None else {},
            )
        return _unpack(response), svc

    def test_creates_and_returns_note_id(self):
        (payload, status), svc = self._call(
            body={"title": "T", "content": "C", "tags": ["x"]}
        )
        assert status == 201
        assert payload == {"success": True, "note_id": "note-1"}
        svc.create_note_for_research.assert_called_once_with(
            "res-1", title="T", content="C", tags=["x"]
        )

    def test_empty_body_uses_service_defaults(self):
        (payload, status), svc = self._call(body={})
        assert status == 201
        svc.create_note_for_research.assert_called_once_with(
            "res-1", title=None, content=None, tags=None
        )

    def test_unknown_research_maps_lookup_error_to_404(self):
        (payload, status), _ = self._call(side_effect=LookupError("nope"))
        assert status == 404
        assert payload["success"] is False

    def test_validation_error_maps_to_400(self):
        (payload, status), _ = self._call(
            side_effect=ValueError("private validation detail")
        )
        assert status == 400
        assert payload["error"] == "Invalid note data"
        assert "private validation detail" not in payload["error"]


class TestSaveResearchAsNote:
    def _call(self, research, report="# Report body", create_side_effect=None):
        session_mock = MagicMock()
        session_mock.query.return_value.filter_by.return_value.first.return_value = research

        @contextmanager
        def fake_session(username=None, password=None):
            yield session_mock

        storage = MagicMock()
        storage.get_report.return_value = report

        with (
            patch(
                "local_deep_research.database.session_context.get_user_db_session",
                fake_session,
            ),
            patch(
                "local_deep_research.storage.get_report_storage",
                return_value=storage,
            ),
            patch.object(notes_routes, "NoteService") as svc_cls,
            patch.object(
                notes_routes,
                "_trigger_note_auto_index",
                lambda *a, **k: None,
            ),
        ):
            svc = MagicMock()
            if create_side_effect is not None:
                svc.create_note_for_research.side_effect = create_side_effect
            else:
                svc.create_note_for_research.return_value = "note-9"
            svc_cls.return_value = svc
            response = _handler(notes_routes.save_research_as_note)(
                _request("/notes/api/research/res-1/save-as-note", "POST"),
                "res-1",
                username=USERNAME,
                body={},
            )
        return _unpack(response), svc

    @staticmethod
    def _completed_research(query="What is X?"):
        research = MagicMock()
        research.status = "completed"
        research.query = query
        research.research_meta = {}
        return research

    def test_missing_research_maps_to_404(self):
        (payload, status), _ = self._call(research=None)
        assert status == 404

    def test_incomplete_research_maps_to_409(self):
        research = self._completed_research()
        research.status = "in_progress"
        (payload, status), _ = self._call(research=research)
        assert status == 409
        assert payload["status"] == "in_progress"

    def test_missing_report_maps_to_502(self):
        (payload, status), _ = self._call(
            research=self._completed_research(), report=None
        )
        assert status == 502
        assert "unavailable" in payload["error"]

    def test_saves_report_with_provenance_header(self):
        (payload, status), svc = self._call(
            research=self._completed_research("What is X?")
        )
        assert status == 201
        assert payload == {"success": True, "note_id": "note-9"}
        kwargs = svc.create_note_for_research.call_args.kwargs
        assert kwargs["title"] == "Research: What is X?"
        # Provenance line first, then the untouched report markdown.
        assert kwargs["content"].startswith("> Saved from the research run")
        assert kwargs["content"].endswith("# Report body")
        assert "/results/res-1" in kwargs["content"]

    def test_content_cap_violation_maps_to_400(self):
        (payload, status), _ = self._call(
            research=self._completed_research(),
            create_side_effect=ValueError("private validation detail"),
        )
        assert status == 400
        assert payload["error"] == "Research cannot be saved as a note"
        assert "private validation detail" not in payload["error"]


class TestResearchAnnotations:
    """Annotation endpoints (note_references-backed): the comment IS a
    note; the anchor is a NoteReference row (research target)."""

    def _run(
        self, handler, args, method, url, body, research_row, svc_setup=None
    ):
        session_mock = MagicMock()
        session_mock.query.return_value.filter_by.return_value.first.return_value = research_row

        @contextmanager
        def fake_session(username=None, password=None):
            yield session_mock

        svc = MagicMock()
        if svc_setup:
            svc_setup(svc)
        kwargs = {"username": USERNAME}
        if method in ("POST", "PUT", "PATCH"):
            kwargs["body"] = body if body is not None else {}
        with (
            patch(
                "local_deep_research.database.session_context.get_user_db_session",
                fake_session,
            ),
            patch.object(notes_routes, "NoteService") as svc_cls,
            patch.object(
                notes_routes,
                "_trigger_note_auto_index",
                lambda *a, **k: None,
            ),
        ):
            svc_cls.return_value = svc
            response = _handler(handler)(_request(url, method), *args, **kwargs)
        return _unpack(response), svc

    @staticmethod
    def _research_row(query="What is X?"):
        row = MagicMock()
        row.query = query
        return row

    # ---- GET ----

    def test_get_unknown_research_404(self):
        (payload, status), _ = self._run(
            notes_routes.get_research_annotations,
            ("res-1",),
            "GET",
            "/notes/api/research/res-1/annotations",
            None,
            research_row=None,
        )
        assert status == 404

    def test_get_returns_service_annotations(self):
        anns = [
            {
                "note_id": "n1",
                "quote": "q",
                "prefix": "",
                "suffix": "",
                "note_title": "Comment: hi",
                "comment_preview": "hi",
                "created_at": None,
            }
        ]
        (payload, status), svc = self._run(
            notes_routes.get_research_annotations,
            ("res-1",),
            "GET",
            "/notes/api/research/res-1/annotations",
            None,
            research_row=self._research_row(),
            svc_setup=lambda s: setattr(
                s.get_annotations_for_target, "return_value", anns
            ),
        )
        assert status == 200
        assert payload["annotations"] == anns
        svc.get_annotations_for_target.assert_called_once_with(
            research_id="res-1"
        )

    # ---- POST ----

    def test_post_creates_anchored_comment_note(self):
        (payload, status), svc = self._run(
            notes_routes.create_research_annotation,
            ("res-1",),
            "POST",
            "/notes/api/research/res-1/annotations",
            {
                "quote": "the passage",
                "prefix": "pre ",
                "suffix": " post",
                "comment": "verify this",
            },
            research_row=self._research_row("What is X?"),
            svc_setup=lambda s: setattr(
                s.create_note_for_research, "return_value", "note-c1"
            ),
        )
        assert status == 201
        assert payload["annotation"]["note_id"] == "note-c1"
        kwargs = svc.create_note_for_research.call_args.kwargs
        assert kwargs["title"] == "Comment: verify this"
        assert kwargs["content"].startswith("verify this\n\n> the passage")
        assert "/results/res-1" in kwargs["content"]
        # The anchor rides through the service into note_references.
        assert kwargs["quote"] == "the passage"
        assert kwargs["prefix"] == "pre "
        assert kwargs["suffix"] == " post"

    def test_post_missing_comment_400(self):
        (payload, status), svc = self._run(
            notes_routes.create_research_annotation,
            ("res-1",),
            "POST",
            "/notes/api/research/res-1/annotations",
            {"quote": "q"},
            research_row=self._research_row(),
        )
        assert status == 400
        svc.create_note_for_research.assert_not_called()

    # ---- DELETE ----

    def test_delete_requires_matching_anchor(self):
        (payload, status), svc = self._run(
            notes_routes.delete_research_annotation,
            ("res-1", "nope"),
            "DELETE",
            "/notes/api/research/res-1/annotations/nope",
            None,
            research_row=self._research_row(),
            svc_setup=lambda s: setattr(
                s.has_annotation, "return_value", False
            ),
        )
        assert status == 404
        svc.delete_note.assert_not_called()

    def test_delete_removes_note(self):
        (payload, status), svc = self._run(
            notes_routes.delete_research_annotation,
            ("res-1", "n1"),
            "DELETE",
            "/notes/api/research/res-1/annotations/n1",
            None,
            research_row=self._research_row(),
            svc_setup=lambda s: setattr(s.has_annotation, "return_value", True),
        )
        assert status == 200
        svc.has_annotation.assert_called_once_with("n1", research_id="res-1")
        svc.delete_note.assert_called_once_with("n1")


class TestDocumentNotesRoutes:
    """Document-target twins of the research routes."""

    def _run(self, handler, args, method, url, body, doc_row, svc_setup=None):
        session_mock = MagicMock()
        session_mock.query.return_value.filter_by.return_value.first.return_value = doc_row

        @contextmanager
        def fake_session(username=None, password=None):
            yield session_mock

        svc = MagicMock()
        if svc_setup:
            svc_setup(svc)
        kwargs = {"username": USERNAME}
        if method in ("POST", "PUT", "PATCH"):
            kwargs["body"] = body if body is not None else {}
        with (
            patch(
                "local_deep_research.database.session_context.get_user_db_session",
                fake_session,
            ),
            patch.object(notes_routes, "NoteService") as svc_cls,
            patch.object(
                notes_routes,
                "_trigger_note_auto_index",
                lambda *a, **k: None,
            ),
        ):
            svc_cls.return_value = svc
            response = _handler(handler)(_request(url, method), *args, **kwargs)
        return _unpack(response), svc

    def test_get_document_notes_404_when_missing(self):
        (payload, status), _ = self._run(
            notes_routes.get_document_notes,
            ("doc-1",),
            "GET",
            "/notes/api/documents/doc-1/notes",
            None,
            doc_row=None,
            svc_setup=lambda s: setattr(
                s.get_notes_for_document, "return_value", None
            ),
        )
        assert status == 404

    def test_create_document_note_maps_value_error_to_400(self):
        def raise_ve(*a, **k):
            raise ValueError("private validation detail")

        (payload, status), _ = self._run(
            notes_routes.create_document_note,
            ("doc-1",),
            "POST",
            "/notes/api/documents/doc-1/notes",
            {},
            doc_row=MagicMock(),
            svc_setup=lambda s: setattr(
                s.create_note_for_document, "side_effect", raise_ve
            ),
        )
        assert status == 400
        assert payload["error"] == "Invalid document note data"
        assert "private validation detail" not in payload["error"]

    def test_create_document_annotation_builds_comment_note(self):
        doc_row = MagicMock()
        doc_row.title = "A Paper"
        (payload, status), svc = self._run(
            notes_routes.create_document_annotation,
            ("doc-1",),
            "POST",
            "/notes/api/documents/doc-1/annotations",
            {"quote": "a finding", "comment": "check the methodology"},
            doc_row=doc_row,
            svc_setup=lambda s: setattr(
                s.create_note_for_document, "return_value", "note-d1"
            ),
        )
        assert status == 201
        kwargs = svc.create_note_for_document.call_args.kwargs
        assert kwargs["title"] == "Comment: check the methodology"
        assert "> a finding" in kwargs["content"]
        assert "/library/document/doc-1" in kwargs["content"]
        assert kwargs["quote"] == "a finding"

    def test_delete_document_annotation_requires_anchor(self):
        (payload, status), svc = self._run(
            notes_routes.delete_document_annotation,
            ("doc-1", "n9"),
            "DELETE",
            "/notes/api/documents/doc-1/annotations/n9",
            None,
            doc_row=MagicMock(),
            svc_setup=lambda s: setattr(s.has_annotation, "return_value", True),
        )
        assert status == 200
        svc.has_annotation.assert_called_once_with("n9", document_id="doc-1")
        svc.delete_note.assert_called_once_with("n9")


class TestNewEndpointsAutoIndex:
    """Regression: notes created through the research/document endpoints
    must be queued for embedding (like the plain POST /api/notes route),
    or they never reach semantic search / 'Ask your notes'."""

    def _run(self, handler, args, url, body, svc_setup):
        svc = MagicMock()
        svc_setup(svc)
        triggered = []
        with (
            patch.object(notes_routes, "NoteService", return_value=svc),
            patch.object(
                notes_routes,
                "_trigger_note_auto_index",
                lambda note_id, service, username, session_id=None: (
                    triggered.append(note_id)
                ),
            ),
        ):
            _unpack(
                _handler(handler)(
                    _request(url, "POST"),
                    *args,
                    username=USERNAME,
                    body=body,
                )
            )
        return triggered, svc

    def test_create_research_note_triggers_autoindex(self):
        triggered, _ = self._run(
            notes_routes.create_research_note,
            ("res-1",),
            "/notes/api/research/res-1/notes",
            {},
            lambda s: setattr(
                s.create_note_for_research, "return_value", "note-1"
            ),
        )
        assert triggered == ["note-1"]

    def test_create_document_note_triggers_autoindex(self):
        triggered, _ = self._run(
            notes_routes.create_document_note,
            ("doc-1",),
            "/notes/api/documents/doc-1/notes",
            {},
            lambda s: setattr(
                s.create_note_for_document, "return_value", "note-2"
            ),
        )
        assert triggered == ["note-2"]