vectr 1.0.0__py3-none-any.whl

agent/eviction_advisor.py

@@ -0,0 +1,447 @@
+"""
+EvictionAdvisor — tells the LLM which chunks vectr can re-retrieve in <50ms.
+
+The guarantee: anything listed here is fully indexed and re-retrievable in <50ms.
+This is the reverse signal in the bidirectional protocol. The LLM calls vectr_remember
+to save notes; the EvictionAdvisor proactively signals when retrieved content
+is fully indexed and can be re-retrieved without re-reading the file.
+
+The advisor tracks which chunks have been retrieved in the current session and
+estimates their token cost. When the session hits a threshold, it fires an
+eviction hint.
+
+Limitation — Read/Bash blind spot (E2):
+The advisor only tracks content delivered through vectr's own tools (vectr_search,
+vectr_locate, vectr_trace, vectr_recall). Code the agent reads via the IDE's native
+Read or Bash tools is invisible here. Token estimates are therefore a lower bound;
+eviction may fire later than ideal on sessions that mix vectr retrieval with direct
+file reading. The gap shrinks as agents adopt vectr_search as their primary navigation
+path (Problem 3). Track `vectr_evict_hint_triggered` in benchmarks (E5) to monitor
+real-world eviction uptake.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+from agent.config import (
+    EVICTION_HINT_MAX_IDS,
+    EVICTION_REMEMBER_ESCALATION_CHUNKS,
+    EVICTION_REMEMBER_ESCALATION_TOKENS,
+    EVICTION_RETRIEVED_TOKEN_GATE,
+)
+
+
+@dataclass
+class RetrievedChunk:
+    file_path: str
+    lines: str
+    symbol_name: str
+    content: str
+    # UPG-EVICT-SESSION-SCOPE: the exact vectr_fetch re-fetch key for this chunk
+    # (`file_path:start_line-end_line`), when the caller had one. Empty for
+    # chunks recorded from a surface that doesn't guarantee an exact indexed
+    # chunk id (e.g. a symbol-graph snippet whose line range may not match a
+    # stored chunk boundary) — never guessed, so eviction_hint() only ever
+    # advertises a re-fetch key that is known to work.
+    chunk_id: str = ""
+    retrieved_at: float = field(default_factory=time.time)
+
+    @property
+    def estimated_tokens(self) -> int:
+        return max(1, len(self.content) // 4)
+
+
+class EvictionAdvisor:
+    """
+    Tracks what the LLM has retrieved this session and advises on eviction.
+
+    Usage:
+        advisor = EvictionAdvisor(eviction_threshold_tokens=4000)
+        advisor.record(chunk)          # call after every vectr_search result
+        hint = advisor.eviction_hint() # returns text the LLM can act on
+    """
+
+    def __init__(
+        self,
+        eviction_threshold_tokens: int = 40_000,
+        tool_call_threshold: int = 10,
+        retrieval_call_threshold: int = 1,
+        time_threshold_seconds: float = 180.0,
+        rearm_retrieval_calls: int = 4,
+        retrieved_token_gate: int | None = None,
+        remember_escalation_chunks: int | None = None,
+        remember_escalation_tokens: int | None = None,
+    ) -> None:
+        # Fire when ANY of these conditions is met:
+        #   cumulative injected chars ÷ 4 >= 40K  (vectr-tracked content)
+        #   tool_call_count > 10                   (all MCP calls this session)
+        #   retrieval_call_count > 1               (search/locate/trace calls only)
+        #   elapsed seconds >= 180                 (wall-clock since session start)
+        #
+        # Why retrieval_call_threshold: the tool_call_count trigger counts all vectr MCP
+        # calls, but the LLM typically makes only 3-4 per task (status + 1 locate + 2 search)
+        # so threshold=10 never fires. Counting only retrieval calls (search/locate/trace)
+        # and firing on the 2nd one gives a natural mid-task trigger: the LLM has found
+        # something worth keeping before it switches into implementation mode.
+        #
+        # Why time_threshold: the eviction protocol requires vectr to see every retrieval
+        # to track real context pressure (spec line 78), but the LLM uses native Read/Bash
+        # for most reading — those calls are invisible here. A time-based trigger fires
+        # regardless of tool mix, catching sessions where the LLM barely uses vectr at all.
+        # arXiv:2310.08560, arXiv:2510.24699.
+        self._threshold = eviction_threshold_tokens
+        self._tool_call_threshold = tool_call_threshold
+        self._retrieval_call_threshold = retrieval_call_threshold
+        self._time_threshold_seconds = time_threshold_seconds
+        # UPG-7.1: re-arm the auto-footer only after this many further retrieval
+        # calls (or a fresh token/time crossing) since the last time it fired —
+        # so the footer can't repeat on every response.
+        self._rearm_retrieval_calls = rearm_retrieval_calls
+        # UPG-11.15: suppress auto_eviction_hint() when accumulated retrieved
+        # tokens since the last hint (or session start) are below this gate.
+        # Prevents a burst of small-result searches from triggering the full
+        # ACTION REQUIRED block before real context pressure has accumulated.
+        # None → use the config value (EVICTION_RETRIEVED_TOKEN_GATE).
+        self._retrieved_token_gate: int = (
+            retrieved_token_gate if retrieved_token_gate is not None
+            else EVICTION_RETRIEVED_TOKEN_GATE
+        )
+        # UPG-REMEMBER-BANNER-FATIGUE: gates auto_eviction_hint()'s escalated
+        # directive on chunks retrieved since the last vectr_remember, not
+        # just on raw context pressure — see note_remembered().
+        self._remember_escalation_chunks: int = (
+            remember_escalation_chunks if remember_escalation_chunks is not None
+            else EVICTION_REMEMBER_ESCALATION_CHUNKS
+        )
+        # UPG-EVICT-ESCALATION-GATE-TOO-LOW: companion gate required IN ADDITION
+        # to _remember_escalation_chunks — see note_remembered() and
+        # _tokens_since_remember(). A single large search can satisfy the chunk
+        # gate alone in one burst; requiring both makes that burst insufficient
+        # on its own to re-trip the escalated directive.
+        self._remember_escalation_tokens: int = (
+            remember_escalation_tokens if remember_escalation_tokens is not None
+            else EVICTION_REMEMBER_ESCALATION_TOKENS
+        )
+        self._chunks: list[RetrievedChunk] = []
+        self._tool_call_count: int = 0
+        self._retrieval_call_count: int = 0
+        self._session_started_at: float = time.time()
+        # (tokens, retrieval_count, wall_time) recorded the last time the auto
+        # footer emitted; None until the first emit. Gates auto_eviction_hint().
+        self._last_emit: tuple[int, int, float] | None = None
+        # New chunks recorded since the caller's last vectr_remember (or
+        # session start). Reset by note_remembered(). See
+        # EVICTION_REMEMBER_ESCALATION_CHUNKS.
+        self._chunks_since_remember: int = 0
+        # Tracked total-token count as of the caller's last vectr_remember (or
+        # 0 at session start). _tokens_since_remember() subtracts this baseline
+        # from the running total (UPG-EVICT-ESCALATION-GATE-TOO-LOW).
+        self._tokens_at_last_remember: int = 0
+        # True once note_remembered() has fired and no escalated (ACTION
+        # REQUIRED) directive has re-emitted since. While True, the NEXT
+        # eligible auto-hint renders the softer, non-imperative form instead
+        # of escalating immediately — repeating harsh wording on the very
+        # next search after compliance trains the caller to ignore it.
+        # Starts False: before the caller has ever called vectr_remember,
+        # auto_eviction_hint() escalates immediately as before.
+        self._soft_fire_pending: bool = False
+
+    def record(
+        self, file_path: str, lines: str, symbol_name: str, content: str,
+        chunk_id: str = "",
+    ) -> None:
+        """Record a chunk that was delivered to the LLM this session."""
+        # avoid duplicate tracking for the same file:lines
+        key = f"{file_path}:{lines}"
+        for i, c in enumerate(self._chunks):
+            if f"{c.file_path}:{c.lines}" == key:
+                # UPG-EVICT-RECENCY-DEDUP-BLIND: a repeat retrieval of the exact
+                # same chunk (the LLM re-running the same query and getting the
+                # same top hit) is the common case, and eviction_hint()'s
+                # most-recently-retrieved-first ordering keys recency off a
+                # file's position in self._chunks. Without this move, re-touching
+                # a file never refreshes that position, so the file the caller
+                # just retrieved again silently renders LAST instead of first.
+                # Move the existing entry to the end (fresh recency) without
+                # storing a duplicate or advancing any counter below — a dedup
+                # hit must be a no-op for token/chunk totals, only recency moves.
+                self._chunks.append(self._chunks.pop(i))
+                return
+        self._chunks.append(RetrievedChunk(
+            file_path=file_path,
+            lines=lines,
+            symbol_name=symbol_name,
+            content=content,
+            chunk_id=chunk_id,
+        ))
+        self._chunks_since_remember += 1
+
+    def record_results(self, results: list) -> None:
+        """Record a batch of SearchResult objects (from searcher.py)."""
+        for r in results:
+            self.record(
+                file_path=r.file_path,
+                lines=str(r.lines),
+                symbol_name=r.symbol_name or "",
+                content=r.content,
+                chunk_id=getattr(r, "chunk_id", "") or "",
+            )
+
+    def note_remembered(self) -> None:
+        """Call when the caller's vectr_remember succeeds this session.
+
+        Resets the chunks-since-last-remember counter and the tokens-since-
+        last-remember baseline so auto_eviction_hint()'s escalated directive
+        doesn't immediately re-fire on the very next retrieval
+        (UPG-REMEMBER-BANNER-FATIGUE, UPG-EVICT-ESCALATION-GATE-TOO-LOW).
+        Also arms the softer first-refire wording (see _soft_fire_pending).
+        Does not touch should_evict()'s own token/call/time state — a
+        vectr_remember doesn't reduce the actual context already retrieved.
+        """
+        self._chunks_since_remember = 0
+        self._tokens_at_last_remember = self.total_tokens_in_session()
+        self._soft_fire_pending = True
+
+    def _tokens_since_remember(self) -> int:
+        """Tokens tracked since the caller's last vectr_remember (or session
+        start, if never called). Companion to _chunks_since_remember —
+        see EVICTION_REMEMBER_ESCALATION_TOKENS."""
+        return self.total_tokens_in_session() - self._tokens_at_last_remember
+
+    def increment_tool_call(self) -> None:
+        """Increment the total MCP tool call counter for this session."""
+        self._tool_call_count += 1
+
+    def increment_retrieval_call(self) -> None:
+        """Increment the retrieval-specific call counter (search/locate/trace only)."""
+        self._retrieval_call_count += 1
+
+    def total_tokens_in_session(self) -> int:
+        return sum(c.estimated_tokens for c in self._chunks)
+
+    def should_evict(self) -> bool:
+        elapsed = time.time() - self._session_started_at
+        return (
+            self.total_tokens_in_session() >= self._threshold
+            or self._tool_call_count > self._tool_call_threshold
+            or self._retrieval_call_count > self._retrieval_call_threshold
+            or elapsed >= self._time_threshold_seconds
+        )
+
+    def _fresh_escalation(self) -> bool:
+        """True on the first auto-emit, then only after a MATERIAL increase since
+        the last one: another full token-threshold retrieved, `_rearm_retrieval_calls`
+        more retrieval calls, or another time-threshold window elapsed. Keeps the
+        per-response footer from repeating once pressure has already been flagged."""
+        if self._last_emit is None:
+            return True
+        tokens0, retr0, t0 = self._last_emit
+        return (
+            self.total_tokens_in_session() - tokens0 >= self._threshold
+            or self._retrieval_call_count - retr0 >= self._rearm_retrieval_calls
+            or (time.time() - t0) >= self._time_threshold_seconds
+        )
+
+    def _tokens_since_last_hint(self) -> int:
+        """Tokens accumulated since the last auto-hint emit (or session start)."""
+        tokens_at_last = self._last_emit[0] if self._last_emit is not None else 0
+        return self.total_tokens_in_session() - tokens_at_last
+
+    def auto_eviction_hint(self) -> str:
+        """Gated variant for the per-response footer (UPG-7.1 / UPG-11.15).
+
+        Emits the hint only when BOTH conditions hold:
+          1. Context pressure freshly escalates (UPG-7.1 — never on every response).
+          2. Accumulated retrieved tokens since the last hint (or session start)
+             have crossed _retrieved_token_gate (UPG-11.15 — suppresses bursts of
+             small-result searches that add negligible context pressure).
+
+        The explicit ``vectr_evict_hint`` tool and the ``/v1/evict`` endpoint
+        still use ``eviction_hint()`` (ungated): an explicit ask always answers.
+
+        UPG-REMEMBER-BANNER-FATIGUE / UPG-EVICT-ESCALATION-GATE-TOO-LOW: also
+        suppressed unless BOTH enough new chunks AND enough new tokens have
+        been retrieved since the caller's last vectr_remember (or session
+        start) — a single large search can trip a chunk-only gate in one
+        burst, so both must independently clear before the gate is satisfied
+        at all. Below that, MCP dispatch's own turn-count soft nudge (or
+        nothing) takes over instead of this method's wording.
+
+        Once the gate is satisfied, the FIRST eligible fire after a
+        vectr_remember renders the softer, non-imperative form (not ACTION
+        REQUIRED); only a second-or-later eligible fire without an
+        intervening vectr_remember escalates to the imperative directive
+        (UPG-EVICT-ESCALATION-GATE-TOO-LOW) — so compliance is never
+        answered with the same harsh wording on the very next response.
+        """
+        if not self.should_evict() or not self._fresh_escalation():
+            return ""
+        # UPG-11.15: even if should_evict() is true (e.g. retrieval_call_count
+        # tripped), don't emit if the retrieved content since the last hint is
+        # small.  The per-call-count trigger fires on the 2nd retrieval call,
+        # but three 15-line methods contribute only ~100–150 tokens — far below
+        # real context pressure.
+        if self._tokens_since_last_hint() < self._retrieved_token_gate:
+            return ""
+        if (
+            self._chunks_since_remember < self._remember_escalation_chunks
+            or self._tokens_since_remember() < self._remember_escalation_tokens
+        ):
+            return ""
+        escalate = not self._soft_fire_pending
+        hint = self.eviction_hint(escalated=escalate)
+        if hint:
+            self._last_emit = (
+                self.total_tokens_in_session(),
+                self._retrieval_call_count,
+                time.time(),
+            )
+            if not escalate:
+                # Soft form consumed — the next eligible fire (without an
+                # intervening vectr_remember) escalates.
+                self._soft_fire_pending = False
+        return hint
+
+    def eviction_hint(self, escalated: bool = True) -> str:
+        """
+        Return a message listing chunks vectr can re-retrieve in <50ms.
+        Always safe to call — returns an empty hint if nothing has been retrieved
+        and no time-based pressure exists.
+
+        escalated=True (the default, used by the explicit vectr_evict_hint tool
+        and the /v1/evict endpoint — an explicit ask always gets the full
+        directive) renders the imperative "ACTION REQUIRED" wording plus a
+        trailing machine-readable ``needs_remember: true`` line a harness can
+        key off without parsing prose. escalated=False renders the identical
+        factual content (files, token count, re-fetch keys) with softer,
+        non-imperative wording and omits the needs_remember line — used by
+        auto_eviction_hint() for the first eligible re-fire after a
+        vectr_remember (UPG-EVICT-ESCALATION-GATE-TOO-LOW).
+        """
+        if not self._chunks:
+            # No vectr-tracked chunks, but time pressure still warrants a nudge
+            elapsed = time.time() - self._session_started_at
+            if elapsed >= self._time_threshold_seconds:
+                if escalated:
+                    return (
+                        "─── ACTION REQUIRED ───\n"
+                        "Call vectr_remember(content, tags=[...]) NOW before continuing.\n"
+                        "Save: key type names, module paths, entry points, non-obvious patterns.\n"
+                        "Your synthesized understanding does not persist automatically.\n"
+                        "Call vectr_remember now, then continue your task.\n"
+                        "needs_remember: true"
+                    )
+                return (
+                    "Reminder: consider calling vectr_remember(content, tags=[...]) soon.\n"
+                    "Save: key type names, module paths, entry points, non-obvious patterns.\n"
+                    "Your synthesized understanding does not persist automatically."
+                )
+            return ""
+
+        total_tokens = self.total_tokens_in_session()
+        by_file: dict[str, list[RetrievedChunk]] = {}
+        for c in self._chunks:
+            by_file.setdefault(c.file_path, []).append(c)
+
+        # UPG-EVICT-HINT-RECENCY: order files most-recently-retrieved-first,
+        # not by first-ever-recorded order (a dict's insertion-order iteration
+        # was an accident of implementation, not a chosen policy). The
+        # caller's active working set — what it can most usefully drop from
+        # context and re-fetch on demand — is whatever it retrieved most
+        # recently, not whatever it happened to retrieve first this session.
+        # A file's recency is the position (in self._chunks) of the LAST
+        # chunk recorded for it; since record() appends monotonically, that
+        # position doubles as a recency sequence number. Sorting descending
+        # by this unique-per-file key is deterministic; the stable sort
+        # tie-breaks by insertion order in the (practically unreachable)
+        # case of equal keys.
+        last_seq: dict[str, int] = {}
+        for i, c in enumerate(self._chunks):
+            last_seq[c.file_path] = i
+        file_items = sorted(by_file.items(), key=lambda kv: last_seq[kv[0]], reverse=True)
+        shown = file_items[:5]
+        overflow = len(file_items) - len(shown)
+
+        if escalated:
+            lines = [
+                "─── ACTION REQUIRED ───",
+                "Call vectr_remember(content, tags=[...]) NOW before continuing.",
+                "Save: key type names, module paths, entry points, non-obvious patterns.",
+                "Your synthesized understanding does not persist automatically — the output",
+                "file captures findings, not the navigational path to reach them.",
+                "",
+            ]
+        else:
+            lines = [
+                "─── context recap ───",
+                "New content has been retrieved since your last vectr_remember. If you found",
+                "anything worth keeping — key type names, module paths, entry points, non-obvious",
+                "patterns — call vectr_remember(content, tags=[...]) now; otherwise continue.",
+                "",
+            ]
+        lines += [
+            f"Vectr has {len(self._chunks)} retrieved chunks (~{total_tokens} tokens)"
+            " fully indexed. Drop these chunks from context — each is re-fetchable"
+            " verbatim via vectr_fetch(ids=[...]) in <50ms."
+            " Your synthesized analysis (saved via vectr_remember) is retrievable via vectr_recall.",
+            "",
+            "Files below are listed most recently retrieved first:",
+        ]
+        for fpath, chunks in shown:
+            ranges = ", ".join(
+                f"lines {c.lines}" + (f" ({c.symbol_name})" if c.symbol_name else "")
+                for c in chunks
+            )
+            lines.append(f"  {fpath}  [{ranges}]")
+        if overflow:
+            lines.append(f"  ... and {overflow} more file(s). All retrievable via vectr_search('<description>').")
+
+        # UPG-EVICT-SESSION-SCOPE: list the exact re-fetch keys additively —
+        # only for chunks whose id is a known-good vectr_fetch key (never a
+        # guessed one), capped so the hint's own token cost stays bounded.
+        # UPG-EVICT-REFETCH-KEYS-STALE: self._chunks is oldest-first with
+        # re-touched chunks moved to the end, so take the suffix and reverse —
+        # most recently retrieved first, matching the file list's stated
+        # ordering above. The old prefix slice pinned the session's OLDEST
+        # chunks here forever, rendering the identical id list in every
+        # escalated banner regardless of what was retrieved since.
+        fetch_ids = [c.chunk_id for c in self._chunks if c.chunk_id][-EVICTION_HINT_MAX_IDS:][::-1]
+        if fetch_ids:
+            id_list = ", ".join(f'"{i}"' for i in fetch_ids)
+            lines += [
+                "",
+                f"Re-fetch keys: vectr_fetch(ids=[{id_list}]) restores these verbatim.",
+            ]
+
+        if escalated:
+            lines += [
+                "",
+                "Call vectr_remember now, then continue your task.",
+                "needs_remember: true",
+            ]
+        return "\n".join(lines)
+
+    def clear_session(self) -> None:
+        """Reset for a new session."""
+        self._chunks.clear()
+        self._tool_call_count = 0
+        self._retrieval_call_count = 0
+        self._session_started_at = time.time()
+        self._last_emit = None
+        self._chunks_since_remember = 0
+        self._tokens_at_last_remember = 0
+        self._soft_fire_pending = False
+
+    def as_chunk_dicts(self) -> list[dict]:
+        """Serialisable form for snapshot storage."""
+        return [
+            {
+                "file": c.file_path,
+                "lines": c.lines,
+                "symbol": c.symbol_name,
+                "content": c.content,
+                "chunk_id": c.chunk_id,
+            }
+            for c in self._chunks
+        ]

agent/identifier_hint.py

@@ -0,0 +1,68 @@
+"""
+Identifier-shape tokenizer for the vectr_search additive symbol-graph hint
+(UPG-QUERYTYPE-REROUTE).
+
+This replaces the deleted `agent/query_router.py` regex query-classification
+layer. That layer classified a query's INTENT via keyword/phrase lists
+(`\\boverride\\b`, `\\bsubclass(es)?\\b`, `\\b(dependenc(y|ies)|downstream|
+upstream)\\b`, ...) and, on a match, silently overrode the fingerprint-derived
+semantic weight and guessed a symbol to look up from the query's first
+non-stopword word — an innocent NL question about "dependencies" or
+"overriding a method" misrouted into a same-named-homonym symbol lookup with
+no ranking tie to the query at all.
+
+The replacement here does no intent classification whatsoever. It detects
+token SHAPE, not meaning: CamelCase, snake_case, and dotted/qualified
+(`Class.method`) forms are structural properties of an identifier regardless
+of what the surrounding sentence is about. A plain word is never treated as
+an identifier candidate even if it happens to also be a symbol name — the
+`identifier_hint_symbols()` caller (see `app/service.py`) additionally
+requires an EXACT symbol-graph match before anything is surfaced, so a
+shape-detected token that doesn't resolve produces no output at all.
+"""
+from __future__ import annotations
+
+import re
+
+# Combined, single regex — shape detection only, no word/keyword/phrase list:
+#   1. dotted/qualified form   e.g. "QuerySet.delete"
+#   2. CamelCase/PascalCase    e.g. "WorkspaceLock" (leading capital, an
+#                              internal lower-then-upper transition — this
+#                              excludes an ordinary capitalised sentence word
+#                              like "Where", which has no internal transition)
+#   3. lowerCamelCase          e.g. "scheduleUpdateOnFiber" (leading
+#                              lowercase, at least two lower/digit chars, then
+#                              an internal lower-then-upper transition — the
+#                              two-char minimum before the transition is what
+#                              excludes a single-letter-prefix brand word like
+#                              "iPhone"/"eBay", not shape detection of any
+#                              particular word)
+#   4. snake_case              e.g. "acquire_lock" (contains an underscore)
+# Order matters: the dotted alternative is tried first so "Class.method" is
+# captured as one token rather than splitting at the dot. ALLCAPS tokens
+# ("HTML", "API") match none of these — the CamelCase/lowerCamelCase
+# alternatives both require an internal LOWERCASE run before the case
+# transition, which an all-uppercase run never has.
+_IDENTIFIER_TOKEN_RE = re.compile(
+    r"[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*"
+    r"|[A-Z][a-z0-9]+[A-Z][A-Za-z0-9]*"
+    r"|[a-z][a-z0-9]+[A-Z][A-Za-z0-9]*"
+    r"|[A-Za-z_][A-Za-z0-9]*_[A-Za-z0-9_]*"
+)
+
+
+def extract_identifier_tokens(query: str) -> list[str]:
+    """Extract identifier-SHAPED tokens from a raw query string.
+
+    Returns candidates in order of first appearance, deduplicated. Empty for
+    a query built entirely of plain words (no CamelCase/snake_case/dotted
+    signal) — the common case for ordinary natural-language questions.
+    """
+    seen: set[str] = set()
+    tokens: list[str] = []
+    for m in _IDENTIFIER_TOKEN_RE.finditer(query):
+        tok = m.group(0)
+        if tok not in seen:
+            seen.add(tok)
+            tokens.append(tok)
+    return tokens

agent/indexer/__init__.py

@@ -0,0 +1,112 @@
+"""AST-aware code chunking and embedding pipeline.
+
+Package layout:
+  _constants.py — LANG_BY_EXT, EXCLUDED_DIRS, batch-size constants
+  _types.py     — CodeChunk dataclass, EmbedProvider protocol, embed provider classes
+  _chunking.py  — tree-sitter parsers, chunk collection, fallback window chunker
+  _core.py      — CodeIndexer orchestration class
+
+All names that existed on the flat agent/indexer.py module are re-exported here
+so every existing import site keeps working unchanged:
+  from agent.indexer import CodeIndexer        (watcher, searcher, service, tests)
+  from agent.indexer import chunk_file         (tests)
+  from agent.indexer import LANG_BY_EXT        (watcher, cartographer, symbol_graph)
+  from agent.indexer import EXCLUDED_DIRS      (watcher, cartographer)
+  from agent.indexer import get_embed_provider (tests — patched at this namespace)
+  from agent.indexer import c_symbol_name      (symbol_graph)
+  from agent.indexer import _get_parser        (symbol_graph)
+  from agent.indexer import _parser_language_for (symbol_graph — UPG-JSFLOW-SYMBOLS)
+"""
+from __future__ import annotations
+
+# Public constants
+from agent.indexer._constants import (
+    LANG_BY_EXT,
+    EXCLUDED_DIRS,
+    _FILE_BATCH_SIZE,
+    _EMBED_BATCH_SIZE,
+    _UPSERT_BATCH_SIZE,
+    _CHUNK_WORKERS,
+)
+
+# Public types / embed providers
+from agent.indexer._types import (
+    CodeChunk,
+    EmbedProvider,
+    LocalEmbedProvider,
+    VoyageEmbedProvider,
+    OpenAIEmbedProvider,
+    get_embed_provider,
+)
+
+# Config-sourced tunables re-exported so `import agent.indexer as m; m._MAX_CHUNK_LINES`
+# continues to work (test_config_loader asserts these are the same objects as config.py).
+from agent.config import (
+    INDEXING_MAX_CHUNK_LINES as _MAX_CHUNK_LINES,
+    INDEXING_CLASS_HEADER_LINES as _CLASS_HEADER_LINES,
+)
+
+# Public chunking symbols (tests import chunk_file; symbol_graph imports
+# _get_parser and c_symbol_name directly from agent.indexer)
+from agent.indexer._chunking import (
+    chunk_file,
+    c_symbol_name,
+    _get_parser,
+    _PARSER_CACHE,
+    _CLASS_NODE_TYPES,
+    _CHUNK_NODE_TYPES,
+    _SYMBOL_FIELD,
+    _C_TYPE_NAME_NODES,
+    _c_declarator_name,
+    _extract_symbol_name,
+    _get_leading_comments,
+    _collect_chunks_ast,
+    _fallback_window_chunks,
+    _chunk_markdown,
+    _postprocess_chunks,
+    is_flow_javascript,
+    _parser_language_for,
+)
+
+# Public indexer class
+from agent.indexer._core import CodeIndexer
+
+__all__ = [
+    # Config-sourced tunables (re-exported for test_config_loader)
+    "_MAX_CHUNK_LINES",
+    "_CLASS_HEADER_LINES",
+    # Constants
+    "LANG_BY_EXT",
+    "EXCLUDED_DIRS",
+    "_FILE_BATCH_SIZE",
+    "_EMBED_BATCH_SIZE",
+    "_UPSERT_BATCH_SIZE",
+    "_CHUNK_WORKERS",
+    # Types / providers
+    "CodeChunk",
+    "EmbedProvider",
+    "LocalEmbedProvider",
+    "VoyageEmbedProvider",
+    "OpenAIEmbedProvider",
+    "get_embed_provider",
+    # Chunking
+    "chunk_file",
+    "c_symbol_name",
+    "_get_parser",
+    "_PARSER_CACHE",
+    "_CLASS_NODE_TYPES",
+    "_CHUNK_NODE_TYPES",
+    "_SYMBOL_FIELD",
+    "_C_TYPE_NAME_NODES",
+    "_c_declarator_name",
+    "_extract_symbol_name",
+    "_get_leading_comments",
+    "_collect_chunks_ast",
+    "_fallback_window_chunks",
+    "_chunk_markdown",
+    "_postprocess_chunks",
+    "is_flow_javascript",
+    "_parser_language_for",
+    # Core
+    "CodeIndexer",
+]