codebase-index 1.6.0__py3-none-any.whl

codebase_index/retrieval/intent.py

@@ -0,0 +1,56 @@
+"""Cheap rule-first intent classifier (regex/keyword heuristics).
+
+Each intent maps to retriever weights over {"path","symbol","fts"}, a default
+token budget, and a graph strategy (consumed later by M5).
+"""
+
+from __future__ import annotations
+
+import re
+
+from .types import Intent, IntentPlan
+
+_RULES: list[tuple[re.Pattern[str], Intent]] = [
+    (re.compile(r"traceback|stack ?trace|error:|exception|why does .* fail", re.I), Intent.DEBUG_ERROR),
+    (re.compile(r"\b(who calls|find references|references to|callers of)\b", re.I), Intent.FIND_REFS),
+    (re.compile(r"\b(what breaks|what depends on|impact of|affected if)\b", re.I), Intent.IMPACT),
+    (re.compile(r"\b(data ?flow|where does .* get set|trace .* flow)\b", re.I), Intent.DATA_FLOW),
+    (re.compile(r"\b(architecture|high-?level|overview|structure of)\b", re.I), Intent.ARCHITECTURE),
+    (re.compile(r"\b(how does|how do|explain how|how .* works?)\b", re.I), Intent.HOW_IT_WORKS),
+    (re.compile(r"\b(where is|find the|locate|implementation of|defined)\b", re.I), Intent.LOCATE_IMPL),
+]
+
+_PLANS: dict[Intent, IntentPlan] = {
+    Intent.LOCATE_IMPL: IntentPlan(Intent.LOCATE_IMPL, {"symbol": 1.0, "path": 0.7, "fts": 0.4, "vector": 0.2}, 1500),
+    Intent.HOW_IT_WORKS: IntentPlan(Intent.HOW_IT_WORKS, {"fts": 1.0, "symbol": 0.7, "path": 0.3, "vector": 0.8}, 2200, graph_strategy="down"),
+    Intent.IMPACT: IntentPlan(Intent.IMPACT, {"symbol": 1.0, "path": 0.6, "fts": 0.3, "vector": 0.3}, 1800, graph_strategy="up"),
+    Intent.FIND_REFS: IntentPlan(Intent.FIND_REFS, {"symbol": 1.0, "fts": 0.3, "path": 0.2, "vector": 0.2}, 1500, graph_strategy="refs"),
+    Intent.DATA_FLOW: IntentPlan(Intent.DATA_FLOW, {"symbol": 0.9, "fts": 0.8, "path": 0.3, "vector": 0.6}, 2000, graph_strategy="both"),
+    Intent.DEBUG_ERROR: IntentPlan(Intent.DEBUG_ERROR, {"fts": 1.0, "symbol": 0.6, "path": 0.3, "vector": 0.4}, 1800),
+    Intent.ARCHITECTURE: IntentPlan(Intent.ARCHITECTURE, {"fts": 0.6, "symbol": 0.4, "path": 0.5, "vector": 0.5}, 2500, summaries_first=True),
+    Intent.KEYWORD: IntentPlan(Intent.KEYWORD, {"fts": 1.0, "symbol": 0.6, "path": 0.5, "vector": 0.7}, 1500),
+}
+
+
+def detect_intent(query: str) -> IntentPlan:
+    matched = [_PLANS[intent] for pattern, intent in _RULES if pattern.search(query)]
+    if not matched:
+        return _PLANS[Intent.KEYWORD]
+    if len(matched) == 1:
+        return matched[0]
+
+    # Merge multiple matched intents: max weight per retriever, max token_budget,
+    # primary intent/graph_strategy from first match.
+    merged_weights: dict[str, float] = {}
+    for plan in matched:
+        for key, val in plan.weights.items():
+            merged_weights[key] = max(merged_weights.get(key, 0.0), val)
+
+    primary = matched[0]
+    return IntentPlan(
+        intent=primary.intent,
+        weights=merged_weights,
+        token_budget=max(p.token_budget for p in matched),
+        graph_strategy=primary.graph_strategy,
+        summaries_first=any(p.summaries_first for p in matched),
+    )

codebase_index/retrieval/pipeline.py

