retrieval

type CandidateSource ¶

type CandidateSource struct {
	ID         string
	ScoreSpace string
	Limit      int
	Weight     float64
}

CandidateSource describes one provider-neutral candidate source in a retrieval plan.

type ChunkResult ¶

type ChunkResult struct {
	Text       string
	Embedding  []float64
	Similarity float64
}

func BestChunk(queryEmbedding []float64, chunks []ChunkResult) ChunkResult

type ContextOption ¶ added in v0.11.0

type ContextOption func(*contextConfig)

ContextOption configures FormatContext.

func WithHeader(template string) ContextOption

func WithMaxTokens(maxTokens int, counter ContextTokenCounter) ContextOption

func WithSeparator(separator string) ContextOption

type ContextTokenCounter ¶ added in v0.11.0

type ContextTokenCounter interface {
	Count(text string) (int, error)
}

ContextTokenCounter counts tokens using the caller's provider and model policy.

type EvalQuery ¶

type EvalQuery struct {
	ID         string
	Relevant   map[string]float64
	TopicByDoc map[string]string
}

EvalQuery describes expected relevant documents for one retrieval query.

func EvalQueryFromFixture(fq FixtureQuery) EvalQuery

type Filter ¶

type Filter struct {
	IncludeExts []string
	IgnoreDirs  []string
	IgnoreExts  []string
}

func DefaultFilter() Filter

func (f Filter) Include(path string) bool

type Fixture ¶

type Fixture struct {
	ID          string
	Description string
	Queries     []FixtureQuery
}

Fixture is a caller-owned golden query set for deterministic retrieval quality reports.

type FixtureQuery ¶

type FixtureQuery struct {
	ID        string
	Text      string
	Judgments []Judgment
}

FixtureQuery is one golden query and its judged documents.

func (fq FixtureQuery) EvalQuery() EvalQuery

type FusionMode ¶

type FusionMode string

FusionMode labels how source candidate lists are combined. It is a caller contract only; this package does not execute provider queries or rerankers.

const (
	FusionModeNone     FusionMode = ""
	FusionModeRRF      FusionMode = "rrf"
	FusionModeWeighted FusionMode = "weighted"
)

type Judgment ¶

type Judgment struct {
	DocID     string
	Relevance float64
	Topic     string
	Segment   string
}

Judgment labels one document for a fixture query. Relevance values greater than zero are relevant; zero relevance can still provide topic or segment metadata for evaluated results.

type LayerReport ¶

type LayerReport struct {
	RelevantCount       int
	CandidateCount      int
	CandidateHitCount   int
	CandidateRecall     float64
	CandidateMetrics    Metrics
	RerankMetrics       Metrics
	DiversifiedMetrics  Metrics
	FinalMetrics        Metrics
	DiversityLiftAtK    int
	FinalDeltaRecallAtK float64
}

LayerReport separates candidate generation, reranking, diversification, and final top-k quality so retrieval regressions can be localized to one stage.

func EvaluateLayers(query EvalQuery, layers LayeredResults, k int) LayerReport

type LayeredResults ¶

type LayeredResults struct {
	Candidates  []RankedResult
	Reranked    []RankedResult
	Diversified []RankedResult
	Final       []RankedResult
}

LayeredResults carries ranked result lists captured at each retrieval stage. Empty slices are valid and report zero metrics for that layer.

type MMRExplanation ¶ added in v0.11.0

type MMRExplanation struct {
	Lambda                float64
	Relevance             float64
	MaxSimilarity         float64
	RelevanceContribution float64
	Penalty               float64
	SelectionScore        float64
}

MMRExplanation describes one maximal-marginal-relevance selection. MaxSimilarity is the maximum positive cosine similarity to a previously selected item; missing, orthogonal, and negatively correlated embeddings contribute zero. Penalty is signed and is therefore zero or negative.

type MMRItem ¶

type MMRItem struct {
	ID        string
	Score     float64
	Embedding []float64
	Topic     string
}

MMRItem represents an item participating in MMR diversification.

