retrieval

type ActionType string

type AgentAction struct {
	Type  ActionType // which branch to execute next
	Query string     // refined sub-query for the retrieve action (empty for reflect/finish)
}

type AgentActionSelector interface {
	SelectAction(ctx context.Context, query, reasoning string, iteration, maxIterations int) (*AgentAction, error)
}

type AgentReasoner interface {
	Reason(ctx context.Context, query string, retrieved [][]*entity.Chunk, answer string) (reasoning string, err error)
}

type AgenticMetadata = entity.AgenticMetadata

type CRAGEvaluation struct {
	Relevance float32
	Label     CRAGLabel
	Reason    string
}

type CRAGEvaluator interface {
	Evaluate(ctx context.Context, query *entity.Query, chunks []*entity.Chunk) (*CRAGEvaluation, error)
}

type CRAGLabel string

type DecompositionResult struct {
	SubQueries []string
	Reasoning  string
	IsComplex  bool
}

type EntityExtractionResult struct {
	Entities []string
}

type EntityExtractor interface {
	Extract(ctx context.Context, query *entity.Query) (*EntityExtractionResult, error)
}

type FilterExtractor interface {
	ExtractFilters(ctx context.Context, query *entity.Query) (map[string]any, error)
}

type FusionEngine interface {
	// ReciprocalRankFusion (RRF) merges results from different modalities
	// (e.g., Sparse + Dense, or Vector + Graph) and re-ranks them based on their reciprocal positions.
	ReciprocalRankFusion(ctx context.Context, resultSets [][]*entity.Chunk, topK int) ([]*entity.Chunk, error)
}

type GenerationResult struct {
	Answer string
}

type Generator interface {
	Generate(ctx context.Context, query *entity.Query, chunks []*entity.Chunk) (*GenerationResult, error)
}

type GraphGlobalSearcher interface {
	// Search performs a Map-Reduce over community summaries at a specific hierarchical level.
	Search(ctx context.Context, query string, communityLevel int) (string, error)
}

type GraphLocalSearcher interface {
	// Search returns a textual description of the N-Hop relationship sub-graph.
	Search(ctx context.Context, entities []string, maxHops int, topK int) (string, error)
}

type HyDEGenerator interface {
	GenerateHypotheticalDocument(ctx context.Context, query *entity.Query) (*entity.Document, error)
}

type IntentClassifier interface {
	Classify(ctx context.Context, query *entity.Query) (*IntentResult, error)
}

type IntentResult struct {
	Intent     IntentType
	Confidence float32
	Reason     string
}

type IntentType string

type QueryDecomposer interface {
	Decompose(ctx context.Context, query *entity.Query) (*DecompositionResult, error)
}

type QueryRewriter interface {
	Rewrite(ctx context.Context, query *entity.Query) (*entity.Query, error)
}

type RAGEScores = entity.RAGEScores

type RAGEvaluator interface {
	Evaluate(ctx context.Context, query, answer, context string) (*RAGEScores, error)
}

type ResultEnhancer interface {
	Enhance(ctx context.Context, results *entity.RetrievalResult) (*entity.RetrievalResult, error)
}

type RetrievalResult struct {
	Chunks []*entity.Chunk
	Scores []float32
}

type Retriever interface {
	Retrieve(ctx context.Context, queries []string, topK int) ([]*RetrievalResult, error)
}

type StepBackGenerator interface {
	GenerateStepBackQuery(ctx context.Context, query *entity.Query) (*entity.Query, error)
}