cache

package
v0.3.1 Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2026 License: MIT Imports: 8 Imported by: 0

README

cache

In-memory LRU caches with TTL for the expensive results in a RAG pipeline: embeddings, query results, and graph traversals.

API

  • Cache — the core interface (Get, Set, Delete, Len, Stats).
  • NewLRUCache(config) / DefaultCacheConfig() — LRU implementation with optional TTL and a size cap.
  • NewEmbeddingCache(config) + GenerateEmbeddingKey(text) — cache keyed on the hashed input text; wraps with embedder.NewCachingEmbedder(inner, cache, ttl) to memoize an embedder.
  • NewQueryCache(config) + GenerateQueryKey(query, filters) — keyed on the query plus a canonicalized filter representation.
  • NewGraphCache(config) + GenerateGraphTraversalKey(...) — keyed on entity + traversal type + depth.
  • CacheManager — manages multiple named caches; CacheStats reports hits/misses/evictions.

Used by

embedder (embedding memoization) and application code in front of pipeline / graph.

Documentation

Overview

Package cache provides intelligent caching for query results, embeddings, and graph traversals to reduce latency and cost for repeated queries.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateEmbeddingKey 

func GenerateEmbeddingKey(text string) string

GenerateEmbeddingKey generates a cache key for an embedding input.

func GenerateGraphTraversalKey 

func GenerateGraphTraversalKey(entityID string, traversalType string, depth int) string

GenerateGraphTraversalKey generates a cache key for a graph traversal query.

func GenerateQueryKey 

func GenerateQueryKey(query string, filters map[string]interface{}) string

GenerateQueryKey generates a cache key for a query and its filters.

Types

type Cache 

type Cache interface {
	// Get retrieves a value from the cache by key.
	Get(key string) (interface{}, bool)

	// Set stores a value in the cache with the given key and TTL.
	Set(key string, value interface{}, ttl time.Duration)

	// Delete removes a value from the cache by key.
	Delete(key string)

	// Clear removes all values from the cache.
	Clear()

	// Stats returns cache statistics.
	Stats() CacheStats
}

Cache defines the interface for all cache implementations.

type CacheConfig 

type CacheConfig struct {
	MaxSize        int
	DefaultTTL     time.Duration
	EvictionPolicy EvictionPolicy
}

CacheConfig holds configuration for cache instances.

func DefaultCacheConfig 

func DefaultCacheConfig() CacheConfig

DefaultCacheConfig returns default configuration for caches.

type CacheEntry 

type CacheEntry struct {
	Value        interface{}
	ExpiresAt    time.Time
	CreatedAt    time.Time
	LastAccessed time.Time
}

CacheEntry represents a single entry in the cache.

func (*CacheEntry) IsExpired 

func (e *CacheEntry) IsExpired() bool

IsExpired returns true if the cache entry has expired.

type CacheManager 

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

CacheManager manages multiple cache instances.

func NewCacheManager 

func NewCacheManager(config CacheConfig) *CacheManager

NewCacheManager creates a new CacheManager with default configuration.

func (*CacheManager) ClearAll 

func (m *CacheManager) ClearAll()

ClearAll clears all caches.

func (*CacheManager) DeleteCache 

func (m *CacheManager) DeleteCache(name string)

DeleteCache removes a cache by name.

func (*CacheManager) GetCache 

func (m *CacheManager) GetCache(name string) Cache

GetCache returns a cache by name, creating it if it doesn't exist.

func (*CacheManager) Stats 

func (m *CacheManager) Stats() map[string]CacheStats

Stats returns aggregated statistics for all caches.

type CacheStats 

type CacheStats struct {
	Hits   int
	Misses int
	Size   int
}

CacheStats contains statistics about cache performance.

type CacheWarmer 

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

CacheWarmer provides cache warming strategies to pre-populate the cache.

func NewCacheWarmer 

