memory

type Hit ¶

type Hit struct {
	Kind HitKind
	// Similarity is the winning cosine similarity for HitSemantic.
	Similarity float32
}

Hit reports how a lookup resolved. A miss is the zero Hit.

type HitKind ¶

type HitKind int

HitKind classifies a SemanticStore lookup.

const (
	// HitNone reports a miss.
	HitNone HitKind = iota
	// HitExact reports an exact fingerprint hit.
	HitExact
	// HitSemantic reports a similarity-threshold hit.
	HitSemantic
)

type Key ¶

type Key struct {
	// Tenant isolates one customer or deployment's judgments.
	Tenant string
	// Schema versions the judging pipeline; changing prompts, models, or
	// option sets bumps the schema and invalidates older entries.
	Schema string
	// Primitive is the judgment primitive the entry holds.
	Primitive Primitive
	// Fingerprint identifies the exact request content, typically from
	// FingerprintChoice, FingerprintScore, or FingerprintNoul.
	Fingerprint string
}

Key identifies one cacheable judgment. Entries are shared only when Tenant, Schema, Primitive, and Fingerprint are all identical.

type Metrics ¶

type Metrics struct {
	Insertions uint64
	Updates    uint64
	Hits       uint64
	Misses     uint64
	Evictions  uint64
}

Metrics reports lifetime store counters.

type Option ¶

type Option func(*config)

Option configures a Store at construction.

func WithCapacity(limit uint64) Option

func WithDisableTouchOnHit() Option

func WithTTL(lifetime time.Duration) Option

type Primitive ¶

type Primitive string

Primitive names which judgment primitive a cached entry holds.

const (
	// PrimitiveChoice marks a cached judgment.Choice.
	PrimitiveChoice Primitive = "choice"
	// PrimitiveScore marks a cached judgment.Score.
	PrimitiveScore Primitive = "score"
	// PrimitiveNoul marks a cached judgment.Noul.
	PrimitiveNoul Primitive = "noul"
)

func (p Primitive) Valid() bool

type PutOption ¶

type PutOption func(*putConfig)

PutOption tunes one insertion.

func WithEntryTTL(lifetime time.Duration) PutOption

type SemanticConfig ¶

type SemanticConfig struct {
	// Embedder embeds judgment inputs for semantic comparison.
	Embedder embedding.Embedder
	// Model identifies the embedding space; Dim must be positive and
	// must match every embedded vector.
	Model embedding.ModelRef
	// Threshold is the minimum cosine similarity for a semantic hit.
	// Zero means the 0.92 default.
	Threshold float64
}

SemanticConfig wires the semantic layer. Embedder and Model.Dim are required; Threshold is optional and defaults to 0.92.

type SemanticMetrics ¶

type SemanticMetrics struct {
	ExactHits    uint64
	SemanticHits uint64
	Misses       uint64
	Insertions   uint64
}

SemanticMetrics counts SemanticStore activity.

type SemanticStore ¶

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

SemanticStore is a judgment cache that answers both exact fingerprint hits and semantic matches. Entries whose inputs embed near a stored vector (cosine similarity at or above the configured threshold within the same tenant, schema, and primitive scope) reuse the cached judgment without calling a provider.

The embedder is injected and stays caller-owned; the store performs no network or provider I/O of its own beyond that embedder call.

func NewSemantic(cfg SemanticConfig, opts ...Option) (*SemanticStore, error)

func (s *SemanticStore) Close() error

func (s *SemanticStore) GetChoice(ctx context.Context, key Key, rawInput string) (judgment.Choice, Hit, error)

func (s *SemanticStore) GetNoul(ctx context.Context, key Key, rawInput string) (judgment.Noul, Hit, error)

func (s *SemanticStore) GetScore(ctx context.Context, key Key, rawInput string) (judgment.Score, Hit, error)

func (s *SemanticStore) Metrics() SemanticMetrics

func (s *SemanticStore) PutChoice(ctx context.Context, key Key, rawInput string, result judgment.Choice, opts ...PutOption) error

func (s *SemanticStore) PutNoul(ctx context.Context, key Key, rawInput string, result judgment.Noul, opts ...PutOption) error

func (s *SemanticStore) PutScore(ctx context.Context, key Key, rawInput string, result judgment.Score, opts ...PutOption) error

type Store ¶

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

Store is an exact-hit judgment cache backed by ttlcache.

func New(opts ...Option) (*Store, error)

store, err := New(WithTTL(10 * time.Minute))
if err != nil {
	fmt.Println("new store:", err)
	return
}
defer store.Close()

request := judgment.ChoiceRequest{
	Task:    "route the incoming request",
	Options: []judgment.Option{{ID: "search"}, {ID: "summarize"}},
}
key := Key{
	Tenant:      "acme",
	Schema:      "router.v2",
	Primitive:   PrimitiveChoice,
	Fingerprint: FingerprintChoice(request),
}
result := judgment.Choice{
	Selected: "search",
	Distribution: []judgment.OptionProbability{
		{Option: "search", Probability: 0.7},
		{Option: "summarize", Probability: 0.3},
	},
}
if err := store.PutChoice(key, result); err != nil {
	fmt.Println("put:", err)
	return
}
if hit, ok := store.GetChoice(key); ok {
	fmt.Println("cache hit:", hit.Selected)
}

Output:
cache hit: search

func (s *Store) Close() error

func (s *Store) Delete(key Key)

func (s *Store) GetChoice(key Key) (judgment.Choice, bool)

func (s *Store) GetNoul(key Key) (judgment.Noul, bool)

func (s *Store) GetScore(key Key) (judgment.Score, bool)

func (s *Store) Len() int

func (s *Store) Metrics() Metrics

func (s *Store) PutChoice(key Key, result judgment.Choice, opts ...PutOption) error

func (s *Store) PutNoul(key Key, result judgment.Noul, opts ...PutOption) error

func (s *Store) PutScore(key Key, result judgment.Score, opts ...PutOption) error