Semantic Retrieval

How Weave retrieves relevant chunks — similarity, MMR, hybrid, and cross-collection search.

engine.Retrieve is the primary retrieval interface. It embeds the query, searches the vector store, and returns scored chunks ranked by relevance.

Basic retrieval

import (
    "github.com/xraph/weave"
    "github.com/xraph/weave/engine"
)

ctx = weave.WithTenant(ctx, "tenant-1")

results, err := eng.Retrieve(ctx, "What is the return policy?",
    engine.WithCollection(colID),
    engine.WithTopK(5),
    engine.WithMinScore(0.75),
)

for _, r := range results {
    fmt.Printf("[%.2f] %s\n", r.Score, r.Chunk.Content[:80])
}

Retrieve options

Option	Description
`engine.WithCollection(colID)`	Restrict results to a specific collection
`engine.WithTopK(k)`	Maximum number of results (default: `Config.DefaultTopK`)
`engine.WithMinScore(score)`	Drop results with score below threshold
`engine.WithStrategy(name)`	Override the retrieval strategy: `"similarity"`, `"mmr"`, `"hybrid"`
`engine.WithTenantID(id)`	Explicit tenant — defaults to context value

ScoredChunk

Retrieve returns []engine.ScoredChunk:

type ScoredChunk struct {
    Chunk *chunk.Chunk `json:"chunk"`
    Score float64      `json:"score"`
}

Results are sorted by Score descending. Score is cosine similarity in the range [0, 1]. Use WithMinScore to filter out low-confidence results.

Retrieval pipeline

When Retrieve is called:

Emit OnRetrievalStarted
If a custom Retriever is configured, delegate to it entirely
Otherwise, embed the query with the engine's embedder
Search the vector store with filter["collection_id"] and filter["tenant_id"]
Map search results to []ScoredChunk
Emit OnRetrievalCompleted with result count and elapsed time

If the search fails, OnRetrievalFailed is emitted before the error is returned.

Retrieval strategies

Plug in a custom retriever.Retriever via engine.WithRetriever(r) to use different strategies:

Strategy	Package	Description
`similarity`	`retriever/similarity`	Default cosine similarity search
`mmr`	`retriever/mmr`	Maximal Marginal Relevance — diversity-optimized results
`hybrid`	`retriever/hybrid`	Combines dense vector search with keyword matching
`reranker`	`retriever/reranker`	Two-stage: retrieve many, re-rank with a cross-encoder

Cross-collection search

HybridSearch retrieves across one or more collections and merges results:

results, err := eng.HybridSearch(ctx, "return policy",
    &engine.HybridSearchParams{
        Collections: []id.CollectionID{col1, col2},
        TopK:        10,
        MinScore:    0.7,
    },
)

When Collections is non-empty, Weave retrieves from each collection independently, merges the results, re-sorts by score, and trims to TopK. When empty, it searches across all collections visible to the current tenant.

Retriever interface

Implement retriever.Retriever to plug in a completely custom retrieval strategy:

type Retriever interface {
    Retrieve(ctx context.Context, query string, opts *Options) ([]Result, error)
}

// Options provides all context the retriever needs:
type Options struct {
    CollectionID string
    TenantKey    string
    TopK         int
    MinScore     float64
    Filter       map[string]string
}