semantic

package
v0.2.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 30, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package semantic provides a Redis Stack (RediSearch) vector store used by the semantic cache plugin to look up and persist responses by embedding similarity, scoped per rule via a hashed tag.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Candidate 

type Candidate struct {
	Response   string
	Similarity float64
}

Candidate is a cache hit returned by Lookup.

type Deps added in v0.2.4 

type Deps struct {
	Redis  *redis.Client
	Pool   *pgxpool.Pool
	Logger *slog.Logger
}

Deps carries the backend handles a Store may need; only the field matching the selected kind is required.

type Entry 

type Entry struct {
	RuleID    string
	Embedding *embedding.Embedding
	Response  string
	TTL       time.Duration
}

Entry is a response to persist for future similarity lookups.

type MemoryStore added in v0.2.4 

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

MemoryStore is an in-process Store backed by a TTL map and brute-force cosine similarity. It suits development and small single-replica deployments; eviction is purely TTL-based.

func NewMemoryStore added in v0.2.4 

func NewMemoryStore(logger *slog.Logger) *MemoryStore

NewMemoryStore builds an empty in-memory Store.

func (*MemoryStore) EnsureIndex added in v0.2.4 

func (s *MemoryStore) EnsureIndex(ctx context.Context, dimension int) error

EnsureIndex is a no-op for the in-memory backend.

func (*MemoryStore) GetExact added in v0.2.4 

func (s *MemoryStore) GetExact(ctx context.Context, ruleID, key string) (string, bool, error)

GetExact returns the response cached under the exact key for the rule when it is still live, filtering out expired entries on read.

func (*MemoryStore) Lookup added in v0.2.4 

func (s *MemoryStore) Lookup(ctx context.Context, ruleID string, emb *embedding.Embedding, topK int) ([]Candidate, error)

Lookup returns the topK live cached responses for the rule, ordered by descending cosine similarity.

func (*MemoryStore) PutExact added in v0.2.4 

func (s *MemoryStore) PutExact(ctx context.Context, ruleID, key, response string, ttl time.Duration) error

PutExact stores a response under the exact key for the rule. A TTL of zero or less means the entry never expires.

func (*MemoryStore) Store added in v0.2.4 

func (s *MemoryStore) Store(ctx context.Context, entry Entry) error

Store appends a response keyed by its embedding under the rule. A TTL of zero or less means the entry never expires.

type Option 

type Option func(*RedisStore)

Option customizes a RedisStore.

func WithIndexName 

func WithIndexName(name string) Option

WithIndexName overrides the RediSearch index name.

type PgvectorStore added in v0.2.4 

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

PgvectorStore implements Store against PostgreSQL with the pgvector extension. The schema is created lazily on first use so the backend stays inert (and never blocks process startup) unless it is the configured vector store.

func NewPgvectorStore added in v0.2.4 

func NewPgvectorStore(pool *pgxpool.Pool, logger *slog.Logger) *PgvectorStore

NewPgvectorStore builds a vector store over the given pgx pool.

func (*PgvectorStore) EnsureIndex added in v0.2.4 

func (s *PgvectorStore) EnsureIndex(ctx context.Context, dimension int) error

EnsureIndex validates the requested dimension. A dimension other than the supported width is rejected so the plugin degrades to pass-through. Schema creation is deferred to the first data operation via ensureSchema.

func (*PgvectorStore) GetExact added in v0.2.4 

func (s *PgvectorStore) GetExact(ctx context.Context, ruleID, key string) (string, bool, error)

GetExact returns the response cached under the exact key for the rule. A miss or a transient backend error degrades to ("", false, nil) so the caller falls through to the upstream.

func (*PgvectorStore) Lookup added in v0.2.4 

func (s *PgvectorStore) Lookup(ctx context.Context, ruleID string, emb *embedding.Embedding, topK int) ([]Candidate, error)

Lookup returns the topK nearest cached responses for the rule, ordered by descending cosine similarity. Any query error degrades to no candidates so the caller falls through to the upstream.

func (*PgvectorStore) PutExact added in v0.2.4 

func (s *PgvectorStore) PutExact(ctx context.Context, ruleID, key, response string, ttl time.Duration) error

PutExact stores a response under the exact key for the rule. A TTL of zero or less stores the entry without expiry.

func (*PgvectorStore) Store added in v0.2.4 

func (s *PgvectorStore) Store(ctx context.Context, entry Entry) error

Store persists a response keyed by its embedding under the rule. An embedding whose width is not the supported dimension degrades to a no-op.

type RedisStore 

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

RedisStore implements Store against Redis Stack RediSearch.

func NewRedisStore 

func NewRedisStore(client *redis.Client, logger *slog.Logger, opts ...Option) *RedisStore

NewRedisStore builds a vector store over the given Redis client.

func (*RedisStore) EnsureIndex 

func (s *RedisStore) EnsureIndex(ctx context.Context, dimension int) error

EnsureIndex creates the vector index once, tolerating a pre-existing index.

func (*RedisStore) GetExact added in v0.2.4 

func (s *RedisStore) GetExact(ctx context.Context, ruleID, key string) (string, bool, error)

GetExact returns the response cached under the exact key for the rule. A miss or a transient backend error degrades to ("", false, nil) so the caller falls through to the upstream, matching Lookup's degrade-on-error contract.

func (*RedisStore) Lookup 

func (s *RedisStore) Lookup(ctx context.Context, ruleID string, emb *embedding.Embedding, topK int) ([]Candidate, error)

Lookup returns the topK nearest cached responses for the rule, ordered by descending similarity. A query error degrades to no candidates so the caller can fall through to the upstream.

func (*RedisStore) PutExact added in v0.2.4 

func (s *RedisStore) PutExact(ctx context.Context, ruleID, key, response string, ttl time.Duration) error

PutExact stores a response under the exact key for the rule. A TTL of zero or less stores the entry without expiry.

func (*RedisStore) Store 

func (s *RedisStore) Store(ctx context.Context, entry Entry) error

Store persists a response keyed by its embedding under the rule's tag.

type Store 

type Store interface {
	EnsureIndex(ctx context.Context, dimension int) error
	Lookup(ctx context.Context, ruleID string, emb *embedding.Embedding, topK int) ([]Candidate, error)
	Store(ctx context.Context, entry Entry) error
	GetExact(ctx context.Context, ruleID, key string) (string, bool, error)
	PutExact(ctx context.Context, ruleID, key, response string, ttl time.Duration) error
}

Store is the vector cache backing the semantic cache plugin.

func NewStore added in v0.2.4 

func NewStore(kind string, deps Deps) (Store, error)

NewStore builds the Store backend named by kind. An empty kind defaults to redis, preserving the historical behaviour.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.