@@ -0,0 +1,207 @@
+"""Orchestrate the hybrid retrieval pipeline (RETRIEVAL.md §1–§7).
+
+query -> intent -> retrievers -> RRF fuse -> rerank -> budget -> payload.
+Graph expansion (§5) and vector retrieval (§2 vector) are deferred to M5/M6.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from pathlib import Path
+from typing import Optional
+
+from ..config import Config
+from ..indexer.freshness import compute_freshness
+from . import searchers
+from .budget import apply_budget
+from .fusion import fuse
+from .intent import detect_intent
+from .rerank import rerank
+from .types import Confidence
+
+_TERM_RE = re.compile(r"[A-Za-z0-9_]+")
+_RRF_K = 60
+# Max results kept per file before extras are pushed to the tail. Bucketed fusion
+# already collapses co-located hits; this caps the long tail of one big file
+# dominating the page so distinct files get surfaced.
+_MAX_PER_FILE = 3
+_KIND_ALIASES = {
+    "method": "method",
+    "methods": "method",
+    "function": "function",
+    "functions": "function",
+    "class": "class",
+    "classes": "class",
+    "interface": "interface",
+    "interfaces": "interface",
+    "enum": "enum",
+    "enums": "enum",
+    "type": "type",
+    "types": "type",
+}
+
+
+def _requested_symbol_kind(query: str) -> str | None:
+    kinds = {
+        _KIND_ALIASES[t.lower()]
+        for t in _TERM_RE.findall(query)
+        if t.lower() in _KIND_ALIASES
+    }
+    return next(iter(kinds)) if len(kinds) == 1 else None
+
+
+def _run_retrievers(conn, query, *, mode, limit, weights, backend=None):
+    lists = {}
+    symbol_kind = _requested_symbol_kind(query)
+    if mode in ("hybrid", "fts"):
+        lists["fts"] = searchers.fts_candidates(conn, query, limit=limit)
+    if mode in ("hybrid", "symbol"):
+        lists["symbol"] = searchers.symbol_candidates(conn, query, limit=limit, kind=symbol_kind)
+    if mode == "hybrid":
+        lists["path"] = searchers.path_candidates(conn, query, limit=limit)
+    if mode in ("hybrid", "vector") and backend is not None and getattr(backend, "enabled", False):
+        lists["vector"] = searchers.vector_candidates(conn, query, backend, limit=limit)
+    if mode != "hybrid":
+        weights = {mode: 1.0}
+    return lists, weights
+
+
+def _confidence(ranked) -> Confidence:
+    if not ranked:
+        return Confidence.LOW
+    top = ranked[0]
+    if top.score <= 0:
+        return Confidence.LOW
+    if len(ranked) == 1:
+        return Confidence.MEDIUM
+    # Relative gap, not absolute: scale-invariant, so it stays meaningful regardless
+    # of fusion's score magnitude. agreeing_sources is file-level (how many retrievers
+    # surfaced the winning file at all), the signal RRF agreement is meant to capture.
+    rel_gap = (top.score - ranked[1].score) / top.score
+    agree = getattr(top, "agreeing_sources", 1)
+    exact = getattr(top, "exact_symbol", False)
+    n = len(ranked)
+    # Exact symbol match always high confidence
+    if exact:
+        return Confidence.HIGH
+    # Strong multi-source agreement with a clear score gap
+    if agree >= 3 and rel_gap > 0.15:
+        return Confidence.HIGH
+    if agree >= 2 and rel_gap > 0.25:
+        return Confidence.HIGH
+    # Single source but very dominant winner
+    if agree == 1 and rel_gap > 0.5:
+        return Confidence.HIGH
+    if agree >= 2 or rel_gap > 0.1 or n >= 5:
+        return Confidence.MEDIUM
+    return Confidence.LOW
+
+
+def _diversify(ranked: list, *, per_file: int) -> list:
+    """Stable reorder: keep the first `per_file` hits of each file in place, push
+    the rest to the tail (preserving their relative order). Nothing is dropped, so
+    recall is intact; the page just isn't monopolised by one file's many regions."""
+    kept: list = []
+    overflow: list = []
+    counts: dict[str, int] = {}
+    for c in ranked:
+        counts[c.path] = counts.get(c.path, 0) + 1
+        (kept if counts[c.path] <= per_file else overflow).append(c)
+    return kept + overflow
+
+
+def _fallback_suggestions(query, ranked) -> dict:
+    terms = _TERM_RE.findall(query)
+    if not terms:
+        return {}
+    longest = max(terms, key=len)
+    rg = [f'rg -n "{longest}"']
+    if len(terms) > 1:
+        rg.append(f'rg -n "{".*".join(terms[:3])}"')
+    return {"ripgrep": rg}
+
+
+def search(
+    conn: sqlite3.Connection,
+    query: str,
+    *,
+    mode: str,
+    limit: int,
+    token_budget: int,
+    no_fallback: bool,
+    backend=None,
+    root: Optional[Path] = None,
+    config: Optional[Config] = None,
+    offset: int = 0,
+    compact: bool = True,
+    compact_min_reduction: float = 0.25,
+) -> dict:
+    plan = detect_intent(query)
+    if token_budget <= 0:
+        token_budget = plan.token_budget
+    fetch_limit = limit + offset
+    lists, weights = _run_retrievers(
+        conn, query, mode=mode, limit=fetch_limit, weights=plan.weights, backend=backend
+    )
+    fused = fuse(lists, weights=weights, k=_RRF_K)
+    ranked = _diversify(rerank(fused, query=query, intent=plan.intent), per_file=_MAX_PER_FILE)
+    ranked = ranked[:fetch_limit]
+    confidence = _confidence(ranked)
+    # Scale budget proportionally so later pages receive snippet coverage.
+    scaled_budget = token_budget * fetch_limit // max(limit, 1) if offset > 0 else token_budget
+    from .skeleton import make_compactor
+
+    compactor = make_compactor(
+        intent=plan.intent, query=query,
+        enabled=compact, min_reduction=compact_min_reduction,
+    )
+    all_results, all_recommended = apply_budget(
+        ranked, token_budget=scaled_budget, compactor=compactor
+    )
+
+    # Paginate: slice results and filter recommended_reads to the current page.
+    paginated = all_results[offset:offset + limit]
+    paginated_keys = {(r["path"], r["line_start"], r["line_end"]) for r in paginated}
+    recommended = [
+        r for r in all_recommended
+        if (r["path"], r["line_start"], r["line_end"]) in paginated_keys
+    ]
+    has_more = len(all_results) > offset + limit
+
+    fallback = {}
+    if not no_fallback and confidence == Confidence.LOW:
+        fallback = _fallback_suggestions(query, ranked)
+
+    if config is not None and root is not None:
+        freshness = compute_freshness(conn, root, config)
+    else:
+        from ..models import IndexFreshness
+        from ..storage import repo
+        built_at = repo.get_meta(conn, "built_at")
+        freshness = IndexFreshness(
+            exists=built_at is not None,
+            stale=False,
+            files_changed_since_build=0,
+            built_at=built_at,
+            head_commit=repo.get_meta(conn, "head_commit"),
+        )
+
+    payload: dict = {
+        "query": query,
+        "intent": plan.intent.value,
+        "mode": mode,
+        "index": freshness.model_dump(),
+        "confidence": confidence.value,
+        "results": paginated,
+        "recommended_reads": recommended,
+        "fallback_suggestions": fallback,
+    }
+    if offset > 0 or has_more:
+        payload["pagination"] = {
+            "offset": offset,
+            "limit": limit,
+            "has_more": has_more,
+            "next_offset": offset + limit if has_more else None,
+        }
+    return payload

codebase_index/retrieval/rerank.py

@@ -0,0 +1,69 @@
+"""Explainable feature reranker layered on the fused order (RETRIEVAL.md §4).
+
+Adds a bounded bonus/penalty to the fused RRF score and produces a human-readable
+`reason` per candidate. No external model. Graph centrality uses the denormalized
+symbols.in_degree/out_degree; cross-node graph expansion is M5.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+
+from ..discovery.classify import is_test_path
+from .types import Candidate, Intent
+
+_TERM_RE = re.compile(r"[A-Za-z0-9_]+")
+
+# Graph-centrality bonus. Logarithmic (not linear) so a "god class" with hundreds
+# of callers cannot dominate a genuinely relevant low-degree match on a stray-term
+# tie. log1p compresses the tail — in_degree 4 → 10 → 100 yields a gently rising,
+# capped bonus instead of saturating the cap by in_degree 10 — and the lower cap
+# keeps centrality a tiebreak rather than an override. This dampens the god-class
+# over-ranking documented in tests/benchmark_honest_RESULTS.md.
+_DEGREE_SCALE = 0.03
+_DEGREE_CAP = 0.08
+
+
+def rerank(candidates: list[Candidate], *, query: str, intent: Intent) -> list[Candidate]:
+    terms = {t.lower() for t in _TERM_RE.findall(query)}
+    for c in candidates:
+        bonus = 0.0
+        reasons: list[str] = []
+
+        if c.source == "symbol" and c.kind in {"function", "method", "class", "interface", "type"}:
+            bonus += 0.05
+        if c.exact_symbol:
+            bonus += 0.20
+            reasons.append("exact symbol match")
+        if c.symbol and c.symbol.lower() in terms:
+            bonus += 0.05
+
+        if any(t in c.path.lower() for t in terms):
+            bonus += 0.05
+            reasons.append(f"in {c.path.rsplit('/', 1)[0] or '.'}/")
+
+        if c.in_degree:
+            bonus += min(_DEGREE_CAP, math.log1p(c.in_degree) * _DEGREE_SCALE)
+            reasons.append(f"{c.in_degree} callers")
+        elif c.ref_count:
+            # Precise in_degree is only computed for globally-unique symbol names
+            # (ambiguous names never resolve), so common names like `run`/`handle`
+            # always score 0. Fall back to a damped name-reference count — half the
+            # scale and cap — so centrality still breaks ties without overriding the
+            # precise signal where it exists.
+            bonus += min(_DEGREE_CAP / 2, math.log1p(c.ref_count) * (_DEGREE_SCALE / 2))
+            reasons.append(f"~{c.ref_count} refs by name")
+        if intent is Intent.ARCHITECTURE and (c.in_degree + c.out_degree):
+            bonus += min(_DEGREE_CAP, math.log1p(c.in_degree + c.out_degree) * (_DEGREE_SCALE / 2))
+
+        wants_tests = "test" in terms or "tests" in terms
+        if c.is_generated or (is_test_path(c.path) and not wants_tests):
+            bonus -= 0.15
+            reasons.append("generated/test demoted")
+
+        c.score += bonus
+        c.reason = " · ".join(reasons) if reasons else c.source
+
+    candidates.sort(key=lambda c: c.score, reverse=True)
+    return candidates