func MMR(items []MMRItem, k int, lambda float64) []MMRItem

package main

import (
	"fmt"

	"github.com/dotcommander/reliquary/retrieval"
)

func main() {
	// Diversify items to avoid returning multiple identical documents
	items := []retrieval.MMRItem{
		{
			ID:        "doc1",
			Score:     0.95,
			Embedding: []float64{0.1, 0.2, 0.3},
		},
		{
			ID:        "doc2", // Highly redundant with doc1 (identical embedding)
			Score:     0.92,
			Embedding: []float64{0.1, 0.2, 0.3},
		},
		{
			ID:        "doc3", // Lower score but different topic
			Score:     0.75,
			Embedding: []float64{0.9, 0.1, 0.0},
		},
	}

	// k = 2, lambda = 0.5 (equal balance of relevance and diversity)
	diversified := retrieval.MMR(items, 2, 0.5)

	for _, item := range diversified {
		fmt.Printf("- %s (Score: %.2f)\n", item.ID, item.Score)
	}
}

Output:
- doc1 (Score: 0.95)
- doc3 (Score: 0.75)

func MMRItems(results []*Result) []MMRItem

type Metadata ¶

type Metadata struct {
	Title    string
	Headings []string
	Path     string
}

func ExtractMetadata(path string, content string) Metadata

type Metrics ¶

type Metrics struct {
	RecallAtK      float64
	PrecisionAtK   float64
	MRR            float64
	NDCGAtK        float64
	UniqueTopicAtK int
}

Metrics summarizes retrieval quality for a ranked result list.

func Evaluate(query EvalQuery, results []RankedResult, k int) Metrics

type Plan ¶

type Plan struct {
	ID             string
	Sources        []CandidateSource
	Fusion         FusionMode
	RerankLabel    string
	DiversifyLabel string
	Budgets        []StageBudget
	Identity       hash.Digest
}

Plan describes source budgets and stage labels for a retrieval run.

type PlanRun ¶

type PlanRun struct {
	Plan    Plan
	QueryID string
	Sources []SourceReport
	Layers  LayeredResults
	Report  LayerReport
}

PlanRun captures the observed outputs for a retrieval plan.

func EvaluatePlan(query EvalQuery, plan Plan, layers LayeredResults, sources []SourceReport, k int) PlanRun

package main

import (
	"fmt"

	"github.com/dotcommander/reliquary/retrieval"
)

func main() {
	query := retrieval.EvalQuery{
		ID:       "q1",
		Relevant: map[string]float64{"doc1": 1, "doc3": 1},
	}
	plan := retrieval.Plan{
		ID:     "hybrid",
		Fusion: retrieval.FusionModeRRF,
		Sources: []retrieval.CandidateSource{
			{ID: "lexical", ScoreSpace: "local_bm25", Limit: 2},
			{ID: "vector", ScoreSpace: "cosine", Limit: 2},
		},
	}
	sources := []retrieval.SourceReport{
		{Source: plan.Sources[0], Results: []retrieval.RankedResult{{ID: "doc1"}, {ID: "doc2"}}},
		{Source: plan.Sources[1], Results: []retrieval.RankedResult{{ID: "doc3"}, {ID: "doc4"}}},
	}
	layers := retrieval.LayeredResults{
		Candidates: []retrieval.RankedResult{{ID: "doc1"}, {ID: "doc2"}, {ID: "doc3"}, {ID: "doc4"}},
		Final:      []retrieval.RankedResult{{ID: "doc1"}, {ID: "doc3"}},
	}

	run := retrieval.EvaluatePlan(query, plan, layers, sources, 2)
	fmt.Println(run.Report.CandidateRecall, run.Sources[0].CandidateRecall)
}

Output:
1 0.5

type RRFExplanation ¶ added in v0.11.0

type RRFExplanation struct {
	K                   float64
	VectorRank          int
	LexicalRank         int
	VectorContribution  float64
	LexicalContribution float64
	FusedScore          float64
	FusedRank           int
}

