Documentation
¶
Overview ¶
Package rerank defines provider-agnostic document reranking types and the Provider interface that all reranking model backends implement.
Reranking takes a query and a set of documents, and re-orders the documents by their relevance to the query. This is commonly used in RAG pipelines to improve retrieval quality.
The types in this package form the canonical request/response shape used across the SDK. Concrete providers translate to and from these types so that higher-level code can remain backend-independent.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoProvider indicates the Client has no underlying Provider configured. ErrNoProvider = errors.New("rerank: no provider configured") // ErrInvalidRequest indicates the Request is malformed or missing // required fields (for example, no Model, empty Query, or empty Documents). ErrInvalidRequest = errors.New("rerank: invalid request") // unreachable or returned a transient failure. ErrProviderUnavailable = errors.New("rerank: provider unavailable") // ErrRateLimited indicates the upstream provider rejected the request // due to rate limiting or quota exhaustion. ErrRateLimited = errors.New("rerank: rate limited") // ErrAuthFailed indicates the provider rejected the supplied credentials. ErrAuthFailed = errors.New("rerank: authentication failed") // ErrUnsupported indicates the provider does not support a requested // capability. ErrUnsupported = errors.New("rerank: unsupported operation") )
Functions ¶
func ProviderOptionsFor ¶
ProviderOptionsFor extracts the provider-specific options bucket from a ProviderOptions map (typically Request.ProviderOptions) into a typed value.
providerName is the key used to namespace the bucket — by convention the provider's Provider.Name return value, e.g. "togetherai", "cohere".
Two input shapes are supported transparently:
- The bucket is already the typed Options struct (or a pointer to one) — it is returned as-is.
- The bucket is a map[string]any (e.g. constructed from JSON) — it is re-marshalled and decoded into T using encoding/json so that JSON tags on T's fields are honoured.
If po is nil or the providerName key is absent, the zero value of T is returned with a nil error.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a thin, provider-agnostic facade over a Provider. It centralises concerns that are independent of the underlying backend and provides a single entry point that higher-level code can depend on.
func NewClient ¶
NewClient returns a Client backed by the given Provider. The Provider may be nil; in that case the Client's methods will return ErrNoProvider.
type Provider ¶
type Provider interface {
// Name returns a short, stable identifier for the provider
// (for example, "togetherai", "cohere").
Name() string
// Rerank re-orders documents by relevance to the query.
Rerank(ctx context.Context, req Request) (Response, error)
}
Provider is implemented by reranking model backends. Implementations translate between the provider-agnostic types defined in this package and their underlying API.
type RankingItem ¶
type RankingItem struct {
// OriginalIndex is the index into [Request.Documents] this item
// came from (0-indexed).
OriginalIndex int `json:"original_index"`
// Score is the relevance score assigned by the model. Higher is
// more relevant. The score range is model-dependent.
Score float64 `json:"score"`
// Document is the document text (same as the input).
Document string `json:"document"`
}
RankingItem represents a single document in the ranked result set.
type Request ¶
type Request struct {
// Model identifies the reranking model to use.
Model string `json:"model"`
// Query is the search query to rank documents against.
Query string `json:"query"`
// Documents are the texts to rerank. Providers may also support
// structured documents (objects with text fields). For those cases
// the text content should be flattened into this slice.
Documents []string `json:"documents"`
// TopN limits the result to the top N documents. When 0 (or unset)
// all documents are returned in ranked order.
TopN int `json:"top_n,omitempty"`
// ProviderOptions carries provider-specific options.
ProviderOptions map[string]any `json:"provider_options,omitempty"`
}
Request is a provider-agnostic reranking request.
type Response ¶
type Response struct {
// Model identifies the model that produced this result.
Model string `json:"model,omitempty"`
// Ranking contains the ranked documents.
Ranking []RankingItem `json:"ranking"`
// Warnings contains non-fatal provider warnings.
Warnings []string `json:"warnings,omitempty"`
}
Response is the result of a reranking request. Items appear in descending order of relevance (highest Score first).
Source Files