vectr 1.0.0__py3-none-any.whl

agent/config.yaml

@@ -0,0 +1,1153 @@
+# vectr internal configuration — versioned in the repo.
+# All tunables that affect ranking behaviour live here so changes are auditable
+# via git history rather than buried in code.
+#
+# Do NOT set these via environment variables or per-user config files.
+# Runtime code reads this file via importlib.resources so it works for both
+# the repo-local interpreter and the pip-installed global binary.
+
+ranking:
+  quality_priors:
+    # Multipliers applied to the hybrid similarity score. 1.0 = neutral.
+    # Lower = de-ranked further. Applied in chunk_quality.quality_score().
+
+    # Bare stub chunks with almost no content (single-line import, lone brace, etc.)
+    trivial: 0.15
+
+    # Maximum number of non-blank lines a HTML/markup or plain-text chunk may contain
+    # and still be classified as trivial by is_trivial_chunk() (UPG-15.5).
+    # 1-line and 2-line test-fixture templates ("Logged out", "{{ form }}", top_level.txt)
+    # are trivial; any real doc prose chunk has many more lines than this.
+    # Must be a small integer (≥1) so that multi-line .txt/.rst documentation
+    # (Django docs/howto/*.txt, docs/topics/*.txt) are NOT classified trivial.
+    # Conservative default: 2 — catches single-line HTML templates and 1–2-line
+    # TXT fixtures without risk of demoting substantive documentation.
+    trivial_doc_max_lines: 2
+
+    # Re-export / import-only "navigational" chunks (no implementation substance)
+    navigational: 0.35
+
+    # UPG-NAV-OVERDEMOTE-DECL (F59): a bare-constructor-manifest chunk (UPG-
+    # PREFIX-COMPOSE's ``request_started = Signal()`` pattern) is ALSO the
+    # corpus-wide unique declaration site of each name it assigns. For a
+    # conceptual query ("signal dispatcher implementation") the manifest is
+    # correctly navigational-demoted to `navigational` above (F44/F53's
+    # re-export-stub-overrank fix). For a query that names one of the
+    # declared identifiers directly ("where is request_started signal
+    # defined") — a lexical match, gated on the query's own BM25 tokens, not
+    # a keyword list — the chunk IS the singular correct answer and the full
+    # navigational demotion buries it (F59: django/core/signals.py absent
+    # from top-25 despite being in the candidate pool). This softened value
+    # applies only in that lexically-gated case (chunk_quality.quality_score
+    # query_tokens argument); every other query for the same chunk still
+    # gets the full `navigational` demotion. Measured against the F59 offline
+    # replay (benchmarks/acceptance/product_cases.jsonl, django corpus,
+    # tmp/vectr-accept-django index): the pool-rank gap needs a value in this
+    # range to surface the chunk in top-10 without letting the still-nav-
+    # shaped chunk outrank undemoted real implementation code (kept < 1.0).
+    navigational_declaration_rescue: 0.75
+
+    # Markdown chunks that contain only headings (no prose or code body)
+    heading_only: 0.40
+
+    # Machine-generated files (migrations, protobuf output, build artifacts)
+    generated: 0.45
+
+    # vectr's own config files — we never want to surface our own internals
+    vectr_config: 0.10
+
+    # Test files when the query does not explicitly target tests. UPG-PREFIX-
+    # COMPOSE: lowered from 0.55 — once the query-prefix fix (UPG-ARCTIC-QUERY-
+    # PREFIX) changed dense pool composition, a test-file symbol whose name or
+    # docstring happens to restate the query in plain language (e.g. a helper
+    # class documented as "track threads and kwargs when signals are
+    # dispatched") could out-rank the canonical production symbol it merely
+    # name-echoes, because purpose_rank's textual-similarity boost (below) is
+    # otherwise blind to quality tier. 0.46 is the largest reduction that still
+    # satisfies test_ordering's invariant (test_deprioritised > generated=0.45,
+    # tests/test_chunk_quality.py::TestQualityScore::test_ordering) — this value
+    # only matters in combination with purpose_rank.lambda below (see there for
+    # the joint tuning rationale); it does not fix anything on its own.
+    test_deprioritised: 0.46
+
+    # UPG-TESTPATH-FRAMEWORK-MISCLASS (F58): is_test_file()'s path-segment
+    # heuristic (any "test"/"tests"/... directory component) cannot tell a
+    # disposable test module apart from a shipped testing-FRAMEWORK subpackage
+    # that happens to live at a test-named path (e.g. django/test/utils.py —
+    # a stable public API, not a throwaway test). Filtering by "called only
+    # from non-test files" was measured and rejected: a testing framework is,
+    # by definition, called almost exclusively from test code, so that signal
+    # never fires (0/175 measured non-test callers of override_settings on
+    # the django corpus) even though the file plainly IS shipped API surface.
+    # The signal that DOES discriminate cleanly is corpus-wide unambiguous
+    # caller BREADTH: symbol_graph.file_fan_in() counts, per file, the number
+    # of DISTINCT calling files across edges whose target symbol name
+    # resolves to exactly one defining file corpus-wide (excludes common
+    # same-leaf collisions like __init__/setUp that would otherwise dilute
+    # the count with unrelated files). Measured on the django corpus:
+    # django/test/utils.py=285, django/test/testcases.py=518,
+    # django/test/client.py=85, vs. the next-highest genuinely-disposable
+    # test file at 42 and a median near 0 — a wide, well-separated gap.
+    # A file at or above this threshold is exempted from the
+    # test_deprioritised multiplier above regardless of its path.
+    test_framework_fan_in_threshold: 60
+
+    # substantive documentation prose vs implementation code
+    doc_prose: 0.70
+
+    # bodies with very few meaningful lines
+    short_penalty: 0.80
+
+    # A private/internal symbol (single leading underscore, e.g. `_helper`,
+    # not a dunder like `__init__`) is a mild demotion vs. its public-API
+    # sibling. This is a language-general naming convention (Python's PEP 8
+    # "internal use" prefix; the same single-underscore-for-internal idiom
+    # appears in Go, JS/TS, and Rust codebases too), not a corpus- or query-
+    # specific rule, so it applies uniformly regardless of query text.
+    # Root cause it addresses: a keyword-dense private helper's raw text can
+    # score higher on cross-encoder + BM25 similarity than the public method
+    # a natural-language query is actually asking about, because the helper's
+    # body happens to restate more of the query's vocabulary literally (e.g.
+    # a queryset-filtering helper's body mentions "queryset"/"filter" several
+    # times while the public method it supports has a terse one-line body).
+    # The importance/purpose priors (ranking.importance_prior, ranking.
+    # purpose_rank) already favor the public symbol's file/class, but a
+    # sizeable base-rerank gap from the raw-text-similarity effect above can
+    # still outweigh them; this prior corrects the imbalance at its source
+    # (django/db/models/query.py QuerySet.filter vs. the private
+    # _filter_prefetch_queryset helper in fields/related_descriptors.py is
+    # the measured witness case, UPG-16.1/F30). Mild (comparable to
+    # short_penalty) because a private helper is still legitimate,
+    # sometimes-wanted code — just usually not the intended answer to a
+    # concept-level query naming the public operation.
+    private_symbol_deprioritised: 0.80
+
+    # Maximum number of attribute-assignment body lines for an attribute-only
+    # class body to be classified as trivial by is_trivial_chunk() (UPG-15.9 / F25).
+    # A ``class Meta:`` inner stub with ≤ this many attribute-assignment body lines
+    # and NO method definitions / control flow is trivial — it is a configuration
+    # stub, not a real class definition.  Django test files have 200+ such 3-line
+    # stubs (class Meta: / model = X / fields = '__all__') that flood doc-intent
+    # queries.  Real small library classes with more attributes or any method body
+    # are unaffected.  Conservative default 3: catches the dominant Meta stub
+    # pattern without risk of demoting real dataclass-style classes.
+    trivial_attr_class_max_attrs: 3
+
+  importance_prior:
+    # ARCH-1b: file-level PageRank importance (computed at index time by ARCH-1a,
+    # stored in the symbol_importance table) is blended into the FINAL search sort
+    # as a relevance-gated multiplicative prior:
+    #     final_score = base_rerank_score * quality_score * (1 + lambda * importance)
+    # where importance ∈ [0,1] is the normalized file-level PageRank of the chunk's
+    # file (0 when unknown). The multiply by base_rerank_score keeps it relevance-
+    # gated — an irrelevant high-importance file (base ≈ 0) is not lifted. A global
+    # standing prior (canonical = most-referenced), NOT a query-keyword heuristic.
+    # lambda=0 disables it (behaviour identical to pre-ARCH-1b). Conservative default
+    # 0.25: reorders near-ties toward canonical files without overriding clear
+    # relevance. Live F22/F23 tuning is tracked in tasks.md ARCH-1b.
+    lambda: 0.25
+
+  class_importance:
+    # ARCH-2: class/symbol-name "canonical = most-referenced" importance
+    # (whole-word reference frequency of the name across the corpus, computed
+    # at index time by SymbolGraph._compute_and_store_class_importance and
+    # stored in the class_importance table) is blended into the FINAL search
+    # sort as a second relevance-gated multiplicative prior, alongside
+    # ARCH-1b's file-level prior:
+    #     final_score = base_rerank_score * quality_score
+    #                    * (1 + lambda_file * file_importance)
+    #                    * (1 + lambda_class * class_importance)
+    # where class_importance ∈ [0,1] is the normalized reference frequency of
+    # the relevant name. This is the lever for same-leaf collisions (two
+    # unrelated classes that both define a method with the same name; a
+    # canonical type's own definition chunk crowded by a same-file, narrower
+    # sibling type; a corpus-central module-level function crowded by a
+    # rarely-referenced sibling function — UPG-SIBLING-TYPEDEF-CROWDING) that
+    # file-level importance cannot discriminate — a symbol's own body often IS
+    # the file, so file-level PageRank has no separating signal.
+    #
+    # UPG-SIBLING-TYPEDEF-CROWDING extended attribution beyond methods: a
+    # METHOD chunk still uses its owning class's name (unchanged); a
+    # TYPE-DEFINITION chunk (struct/enum/trait/class/interface/typedef) or a
+    # MODULE-LEVEL FUNCTION chunk is instead attributed to its OWN name —
+    # previously stuck at class_importance=0 forever since neither has an
+    # owning-class context to key off. See agent/searcher.py
+    # (is_type_definition_chunk / is_module_level_function_chunk gated
+    # lookup).
+    #
+    # lambda=0 disables it (behaviour identical to pre-ARCH-2). Conservative
+    # default 0.25, matching ARCH-1b's default: reorders same-leaf look-alikes
+    # toward the canonical symbol without overriding clear relevance — the
+    # multiplicative gate bounds the factor to [1, 1+lambda] regardless of how
+    # skewed the importance map is, so a modest lambda here cannot let even a
+    # maximum-importance rival overturn a clear cross-encoder relevance lead.
+    # Live F22/F23 tuning is tracked in tasks.md ARCH-2.
+    lambda: 0.25
+
+  purpose_rank:
+    # ARCH-4b: carries the ARCH-4 dual-vector purpose similarity (STEP-0/ARCH-4
+    # gated it into POOL ENTRY only) into the FINAL search sort as a third
+    # relevance-gated multiplicative prior, alongside ARCH-1b's file-level and
+    # ARCH-2's class-level priors:
+    #     final_score = base_rerank_score * quality_score
+    #                    * (1 + lambda_file * file_importance)
+    #                    * (1 + lambda_class * class_importance)
+    #                    * (1 + lambda_purpose * purpose_sim)
+    # where purpose_sim ∈ [0,1] is the chunk's own body-vs-purpose-vector cosine
+    # similarity to the query (0 when the chunk has no purpose vector, e.g. a
+    # doc/config chunk, or dual_vector is disabled). Without this, a symbol whose
+    # signature+docstring is the single best purpose match in the corpus can still
+    # be buried under its own subclasses/near-duplicates in the final MCP ranking,
+    # because the cross-encoder rerank that dominates base_rerank_score only sees
+    # BODY text and has no visibility into the purpose signal that got the chunk
+    # into the pool in the first place. lambda=0 disables it (behaviour identical
+    # to pre-ARCH-4b). Default 0.9 (raised from ARCH-4b's original 0.5 by
+    # UPG-PREFIX-COMPOSE, see below), higher than ARCH-1b/ARCH-2's 0.25: those
+    # two priors are typically fed near-binary importance scores (0 or ~1), so a
+    # one-rank near-tie gap clears at 0.25; purpose_sim is a continuous cosine
+    # similarity that rarely reaches 1.0 even for a strong match and must also
+    # recover deeper rerank-pool burial (observed: purpose-rank-1 chunk landing
+    # at final rank 16 in a ~60-candidate pool) — algebra on the multiplicative
+    # gate shows 0.25 only clears a 1-of-10-rank gap, not a 15-of-60-rank gap.
+    # See TestPurposeRankPrior in tests/test_indexer_searcher.py for the worked
+    # cases.
+    #
+    # UPG-PREFIX-COMPOSE: purpose_sim measures textual similarity between the
+    # query and a chunk's own qualified-name+docstring independent of the
+    # chunk's quality tier, so a quality-demoted chunk (a test helper whose
+    # docstring happens to restate the query in plain language) can carry a
+    # HIGHER purpose_sim than the canonical production symbol it name-echoes —
+    # letting a shallow textual echo outrank the real implementation no matter
+    # how large lambda is scaled, since raising lambda amplifies the demoted
+    # chunk's edge by the same factor (a case witnessed on the django corpus:
+    # a test-only helper class's docstring out-scored the production Signal
+    # class's own docstring on raw cosine similarity). Raising this lambda
+    # alone (against the un-weighted prior) to clear that gap also
+    # disproportionately boosts every OTHER demoted-but-purpose-matching chunk
+    # against non-symbol content that has no purpose vector at all (prose/doc
+    # chunks default purpose_sim to 0 — see above), which was observed to
+    # invert an unrelated doc-vs-test-code ranking on the same corpus. The
+    # searcher now weights this factor by the chunk's own quality_score
+    # (1 + lambda * purpose_sim * quality_score, in
+    # agent/searcher.py._apply_quality_and_dedup) so a demoted chunk's textual
+    # echo can no longer buy back more rank than an undemoted chunk's smaller
+    # one, while an undemoted (quality=1.0) candidate keeps the full boost.
+    # With that weighting, lambda=0.9 (paired with test_deprioritised=0.46
+    # above) is stable across a lambda range of roughly [0.7, 1.1] on the
+    # verified case above — not a knife-edge value — and the full django
+    # offline acceptance replay (benchmarks/acceptance/product_cases.jsonl)
+    # shows zero other case flipped by this change.
+    lambda: 0.9
+
+  type_def_prior:
+    # UPG-RUST-DEF-EVICTION / DEF-B: a fourth relevance-gated multiplicative
+    # prior, same shape as file_importance/class_importance/purpose_rank
+    # above:
+    #     final_score = base_rerank_score * quality_score
+    #                    * (1 + lambda_file * file_importance)
+    #                    * (1 + lambda_class * class_importance)
+    #                    * (1 + lambda_purpose * purpose_sim * quality_score)
+    #                    * (1 + lambda_def * is_type_definition)
+    # where is_type_definition is 1 when the chunk's own node_type is a TYPE
+    # DEFINITION (struct/enum/trait/class/interface — see
+    # chunk_quality.is_type_definition_chunk), else 0. Cross-language witness:
+    # a struct/type's canonical definition chunk repeatedly loses to same-name
+    # test code and usage sites at comparable rerank scores because the
+    # cross-encoder has no visibility into "this chunk IS the definition" —
+    # only the AST does. lambda=0 disables it (pre-DEF-B behaviour). Default
+    # 0.15, smaller than class_importance/file_importance's 0.25: this prior
+    # fires on every type-def chunk unconditionally (not gated by corpus-wide
+    # reference frequency), so a larger lambda would systematically favour
+    # definitions over well-matched usage sites even when the usage IS the
+    # better answer to the query.
+    lambda: 0.15
+
+  docstring_dedup:
+    # UPG-RUST-DEF-EVICTION / DEF-C: a second, independent dedup key
+    # (alongside the existing byte-normalized full-content key, UPG-2.2)
+    # keyed on a chunk's normalized LEADING docstring/comment block only.
+    # Near-duplicate boilerplate headers (the same rustdoc/JSDoc/docstring
+    # copy-pasted across several thin wrapper/test chunks with otherwise
+    # different bodies) evade the full-content key but still bury the
+    # canonical definition under several near-identical-looking results.
+    # `lines` bounds how many leading doc lines are compared (matches the
+    # dual-vector purpose-text docstring cap's spirit — a header is a header,
+    # extra lines rarely add distinguishing signal). `min_chars` is a floor
+    # on the normalized header's length below which a chunk is NEVER folded
+    # into this key (chunks with a trivial/near-empty leading header, or none
+    # at all, keep every occurrence — collapsing on near-nothing would fold
+    # together unrelated chunks that merely share a blank or 1-word header).
+    lines: 3
+    min_chars: 20
+
+  locate_ranking:
+    # UPG-15.10: scope-depth + line-span signals for locate ranking.
+    # These penalise class/function definitions that are buried inside function
+    # bodies (inner test-scope defs) and reward large, substantive definitions.
+
+    # Line-span threshold (in lines) above which a symbol definition is considered
+    # "large" — typically a canonical library class or function.  Symbols with
+    # end_line - start_line >= this value get the best span bucket (0).
+    # Django's Model base class has ~1400 lines; real functions are ≥10 lines.
+    # Test-inner stubs are typically 2–5 lines.
+    large_span_threshold: 50
+
+    # Line-span threshold below which a symbol definition is considered "tiny" —
+    # a stub or inner test class.  Symbols with span < this value get the worst
+    # span bucket (2); spans in [small, large) get bucket 1.
+    small_span_threshold: 10
+
+  rerank:
+    # Cross-encoder reranker model (HuggingFace id). The VECTR_RERANKER_MODEL
+    # env var overrides this key (test fixtures rely on that); an empty value
+    # disables reranking entirely. Swapping this model needs no reindex —
+    # the reranker scores (query, chunk) pairs at query time only.
+    model: "BAAI/bge-reranker-base"
+
+    # rerank this many hybrid candidates before trimming to n_results
+    top_k: 40
+
+    # When no language filter is set, doc prose dominates the shallow hybrid pool and
+    # real implementation chunks fall outside it (audit: extractor.py / chunk_file never
+    # fetched). Fetch a deeper pool in that case so the quality prior has code to surface.
+    top_k_unfiltered: 60
+
+    # Over-fetch depth for the pool-entry trivial filter (UPG-15.7).
+    # Before trimming to top_k_unfiltered, the hybrid retrieval fetches this many raw
+    # candidates, drops any that are trivial (is_trivial_chunk == True) and not
+    # forced-inclusion candidates, THEN trims to top_k_unfiltered.  This ensures the
+    # rerank pool of ~60 is filled with real code even on fixture-heavy repos
+    # (a large web codebase can carry a hundred-plus 1–2-line HTML/TXT template
+    # chunks that otherwise crowd out code).
+    # Rule: pre_filter_fetch_k must be >= top_k_unfiltered.  ~200 covers such
+    # fixture blocks while remaining a tiny fraction of a 40k-chunk corpus.
+    # The cross-encoder reranker only sees ~top_k_unfiltered (~60) candidates, so latency
+    # is unaffected by this wider initial fetch.
+    pre_filter_fetch_k: 200
+
+  notfound_floor:
+    # UPG-NOTFOUND-FLOOR (F46): the score shown to the caller is the FINAL
+    # rank-based composite (searcher._apply_quality_and_dedup: base = 1 -
+    # rank/n, then quality/importance multipliers) — it is re-derived from
+    # each query's own candidate ORDER, so the top result of any query always
+    # displays close to 1.0 even when every candidate is irrelevant. A signal
+    # independent of that per-query rescaling is needed to tell the caller
+    # the whole result set may be a guess.
+    #
+    # UPG-NOTFOUND-FLOOR-2: the first version of this signal gated on the raw
+    # pre-rerank vector-search cosine similarity (the one score in the
+    # pipeline NOT re-normalized per query) against an absolute constant
+    # (dense_score_floor). Measured against the production embedder on a
+    # large real corpus, that constant never fires: an absent-topic query's
+    # best pool cosine and a genuinely on-topic query's best pool cosine
+    # overlap the same ~0.60-0.86 band (one nonsense string measured HIGHER
+    # than several real on-topic queries) — every sentence embedding this
+    # model produces lands close to the corpus centroid regardless of
+    # relevance, so no absolute cosine constant can separate the two
+    # classes. (One parenthetical data point from the django benchmark
+    # corpus: the query "CORS handling implementation" — a protocol
+    # Django's own source never touches — still measured a pool-max cosine
+    # of 0.75, comfortably inside the on-topic band.) The defect was the
+    # signal, not the threshold.
+    #
+    # The replacement is distributional rather than absolute: does every
+    # content word in the query occur, even once, anywhere in the corpus's
+    # indexed vocabulary? A query naming a concept the codebase genuinely
+    # does not contain is built from at least one word that has literally
+    # zero document frequency across the whole corpus (not just the
+    # query's fetched candidate pool); a query about something the
+    # codebase does contain, however badly it is then ranked, is built
+    # entirely from words that really do appear in it. This generalizes
+    # past absolute-cosine floors to any embedder vectr ships, because it
+    # never looks at a cosine value at all — only at whether the corpus's
+    # own vocabulary contains the query's words.
+    enabled: true
+
+    # A query token shorter than this is excluded from the zero-document-
+    # frequency check — very short tokens (2-letter abbreviations, stray
+    # punctuation fragments) are too ambiguous to serve as a reliable
+    # vocabulary anchor in either direction.
+    min_content_token_length: 3
+
+    # Generic English/query-scaffolding words excluded from the zero-
+    # document-frequency check. These are near-universal across any real
+    # codebase's comments and docstrings (so they would essentially never
+    # have zero document frequency) — excluding them only avoids wasted
+    # per-query token lookups, it does not change which queries get
+    # flagged.
+    stopwords:
+      - the
+      - a
+      - an
+      - of
+      - to
+      - in
+      # Quoted: bare "on"/"off"/"yes"/"no" are YAML 1.1 boolean literals — an
+      # unquoted "on" here is parsed as the Python bool True, not the string
+      # "on", corrupting this list (agent/config.py loads with pyyaml's
+      # default YAML 1.1 resolver).
+      - "on"
+      - for
+      - and
+      - or
+      - is
+      - are
+      - how
+      - what
+      - does
+      - do
+      - implementation
+      - code
+      - framework
+      - using
+      - use
+
+    # Minimum number of query content tokens with zero corpus-wide document
+    # frequency required to flag the result set low_confidence. 1 (default)
+    # flags as soon as a single content word never appears anywhere in the
+    # indexed corpus. Set arbitrarily high (or set enabled: false) to
+    # disable — the floor never fires and low_confidence is always false,
+    # i.e. an exact no-op restoring pre-UPG-NOTFOUND-FLOOR behaviour.
+    min_zero_df_tokens: 1
+
+    # UPG-SCORE-DISPLAY-FLAT: a second, independent low-confidence sub-signal —
+    # the top result's own displayed relevance is below this absolute floor.
+    # Gated on the cross-encoder relevance score specifically (ce_relevance),
+    # never on the raw dense-cosine fallback: the UPG-NOTFOUND-FLOOR-2
+    # measurement above already showed a bi-encoder cosine cannot separate
+    # absent-topic from on-topic queries, so flooring on it here would
+    # reintroduce that same defect. A cross-encoder score is a different,
+    # calibrated relevance judgment (trained to predict query-doc relevance
+    # directly), so it is safe to floor on. A no-op (this sub-signal never
+    # fires) whenever reranking didn't run (rerank=False, or the reranker
+    # model failed to load) — low_confidence then falls back to the
+    # zero-document-frequency check above alone.
+    min_top_relevance: 0.30
+
+    # Text prepended to the MCP vectr_search response when the floor fires.
+    # Results are still shown in full below it — the caller LLM may still
+    # salvage a lead; this only adds a signal it currently has no way to see.
+    banner: "No strong match for this query — the results below scored low on absolute relevance and may be unrelated. Try vectr_locate with the exact symbol name, rephrase the query, or fall back to grep/reading the file directly."
+
+    # UPG-CLI-SEARCH-FLOOR: separate CLI-surface banner, printed by `vectr
+    # search` when SearchResponse.low_confidence is true. The MCP banner
+    # above names `vectr_locate` — meaningless at a shell prompt, since no
+    # `vectr locate` subcommand exists. Same signal, phrasing for a human
+    # terminal reader instead of the editor's LLM.
+    banner_cli: "No strong match for this query — the results below scored low on absolute relevance and may be unrelated. Try an exact symbol name, rephrase the query, or fall back to grep/reading the file directly."
+
+strategy:
+  # Fallback hybrid-search weights used before the first index-time codebase
+  # fingerprint has run (agent.strategy_selector.select_strategy). Once a
+  # workspace is indexed these are superseded by the fingerprint-derived
+  # RetrievalStrategy; until then `status` and `search` use this pair so
+  # retrieval behaviour — and its reporting — is deterministic from the very
+  # first call rather than silently absent (UPG-8.2). Must sum to 1.0.
+  default_semantic_weight: 0.70
+  default_bm25_weight: 0.30
+retrieval:
+  dual_vector:
+    # ARCH-4: per-symbol dual-vector pool entry. STEP-0 spike proved a mechanical
+    # implementation body dilutes the intent-bearing signature/docstring tokens
+    # when mean-pooled into a single embedding — a documented method can miss
+    # dense pool entry entirely even though its own docstring paraphrases the
+    # query. Fix: embed a second, body-stripped "purpose" text (qualified
+    # signature + docstring/leading comment) per symbol-bearing chunk and query
+    # both vector spaces; the two are merged uniformly for every query, never
+    # gated on query content. Non-symbol chunks (docs/markdown/config) are
+    # unaffected — no purpose vector is stored for them.
+    enabled: true
+
+    # How a chunk's two similarity scores (body, purpose) combine into the one
+    # dense score consumed by pool entry and the hybrid merge:
+    #   "max"      — dense_score = max(body_sim, purpose_sim). A chunk enters the
+    #                pool if EITHER vector matches; never scores worse than a
+    #                body-only search would. This is the evidence-gated choice:
+    #                the spike showed purpose_sim clears pool-entry threshold
+    #                while body_sim does not (0.601 vs 0.706 for one phrasing),
+    #                so averaging the two would still leave the chunk short —
+    #                only a non-averaging max recovers pool entry.
+    #   "weighted" — dense_score = (1 - blend_weight) * body_sim + blend_weight *
+    #                purpose_sim. Kept as an evaluated alternative for future
+    #                tuning; not the default because averaging re-introduces the
+    #                dilution the mechanism exists to defeat.
+    blend_mode: "max"
+
+    # Purpose-vector weight when blend_mode is "weighted" (ignored under "max").
+    blend_weight: 0.5
+
+    # Maximum lines captured as a chunk's "signature" when distilling the
+    # purpose text — the declaration line(s) up to (and including) the line that
+    # opens the body (python ':' / brace-block '{'). Bounds pathologically long
+    # multi-line parameter lists.
+    max_signature_lines: 8
+
+    # Maximum lines captured from a Python docstring (or a non-Python leading
+    # doc-comment block) when building the purpose text.
+    max_docstring_lines: 12
+
+    # Maximum characters kept from the captured docstring/leading-comment text —
+    # a hard cap so a very long module-style docstring doesn't itself dilute the
+    # purpose embedding the same way a long body would.
+    max_docstring_chars: 600
+
+search:
+  identifier_hint:
+    # UPG-QUERYTYPE-REROUTE: additive, high-precision symbol-graph hint
+    # appended below vectr_search's L3 results. Replaces the deleted
+    # agent/query_router.py regex query-classification layer, which
+    # misrouted innocent NL questions containing bare nouns like
+    # "dependency"/"override"/"subclass" into a CALL_GRAPH intent — silently
+    # overriding the fingerprint-derived semantic weight and guessing a
+    # same-named homonym via the query's first non-stopword word, with no
+    # ranking tie to the query at all. This mechanism does no intent
+    # classification: it tokenizes the RAW query for identifier-SHAPED
+    # tokens (CamelCase, snake_case, dotted Class.method — a structural
+    # transform, never a keyword/phrase match) and appends a section only
+    # when at least one token resolves to an EXACT symbol-graph hit (no
+    # fuzzy/prefix/substring). A query with no identifier-shaped token, or
+    # one whose plain words merely coincide with a symbol name, gets no
+    # section and no weight override.
+    enabled: true
+
+    # Maximum number of distinct identifier-shaped tokens (query order,
+    # deduplicated) attempted against the symbol graph per search.
+    max_identifiers: 2
+
+    # Maximum resolved symbol locations shown per identifier.
+    max_locations: 3
+
+    # UPG-NEARMISS-SYMBOL-NAMES: when an identifier-shaped token fails EXACT
+    # resolution, additively surface the nearest existing symbol NAMES so the
+    # caller LLM learns it misremembered a name rather than seeing nothing.
+    # Sourced entirely from the symbol graph's own deterministic partial-match
+    # machinery (locate_l2's non-exact strategies, plus one bounded prefix-
+    # containment check — see SymbolGraph.nearest_symbol_names) — never a
+    # semantic guess, and always labeled inexact in the rendered section.
+    nearmiss_enabled: true
+
+    # Maximum distinct near-miss symbol names shown, TOTAL across the whole
+    # response (not per token) — keeps the addition small even when more
+    # than one identifier-shaped token in the query fails to resolve exactly.
+    nearmiss_max: 3
+
+    # Minimum length (characters) an existing symbol's name must have to be
+    # offered as a prefix-containment near-miss candidate (the token "starts
+    # with" that shorter, real symbol name). Prevents a short, generic symbol
+    # name (e.g. a 2-3 char helper) from spuriously "matching" as a prefix of
+    # many unrelated tokens.
+    nearmiss_min_prefix_len: 6
+
+indexing:
+  # hard cap — prevents single huge chunks diluting embeddings
+  max_chunk_lines: 150
+
+  # lines kept for class-level chunk (sig + docstring + attrs)
+  class_header_lines: 40
+
+  # Build-artifact directories excluded from indexing at file-walk time (UPG-15.9).
+  # Any path component that ENDS WITH one of these suffixes is treated as a build
+  # artifact directory and every file inside it is excluded.  This catches Python
+  # egg-info directories (e.g. Django.egg-info/, mypackage.egg-info/) whose
+  # SOURCES.txt / PKG-INFO / *.txt files are plain file-path listings with no
+  # educational content but high BM25 IDF on module/command identifiers.
+  # Rule: suffix match on each path part — "Django.egg-info" ends with ".egg-info".
+  # Do NOT widen to cover real documentation dirs (docs/, howto/) — only build
+  # artifacts whose entire directory is machine-generated have no index value.
+  build_artifact_dir_suffixes:
+    - ".egg-info"
+    - ".dist-info"
+
+  # UPG-JSFLOW-SYMBOLS: Flow-typed `.js` detection. tree-sitter-javascript
+  # treats Flow type syntax (`@flow` pragma, `import type {...}`, `: Type`
+  # annotations, generics) as ERROR nodes and desyncs the symbol walk —
+  # canonical functions go missing and keyword tokens get misattributed as
+  # symbol names. Files that signal Flow are parsed with the typescript/tsx
+  # grammar instead (which understands type annotations); plain `.js` is
+  # unaffected. Detection is a cheap header scan (first `scan_head_bytes`
+  # bytes), done once per file parse — never per AST node.
+  flow_detection:
+    # Bytes scanned from the start of the file when looking for a Flow signal.
+    scan_head_bytes: 2000
+    # Primary signal: the `@flow` pragma, conventionally in the file's leading comment.
+    pragma: "@flow"
+    # Secondary signal: Flow-only import syntax, checked within the same head window.
+    secondary_markers:
+      - "import type "
+      - "export type "
+
+output:
+  # Number of lines returned as a snippet with each symbol location.
+  # Enough for the AI to understand signature + first few lines of the body.
+  snippet_lines: 12
+
+behavior:
+  remember_nudge:
+    # After this many vectr tool calls without a vectr_remember, the next
+    # vectr_search / vectr_locate / vectr_trace response appends an imperative
+    # reminder. The counter resets on every vectr_remember call.
+    threshold: 10
+
+    # After the threshold fires, re-fires every this many calls so a single
+    # dismissal cannot silence it for the rest of the session.
+    cooldown: 5
+
+  eviction:
+    # Minimum accumulated retrieved-token estimate (since the last auto-eviction
+    # hint or session start) required before auto_eviction_hint() will emit the
+    # ACTION REQUIRED block.  Gates on real context pressure rather than raw
+    # call count — a burst of tiny searches (7-15 line methods, ~30-60 tokens
+    # each) does not trigger the hint until meaningful content has been retrieved.
+    # Token estimate: len(content) // 4.  At ~100 chars/line, 4000 tokens ≈ 10
+    # small methods or 2-3 medium functions.  The explicit vectr_evict_hint tool
+    # and /v1/evict endpoint remain ungated.
+    retrieved_token_gate: 4000
+
+    # UPG-EVICT-SESSION-SCOPE: maximum number of chunk ids listed as re-fetch
+    # keys (`vectr_fetch(ids=[...])`) in the eviction_hint() render. Bounds the
+    # hint's own token cost — a session with hundreds of retrieved chunks still
+    # gets a short, actionable list rather than every id it has ever seen.
+    hint_max_ids: 5
+
+    # UPG-EVICT-SESSION-SCOPE: each MCP session gets its own EvictionAdvisor so
+    # one session never sees chunks retrieved by another. Bounds the daemon-
+    # wide registry of per-session advisors — oldest session is dropped (LRU)
+    # once this many concurrent sessions have been tracked, so a long-running
+    # daemon serving many short-lived sessions can't grow this without bound.
+    max_tracked_sessions: 50
+
+    # UPG-REMEMBER-BANNER-FATIGUE: auto_eviction_hint()'s escalated
+    # "ACTION REQUIRED: call vectr_remember NOW" directive only fires once
+    # this many NEW chunks have been retrieved since the caller's last
+    # vectr_remember call (or since session start, if it has never called
+    # vectr_remember). Right after a vectr_remember, repeating the same
+    # urgent directive on the very next retrieval trains the caller to
+    # ignore it — the counter gives it a chance to actually comply before
+    # escalating again. Below this count, MCP dispatch's existing
+    # turn-count soft nudge (behavior.remember_nudge, or nothing) takes
+    # over instead; see _should_nudge_remember/_remember_nudge_text.
+    # Set in the same order of magnitude as rearm_retrieval_calls (4) above.
+    remember_escalation_chunks: 3
+
+    # UPG-EVICT-ESCALATION-GATE-TOO-LOW: companion gate to remember_escalation_chunks,
+    # required in ADDITION to it (both must hold). remember_escalation_chunks alone is
+    # smaller than a single search's default n_results (5), so on large-chunk corpora
+    # one vectr_search call can add >4000 tokens in a single burst — tripping both the
+    # chunk-count gate AND the existing retrieved_token_gate at once, right after the
+    # caller just complied with vectr_remember. Gating on accumulated TOKENS since the
+    # last vectr_remember (not just since the last hint) means a single typical search
+    # (~4000 tokens on a large-chunk corpus, per retrieved_token_gate's own comment)
+    # cannot cross this threshold alone — it takes roughly two such searches, giving the
+    # caller a real chance to act on vectr_remember before repeat pressure builds back up.
+    remember_escalation_tokens: 8000
+
+  boot:
+    # SessionStart boot recall (UPG-9.2): unconditional directive notes are
+    # capped defensively so a workspace with unusually many standing rules
+    # doesn't inject an unbounded block every session. Directives are
+    # ordered oldest-first (standing rules stay in a stable order).
+    max_directive_notes: 100
+
+    # UPG-TASK-NOTE-INJECTION-RECENCY: kind=task notes are current-work
+    # state, not relevance-ranked learnings — they are ordered strictly
+    # newest-first (ignoring author_trust_score/decay_score) and capped to
+    # this many so the boot set surfaces only the freshest checkpoints, not
+    # the full task history.
+    max_task_notes: 5
+
+  ingest_traces:
+    # Maximum number of "caller/callee not found in the indexed symbol graph"
+    # example strings surfaced in the vectr_ingest_traces response text (UPG-7.3).
+    # The edge is still ingested — an unresolved name is common and expected
+    # (external library, dynamic dispatch target added at runtime, or a symbol
+    # kind the static extractor doesn't capture) — this only bounds how many
+    # examples are echoed back so a large trace batch doesn't flood the response.
+    max_unresolved_examples: 10
+
+  # UPG-TRACE-GRAPH-INCOMPLETE (F40-class, reproduced on vectr_trace): the MCP
+  # schema's required parameter is "name", but every symbol-name-bearing tool
+  # description has read like a positional example, training callers to guess
+  # a different key. Rather than rely on descriptions alone, the dispatch
+  # layer accepts these as drop-in aliases for "name" on vectr_locate and
+  # vectr_trace — a call using any of them succeeds instead of erroring.
+  symbol_name_param_aliases:
+    - symbol
+    - symbol_name
+
+symbol_graph:
+  # UPG-JSFLOW-SYMBOLS: language keywords that must never be minted as a
+  # symbol name or call-edge target. A desynced parse (e.g. Flow syntax
+  # hitting the plain javascript grammar, or any other ERROR-node recovery)
+  # can misattribute a keyword token as an identifier — these sets are the
+  # global reject-list, checked alongside the per-node ERROR-ancestor guard.
+  # Grouped per language (most C-descended languages share a keyword core,
+  # but each set is kept explicit rather than merged so a language's grammar
+  # can evolve independently).
+  reserved_keywords:
+    python:
+      - if
+      - elif
+      - else
+      - for
+      - while
+      - return
+      - def
+      - class
+      - import
+      - from
+      - try
+      - except
+      - finally
+      - with
+      - as
+      - pass
+      - break
+      - continue
+      - lambda
+      - yield
+      - global
+      - nonlocal
+      - assert
+      - raise
+      - del
+      - in
+      - is
+      - not
+      - and
+      - or
+      - async
+      - await
+      - None
+      - True
+      - False
+      # Not a real keyword, but a pre-existing noise guard: `print(...)` call
+      # sites were already suppressed as call-edge targets before this list
+      # existed — kept here so the exclusion stays config-driven.
+      - print
+    javascript:
+      - if
+      - else
+      - for
+      - while
+      - do
+      - switch
+      - case
+      - default
+      - break
+      - continue
+      - return
+      - function
+      - class
+      - const
+      - let
+      - var
+      - new
+      - typeof
+      - instanceof
+      - in
+      - of
+      - void
+      - delete
+      - yield
+      - async
+      - await
+      - export
+      - import
+      - extends
+      - super
+      - this
+      - static
+      - get
+      - set
+      - try
+      - catch
+      - finally
+      - throw
+    typescript:
+      - if
+      - else
+      - for
+      - while
+      - do
+      - switch
+      - case
+      - default
+      - break
+      - continue
+      - return
+      - function
+      - class
+      - const
+      - let
+      - var
+      - new
+      - typeof
+      - instanceof
+      - in
+      - of
+      - void
+      - delete
+      - yield
+      - async
+      - await
+      - export
+      - import
+      - extends
+      - super
+      - this
+      - static
+      - get
+      - set
+      - try
+      - catch
+      - finally
+      - throw
+      - interface
+      - type
+      - enum
+      - implements
+      - namespace
+      - declare
+      - as
+    go:
+      - if
+      - else
+      - for
+      - switch
+      - case
+      - default
+      - break
+      - continue
+      - return
+      - func
+      - package
+      - import
+      - defer
+      - go
+      - select
+      - chan
+      - range
+      - var
+      - const
+      - type
+      - struct
+      - interface
+      - map
+      - goto
+      - fallthrough
+    rust:
+      - if
+      - else
+      - for
+      - while
+      - loop
+      - match
+      - break
+      - continue
+      - return
+      - fn
+      - let
+      - mut
+      - struct
+      - enum
+      - impl
+      - trait
+      - use
+      - mod
+      - pub
+      - self
+      - Self
+      - in
+      - unsafe
+      - async
+      - await
+      - move
+      - ref
+      - where
+      - dyn
+      - static
+      - const
+      - type
+    java:
+      - if
+      - else
+      - for
+      - while
+      - do
+      - switch
+      - case
+      - default
+      - break
+      - continue
+      - return
+      - class
+      - interface
+      - extends
+      - implements
+      - public
+      - private
+      - protected
+      - static
+      - void
+      - this
+      - super
+      - new
+      - try
+      - catch
+      - finally
+      - throw
+      - throws
+      - import
+      - package
+      - enum
+    zig:
+      - if
+      - else
+      - for
+      - while
+      - switch
+      - break
+      - continue
+      - return
+      - fn
+      - const
+      - var
+      - pub
+      - struct
+      - enum
+      - union
+      - defer
+      - errdefer
+      - try
+      - catch
+      - comptime
+      - async
+      - await
+      - orelse
+    c:
+      - if
+      - else
+      - for
+      - while
+      - do
+      - switch
+      - case
+      - default
+      - break
+      - continue
+      - return
+      - goto
+      - sizeof
+      - typedef
+      - struct
+      - union
+      - enum
+      - static
+      - const
+      - void
+      - extern
+      - volatile
+    cpp:
+      - if
+      - else
+      - for
+      - while
+      - do
+      - switch
+      - case
+      - default
+      - break
+      - continue
+      - return
+      - goto
+      - sizeof
+      - typedef
+      - struct
+      - union
+      - enum
+      - class
+      - namespace
+      - template
+      - static
+      - const
+      - void
+      - new
+      - delete
+      - try
+      - catch
+      - throw
+      - public
+      - private
+      - protected
+      - virtual
+      - using
+
+  # UPG-REACT-TSX-FUNCTION-DECL-DROP: recovery for a grammar desync that
+  # swallows an unrelated region of siblings into one opaque, mis-typed node
+  # (e.g. a single unparseable construct hundreds of lines earlier can wreck
+  # the parser's recovery for the rest of the file). Language-agnostic — any
+  # tree-sitter grammar's error-recovery path can produce this shape, not
+  # just Flow/tsx. When the walker hits a node that is not itself a
+  # recognized symbol/call construct but has_error is set and its own span
+  # is large, it is worth an isolated reparse of just that byte range: the
+  # parser often resyncs cleanly once it starts fresh without the earlier
+  # desync's carried-over state.
+  error_recovery:
+    # Minimum line-span (end_line - start_line) an opaque errored node must
+    # cover before an isolated reparse is attempted. A short span IS the
+    # error (no swallowed siblings to recover) — reparsing it wastes a parse
+    # pass for nothing.
+    min_span_lines: 8
+    # Reparse attempts budget per file. Bounds worst-case parse cost when a
+    # file has many/deeply-nested desynced regions.
+    max_reparse_attempts_per_file: 200
+    # Per-attempt cap on how many original siblings a single recovery reparse
+    # may absorb while growing past an arbitrary mid-declaration cut (see
+    # error_recovery above). Without its own cap, one badly-cut region can
+    # burn the entire per-file budget growing sibling-by-sibling and starve
+    # every other desynced region in the same file.
+    max_extend_steps_per_attempt: 20
+
+cli:
+  # UPG-CLI-START-READY-RACE: `vectr start`/`restart` spawn the daemon as a
+  # detached background process and used to print a success block
+  # immediately after Popen() returned — before the daemon had bound its
+  # port or finished loading the embedder in its FastAPI lifespan. A
+  # `vectr status` run right after start's "success" message could still see
+  # a connection refused, reading as "start lied." `_do_start` now polls
+  # /v1/status until the daemon actually answers (or this timeout elapses)
+  # before printing anything, so the message reflects reality.
+  start_ready_poll_timeout_s: 20.0
+  # How often to retry the readiness probe while waiting (above).
+  start_ready_poll_interval_s: 0.3
+  # Per-attempt HTTP timeout for a single readiness probe during the poll
+  # loop above — short, since a probe that hangs this long just means "not
+  # ready yet," and we want to retry rather than block on one slow attempt.
+  start_ready_probe_timeout_s: 1.0
+  # UPG-CLI-DAEMON-VERSION-SKEW: HTTP timeout for the standalone /v1/status
+  # probe a daemon-talking subcommand issues to compare its local version
+  # stamp against the running daemon's. Short and best-effort — a slow/failed
+  # probe just means the check is skipped this invocation, never a blocked
+  # command.
+  version_skew_probe_timeout_s: 1.0
+
+workspace:
+  # Directory names written into a FRESH .vectrignore on first `vectr start` /
+  # `vectr init` when the workspace has none yet (UPG-13.2). An existing
+  # .vectrignore is never overwritten. These mirror the built-in indexing
+  # excludes (agent.indexer.EXCLUDED_DIRS) plus common ecosystem cache/build
+  # dirs, so a new user sees sensible excludes without hand-authoring them.
+  default_vectrignore_dirs:
+    - node_modules
+    - .venv
+    - venv
+    - env
+    - __pycache__
+    - .git
+    - dist
+    - build
+    - target
+    - .mypy_cache
+    - .pytest_cache
+    - .ruff_cache
+    - htmlcov
+    - coverage
+    - .tox
+    - .cache
+    - tmp
+    - vendor
+    - .next
+    - .nuxt
+    - out
+
+watcher:
+  # How often (seconds) CodeWatcher shallow-scans each workspace root's
+  # TOP-LEVEL entries only (UPG-13.1/13.3). The watcher never schedules a
+  # native OS watch on the workspace root itself — on macOS, FSEvents
+  # delivers every event under a watched path's *entire* subtree to the
+  # Python emitter regardless of the `recursive` flag passed to watchdog, so
+  # watching the root non-recursively gives zero protection against a large
+  # excluded sibling directory (confirmed empirically: churn inside an
+  # unwatched excluded dir produces zero native events; churn inside the
+  # same dir under a "non-recursive" root watch delivers 100% of events).
+  # Only per-included-top-level-directory watches actually stop the flood.
+  # This interval is how quickly a brand-new top-level directory, or an edit
+  # to a top-level loose file, is picked up instead — the shallow scan stats
+  # only the root's direct children, never the whole tree, so it stays cheap
+  # regardless of repo size.
+  top_level_rescan_interval_s: 5.0
+
+  # UPG-WATCHER-PRESSURE-GOVERNOR: burst coalescing. A sustained multi-file
+  # edit stream (AI coding agents editing many files in quick succession) hits
+  # the per-file debounce independently for every path, so the embed pipeline
+  # never goes idle — no global ceiling on concurrent re-embed work. When more
+  # than this many distinct paths are pending debounce SIMULTANEOUSLY, every
+  # per-file timer is cancelled and every pending path collapses into one
+  # deferred batch re-index instead — an edit storm then costs one batch pass
+  # over N files, not N independent re-embeds.
+  burst_files_threshold: 8
+  # Seconds of repo-wide silence (no new watched-file event) required, once
+  # burst coalescing has kicked in, before the collapsed batch actually runs.
+  # Keeps the batch from firing mid-storm and having to run again seconds
+  # later for the next wave of edits from the same agent turn.
+  burst_quiet_seconds: 15.0
+  # Optional self-limit (MB) on this process's own resident memory before a
+  # watcher-triggered batch re-index is allowed to run; 0 disables the check
+  # (default — the watcher never inspects memory unless a laptop operator
+  # opts in). When set and exceeded, the batch is deferred to the next quiet
+  # window and ONE warning line is logged instead of running — the collected
+  # paths are never dropped, just retried later. Reads this process's peak
+  # resident set size (stdlib `resource.getrusage`, no extra dependency);
+  # peak RSS is monotonically non-decreasing for the life of the process, so
+  # once tripped this acts as a standing "this process has run hot before,
+  # stop feeding it more embed work" brake rather than an instantaneous
+  # reading — deliberately conservative for a resource-safety guard.
+  max_rss_mb: 0
+
+hooks:
+  # UPG-HOOK-INJECT-OBSERVABILITY: when true, every hook-driven recall that
+  # actually injects notes (SessionStart/UserPromptSubmit/PreToolUse) appends
+  # one line to ~/.vectr/logs/<workspace-hash>.hooks.log — timestamp, hook
+  # kind, and an approximate token count of what was injected. Off by
+  # default: the per-hook-kind counters in `vectr status` already answer the
+  # common "is this actually firing" question without writing to disk; turn
+  # this on only when auditing exact injection timing/volume.
+  log_injections: false
+
+  # Divisor used to turn the injected notes' character count into an
+  # approximate token count for the optional injection log above. 4 is the
+  # commonly-cited chars-per-token ratio for English/code text; this is a
+  # rough sizing signal for the log, not a billing-accurate count.
+  log_chars_per_token: 4
+
+embedding:
+  # Default local (sentence-transformers) embedding model for the L3 content
+  # index (UPG-EMBEDDER-SWAP-GRANITE). Dimension-compatible drop-in for the
+  # prior default (Snowflake/snowflake-arctic-embed-m-v1.5 — both 768-dim),
+  # but a DIFFERENT vector space: a workspace's collection must never mix
+  # vectors from the two (see CodeIndexer's embed-model stamp, which forces
+  # a full rebuild on a stamp mismatch rather than letting old and new
+  # vectors coexist). Query-prompt handling stays model-driven, never
+  # hardcoded to either model's specific prefix convention: LocalEmbedProvider
+  # detects a registered "query" prompt on the loaded model itself
+  # (`model.prompts`) and only applies it when one exists, so a model with no
+  # such registration (like this default) embeds queries and documents
+  # identically, unchanged.
+  default_model: ibm-granite/granite-embedding-english-r2
+  # Hard cap on the encoder's token sequence length for local (sentence-
+  # transformers) embedding, applied on top of whatever the model's own
+  # config declares. Long-context embedders (this default declares 8192)
+  # otherwise encode every long chunk at full length — quadratic-attention
+  # cost on CPU, observed to stall a full-corpus index for hours — while
+  # short-context models (512) are unaffected. 512 matches the prior
+  # default's behavior; raise deliberately, with indexing throughput in mind.
+  max_seq_length: 512
+
+fetch:
+  # UPG-CTX-EVICT: deterministic re-fetch-by-chunk-id contract. Every chunk
+  # already carries a stable id (`file_path:start_line-end_line`, the literal
+  # ChromaDB id) — vectr_fetch/POST /v1/fetch/`vectr fetch` restore any of
+  # them verbatim in one call, no embedding or rerank involved. This caps how
+  # many ids a single call may request, so a caller can't turn the re-fetch
+  # surface into an unbounded bulk-export of the whole index.
+  max_ids_per_call: 20