func NewCacheWarmer(cache Cache) *CacheWarmer

NewCacheWarmer creates a new CacheWarmer.

func (*CacheWarmer) AddRequest 

func (cw *CacheWarmer) AddRequest(req WarmRequest)

AddRequest adds a request to warm the cache.

func (*CacheWarmer) ClearPending 

func (cw *CacheWarmer) ClearPending()

ClearPending clears all pending warm requests.

func (*CacheWarmer) Stats 

func (cw *CacheWarmer) Stats() WarmStats

Stats returns cache warming statistics.

func (*CacheWarmer) Warm 

func (cw *CacheWarmer) Warm()

Warm executes all pending warm requests.

type EmbeddingCache 

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

EmbeddingCache provides caching for embedding vectors to avoid redundant computation.

func NewEmbeddingCache 

func NewEmbeddingCache(maxSize int) *EmbeddingCache

NewEmbeddingCache creates a new EmbeddingCache with default configuration.

func (*EmbeddingCache) Clear 

func (ec *EmbeddingCache) Clear()

Clear removes all cached embeddings.

func (*EmbeddingCache) Delete 

func (ec *EmbeddingCache) Delete(text string)

Delete removes a cached embedding.

func (*EmbeddingCache) Get 

func (ec *EmbeddingCache) Get(text string) ([]float32, bool)

Get retrieves a cached embedding vector.

func (*EmbeddingCache) InvalidateByPrefix 

func (ec *EmbeddingCache) InvalidateByPrefix(prefix string)

InvalidateByPrefix invalidates all cached embeddings matching a prefix.

func (*EmbeddingCache) Set 

func (ec *EmbeddingCache) Set(text string, embedding []float32, ttl time.Duration)

Set stores an embedding vector in the cache.

func (*EmbeddingCache) Stats 

func (ec *EmbeddingCache) Stats() CacheStats

Stats returns cache statistics.

type EvictionPolicy 

type EvictionPolicy int

EvictionPolicy defines the cache eviction strategy. 

const (
	// EvictionLRU uses Least Recently Used eviction.
	EvictionLRU EvictionPolicy = iota
	// EvictionLFU uses Least Frequently Used eviction.
	EvictionLFU
	// EvictionFIFO uses First In First Out eviction.
	EvictionFIFO
)

type GraphCache 

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

GraphCache provides caching for graph traversal results.

func NewGraphCache 

func NewGraphCache(maxSize int) *GraphCache

NewGraphCache creates a new GraphCache with default configuration.

func (*GraphCache) Clear 

func (gc *GraphCache) Clear()

Clear removes all cached graph traversal results.

func (*GraphCache) Delete 

func (gc *GraphCache) Delete(entityID string, traversalType string, depth int)

Delete removes a cached graph traversal result.

func (*GraphCache) Get 

func (gc *GraphCache) Get(entityID string, traversalType string, depth int) (*GraphTraversalResult, bool)

Get retrieves a cached graph traversal result.

func (*GraphCache) InvalidateByEntity 

func (gc *GraphCache) InvalidateByEntity(entityID string)

InvalidateByEntity invalidates all cached results for a specific entity.

func (*GraphCache) Set 

func (gc *GraphCache) Set(entityID string, traversalType string, depth int, result *GraphTraversalResult, ttl time.Duration)

Set stores a graph traversal result in the cache.

func (*GraphCache) Stats 

func (gc *GraphCache) Stats() CacheStats

Stats returns cache statistics.

type GraphTraversalResult 

type GraphTraversalResult struct {
	Query     string
	Results   []*graph.Entity
	Timestamp time.Time
	Latency   time.Duration
}

GraphTraversalResult represents a cached graph traversal result.

type LRUCache 

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

LRUCache implements a Least Recently Used (LRU) cache with TTL support.

func NewLRUCache 

func NewLRUCache(config CacheConfig) *LRUCache

NewLRUCache creates a new LRU cache with the given configuration.

