Documentation
¶
Overview ¶
Package retrieve is the wedge: it fuses the FTS5 and graph-BM25 signals, expands one hop along the graph, boosts the institutional-memory tier, and packs the result to a token budget. The agent calls this, not raw search.
Index ¶
- func EstimateTokens(s string) int
- func TotalTokens(cards []Card) int
- type Card
- type Options
- type Retriever
- func (r *Retriever) EnableRerank(rr rerank.Reranker) bool
- func (r *Retriever) EnableVectors(e embed.Embedder, model string, storedDim int, vecs map[string][][]float32) bool
- func (r *Retriever) HNSWActive() bool
- func (r *Retriever) RerankActive() bool
- func (r *Retriever) RerankModel() string
- func (r *Retriever) Retrieve(ctx context.Context, query string, opt Options) ([]Card, error)
- func (r *Retriever) SetWeights(fts, graph, vec float64)
- func (r *Retriever) VectorModel() string
- func (r *Retriever) VectorsActive() bool
- func (r *Retriever) Weights() (fts, graph, vec float64)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EstimateTokens ¶
EstimateTokens is the exported counter so the measurement harness counts both arms with the exact same function the packer uses.
func TotalTokens ¶
TotalTokens sums the estimated cost of a set of cards.
Types ¶
type Card ¶
type Card struct {
NodeID string
NoteID string
Title string
Path string
Type string
Scope string // access-control scope(s), comma-joined (for the scope read filter)
Snippet string
Score float64
Tier0 bool
Reason string
}
Card is one retrieval result: a note, why it surfaced, and its fused score.
type Options ¶
type Options struct {
Limit int // candidates pulled per signal (default 20)
Budget int // token budget for packing; 0 = return all ranked
WeightFTS float64 // fusion weight; 0 across all three => resolved defaults
WeightGraph float64
WeightVec float64
NoRerank bool // skip the cross-encoder stage even when configured (for tuning the fusion itself)
// AllowedScopes, when non-nil, restricts results to notes whose scope intersects
// the set (access control). nil = unrestricted (solo / no-ACL fast path). This is
// THE read boundary: it is applied at the card loop below so it covers FTS, graph,
// vector, and 1-hop expansion in one place, and before the reranker reads any doc.
AllowedScopes map[string]bool
}
Options tunes a retrieval. Zero values get sensible defaults.
type Retriever ¶
type Retriever struct {
// contains filtered or unexported fields
}
func NewFromEnv ¶
NewFromEnv builds a retriever and enables the optional BYOAI stages from the environment. The semantic (vector) and rerank stages are independent: either, both, or neither can be on. Falls back silently to lexical-only when nothing is configured.
func (*Retriever) EnableRerank ¶
EnableRerank turns on the cross-encoder rerank stage. The reranker reorders the top-K fused candidates; it never gates retrieval, so a failing endpoint degrades silently to the fused order. Returns false for a nil reranker.
func (*Retriever) EnableVectors ¶
func (r *Retriever) EnableVectors(e embed.Embedder, model string, storedDim int, vecs map[string][][]float32) bool
EnableVectors turns on the semantic signal. It is a no-op unless the query embedder's model matches the vault's stored model AND its vector width matches the stored width (homogeneity guard: vectors from a different model, or even the same model name at a different dimension, are not comparable. A length mismatch makes every cosine return 0, which min-max then normalizes to a uniform 1 - a silent garbage signal that boosts every note equally. We fail safe to lexical-only rather than emit it). storedDim is the vault's recorded width; if it is 0 (old vault, pre-vector_dim) we derive it from the loaded vectors.
func (*Retriever) HNSWActive ¶
HNSWActive reports whether the ANN index is built and serving the vector signal (vs the brute-force scan). Only true past the configured MESH_HNSW_THRESHOLD, and only in the pro build (the open core has no ANN implementation wired).
func (*Retriever) RerankActive ¶
RerankActive reports whether a cross-encoder rerank stage is configured.
func (*Retriever) RerankModel ¶
RerankModel returns the configured rerank model id (empty when inactive).
func (*Retriever) Retrieve ¶
Retrieve runs the full pipeline and returns ranked (and optionally budget-packed) cards.
func (*Retriever) SetWeights ¶
SetWeights sets the fusion-weight defaults used when a retrieval does not pass explicit Options weights (e.g. learned weights from `mesh tune`). Any value may be 0; if all three are 0 the built-in defaults apply.
func (*Retriever) VectorModel ¶
VectorModel returns the active embedding model id (empty when inactive).
func (*Retriever) VectorsActive ¶
VectorsActive reports whether the semantic signal will fire (an embedder is configured and the vault has stored vectors that match its model).
Source Files