embedding

type APIConfig ¶

type APIConfig struct {
	// Name labels the provider instance in logs (default "openai-embedding").
	Name string
	// Model is the embedding model id sent to the API (e.g. "text-embedding-3-small").
	Model string
	// Dim is the output dimension to request. When > 0 it is sent as the API
	// `dimensions` parameter (supported by text-embedding-3-*), pinning output to
	// the storage width so no padding is needed. Leave 0 for models that don't
	// support it (the model's native dimension is then used).
	Dim     int
	APIKey  string
	BaseURL string
}

APIConfig configures an OpenAI-compatible embedding API provider.

func (c APIConfig) SpaceKey() string

type BootConfig ¶

type BootConfig struct {
	DB        *pgxpool.Pool
	Settings  SettingsProvider // live config source (DB-backed)
	BatchSize int              // indexer batch size (0 => defaultBatchSize)
	Interval  time.Duration    // backfill tick (0 => defaultInterval)
	Logger    *slog.Logger
}

BootConfig is the wiring the composition root supplies to build the lane.

type BreakerConfig ¶

type BreakerConfig struct {
	// FailureThreshold is the count of consecutive transient failures that trips
	// the breaker open.
	FailureThreshold int
	// OpenDuration is how long the breaker stays open before a single half-open
	// probe is allowed through.
	OpenDuration time.Duration
}

BreakerConfig tunes the per-provider circuit breaker. Zero values fall back to sensible defaults (see NewChain).

type Chain ¶

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

Chain is an API-first provider chain: it tries providers in priority order (primary first) and falls back to the next only on transient failure. The rules, in order, for each request:

• Privacy: a PrivacySensitive request skips every KindAPI provider.
• Circuit breaker: a provider whose breaker is open is skipped without a call, so a dead API costs one timeout per open-window, not one per request.
• Terminal error: a caller/data fault (IsTerminal) stops the chain and returns immediately — falling back would only get the same rejection.
• Transient error: records a breaker failure and advances to the next provider.

If no provider is eligible (all skipped) the chain returns ErrNoProvider; if every eligible provider failed transiently it returns the last error.

func NewChain(providers []Provider, cfg BreakerConfig, clock func() time.Time) *Chain

func (c *Chain) Embed(ctx context.Context, req Request) (Result, error)

type Embedder ¶

type Embedder interface {
	Embed(ctx context.Context, req Request) (Result, error)
}

Embedder is the entry point the indexer depends on; *Chain satisfies it. Kept as a narrow interface so tests inject a deterministic fake.

type IndexConfig ¶

type IndexConfig struct {
	// Model is the canonical vector space this deployment embeds into. The indexer
	// scans for rows missing this space and writes only vectors produced in it, so
	// a fallback to a different space never fragments the stored corpus.
	Model string
	// Normalize L2-normalizes each vector before storage (cosine as dot product).
	Normalize bool
	// BatchSize bounds how many rows of each source one BackfillOnce pass embeds
	// (default 128). One API round-trip embeds a whole batch.
	BatchSize int
}

IndexConfig configures backfill.

type Indexer ¶

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

Indexer populates the *_embedding sidecars from their source rows. One pass (BackfillOnce) embeds up to BatchSize stale rows per source; a periodic caller drives it until the backlog drains.

func NewIndexer(q *sqlc.Queries, emb Embedder, cfg IndexConfig) *Indexer

func (ix *Indexer) BackfillOnce(ctx context.Context) (int, error)

type Kind ¶

type Kind string

Kind is where a provider runs: a remote API, or a local in-process model.

const (
	KindAPI   Kind = "api"
	KindLocal Kind = "local"
)

type Mode ¶

type Mode string

Mode distinguishes embedding a search query from embedding stored content. Some models embed the two asymmetrically (a query prompt vs a document prompt); providers that don't care ignore it.

const (
	ModeQuery    Mode = "query"
	ModeDocument Mode = "document"
)

type Privacy ¶

type Privacy string

Privacy gates whether a request may leave the machine. A sensitive request skips every remote (KindAPI) provider in the chain and is served only by a local one; if none is configured it fails rather than silently going remote.

const (
	PrivacyNormal    Privacy = "normal"
	PrivacySensitive Privacy = "sensitive"
)

type Provider ¶

type Provider interface {
	// Name identifies the provider instance in logs and Result.ProviderName.
	Name() string
	// Kind reports whether the provider is remote or local, which the chain uses
	// to honor PrivacySensitive.
	Kind() Kind
	// Model is the vector-space key every vector from this provider belongs to.
	Model() string
	// Embed returns one vector per input text, in order. It must return a
	// Terminal error (see IsTerminal) for caller/data faults that retrying or
	// failing over cannot fix; any other error is treated as transient and lets
	// the chain fall back.
	Embed(ctx context.Context, req Request) (Result, error)
}

Provider is one embedding backend. Implementations are expected to be safe for concurrent use.

func NewAPIProvider(cfg APIConfig) Provider

type Request ¶

type Request struct {
	Texts   []string
	Mode    Mode
	Privacy Privacy
}

Request is one batch embed call. All texts are embedded in the same mode and returned in input order.

type Result ¶

type Result struct {
	// Vectors aligns 1:1 with Request.Texts, in order. Each has the producing
	// provider's native dimension; widening to the fixed storage width is a
	// separate step at the persistence boundary, not the provider's job.
	Vectors [][]float32
	// Model is the vector-space key: the value to write into the *_embedding
	// "model" column and to filter on at query time. Two vectors are comparable
	// iff their Model matches.
	Model string
	// ProviderName is the provider that actually served the request (for metrics
	// and debugging); FallbackUsed is true when it was not the chain's primary.
	ProviderName string
	FallbackUsed bool
}

Result holds the vectors for a Request plus the provenance a caller needs to store and later query them safely.

type Service ¶

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

Service is the always-present bundle for the embedding lane. Unlike a boot-fixed provider, it is config-driven: it reads Settings on each use and (re)builds its chain + indexer when the configuration changes, so enabling/disabling the lane or swapping model/key/dimension in the UI takes effect at runtime. It does NOT own a River client; the composition root injects the shared one via BindRiverClient.

When the lane is disabled the query embedder reports "no space" (search stays pure-BM25) and the backfill worker no-ops, so an unconfigured deployment behaves exactly as if no embedding existed — the worker just idles.

func Boot(cfg BootConfig) *Service

func (s *Service) BackfillQueueConfig() (string, river.QueueConfig)

func (s *Service) BindRiverClient(c *river.Client[pgx.Tx]) error

func (s *Service) EmbedQuery(ctx context.Context, text string) (pgvector.Vector, string, error)

func (s *Service) RegisterRiverWorker(workers *river.Workers)

func (s *Service) StartBackfill() (rivertype.PeriodicJobHandle, error)

func (s *Service) StopBackfill(handle rivertype.PeriodicJobHandle)

type Settings ¶

type Settings struct {
	Enabled   bool
	Model     string // model id sent to the API
	Dim       int    // requested output dimension (0 = model native)
	APIKey    string
	BaseURL   string
	Normalize bool
}

Settings is the runtime embedding configuration the Service reads on every query and backfill pass, so changes made in the UI take effect without a restart.

type SettingsProvider ¶

type SettingsProvider interface {
	EmbeddingSettings(ctx context.Context) (Settings, error)
}

SettingsProvider supplies the current embedding configuration. The composition root backs it with the DB config store; the Service reads it live.