lorebase-keeper 0.2.3__tar.gz → 0.3.0__tar.gz

{lorebase_keeper-0.2.3 → lorebase_keeper-0.3.0}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.5
 Name: lorebase-keeper
-Version: 0.2.3
+Version: 0.3.0
 Summary: Lorebase Keeper: REST API service
 Requires-Python: >=3.12
 Requires-Dist: asyncpg>=0.29
 Requires-Dist: fastapi>=0.115
 Requires-Dist: httpx>=0.27
-Requires-Dist: lorebase-platform<0.3,>=0.2
-Requires-Dist: lorebase-store<0.3,>=0.2
+Requires-Dist: lorebase-core<0.4,>=0.3
+Requires-Dist: lorebase-platform<0.4,>=0.3
+Requires-Dist: lorebase-store<0.4,>=0.3
 Requires-Dist: opentelemetry-api>=1.25
+Requires-Dist: pgvector>=0.3
 Requires-Dist: pydantic>=2.7
 Requires-Dist: pyjwt[crypto]>=2.8
 Requires-Dist: python-multipart>=0.0.9

{lorebase_keeper-0.2.3 → lorebase_keeper-0.3.0}/pyproject.toml

@@ -1,16 +1,18 @@
 [project]
 name = "lorebase-keeper"
