~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
"""
Notes Routes - API endpoints and pages for the notes feature (FastAPI).
Ported from the Flask ``web/routes/notes_routes.py`` blueprint (``notes_bp``,
url_prefix ``/notes``). Every endpoint preserves the same paths, methods,
and service calls. Three deliberate divergences from the Flask blueprint:
* error responses use fixed client-safe messages rather than
exception-derived detail;
* ``link_research_to_note`` checks that the note exists both before
calling the service and again when the service raises (the Flask route
recovered that 404 by matching "not found" in the exception text, which
the fixed messages no longer allow; the second check covers a note
deleted between the first check and the call);
* the nine LLM-backed AI routes classify an unconfigured LLM separately
from an invalid request and from a server fault -- 400 with
``error_type: model_not_configured`` via
``_llm_not_configured_response``, where Flask answered a generic 500
(and, on ``suggest-tags``, a request-validation 400).
Notes on the port:
* ``@login_required`` → ``Depends(require_auth)``; the per-route manual
``session.get("username")`` / 401 guard is dropped because ``require_auth``
already raises 401 when there is no authenticated user.
* The two blueprint-wide ``before_request`` hooks (``_reject_oversized_bodies``
and ``_reject_non_object_json_body``) are collapsed into the shared
``_notes_json_body`` dependency, injected into every mutating route.
* Flask ``request.args`` → ``request.query_params``; ``session[...]`` →
the ``username`` dependency / ``request.session``.
* Route registration order is deliberate: the literal ``/api/notes/...`` GET
routes are registered BEFORE ``GET /api/notes/{note_id}`` because Starlette
matches routes in registration order (Flask's map gave static rules
priority automatically; FastAPI does not).
"""
import asyncio
import builtins
import itertools
import json
import math
import reprlib
from fastapi import APIRouter, Depends, Request
from fastapi.responses import JSONResponse
from loguru import logger
from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import load_only
from ...config.llm_config import (
LLM_NOT_CONFIGURED_CLIENT_MESSAGE,
LLMNotConfiguredError,
)
from ...research_library.notes.services.note_ai_service import NoteAIService
from ...research_library.notes.services.note_service import (
MAX_TAG_LENGTH,
MAX_TAGS_PER_NOTE,
NOTE_CONTENT_MAX_BYTES,
NoteService,
_assert_content_size,
escape_markdown_link_label,
)
from ...research_library.utils import handle_api_error
from ...security.data_sanitizer import REDACTION_TEXT
from ...security.log_sanitizer import (
_LOG_REDACTION_MAX_CHARS,
_is_empty_log_value,
_is_sensitive_log_key,
_truncate_for_log_redaction,
redact_for_log,
)
from ..dependencies.auth import require_auth
from ..dependencies.json_body import is_json_request
from ..dependencies.rate_limit import async_shared_limit, limiter, _user_key
from ..dependencies.threadpool import run_db_sync
from ..template_config import templates
# Cap on user-supplied free-text query params that flow into `ILIKE %...%`
# over unbounded TEXT columns — shared with unified_search_routes via
# _search_constants so the two route modules can't diverge. The router lives
# in web/routers/, so reach the file in web/routes/.
from ..routes._search_constants import MAX_SEARCH_LEN
from typing import Annotated, Any
# Bound at import time (not looked up on the class at call time) because
# tests monkeypatch the ``NoteAIService`` name in this module.
_MAX_GRADE_SOURCES = NoteAIService.MAX_GRADE_SOURCES
MAX_LINK_TEXT_LEN = 500
# Per-claim length cap for the fact-check grade endpoint (claims are free text
# from the client; the grader bounds the count but not the per-string size).
MAX_CLAIM_LEN = 1000
# Upper bound on any ?limit query param across the list/search endpoints
# (was an unnamed 200 repeated at six call sites).
MAX_LIMIT = 200
def _clamp_limit(request: Request, default, max_=MAX_LIMIT):
"""Parse ``?limit`` into ``[1, max_]``, defaulting to ``default``.
Raises ``ValueError`` on a non-integer value; the caller wraps this in
``try`` and returns the 400 (matching the six former inline copies).
"""
return max(1, min(int(request.query_params.get("limit", default)), max_))
def _clamp_text_query(value, name, max_len=MAX_SEARCH_LEN):
"""Return value or raise ValueError if it exceeds the cap.
``None``/empty pass through unchanged so optional params behave the
same as before. The caller maps the failure to a fixed 400 response.
Two distinct failures share the ``ValueError``: a non-string value and
an over-length one. A caller that passes ``request.query_params.get(...)``
can only ever hit the length branch (Starlette's query params are always
``str``), so a single fixed length message is truthful there. A caller
reading a JSON body must decide by type BEFORE calling this — see
``resolve_link`` — because the body is an uncoerced ``dict``.
That makes the non-string branch DEAD at every current call site (three
query-param readers plus ``resolve_link``, which type-checks first). It
is kept as a defensive guard, not as live behaviour: without it a future
caller that forgets the type check would reach ``len(value)`` and raise
``TypeError``, which no caller here catches, turning a bad body into a
500 instead of a 400. Any new call site that can pass a non-string must
still do its own type check so its fixed message stays truthful.
"""
if value is None:
return value
if not isinstance(value, str):
raise ValueError(f"{name} must be a string")
if len(value) > max_len:
raise ValueError(f"{name} exceeds maximum length ({max_len} chars)")
return value
# Bounded repr for an untrusted value going into an audit-log line. A naive
# ``repr(value)[:100]`` slices AFTER building the full repr — for a value
# that came out of ``_notes_json_body`` (up to the 100 MB notes JSON body
# cap, see ``_MAX_JSON_BODY_BYTES`` above) that means materializing a second
# ~100 MB+ string (more if it's escape-heavy, since ``repr`` expands each
# control char to ``\xNN``) just to throw all but 100 chars away. Same
# problem for a huge list/dict: ``repr()`` walks and stringifies every
# element before any truncation happens.
#
# ``reprlib.Repr`` avoids this for STRINGS and LISTS/TUPLES only: its
# ``repr_str`` slices, and ``repr_list``/``repr_tuple`` ``itertools.islice``,
# BEFORE recursing/stringifying (see ``reprlib.Repr.repr_str`` /
# ``repr_list`` in the stdlib), so those costs are bounded by the limits
# below regardless of the input's real size. It does NOT hold for
# dict/set/frozenset: ``repr_dict`` / ``repr_set`` / ``repr_frozenset``
# call ``reprlib._possibly_sorted()`` — a plain ``sorted()`` over the FULL
# container — and slice to ``maxdict``/``maxset``/``maxfrozenset`` only
# afterwards. That is why values reach ``reprlib`` here only through the
# bounded walk in ``_bound_dict_shaped_walk`` below. ``maxlevel`` also caps
# recursion depth for a deeply nested dict.
#
# Redaction runs BEFORE any cut. ``repr_str`` keeps a long string's first
# and last ~48 characters and drops the middle; the final ``[:100]``
# backstop below keeps only a prefix. Either cut can drop a credential's
# label (``?key=``, ``api_key=``, the ``user:`` ... ``@`` around URL
# userinfo) while keeping part of the secret, and the loguru patcher's
# redaction — the backstop for every sink — then has nothing to match. The
# value was often logged in full before it went through this preview, so
# the patcher used to see the whole thing. ``_RedactingRepr`` therefore runs
# the patcher's own redaction (``redact_for_log``) on every string, and on
# every ``builtins.repr`` text ``repr_instance`` falls back to, before
# reprlib shortens it; ``_bound_dict_shaped_walk`` masks a value under a
# sensitive key name (``api_key``, ``password``, ...), as the patcher's
# ``extra`` redaction does, because per-string redaction cannot see a label
# that lives in the dict key (and masks the value under any key its
# key-check budget cannot cover, see ``_PREVIEW_KEY_CHECK_BUDGET``).
#
# Redaction costs about 2 microseconds per character on adversarial input
# (a run of spaces, or of ``https://a:b@ ``): ~70-120 ms for a 32 KiB
# string, where the unredacted preview cost well under 0.1 ms. The preview
# shows at most 100 characters, so each string is redacted only up to
# ``_PREVIEW_STRING_REDACTION_MAX_CHARS``: it is cut first by the
# patcher's own rule (``_truncate_for_log_redaction`` with that bound,
# only at a whitespace boundary, dropping the whole run the bound falls
# in), the kept head is redacted, and the rest is replaced by the
# omitted-length marker. A credential token holds no boundary character,
# so the head never keeps part of a token whose label or ``@`` lies past
# the cut, and nothing past the cut is shown. A bounded container can
# still hold over twenty thousand strings (reprlib renders up to ten keys
# and ten values per dict at each of four levels), so each preview also
# has a total redaction budget of ``_PREVIEW_REDACTION_BUDGET``
# characters. Each redaction also has a fixed cost of about 25
# microseconds however short the string, so every call is charged at
# least ``_PREVIEW_REDACTION_MIN_CHARGE`` characters: a preview runs at
# most ``_PREVIEW_REDACTION_BUDGET // _PREVIEW_REDACTION_MIN_CHARGE``
# (32) redactions over at most ``_PREVIEW_REDACTION_BUDGET`` characters
# in total, a few milliseconds at worst. The 100-character preview shows
# only the first few strings reprlib renders, and those are the ones
# redacted first. A string that does not fit the remaining budget is
# shown as ``<N-char string not shown>``, never raw.
_PREVIEW_STRING_REDACTION_MAX_CHARS = 512
_PREVIEW_REDACTION_BUDGET = 1_024
_PREVIEW_REDACTION_MIN_CHARGE = 32
class _RedactingRepr(reprlib.Repr):
"""``reprlib.Repr`` that redacts each string before shortening it.
Stateful (the remaining budget), so ``_log_value_preview`` builds a new
one per call; the module-level ``_log_value_repr`` instance only holds
the shared limits.
"""
def __init__(self) -> None:
super().__init__(
maxlevel=4,
maxtuple=10,
maxlist=10,
maxdict=10,
maxset=10,
maxfrozenset=10,
maxstring=100,
maxlong=100,
maxother=100,
)
self._budget = _PREVIEW_REDACTION_BUDGET
def _redacted(self, text: str):
cost = max(
min(len(text), _PREVIEW_STRING_REDACTION_MAX_CHARS),
_PREVIEW_REDACTION_MIN_CHARGE,
)
if cost > self._budget:
return None
self._budget -= cost
head, marker = _truncate_for_log_redaction(
text, _PREVIEW_STRING_REDACTION_MAX_CHARS
)
return redact_for_log(head) + marker
def repr_str(self, x, level):
redacted = self._redacted(x)
if redacted is None:
return f"<{len(x)}-char string not shown>"
return super().repr_str(redacted, level)
def repr_instance(self, x, level):
try:
text = builtins.repr(x)
except Exception:
return f"<{x.__class__.__name__} instance at {id(x):#x}>"
redacted = self._redacted(text)
if redacted is None:
return f"<{x.__class__.__name__} repr not shown>"
if len(redacted) > self.maxother:
i = max(0, (self.maxother - 3) // 2)
j = max(0, self.maxother - 3 - i)
redacted = (
redacted[:i] + self.fillvalue + redacted[len(redacted) - j :]
)
return redacted
_log_value_repr = _RedactingRepr()
def _log_value_preview(value: Any) -> str:
"""Bounded, ``logger.warning``-safe preview of an untrusted JSON value.
Use in place of ``repr(value)[:100]`` at any audit-log site whose value
comes from request input (query params, and especially JSON bodies,
which this router allows up to ~100 MB). See ``_log_value_repr`` above
for why plain ``repr()[:100]`` is unsafe here.
``value`` is pre-bounded by ``_bound_dict_shaped_walk`` before it
reaches ``reprlib`` — see that function for why reprlib's own limits do
not bound dict/set/frozenset cost on their own.
The final bound is a cheap backstop, not the primary defense — the
limits on ``_log_value_repr`` plus the pre-bounding step already keep
the *work* bounded; this just keeps the *output* bounded too (a
container's ten per-element reprs, plus reprlib's own ``...`` marker,
can still sum past 100 chars). But the backstop must not slice
truncation *markers* off with the content, and it must keep the two
truncation conditions distinguishable. When it truncates, the preview
gets one of exactly two endings, each carrying its own meaning:
* an items-omitted tail — ``', ...}'``, ``', ...]'`` or ``', ...)'``:
ENTRIES were dropped from some container (it held strictly more
than ``reprlib``'s per-container limit of 10). A repr that already
ends in one of ``reprlib``'s own container tails keeps it inside
the cap; a repr whose dropped entries are NESTED — the tail sits
inside the repr, followed by the outer container's closing
delimiters, so it is not the suffix of the whole repr and the
tail check cannot see it — instead gets
``_PREVIEW_ITEMS_OMITTED_TAIL`` appended, guided by the
``items_omitted`` flag the pre-bounding walk reports.
* a bare ``...`` (``_PREVIEW_ELLIPSIS``): LENGTH-only truncation —
no visited container lost entries; the repr simply exceeded the
char cap.
The two endings differ in their final character and so can never be
byte-equal: an 11-key (or 50,010-key) payload nested anywhere the
pre-bounding walk visits always previews differently from the
corresponding all-≤10-key payload. Reprs that fit the cap are
returned untouched, and the preview never exceeds the cap.
Every string (and every ``repr`` text of a non-container object) has
already been through the log patcher's credential redaction before
``reprlib`` or the backstop shortens it, and a value under a sensitive
dict key (or under a key the key-check budget could not cover) is
masked whole — see ``_RedactingRepr`` above. A cut
therefore only removes text the patcher already redacted or would
leave as is: it cannot strip a recognised credential's label while
keeping part of the secret.
"""
bounded, items_omitted = _bound_dict_shaped_walk(value, 0)
text = _RedactingRepr().repr(bounded)
if len(text) <= _PREVIEW_MAX_CHARS:
return text
for tail in _PREVIEW_CONTAINER_TAILS:
if text.endswith(tail):
return text[: _PREVIEW_MAX_CHARS - len(tail)] + tail
if items_omitted:
return (
text[: _PREVIEW_MAX_CHARS - len(_PREVIEW_ITEMS_OMITTED_TAIL)]
+ _PREVIEW_ITEMS_OMITTED_TAIL
)
return (
text[: _PREVIEW_MAX_CHARS - len(_PREVIEW_ELLIPSIS)] + _PREVIEW_ELLIPSIS
)
# One MORE than ``_log_value_repr``'s own maxdict/maxlist/maxset/maxtuple
# (10), deliberately. reprlib only appends its ``...`` truncation marker
# when the container handed to it is STRICTLY longer than that limit (``if
# n > self.maxdict: pieces.append(self.fillvalue)``). Pre-truncating to
# exactly 10 would make an attacker's 400,000-key body render byte-identical
# to a legitimate 10-key one — silently erasing "there was more" from the
# audit line, which is the one thing this log site exists to record. Keeping
# 11 costs nothing (reprlib discards the 11th) and restores the marker.
# ``_PREVIEW_MAX_DEPTH`` matches ``_log_value_repr``'s ``maxlevel``.
_PREVIEW_MAX_ITEMS = 11
_PREVIEW_MAX_DEPTH = 4
# Final output cap for ``_log_value_preview`` (previously an inline
# ``[:100]`` slice).
_PREVIEW_MAX_CHARS = 100
# Matches reprlib's ``fillvalue`` and the ``...`` marker convention used
# throughout this module.
_PREVIEW_ELLIPSIS = "..."
# reprlib's "the container had more items than I showed" tails — its ``...``
# fillvalue joined onto the container's closing bracket. When the final
# char bound bites, preserving the tail keeps an item-bounded payload (e.g.
# a 50,010-key dict whose first ten ~100-char values fill the cap on their
# own) distinguishable from a merely char-bounded one, instead of slicing
# the marker off entirely.
_PREVIEW_CONTAINER_TAILS = (", ...}", ", ...]", ", ...)")
# The nested counterpart to the tails above. When the pre-bounding walk
# reports that some container it visited held more entries than
# ``reprlib``'s per-container limit (so entries were dropped) but the
# ``reprlib`` fill sits INSIDE the repr — followed by the outer
# container's closing delimiters, not at the very end — the tail check
# in ``_log_value_preview`` cannot preserve it. Appending this explicit
# tail keeps such a payload (e.g. ``{"outer": {<11 keys with ~100-char
# values>}}``) byte-distinguishable from the corresponding all-≤10-key
# payload, whose only truncation is the char cap and which therefore
# ends in a bare ``...``. Deliberately identical to the dict tail: both
# spell "entries were omitted".
_PREVIEW_ITEMS_OMITTED_TAIL = ", ...}"
# Budget for the sensitive-key check in ``_bound_dict_shaped_walk``. The
# check walks the whole key (``DataSanitizer.is_sensitive_setting``
# normalises it character by character), JSON keys have no length limit,
# and the walk can visit over sixteen thousand keys (up to 11 per dict in
# up to 1,464 dicts). Each check of a str key is charged the key's length,
# at least ``_PREVIEW_KEY_CHECK_MIN_CHARGE`` (a non-str key is never
# sensitive, and its check is free), so one preview checks at most
# ``_PREVIEW_KEY_CHECK_BUDGET`` characters of keys in at most 512 checks.
# A key the remaining budget cannot cover is not checked, and its value is
# masked as if the key were sensitive (fail closed).
_PREVIEW_KEY_CHECK_BUDGET = _LOG_REDACTION_MAX_CHARS
_PREVIEW_KEY_CHECK_MIN_CHARGE = 64
def _bound_dict_shaped_walk(
value: Any, _depth: int, _key_budget: list[int] | None = None
) -> tuple[Any, bool]:
"""Return a size-bounded copy of ``value``, safe to hand to
``_log_value_repr.repr()``, plus an "entries were dropped" flag.
``reprlib.Repr`` bounds *string* and *list/tuple* reprs by slicing
BEFORE recursing (see ``repr_str`` / ``repr_list`` in the stdlib), so
those are already O(1) regardless of input size — the module comment
above relies on that. But ``repr_dict`` / ``repr_set`` /
``repr_frozenset`` call stdlib ``reprlib._possibly_sorted()`` — which is
a plain ``sorted(x)`` over the FULL container — and only slice to
``maxdict``/``maxset``/``maxfrozenset`` afterwards. For a dict/set built
from a large attacker-controlled JSON body (this router allows up to
~100 MB, e.g. ``{"is_collapsed": {<N keys>}}`` reaching
``patch_note_research``) that reintroduces the exact O(N log N) time /
O(N) memory cost ``_log_value_repr`` exists to eliminate — measured at
~10-22 ms for a 400k-entry dict/set on py3.14, scaling linearly, versus
~0 ms for an equivalently large string or list through the same helper.
Fix: truncate every dict/set/frozenset to ``_PREVIEW_MAX_ITEMS`` entries
OURSELVES — via ``itertools.islice`` over the container's natural
iteration order (insertion order for dicts, arbitrary-but-cheap for
sets), never ``sorted()`` — before reprlib ever sees it. Once bounded
this way, reprlib's own ``repr_dict``/``repr_set`` still calls
``sorted()``, but over at most ``_PREVIEW_MAX_ITEMS`` items, which is
negligible.
Recurses into dict values and list/tuple elements (only the first
``_PREVIEW_MAX_ITEMS`` of each, mirroring reprlib's own slicing) up to
``_PREVIEW_MAX_DEPTH`` — matching ``_log_value_repr``'s ``maxlevel`` —
so a large dict/set nested a few levels down (e.g. inside a list inside
a dict) is bounded too, not just one sitting at the top level. The
number of containers copied is the geometric sum
``1 + M + M**2 + M**3`` for ``M = _PREVIEW_MAX_ITEMS`` (1,464 at the
current limits), NOT ``M ** _PREVIEW_MAX_DEPTH``, regardless of the real
structure's size. Dict/set *keys* are returned unbounded: JSON object
keys are always strings, and rendering a huge key is bounded by
``_RedactingRepr``'s redaction budget and ``repr_str`` slicing. The
sensitive-key check on each visited dict key is NOT free — it walks the
whole key — so it draws on a per-preview budget,
``_PREVIEW_KEY_CHECK_BUDGET`` (``_key_budget`` holds what remains; the
outermost call creates it). A key the remaining budget cannot cover is
not checked and its value is masked whole, as for a sensitive key. The
walk still descends into that masked value (with no budget, so every
key under it is masked unchecked) to compute the items-omitted flag.
Past ``_PREVIEW_MAX_DEPTH`` the walk stops and the sub-value is handed
to reprlib untouched. For a **dict** that costs nothing: ``repr_dict``
checks ``level <= 0`` *before* calling ``_possibly_sorted``, so an
over-deep dict collapses to ``{...}`` unsorted. It is NOT free for a
**set/frozenset**: ``repr_set``/``repr_frozenset`` call
``_possibly_sorted`` at the top of the method, *before*
``_repr_iterable`` gets to check ``level``, so a huge set nested past
the cap is still sorted in full and the result thrown away (measured
~13 ms for ``[[[[set(range(400_000))]]]]``, output ``[[[[{...}]]]]``).
Likewise, set/frozenset *elements* are never recursed into, so a
container inside a set — a frozenset or tuple, the only hashable
candidates — stays unbounded at any depth (~13 ms for
``{frozenset(range(400_000))}``). Neither shape is reachable from this
router (JSON has no set literal), but both matter if this helper is
reused elsewhere.
Values that are not dict/set/frozenset/list/tuple (str, int, float,
bool, None) pass through unchanged — reprlib's ``maxstring`` /
``maxlong`` bound those. ``maxlong`` only slices an ALREADY-built
string, though: ``reprlib.repr_int`` calls ``builtins.repr(x)`` in full
before truncating, so a huge ``int`` is the one JSON-native type whose
repr cost this helper does not bound (measured ~2 s for a 2,000,000-
digit int). It is unreachable from this router only because
``json.loads`` refuses an integer literal longer than
``sys.get_int_max_str_digits()`` (4300 by default). Nor does the
pass-through extend to an arbitrary object: reprlib has no per-type
method for a custom class, so it falls through to ``repr_instance``,
which calls ``builtins.repr(x)`` in FULL and ignores ``level``
entirely — a hostile ``__repr__`` can allocate whatever it likes
(measured ~170 ms / 200 MB) before reprlib truncates the resulting
string. Nothing here bounds that. It is unreachable at this router's
call sites, whose values all come out of ``json.loads`` and so can only
be JSON-native types, but any reuse of this helper at a call site
logging a non-JSON-sourced value must account for it.
Returns ``(bounded_value, items_omitted)``. ``items_omitted`` is True
iff any dict/set/frozenset/list/tuple visited at a depth ``reprlib``
still enumerates (below ``_PREVIEW_MAX_DEPTH``, which matches its
``maxlevel``) holds at least ``_PREVIEW_MAX_ITEMS`` entries — i.e.
strictly more than ``reprlib``'s per-container limit of one less, the
condition under which ``reprlib`` drops entries and appends its
``...`` fill. ``_log_value_preview`` uses the flag to give over-cap
reprs whose item truncation is nested (fill not at the end of the
repr) the explicit ``_PREVIEW_ITEMS_OMITTED_TAIL`` ending.
Containers at or past the depth cap are handed to ``reprlib``
untouched and collapse there to ``{...}`` / ``[...]`` wholesale — no
per-entry output at any item count — so they do not set the flag.
"""
if _depth >= _PREVIEW_MAX_DEPTH:
return value, False
if _key_budget is None:
_key_budget = [_PREVIEW_KEY_CHECK_BUDGET]
if isinstance(value, dict):
bounded: dict[Any, Any] = {}
omitted = len(value) >= _PREVIEW_MAX_ITEMS
for k, v in itertools.islice(value.items(), _PREVIEW_MAX_ITEMS):
# A non-str key is never sensitive and costs nothing to check.
cost = (
max(len(k), _PREVIEW_KEY_CHECK_MIN_CHARGE)
if isinstance(k, str)
else 0
)
if cost > _key_budget[0]:
# Not checked (see ``_PREVIEW_KEY_CHECK_BUDGET``), so
# masked unless empty. The walk below only computes the
# flag: with no budget, everything under it is masked too.
if not _is_empty_log_value(v):
bounded[k] = REDACTION_TEXT
_, child_omitted = _bound_dict_shaped_walk(
v, _depth + 1, [0]
)
omitted = omitted or child_omitted
continue
else:
_key_budget[0] -= cost
if _is_sensitive_log_key(k) and not _is_empty_log_value(v):
# Masked whole, as the log patcher masks a sensitive
# ``extra`` key: string redaction cannot see a label
# that lives in the key (see ``_RedactingRepr``).
bounded[k] = REDACTION_TEXT
continue
bounded[k], child_omitted = _bound_dict_shaped_walk(
v, _depth + 1, _key_budget
)
omitted = omitted or child_omitted
return bounded, omitted
if isinstance(value, (set, frozenset)):
# Bound the count only — set/frozenset elements are NOT recursed
# into (see the docstring: a frozenset or tuple nested inside a set
# therefore stays unbounded; unreachable from JSON input, which has
# no set literal). Rebuilt as a plain ``set``/``frozenset`` rather
# than ``type(value)(...)``, because a set SUBCLASS with a custom
# ``__init__`` would come back silently EMPTY or raise ``TypeError``
# from inside a logging call — turning a 400 into a 500.
bounded_items = itertools.islice(value, _PREVIEW_MAX_ITEMS)
if isinstance(value, frozenset):
return frozenset(bounded_items), len(value) >= _PREVIEW_MAX_ITEMS
return set(bounded_items), len(value) >= _PREVIEW_MAX_ITEMS
if isinstance(value, (list, tuple)):
bounded = []
omitted = len(value) >= _PREVIEW_MAX_ITEMS
for v in itertools.islice(value, _PREVIEW_MAX_ITEMS):
bounded_item, child_omitted = _bound_dict_shaped_walk(
v, _depth + 1, _key_budget
)
bounded.append(bounded_item)
omitted = omitted or child_omitted
# Rebuilt as a plain ``tuple``, so a namedtuple degrades to a
# bare tuple in the preview — acceptable for an audit line.
bounded_tuple = tuple(bounded) if isinstance(value, tuple) else bounded
return bounded_tuple, omitted
return value, False
def _llm_not_configured_response(operation: str) -> JSONResponse:
"""400 for a notes AI route whose LLM is not configured.
Nine routes in this file run an LLM (``summarize``,
``research-questions``, ``suggest-tags``, ``key-concepts``,
``fact-check``, ``fact-check/.../grade``, ``synthesize/preview``,
``synthesize``, ``versions/semantic-diff``). Every one of them reaches
``NoteAIService._get_llm`` -> ``config.llm_config.get_llm``, which raises
``LLMNotConfiguredError`` when the user has not chosen a provider/model
yet -- and on a fresh install that is the FIRST thing these endpoints
hit. Left to ``handle_api_error`` they answer 500 "contact support"; in
``suggest_tags``, whose handler also maps ``ValueError`` to a
request-validation 400, it came back as a bad-request verdict on a body
that was perfectly fine. Both send the user looking in the wrong place.
400 with ``error_type: model_not_configured`` is this repository's
existing answer for an unconfigured LLM, not a 5xx: see
``web/routers/api.py::check_ollama_model`` (the same ``error_type`` for
an empty ``llm.model``), ``web/routers/followup.py::start_followup``
(400 before any DB write when ``llm.model`` is empty), and
``web/routers/zotero.py::_not_configured_response`` -- "that is a
client-state problem, not a server error". The 503s in ``rag.py`` and
``settings.py`` are NOT the precedent: those are egress-policy
``settings_unavailable`` arms, a different condition.
One helper rather than nine copies so the status, the message and the
``error_type`` cannot drift apart route by route. ``operation`` names
the route in the server-side log only; it never reaches the client, and
the client message is always the module constant -- never ``str(exc)``,
whose setup guidance can carry a settings path.
"""
logger.warning("Notes AI: {} refused, LLM not configured", operation)
return JSONResponse(
{
"success": False,
"error": LLM_NOT_CONFIGURED_CLIENT_MESSAGE,
"error_type": "model_not_configured",
},
status_code=400,
)
# Rate limits for AI-heavy endpoints. Split into two buckets so cheap
# FAISS / local-embedding lookups (semantic search, similar notes,
# suggested links, related research) don't drain the same budget as
# expensive LLM calls (summarize, suggest_tags, extract_key_concepts,
# semantic_diff). A user typing through the autocomplete UI shouldn't
# block a single LLM call for a full minute.
#
# ``key_func=_user_key`` keys each bucket per authenticated user; without it
# the global Limiter default (client IP) would let shared-IP users (NAT, lab,
# reverse-proxy-without-trusted-forward-headers) drain each other's
# LLM/synthesis budgets.
_notes_ai_limit = async_shared_limit(
limiter, "10 per minute", scope="notes_ai", key_func=_user_key
)
_notes_search_limit = limiter.shared_limit(
"60 per minute", scope="notes_search", key_func=_user_key
)
_notes_synthesize_limit = async_shared_limit(
limiter, "5 per minute", scope="notes_synthesize", key_func=_user_key
)
# Notes write budget — applies to create_note, update_note, delete_note,
# and add/remove from collection. 60/min comfortably covers active
# editing (a save every second for a minute) but blocks scripted abuse:
# pre-fix an authenticated user could rapid-POST PUT /api/notes/<id>
# under the global IP cap (5000/hr) and saturate the 4-worker
# summary_executor with bursty LLM change-summary tasks, queueing
# hundreds of MB of (old, new) content pairs. Per-user keying so two
# real users on shared NAT don't compete for the same bucket.
_notes_write_limit = limiter.shared_limit(
"60 per minute", scope="notes_write", key_func=_user_key
)
# Save-as-note copies a whole completed report (up to the 50MB content
# cap) into a fresh note + version snapshot per call. At the generic
# notes_write 60/min that's on the order of GBs/min of per-user DB writes
# from one client — a disk/backup-bloat vector. Tighter, cost-aware bucket.
_notes_save_as_note_limit = limiter.shared_limit(
"10 per minute", scope="notes_save_as_note", key_func=_user_key
)
# Fact-check kicks off a full LDR research run downstream, so it's strictly
# tighter than the LLM bucket — a few per minute bounds research load.
_notes_factcheck_limit = async_shared_limit(
limiter, "3 per minute", scope="notes_factcheck", key_func=_user_key
)
router = APIRouter(prefix="/notes", tags=["notes"])
# Pre-parse request-body ceiling for this JSON API surface. The app-wide
# request size limit is sized for multi-file uploads (hundreds of GB), and
# parsing buffers the WHOLE body before any service validation runs — so
# without this check a multi-GB JSON body reached memory before
# _assert_content_size could reject it at 50 MB.
#
# Budget 2× the content cap. This bounds pre-parse memory; it does NOT
# precisely enforce the 50 MB content limit (that stays in
# _assert_content_size after parsing). 2× covers the realistic worst case
# where every character needs a 2-byte JSON escape (``"`` / ``\`` /
# newline); content dominated by control chars (each expands to a 6-byte
# ``\uXXXX``) can still exceed this and get a 413 even though its decoded
# size is under 50 MB — an acceptable trade for keeping the cap far below
# a memory-exhausting multi-GB body.
_MAX_JSON_BODY_BYTES = 2 * NOTE_CONTENT_MAX_BYTES
#: Above this size the JSON parse is handed to a worker thread. Measured on
#: the pinned interpreter with an adversarial-but-valid document (many small
#: objects, which is what an attacker sends -- not one long string, which is
#: what a benign client sends), ``json.loads`` runs at ~110 ms/MB and scales
#: linearly. So 64 KiB is ~7 ms on the loop, and the notes ceiling of 100 MB
#: would be ~11 SECONDS -- a whole-instance freeze under single-worker
#: uvicorn, where Flask's thread-per-request model only cost one thread.
#: Below the threshold the parse is sub-10 ms and dispatching it would trade
#: that for contention on the same threadpool the DB work uses.
_JSON_OFFLOAD_THRESHOLD_BYTES = 64 * 1024
async def _parse_json_off_loop(body):
"""``json.loads`` without stalling the event loop on a large body.
``asyncio.to_thread`` rather than ``run_db_sync``: this opens no DB
session, so the session cleanup that wrapper does is unnecessary
(see dependencies/threadpool.py::run_db_sync).
The bytearray is passed through without copying to ``bytes`` -- at the
notes cap that copy would itself be a 100 MB allocation, and nothing
mutates the buffer after this point.
"""
if len(body) < _JSON_OFFLOAD_THRESHOLD_BYTES:
return json.loads(body)
return await asyncio.to_thread(json.loads, body)
async def _notes_json_body(
request: Request,
) -> dict[str, Any] | JSONResponse:
"""Shared body gate for every mutating notes route.
Replaces the blueprint's two ``before_request`` hooks:
* 413 a body whose ``Content-Length`` exceeds ``_MAX_JSON_BODY_BYTES``
(bounds pre-parse memory before ``request.json()`` buffers it).
* 400 a declared-JSON body that parses to something other than an
object — ``true`` / ``123`` / ``"x"`` / ``[1, 2]`` would otherwise
slip past the routes' ``... or {}`` idioms and crash on the first
``.get`` as an opaque 500.
Returns either a ``JSONResponse`` (the caller must return it verbatim) or
the parsed dict. A missing/empty/malformed body becomes ``{}`` so each
route applies its own "no data provided" default exactly as before.
"""
def _too_large():
return JSONResponse(
{
"success": False,
"error": (
"Request body too large "
f"(max {_MAX_JSON_BODY_BYTES // (1024 * 1024)} MB)"
),
},
status_code=413,
)
# Fast path: reject a body that DECLARES an over-cap Content-Length before
# reading anything.
content_length = request.headers.get("content-length")
if content_length is not None:
try:
declared = int(content_length)
except (TypeError, ValueError):
declared = None
if declared is not None and declared > _MAX_JSON_BODY_BYTES:
return _too_large()
# Read the body from the stream with a running cap, so a chunked request
# (``Transfer-Encoding: chunked``, no Content-Length) is cut off at the
# notes ceiling BEFORE it is fully buffered — the Flask blueprint got this
# from ``arm_notes_body_cap`` setting ``request.max_content_length`` at the
# stream level; the plain Content-Length check above cannot (a chunked
# body has no Content-Length to inspect). No notes route reads the body
# again after this dependency, so consuming the stream here is safe.
body = bytearray()
async for chunk in request.stream():
body.extend(chunk)
if len(body) > _MAX_JSON_BODY_BYTES:
return _too_large()
# Keep the body cap for every media type. Flask's get_json(silent=True)
# then treated a non-JSON media type as no data, even when its bytes
# looked like JSON.
if not is_json_request(request):
return {}
if not body:
# Missing/empty body — leave the route to default as it sees fit
# (matches Flask's ``get_json(silent=True) -> None``).
return {}
try:
data = await _parse_json_off_loop(body)
except Exception:
# Malformed JSON — same "leave the route to default" behavior.
return {}
if not isinstance(data, dict):
return JSONResponse(
{
"success": False,
"error": "Request body must be a JSON object",
},
status_code=400,
)
return data
_NotesBody = Annotated[
dict[str, Any] | JSONResponse,
Depends(_notes_json_body),
]
def _trigger_note_auto_index(note_id, service, username, session_id):
"""Trigger async auto-indexing for a note (non-blocking)."""
try:
from ...web.routers.rag import trigger_auto_index
from ...database.session_passwords import session_password_store
db_password = session_password_store.get_session_password(
username, session_id
)
if not db_password:
logger.debug(
"Skipping note auto-index for {}: no session password available",
note_id,
)
return
collection_id = service.get_notes_collection_id()
if not collection_id:
logger.debug(
"Skipping note auto-index for {}: no notes collection",
note_id,
)
return
trigger_auto_index([note_id], collection_id, username, db_password)
except Exception:
logger.exception("Failed to trigger auto-indexing for note")
# ============================================================================
# Page Routes
# ============================================================================
@router.get("/")
def notes_page(
request: Request, username: Annotated[str, Depends(require_auth)]
):
"""Render the notes list page."""
return templates.TemplateResponse(
request=request,
name="pages/notes.html",
context={"active_page": "notes"},
)
@router.get("/{note_id}")
def note_detail_page(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Render the note detail page."""
from ..utils.path_ids import validated_uuid_path_param
note_id = validated_uuid_path_param(note_id, "Note")
return templates.TemplateResponse(
request=request,
name="pages/note_detail.html",
context={"active_page": "notes", "note_id": note_id},
)
# ============================================================================
# API Routes - Notes CRUD
# ============================================================================
@router.get("/api/notes")
@_notes_search_limit
def list_notes(
request: Request, username: Annotated[str, Depends(require_auth)]
):
"""
List notes with optional filtering.
Query params:
collection_id: Filter by collection
search: Search in title and content (capped at MAX_SEARCH_LEN)
pinned_only: Only return pinned notes
limit: Maximum number (default 100)
offset: Offset for pagination (default 0)
"""
try:
service = NoteService(username)
collection_id = request.query_params.get("collection_id")
try:
search = _clamp_text_query(
request.query_params.get("search"), "search"
)
except ValueError:
return JSONResponse(
{
"success": False,
"error": (
f"search exceeds maximum length "
f"({MAX_SEARCH_LEN} chars)"
),
},
status_code=400,
)
pinned_only = (
request.query_params.get("pinned_only", "").lower() == "true"
)
try:
limit = _clamp_limit(request, 100)
offset = max(0, int(request.query_params.get("offset", 0)))
except (ValueError, TypeError):
return JSONResponse(
{"success": False, "error": "Invalid limit or offset"},
status_code=400,
)
# Total under the same filter — lets the frontend render a real
# page-N-of-M control rather than guessing from len(notes) ==
# limit. count_notes repeats the filtered scan list_notes runs
# (for a keyword search that is a second full ILIKE pass over
# text_content), so skip it when a short first page already
# reveals the total.
if offset == 0:
notes = service.list_notes(
collection_id=collection_id,
search=search,
pinned_only=pinned_only,
limit=limit,
offset=0,
)
total = (
len(notes)
if len(notes) < limit
else service.count_notes(
collection_id=collection_id,
search=search,
pinned_only=pinned_only,
)
)
else:
total = service.count_notes(
collection_id=collection_id,
search=search,
pinned_only=pinned_only,
)
# Clamp an offset past the end of the result set: it returns
# an empty page anyway, so don't make the DB scan-and-discard
# `offset` rows for a guaranteed-empty result (mirrors
# get_note_versions).
if offset > total:
offset = total
notes = service.list_notes(
collection_id=collection_id,
search=search,
pinned_only=pinned_only,
limit=limit,
offset=offset,
)
return {
"success": True,
"notes": notes,
"total": total,
"limit": limit,
"offset": offset,
}
except Exception as e:
return handle_api_error("listing notes", e)
@router.post("/api/notes")
@_notes_write_limit
def create_note(
request: Request,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""
Create a new note.
Body:
title: Note title (required)
content: Note content (required)
tags: List of tags (optional)
collection_ids: List of collection IDs (optional)
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
if not isinstance(data, dict) or not data:
# get_json returns the parsed body verbatim, so a top-level JSON
# array/string/number would pass a bare truthiness check and then
# crash data.get() with AttributeError → opaque 500. Require an
# object.
return JSONResponse(
{"success": False, "error": "No data provided"},
status_code=400,
)
title = data.get("title")
content = data.get("content")
if not title:
return JSONResponse(
{"success": False, "error": "Title is required"},
status_code=400,
)
if not content:
return JSONResponse(
{"success": False, "error": "Content is required"},
status_code=400,
)
service = NoteService(username)
note_id = service.create_note(
title=title,
content=content,
tags=data.get("tags"),
collection_ids=data.get("collection_ids"),
)
# Trigger async auto-indexing (non-blocking)
_trigger_note_auto_index(
note_id, service, username, request.session.get("session_id")
)
return JSONResponse({"success": True, "id": note_id}, status_code=201)
except ValueError:
# Never serialize exception text at the HTTP boundary. Even callers
# that normally raise fixed validation messages can regress to an
# exception containing paths, SQL, credentials, or library internals.
return JSONResponse(
{"success": False, "error": "Invalid note data"}, status_code=400
)
except Exception as e:
return handle_api_error("creating note", e)
# ---------------------------------------------------------------------------
# Literal-path GET routes under /api/notes/... MUST be registered before
# GET /api/notes/{note_id} below — Starlette matches routes in registration
# order, so otherwise ``/api/notes/semantic-search`` etc. would be captured
# by the ``{note_id}`` route. (Flask's URL map gave static rules priority
# automatically; FastAPI does not.)
# ---------------------------------------------------------------------------
@router.get("/api/notes/semantic-search")
@_notes_search_limit
def semantic_search_notes(
request: Request, username: Annotated[str, Depends(require_auth)]
):
"""
Search notes using semantic similarity.
Finds notes by meaning rather than keyword matching.
Query params:
q: Search query (required)
limit: Maximum results (default 10)
min_similarity: Minimum similarity threshold 0.0-1.0 (default 0.3)
collection_id: Optional — restrict results to this collection's notes
(matches the text-search filter).
"""
try:
try:
query = _clamp_text_query(request.query_params.get("q", ""), "q")
except ValueError:
return JSONResponse(
{
"success": False,
"error": f"q exceeds maximum length ({MAX_SEARCH_LEN} chars)",
},
status_code=400,
)
query = (query or "").strip()
if not query:
return JSONResponse(
{"success": False, "error": "Query is required"},
status_code=400,
)
try:
limit = _clamp_limit(request, 10)
min_similarity_raw = float(
request.query_params.get("min_similarity", 0.3)
)
min_similarity = max(0.0, min(min_similarity_raw, 1.0))
except (ValueError, TypeError):
return JSONResponse(
{"success": False, "error": "Invalid limit or min_similarity"},
status_code=400,
)
if not math.isfinite(min_similarity_raw):
logger.warning(
"notes_api validation reject: min_similarity={!r} (non-finite) "
"(user={!r})",
min_similarity_raw,
username,
)
return JSONResponse(
{"success": False, "error": "Invalid limit or min_similarity"},
status_code=400,
)
collection_id = request.query_params.get("collection_id") or None
service = NoteAIService(username)
results = service.semantic_search(
query,
limit=limit,
min_similarity=min_similarity,
collection_id=collection_id,
)
return {
"success": True,
"query": query,
"results": results,
"count": len(results),
}
except Exception as e:
return handle_api_error("semantic search", e)
@router.get("/api/notes/ask-context")
@_notes_search_limit
def ask_context(
request: Request, username: Annotated[str, Depends(require_auth)]
):
"""Pre-flight context for the 'Ask your notes' box: the Notes collection
id + note/indexed counts, so the UI can warn when there's nothing to
search before starting a research run pinned to that collection.
"""
try:
service = NoteService(username)
status = service.get_notes_index_status()
return {"success": True, **status}
except Exception as e:
return handle_api_error("getting ask-notes context", e)
@router.get("/api/notes/search-for-linking")
@_notes_search_limit
def search_notes_for_linking(
request: Request, username: Annotated[str, Depends(require_auth)]
):
"""
Search notes for the [[link]] autocomplete feature.
Query params:
query: Search query (partial title match)
exclude_note_id: Note ID to exclude from results
limit: Maximum number of results (default 10)
"""
try:
try:
query = _clamp_text_query(
request.query_params.get("query", ""), "query"
)
except ValueError:
return JSONResponse(
{
"success": False,
"error": (
f"query exceeds maximum length ({MAX_SEARCH_LEN} chars)"
),
},
status_code=400,
)
if not query:
return {"success": True, "notes": []}
exclude_note_id = request.query_params.get("exclude_note_id")
try:
limit = _clamp_limit(request, 10)
except (ValueError, TypeError):
return JSONResponse(
{"success": False, "error": "Invalid limit"}, status_code=400
)
service = NoteService(username)
notes = service.search_notes_for_linking(query, exclude_note_id, limit)
return {"success": True, "notes": notes}
except Exception as e:
return handle_api_error("searching notes for linking", e)
@router.get("/api/notes/{note_id}")
def get_note(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Get a specific note."""
try:
service = NoteService(username)
note = service.get_note(note_id)
if not note:
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
return {"success": True, "note": note}
except Exception as e:
return handle_api_error("getting note", e)
@router.put("/api/notes/{note_id}")
@_notes_write_limit
def update_note(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""
Update a note.
Body:
title: New title (optional)
content: New content (optional)
tags: New tags (optional)
pinned: New pinned status (optional) — wire-level alias for the
``Document.favorite`` column; the UI vocabulary is "pin".
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
if not data:
return JSONResponse(
{"success": False, "error": "No data provided"},
status_code=400,
)
# Every sibling field gets a clean 400 via the service validators
# (_validate_title/_assert_content_size/_validate_tags); pinned is
# assigned straight into the Boolean column, where a non-bool
# raises StatementError at flush → an opaque 500.
pinned = data.get("pinned")
if pinned is not None and not isinstance(pinned, bool):
return JSONResponse(
{"success": False, "error": "pinned must be a boolean"},
status_code=400,
)
service = NoteService(username)
content_provided = data.get("content") is not None
try:
success = service.update_note(
note_id=note_id,
title=data.get("title"),
content=data.get("content"),
tags=data.get("tags"),
favorite=pinned,
)
except ValueError:
return JSONResponse(
{"success": False, "error": "Invalid note data"},
status_code=400,
)
if not success:
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
# Trigger async auto-indexing if content OR title was updated
# (non-blocking). The service marks DocumentCollection.indexed=False
# for either change and relies on this post-commit trigger; the
# title is baked into every chunk's metadata at index time, so a
# rename leaves stale titles in search results until reindexed. A
# title-only PUT used to flip indexed=False without ever scheduling
# the reindex. Unchanged values are harmless: the worker runs with
# force_reindex=False and skips rows still marked indexed=True.
if content_provided or data.get("title") is not None:
_trigger_note_auto_index(
note_id, service, username, request.session.get("session_id")
)
return {"success": True}
except Exception as e:
return handle_api_error("updating note", e)
@router.delete("/api/notes/{note_id}")
@_notes_write_limit
def delete_note(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Delete a note."""
try:
service = NoteService(username)
success = service.delete_note(note_id)
if not success:
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
return {"success": True}
except Exception as e:
return handle_api_error("deleting note", e)
# ============================================================================
# API Routes - Collections
# ============================================================================
@router.get("/api/notes/{note_id}/collections")
def get_note_collections(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Get collections a note belongs to."""
try:
service = NoteService(username)
# 404 on unknown note id rather than returning an empty list.
# Pre-fix, a typo in the note UUID returned 200 with [] —
# indistinguishable from "this note has no collections" — making
# client-side bugs invisible to QA. The sibling get_note route
# already 404s for unknown ids; align with that contract.
if not service.note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
collections = service.get_note_collections(note_id)
return {"success": True, "collections": collections}
except Exception as e:
return handle_api_error("getting note collections", e)
@router.post("/api/notes/{note_id}/collections")
@_notes_write_limit
def add_note_to_collection(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""
Add a note to a collection.
Body:
collection_id: The collection ID
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
if not data or not data.get("collection_id"):
return JSONResponse(
{"success": False, "error": "collection_id is required"},
status_code=400,
)
service = NoteService(username)
# add_to_collection returns the same False for "note id missing /
# not a note" and "already a member"; without this guard a stale
# id (note deleted in another tab) produced a factually wrong 409
# "Already in collection". 404 first, like get_note_collections.
if not service.note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
success = service.add_to_collection(note_id, data["collection_id"])
if not success:
return JSONResponse(
{"success": False, "error": "Already in collection"},
status_code=409,
)
return {"success": True}
except LookupError:
return JSONResponse(
{"success": False, "error": "Collection not found"},
status_code=404,
)
except Exception as e:
return handle_api_error("adding note to collection", e)
@router.delete("/api/notes/{note_id}/collections/{collection_id}")
@_notes_write_limit
def remove_note_from_collection(
request: Request,
note_id: str,
collection_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Remove a note from a collection."""
try:
service = NoteService(username)
# Same conflation as add_note_to_collection: a missing/non-note id
# used to 404 with the misleading "Not in collection" message.
if not service.note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
success = service.remove_from_collection(note_id, collection_id)
if not success:
return JSONResponse(
{"success": False, "error": "Not in collection"},
status_code=404,
)
return {"success": True}
except ValueError:
return JSONResponse(
{
"success": False,
"error": "Note cannot be removed from this collection",
},
status_code=400,
)
except Exception as e:
return handle_api_error("removing note from collection", e)
# ============================================================================
# API Routes - Research
# ============================================================================
@router.get("/api/notes/{note_id}/research")
def get_note_research(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Get research runs triggered from a note."""
try:
service = NoteService(username)
# 404 on unknown note id — see get_note_collections for the
# rationale. The two routes had the same contract gap.
if not service.note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
research = service.get_note_research(note_id)
return {"success": True, "research": research}
except Exception as e:
return handle_api_error("getting note research", e)
@router.post("/api/notes/{note_id}/research")
@_notes_write_limit
def link_research_to_note(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""
Link a research run to a note.
Body:
research_id: The research history ID
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
if not data or not data.get("research_id"):
return JSONResponse(
{"success": False, "error": "research_id is required"},
status_code=400,
)
service = NoteService(username)
if not service.note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
link_id = service.link_research_to_note(
note_id=note_id,
research_id=data["research_id"],
)
return JSONResponse({"success": True, "id": link_id}, status_code=201)
except ValueError:
# The pre-check above answers 404 for an id that was already unknown.
# A note DELETED between that check and the service call lands here
# instead (the service raises ValueError("... not found")), so re-run
# the existence check to keep that narrow race answering 404 rather
# than a misleading "cannot be linked" 400. Best-effort: this runs
# inside an except handler, so a failure of the re-check itself must
# not replace the 400 with a 500.
try:
if not NoteService(username).note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"},
status_code=404,
)
except Exception:
logger.warning(
"notes_api: note_exists re-check failed while classifying a "
"link-research failure (user={!r})",
username,
)
return JSONResponse(
{
"success": False,
"error": "Research cannot be linked to this note",
},
status_code=400,
)
except IntegrityError as exc:
# Only the (document_id, research_id) uniqueness collision means the
# research is already linked → 409. A display_order retry-exhaustion
# or an FK race (stale/deleted research_id) also surfaces as
# IntegrityError but is NOT a duplicate — don't mislabel those as
# "already linked"; let them fall through to a generic error.
msg = str(getattr(exc, "orig", exc)).lower()
if "foreign key" in msg:
# research_id references a research run that doesn't exist (or
# was deleted) — a client-fixable 404, not an opaque 500.
return JSONResponse(
{"success": False, "error": "Research run not found"},
status_code=404,
)
if "display_order" in msg:
return handle_api_error("linking research to note", exc)
return JSONResponse(
{"success": False, "error": "Research already linked to this note"},
status_code=409,
)
except Exception as e:
return handle_api_error("linking research to note", e)
@router.patch("/api/notes/{note_id}/research/{research_id}")
@_notes_write_limit
def patch_note_research(
request: Request,
note_id: str,
research_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Update a NoteResearch row (currently supports is_collapsed toggle).
Body:
is_collapsed: bool (optional)
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
# Omitted: is_collapsed stays None and is passed through (no-op).
is_collapsed = data.get("is_collapsed")
if "is_collapsed" in data and not isinstance(
data["is_collapsed"], bool
):
logger.warning(
"notes_api validation reject: is_collapsed={} (type={}) "
"(user={!r})",
_log_value_preview(data["is_collapsed"]),
type(data["is_collapsed"]).__name__,
username,
)
return JSONResponse(
{
"success": False,
"error": "is_collapsed must be a boolean",
},
status_code=400,
)
service = NoteService(username)
updated = service.update_note_research(
note_id=note_id,
research_id=research_id,
is_collapsed=is_collapsed,
)
if not updated:
return JSONResponse(
{"success": False, "error": "Research link not found"},
status_code=404,
)
return {"success": True}
except Exception as e:
return handle_api_error("updating note research", e)
@router.post("/api/notes/{note_id}/research/reorder")
@_notes_write_limit
def reorder_note_research(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Atomically reorder research items for a note.
Body:
research_ids: list of research_id strings in desired display order.
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
research_ids = data.get("research_ids")
if not isinstance(research_ids, list) or not research_ids:
return JSONResponse(
{
"success": False,
"error": "research_ids must be a non-empty list",
},
status_code=400,
)
if not all(isinstance(r, str) for r in research_ids):
# Non-string elements (nested arrays/objects) are unhashable and
# crash the dedup/reorder logic with TypeError → opaque 500.
return JSONResponse(
{
"success": False,
"error": "research_ids must be a list of strings",
},
status_code=400,
)
service = NoteService(username)
# 404 a stale/deleted note id BEFORE the ids-match check, mirroring
# every sibling note-scoped route (get_note_research,
# add_note_to_collection, ...). Otherwise reorder_note_research finds
# no NoteResearch rows for the missing note, returns False on the
# ids-mismatch path, and the route misreports a 404 condition (note
# deleted in another tab) as a 400 validation error.
if not service.note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
ok = service.reorder_note_research(note_id, research_ids)
if not ok:
return JSONResponse(
{
"success": False,
"error": "research_ids do not match the note's linked research",
},
status_code=400,
)
return {"success": True}
except ValueError:
return JSONResponse(
{"success": False, "error": "Invalid research order"},
status_code=400,
)
except Exception as e:
return handle_api_error("reordering note research", e)
# ============================================================================
# API Routes - Research → Notes (results-page Notes panel)
# ============================================================================
@router.get("/api/research/{research_id}/notes")
@_notes_search_limit
def get_research_notes(
request: Request,
research_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""List the notes linked to a research run.
The reverse of GET /api/notes/<id>/research — powers the Notes panel
on the research results page, so commentary attached to a run is
visible from the run itself, not only from the note.
"""
try:
service = NoteService(username)
notes = service.get_notes_for_research(research_id)
if notes is None:
return JSONResponse(
{"success": False, "error": "Research not found"},
status_code=404,
)
return {"success": True, "notes": notes}
except Exception as e:
return handle_api_error("listing notes for research", e)
@router.post("/api/research/{research_id}/notes")
@_notes_write_limit
def create_research_note(
request: Request,
research_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Create a note pre-linked to a research run (all-or-nothing).
Body (all optional): ``title``, ``content``, ``tags``. Defaults
produce a starter note titled after the research query. The results
page's "Add note" (no body) and "Clip to note" (content = the quoted
selection) both come through here.
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
service = NoteService(username)
try:
note_id = service.create_note_for_research(
research_id,
title=data.get("title"),
content=data.get("content"),
tags=data.get("tags"),
)
except LookupError:
return JSONResponse(
{"success": False, "error": "Research not found"},
status_code=404,
)
# Reach semantic search / "Ask your notes" like a normally-created
# note (the plain POST /api/notes route does the same at its tail).
_trigger_note_auto_index(
note_id, service, username, request.session.get("session_id")
)
return JSONResponse(
{"success": True, "note_id": note_id}, status_code=201
)
except ValueError:
return JSONResponse(
{"success": False, "error": "Invalid note data"}, status_code=400
)
except Exception as e:
return handle_api_error("creating note for research", e)
@router.post("/api/research/{research_id}/save-as-note")
@_notes_save_as_note_limit
def save_research_as_note(
request: Request,
research_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Copy a COMPLETED research run's report into a new, linked note.
Deliberately a derivation, not a conversion: the report stays the
immutable record (fact-check grades claims against it and its
provenance must survive), while the note is the user's editable
copy. Provenance is kept twice — the NoteResearch link and a header
line inside the note content — so the copy stays traceable even if
it is later unlinked.
"""
if isinstance(body, JSONResponse):
return body
try:
from ...constants import ResearchStatus
from ...database.models import ResearchHistory
from ...database.session_context import get_user_db_session
from ...storage import get_report_storage
with get_user_db_session(username) as db:
research = (
db.query(ResearchHistory).filter_by(id=research_id).first()
)
if research is None:
return JSONResponse(
{"success": False, "error": "Research not found"},
status_code=404,
)
if research.status != ResearchStatus.COMPLETED:
return JSONResponse(
{
"success": False,
"error": "Research is not complete yet.",
"status": research.status,
},
status_code=409,
)
query_text = (research.query or "").strip()
meta = dict(research.research_meta or {})
# Fetch the report markdown in-request (same pattern as the
# fact-check grade flow: the per-user DB password is available
# here, unlike in a background worker).
settings_snapshot = meta.get("settings_snapshot")
with get_user_db_session(username) as db:
storage = get_report_storage(
session=db, settings_snapshot=settings_snapshot
)
report = storage.get_report(research_id, username)
if not report or not str(report).strip():
# get_report returns None for BOTH a missing report and a
# swallowed read error; saving an empty note would look like
# success while losing the content. Refuse instead.
return JSONResponse(
{
"success": False,
"error": (
"The research report is unavailable, so it cannot "
"be saved as a note. Try re-running the research."
),
},
status_code=502,
)
from ...research_library.notes.services.note_service import (
MAX_TITLE_LENGTH,
)
title = (
f"Research: {query_text}"[:MAX_TITLE_LENGTH]
if query_text
else f"Research {research_id[:8]}"
)
provenance = (
f"> Saved from the research run "
f"[{escape_markdown_link_label(query_text or research_id)}]"
f"(/results/{research_id}).\n\n"
)
service = NoteService(username)
try:
note_id = service.create_note_for_research(
research_id, title=title, content=provenance + str(report)
)
except LookupError:
# Deleted between the checks above and the create — treat like
# any other missing research.
return JSONResponse(
{"success": False, "error": "Research not found"},
status_code=404,
)
_trigger_note_auto_index(
note_id, service, username, request.session.get("session_id")
)
return JSONResponse(
{"success": True, "note_id": note_id}, status_code=201
)
except ValueError:
return JSONResponse(
{
"success": False,
"error": "Research cannot be saved as a note",
},
status_code=400,
)
except Exception as e:
return handle_api_error("saving research as note", e)
# ============================================================================
# API Routes - Inline annotations (Word-review-style comments) and
# document-linked notes. Targets: research runs and library documents —
# both have IMMUTABLE rendered text, so quote anchors can never drift.
# The comment itself is a full NOTE; the anchor lives in note_references.
# ============================================================================
MAX_ANNOTATION_COMMENT_LEN = 5000
MAX_ANNOTATION_QUOTE_LEN = 1000
MAX_ANNOTATION_CONTEXT_LEN = 100
def _validated_annotation_fields(data):
"""Validate/trim an annotation payload; raises ValueError.
Type-checks every field before touching it: a non-string comment
(e.g. ``{"comment": 123}`` from a direct API caller) would otherwise
crash on ``.strip()`` as an opaque 500 instead of the clean 400 the
length checks produce.
"""
for field in ("comment", "quote", "prefix", "suffix"):
value = data.get(field)
if value is not None and not isinstance(value, str):
raise ValueError(f"{field} must be a string")
comment = (data.get("comment") or "").strip()
quote = (data.get("quote") or "").strip()
if not comment:
raise ValueError("comment is required")
if not quote:
raise ValueError("quote is required")
if len(comment) > MAX_ANNOTATION_COMMENT_LEN:
raise ValueError(
f"comment exceeds maximum length "
f"({MAX_ANNOTATION_COMMENT_LEN} chars)"
)
if len(quote) > MAX_ANNOTATION_QUOTE_LEN:
raise ValueError(
f"quote exceeds maximum length ({MAX_ANNOTATION_QUOTE_LEN} chars)"
)
prefix = (data.get("prefix") or "")[-MAX_ANNOTATION_CONTEXT_LEN:]
suffix = (data.get("suffix") or "")[:MAX_ANNOTATION_CONTEXT_LEN]
return comment, quote, prefix, suffix
def _comment_note_title(comment):
"""Derive the comment-note's title from its first words."""
one_line = " ".join(comment.split())
if len(one_line) > 60:
one_line = one_line[:60].rstrip() + "…"
return f"Comment: {one_line}"
# Length of the comment preview echoed back in an annotation response (was
# a bare 300 duplicated across both create-annotation handlers).
_ANNOTATION_COMMENT_PREVIEW_CHARS = 300
def _annotation_response(note_id, comment, quote, prefix, suffix):
"""The annotation-created response payload shared by the research and
document create-annotation handlers (previously byte-identical dicts)."""
return {
"note_id": note_id,
"quote": quote,
"prefix": prefix,
"suffix": suffix,
"note_title": _comment_note_title(comment),
"comment_preview": comment[:_ANNOTATION_COMMENT_PREVIEW_CHARS],
}
def _comment_note_content(comment, quote, target_label, target_url):
"""Comment-first note body: remark, quoted passage, provenance.
``target_label`` (a research query or a library document title, both
potentially untrusted) is escaped so it can't break out of the
provenance link — see ``escape_markdown_link_label``.
"""
quote_block = "\n".join(f"> {line}" for line in quote.split("\n"))
label = escape_markdown_link_label(target_label)
return (
f"{comment}\n\n{quote_block}\n\n— comment on [{label}]({target_url})\n"
)
def _research_exists(username, research_id):
"""(exists, query_text) for a research id in the user's DB."""
from ...database.models import ResearchHistory
from ...database.session_context import get_user_db_session
with get_user_db_session(username) as db:
row = (
db.query(ResearchHistory.id, ResearchHistory.query)
.filter_by(id=research_id)
.first()
)
if row is None:
return False, None
return True, (row.query or "").strip()
@router.get("/api/research/{research_id}/annotations")
@_notes_search_limit
def get_research_annotations(
request: Request,
research_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""List a research run's inline annotations (anchored comment notes)."""
try:
exists, _query = _research_exists(username, research_id)
if not exists:
return JSONResponse(
{"success": False, "error": "Research not found"},
status_code=404,
)
service = NoteService(username)
annotations = service.get_annotations_for_target(
research_id=research_id
)
return {"success": True, "annotations": annotations}
except Exception as e:
return handle_api_error("listing research annotations", e)
@router.post("/api/research/{research_id}/annotations")
@_notes_write_limit
def create_research_annotation(
request: Request,
research_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Attach a comment to a passage of the research report.
Body: ``quote`` (the selected rendered text), optional ``prefix`` /
``suffix`` (Hypothesis-style disambiguation context), ``comment``.
The comment becomes a NOTE linked to the run; the anchor is a
note_references row.
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
comment, quote, prefix, suffix = _validated_annotation_fields(data)
exists, query_text = _research_exists(username, research_id)
if not exists:
return JSONResponse(
{"success": False, "error": "Research not found"},
status_code=404,
)
service = NoteService(username)
note_id = service.create_note_for_research(
research_id,
title=_comment_note_title(comment),
content=_comment_note_content(
comment,
quote,
query_text or research_id,
f"/results/{research_id}",
),
quote=quote,
prefix=prefix,
suffix=suffix,
)
_trigger_note_auto_index(
note_id, service, username, request.session.get("session_id")
)
return JSONResponse(
{
"success": True,
"annotation": _annotation_response(
note_id, comment, quote, prefix, suffix
),
},
status_code=201,
)
except LookupError:
return JSONResponse(
{"success": False, "error": "Research not found"}, status_code=404
)
except ValueError:
return JSONResponse(
{"success": False, "error": "Invalid annotation data"},
status_code=400,
)
except Exception as e:
return handle_api_error("creating research annotation", e)
@router.delete("/api/research/{research_id}/annotations/{note_id}")
@_notes_write_limit
def delete_research_annotation(
request: Request,
research_id: str,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Remove an annotation: the comment note is deleted (standard delete
path — version cascade, vector purge) and its anchor row cascades."""
try:
service = NoteService(username)
if not service.has_annotation(note_id, research_id=research_id):
return JSONResponse(
{"success": False, "error": "Annotation not found"},
status_code=404,
)
service.delete_note(note_id)
return {"success": True}
except Exception as e:
return handle_api_error("deleting research annotation", e)
# ---- Library documents: same surface, document targets --------------------
@router.get("/api/documents/{document_id}/notes")
@_notes_search_limit
def get_document_notes(
request: Request,
document_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""List the notes referencing a library document (its Notes panel)."""
try:
service = NoteService(username)
notes = service.get_notes_for_document(document_id)
if notes is None:
return JSONResponse(
{"success": False, "error": "Document not found"},
status_code=404,
)
return {"success": True, "notes": notes}
except Exception as e:
return handle_api_error("listing notes for document", e)
@router.post("/api/documents/{document_id}/notes")
@_notes_write_limit
def create_document_note(
request: Request,
document_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Create a note referencing a library document (all-or-nothing).
Body (all optional): ``title``, ``content``, ``tags``. Defaults
produce a starter note titled after the document.
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
service = NoteService(username)
try:
note_id = service.create_note_for_document(
document_id,
title=data.get("title"),
content=data.get("content"),
tags=data.get("tags"),
)
except LookupError:
return JSONResponse(
{"success": False, "error": "Document not found"},
status_code=404,
)
_trigger_note_auto_index(
note_id, service, username, request.session.get("session_id")
)
return JSONResponse(
{"success": True, "note_id": note_id}, status_code=201
)
except ValueError:
return JSONResponse(
{"success": False, "error": "Invalid document note data"},
status_code=400,
)
except Exception as e:
return handle_api_error("creating note for document", e)
@router.get("/api/documents/{document_id}/annotations")
@_notes_search_limit
def get_document_annotations(
request: Request,
document_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""List a library document's inline annotations."""
try:
service = NoteService(username)
# Existence gate doubles as the 404 (get_notes_for_document
# checks the Document row).
if service.get_notes_for_document(document_id) is None:
return JSONResponse(
{"success": False, "error": "Document not found"},
status_code=404,
)
annotations = service.get_annotations_for_target(
document_id=document_id
)
return {"success": True, "annotations": annotations}
except Exception as e:
return handle_api_error("listing document annotations", e)
@router.post("/api/documents/{document_id}/annotations")
@_notes_write_limit
def create_document_annotation(
request: Request,
document_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Attach a comment to a passage of a library document's text."""
if isinstance(body, JSONResponse):
return body
try:
data = body
comment, quote, prefix, suffix = _validated_annotation_fields(data)
from ...database.models import Document
from ...database.session_context import get_user_db_session
with get_user_db_session(username) as db:
row = (
db.query(Document.id, Document.title)
.filter_by(id=document_id)
.first()
)
if row is None:
return JSONResponse(
{"success": False, "error": "Document not found"},
status_code=404,
)
doc_title = (row.title or "").strip() or document_id
service = NoteService(username)
note_id = service.create_note_for_document(
document_id,
title=_comment_note_title(comment),
content=_comment_note_content(
comment,
quote,
doc_title,
f"/library/document/{document_id}",
),
quote=quote,
prefix=prefix,
suffix=suffix,
)
_trigger_note_auto_index(
note_id, service, username, request.session.get("session_id")
)
return JSONResponse(
{
"success": True,
"annotation": _annotation_response(
note_id, comment, quote, prefix, suffix
),
},
status_code=201,
)
except LookupError:
return JSONResponse(
{"success": False, "error": "Document not found"}, status_code=404
)
except ValueError:
return JSONResponse(
{"success": False, "error": "Invalid annotation data"},
status_code=400,
)
except Exception as e:
return handle_api_error("creating document annotation", e)
@router.delete("/api/documents/{document_id}/annotations/{note_id}")
@_notes_write_limit
def delete_document_annotation(
request: Request,
document_id: str,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Remove a document annotation (deletes the comment note; the
anchor row cascades)."""
try:
service = NoteService(username)
if not service.has_annotation(note_id, document_id=document_id):
return JSONResponse(
{"success": False, "error": "Annotation not found"},
status_code=404,
)
service.delete_note(note_id)
return {"success": True}
except Exception as e:
return handle_api_error("deleting document annotation", e)
# ============================================================================
# API Routes - RAG Indexing
# ============================================================================
@router.post("/api/notes/{note_id}/index")
@_notes_write_limit
def index_note_to_collection(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""
Index a note into a collection for RAG search.
Body:
collection_id: The collection to index the note into (required)
force_reindex: Whether to force reindexing (optional, default false)
"""
from ...web.routers.rag import _client_indexing_error, get_rag_service
if isinstance(body, JSONResponse):
return body
try:
data = body
if not data or not data.get("collection_id"):
return JSONResponse(
{"success": False, "error": "collection_id is required"},
status_code=400,
)
collection_id = data["collection_id"]
# Omitted: defaults to False (do not force-reindex).
force_reindex = data.get("force_reindex", False)
if not isinstance(force_reindex, bool):
logger.warning(
"notes_api validation reject: force_reindex={} (type={}) "
"(user={!r})",
_log_value_preview(force_reindex),
type(force_reindex).__name__,
username,
)
return JSONResponse(
{
"success": False,
"error": "force_reindex must be a boolean",
},
status_code=400,
)
# Verify the id is actually a note before indexing — every sibling
# note route guards this, but this one passed the id straight to the
# RAG service, which would index an arbitrary user document.
if not NoteService(username).note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
# Get RAG service configured for the collection
with get_rag_service(request, username, collection_id) as rag_service:
# Index the note (notes are now documents)
result = rag_service.index_document(
document_id=note_id,
collection_id=collection_id,
force_reindex=force_reindex,
)
if result["status"] == "error":
# Same boundary as the RAG document routes: known document
# guidance passes, any other service text is withheld.
return JSONResponse(
{
"success": False,
"error": _client_indexing_error(result.get("error")),
},
status_code=400,
)
return {"success": True, "result": result}
except Exception as e:
return handle_api_error("indexing note", e)
# ============================================================================
# API Routes - AI Features
# (semantic_search_notes is registered above, before GET /api/notes/{note_id})
# ============================================================================
@router.get("/api/notes/{note_id}/similar")
@_notes_search_limit
def get_similar_notes(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""
Find notes similar to the given note using embeddings.
Query params:
limit: Maximum number of results (default 5)
"""
try:
try:
limit = _clamp_limit(request, 5)
except (ValueError, TypeError):
return JSONResponse(
{"success": False, "error": "Invalid limit"}, status_code=400
)
# 404 on unknown note id — the AI service returns [] for both a
# missing note and a note with no similar matches, which made a
# stale id indistinguishable from a real-empty result. Same guard
# as get_note_collections / get_note_research.
if not NoteService(username).note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
service = NoteAIService(username)
similar = service.find_similar_notes(note_id, limit=limit)
return {"success": True, "similar_notes": similar}
except Exception as e:
return handle_api_error("finding similar notes", e)
@router.post("/api/notes/{note_id}/summarize")
@_notes_ai_limit
async def summarize_note(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Generate an AI summary of the note."""
if isinstance(body, JSONResponse):
return body
try:
service = NoteAIService(username)
summary = await service.summarize_note(note_id)
# summarize_note returns None only for a missing/empty note (real LLM
# failures raise → handled below as 500). That's a client/data
# condition, so 404 — consistent with the sibling AI endpoints.
if summary is None:
return JSONResponse(
{"success": False, "error": "Note not found or empty"},
status_code=404,
)
return {"success": True, "summary": summary}
except LLMNotConfiguredError:
# Same contract as suggest-tags: an unconfigured LLM is a
# client-state problem, not a 500. See
# ``_llm_not_configured_response``.
return _llm_not_configured_response("summarize")
except Exception as e:
return handle_api_error("summarizing note", e)
@router.post("/api/notes/{note_id}/research-questions")
@_notes_ai_limit
async def extract_research_questions(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Extract potential research questions from the note."""
if isinstance(body, JSONResponse):
return body
try:
# 404 on unknown note id — see get_similar_notes for the rationale.
if not await run_db_sync(NoteService(username).note_exists, note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
service = NoteAIService(username)
questions = await service.extract_research_questions(note_id)
return {"success": True, "questions": questions}
except LLMNotConfiguredError:
# Same contract as suggest-tags: an unconfigured LLM is a
# client-state problem, not a 500. See
# ``_llm_not_configured_response``.
return _llm_not_configured_response("research-questions")
except Exception as e:
return handle_api_error("extracting research questions", e)
@router.post("/api/notes/suggest-tags")
@_notes_ai_limit
async def suggest_tags(
request: Request,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""
Suggest tags for note content.
Body:
content: The note content to analyze
existing_tags: Current tags to avoid duplicates (optional)
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
if not data or not data.get("content"):
return JSONResponse(
{"success": False, "error": "content is required"},
status_code=400,
)
# Cap body size — same MAX_CONTENT_SIZE used by create_note /
# update_note. Without this, the route accepts unbounded text and
# holds it all in memory while the LLM call runs.
_assert_content_size(data["content"])
# existing_tags is interpolated/joined downstream; a non-list (or a
# list with non-string items) would raise deep in the service and
# surface as an opaque 500. Validate to a clean 400 here.
existing_tags = data.get("existing_tags")
if existing_tags is not None and (
not isinstance(existing_tags, list)
or not all(isinstance(t, str) for t in existing_tags)
):
return JSONResponse(
{
"success": False,
"error": "existing_tags must be a list of strings",
},
status_code=400,
)
# Cap count + per-item length like _validate_tags does on the
# create/update paths. suggest_tags joins the WHOLE list before
# truncating the joined result, so without a cap a client could send a
# multi-MB existing_tags array (within the body ceiling, at 10/min) and
# force a large in-memory join on every call.
if existing_tags is not None and (
len(existing_tags) > MAX_TAGS_PER_NOTE
or any(len(t) > MAX_TAG_LENGTH for t in existing_tags)
):
return JSONResponse(
{
"success": False,
"error": (
f"existing_tags exceeds limits (max "
f"{MAX_TAGS_PER_NOTE} tags, {MAX_TAG_LENGTH} chars each)"
),
},
status_code=400,
)
service = NoteAIService(username)
tags = await service.suggest_tags(
content=data["content"],
existing_tags=existing_tags,
)
return {"success": True, "tags": tags}
except LLMNotConfiguredError:
# MUST precede the ValueError arm: this is a ValueError subclass, so
# ordering is what separates "you have not configured a model" from
# "your request body was invalid" here. See
# ``_llm_not_configured_response`` for why the answer is a 400 with
# ``error_type: model_not_configured``.
return _llm_not_configured_response("suggest-tags")
except ValueError:
return JSONResponse(
{"success": False, "error": "Invalid tag request"},
status_code=400,
)
except Exception as e:
return handle_api_error("suggesting tags", e)
@router.post("/api/notes/{note_id}/key-concepts")
@_notes_ai_limit
async def extract_key_concepts(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Extract key concepts, entities, and themes from the note."""
if isinstance(body, JSONResponse):
return body
try:
# 404 on unknown note id — see get_similar_notes for the rationale.
if not await run_db_sync(NoteService(username).note_exists, note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
service = NoteAIService(username)
concepts = await service.extract_key_concepts(note_id)
return {"success": True, "concepts": concepts}
except LLMNotConfiguredError:
# Same contract as suggest-tags: an unconfigured LLM is a
# client-state problem, not a 500. See
# ``_llm_not_configured_response``.
return _llm_not_configured_response("key-concepts")
except Exception as e:
return handle_api_error("extracting key concepts", e)
# ============================================================================
# API Routes - Smart Note Linking
# ============================================================================
@router.get("/api/notes/{note_id}/backlinks")
@_notes_search_limit
def get_backlinks(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Get notes that link to this note (backlinks)."""
try:
service = NoteService(username)
# 404 an unknown id like the other note routes, so an empty list
# for a real note is distinguishable from "no such note".
if not service.note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
backlinks = service.get_backlinks(note_id)
return {
"success": True,
"backlinks": backlinks,
"total": len(backlinks),
}
except Exception as e:
return handle_api_error("getting backlinks", e)
@router.get("/api/notes/{note_id}/outgoing-links")
@_notes_search_limit
def get_outgoing_links(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Get notes that this note links to."""
try:
service = NoteService(username)
# 404 an unknown id like the other note routes.
if not service.note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
links = service.get_outgoing_links(note_id)
return {
"success": True,
"links": links,
"total": len(links),
}
except Exception as e:
return handle_api_error("getting outgoing links", e)
@router.get("/api/notes/{note_id}/suggested-links")
@_notes_search_limit
def get_suggested_links(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Get AI-suggested notes to link to based on semantic similarity."""
try:
try:
limit = _clamp_limit(request, 5)
except (ValueError, TypeError):
return JSONResponse(
{"success": False, "error": "Invalid limit"}, status_code=400
)
# 404 a missing/unknown note like every sibling AI-link route
# (suggest_links returns [] for a missing note, which is otherwise
# indistinguishable from "a real note with no suggestions").
if not NoteService(username).note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
service = NoteAIService(username)
suggestions = service.suggest_links(note_id, limit=limit)
return {"success": True, "suggestions": suggestions}
except Exception as e:
return handle_api_error("getting suggested links", e)
@router.post("/api/notes/{note_id}/accept-link")
@_notes_write_limit
def accept_suggested_link(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Accept an AI-suggested link: insert [[Target Title]] into the note
content and flag the resulting NoteLink as auto_suggested=True.
Body:
target_note_id: The ID of the note to link to.
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
target_note_id = data.get("target_note_id")
if not target_note_id:
return JSONResponse(
{"success": False, "error": "target_note_id required"},
status_code=400,
)
service = NoteService(username)
result = service.accept_suggested_link(note_id, target_note_id)
if not result:
return JSONResponse(
{"success": False, "error": "Link could not be accepted"},
status_code=404,
)
return {"success": True, "note": result}
except ValueError:
return JSONResponse(
{
"success": False,
"error": "Suggested link cannot be accepted",
},
status_code=400,
)
except Exception as e:
return handle_api_error("accepting suggested link", e)
@router.get("/api/notes/{note_id}/unlinked-mentions")
@_notes_search_limit
def get_unlinked_mentions(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Notes whose text mentions this note's title but don't yet link to it.
Lexical (no embeddings). The client links one via the existing
/accept-link route on the *mentioning* note (target = this note).
"""
try:
service = NoteService(username)
# 404 an unknown id like the other note routes.
if not service.note_exists(note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
mentions = service.get_unlinked_mentions(note_id)
return {"success": True, "mentions": mentions}
except Exception as e:
return handle_api_error("getting unlinked mentions", e)
# Passage text is a paragraph-ish selection; cap it so a huge selection
# can't be sent as the embedding query.
MAX_PASSAGE_LEN = 2000
@router.post("/api/notes/{note_id}/similar-passages")
@_notes_search_limit
def similar_passages(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Find note passages (chunks) semantically similar to a given snippet.
Body: ``{"text": "<selected paragraph>"}``. Chunks from this note are
excluded so the result is "related passages elsewhere".
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
text = data.get("text")
if not text or not isinstance(text, str) or not text.strip():
return JSONResponse(
{"success": False, "error": "text required"}, status_code=400
)
text = text.strip()[:MAX_PASSAGE_LEN]
if not NoteService(username).note_exists(note_id):
logger.warning(
"notes_api validation reject: similar-passages note_id={} "
"not found (user={!r})",
_log_value_preview(note_id),
username,
)
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
service = NoteAIService(username)
passages = service.find_similar_passages(text, exclude_note_id=note_id)
return {"success": True, "passages": passages}
except Exception as e:
return handle_api_error("finding similar passages", e)
# ============================================================================
# API Routes - Ask your notes (research pinned to the Notes collection)
# (ask_context is registered above, before GET /api/notes/{note_id})
# ============================================================================
# ============================================================================
# API Routes - Verify Note with Research (fact-check)
# ============================================================================
@router.post("/api/notes/{note_id}/fact-check")
@_notes_factcheck_limit
async def fact_check_note(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Extract checkable factual claims from a note and synthesize a research
query for verifying them.
The client then starts a research run (reusing /api/start_research + the
research-link flow, exactly like "Research This Note") and, once it
completes, POSTs the claims to the /grade endpoint below.
"""
if isinstance(body, JSONResponse):
return body
try:
# Guard the note id like every other note route: without this an
# unknown/typo'd id fell through to the claim-less 422 below, conflating
# "this note has nothing to verify" with "there is no such note".
if not await run_db_sync(NoteService(username).note_exists, note_id):
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
ai = NoteAIService(username)
claims = await ai.extract_claims(note_id)
if not claims:
# The note exists but has no checkable factual claims.
return JSONResponse(
{
"success": False,
"error": "No checkable factual claims found in this note.",
},
status_code=422,
)
query = ai.synthesize_factcheck_query(claims)
return {"success": True, "claims": claims, "query": query}
except LLMNotConfiguredError:
# Same contract as suggest-tags: an unconfigured LLM is a
# client-state problem, not a 500. See
# ``_llm_not_configured_response``.
return _llm_not_configured_response("fact-check")
except Exception as e:
return handle_api_error("starting note fact-check", e)
async def _grade_note_claims(username, note_id, research_id, claims):
"""Grade ``claims`` against a COMPLETED research run's report and persist
the verdicts under ``research_meta['fact_check']``.
Returns a ``(payload, status_code)`` tuple. Extracted from the route so it
can be unit-tested without a client. DB steps run on worker threads via
``run_db_sync`` (thread-local sessions must stay off the event loop —
#6043), and the LLM grade awaits on the loop so the request thread is
freed for the length of the model's response (#5854).
The per-user DB password stays resolvable on those worker threads
because ``get_user_db_session`` resolves it from the PROCESS-GLOBAL
``session_password_store`` (``get_any_session_password(username)``),
which is neither thread- nor context-bound; the thread-local context
is only its third fallback, after an explicit ``session_id`` lookup.
Nothing has to be propagated to the pool here — unlike the
change-summary executor worker, which is off the request path entirely
and has the password threaded in explicitly as ``dbpw``.
"""
from ...constants import ResearchStatus
from ...database.models import NoteResearch, ResearchHistory
from ...database.session_context import get_user_db_session
from ...storage import get_report_storage
from ..services.report_assembly_service import (
get_research_source_links_batch,
)
def _load_research():
# Load the research (per-user DB session scopes it to this user) and
# require it to have completed before grading.
with get_user_db_session(username) as db:
research = (
db.query(ResearchHistory).filter_by(id=research_id).first()
)
if not research:
return None
# Require the research to actually be linked to THIS note — otherwise a
# client could grade an arbitrary completed research against an
# arbitrary note and stamp a foreign note_id into its meta.
linked = (
db.query(NoteResearch)
.filter_by(document_id=note_id, research_id=research_id)
.first()
)
if not linked:
return False
return research.status, dict(research.research_meta or {})
loaded = await run_db_sync(_load_research)
if loaded is None:
return {"success": False, "error": "Research not found"}, 404
if loaded is False:
return {
"success": False,
"error": "Research is not linked to this note",
}, 404
status, meta = loaded
if status != ResearchStatus.COMPLETED:
return {
"success": False,
"error": "Research is not complete yet.",
"status": status,
}, 409
settings_snapshot = meta.get("settings_snapshot")
def _fetch_report_and_sources():
# Fetch the report markdown + sources.
with get_user_db_session(username) as db:
storage = get_report_storage(
session=db, settings_snapshot=settings_snapshot
)
report = storage.get_report(research_id, username)
# Sources live in the research_resources table, not research_meta.
# The post-refactor save path never writes the legacy
# `all_links_of_system` metadata key (see the identical fix in
# research_routes.get_report), so reading it here returned [] for
# every research: the grader prompt always showed "(no sources)"
# and every verdict's sources array was empty, leaving the
# citation-validation/anti-rubber-stamp checks unreachable. Read
# the structured table instead — the same source of truth the
# results page uses. Fetch only the MAX_GRADE_SOURCES window the
# grader will actually show; anything past it was discarded.
sources = get_research_source_links_batch(
[research_id], db, limit=_MAX_GRADE_SOURCES
).get(research_id, [])
return report, sources
report, sources = await run_db_sync(_fetch_report_and_sources)
# get_report returns None for BOTH a missing report and a swallowed read
# error. Grading against an empty report would label every claim
# "unverified" and persist that as a successful fact-check — a false result.
# Refuse to grade instead.
if not report or not str(report).strip():
return {
"success": False,
"error": (
"The research report is unavailable, so its claims cannot be "
"graded. Try re-running the research."
),
}, 502
ai = NoteAIService(username)
verdicts = await ai.grade_all_claims(claims, report, sources)
def _persist_verdicts():
# Persist verdicts under research_meta['fact_check']. Reassign the whole
# dict so SQLAlchemy marks the plain-JSON column dirty (this codebase
# deliberately avoids MutableDict — see research_sources_service.py).
with get_user_db_session(username) as db:
research = (
db.query(ResearchHistory).filter_by(id=research_id).first()
)
if research is None:
# The research row existed when we loaded it for grading (above)
# but has since vanished — e.g. a concurrent delete between the
# grade and this persist. The verdicts were computed but cannot be
# saved. Returning success here would tell the client a fact-check
# was persisted that never was (a silent partial failure); report
# the conflict explicitly instead.
return False
try:
new_meta = dict(research.research_meta or {})
new_meta["fact_check"] = {
"note_id": note_id,
"claims": claims,
"verdicts": verdicts,
}
research.research_meta = new_meta
db.commit()
except Exception:
# Don't leave the shared request session poisoned.
db.rollback()
raise
return True
if not await run_db_sync(_persist_verdicts):
return {
"success": False,
"error": (
"The research run disappeared before its fact-check "
"verdicts could be saved. Please try again."
),
}, 409
return {"success": True, "verdicts": verdicts}, 200
@router.post("/api/notes/{note_id}/fact-check/{research_id}/grade")
@_notes_factcheck_limit
async def grade_note_fact_check(
request: Request,
note_id: str,
research_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Grade a note's claims against a COMPLETED research run's report.
Body: ``{"claims": ["...", ...]}`` — the claims returned by /fact-check.
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
raw_claims = data.get("claims")
if not isinstance(raw_claims, list):
return JSONResponse(
{"success": False, "error": "claims required"}, status_code=400
)
# Cap both the count AND each claim's length — the rest of this file
# length-bounds free text (MAX_SEARCH_LEN / _clamp_text_query) but the
# grade endpoint took client claims with no per-string bound.
claims = [
c.strip()[:MAX_CLAIM_LEN]
for c in raw_claims
if isinstance(c, str) and c.strip()
][: NoteAIService.MAX_CLAIMS_PER_NOTE]
if not claims:
return JSONResponse(
{"success": False, "error": "claims required"}, status_code=400
)
payload, status_code = await _grade_note_claims(
username, note_id, research_id, claims
)
return JSONResponse(payload, status_code=status_code)
except LLMNotConfiguredError:
# Same contract as suggest-tags: an unconfigured LLM is a
# client-state problem, not a 500. See
# ``_llm_not_configured_response``.
return _llm_not_configured_response("fact-check grade")
except Exception as e:
return handle_api_error("grading note fact-check", e)
@router.post("/api/notes/resolve-link")
@_notes_search_limit
def resolve_link(
request: Request,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""
Resolve a [[link]] text to a note.
Body:
link_text: The text inside [[brackets]]
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
if not data or not data.get("link_text"):
return JSONResponse(
{"success": False, "error": "link_text is required"},
status_code=400,
)
link_text = data["link_text"]
# ``_NotesBody`` is a plain parsed-JSON dict with no per-field
# coercion, so ``link_text`` can be any JSON type. Select the fixed
# 400 message by TYPE rather than by matching the exception text:
# ``_clamp_text_query`` raises for two different reasons and only
# one of them is a length problem, so reporting "exceeds maximum
# length" for ``{"link_text": 123}`` would be false.
if not isinstance(link_text, str):
return JSONResponse(
{"success": False, "error": "link_text must be a string"},
status_code=400,
)
try:
link_text = _clamp_text_query(
link_text, "link_text", max_len=MAX_LINK_TEXT_LEN
)
except ValueError:
return JSONResponse(
{
"success": False,
"error": (
f"link_text exceeds maximum length "
f"({MAX_LINK_TEXT_LEN} chars)"
),
},
status_code=400,
)
service = NoteService(username)
result = service.resolve_link(link_text)
if result:
return {"success": True, "note": result}
return JSONResponse(
{"success": False, "error": "Note not found"}, status_code=404
)
except Exception as e:
return handle_api_error("resolving link", e)
# ============================================================================
# API Routes - Note Synthesis
# ============================================================================
@router.post("/api/notes/synthesize/preview")
@_notes_synthesize_limit
async def preview_synthesis(
request: Request,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""
Preview what a synthesis would produce.
Body:
note_ids: List of note IDs (2-5)
synthesis_type: 'merge', 'summarize', or 'compare'
"""
if isinstance(body, JSONResponse):
return body
try:
data = body
if not data or not data.get("note_ids"):
return JSONResponse(
{"success": False, "error": "note_ids is required"},
status_code=400,
)
note_ids = data["note_ids"]
if not isinstance(note_ids, list) or not all(
isinstance(n, str) for n in note_ids
):
# Element type matters: synthesize_notes does dict.fromkeys(note_ids),
# which raises TypeError (→ 500) on unhashable items like dicts.
return JSONResponse(
{
"success": False,
"error": "note_ids must be a list of strings",
},
status_code=400,
)
synthesis_type = data.get("synthesis_type", "merge")
# synthesize_notes checks `synthesis_type not in {set}` (a hash), which
# raises TypeError (→ opaque 500) on an unhashable non-string like a
# list/dict. Reject to a clean 400 here, like note_ids above.
if not isinstance(synthesis_type, str):
return JSONResponse(
{
"success": False,
"error": "synthesis_type must be a string",
},
status_code=400,
)
# synthesize_notes returns the result without saving — callers (this
# preview route, and the create-note flow downstream) decide whether
# to persist it. Same call site, same payload.
service = NoteAIService(username)
preview = await service.synthesize_notes(note_ids, synthesis_type)
if "error" in preview:
return JSONResponse(
{"success": False, "error": preview["error"]},
status_code=400,
)
return {"success": True, "result": preview}
except LLMNotConfiguredError:
# Same contract as suggest-tags: an unconfigured LLM is a
# client-state problem, not a 500. See
# ``_llm_not_configured_response``.
return _llm_not_configured_response("synthesize preview")
except Exception as e:
return handle_api_error("previewing synthesis", e)
@router.post("/api/notes/synthesize")
@_notes_synthesize_limit
async def synthesize_notes(
request: Request,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""
Synthesize multiple notes into one.
Body:
note_ids: List of note IDs (2-5)
synthesis_type: 'merge', 'summarize', or 'compare'
create_note: Whether to create the note (default true)
"""
from ...database.models import NoteSynthesis, NoteSynthesisSource
if isinstance(body, JSONResponse):
return body
try:
data = body
if not data or not data.get("note_ids"):
return JSONResponse(
{"success": False, "error": "note_ids is required"},
status_code=400,
)
note_ids = data["note_ids"]
if not isinstance(note_ids, list) or not all(
isinstance(n, str) for n in note_ids
):
# Element type matters: synthesize_notes does dict.fromkeys(note_ids),
# which raises TypeError (→ 500) on unhashable items like dicts.
return JSONResponse(
{
"success": False,
"error": "note_ids must be a list of strings",
},
status_code=400,
)
synthesis_type = data.get("synthesis_type", "merge")
# synthesize_notes checks `synthesis_type not in {set}` (a hash), which
# raises TypeError (→ opaque 500) on an unhashable non-string like a
# list/dict. Reject to a clean 400 here, like note_ids above.
if not isinstance(synthesis_type, str):
return JSONResponse(
{
"success": False,
"error": "synthesis_type must be a string",
},
status_code=400,
)
# Omitted: defaults to True (persist synthesis as a new note).
create_note = data.get("create_note", True)
if not isinstance(create_note, bool):
logger.warning(
"notes_api validation reject: create_note={} (type={}) "
"(user={!r})",
_log_value_preview(create_note),
type(create_note).__name__,
username,
)
return JSONResponse(
{
"success": False,
"error": "create_note must be a boolean",
},
status_code=400,
)
ai_service = NoteAIService(username)
result = await ai_service.synthesize_notes(note_ids, synthesis_type)
if "error" in result:
return JSONResponse(
{"success": False, "error": result["error"]},
status_code=400,
)
# Create the note if requested
if create_note:
note_service = NoteService(username)
def _create_note_and_record_synthesis():
# Runs on a worker thread via run_db_sync: create_note and
# the synthesis-record persist both open thread-local DB
# sessions, which must stay off the event loop (#6043).
new_note_id = note_service.create_note(
title=result["suggested_title"],
content=result["content"],
tags=["synthesized", synthesis_type],
)
# Record the synthesis. Use the FILTERED source set the AI
# service actually fed to the LLM (result["source_notes"])
# rather than the raw client input — NoteAIService.synthesize_notes
# silently drops any non-note Document IDs from the prompt, so
# persisting raw note_ids would (a) record IDs the LLM never
# saw as "sources" and (b) FK-violate on any bogus ID after
# create_note has already committed.
from ...database.session_context import get_user_db_session
filtered_source_ids = [
src["id"]
for src in result.get("source_notes", [])
if "id" in src
]
db_session = None
try:
with get_user_db_session(username) as db_session:
synthesis_record = NoteSynthesis(
result_document_id=new_note_id,
synthesis_type=synthesis_type,
)
for doc_id in filtered_source_ids:
synthesis_record.sources.append(
NoteSynthesisSource(source_document_id=doc_id)
)
db_session.add(synthesis_record)
db_session.commit()
except Exception:
# create_note() already committed the new Document in its own
# session, so a failure here would leave an orphaned
# "synthesized" note with no provenance record. Roll back the
# poisoned shared session and delete the just-created note
# before surfacing the error.
logger.exception(
"Failed to persist synthesis record for note {}; "
"deleting the orphaned note",
new_note_id,
)
NoteService._rollback_quietly(db_session)
try:
note_service.delete_note(new_note_id)
except Exception:
logger.exception(
"Failed to delete orphaned synthesized note {}",
new_note_id,
)
raise
return new_note_id
result["note_id"] = await run_db_sync(
_create_note_and_record_synthesis
)
status_code = 201 if create_note else 200
return JSONResponse(
{"success": True, "result": result}, status_code=status_code
)
except LLMNotConfiguredError:
# Same contract as suggest-tags: an unconfigured LLM is a
# client-state problem, not a 500. See
# ``_llm_not_configured_response``.
return _llm_not_configured_response("synthesize")
except Exception as e:
return handle_api_error("synthesizing notes", e)
# ============================================================================
# API Routes - Version History
# ============================================================================
@router.get("/api/notes/{note_id}/versions")
def get_note_versions(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""
Get version history for a note.
Query params:
limit: Maximum number of versions to return (default 20, max 200)
offset: Number of versions to skip (default 0). Combined with
limit, this makes older versions reachable when total > limit.
Pre-fix the route had no offset support, so versions 1
through (total - limit) were unreachable through the UI.
"""
from ...database.models import Document, NoteVersion
from ...database.session_context import get_user_db_session
note_service = NoteService(username)
try:
try:
limit = _clamp_limit(request, 20)
except (ValueError, TypeError):
return JSONResponse(
{"success": False, "error": "Invalid limit"}, status_code=400
)
try:
offset = max(0, int(request.query_params.get("offset", 0)))
except (ValueError, TypeError):
return JSONResponse(
{"success": False, "error": "Invalid offset"}, status_code=400
)
with get_user_db_session(username) as db_session:
# Defense-in-depth: confirm the document is a note before
# serving anything from its version history. Mirrors the
# guard on the sibling version routes (get_note_version,
# get_semantic_diff, restore_note_version). load_only keeps
# the guard from hydrating text_content (up to 50 MB) just
# to check the source type.
doc = (
db_session.query(Document)
.options(load_only(Document.id, Document.source_type_id))
.filter_by(id=note_id)
.first()
)
if not doc or not note_service._is_note(db_session, doc):
return JSONResponse(
{"success": False, "error": "Note not found"},
status_code=404,
)
total = (
db_session.query(NoteVersion)
.filter_by(document_id=note_id)
.count()
)
# Cap offset at total: an unbounded OFFSET (e.g.
# ?offset=1_000_000_000) forces SQLite to row-walk the
# whole table in a backward index scan even though the
# result is empty. Clamping is cheap and harmless — a real
# caller with offset > total wants the empty page anyway.
if offset > total:
offset = total
# Column projection: each NoteVersion row carries a full
# content snapshot (up to the 50 MB cap); loading whole
# entities transferred `limit` note bodies per call to render
# a metadata-only list.
versions = (
db_session.query(
NoteVersion.id,
NoteVersion.title,
NoteVersion.change_type,
NoteVersion.change_summary,
NoteVersion.created_at,
)
.filter_by(document_id=note_id)
.order_by(
NoteVersion.created_at.desc(),
NoteVersion.id.desc(), # id tiebreaker for stable paging
)
.offset(offset)
.limit(limit)
.all()
)
return {
"success": True,
"total": total,
"limit": limit,
"offset": offset,
"versions": [
{
"id": v.id,
# Global version index — newest is `total`,
# oldest is 1. Stable across pages.
"version_number": total - offset - i,
"title": v.title,
"change_type": v.change_type,
"change_summary": v.change_summary,
"created_at": v.created_at.isoformat()
if v.created_at
else None,
}
for i, v in enumerate(versions)
],
}
except Exception as e:
return handle_api_error("getting note versions", e)
@router.get("/api/notes/{note_id}/versions/semantic-diff")
@_notes_ai_limit
async def get_semantic_diff(
request: Request,
note_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""
Get AI-powered semantic diff between two versions.
Query params:
version1: First version UUID
version2: Second version UUID, or the literal "current" to diff
against the note's current content.
"""
from ...database.models import Document, NoteVersion
from ...database.session_context import get_user_db_session
note_service = NoteService(username)
try:
version1 = request.query_params.get("version1")
version2 = request.query_params.get("version2")
if not version1 or not version2:
return JSONResponse(
{
"success": False,
"error": "version1 and version2 are required",
},
status_code=400,
)
def _load_diff_versions():
# Runs on a worker thread via run_db_sync: the version fetch
# opens a thread-local DB session, which must stay off the
# event loop (#6043). Returns ("note"|"version"|None, c1, c2):
# the first element names the 404 flavor, the strings are the
# two contents to diff (None when erroring).
with get_user_db_session(username) as db_session:
# Defense-in-depth: confirm the document is a note before
# serving anything from its version history. load_only defers
# text_content; the "current" branch below lazy-loads it only
# when actually diffing against the live note.
doc = (
db_session.query(Document)
.options(load_only(Document.id, Document.source_type_id))
.filter_by(id=note_id)
.first()
)
if not doc or not note_service._is_note(db_session, doc):
return "note", None, None
v1 = (
db_session.query(NoteVersion)
.filter_by(document_id=note_id, id=version1)
.first()
)
if not v1:
return "version", None, None
if version2 == "current":
return None, v1.content, doc.text_content or ""
v2 = (
db_session.query(NoteVersion)
.filter_by(document_id=note_id, id=version2)
.first()
)
if not v2:
return "version", None, None
return None, v1.content, v2.content
missing, v1_content, v2_content = await run_db_sync(_load_diff_versions)
if missing == "note":
return JSONResponse(
{"success": False, "error": "Note not found"},
status_code=404,
)
if missing == "version":
return JSONResponse(
{"success": False, "error": "Version not found"},
status_code=404,
)
ai_service = NoteAIService(username)
diff = await ai_service.semantic_diff(v1_content, v2_content)
return {"success": True, "diff": diff}
except LLMNotConfiguredError:
# Same contract as suggest-tags: an unconfigured LLM is a
# client-state problem, not a 500. See
# ``_llm_not_configured_response``.
return _llm_not_configured_response("semantic-diff")
except Exception as e:
return handle_api_error("getting semantic diff", e)
@router.get("/api/notes/{note_id}/versions/{version_id}")
def get_note_version(
request: Request,
note_id: str,
version_id: str,
username: Annotated[str, Depends(require_auth)],
):
"""Get a specific version of a note."""
from ...database.models import Document, NoteVersion
from ...database.session_context import get_user_db_session
note_service = NoteService(username)
try:
with get_user_db_session(username) as db_session:
# Defense-in-depth: confirm the parent document is a note.
# load_only keeps the guard from hydrating text_content.
doc = (
db_session.query(Document)
.options(load_only(Document.id, Document.source_type_id))
.filter_by(id=note_id)
.first()
)
if not doc or not note_service._is_note(db_session, doc):
return JSONResponse(
{"success": False, "error": "Note not found"},
status_code=404,
)
version = (
db_session.query(NoteVersion)
.filter_by(document_id=note_id, id=version_id)
.first()
)
if not version:
return JSONResponse(
{"success": False, "error": "Version not found"},
status_code=404,
)
return {
"success": True,
"version": {
"id": version.id,
"title": version.title,
"content": version.content,
"tags": version.tags,
"change_type": version.change_type,
"change_summary": version.change_summary,
"created_at": version.created_at.isoformat()
if version.created_at
else None,
},
}
except Exception as e:
return handle_api_error("getting note version", e)
@router.post("/api/notes/{note_id}/versions/{version_id}/restore")
@_notes_write_limit
def restore_note_version(
request: Request,
note_id: str,
version_id: str,
username: Annotated[str, Depends(require_auth)],
body: _NotesBody,
):
"""Restore a note to a previous version.
Delegates to ``NoteService.restore_with_bookends`` which wraps
PRE_RESTORE + content update + RESTORE in a single transaction.
Earlier code orchestrated this from three separate sessions — process
death between writes could leave a restored note with no audit-trail
row. Keep the orchestration in the service; this handler just routes.
"""
if isinstance(body, JSONResponse):
return body
note_service = NoteService(username)
try:
success, error = note_service.restore_with_bookends(note_id, version_id)
if not success:
if error == "note_not_found":
return JSONResponse(
{"success": False, "error": "Note not found"},
status_code=404,
)
if error == "version_not_found":
return JSONResponse(
{"success": False, "error": "Version not found"},
status_code=404,
)
return JSONResponse(
{"success": False, "error": "Failed to restore version"},
status_code=500,
)
_trigger_note_auto_index(
note_id, note_service, username, request.session.get("session_id")
)
return {
"success": True,
"message": f"Restored to version {version_id[:8]}",
}
except Exception as e:
return handle_api_error("restoring note version", e)