abstraction

type Edge struct {
	ID         string         `json:"id"`         // Unique identifier for the edge
	Type       string         `json:"type"`       // Type of the edge
	Source     string         `json:"source"`     // Source node ID
	Target     string         `json:"target"`     // Target node ID
	Properties map[string]any `json:"properties"` // Properties of the edge
}

type GraphStore interface {
	// CreateNode creates a new node in the graph.
	CreateNode(ctx context.Context, node *Node) error

	// CreateEdge creates a new edge in the graph.
	CreateEdge(ctx context.Context, edge *Edge) error

	// GetNode retrieves a node by its ID.
	GetNode(ctx context.Context, id string) (*Node, error)

	// GetEdge retrieves an edge by its ID.
	GetEdge(ctx context.Context, id string) (*Edge, error)

	// DeleteNode deletes a node from the graph.
	DeleteNode(ctx context.Context, id string) error

	// DeleteEdge deletes an edge from the graph.
	DeleteEdge(ctx context.Context, id string) error

	// Query executes a graph query and returns the results.
	Query(ctx context.Context, query string, params map[string]any) ([]map[string]any, error)

	// GetNeighbors retrieves the neighbors of a node.
	GetNeighbors(ctx context.Context, nodeID string, limit int) ([]*Node, error)

	// GetCommunitySummaries retrieves community summaries from the graph.
	GetCommunitySummaries(ctx context.Context, limit int) ([]map[string]any, error)

	// UpsertNodes batch updates or inserts nodes.
	UpsertNodes(ctx context.Context, nodes []*Node) error

	// UpsertEdges batch updates or inserts edges.
	UpsertEdges(ctx context.Context, edges []*Edge) error

	// Close closes the graph store.
	Close(ctx context.Context) error
}

type Metrics interface {

	// RecordIndexingDuration 记录文件索引耗时
	RecordIndexingDuration(file string, duration time.Duration)

	// RecordParsingErrors 记录解析错误
	RecordParsingErrors(file string, err error)

	// RecordEmbeddingCount 记录 embedding 数量
	RecordEmbeddingCount(count int)

	// RecordVectorStoreOperations 记录向量存储操作
	RecordVectorStoreOperations(op string, count int)

	// RecordGraphOperations 记录图存储操作
	RecordGraphOperations(op string, count int)

	// RecordSearchDuration 记录一次 Search 调用的端到端耗时。
	// searcher 为 Searcher 类型标识（如 "native"、"hybrid"）。
	RecordSearchDuration(searcher string, duration time.Duration)

	// RecordSearchError 记录一次 Search 调用失败。
	RecordSearchError(searcher string, err error)

	// RecordSearchResult 记录一次 Search 调用成功，并附带检索到的文档块数量。
	RecordSearchResult(searcher string, chunkCount int)

	// GetMetrics 获取所有指标数据
	GetMetrics() map[string]interface{}
}

type MultimodalEmbedder interface {
	// EmbedText encodes a plain-text string into a vector in the shared embedding space.
	EmbedText(ctx context.Context, text string) ([]float32, error)

	// EmbedImage encodes raw image bytes (JPEG/PNG) into a vector in the shared embedding space.
	// Implementations may return an error if imageData is nil or malformed.
	EmbedImage(ctx context.Context, imageData []byte) ([]float32, error)
}

type Node struct {
	ID         string         `json:"id"`         // Unique identifier for the node
	Type       string         `json:"type"`       // Type of the node
	Properties map[string]any `json:"properties"` // Properties of the node
}

type NoopMetrics struct{}

type Reranker interface {
	// Rerank re-scores a list of chunks against the query and returns the topK most relevant chunks.
	Rerank(ctx context.Context, query string, chunks []*entity.Chunk, topK int) ([]*entity.Chunk, []float32, error)
}

type SemanticCache interface {
	// Get retrieves a cached response if the semantic distance of the query vector
	// is within the given threshold (e.g., Cosine Similarity > 0.98).
	Get(ctx context.Context, queryEmbedding []float32, threshold float32) (string, bool, error)

	// Set stores the query vector and its corresponding response in the cache.
	Set(ctx context.Context, queryEmbedding []float32, response string) error
}

type VectorStore interface {
	// Add adds a single vector to the store.
	Add(ctx context.Context, vector *entity.Vector) error

	// AddBatch adds multiple vectors to the store in batch.
	AddBatch(ctx context.Context, vectors []*entity.Vector) error

	// Search searches for similar vectors based on the query vector.
	Search(ctx context.Context, query []float32, topK int, filter map[string]any) ([]*entity.Vector, []float32, error)

	// Delete deletes a vector from the store.
	Delete(ctx context.Context, id string) error

	// DeleteBatch deletes multiple vectors from the store in batch.
	DeleteBatch(ctx context.Context, ids []string) error

	// Close closes the vector store.
	Close(ctx context.Context) error
}