retrieve

type BodySegment struct {
	StartLine int
	Lines     int
}

type Embedder interface {
	Embed(ctx context.Context, texts []string) ([][]float32, error)
}

type FlowRef struct {
	QualifiedName string
	File          string
	Lines         string
	Kind          string
	Distance      int
	Via           string
}

type Graph struct {
	NumNodes int
	NodeIdx  map[int64]int
	NodeIDs  []int64
	OutEdges [][]int
}

type IntentRanker interface {
	Ranker
	IsIntentRanker()
}

type Mode int

type NextStepsHints struct {
	IfTopCorrect string
	IfUnsure     string
	ToExplore    []string
}

type OutputMode int

type Ranker interface {
	Rank(query string, candidates []ScoredResult) []ScoredResult
}

type RankingFeatures struct {
	VectorSeed       float32
	FTSSeed          float32
	PPR              float32
	EffectiveAlpha   float32
	SeedScore        float32
	PPRScore         float32
	SeedRank         int
	PPRRank          int
	ShortNameOverlap float32
	NameOverlap      float32
	PathOverlap      float32
	KindOverlap      float32
	SignatureOverlap float32
	BodyOverlap      float32
	IsConstructor    float32
	KindFunction     float32
	KindMethod       float32
	HubPenalty       float32
}

type RelatedFile struct {
	File    string
	Symbols []string
	Shared  []string // the rare names that put it here, best evidence first
	Score   float64
}

type Request struct {
	Query        string
	BudgetTokens int
	SeedK        int
	MaxResults   int
	RerankK      int
	// AnchorExpand adds this many 1-hop graph neighbours of the top seeds to the
	// candidate pool (0 = off).
	AnchorExpand int
	// TestFloor reserves this many top answer slots for non-test files (0 = off).
	// Tests keep their order behind them, so they fill what implementation
	// candidates leave empty. See internal/retrieve/testfloor.go.
	TestFloor int
	// LiteralSlots hands this many of the last answer slots to files where
	// several of the query's identifiers occur together (0 = off). Worth
	// switching on when the index holds test files; see internal/retrieve/literal.go.
	LiteralSlots   int
	AdaptiveRerank bool
	// LazyRerank inverts the reranking default: the cross-encoder runs only
	// when the fused ranking is ambiguous (small gap / several near-ties),
	// instead of on every query.
	LazyRerank bool
	// FullBodyResults caps how many top results keep their full body in the
	// packed response (0 = default 3, negative = all results keep bodies).
	FullBodyResults int
	// PreserveFullBodies disables query-relevant evidence trimming. Serving
	// paths set it only for an explicit full_bodies compatibility override;
	// normal navigation uses excerpts and expand_context for exact hydration.
	PreserveFullBodies bool
	Mode               Mode
	OutputMode         OutputMode
	Alpha              float32
	AlphaSet           bool
	IncludeTrivial     bool
	SkipRerank         bool
	SkipIntent         bool
}

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

type Result struct {
	Symbols         []ScoredResult
	TotalTokens     int
	Stats           Stats
	Structure       *StructureView
	NextSteps       *NextStepsHints
	RetrievalHealth *RetrievalHealth
	// ExpansionSymbols is an internal snapshot of the selected ranked symbols
	// before tiering and evidence trimming. MCP caches it by request_id so
	// expand_context can hydrate an already-found symbol without rerunning
	// embedding, graph ranking, or reranking.
	ExpansionSymbols []ScoredResult
}

type RetrievalHealth struct {
	CandidatesSeen int
	TopScoreGap    float32
	TiedCandidates int
	Confidence     string
	Suggestion     string
}

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