RRFExplanation describes reciprocal-rank fusion for one result. A zero lane rank and contribution mean that the result was absent from that lane.

type RankedResult ¶

type RankedResult struct {
	ID    string
	Score float64
	Topic string
}

RankedResult is a scored retrieval result for metric evaluation.

type Report ¶

type Report struct {
	FixtureID  string
	RunID      string
	K          int
	QueryCount int
	Metrics    Metrics
	Queries    []ReportQuery
}

Report is the aggregate and per-query fixture evaluation output.

func EvaluateRun(f Fixture, r Run, k int) (Report, error)

type ReportQuery ¶

type ReportQuery struct {
	ID       string
	Metrics  Metrics
	Segments []SegmentMetrics
	Layers   LayerReport
}

ReportQuery is the per-query portion of a fixture evaluation report.

type ReportThresholds ¶

type ReportThresholds struct {
	MinRecallAtK       float64
	MinPrecisionAtK    float64
	MinMRR             float64
	MinNDCGAtK         float64
	MinUniqueTopicsAtK int
}

ReportThresholds declares aggregate metric floors for CheckThresholds.

type Reranker ¶ added in v0.11.0

type Reranker interface {
	Rerank(ctx context.Context, query string, candidates []*Result) ([]float64, error)
}

Reranker assigns an external relevance score to each candidate for a query. Returned scores correspond positionally to candidates.

Separate Search calls may invoke the same Reranker concurrently. Implementations that are not concurrency-safe must provide their own synchronization.

type RerankerExplanation ¶ added in v0.11.0

type RerankerExplanation struct {
	InputRank int
	Score     float64
	Rank      int
}

RerankerExplanation describes the observable input and output of an external reranker. The Reranker interface does not expose model-internal reasoning.

type Result ¶

type Result struct {
	ID              string
	IndexIdentity   string
	DocumentID      string
	Content         string
	Filename        string
	Metadata        map[string]any
	Embedding       []float64
	EmbeddingScore  float64
	KeywordScore    float64
	FilenameScore   float64
	RecencyScore    float64
	ImportanceScore float64
	CombinedScore   float64
	Explain         *SearchExplanation
}

Result represents a scored item.

RecencyScore and ImportanceScore are caller-supplied, already-normalized 0..1 values. Unlike EmbeddingScore/KeywordScore/FilenameScore they are NOT corpus min-max calibrated by Rerank: importance is an absolute salience tier and recency is an absolute time-decay, so corpus-relative rescaling would distort their meaning. Map your own importance tier (e.g. 1..5) or timestamp age (see RecencyFromAge) into 0..1 before assigning. Explain is ephemeral facade output and is nil unless reliquary.WithExplain was requested.

func Diversify(results []*Result, k int, lambda float64) []*Result

func ResultsFromDocuments(docs []document.Document, strategy chunking.Strategy, size, overlap int) ([]*Result, error)

type Run ¶

type Run struct {
	ID      string
	Queries []RunQuery
}

Run is a captured retrieval run to evaluate against a Fixture.

type RunQuery ¶

type RunQuery struct {
	ID      string
	Results []RankedResult
	Stages  StageResults
}

RunQuery contains the primary ranked results and optional stage outputs for one fixture query.

type ScoreBand ¶

type ScoreBand string

const (
	BandWeak   ScoreBand = "weak"
	BandMedium ScoreBand = "medium"
	BandStrong ScoreBand = "strong"
)

func Band(score float64) ScoreBand

type ScoreComponents ¶

type ScoreComponents struct {
	Semantic float64
	Keyword  float64
	Filename float64
	Metadata float64
}

type ScoreReference ¶

type ScoreReference struct {
	Version   int
	CreatedAt time.Time
	Identity  ScoreReferenceIdentity
	Values    []float64
}

ScoreReference stores a sorted production/reference score cohort. Callers can persist this data in their own format and map future raw scores to stable cohort-relative percentiles with Percentile.

func FitScoreReference(values []float64, identity ScoreReferenceIdentity) (ScoreReference, error)

