Documentation
¶
Overview ¶
Package rag provides small interfaces and combinators for Retrieval-Augmented Generation.
The root package owns queries, candidates, citations, prompt replacement intent, stage contracts (Transformer, Expander, Retriever, Refiner, and Augmenter), and deterministic retrieval composition. It depends on document values rather than model, storage, or tool protocols. Adapters in this module build on the same contracts:
- github.com/Tangerg/scope/rag/chat owns model-backed query transforms, expansion, chat-backed rerank models, contextual prompts, and chat request preparation.
- github.com/Tangerg/scope/rag/vector adapts vector search to retrieval.
- github.com/Tangerg/scope/rag/rerank adapts any rerank model to refinement.
- github.com/Tangerg/scope/rag/tool exposes retrieval as a model-visible tool.
Composition is explicit. Wrap a retriever with the stages you need:
r, err := rag.Transform(base, rewrite, translate)
r, err = rag.Expand(rag.ExpansionConfig{Retriever: r, Expander: multiQuery})
top, err := rag.TopK(8)
r, err = rag.Refine(r, top)
docs, err := r.Retrieve(ctx, q)
Function adapters such as RetrieverFunc forward calls without adding policy. A composed retriever validates its query at entry and each external stage's output before the next stage consumes it; built-in stages also validate their own inputs so they can be used outside a composition.
Parallel retriever fan-out ¶
ReciprocalRankFusion combines independent rankings without comparing their raw scores, and Expand applies the same fusion to expanded queries:
combined, err := rag.ReciprocalRankFusion(rag.FusionRetrieverConfig{}, vectorR1, vectorR2)
TopK only sorts and caps a comparable result. Deduplicator keeps the best candidate for each known document identity; apply it before TopK when a single source can return duplicate identities. Fusion already merges them.
Routing and agentic retrieval ¶
There is no router stage. Route a query by implementing Retriever around the decision the router owns, such as a classifier over the query text:
func (r *routingRetriever) Retrieve(ctx context.Context, q rag.Query) (rag.Candidates, error) {
if r.isLogQuestion(q.Text()) {
return r.logs.Retrieve(ctx, q)
}
return r.docs.Retrieve(ctx, q)
}
Host authority such as a tenant is bound when a Retriever is built for it, never carried by the query.
github.com/Tangerg/scope/rag/tool.NewRetrieval adapts any composed Retriever to the ordinary core tool contract, so agents need no RAG-specific API.
Index ¶
- Constants
- Variables
- func CitationMarker(index int) string
- type Augmentation
- type Augmenter
- type AugmenterFunc
- type Candidate
- type Candidates
- type Citations
- type Deduplicator
- type Evidence
- type Excerpt
- type Expander
- type ExpanderFunc
- type ExpansionConfig
- type FusionRetriever
- type FusionRetrieverConfig
- type PipelineRetriever
- type Query
- type ReciprocalRankFusionConfig
- type Refiner
- type RefinerFunc
- type Retriever
- type RetrieverFunc
- type Score
- type TopKRefiner
- type Transformer
- type TransformerFunc
Examples ¶
Constants ¶
const DefaultMaxConcurrentRetrievals = 4
const DefaultReciprocalRankConstant = 60
DefaultReciprocalRankConstant is the conventional RRF smoothing constant.
Variables ¶
var ( // ErrInvalidAugmentation identifies generation input or citation numbering // that cannot be represented portably. ErrInvalidAugmentation = errors.New("rag: invalid augmentation") ErrNilAugmenter = errors.New("rag: augmenter must not be nil") )
var ( ErrInvalidQuery = errors.New("rag: invalid query") ErrNilRetriever = errors.New("rag: retriever must not be nil") )
var ( // ErrInvalidCandidate identifies an invalid document or non-finite score. ErrInvalidCandidate = errors.New("rag: invalid retrieval candidate") // ErrInvalidReranking identifies invalid model rankings or candidate projections. ErrInvalidReranking = errors.New("rag: invalid reranking") ErrNilTransformer = errors.New("rag: transformer must not be nil") ErrNilExpander = errors.New("rag: expander must not be nil") ErrNilRefiner = errors.New("rag: refiner must not be nil") ErrEmptyExpansion = errors.New("rag: expander returned no queries") // ErrInvalidExpansion identifies invalid or duplicate expanded queries. ErrInvalidExpansion = errors.New("rag: invalid query expansion") )
var ErrInvalidRankConstant = errors.New("rag: reciprocal-rank constant must not be negative")
var ErrInvalidRetrievalConcurrency = errors.New("rag: retrieval concurrency must not be negative")
var ErrUnidentifiedCitation = errors.New("rag: citation requires a document ID")
ErrUnidentifiedCitation means the selected document has no stable document ID.
var ErrUnknownCitation = errors.New("rag: unknown citation marker")
ErrUnknownCitation means the marker is malformed or is outside this prompt's selection.
Functions ¶
func CitationMarker ¶ added in v0.45.0
CitationMarker is the one-based prompt marker of the citation at index.
Types ¶
type Augmentation ¶
type Augmentation struct {
// contains filtered or unexported fields
}
Augmentation owns the decision to preserve or replace generation text. Its zero value preserves the original input, including content omitted by Query's retrieval projection. Values and citations are immutable.
func NewAugmentation ¶
func NewAugmentation(text string) (Augmentation, error)
NewAugmentation requires replacement even when text equals the retrieval query. The non-blank UTF-8 text is preserved exactly.
func (Augmentation) Citations ¶
func (a Augmentation) Citations() Citations
Citations returns the immutable selection used for this prompt.
func (Augmentation) ReplacementText ¶ added in v0.60.0
func (a Augmentation) ReplacementText() (string, bool)
ReplacementText separates an explicit rewrite from preserving the original input; consumers must not infer that decision by comparing text.
func (Augmentation) Validate ¶
func (a Augmentation) Validate() error
type Augmenter ¶
type Augmenter interface {
// Augment decides whether to replace generation text using one query and
// its ordered candidates. It must not mutate either input, must preserve any
// citation-to-candidate relationship it emits, and must honor ctx.
Augment(ctx context.Context, query Query, candidates Candidates) (Augmentation, error)
}
type AugmenterFunc ¶
type AugmenterFunc func(context.Context, Query, Candidates) (Augmentation, error)
func IdentityAugmenter ¶
func IdentityAugmenter() AugmenterFunc
IdentityAugmenter keeps the original generation input rather than replacing it with the query's normalized retrieval text.
func (AugmenterFunc) Augment ¶
func (a AugmenterFunc) Augment(ctx context.Context, query Query, candidates Candidates) (Augmentation, error)
type Candidate ¶
Candidate relates a document to the retrieval operation that produced it. Score is query-specific and therefore does not belong on document.Document.
type Candidates ¶
type Candidates []Candidate
Candidates is an ordered retrieval result. Its methods never mutate the receiver, preserving declaration and retrieval order where scores tie.
func (Candidates) Clone ¶
func (c Candidates) Clone() Candidates
func (Candidates) Validate ¶
func (c Candidates) Validate() error
type Citations ¶
type Citations struct {
// contains filtered or unexported fields
}
Citations is the immutable selection supplied to one prompt. The position owns its marker; neither model output nor changes to a returned document can create or renumber an entry. Its zero value is an empty selection.
func (Citations) Candidates ¶ added in v0.59.0
func (c Citations) Candidates() Candidates
Candidates returns an owned snapshot of admitted evidence in marker order. This also exposes temporary material without claiming that it is reproducible.
func (Citations) Len ¶ added in v0.59.0
Len reports how many prompt markers can resolve to admitted material.
func (Citations) MarshalJSON ¶ added in v0.59.0
MarshalJSON exposes the ordered admitted entries to host clients. Position, rather than a second stored field, determines each entry's marker.
func (Citations) Resolve ¶ added in v0.59.0
Resolve returns the original, detached document for an exact canonical prompt marker such as "[1]". Its Provenance owns the source, revision and known location. Anonymous material returns document.ErrUnversionedSource. Resolution neither fetches a source nor establishes that it supports a generated claim.
type Deduplicator ¶ added in v0.57.0
type Deduplicator struct{}
Deduplicator is the Refiner that keeps the highest-scoring candidate for each nonempty document ID within the same source revision and location. Its zero value is ready to use. For unversioned local data, the caller owns the ID namespace. Identities retain first-seen order, and equal scores retain the first candidate. Documents without an ID remain distinct because the framework cannot prove they are duplicates.
func (Deduplicator) Refine ¶ added in v0.57.0
func (d Deduplicator) Refine(ctx context.Context, query Query, candidates Candidates) (Candidates, error)
type Evidence ¶ added in v0.59.0
type Evidence []Excerpt
Evidence is an ordered selection of complete excerpts. The same sequence renders the prompt block and binds its marker positions to original documents.
type Excerpt ¶ added in v0.59.0
Excerpt pairs an original retrieval candidate with the exact text rendered from it. Content may be a host-formatted projection rather than a byte range in the original. The candidate's document remains the provenance owner.
type Expander ¶
type Expander interface {
// Expand returns a non-empty, ordered set of valid alternative or decomposed
// queries with distinct Text values. It must not mutate query or expose
// reusable backing storage;
// ordering is semantic because downstream fusion uses it for stable ties.
Expand(ctx context.Context, query Query) ([]Query, error)
}
type ExpanderFunc ¶
type ExpansionConfig ¶ added in v0.18.0
type ExpansionConfig struct {
Retriever Retriever
Expander Expander
Fusion ReciprocalRankFusionConfig
// MaxConcurrentRetrievals bounds expanded-query retrievals per invocation.
// Zero uses DefaultMaxConcurrentRetrievals; one is sequential.
MaxConcurrentRetrievals int
}
type FusionRetriever ¶ added in v0.57.0
type FusionRetriever struct {
// contains filtered or unexported fields
}
FusionRetriever owns an admitted, detached set of rank-fusion inputs. Construct it with ReciprocalRankFusion; its zero value is invalid.
func ReciprocalRankFusion ¶
func ReciprocalRankFusion(config FusionRetrieverConfig, retrievers ...Retriever) (*FusionRetriever, error)
ReciprocalRankFusion returns a retriever that concurrently executes each input retriever and fuses their ordered results using reciprocal-rank fusion. Raw candidate scores are deliberately ignored because independent retrievers commonly use incomparable score scales. Every retriever must succeed; the first failure cancels the remaining retrievals and is returned without partial results.
func (*FusionRetriever) Retrieve ¶ added in v0.57.0
func (f *FusionRetriever) Retrieve(ctx context.Context, query Query) (Candidates, error)
type FusionRetrieverConfig ¶ added in v0.19.0
type FusionRetrieverConfig struct {
Fusion ReciprocalRankFusionConfig
// MaxConcurrentRetrievals bounds active child calls independently per
// invocation. Zero uses DefaultMaxConcurrentRetrievals; one is sequential.
MaxConcurrentRetrievals int
}
type PipelineRetriever ¶ added in v0.57.0
type PipelineRetriever struct {
// contains filtered or unexported fields
}
PipelineRetriever owns the public entry boundary. Its pipeline checks each external stage result before passing it onward, so returning that same result does not require another candidate traversal. Construct it with Transform, Expand, or Refine; its zero value is invalid.
func Expand ¶ added in v0.60.0
func Expand(config ExpansionConfig) (*PipelineRetriever, error)
Expand returns a Retriever that retrieves each expanded query under the configured concurrency bound and combines rankings with reciprocal-rank fusion. Every query must succeed; the first failure cancels the remaining retrievals and is returned. Raw scores never cross query boundaries.
func Refine ¶ added in v0.60.0
func Refine(next Retriever, refiners ...Refiner) (*PipelineRetriever, error)
Refine returns a Retriever that calls next and then applies refiners to the returned documents in order.
func Transform ¶ added in v0.60.0
func Transform(next Retriever, transformers ...Transformer) (*PipelineRetriever, error)
Transform returns a Retriever that rewrites the query through transformers before calling next.
func (*PipelineRetriever) Retrieve ¶ added in v0.57.0
func (p *PipelineRetriever) Retrieve(ctx context.Context, query Query) (Candidates, error)
type Query ¶
type Query struct {
// contains filtered or unexported fields
}
Query is the text a retrieval stage acts on. It carries no side slots: a stage that needs more input, such as conversation history, declares it in its own input type instead of reading hidden state from the query.
type ReciprocalRankFusionConfig ¶
type ReciprocalRankFusionConfig struct {
RankConstant int
}
ReciprocalRankFusionConfig sets the constant added to each one-based rank before reciprocal weighting; zero uses DefaultReciprocalRankConstant.
type Refiner ¶
type Refiner interface {
// Refine returns a valid, independently owned subset or reordering of
// candidates for query. It must not mutate either input; a successful empty
// result explicitly means no evidence survived refinement.
Refine(ctx context.Context, query Query, candidates Candidates) (Candidates, error)
}
type RefinerFunc ¶
type RefinerFunc func(context.Context, Query, Candidates) (Candidates, error)
func (RefinerFunc) Refine ¶
func (r RefinerFunc) Refine(ctx context.Context, query Query, candidates Candidates) (Candidates, error)
type Retriever ¶
type Retriever interface {
// Retrieve returns independently owned, valid candidates in the source's
// relevance order. Scores remain query-relative; the implementation must
// honor ctx and must not mutate query.
Retrieve(ctx context.Context, query Query) (Candidates, error)
}
type RetrieverFunc ¶
type RetrieverFunc func(context.Context, Query) (Candidates, error)
func (RetrieverFunc) Retrieve ¶
func (r RetrieverFunc) Retrieve(ctx context.Context, query Query) (Candidates, error)
type Score ¶ added in v0.13.0
type Score float64
Score is a finite, query-relative ordering value. Scores are comparable only within the retrieval or fusion result that produced them.
type TopKRefiner ¶ added in v0.57.0
type TopKRefiner struct {
// contains filtered or unexported fields
}
TopKRefiner retains the bound admitted by TopK. Its zero value is invalid.
func TopK ¶
func TopK(topK int) (*TopKRefiner, error)
TopK returns a Refiner that stably sorts candidates by descending score and returns at most topK candidates. topK must be positive. Use Deduplicator before TopK when unique document identities are required.
Example ¶
package main
import (
"context"
"fmt"
"github.com/Tangerg/scope/core/document"
"github.com/Tangerg/scope/rag"
)
func main() {
first, err := document.NewDocument("first", nil)
if err != nil {
panic(err)
}
second, err := document.NewDocument("second", nil)
if err != nil {
panic(err)
}
query, err := rag.NewQuery("rank the evidence")
if err != nil {
panic(err)
}
refiner, err := rag.TopK(1)
if err != nil {
panic(err)
}
result, err := refiner.Refine(context.Background(), query, rag.Candidates{
{Document: first, Score: 0.25},
{Document: second, Score: 0.75},
})
if err != nil {
panic(err)
}
fmt.Println(result[0].Document.Text)
}
Output: second
func (*TopKRefiner) Refine ¶ added in v0.57.0
func (t *TopKRefiner) Refine(ctx context.Context, query Query, candidates Candidates) (Candidates, error)
type Transformer ¶
type Transformer interface {
// Transform returns one valid query that preserves the caller's retrieval
// intent while changing its representation. It must not mutate query, must
// honor ctx, and transfers ownership of the returned value to the caller.
Transform(ctx context.Context, query Query) (Query, error)
}
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package chat composes retrieval with chat models through the rag domain contracts.
|
Package chat composes retrieval with chat models through the rag domain contracts. |
|
Package index prepares and embeds source-bound documents before sending precomputed records to a native index.
|
Package index prepares and embeds source-bound documents before sending precomputed records to a native index. |
|
Package rerank adapts rerank models to the rag Refiner contract.
|
Package rerank adapts rerank models to the rag Refiner contract. |
|
Package tool exposes rag retrieval through the ordinary core Tool contract.
|
Package tool exposes rag retrieval through the ordinary core Tool contract. |
|
Package vector adapts core vector search to the rag Retriever contract.
|
Package vector adapts core vector search to the rag Retriever contract. |