vector

type CacheStatsSnapshot struct {
	EmbeddingHits   int64 `json:"embedding_hits"`
	EmbeddingMisses int64 `json:"embedding_misses"`
	ResultHits      int64 `json:"result_hits"`
	ResultMisses    int64 `json:"result_misses"`
}

type Client interface {
	// AddDocuments adds documents with their embeddings to the vector store.
	AddDocuments(ctx context.Context, docs []Document) error

	// DeleteDocuments removes documents by their IDs.
	DeleteDocuments(ctx context.Context, ids []string) error

	// Query performs a vector similarity search.
	Query(ctx context.Context, query string, limit int, where map[string]any) ([]QueryResult, error)

	// IsConnected checks if the vector store is available.
	IsConnected() bool

	// Close releases resources.
	Close() error

	// Count returns the total number of vectors in the store.
	Count(ctx context.Context) (int64, error)

	// ModelVersion returns the current embedding model version.
	ModelVersion() string

	// NeedsRebuild checks if vectors need to be rebuilt due to model version change.
	NeedsRebuild(ctx context.Context) (bool, string)

	// GetStaleVectors returns info about vectors with mismatched or null model versions.
	GetStaleVectors(ctx context.Context) ([]StaleVectorInfo, error)

	// DeleteVectorsByDocIDs removes vectors by their doc_ids.
	DeleteVectorsByDocIDs(ctx context.Context, docIDs []string) error

	// GetHealthStats returns comprehensive health statistics about the vector store.
	GetHealthStats(ctx context.Context) (*HealthStats, error)

	// GetCacheStats returns cache performance statistics.
	// Backends without a local cache return a zero-value CacheStatsSnapshot.
	GetCacheStats() CacheStatsSnapshot

	// DeleteByObservationID removes all vectors associated with an observation ID.
	DeleteByObservationID(ctx context.Context, obsID int64) error

	// CacheStats returns basic cache size info for backward compatibility.
	// Deprecated: Use GetCacheStats for comprehensive statistics.
	CacheStats() (size int, maxSize int)
}

type DocType string

type Document struct {
	Metadata map[string]any
	ID       string
	Content  string
}

type ExtractedIDs struct {
	ObservationIDs []int64
	SummaryIDs     []int64
	PromptIDs      []int64
}

type HealthStats struct {
	TotalVectors  int64  `json:"total_vectors"`
	StaleVectors  int64  `json:"stale_vectors"`
	CurrentModel  string `json:"current_model"`
	NeedsRebuild  bool   `json:"needs_rebuild"`
	RebuildReason string `json:"rebuild_reason"`
}

type QueryResult struct {
	Metadata   map[string]any
	ID         string
	Distance   float64
	Similarity float64
}

type StaleVectorInfo struct {
	DocID     string
	DocType   string
	FieldType string
	Project   string
	Scope     string
	SQLiteID  int64
}