Documentation
¶
Overview ¶
Package smartctx is the shared "smart 1-shot retrieval" implementation used by both internal/mcp.get_context_for_task and internal/eval's δ baseline. Before this package existed the two callers had separate algorithms — the MCP path was a 50-line BM25/PR/usage fusion, the eval δ was `SearchFTS top-10 dump`. The asymmetry meant eval H1/H2 hypotheses did not measure what MCP actually returns to LLMs.
BuildContext is now the single source of truth. Callers serialize the returned Pack however they prefer (mcp wraps it in mcp.NewToolResult; eval encodes to JSON and embeds in the LLM prompt).
Citation Enforcement (warn mode): every body/summary/subgraph node includes file_path + start_line. Nodes that lack either are kept in the response (to preserve recall) but recorded under `metadata.warnings` with code "missing-citation". A future strict mode will drop those nodes outright once the warn-mode signal proves stable.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildContext ¶
BuildContext is the shared smart-retrieval algorithm:
(a) Search — top opt.CandidateLimit via the store's smart router.
(b) Expand — opt.HopDepth-hop BFS via QueryEdgesForNodes, each
hop capped at opt.HopFrontierCap new nodes.
(c) Score — 0.5 BM25 + 0.3 PageRank + 0.2 Usage.
(d) Diversify — V0: opt.RankedCap. Per-cluster diversity is V1+.
(e) Pack — top MaxBodies get full source; next ≤MaxSummaries get
sig+doc.
(f) Cite — every emitted item gets file_path + start_line.
Items missing either generate a warning record.
Types ¶
type Options ¶
type Options struct {
BudgetTokens int // default 8000
IncludeBlobs bool // mcp default true; eval may set false
MaxBodies int // default 5
// CandidateLimit caps the initial Search() top-N. Bumped from
// 30 to 100 in P0 #3 — the prior cap was the dominant recall
// bottleneck in the Stage B 2026-05-29 measurement. Override
// to a smaller value when callers want a tight, fast response.
CandidateLimit int // default 100
// RankedCap caps the size of the per-query ranked slice that
// reaches the packer. Must be >= MaxBodies + a small headroom
// so the summary tier has rows to choose from. Default 50.
RankedCap int // default 50
// MaxSummaries caps signature/doc entries emitted alongside the
// MaxBodies full sources. Default 25.
MaxSummaries int
// HopDepth controls how many edge hops the expand stage walks
// out from the seed candidate set. 1 (default) preserves the
// original O(candidates · avgFanout) cost. 2 enables a second
// BFS hop — useful when the query's relevant context lives two
// edges away (caller-of-caller, type-of-field-type). Bounded
// at HopFrontierCap per hop to prevent fan-out explosions on
// hub nodes. P2 #7 follow-up to the P0 #3 widening.
HopDepth int
// HopFrontierCap caps the per-hop frontier size when HopDepth
// > 1. Without it a hub node like a generic "Logger" symbol
// could pull in tens of thousands of callers at hop 2 and
// blow the rank/pack budget. Default 200 — wide enough that
// the BM25 re-ranker still has a meaningful set to discriminate
// from, narrow enough that the per-hop store.NodesByIDs round
// trip stays bounded.
HopFrontierCap int
// IncludePRs attaches up to PRsPerNode breadcrumbs to each body
// entry (the "왜" history landed in P0 #1). Off by default so
// the eval δ baseline's measurement remains comparable to its
// pre-2026-05-29 runs.
IncludePRs bool
PRsPerNode int // default 3
PRCutoff time.Time // zero = no cutoff (return full history)
// IncludeImpact runs pkg/impact.Compute against the highest-
// scoring kept node (rows[0]) so the agent gets reverse-deps in
// the same response. Off by default — adds an O(impact.groups
// × depth) traversal that's only worth paying for when the
// caller actually wants impact info.
IncludeImpact bool
ImpactDepth int // default 1; clamped by pkg/impact internally
}
Options bundles the tunable knobs of BuildContext. Zero values are resolved to documented defaults inside BuildContext so callers can pass an empty struct for the typical case.
The IncludePRs / IncludeImpact flags drive P0 #2 — the 1-shot retrieval surface from docs/PROJECT-BLUEPRINT-ALIGNMENT.md §4.2. Both default to false so existing callers (eval δ baseline, MCP pre-merge consumers) see the same output shape they had before; the new keys (recent_prs / impact) only appear when the caller explicitly opts in.
CandidateLimit / RankedCap / MaxSummaries (P0 #3) expose the pipeline width knobs that were previously baked into private package constants. Bumping them widens recall at a roughly linear O(N) cost — the Stage B 2026-05-29 measurement found that the 30-candidate cap was leaving δ score at 76% of β's. The new defaults (100 / 50 / 25) close most of that gap on the eval fixture without changing the algorithm itself.
Source Files