codebase_index/retrieval/searchers.py

@@ -0,0 +1,291 @@
+"""Three retrievers, each emitting a uniform list[Candidate].
+
+Vector retrieval (RETRIEVAL.md §2) is M6 and intentionally absent here; the
+pipeline degrades to path+symbol+fts.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from pathlib import Path
+from typing import Optional
+
+from ..config import Config
+from ..indexer.freshness import compute_freshness
+from ..models import (
+    GraphCoverage,
+    IndexFreshness,
+    RefSite,
+    RefsResponse,
+    SymbolDef,
+    SymbolResponse,
+)
+from ..storage import repo
+from .types import Candidate as M4Candidate
+
+_WORD_RE = re.compile(r"[A-Za-z0-9_]+")
+_CAMEL_RE = re.compile(r"[A-Z]+(?![a-z])|[A-Z]?[a-z0-9]+")
+
+
+def fts_candidates(conn: sqlite3.Connection, query: str, *, limit: int) -> list[M4Candidate]:
+    match = build_match_query(query)
+    if not match:
+        return []
+    out: list[M4Candidate] = []
+    for row in repo.fts_search(conn, match, limit=limit):
+        out.append(
+            M4Candidate(
+                path=row["path"],
+                line_start=row["line_start"],
+                line_end=row["line_end"],
+                source="fts",
+                score=-float(row["bm25"]),
+                content=row["content"],
+                token_est=int(row["token_est"]),
+            )
+        )
+    return out
+
+
+# Natural-language filler that is never a useful symbol query term. Kept deliberately small:
+# anything that could plausibly be an identifier (get/set/run/...) is NOT a stopword.
+_SYMBOL_STOPWORDS = {
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being", "how", "does",
+    "do", "did", "what", "where", "which", "who", "whom", "when", "why", "to", "of", "in",
+    "on", "for", "and", "or", "with", "from", "it", "this", "that", "these", "those",
+    "into", "during", "if", "via", "across", "between", "about", "their", "its",
+}
+
+
+def _salient_terms(query: str) -> list[str]:
+    """Lower-cased query terms worth matching against symbol names (dedup, order-preserving)."""
+    out: list[str] = []
+    for t in _WORD_RE.findall(query):
+        tl = t.lower()
+        if len(tl) < 3 or tl in _SYMBOL_STOPWORDS:
+            continue
+        out.append(tl)
+    return list(dict.fromkeys(out))
+
+
+def _name_subtokens(name: str) -> set[str]:
+    """camelCase + snake_case split of a symbol name, lower-cased (e.g. ReligionManager ->
+    {religion, manager}; refresh_access_token -> {refresh, access, token})."""
+    return {s.lower() for s in _subtokens(name)}
+
+
+def symbol_candidates(
+    conn: sqlite3.Connection, query: str, *, limit: int, kind: str | None = None
+) -> list[M4Candidate]:
+    """Symbol retriever that scores by how many query terms a symbol's name covers.
+
+    The old behaviour searched only the single longest term, so "religion manager" matched
+    the bare `Religion` class (exact) and never reached `ReligionManager`. Now every salient
+    term is searched and candidates are ranked by camelCase/underscore-split *coverage* of the
+    query, so the multi-word concept lands on the multi-word symbol.
+    """
+    terms = _salient_terms(query)
+    if not terms:
+        return []
+
+    term_set = set(terms)
+    joined = "".join(terms)
+    rows_by_key: dict[tuple, sqlite3.Row] = {}
+    for term in terms:
+        for row in repo.symbol_search(conn, term, limit=limit, kind=kind):
+            key = (row["path"], row["line_start"], row["name"])
+            rows_by_key.setdefault(key, row)
+
+    scored: list[tuple] = []
+    for row in rows_by_key.values():
+        subs = _name_subtokens(row["name"])
+        name_l = (row["name"] or "").lower()
+        covered = sum(1 for t in terms if t in subs or t in name_l)
+        tightness = len(subs & term_set) / len(subs) if subs else 0.0
+        # Exact-match precedence is for *precise* lookups only. With one salient term it's a
+        # real identifier query; with many it must match the whole camelCase-joined name
+        # (e.g. "religion manager" -> ReligionManager). A single shared term ("token" hitting
+        # a generated `Token` type) must NOT count as exact.
+        exact = (len(terms) == 1 and bool(row["is_exact"])) or (bool(joined) and name_l == joined)
+        # Ranking: most query terms covered, then exact-name match, then a tighter name
+        # (fewer junk subtokens), then more-referenced (in_degree), then a shorter name.
+        sort_key = (covered, int(exact), tightness, int(row["in_degree"]), -len(name_l))
+        score = covered + tightness + (2.0 if exact else 0.0)
+        scored.append((sort_key, score, exact, row))
+
+    scored.sort(key=lambda x: x[0], reverse=True)
+
+    out: list[M4Candidate] = []
+    for sort_key, score, exact, row in scored[:limit]:
+        out.append(
+            M4Candidate(
+                path=row["path"],
+                line_start=row["line_start"],
+                line_end=row["line_end"],
+                source="symbol",
+                score=float(score),
+                kind=row["kind"],
+                symbol=row["name"],
+                content=row["signature"],
+                token_est=max(1, len(row["signature"] or "") // 4),
+                in_degree=int(row["in_degree"]),
+                out_degree=int(row["out_degree"]),
+                is_generated=bool(row["is_generated"]),
+                exact_symbol=exact,
+            )
+        )
+
+    # Damped centrality fallback: symbols whose name is not globally unique never
+    # get a resolved in_degree, so back-fill a name-reference count for the zero ones.
+    zero_deg = [c.symbol for c in out if not c.in_degree and c.symbol]
+    if zero_deg:
+        counts = repo.name_ref_counts(conn, zero_deg)
+        for c in out:
+            if not c.in_degree and c.symbol:
+                c.ref_count = counts.get(c.symbol, 0)
+    return out
+
+
+def path_candidates(conn: sqlite3.Connection, query: str, *, limit: int) -> list[M4Candidate]:
+    out: list[M4Candidate] = []
+    for rank, row in enumerate(repo.path_search(conn, query, limit=limit)):
+        out.append(
+            M4Candidate(
+                path=row["path"],
+                line_start=1,
+                line_end=1,
+                source="path",
+                score=float(row["hits"]) / (1 + rank),
+                is_generated=bool(row["is_generated"]),
+            )
+        )
+    return out
+
+
+def _subtokens(term: str) -> list[str]:
+    parts: list[str] = []
+    for piece in term.split("_"):
+        parts.extend(m.group(0) for m in _CAMEL_RE.finditer(piece))
+    return [p for p in parts if len(p) >= 2]
+
+
+def build_match_query(query: str) -> str:
+    """Build the FTS5 MATCH expression for `query`.
+
+    Each whitespace term expands to an OR group over the term and its
+    camelCase/snake_case subtokens; groups are AND-ed. Natural-language filler
+    ("how does X work") is dropped first: otherwise FTS would AND-in stopwords
+    that code chunks never contain, collapsing recall to zero on the very intents
+    (HOW_IT_WORKS / DEBUG_ERROR) that weight FTS highest. If *every* term is a
+    stopword we fall back to the full set rather than emit an empty match.
+    """
+    groups: list[str] = []
+    salient: list[str] = []
+    for term in _WORD_RE.findall(query):
+        variants = {term, *_subtokens(term)}
+        variants = {v for v in variants if len(v) >= 2}
+        if not variants:
+            continue
+        ored = " OR ".join(f'"{v}"' for v in sorted(variants, key=str.lower))
+        # FTS5 rejects implicit AND (space) when a group contains parenthesised OR
+        # expressions; explicit AND is required between all groups.
+        group = f"({ored})" if len(variants) > 1 else ored
+        groups.append(group)
+        if term.lower() not in _SYMBOL_STOPWORDS:
+            salient.append(group)
+    return " AND ".join(salient or groups)
+
+
+def _freshness(
+    conn: sqlite3.Connection, root: Optional[Path] = None, config: Optional[Config] = None
+) -> IndexFreshness:
+    if config is not None and root is not None:
+        return compute_freshness(conn, root, config)
+    built_at = repo.get_meta(conn, "built_at")
+    return IndexFreshness(
+        exists=built_at is not None,
+        stale=False,
+        files_changed_since_build=0,
+        built_at=built_at,
+        head_commit=repo.get_meta(conn, "head_commit"),
+    )
+
+
+def symbol_lookup(
+    conn: sqlite3.Connection, name: str, *, kind: Optional[str], exact: bool
+) -> SymbolResponse:
+    rows = repo.symbols_by_name(conn, name, kind=kind, exact=exact)
+    symbols = [
+        SymbolDef(
+            name=row["name"],
+            qualified=row["qualified"],
+            kind=row["kind"],
+            path=row["path"],
+            line_start=row["line_start"],
+            line_end=row["line_end"],
+            signature=row["signature"],
+        )
+        for row in rows
+    ]
+    return SymbolResponse(query=name, index=_freshness(conn), symbols=symbols)
+
+
+def refs_lookup(conn: sqlite3.Connection, name: str, *, kind: str) -> RefsResponse:
+    defs = repo.symbols_by_name(conn, name, exact=True)
+    sites = [
+        RefSite(
+            path=row["path"],
+            line=row["line"],
+            kind="call",
+            confidence=row["confidence"] if "confidence" in row.keys() else "extracted",
+        )
+        for row in repo.refs_for_name(conn, name)
+    ]
+    if kind == "all":
+        sites.extend(
+            # A definition is the symbol itself — exact by construction.
+            RefSite(path=row["path"], line=row["line_start"], kind="definition")
+            for row in defs
+        )
+    sites.sort(key=lambda site: (site.path, site.line, site.kind))
+    # Coverage is judged by the symbol's defining language(s); fall back to the
+    # call-site files when the symbol has no indexed definition.
+    coverage_paths = [row["path"] for row in defs] or [s.path for s in sites]
+    return RefsResponse(
+        query=name,
+        index=_freshness(conn),
+        sites=sites,
+        coverage=GraphCoverage.for_paths(coverage_paths),
+    )
+
+
+def vector_candidates(
+    conn: sqlite3.Connection, query: str, backend, *, limit: int
+) -> list["M4Candidate"]:
+    """Semantic retriever: embed the query, KNN over vec_chunks.
+
+    `backend` must be an enabled EmbeddingBackend; callers pass None/Noop when
+    embeddings are disabled and simply skip this retriever. sqlite-vec `distance`
+    is smaller-is-better, so the candidate score negates it for "higher is better".
+    """
+    if backend is None or not getattr(backend, "enabled", False):
+        return []
+    query = query.strip()
+    if not query:
+        return []
+    vec = backend.embed([query])[0]
+    out: list[M4Candidate] = []
+    for row in repo.vector_search(conn, vec, limit=limit):
+        out.append(
+            M4Candidate(
+                path=row["path"],
+                line_start=row["line_start"],
+                line_end=row["line_end"],
+                source="vector",
+                score=-float(row["distance"]),
+                content=row["content"],
+                token_est=int(row["token_est"]),
+            )
+        )
+    return out