Documentation
¶
Overview ¶
Package chat composes retrieval with chat models through the rag domain contracts. It owns query transforms, expansion, model-backed ranking, contextual prompts, and retrieval preparation for chat requests. Chat history and prompt policy remain here; queries, candidates, citations, and generation input retain their owners in rag.
Index ¶
- Constants
- Variables
- func HistoryValueKey() rag.ValueKey[[]corechat.Message]
- type CompressionTransformer
- type CompressionTransformerConfig
- type ContextualAugmenter
- type ContextualAugmenterConfig
- type Evidence
- type MultiQueryExpander
- type MultiQueryExpanderConfig
- type PreparedRequest
- type Preparer
- type PreparerConfig
- type Reranker
- type RerankerConfig
- type RewriteTransformer
- type RewriteTransformerConfig
- type TranslationTransformer
- type TranslationTransformerConfig
Examples ¶
Constants ¶
const DefaultMultiQueryCount = 3
Variables ¶
var ( ErrNilResponse = errors.New("rag: chat model returned a nil response") ErrNilStreamSequence = errors.New("rag: chat streamer returned a nil sequence") // ErrNoFinalUserMessage rejects requests whose active retrieval query is // ambiguous. ErrNoFinalUserMessage = errors.New("rag: chat request must end with a user message") )
var ErrContextBudgetExceeded = errors.New("rag: context token budget cannot admit evidence")
ErrContextBudgetExceeded means retrieved evidence exists but no complete candidate fits the configured context budget.
var ErrEmptyModelOutput = errors.New("rag: model returned empty query text")
ErrEmptyModelOutput classifies a model response that rag.Query will not accept as query text, such as text that is empty or blank after trimming. Query owns that admission rule; this sentinel only records that the rejected text came from the model, so a caller can tell it apart from its own invalid query. Missing response text and unsuccessful completion preserve the chatclient errors.
var ErrInvalidContextBudget = errors.New("rag: invalid context token budget")
ErrInvalidContextBudget identifies an invalid context window or token measurement.
Functions ¶
Types ¶
type CompressionTransformer ¶
type CompressionTransformer struct {
// contains filtered or unexported fields
}
func NewCompressionTransformer ¶
func NewCompressionTransformer(config CompressionTransformerConfig) (*CompressionTransformer, error)
type CompressionTransformerConfig ¶
type CompressionTransformerConfig struct {
Model corechat.Model
// PromptTemplate replaces the built-in prompt and must declare
// {{.History}} and {{.Query}}.
PromptTemplate *chatclient.Template
}
type ContextualAugmenter ¶
type ContextualAugmenter struct {
// contains filtered or unexported fields
}
Example ¶
package main
import (
"context"
"fmt"
"github.com/Tangerg/scope/core/document"
"github.com/Tangerg/scope/rag"
ragchat "github.com/Tangerg/scope/rag/chat"
)
func main() {
augmenter, err := ragchat.NewContextualAugmenter(ragchat.ContextualAugmenterConfig{})
if err != nil {
panic(err)
}
query, err := rag.NewQuery("What does Scope provide?")
if err != nil {
panic(err)
}
doc, err := document.NewDocument("Scope provides AI infrastructure.", nil)
if err != nil {
panic(err)
}
doc.ID = "scope"
doc.Provenance = document.NewProvenance("scope.txt", []byte(doc.Text))
result, err := augmenter.Augment(context.Background(), query, rag.Candidates{{Document: doc, Score: 1}})
if err != nil {
panic(err)
}
doc, err = result.Citations().Resolve("[1]")
if err != nil {
panic(err)
}
fmt.Println(doc.ID, doc.Provenance.Source)
}
Output: scope scope.txt
func NewContextualAugmenter ¶
func NewContextualAugmenter(config ContextualAugmenterConfig) (*ContextualAugmenter, error)
func (*ContextualAugmenter) Augment ¶
func (c *ContextualAugmenter) Augment(ctx context.Context, query rag.Query, candidates rag.Candidates) (rag.Augmentation, error)
type ContextualAugmenterConfig ¶
type ContextualAugmenterConfig struct {
// Instructions is the guidance placed before the evidence block. The
// augmenter always writes the evidence block and the query itself, so a
// citation can never claim evidence the prompt omits. Empty uses the default.
Instructions string
// EmptyContextMessage is the prompt used when no documents are retrieved and
// AllowEmptyContext is false. Empty uses the default.
EmptyContextMessage string
// AllowEmptyContext returns the query unchanged when no documents are
// retrieved instead of using EmptyContextMessage.
AllowEmptyContext bool
// Formatter renders each retrieved document. The default [document.TextFormatter]
// rejects media with [document.ErrUnsupportedMedia].
Formatter document.Formatter
// MaxContextTokens limits the encoded evidence block. Zero leaves context
// unbounded. A positive value requires TokenCounter. Only complete
// candidates that fit are included, in retrieval order. Oversized candidates
// are skipped so later candidates can still fit. If none fits, Augment returns
// ErrContextBudgetExceeded regardless of AllowEmptyContext.
MaxContextTokens int
TokenCounter tokenizer.TextCounter
}
type Evidence ¶ added in v0.20.0
type Evidence struct {
Candidates rag.Candidates
Citations rag.Citations
}
Evidence is the retrieval result for one prepared request. It belongs to RAG and remains available independently of model success or stream consumption.
type MultiQueryExpander ¶
type MultiQueryExpander struct {
// contains filtered or unexported fields
}
func NewMultiQueryExpander ¶
func NewMultiQueryExpander(config MultiQueryExpanderConfig) (*MultiQueryExpander, error)
func (*MultiQueryExpander) Expand ¶
Expand requires exactly NumberOfQueries distinct variants; empty, duplicate, and original-query entries do not count toward it. No usable variant returns rag.ErrEmptyExpansion.
type MultiQueryExpanderConfig ¶
type MultiQueryExpanderConfig struct {
Model corechat.Model
// IncludeOriginal prepends the original query to the variant list.
IncludeOriginal bool
// NumberOfQueries is the variant count requested from the model. Zero
// uses [DefaultMultiQueryCount]; negative values are invalid.
NumberOfQueries int
// PromptTemplate replaces the built-in prompt and must declare
// {{.Number}} and {{.Query}}.
PromptTemplate *chatclient.Template
}
type PreparedRequest ¶ added in v0.19.0
type PreparedRequest struct {
// contains filtered or unexported fields
}
PreparedRequest owns an immutable augmented request and its retrieval evidence. Its zero value is invalid. Prepare once, then pass the complete model or tool orchestration to Call or Stream; downstream continuations never retrieve again.
func (PreparedRequest) Call ¶ added in v0.19.0
Call runs the prepared request through next. Evidence remains on the prepared request; this call never retrieves again, including on a model failure.
func (PreparedRequest) Evidence ¶ added in v0.20.0
func (p PreparedRequest) Evidence() Evidence
Evidence returns an owned candidate snapshot and the immutable prompt citations. Complete documents are never added to model response metadata implicitly.
type Preparer ¶ added in v0.19.0
type Preparer struct {
// contains filtered or unexported fields
}
Preparer owns retrieval and augmentation at the start of a user turn. It is immutable after construction and safe for concurrent use when its Retriever and Augmenter are safe for concurrent use. Unchanged augmentation preserves every user Part. Text rewrites require exactly one text Part and preserve all other Parts and their relative positions; ambiguous rewrites fail with rag.ErrInvalidAugmentation before calling the model.
Example ¶
preparer, err := ragchat.NewPreparer(ragchat.PreparerConfig{
Retriever: rag.RetrieverFunc(func(context.Context, rag.Query) (rag.Candidates, error) {
return rag.Candidates{{Document: &document.Document{Text: "Scope provides AI infrastructure."}}}, nil
}),
Augmenter: rag.IdentityAugmenter(),
})
if err != nil {
panic(err)
}
ctx := context.Background()
request, err := chat.NewRequest(chat.NewUserMessage(chat.NewTextPart("What is Scope?")))
if err != nil {
panic(err)
}
prepared, err := preparer.Prepare(ctx, request)
if err != nil {
panic(err)
}
model := chat.ModelFunc(func(context.Context, *chat.Request) (*chat.Response, error) {
return textResponse("AI infrastructure"), nil
})
response, err := prepared.Call(ctx, model)
if err != nil {
panic(err)
}
candidates := prepared.Evidence().Candidates
fmt.Println(response.Text(), len(candidates))
Output: AI infrastructure 1
func NewPreparer ¶ added in v0.19.0
func NewPreparer(config PreparerConfig) (*Preparer, error)
type PreparerConfig ¶ added in v0.19.0
type Reranker ¶
type Reranker struct {
// contains filtered or unexported fields
}
Reranker reorders candidates using a chat model's native structured output and replaces provider-specific retrieval scores with normalized relevance scores.
func NewReranker ¶
func NewReranker(config RerankerConfig) (*Reranker, error)
type RerankerConfig ¶
type RerankerConfig struct {
Model corechat.Model
// PromptTemplate replaces the built-in prompt and must declare
// {{.Query}} and {{.Candidates}}.
PromptTemplate *chatclient.Template
// Formatter renders candidate content. The default [document.TextFormatter]
// rejects media with [document.ErrUnsupportedMedia].
Formatter document.Formatter
}
type RewriteTransformer ¶
type RewriteTransformer struct {
// contains filtered or unexported fields
}
func NewRewriteTransformer ¶
func NewRewriteTransformer(config RewriteTransformerConfig) (*RewriteTransformer, error)
type RewriteTransformerConfig ¶
type RewriteTransformerConfig struct {
Model corechat.Model
// TargetSearchSystem names the downstream search engine — "vector
// store", "web search engine", "database", etc. Required.
TargetSearchSystem string
// PromptTemplate replaces the built-in prompt and must declare
// {{.Target}} and {{.Query}}.
PromptTemplate *chatclient.Template
}
type TranslationTransformer ¶
type TranslationTransformer struct {
// contains filtered or unexported fields
}
func NewTranslationTransformer ¶
func NewTranslationTransformer(config TranslationTransformerConfig) (*TranslationTransformer, error)
type TranslationTransformerConfig ¶
type TranslationTransformerConfig struct {
Model corechat.Model
// TargetLanguage is the language the embedding model expects —
// "English", "Chinese", "Spanish", etc. Required.
TargetLanguage string
// PromptTemplate replaces the built-in prompt and must declare
// {{.Target}} and {{.Query}}.
PromptTemplate *chatclient.Template
}