type ScoredResult struct {
	SymbolID      int64
	File          string
	QualifiedName string
	Kind          string
	Signature     string
	Docstring     string
	StartLine     int
	EndLine       int
	Score         float32
	Body          string
	Why           string
	AlsoVia       []string
	Features      RankingFeatures

	// Relevance is the cross-encoder's own score (sigmoid, 0..1) for this
	// query/document pair — set only when the reranker ran. Score, by
	// contrast, accumulates ranking bonuses (intent priors add up to ~+4),
	// which makes it useless as an absolute "is this actually a match"
	// signal. 0 means "no cross-encoder verdict" (rerank skipped or failed).
	Relevance float32

	// Detail marks how much of the symbol the packed Body carries:
	// "full" (complete indexed body), "excerpt" (a query-relevant source
	// window), or "compact" (signature + doc line).
	Detail string

	// BodyStartLine is the real file line number of the first line of Body. It
	// equals StartLine unless an evidence-span trim moved the body window down,
	// in which case it lets the output number the trimmed lines correctly.
	BodyStartLine int
	// BodyEndLine is the real file line number of the last visible Body line.
	// It differs from EndLine when Detail is "excerpt".
	BodyEndLine int

	// CallersTotal and CalleesTotal are how many graph edges exist before the
	// display cap. Showing five of thirty without saying so is how the hop an
	// agent came for goes missing in silence.
	CallersTotal int
	CalleesTotal int

	// BodySegments describes the windows Body carries when the evidence trim
	// keeps more than one. Body joins them with evidenceGapMarker; the segments
	// carry each window's real first line so numbering stays honest across the
	// gap. Empty means one contiguous span starting at BodyStartLine.
	BodySegments []BodySegment

	Confidence string
	Callers    []SymbolRef
	Callees    []SymbolRef

	Visibility     string
	Tests          []SymbolRef
	Siblings       []SymbolRef
	FlowContext    []FlowRef
	CompanionFiles []string
}

type Stats struct {
	SeedCount         int
	GraphNodes        int
	GraphEdges        int
	PPRIterations     int
	EmbedDuration     time.Duration
	SeedDuration      time.Duration
	GraphDuration     time.Duration
	PPRDuration       time.Duration
	RerankDuration    time.Duration
	IntentDuration    time.Duration
	EscalateDuration  time.Duration
	Escalated         bool
	RerankLazySkipped bool
	PackDuration      time.Duration
	EvidenceDuration  time.Duration
	// GraphCtxDuration covers the callers/callees/tests/siblings SQL
	// enrichment of the selected results (not the PPR graph itself).
	GraphCtxDuration time.Duration
	Total            time.Duration
	EffectiveAlpha   float32
}

type Store interface {
	SearchByVectorScored(ctx context.Context, vec []float32, k int) ([]store.ScoredSymbol, error)
	SearchByText(ctx context.Context, query string, k int) ([]store.ScoredSymbol, error)
	SearchByBodyText(ctx context.Context, query string, k int) ([]store.ScoredSymbol, error)
	SearchByChunkVector(ctx context.Context, vec []float32, k int) ([]store.ScoredSymbol, error)
	GetSymbolsByIDs(ctx context.Context, ids []int64) ([]store.Symbol, error)
	GetSymbolBody(ctx context.Context, symbolID int64) (store.SymbolBody, error)
	GetFilesByIDs(ctx context.Context, ids []int64) (map[int64]string, error)
	ListAllSymbolIDs(ctx context.Context) ([]int64, error)
	ListSymbolMeta(ctx context.Context) ([]store.Symbol, error)
	ListAllEdges(ctx context.Context) ([]store.Edge, error)
	GetEmbeddingsByIDs(ctx context.Context, ids []int64) (map[int64][]float32, error)
	GetCallerEdges(ctx context.Context, dstIDs []int64, limitPerSymbol int) (map[int64][]int64, error)
	GetCalleeEdges(ctx context.Context, srcIDs []int64, limitPerSymbol int) (map[int64][]int64, error)
}

type StructureView struct {
	Summary     string
	PackageView map[string][]string
}

type SymbolRef struct {
	QualifiedName string
	File          string
	Lines         string
	Kind          string
	// CallLine is the file line of the call site: for a callee, where the result
	// symbol calls it; for a caller, where that caller calls the result symbol.
	// 0 when not located. Lets the agent follow a call chain without opening files.
	CallLine int
	// PathStatus is "static_unverified" for call-graph edges. Extractors prove
	// that the call exists in source, not that its surrounding branch executes.
	PathStatus string
	// CallSite is a bounded, line-numbered source window around CallLine. It is
	// populated for top-result graph refs so agents can inspect nearby branch or
	// dispatch conditions without paying for every related symbol body.
	CallSite string
}

type TextScorer interface {
	ScoreTexts(ctx context.Context, query string, docs []string) ([]float32, error)
}