Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 56 additions & 10 deletions src/basic_memory/api/v2/routers/scoped_search_router.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,12 @@
rather than per-project pages merged afterwards.
"""

import time
from collections.abc import Sequence

import logfire
from fastapi import APIRouter, Query, Response
from sqlalchemy.ext.asyncio import AsyncSession

from basic_memory import db
from basic_memory.api.v2.utils import (
Expand All @@ -17,6 +21,7 @@
to_search_results,
)
from basic_memory.deps import AppConfigDep, SessionMakerDep
from basic_memory.models import Entity
from basic_memory.repository.search_repository import create_search_reader
from basic_memory.repository.search_scope import ProjectScope
from basic_memory.repository.semantic_index_freshness import semantic_index_current_as_of
Expand Down Expand Up @@ -75,6 +80,7 @@ async def search_scope(
retrieval_mode=query.retrieval_mode.value,
has_temporal_filter=temporal_requested,
):
search_started = time.perf_counter()
with search_error_boundary():
# Why no exact count: a COUNT(*) over every match cost as much as the search
# on large scopes, and semantic modes would need a second retrieval to count.
Expand All @@ -86,18 +92,44 @@ async def search_scope(
results = results[:page_size]
total = offset + len(results) if results else 0

search_ms = _elapsed_ms(search_started)

# Why one session for every read after the search: each session checks out a
# pooled connection and runs its own transaction, and on a remote database
# every one of those is a round trip. Outcome: project identities, valid
# time, entity hydration and the freshness check share one connection, one
# after another, never concurrently (a small pool could make a concurrent
# read wait behind another request). The search keeps its own session
# because its reader is shared with the per-project route. A page with no
# hits still answers the freshness check, on this same session.
temporal_by_source = {}
project_external_ids: dict[int, str] = {}
if results:
async with db.scoped_session(session_maker) as session:
async with db.scoped_session(session_maker) as session:
hydrate_started = time.perf_counter()
if results:
project_external_ids = await service.project_external_ids(session, results)
if temporal_requested:
temporal_by_source = await load_temporal_metadata(service, session, results)
search_results = await to_search_results(
service,
results,
temporal_by_source=temporal_by_source,
project_external_ids=project_external_ids,
search_results = await to_search_results(
_SessionEntityLookup(service, session),
results,
temporal_by_source=temporal_by_source,
project_external_ids=project_external_ids,
)
hydrate_ms = _elapsed_ms(hydrate_started)

freshness_started = time.perf_counter()
current_as_of = await semantic_index_current_as_of(
session_maker, app_config, scope, session
)
freshness_ms = _elapsed_ms(freshness_started)

# Each step's server time, so a caller (or a host proxying this route) can see
# which step is slow without access to tracing. Durations only, no data.
response.headers["Server-Timing"] = (
f"search;dur={search_ms:.1f}, "
f"hydrate;dur={hydrate_ms:.1f}, "
f"freshness;dur={freshness_ms:.1f}"
)
return SearchResponse(
results=search_results,
Expand All @@ -109,7 +141,21 @@ async def search_scope(
# None, not False, when nothing was asked: an ordinary search payload stays
# exactly what it was before valid time existed.
temporal_applied=True if temporal_requested else None,
semantic_index_current_as_of=await semantic_index_current_as_of(
session_maker, app_config, scope
),
semantic_index_current_as_of=current_as_of,
)


def _elapsed_ms(started: float) -> float:
"""Milliseconds since a ``time.perf_counter()`` reading."""
return (time.perf_counter() - started) * 1000


class _SessionEntityLookup:
"""Hydrate a page's entities on the route's session instead of a new one."""

def __init__(self, service: ScopedSearchService, session: AsyncSession) -> None:
self._service = service
self._session = session

async def get_entities_by_id(self, ids: list[int]) -> Sequence[Entity]:
return await self._service.get_entities_by_id(ids, session=self._session)
6 changes: 5 additions & 1 deletion src/basic_memory/repository/semantic_index_freshness.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,17 +56,21 @@ async def semantic_index_current_as_of(
session_maker: async_sessionmaker[AsyncSession],
app_config: BasicMemoryConfig,
scope: ProjectScope,
session: AsyncSession | None = None,
) -> datetime | None:
"""Return the latest note change semantic search reflects for ``scope``, or None.

