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 WhereFilter) ([]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)

	// 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

	// GetMetrics returns real query instrumentation metrics (count, latency percentiles, doc count).
	GetMetrics(ctx context.Context) VectorMetricsSnapshot

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

type DocType string

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

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
	SQLiteID int64
}

type VectorMetricsSnapshot struct {
	QueryCount   int64   `json:"query_count"`
	AvgLatencyMs float64 `json:"avg_latency_ms"`
	P50LatencyMs float64 `json:"p50_latency_ms"`
	P95LatencyMs float64 `json:"p95_latency_ms"`
	P99LatencyMs float64 `json:"p99_latency_ms"`
	TotalDocs    int64   `json:"total_documents"`
}

type WhereClause struct {
	OrGroup []WhereClause
	Column  string
	Value   any
}

type WhereFilter struct {
	Clauses []WhereClause
}