func (reference ScoreReference) Percentile(score float64) float64

func (reference ScoreReference) Validate(expected ScoreReferenceIdentity) error

type ScoreReferenceIdentity ¶

type ScoreReferenceIdentity struct {
	ScoreVersion string
	ModelID      string
	SchemaHash   string
	ConfigHash   string
}

ScoreReferenceIdentity describes scoring inputs that invalidate a reference distribution when they change. Zero fields are ignored by Validate.

type ScoreSignals ¶

type ScoreSignals struct {
	Embedding  float64
	Keyword    float64
	Filename   float64
	Recency    float64
	Importance float64
}

ScoreSignals groups retrieval signal values.

type ScoreTrace ¶

type ScoreTrace struct {
	ID              string
	QueryTokenCount int
	AdaptiveWeights bool
	Present         SignalPresence
	Weights         Weights
	Raw             ScoreSignals
	Calibrated      ScoreSignals
	Contributions   ScoreSignals
	CombinedScore   float64
}

ScoreTrace explains how a result's CombinedScore was produced.

Raw contains pre-calibration text/vector scores plus caller-supplied salience scores. Calibrated contains the values actually multiplied by Weights. Contributions is Calibrated multiplied by Weights per signal.

type Scorer ¶

type Scorer struct {
	// contains filtered or unexported fields
}

Scorer computes hybrid relevance scores.

func NewScorer(weights Weights) *Scorer

func NewScorerOpts(opts ...WeightOption) *Scorer

func NewScorerWithOptions(weights Weights, adaptiveWeights bool) *Scorer

func (s *Scorer) Rerank(queryEmbedding []float64, queryText string, results []*Result) []*Result

package main

import (
	"fmt"

	"github.com/dotcommander/reliquary/retrieval"
)

func main() {
	scorer := retrieval.NewScorer(retrieval.DefaultWeights())

	// Example data (embeddings must match dimensional lengths)
	queryEmb := []float64{0.1, 0.2, 0.3}
	results := []*retrieval.Result{
		{
			ID:        "doc1",
			Content:   "machine learning algorithms and modeling",
			Filename:  "machine-learning.md",
			Embedding: []float64{0.12, 0.18, 0.31},
		},
		{
			ID:        "doc2",
			Content:   "italian pizza baking recipe",
			Filename:  "cooking.md",
			Embedding: []float64{0.85, 0.05, 0.10},
		},
	}

	ranked := scorer.Rerank(queryEmb, "machine learning", results)

	for _, r := range ranked {
		fmt.Printf("- %s: Score %.4f (Embedding: %.4f, Keyword: %.4f)\n", r.ID, r.CombinedScore, r.EmbeddingScore, r.KeywordScore)
	}
}

Output:
- doc1: Score 1.0000 (Embedding: 1.0000, Keyword: 1.0000)
- doc2: Score 0.0000 (Embedding: 0.0000, Keyword: 0.0000)

func (s *Scorer) RerankEmbedding(queryEmbedding embedding.Vector, queryText string, results []*Result) []*Result

func (s *Scorer) RerankWithReference(queryEmbedding []float64, queryText string, results []*Result, reference ScoreReference) []*Result

func (s *Scorer) RerankWithTrace(queryEmbedding []float64, queryText string, results []*Result) ([]*Result, []ScoreTrace)

func (s *Scorer) Score(queryEmbedding []float64, queryText string, result *Result) float64

type SearchExplanation ¶ added in v0.11.0

type SearchExplanation struct {
	Hybrid          ScoreTrace
	HybridRank      int
	HybridScoreUsed bool
	RRF             *RRFExplanation
	Reranker        *RerankerExplanation
	MMR             *MMRExplanation
	FinalRank       int
}

SearchExplanation describes how a retained search candidate moved through Reliquary's ranking stages. It is populated only for searches using reliquary.WithExplain and is not persistent index data.

type SegmentMetrics ¶

type SegmentMetrics struct {
	Segment       string
	Metrics       Metrics
	RelevantCount int
	ResultCount   int
	HitCount      int
}

