reranker

package
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 3, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package reranker provides the Reranker agent that uses tool calls to select the most relevant topics from vector search candidates.

Package reranker implements agentic RAG candidate filtering using Flash LLM.

The reranker receives top-N vector search candidates and intelligently selects the most relevant ones for the current query context.

Architecture: 

Input: 50 candidates (topics + people + artifacts)
  ↓
Turn 1: Flash sees summaries (~3K tokens), calls get_topics_content([ids])
  ↓
Turn 2: Flash receives full content of requested topics
  ↓
Output: Selected IDs with reasons (JSON response)

Key Features:

  • Agentic: Flash decides what to examine via tool calls
  • Multimodal: Supports images/audio in query for better filtering
  • Fallback: Returns vector top-N on timeout/error
  • Reasons: Each selection includes explanation

Result Format: 

{"topics": [{"id": 42, "reason": "..."}, ...], "people": [...], "artifacts": [...]}

Supported Candidate Types:

  • Topic: Conversation summaries with message counts
  • Person: Social graph entries with similarity scores
  • Artifact: File metadata (images, PDFs, voice)

Configuration:

  • Agents.Reranker.Enabled: Enable/disable reranker
  • Agents.Reranker.Model: LLM model (default: gemini-3-flash-preview)
  • Agents.Reranker.Candidates: Max candidates to show (default 50)
  • Agents.Reranker.Timeout: Total timeout for reranker flow
  • Agents.Reranker.MaxTopics: Max topics in selection (default 15)
  • Agents.Reranker.MaxPeople: Max people in selection (default 10)
  • Agents.Reranker.Artifacts.Max: Max artifacts in selection (default 10)

Fallback Strategy:

  1. If Flash returns valid JSON → use it
  2. If Flash made tool calls but invalid JSON → use requested IDs (top-5)
  3. If timeout before tools → use vector top-5
  4. If API error → use vector top-5

Thread Safety:

  • Reranker.Execute() is thread-safe (no shared state)
  • Each call creates fresh request/response

Package reranker provides the Reranker agent that uses tool calls to select the most relevant topics from vector search candidates.

Package reranker provides the Reranker agent that uses tool calls to select the most relevant topics from vector search candidates.

Package reranker provides the Reranker agent that uses tool calls to select the most relevant topics from vector search candidates.

Package reranker provides the Reranker agent that uses tool calls to select the most relevant topics from vector search candidates.

Package reranker provides the Reranker agent that uses tool calls to select the most relevant topics from vector search candidates.

Index

Constants

View Source 
const (
	// ParamCandidates is the key for reranker candidates ([]Candidate).
	ParamCandidates = "candidates"
	// ParamPersonCandidates is the key for person candidates ([]PersonCandidate) (v0.5.1).
	ParamPersonCandidates = "person_candidates"
	// ParamArtifactCandidates is the key for artifact candidates ([]ArtifactCandidate) (v0.6.0).
	ParamArtifactCandidates = "artifact_candidates"
	// ParamContextualizedQuery is the key for enriched query (string).
	ParamContextualizedQuery = "contextualized_query"
	// ParamOriginalQuery is the key for original user query (string).
	ParamOriginalQuery = "original_query"
	// ParamCurrentMessages is the key for recent conversation (string).
	ParamCurrentMessages = "current_messages"
	// ParamMediaParts is the key for multimodal content ([]interface{}).
	ParamMediaParts = "media_parts"
)

Request parameters for Reranker agent.

Variables

This section is empty.

Functions

func FormatPeopleForReranker added in v0.6.1 

func FormatPeopleForReranker(candidates []PersonCandidate) string

FormatPeopleForReranker formats person candidates for the LLM prompt (v0.5.1). Delegates to storage.FormatPeople for consistent formatting.

Types

type ArtifactCandidate added in v0.6.0 

type ArtifactCandidate struct {
	ArtifactID   int64
	Score        float32
	FileType     string
	OriginalName string
	Summary      string
	Keywords     []string
	Entities     []string // Named entities (people, companies, code mentioned)
	RAGHints     []string // Questions this artifact might answer
}

ArtifactCandidate is an artifact candidate for reranking (v0.6.0).

type ArtifactSelection added in v0.6.0 

type ArtifactSelection struct {
	Reason string `json:"reason"`
	ID     string `json:"id"` // Format: "Artifact:N"
}

ArtifactSelection represents a selected artifact with explanation (v0.6.0). ID is stored as string with prefix "Artifact:N" for unified ID format.

func (*ArtifactSelection) GetNumericID added in v0.6.0 

func (a *ArtifactSelection) GetNumericID() (int64, error)

GetNumericID extracts numeric ID from "Artifact:N" format.

type Candidate 

type Candidate struct {
	TopicID      int64
	Score        float32
	Topic        storage.Topic
	MessageCount int
	SizeChars    int // Estimated: MessageCount * avgCharsPerMessage
}