-version = "0.2.3"
+version = "0.3.0"
 description = "Lorebase Keeper: REST API service"
 requires-python = ">=3.12"
 dependencies = [
-  "lorebase-store>=0.2,<0.3",
-  "lorebase-platform>=0.2,<0.3",
+  "lorebase-core>=0.3,<0.4",
+  "lorebase-store>=0.3,<0.4",
+  "lorebase-platform>=0.3,<0.4",
   "fastapi>=0.115",
   "uvicorn>=0.30",
   "pydantic>=2.7",
   "opentelemetry-api>=1.25",
-  "asyncpg>=0.29",
+  "asyncpg>=0.29",  # readiness probe of the database (imported lazily)
+  "pgvector>=0.3",  # vector column types of semantic search
   "httpx>=0.27",
   "PyJWT[crypto]>=2.8",
   "python-multipart>=0.0.9",  # form parser of Starlette: file uploads of POST schema:infer

lorebase_keeper-0.3.0/src/lorebase_keeper/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{lorebase_keeper-0.2.3 → lorebase_keeper-0.3.0}/src/lorebase_keeper/agents/context.py

@@ -45,6 +45,7 @@ from lorebase_keeper.agents.pack import (
 from lorebase_keeper.agents.settings import ContextSettings
 from lorebase_keeper.reading.compiler import record_columns
 from lorebase_keeper.reading.history import REVISIONS
+from lorebase_keeper.reading.lenses import resolve_lens, trait_kinds
 from lorebase_keeper.reading.points import ReadPoint, not_found
 from lorebase_keeper.reading.problems import invalid
 from lorebase_keeper.reading.records import plan_query, require_kind, run_query
@@ -74,28 +75,77 @@ def timestamp(value: datetime | None) -> str | None:
 
 @dataclass(frozen=True, slots=True)
 class PackSettings:
+    """What a request asks for once its lens is applied (design 8.8): members of the request
+    win over the lens's, which win over the settings."""
+
     budget_tokens: int
     depth: int
+    include_schema: bool = True
+    include_recent_changes: bool = True
+    include_lineage: bool = True
+    relations: tuple[str, ...] = ()
+    """Relation ids of the lens, followed in both directions when the request names none."""
+    kinds: frozenset[str] | None = None
+    """Ids of the Kinds that neighbors and `search` and `query` seeds are limited to, from the
+    request's `traits` or else the lens; `None`: no limit."""
+    capped: bool = False
+    """A budget or depth of the lens was over the configured bounds and is served at them."""
 
 
 def effective(
-    request: ContextRequest, settings: ContextSettings, runtime: ReadRuntime
+    request: ContextRequest,
+    settings: ContextSettings,
+    runtime: ReadRuntime,
+    point: ReadPoint,
 ) -> PackSettings:
-    """Budget and depth of a request, within the configured bounds (422 otherwise)."""
-    budget = request.budget_tokens or settings.default_budget_tokens
-    if budget > settings.max_budget_tokens:
+    """Budget, depth, sections and Kinds of a request: its own members, else those of its
+    lens, else the settings. Values of the request over the configured bounds are 422; those
+    of a lens are served at the bounds (the pack says `capped`)."""
+    resolved = None if request.lens is None else resolve_lens(point, request.lens, "/body/lens")
+    lens = None if resolved is None else resolved.lens
+    capped = False
+    budget = request.budget_tokens
+    if budget is None:
+        budget = (lens.budget_tokens if lens else None) or settings.default_budget_tokens
+        if budget > settings.max_budget_tokens:
+            budget, capped = settings.max_budget_tokens, True
+    elif budget > settings.max_budget_tokens:
         raise invalid(
             "/body/budget_tokens", f"must not exceed {settings.max_budget_tokens}", "limit_exceeded"
         )
-    depth = settings.default_depth if request.depth is None else request.depth
     deepest = min(
         settings.max_depth,
         runtime.read.traverse.max_depth,
         runtime.store_settings.traverse.max_depth,
     )
-    if depth > deepest:
+    depth = request.depth
+    if depth is None:
+        depth = settings.default_depth if lens is None or lens.depth is None else lens.depth
+        if depth > deepest:
+            depth, capped = deepest, True
+    elif depth > deepest:
         raise invalid("/body/depth", f"must not exceed {deepest}", "limit_exceeded")
-    return PackSettings(budget, depth)
+    kinds: frozenset[str] | None = None
+    if request.traits is not None:
+        kinds = frozenset(k.id for k in trait_kinds(point, request.traits, "/body/traits"))
+    elif resolved is not None and resolved.kinds is not None:
+        kinds = frozenset(k.id for k in resolved.kinds)
+
+    def section(asked: bool | None, preset: bool | None) -> bool:
+        return asked if asked is not None else True if preset is None else preset
+
+    return PackSettings(
+        budget,
+        depth,
+        include_schema=section(request.include_schema, lens.include_schema if lens else None),
+        include_recent_changes=section(
+            request.include_recent_changes, lens.include_recent_changes if lens else None
+        ),
+        include_lineage=section(request.include_lineage, lens.include_lineage if lens else None),
+        relations=lens.relations if lens else (),
+        kinds=kinds,
+        capped=capped,
+    )
 
 
 # Seeds ----------------------------------------------------------------------------------------
@@ -107,8 +157,10 @@ async def seed_addresses(
     point: ReadPoint,
     request: ContextRequest,
     settings: ContextSettings,
+    kinds: frozenset[str] | None = None,
 ) -> list[tuple[Kind, str]]:
-    """`(Kind, key)` of the seeds, in request, query or ranking order, without repeats."""
+    """`(Kind, key)` of the seeds, in request, query or ranking order, without repeats.
+    `kinds` (ids) limits the Kinds of `query` and `search` seeds, never those of `refs`."""
     cap = settings.max_seeds
     found: list[tuple[str, str]] = []
     if request.refs is not None:
@@ -129,11 +181,23 @@ async def seed_addresses(
             session, runtime, point, plan, shape="context", cursor_pointer="/body/query/cursor"
         )
         found = [(item.kind, item.key) for item in page.items]
+        if kinds is not None:
+            allowed = {point.schema.kinds[k].api_name for k in kinds if k in point.schema.kinds}
+            found = [(kind, key) for kind, key in found if kind in allowed]
     else:
         assert request.search is not None
         limit = min(cap, runtime.search.results.max_limit)
         hits = await search(
-            session, runtime, point, SearchRequest(q=request.search, mode="lexical", limit=limit)
+            session,
+            runtime,
+            point,
+            SearchRequest(
+                q=request.search,
+                mode="lexical",
+                limit=limit,
+                traits=request.traits,
+                lens=request.lens,
+            ),
         )
         found = [(hit.kind, hit.key) for hit in hits.items]
     unique = list(dict.fromkeys(found))
@@ -203,8 +267,9 @@ async def surroundings(
     seeds: Sequence[RecordOut],
     request: ContextRequest,
     settings: ContextSettings,
-    depth: int,
+    bounds: PackSettings,
 ) -> Surroundings:
+    depth = bounds.depth
     if depth == 0 or not seeds:
         return Surroundings((), (), False)
     caps, walk = runtime.read.traverse, runtime.store_settings.traverse
@@ -216,7 +281,7 @@ async def surroundings(
             point.schema,
             [(require_kind(point, s.kind).id, s.key) for s in seeds],
             depth=depth,
-            follow=_follow(point, request.relations),
+            follow=_follow(point, request.relations, bounds),
             max_nodes=min(len(seeds) + settings.max_neighbors, caps.max_nodes, walk.max_nodes),
             max_links=max(min(settings.max_links, caps.max_edges, walk.max_links), 1),
             runtime=runtime.store,
@@ -264,14 +329,20 @@ async def surroundings(
     return Surroundings(tuple(neighbors), ordered_links, found.truncated)
 
 
-def _follow(point: ReadPoint, names: list[str] | None) -> dict[str, Direction]:
+def _follow(
+    point: ReadPoint, names: list[str] | None, bounds: PackSettings | None = None
+) -> dict[str, Direction]:
     """Relations to walk (id to direction): those named (forward or inverse api name; default:
-    all), in the directions named, between Kinds the caller may read."""
+    those of the lens, else all), in the directions named, between Kinds the caller may read.
+    With `bounds.kinds`, a direction is walked only when it reaches a Kind of that set, so
+    other Kinds are neither returned nor walked through."""
     schema = point.schema
     wanted: dict[str, set[LinkDirection]] = defaultdict(set)
     if names is None:
+        lens_relations = () if bounds is None else bounds.relations
         for relation in schema.relations.values():
-            wanted[relation.id] = set(LinkDirection)
+            if not lens_relations or relation.id in lens_relations:
+                wanted[relation.id] = set(LinkDirection)
     else:
         for index, name in enumerate(names):
             found = schema.relation_by_api_name(name)
@@ -284,6 +355,14 @@ def _follow(point: ReadPoint, names: list[str] | None) -> dict[str, Direction]:
         ends = (schema.kinds.get(relation.from_kind), schema.kinds.get(relation.to_kind))
         if any(kind is None or not point.scope.allows(kind.api_name) for kind in ends):
             continue  # Kinds the caller may not read are neither returned nor walked through
+        if bounds is not None and bounds.kinds is not None:
+            reached = {
+                LinkDirection.FORWARD: relation.to_kind,
+                LinkDirection.INVERSE: relation.from_kind,
+            }
+            directions = {d for d in directions if reached[d] in bounds.kinds}
+            if not directions:
+                continue
         if len(directions) == 2:
             follow[relation_id] = Direction.BOTH
         else:
@@ -444,14 +523,14 @@ async def build_pack(
     settings: ContextSettings,
 ) -> tuple[bytes, str]:
     """The rendered pack and its media type."""
-    bounds = effective(request, settings, runtime)
+    bounds = effective(request, settings, runtime, context.point)
     point = await with_rows(session, runtime, context.point, "Context packs")
-    addresses = await seed_addresses(session, runtime, point, request, settings)
+    addresses = await seed_addresses(session, runtime, point, request, settings, bounds.kinds)
     rows = await fetch_rows(session, point, addresses)
     seeds = [record_out(point.schema, row, masking=point.masking) for row in rows]
-    around = await surroundings(session, runtime, point, seeds, request, settings, bounds.depth)
+    around = await surroundings(session, runtime, point, seeds, request, settings, bounds)
     changes = None
-    if request.include_recent_changes:
+    if bounds.include_recent_changes:
         records = list(addresses)
         for neighbor in around.neighbors:
             kind = point.schema.kind_by_api_name(neighbor.kind)
@@ -465,9 +544,7 @@ async def build_pack(
             floor=context.floor,
             limit=settings.recent_changes_max,
         )
-    lineage = (
-        await lineage_items(session, runtime, point, rows) if request.include_lineage else None
-    )
+    lineage = await lineage_items(session, runtime, point, rows) if bounds.include_lineage else None
     draft = Draft(
         seeds=tuple(
             SeedItem(
@@ -481,7 +558,7 @@ async def build_pack(
         ),
         neighbors=around.neighbors,
         links=around.links,
-        schema=request.include_schema,
+        schema=bounds.include_schema,
         changes=changes,
         lineage=lineage,
     )
@@ -499,7 +576,7 @@ async def build_pack(
         draft,
         budget_tokens=bounds.budget_tokens,
         chars_per_token=settings.chars_per_token,
-        capped=around.capped,
+        capped=around.capped or bounds.capped,
     )
     if markdown:
         # References are resolved when the pack is sent, from the envelope (never by

{lorebase_keeper-0.2.3 → lorebase_keeper-0.3.0}/src/lorebase_keeper/agents/pack.py

@@ -56,11 +56,28 @@ class ContextRequest(BaseModel):
     depth: int | None = Field(default=None, ge=0, description="Neighborhood depth (0: none).")
     relations: list[str] | None = Field(
         default=None,
-        description="Relation api names to follow (forward or inverse); default: all.",
+        description="Relation api names to follow (forward or inverse); default: all, or the "
+        "Relations of `lens`.",
+    )
+    traits: list[str] | None = Field(
+        default=None,
+        description="Trait api names: with `search` or `query` seeds, only Records of the "
+        "Kinds implementing them (that the caller may read) become seeds, and only Records of "
+        "those Kinds are neighbors. Seeds named by `refs` are always kept.",
+    )
+    lens: str | None = Field(
+        default=None,
+        description="Lens api name (a read preset of the schema): its Relations, depth, "
+        "sections and budget are the defaults of this request, its Kinds and Traits limit "
+        "neighbors and `search` and `query` seeds like `traits`. Members given here win.",
+    )
+    include_schema: bool | None = Field(default=None, description="Default: the lens's, else true.")
+    include_recent_changes: bool | None = Field(
+        default=None, description="Default: the lens's, else true."
+    )
+    include_lineage: bool | None = Field(
+        default=None, description="Default: the lens's, else true."
     )
-    include_schema: bool = True
-    include_recent_changes: bool = True
-    include_lineage: bool = True
     since: str | None = Field(
         default=None,
         description="Revision id or tag: recent changes after it; default: the latest changes.",
@@ -167,7 +184,10 @@ class BudgetOut(_Out):
     trimmed: list[TrimOut]
     omitted: dict[str, int] = Field(description="Entries removed to fit, per section.")
     over_budget: bool = Field(description="True when even the seed Records exceed the budget.")
-    capped: bool = Field(description="True when graph caps cut the neighborhood.")
+    capped: bool = Field(
+        description="True when graph caps cut the neighborhood, or a depth or budget of the "
+        "lens was served at the configured cap."
+    )
 
 
 class ContextPackOut(_Out):

{lorebase_keeper-0.2.3 → lorebase_keeper-0.3.0}/src/lorebase_keeper/app.py

@@ -45,6 +45,7 @@ from lorebase_keeper.readiness import (
     ReadinessCheck,
     ReplicaCheck,
     SearchBackendCheck,
+    VectorSearchCheck,
     default_checks,
     packaged_heads,
     run_checks,
@@ -187,6 +188,8 @@ def create_app(
         search_check = SearchBackendCheck(database.sessions, definer=definer)
         if readiness_checks is None:
             checks.append(search_check)
+    if database is not None and readiness_checks is None:
+        checks.append(VectorSearchCheck(database.sessions, search_settings(settings).semantic))
     store = auth_store or (database.auth_store if database else None)
     if keeper.auth.mode != "none" and store is None:
         raise ConfigError(
@@ -219,7 +222,7 @@ def create_app(
     traces = _trace_recorder(keeper.trace, database, trace_sink, telemetry)
 
     @asynccontextmanager
-    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    async def lifespan(application: FastAPI) -> AsyncIterator[None]:
         if search_check is not None:
             found = (await run_checks([search_check], keeper.readiness.timeout_s))[
                 search_check.name
@@ -229,6 +232,9 @@ def create_app(
         try:
             yield
         finally:
+            read_runtime = getattr(application.state, "read_runtime", None)
+            if read_runtime is not None and read_runtime.misses is not None:
+                await read_runtime.misses.aclose()
             if reads is not None:
                 await reads.aclose()
             if traces is not None:

{lorebase_keeper-0.2.3 → lorebase_keeper-0.3.0}/src/lorebase_keeper/auth/permissions.py

@@ -15,7 +15,9 @@ Role semantics where the design table leaves room:
   `editor` uploads documents for extraction (`document.write`) and reads them
   (`document.read`); `reviewer` reads documents too, since extraction items quote them;
   documents are raw, unmasked input, so `viewer`, `explorer` and `agent-reader` do not read
-  them;
+  them; `maintainer` retires documents (`document.retire`: their values raise `stale`
+  candidates and they are never extracted again); only `admin` purges them
+  (`document.purge`: bytes, text and quotes deleted, irreversibly);
   `reviewer` reviews them and resolves Conflicts; merging needs `proposal.merge`
   (`maintainer`), into protected and unprotected branches alike;
 - `admin` holds every permission of the Domain (it is the Domain owner role); only it may
@@ -57,6 +59,8 @@ class Permission(StrEnum):
     SOURCE_SYNC = "source.sync"
     DOCUMENT_READ = "document.read"
     DOCUMENT_WRITE = "document.write"
+    DOCUMENT_RETIRE = "document.retire"
+    DOCUMENT_PURGE = "document.purge"
     JOB_MANAGE = "job.manage"
     GRANT_MANAGE = "grant.manage"
     APIKEY_MANAGE = "apikey.manage"
@@ -113,7 +117,12 @@ BUILTIN_ROLES: Mapping[str, frozenset[Permission]] = MappingProxyType(
         "reviewer": _REVIEWER,
         "maintainer": _EDITOR
         | _REVIEWER
-        | {Permission.PROPOSAL_MERGE, Permission.SOURCE_MANAGE, Permission.JOB_MANAGE},
+        | {
+            Permission.PROPOSAL_MERGE,
+            Permission.SOURCE_MANAGE,
+            Permission.JOB_MANAGE,
+            Permission.DOCUMENT_RETIRE,
+        },
         "admin": frozenset(Permission) - INSTALLATION_ADMIN_PERMISSIONS,
         "agent-reader": _VIEWER,
     }

{lorebase_keeper-0.2.3 → lorebase_keeper-0.3.0}/src/lorebase_keeper/auth/ports.py

@@ -60,6 +60,8 @@ class GroupsPort(Protocol):
         self, principal_id: str, external_groups: Collection[str] = ()
     ) -> list[str]: ...
 
+    async def members(self, group_ids: Collection[str]) -> dict[str, list[str]]: ...
+
     async def subject_exists(self, subject_id: str) -> bool: ...
 
 

{lorebase_keeper-0.2.3 → lorebase_keeper-0.3.0}/src/lorebase_keeper/kindhealth/scan.py

@@ -25,7 +25,6 @@ from sqlalchemy import (
     literal_column,
     or_,
     select,
-    text,
 )
 from sqlalchemy.dialects.postgresql import distinct_on
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -49,30 +48,12 @@ from lorebase_keeper.kindhealth.models import (
     ViolationReport,
 )
 from lorebase_keeper.reading.views import kind_name
+from lorebase_store.duplicates import duplicate_attributes, duplicate_groups
 from lorebase_store.layout import BranchLayout
 
 BATCH = 500
 """Records fetched per round trip while re-validating."""
 
-_DUPLICATES = r"""
-    WITH normalized AS (
-        SELECT key, lower(regexp_replace(btrim("values" ->> :attribute), '\s+', ' ', 'g')) AS norm
-        FROM {records}
-        WHERE domain_id = :domain AND branch = :branch AND kind_id = :kind
-          AND "values" ->> :attribute IS NOT NULL
-    )
-    SELECT norm, count(*) AS members,
-           (array_agg(key ORDER BY key))[1:CAST(:keys AS int)] AS member_keys,
-           count(*) OVER () AS total_groups,
-           sum(count(*)) OVER () AS total_members
-    FROM normalized
-    WHERE norm <> ''
-    GROUP BY norm
-    HAVING count(*) > 1
-    ORDER BY count(*) DESC, norm
-    LIMIT :groups
-    """
-
 
 @dataclass(frozen=True)
 class Branch:
@@ -243,15 +224,6 @@ async def validate_records(
 # Duplicates ---------------------------------------------------------------------------------
 
 
-def duplicate_attributes(kind: Kind) -> list[str]:
-    """Attribute ids checked for duplicates: unique ones, then the title Attribute."""
-    ids = [a.id for a in kind.attributes.values() if a.unique and not a.is_derived]
-    title = kind.attributes.get(kind.title_attribute) if kind.title_attribute else None
-    if title is not None and not title.is_derived and title.id not in ids:
-        ids.append(title.id)
-    return ids
-
-
 async def find_duplicates(
     session: AsyncSession,
     where: Branch,
@@ -279,29 +251,24 @@ async def find_duplicates(
     groups = 0
     for attribute_id in ids:
         attribute = kind.attributes[attribute_id]
-        rows = (
-            await session.execute(
-                text(_DUPLICATES.format(records=where.rows.records_from())),
-                {
-                    "domain": where.domain_id,
-                    "branch": where.branch,
-                    "kind": kind.id,
-                    "attribute": attribute_id,
-                    "keys": settings.duplicate_keys_per_group,
-                    "groups": settings.max_duplicate_groups,
-                },
-            )
-        ).all()
+        rows = await duplicate_groups(
+            session,
+            where.rows,
+            kind.id,
+            attribute_id,
+            keys_per_group=settings.duplicate_keys_per_group,
+            max_groups=settings.max_duplicate_groups,
+        )
         if rows:
-            groups += int(rows[0].total_groups)
+            groups += rows[0].total_groups
         if hidden(attribute):
             if rows:
                 withheld.append(
                     HiddenDuplicates(
                         attribute=attribute.api_name,
                         unique=attribute.unique,
-                        groups=int(rows[0].total_groups),
-                        records=int(rows[0].total_members),
+                        groups=rows[0].total_groups,
+                        records=rows[0].total_members,
                     )
                 )
             continue
@@ -310,7 +277,7 @@ async def find_duplicates(
                 attribute=attribute.api_name,
                 unique=attribute.unique,
                 value=None if sensitive(attribute) else row.norm,
-                count=int(row.members),
+                count=row.members,
                 keys=list(row.member_keys),
             )
             for row in rows

{lorebase_keeper-0.2.3 → lorebase_keeper-0.3.0}/src/lorebase_keeper/readiness.py

@@ -21,9 +21,15 @@ from typing import Any, Protocol
 
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
+from lorebase_keeper.reading.settings import SemanticSettings
 from lorebase_platform.secrets import SecretResolutionError, resolve_secret
 from lorebase_platform.settings import ConfigError, Settings
 from lorebase_store import bm25
+from lorebase_store.embeddings import (
+    ITERATIVE_SCAN_MIN_VERSION,
+    pgvector_version,
+    stored_models,
+)
 from lorebase_store.migrations import head_revisions
 from lorebase_store.replicas import ReplicaState
 
@@ -217,6 +223,50 @@ class SearchBackendCheck:
         )
 
 
+class VectorSearchCheck:
+    """How filtered vector search is served (design 8.8): iterative HNSW scans with pgvector
+    0.8 or later and `search.semantic.iterative_scan: auto`, over-fetching otherwise. Never
+    takes the service out of rotation; the detail names the installed pgvector version.
+
+    Degraded when vectors are stored but none under `search.semantic.model`: the setting
+    drifted from the model Scribe embeds with (`inference.embeddings.model`), and semantic
+    search would find nothing."""
+
+    name = "vector_search"
+
+    def __init__(
+        self, sessions: async_sessionmaker[AsyncSession], semantic: SemanticSettings
+    ) -> None:
+        self._sessions = sessions
+        self._semantic = semantic
+
+    async def __call__(self) -> CheckResult:
+        async with self._sessions() as session, session.begin():
+            version = await pgvector_version(session)
+            models = await stored_models(session) if version is not None else []
+        if version is None:
+            return CheckResult(CheckStatus.DEGRADED, "pgvector is not installed")
+        model = self._semantic.model
+        if models and model not in models:
+            return CheckResult(
+                CheckStatus.DEGRADED,
+                f"search.semantic.model {model!r} has no stored vectors (stored: "
+                f"{', '.join(models)}); semantic search finds nothing",
+            )
+        installed = ".".join(str(part) for part in version)
+        if self._semantic.iterative_scan == "auto" and version >= ITERATIVE_SCAN_MIN_VERSION:
+            return CheckResult(
+                CheckStatus.OK,
+                f"pgvector {installed}: filtered vector search uses iterative scans "
+                f"(up to {self._semantic.max_scan_tuples} tuples)",
+            )
+        return CheckResult(
+            CheckStatus.OK,
+            f"pgvector {installed}: filtered vector search over-fetches "
+            f"{self._semantic.overfetch_factor}x",
+        )
+
+
 def _join(revisions: Collection[str]) -> str:
     return ", ".join(sorted(revisions)) or "none"