SegmentMetrics summarizes retrieval quality for one segment. RelevantCount counts relevant documents assigned to the segment, ResultCount counts top-k results assigned to the segment, and HitCount counts top-k results that are relevant within the segment.

func EvaluateSegments(query EvalQuery, results []RankedResult, k int, segmenter Segmenter) []SegmentMetrics

type Segmenter ¶

type Segmenter func(docID string) string

Segmenter maps a document ID to a caller-owned evaluation segment. Returning an empty string excludes the document from segment summaries.

type SignalPresence ¶

type SignalPresence struct {
	Embedding  bool
	Keyword    bool
	Filename   bool
	Recency    bool
	Importance bool
}

SignalPresence reports which signals had usable inputs for a scored result.

type SourceReport ¶

type SourceReport struct {
	Source          CandidateSource
	Results         []RankedResult
	CandidateCount  int
	HitCount        int
	CandidateRecall float64
	Metrics         Metrics
}

SourceReport captures ranked output and metrics for one candidate source.

func EvaluateSource(query EvalQuery, report SourceReport, k int) SourceReport

type StageBudget ¶

type StageBudget struct {
	Stage string
	Limit int
}

StageBudget describes a limit for a named retrieval stage.

type StageResults ¶

type StageResults = LayeredResults

StageResults aliases the existing layered retrieval stage shape.

type ThresholdFailure ¶

type ThresholdFailure struct {
	Metric string
	Got    float64
	Want   float64
}

ThresholdFailure reports one aggregate metric below its configured floor.

func CheckThresholds(report Report, thresholds ReportThresholds) []ThresholdFailure

type TuneCandidate ¶

type TuneCandidate struct {
	ID        string
	Signals   ScoreSignals
	Embedding []float64
	Topic     string
}

TuneCandidate is a precomputed candidate row for retrieval tuning. Signals are already normalized into caller-owned comparable spaces.

type TuneCase ¶

type TuneCase struct {
	Query      EvalQuery
	Candidates []TuneCandidate
}

TuneCase is one labeled retrieval query and its candidate set.

type TuneConfig ¶

type TuneConfig struct {
	K           int
	Weights     []Weights
	MMRLambdas  []float64
	Constraints TuneConstraints
}

TuneConfig configures deterministic grid search over weights and optional MMR lambdas. Empty MMRLambdas evaluates plain weighted ranking only.

type TuneConstraints ¶

type TuneConstraints struct {
	MinRecallAtK       float64
	MinNDCGAtK         float64
	MinUniqueTopicsAtK int
}

TuneConstraints reject grid configurations that fail required floor metrics.

type TuneReport ¶

type TuneReport struct {
	Results []TuneResult
	Best    TuneResult
	HasBest bool
}

TuneReport contains all grid results plus the best non-rejected result.

func TuneWeights(cases []TuneCase, config TuneConfig) TuneReport

type TuneResult ¶

type TuneResult struct {
	Weights      Weights
	MMRLambda    float64
	UsedMMR      bool
	Metrics      Metrics
	QueryCount   int
	Rejected     bool
	RejectReason string
}

TuneResult reports one grid configuration's aggregate metrics and rejection state.

type WeightOption ¶

type WeightOption func(*Weights)

WeightOption adjusts a Weights value for NewScorerOpts.

func Embedding(v float64) WeightOption

func Filename(v float64) WeightOption

func Importance(v float64) WeightOption

func Keyword(v float64) WeightOption

func Recency(v float64) WeightOption

type Weights ¶

type Weights struct {
	Embedding  float64
	Keyword    float64
	Filename   float64
	Recency    float64
	Importance float64
}

Weights configures relative importance of scoring signals.

Recency and Importance are optional salience axes orthogonal to textual similarity. They default to 0 (DefaultWeights/AdaptiveWeights leave them unset), so callers that supply only Embedding/Keyword/Filename signals produce exactly the same CombinedScore as before these fields existed.

func AdaptiveWeights(queryTokenCount int) Weights

func DefaultWeights() Weights