None means every note's embeddings are current, or there is no semantic search to
be current: a host that cannot load sqlite-vec runs keyword-only (#711), and an
empty scope searched nothing.

A caller that already holds a session passes it, and both reads run on it instead
of on a session of their own.
"""
if scope.is_empty or not semantic_runtime_available(app_config):
return None

async with db.scoped_session(session_maker) as session:
async with db.scoped_session(session_maker, session) as session:
oldest_behind = (await session.execute(oldest_behind_statement(scope))).scalar_one()
# Trigger: no note is behind. Why: the common case, answered from the partial
# index without touching current notes. Outcome: no freshness to report.
Expand Down
12 changes: 10 additions & 2 deletions src/basic_memory/services/scoped_search_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -70,17 +70,25 @@ async def search(

# --- Hydration, bounded by the scope ---

async def get_entities_by_id(self, ids: Sequence[int]) -> Sequence[Entity]:
async def get_entities_by_id(
self,
ids: Sequence[int],
*,
session: AsyncSession | None = None,
) -> Sequence[Entity]:
"""The entities a page of hits refers to, read only from projects in scope.

Only the fields result shaping reads are loaded. Ids reached through a scoped
search already belong to the scope; the predicate keeps that true by
construction rather than by trust.

A caller that already holds a session for the rest of a page's reads passes it,
and the read joins that session instead of checking out its own connection.
"""
if not ids or self.scope.is_empty:
return []
entities: list[Entity] = []
async with db.scoped_session(self.session_maker) as session:
async with db.scoped_session(self.session_maker, session) as session:
for chunk in _chunks(list(ids)):
result = await session.scalars(
select(Entity)
Expand Down
84 changes: 84 additions & 0 deletions tests/api/v2/test_scoped_search_router.py
Original file line number Diff line number Diff line change
Expand Up @@ -235,6 +235,23 @@ async def _add_temporal_assertions(corpus: Corpus, project_ids: list[int]) -> No
await session.commit()


class _Checkouts(list[object]):
"""Pool checkouts seen on an engine: one per database session that ran a statement."""

def append_checkout(self, _dbapi_conn, _record, _proxy) -> None:
self.append(object())


def _count_checkouts(engine: AsyncEngine) -> _Checkouts:
"""Start counting connection checkouts; the caller removes the listener."""
checkouts = _Checkouts()
event.listen(engine.sync_engine, "checkout", checkouts.append_checkout)
return checkouts


SERVER_TIMING = re.compile(r"^search;dur=\d+\.\d, hydrate;dur=\d+\.\d, freshness;dur=\d+\.\d$")


# --- The reader over a scope ---


Expand Down Expand Up @@ -388,6 +405,30 @@ async def test_hydration_reads_only_projects_in_scope(corpus: Corpus) -> None:
assert await service.project_external_ids(session, []) == {}


@pytest.mark.asyncio
async def test_entity_hydration_joins_a_session_the_caller_holds(corpus: Corpus) -> None:
"""Passed a session, the read runs on it; without one, it opens its own as before."""
service = corpus.service(corpus.ids(1))
all_entity_ids = [entity.id for entity in corpus.entities]
checkouts = _count_checkouts(corpus.engine)

try:
on_its_own = await service.get_entities_by_id(all_entity_ids)
own_checkouts = len(checkouts)
async with db.scoped_session(corpus.session_maker) as session:
await session.execute(text("SELECT 1"))
held_checkouts = len(checkouts)
on_the_callers = await service.get_entities_by_id(all_entity_ids, session=session)
joined_checkouts = len(checkouts) - held_checkouts
finally:
event.remove(corpus.engine.sync_engine, "checkout", checkouts.append_checkout)

assert [entity.id for entity in on_its_own] == [corpus.entities[0].id]
assert [entity.id for entity in on_the_callers] == [corpus.entities[0].id]
assert own_checkouts == 1
assert joined_checkouts == 0


# --- The route ---


Expand Down Expand Up @@ -430,6 +471,49 @@ async def test_filters_narrow_the_scope_and_results_carry_project_identity(
assert response.headers["accept-query"] == "application/json"


@pytest.mark.asyncio
async def test_a_search_with_hits_uses_one_session_after_the_search(
corpus: Corpus, client: AsyncClient
) -> None:
"""The search has its own session; every read after it shares a second one."""
ids = corpus.ids(2)
# Notes behind their embeddings, so the freshness check runs both of its reads.
async with db.scoped_session(corpus.session_maker) as session:
await session.execute(text("UPDATE entity SET checksum = 'moved-on'"))
await _add_temporal_assertions(corpus, ids)
checkouts = _count_checkouts(corpus.engine)

try:
response = await client.request(
"QUERY",
"/v2/search/",
json={"project_ids": ids, "text": "nebula", "valid_at": "2026-09-14"},
)
finally:
event.remove(corpus.engine.sync_engine, "checkout", checkouts.append_checkout)

assert response.status_code == 200, response.text
payload = response.json()
assert payload["results"]
assert payload["results"][0]["temporal"]
assert payload["semantic_index_current_as_of"] is not None
assert len(checkouts) == 2


@pytest.mark.asyncio
@pytest.mark.parametrize("text_query, has_hits", [("nebula", True), ("absentword", False)])
async def test_the_response_reports_each_steps_time(
corpus: Corpus, client: AsyncClient, text_query: str, has_hits: bool
) -> None:
response = await client.request(
"QUERY", "/v2/search/", json={"project_ids": corpus.ids(2), "text": text_query}
)

assert response.status_code == 200, response.text
assert bool(response.json()["results"]) is has_hits
assert SERVER_TIMING.match(response.headers["server-timing"]), response.headers["server-timing"]


@pytest.mark.asyncio
async def test_scope_shapes_the_answer(corpus: Corpus, client: AsyncClient) -> None:
for ids, count in [(corpus.ids(3), 9), ([corpus.projects[1].id], 3), ([], 0)]:
Expand Down
37 changes: 37 additions & 0 deletions tests/repository/test_semantic_index_freshness.py
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,43 @@ async def test_one_stuck_note_does_not_date_the_index_back(
assert await _current_as_of(session_maker, app_config, test_project) == recent_time


@pytest.mark.asyncio
async def test_a_session_the_caller_holds_gives_the_same_answer(
entity_repository, search_service, session_maker, app_config, test_project
):
"""Passed a session, both reads run on it and the answer matches a call without one."""
newest_current_time = _local_time(10)
await _embedded_note(
entity_repository,
search_service,
session_maker,
test_project,
title="Current",
updated_at=newest_current_time,
)
held = await _embedded_note(
entity_repository,
search_service,
session_maker,
test_project,
title="Held",
updated_at=_local_time(5),
)
await _edit_without_embedding(session_maker, held, _local_time(1))
scope = ProjectScope.single(test_project.id)

on_its_own = await semantic_index_current_as_of(session_maker, app_config, scope)
async with db.scoped_session(session_maker) as session:
on_the_callers = await semantic_index_current_as_of(
session_maker, app_config, scope, session
)
# The caller still owns the session: it stays open for further reads.
assert (await session.execute(text("SELECT 1"))).scalar_one() == 1

assert on_its_own == newest_current_time
assert on_the_callers == newest_current_time


@pytest.mark.asyncio
async def test_a_note_never_embedded_is_behind(
entity_repository, search_service, session_maker, app_config, test_project
Expand Down
Loading