~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
"""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"]