Candidate is a topic candidate for reranking.

type MessageRepository 

type MessageRepository interface {
	GetMessagesByTopicID(ctx context.Context, topicID int64) ([]storage.Message, error)
}

MessageRepository is the interface for loading topic messages.

type PersonCandidate added in v0.5.1 

type PersonCandidate struct {
	PersonID int64
	Score    float32
	Person   storage.Person
}

PersonCandidate is a person candidate for reranking (v0.5.1).

type PersonSelection added in v0.5.1 

type PersonSelection struct {
	Reason string `json:"reason"`
	ID     string `json:"id"` // Format: "Person:N"
}

PersonSelection represents a selected person with explanation (v0.5.1). ID is stored as string with prefix "Person:N" for unified ID format.

func (*PersonSelection) GetNumericID added in v0.5.4 

func (p *PersonSelection) GetNumericID() (int64, error)

GetNumericID extracts numeric ID from "Person:N" format.

type ReasoningEntry 

type ReasoningEntry struct {
	Iteration int    `json:"iteration"`
	Text      string `json:"text"`
}

ReasoningEntry holds reasoning text for one iteration.

type Reranker 

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

Reranker uses tool calls to select the most relevant topics from vector search candidates.

func New 

func New(
	client openrouter.Client,
	cfg *config.Config,
	logger *slog.Logger,
	translator *i18n.Translator,
	msgRepo MessageRepository,
	agentLogger *agentlog.Logger,
) *Reranker

New creates a new Reranker agent.

func (*Reranker) Capabilities 

func (r *Reranker) Capabilities() agent.Capabilities

Capabilities returns the agent's capabilities.

func (*Reranker) Description 

func (r *Reranker) Description() string

Description returns a human-readable description.

func (*Reranker) Execute 

func (r *Reranker) Execute(ctx context.Context, req *agent.Request) (*agent.Response, error)

Execute runs the reranker with the given request. Required params: candidates, contextualized_query, original_query, current_messages Optional params: media_parts, person_candidates (v0.5.1), artifact_candidates (v0.6.0) Uses SharedContext for user_profile and recent_topics if available.

func (*Reranker) Type 

func (r *Reranker) Type() agent.AgentType

Type returns the agent type.

type RerankerResultBuilder added in v0.6.1 

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

RerankerResultBuilder builds Result objects for testing.

func NewRerankerResultBuilder added in v0.6.1 

func NewRerankerResultBuilder() *RerankerResultBuilder

NewRerankerResultBuilder creates a new RerankerResultBuilder.

func (*RerankerResultBuilder) Build added in v0.6.1 

func (b *RerankerResultBuilder) Build() *Result

Build returns the constructed Result.

func (*RerankerResultBuilder) WithArtifactWithReason added in v0.6.1 

func (b *RerankerResultBuilder) WithArtifactWithReason(id int64, reason string) *RerankerResultBuilder

WithArtifactWithReason adds an artifact with explanation.

func (*RerankerResultBuilder) WithPersonWithReason added in v0.6.1 

func (b *RerankerResultBuilder) WithPersonWithReason(id int64, reason string) *RerankerResultBuilder

WithPersonWithReason adds a person with explanation.

func (*RerankerResultBuilder) WithTopicWithReason added in v0.6.1 

func (b *RerankerResultBuilder) WithTopicWithReason(id int64, reason string) *RerankerResultBuilder

WithTopicWithReason adds a topic with explanation.

func (*RerankerResultBuilder) WithTopics added in v0.6.1 

func (b *RerankerResultBuilder) WithTopics(ids ...int64) *RerankerResultBuilder

WithTopics adds topic IDs (backward compatible format).

type Result 

type Result struct {
	Topics    []TopicSelection    // Final selected topics with reasons
	People    []PersonSelection   // Final selected people with reasons (v0.5.1)
	Artifacts []ArtifactSelection // Final selected artifacts with reasons (v0.6.0)
}

Result contains the output of the reranker.

func (*Result) ArtifactIDs added in v0.6.0 

func (r *Result) ArtifactIDs() []int64

ArtifactIDs returns just the artifact IDs (v0.6.0).

func (*Result) PeopleIDs 

func (r *Result) PeopleIDs() []int64

PeopleIDs returns just the person IDs (v0.5.1).

func (*Result) TopicIDs 

func (r *Result) TopicIDs() []int64

TopicIDs returns just the topic IDs (for backward compatibility).

type TopicSelection 

type TopicSelection struct {
	Reason string `json:"reason"`
	ID     string `json:"id"` // Format: "Topic:N"
}

TopicSelection represents a selected topic with explanation. ID is stored as string with prefix "Topic:N" for unified ID format.

func (*TopicSelection) GetNumericID added in v0.5.4 

func (t *TopicSelection) GetNumericID() (int64, error)

GetNumericID extracts numeric ID from "Topic:N" format.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.