func (*LRUCache) Clear 

func (c *LRUCache) Clear()

Clear removes all values from the cache.

func (*LRUCache) Delete 

func (c *LRUCache) Delete(key string)

Delete removes a value from the cache by key.

func (*LRUCache) Get 

func (c *LRUCache) Get(key string) (interface{}, bool)

Get retrieves a value from the cache by key.

func (*LRUCache) Len 

func (c *LRUCache) Len() int

Len returns the number of items in the cache.

func (*LRUCache) Set 

func (c *LRUCache) Set(key string, value interface{}, ttl time.Duration)

Set stores a value in the cache with the given key and TTL.

func (*LRUCache) Stats 

func (c *LRUCache) Stats() CacheStats

Stats returns cache statistics.

type MultiLevelCache 

type MultiLevelCache struct {
	L1 Cache // In-memory (fast, small)
	L2 Cache // Can be disk-based or larger in-memory (slower, larger)
}

MultiLevelCache provides multi-level caching with L1 (fast, small) and L2 (slower, larger) tiers.

func NewMultiLevelCache 

func NewMultiLevelCache(l1, l2 Cache) *MultiLevelCache

NewMultiLevelCache creates a new MultiLevelCache with L1 and L2 caches.

func (*MultiLevelCache) Clear 

func (mlc *MultiLevelCache) Clear()

Clear removes all values from both L1 and L2 caches.

func (*MultiLevelCache) Delete 

func (mlc *MultiLevelCache) Delete(key string)

Delete removes a value from both L1 and L2 caches.

func (*MultiLevelCache) Get 

func (mlc *MultiLevelCache) Get(key string) (interface{}, bool)

Get retrieves a value from the cache, checking L1 first, then L2.

func (*MultiLevelCache) Set 

func (mlc *MultiLevelCache) Set(key string, value interface{}, ttl time.Duration)

Set stores a value in both L1 and L2 caches.

func (*MultiLevelCache) Stats 

func (mlc *MultiLevelCache) Stats() CacheStats

Stats returns aggregated statistics from both L1 and L2 caches.

type QueryCache 

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

QueryCache provides caching for query results.

func NewQueryCache 

func NewQueryCache(maxSize int) *QueryCache

NewQueryCache creates a new QueryCache with default configuration.

func (*QueryCache) Clear 

func (qc *QueryCache) Clear()

Clear removes all cached query results.

func (*QueryCache) Delete 

func (qc *QueryCache) Delete(query string, filters map[string]interface{})

Delete removes a cached query result.

func (*QueryCache) Get 

func (qc *QueryCache) Get(query string, filters map[string]interface{}) (*QueryResult, bool)

Get retrieves a cached query result.

func (*QueryCache) InvalidateByPrefix 

func (qc *QueryCache) InvalidateByPrefix(prefix string)

InvalidateByPrefix invalidates all cached results matching a query prefix.

func (*QueryCache) Set 

func (qc *QueryCache) Set(query string, filters map[string]interface{}, result *QueryResult, ttl time.Duration)

Set stores a query result in the cache.

func (*QueryCache) Stats 

func (qc *QueryCache) Stats() CacheStats

Stats returns cache statistics.

type QueryResult 

type QueryResult struct {
	Query     string
	Results   []interface{}
	Timestamp time.Time
	Latency   time.Duration
}

QueryResult represents a cached query result.

type WarmRequest 

type WarmRequest struct {
	Query   string
	Filters map[string]interface{}
	Result  interface{}
	TTL     time.Duration
}

WarmRequest represents a request to warm the cache.

type WarmStats 

type WarmStats struct {
	TotalRequests int
	TotalWarmed   int
	StartTime     time.Time
}

WarmStats tracks cache warming statistics.

func (WarmStats) String 

func (ws WarmStats) String() string

String returns a human-readable summary of the cache warming statistics.

Source Files

View all Source files

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.