vector

Documentation

Overview

Package vector provides vector similarity search for retrieval.

Index

• type BatchIndex
• type DistanceMetric
• type Embedder
• type HNSWConfig
• type Index
• type IndexConfig
• type IndexManager
• type IndexStats
• type IndexType
• type Node
• type Retriever
  • func NewRetriever(cfg RetrieverConfig) *Retriever
  • func (r *Retriever) Retrieve(ctx context.Context, q retrieve.Query) (*retrieve.Result, error)
• type RetrieverConfig
• type SearchResult

Types

type BatchIndex

type BatchIndex interface {
	Index
	// InsertBatch adds multiple nodes to the index.
	InsertBatch(ctx context.Context, nodes []Node) error
	// UpsertBatch inserts or updates multiple nodes.
	UpsertBatch(ctx context.Context, nodes []Node) error
	// DeleteBatch removes multiple nodes from the index.
	DeleteBatch(ctx context.Context, ids []string) error
}

BatchIndex extends Index with batch operations for efficiency.

type DistanceMetric

type DistanceMetric string

DistanceMetric defines the distance function for similarity.

const (
	DistanceCosine    DistanceMetric = "cosine"
	DistanceEuclidean DistanceMetric = "euclidean"
	DistanceDot       DistanceMetric = "dot"
)

type Embedder

type Embedder interface {
	// Embed creates an embedding for the given text.
	Embed(ctx context.Context, text string) ([]float32, error)
	// EmbedBatch creates embeddings for multiple texts.
	EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)
	// Model returns the name of the embedding model.
	Model() string
}

Embedder creates embeddings from text.

type HNSWConfig

type HNSWConfig struct {
	// M is the number of connections per layer.
	M int
	// EfConstruction is the size of the dynamic candidate list during construction.
	EfConstruction int
	// EfSearch is the size of the dynamic candidate list during search.
	EfSearch int
}

HNSWConfig contains HNSW index parameters.

type Index

type Index interface {
	// Search finds the k most similar nodes to the given embedding.
	Search(ctx context.Context, embedding []float32, k int, filters map[string]string) ([]SearchResult, error)
	// Insert adds a node to the index.
	Insert(ctx context.Context, node Node) error
	// Upsert inserts or updates a node in the index.
	Upsert(ctx context.Context, node Node) error
	// Delete removes a node from the index.
	Delete(ctx context.Context, id string) error
	// Name returns the name/identifier of this index.
	Name() string
}

Index defines the interface for vector index operations.

type IndexConfig

type IndexConfig struct {
	// Name is the index name.
	Name string
	// Dimensions is the vector dimension size.
	Dimensions int
	// DistanceMetric is the distance function (cosine, euclidean, dot).
	DistanceMetric DistanceMetric
	// IndexType is the index algorithm (hnsw, ivfflat, flat).
	IndexType IndexType
	// HNSWConfig contains HNSW-specific settings.
	HNSWConfig *HNSWConfig
}

IndexConfig configures a vector index.

type IndexManager

type IndexManager interface {
	// CreateIndex creates a new vector index.
	CreateIndex(ctx context.Context, cfg IndexConfig) error
	// DropIndex removes an index.
	DropIndex(ctx context.Context, name string) error
	// IndexExists checks if an index exists.
	IndexExists(ctx context.Context, name string) (bool, error)
	// IndexStats returns statistics for an index.
	IndexStats(ctx context.Context, name string) (*IndexStats, error)
	// ListIndexes returns all index names.
	ListIndexes(ctx context.Context) ([]string, error)
}

IndexManager provides index lifecycle operations.

type IndexStats

type IndexStats struct {
	// Name is the index name.
	Name string
	// NodeCount is the number of nodes in the index.
	NodeCount int64
	// Dimensions is the vector dimension size.
	Dimensions int
	// IndexSizeBytes is the approximate index size in bytes.
	IndexSizeBytes int64
}

IndexStats contains index statistics.

type IndexType

type IndexType string

IndexType defines the index algorithm.

const (
	IndexTypeHNSW    IndexType = "hnsw"
	IndexTypeIVFFlat IndexType = "ivfflat"
	IndexTypeFlat    IndexType = "flat"
)

type Node

type Node struct {
	// ID is the unique identifier for this node.
	ID string
	// Content is the text content of this node.
	Content string
	// Embedding is the vector embedding for this node.
	Embedding []float32
	// Source identifies where this node came from.
	Source string
	// Metadata contains additional node metadata.
	Metadata map[string]string
}

Node represents a node in the vector index.

type Retriever

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

Retriever implements vector-based retrieval.

func NewRetriever

func NewRetriever(cfg RetrieverConfig) *Retriever

NewRetriever creates a new vector retriever.

func (*Retriever) Retrieve

func (r *Retriever) Retrieve(ctx context.Context, q retrieve.Query) (*retrieve.Result, error)

Retrieve performs vector similarity search.

type RetrieverConfig

type RetrieverConfig struct {
	// Index is the vector index to search.
	Index Index
	// Embedder creates embeddings for queries.
	Embedder Embedder
	// DefaultTopK is the default number of results to return.
	DefaultTopK int
	// MinScore is the minimum similarity score threshold.
	MinScore float64
	// Observer for tracing and metrics.
	Observer retrieve.Observer
}

RetrieverConfig configures the vector retriever.

type SearchResult

type SearchResult struct {
	// Node is the matched node.
	Node Node
	// Score is the similarity score (0.0-1.0).
	Score float64
}

SearchResult represents a single search result from vector search.