semantic

type BudgetReport struct {
	Milliseconds int64 `json:"milliseconds"`
	Exhausted    bool  `json:"exhausted"`
}

type CacheEntry struct {
	Key    CacheKey
	Vector []float32
}

type CacheKey struct {
	Model           string
	DocumentVersion string
	ContentHash     string
}

type CandidateRepository interface {
	CandidateNodes(context.Context) ([]graph.Node, error)
}

type Coverage struct {
	// Candidates is the number of graph candidates after filters.
	Candidates int `json:"candidates"`
	// Documents is the number of distinct embedding documents those
	// candidates reduce to.
	Documents int `json:"documents"`
	// Embedded is how many documents had a vector available for ranking.
	Embedded int `json:"embedded"`
	// Missing is how many documents still lack a vector.
	Missing int `json:"missing"`
	// Backfilled is how many documents this call embedded and cached.
	Backfilled int `json:"backfilled"`
	// RankedCandidates is how many candidates were scored.
	RankedCandidates int `json:"ranked_candidates"`
	// ResolvedMatches is how many returned matches carry graph context.
	ResolvedMatches int `json:"resolved_matches"`
	// Fraction is Embedded/Documents, rounded to four decimals.
	Fraction float64 `json:"fraction"`
}

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

type EmbeddingCache interface {
	Load(context.Context, []CacheKey) (map[CacheKey][]float32, error)
	Store(context.Context, []CacheEntry) error
}

type Match struct {
	Node    graph.Node      `json:"node"`
	Score   float64         `json:"score"`
	Context query.Traversal `json:"context"`
}

type SearchFilters struct {
	Languages    []string `json:"languages,omitempty"`
	PathPrefixes []string `json:"path_prefixes,omitempty"`
}

type SearchRequest struct {
	Query string
	Limit int
	// Budget bounds the whole query. A non-positive value selects
	// DefaultSearchBudget; values above MaxSearchBudget are clamped.
	Budget time.Duration
	// MinimumCoverage is the embedded fraction required before ranked results
	// are reported as anything but StatusWarming. Non-positive selects
	// DefaultMinimumCoverage.
	MinimumCoverage float64
	// Languages restricts candidates to these node languages, compared
	// case-insensitively.
	Languages []string
	// PathPrefixes restricts candidates to nodes whose location path lies
	// under one of these repository-relative segment prefixes.
	PathPrefixes []string
}

type SearchResult struct {
	Query   string  `json:"query"`
	Model   string  `json:"model"`
	Matches []Match `json:"matches"`
	// Status is complete, partial, or warming.
	Status SearchStatus `json:"status,omitempty"`
	// Partial is true whenever Status is not complete.
	Partial bool `json:"partial,omitempty"`
	// Coverage separates embedding-cache backfill progress from ranking and
	// graph-resolution progress.
	Coverage Coverage `json:"coverage,omitempty"`
	// Timings reports per-phase durations in a fixed span order.
	Timings Timings `json:"timings,omitempty"`
	// Budget states the applied time bound and whether it ran out.
	Budget BudgetReport `json:"budget,omitempty"`
	// Filters echoes the normalized candidate filters.
	Filters SearchFilters `json:"filters,omitempty"`
	// Notes explain every deviation from a complete answer.
	Notes []string `json:"notes,omitempty"`
	// NextAction is the concrete remedy for a partial or warming answer.
	NextAction string `json:"next_action,omitempty"`
}

type SearchStatus string

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

type Span struct {
	Name         string `json:"name"`
	Milliseconds int64  `json:"milliseconds"`
}

type SyncReport struct {
	Model      string `json:"model"`
	Candidates int    `json:"candidates"`
	Updated    int    `json:"updated"`
	Unchanged  int    `json:"unchanged"`
	Removed    int64  `json:"removed"`
}

type Timings struct {
	Spans             []Span `json:"spans"`
	TotalMilliseconds int64  `json:"total_milliseconds"`
}