vectorstore

type Batcher interface {
	// Batch partitions the supplied pointers without cloning or retaining them.
	// Every input pointer must occur exactly once in the output, global order is
	// preserved, and empty batches are invalid. Context cancellation remains
	// identifiable through errors.Is.
	Batch(ctx context.Context, documents []*document.Document) ([][]*document.Document, error)
}

type Closer interface {
	// Close makes the store unusable. Repeated calls follow the underlying
	// resource's close semantics and are not guaranteed to be idempotent.
	Close() error
}

type FilterDeleter interface {
	// DeleteWhere removes every document matching predicate. Implementations return
	// [ErrMissingFilter] for nil and reject invalid expressions.
	DeleteWhere(ctx context.Context, predicate filter.Predicate) error
}

type IDDeleter interface {
	// DeleteIDs removes the documents with the given ids. Unknown ids
	// are ignored (idempotent); an empty slice is a no-op.
	DeleteIDs(ctx context.Context, ids []string) error
}

type IndexRequest struct {
	Documents []*document.Document `json:"documents"`
}

type Indexer interface {
	// Index persists request documents using caller-assigned IDs. Existing IDs
	// are replaced according to the backend's upsert semantics. Implementations
	// validate the complete request before external I/O. Index does not promise
	// atomic writes across batches: an error may leave earlier documents stored.
	// Backend-specific transaction guarantees belong to the implementation.
	// Accepted document content, including Media, must survive retrieval;
	// implementations reject unsupported media before external I/O.
	//
	// Index never invents document IDs: its error-only result has no channel for
	// returning generated identities to the caller.
	Index(ctx context.Context, request *IndexRequest) error
}

type Score float64

type SearchMode string

type SearchOptions struct {
	// TopK limits the result count. Zero uses DefaultTopK.
	TopK     int   `json:"top_k,omitzero"`
	MinScore Score `json:"min_score,omitzero"`
	// Filter is encoded as its canonical filter DSL string. An omitted or null
	// JSON filter means no predicate; a present string must parse successfully.
	Filter filter.Predicate `json:"filter,omitempty"`
	Mode   SearchMode       `json:"mode,omitempty"`
}

type SearchRequest struct {
	Query   string        `json:"query,omitempty"`
	Options SearchOptions `json:"options"`
}

type SearchResponse struct {
	Results []*SearchResult `json:"results"`
}

type SearchResult struct {
	Document *document.Document `json:"document"`
	Score    Score              `json:"score"`
}

type Searcher interface {
	// Search returns a response honoring the mode, semantic score threshold,
	// metadata filter, and result cap owned by [SearchRequest.Options].
	Search(ctx context.Context, request *SearchRequest) (*SearchResponse, error)
}