retrieval

type EmbeddingProvider interface {
	Similarity(ctx context.Context, recordID string, query []float32) (float64, bool)
}

type EmbeddingService interface {
	EmbedQuery(ctx context.Context, taskDescriptor string) ([]float32, error)
}

type RetrieveRequest struct {
	// TaskDescriptor describes the current task for contextual retrieval.
	TaskDescriptor string

	// QueryEmbedding is an optional pre-computed embedding for the query.
	// When set, Retrieve uses this instead of calling EmbedQuery, avoiding
	// an extra API round-trip and potential rate-limit failures.
	QueryEmbedding []float32

	// Trust is the trust context that gates what records can be returned.
	Trust *TrustContext

	// MemoryTypes optionally restricts retrieval to specific memory types.
	// If empty, all types are queried in layered order.
	MemoryTypes []schema.MemoryType

	// MinSalience filters out records below this salience threshold.
	MinSalience float64

	// Limit caps the total number of returned records. 0 means no limit.
	Limit int
}

type RetrieveResponse struct {
	// Records contains the filtered, sorted, and limited results.
	Records []*schema.MemoryRecord

	// Selection is non-nil when competence or plan_graph candidates were
	// evaluated through the multi-solution selector (RFC 15A.11).
	Selection *SelectionResult
}

type SelectionResult struct {
	// Selected contains the ranked candidates in descending score order.
	Selected []*schema.MemoryRecord

	// Confidence is the selection confidence in [0, 1].
	// Computed as the score gap between the best and second-best candidate,
	// normalized by the best score.
	Confidence float64

	// NeedsMore is true when confidence falls below the selector's threshold,
	// indicating that additional information or user disambiguation is needed.
	NeedsMore bool

	// Scores contains the computed score for each selected record ID.
	Scores map[string]float64
}

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

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

type TrustContext struct {
	// MaxSensitivity is the maximum sensitivity level the requester is allowed to access.
	MaxSensitivity schema.Sensitivity

	// Authenticated indicates whether the requester has been authenticated.
	Authenticated bool

	// ActorID identifies who is making the retrieval request.
	ActorID string

	// Scopes lists the scopes the requester is allowed to access.
	// An empty slice means all scopes are allowed.
	Scopes []string
}

type VectorRanker interface {
	SearchByEmbedding(ctx context.Context, query []float32, limit int) ([]string, error)
}