Documentation
¶
Overview ¶
Package cache implements the shared SQLite-backed embedding cache.
Wire-compatible with the Python EmbeddingCache in src/ogham/embedding_cache.py: same schema, same key format, same JSON value encoding. A Python sidecar writing an entry and a Go native binary reading it (or vice versa) must see the same vector within float32 round-trip precision.
Default path is $HOME/.cache/ogham/embeddings.db on every platform so Python and Go agree even on macOS where os.UserCacheDir would drift to ~/Library/Caches/. Override via cacheDir.
Index ¶
- Constants
- func Key(provider, model string, dim int, text string) string
- func ResetDefault()
- type EmbeddingCache
- func (c *EmbeddingCache) Clear() (int, error)
- func (c *EmbeddingCache) Close() error
- func (c *EmbeddingCache) Contains(key string) (bool, error)
- func (c *EmbeddingCache) Get(key string) ([]float32, bool, error)
- func (c *EmbeddingCache) GetFull(key string) ([]float32, string, bool, error)
- func (c *EmbeddingCache) Len() (int, error)
- func (c *EmbeddingCache) Put(key string, embedding []float32, sparse string) error
- func (c *EmbeddingCache) Stats() (Stats, error)
- type Stats
Constants ¶
const DefaultMaxSize = 10_000
DefaultMaxSize is the eviction ceiling used when none is specified. Matches Python's EmbeddingCache default.
Variables ¶
This section is empty.
Functions ¶
func Key ¶
Key returns the cache key for the given embedding-request scope. Byte-identical to Python's src/ogham/embeddings.py _cache_key(). Exported so callers that want to pre-compute keys (batch paths) can.
func ResetDefault ¶
func ResetDefault()
ResetDefault is a test helper: it closes the singleton (ignoring any close error) and clears the sync.Once so the next Default() call can open a fresh cache -- for example under a newly set HOME. Not safe to use from production code; only exported for cross-package tests.
Types ¶
type EmbeddingCache ¶
type EmbeddingCache struct {
// contains filtered or unexported fields
}
EmbeddingCache is a goroutine-safe SQLite-backed cache for embedding vectors keyed by the SHA-256 of {provider}:{model}:{dim}:{text}.
func Default ¶
func Default() (*EmbeddingCache, error)
Default returns a process-wide singleton cache rooted at $OGHAM_CACHE_DIR (or $EMBEDDING_CACHE_DIR, then $HOME/.cache/ogham/). First call wins; subsequent calls return the same instance even if the env vars have since changed. Safe to call from multiple goroutines.
func Open ¶
func Open(cacheDir string, maxSize int) (*EmbeddingCache, error)
Open opens (or creates) the cache at cacheDir/embeddings.db. Empty cacheDir means $HOME/.cache/ogham/ (cross-stack shared path).
func (*EmbeddingCache) Clear ¶
func (c *EmbeddingCache) Clear() (int, error)
Clear removes every row and zeroes the hit/miss counters. Returns the number of rows that existed before the clear.
func (*EmbeddingCache) Close ¶
func (c *EmbeddingCache) Close() error
Close releases the underlying SQLite handle. Safe to call multiple times; a second call returns sql.DB's idempotent error.
func (*EmbeddingCache) Contains ¶
func (c *EmbeddingCache) Contains(key string) (bool, error)
Contains reports whether key is present without touching hit/miss.
func (*EmbeddingCache) Get ¶
func (c *EmbeddingCache) Get(key string) ([]float32, bool, error)
Get returns the embedding for key, or (nil, false, nil) on miss. The hit/miss counters are updated as a side effect.
func (*EmbeddingCache) GetFull ¶
GetFull returns (embedding, sparse, true, nil) on hit or a miss sentinel. Sparse is "" when the column is NULL.
func (*EmbeddingCache) Len ¶
func (c *EmbeddingCache) Len() (int, error)
Len returns the row count. Stats() is cheaper for repeated calls because it reads the same value under the same lock.
func (*EmbeddingCache) Put ¶
func (c *EmbeddingCache) Put(key string, embedding []float32, sparse string) error
Put writes (or replaces) the entry for key. sparse="" stores NULL. After inserting it runs eviction if the row count exceeded maxSize.
func (*EmbeddingCache) Stats ¶
func (c *EmbeddingCache) Stats() (Stats, error)
Stats returns a snapshot. Never errors on a healthy DB but propagates any DB error from the underlying COUNT.
type Stats ¶
type Stats struct {
Size int `json:"size"`
MaxSize int `json:"max_size"`
Hits int64 `json:"hits"`
Misses int64 `json:"misses"`
Evictions int64 `json:"evictions"`
HitRate float64 `json:"hit_rate"`
}
Stats reports cache usage. Evictions counter always reports 0 for parity with Python's sqlite cache which also doesn't track them.
Source Files