embedder

Documentation

Index

• Constants
• Variables
• func L2NormalizeInPlace(v []float32) error
• func ValidProfile(p Profile) bool
• func ValidateEmbedInput(texts []string) error
• func ValidateGeometry(e Embedder, wantDim int, wantModel string) error
• func ValidateOutputVectors(texts []string, vectors [][]float32, dim int) error
• func VectorL2Norm(v []float32) float64
• type Embedder
• type Profile
• type ProfileDefaults
  • func DefaultGeometry(p Profile) (ProfileDefaults, error)
• type Registry
  • func NewRegistry(byProfile map[Profile]Embedder) (*Registry, error)
  • func (r *Registry) ForProfile(profile Profile) (Embedder, error)
  • func (r *Registry) Profiles() []Profile
• type Stub
  • func NewStub(profile Profile, modelID string, dim int) (*Stub, error)
  • func NewStubForProfile(profile Profile) (*Stub, error)
  • func (s *Stub) Dimensions() int
  • func (s *Stub) Embed(ctx context.Context, texts []string) ([][]float32, error)
  • func (s *Stub) ModelID() string
  • func (s *Stub) Name() string
  • func (s *Stub) Profile() Profile

Constants

const (
	MaxBatchTexts = 64
	MaxTextBytes  = 32 * 1024 // 32 KiB per text
)

Input limits for Embed (fail closed before upstream).

Variables

var (
	// ErrUnknownProfile is returned for unrecognized or empty profile keys.
	ErrUnknownProfile = errors.New("unknown embedding profile")
	// ErrDuplicateProfile is returned when two embedders claim the same profile.
	ErrDuplicateProfile = errors.New("duplicate embedding profile")
	// ErrMissingEmbedder is returned when a required profile has no implementation.
	ErrMissingEmbedder = errors.New("missing embedder implementation")
	// ErrGeometryMismatch is returned when Dimensions/ModelID do not match expected config.
	ErrGeometryMismatch = errors.New("embedding geometry mismatch")
	// ErrEmptyBatch is returned when Embed is called with no texts.
	ErrEmptyBatch = errors.New("empty embedding batch")
	// ErrBatchTooLarge is returned when the batch exceeds MaxBatchTexts.
	ErrBatchTooLarge = errors.New("embedding batch too large")
	// ErrTextTooLong is returned when a text exceeds MaxTextBytes.
	ErrTextTooLong = errors.New("embedding text too long")
	// ErrInvalidVector is returned when a backend yields wrong-length or non-finite vectors.
	ErrInvalidVector = errors.New("invalid embedding vector")
)

Functions

func L2NormalizeInPlace

func L2NormalizeInPlace(v []float32) error

L2NormalizeInPlace scales v to unit length. Zero vectors become an error.

func ValidProfile

func ValidProfile(p Profile) bool

ValidProfile reports whether p is a known deployment profile.

func ValidateEmbedInput

func ValidateEmbedInput(texts []string) error

ValidateEmbedInput rejects empty/oversized batches before calling a backend.

func ValidateGeometry

func ValidateGeometry(e Embedder, wantDim int, wantModel string) error

ValidateGeometry fails closed when the embedder's dim/model do not match expected config.

func ValidateOutputVectors

func ValidateOutputVectors(texts []string, vectors [][]float32, dim int) error

ValidateOutputVectors checks batch length, dim, and finite floats (not L2 — callers may assert separately).

func VectorL2Norm

func VectorL2Norm(v []float32) float64

VectorL2Norm returns the Euclidean norm of v.

Types

type Embedder

type Embedder interface {
	// Embed returns one L2-normalized float32 vector per input text.
	// Length of the result slice equals len(texts); each vector length equals Dimensions().
	Embed(ctx context.Context, texts []string) ([][]float32, error)

	// Name returns the backend identifier (e.g. "stub", "tei", "openai", "local").
	Name() string

	// ModelID returns the model identifier (e.g. "all-MiniLM-L6-v2", "BAAI/bge-m3").
	ModelID() string

	// Dimensions returns the embedding vector length for this backend.
	Dimensions() int

	// Profile returns the deployment profile this backend serves.
	Profile() Profile
}

Embedder produces embedding vectors for text batches. Implementations must be safe for concurrent use after construction. All vectors from a single Embed call use the same model geometry.

type Profile

type Profile string

Profile is a deployment-time embedding profile key. Profiles are not interchangeable at the vector-search level without migration.

const (
	ProfileCPU    Profile = "cpu"
	ProfileGPU    Profile = "gpu"
	ProfileHosted Profile = "hosted"
)

type ProfileDefaults

type ProfileDefaults struct {
	ModelID    string
	Dimensions int
}

ProfileDefaults documents the planned default geometry per profile (ADR-0046). M1 does not run TEI/OpenAI; stubs may use these dims for contract tests.

func DefaultGeometry

func DefaultGeometry(p Profile) (ProfileDefaults, error)

DefaultGeometry returns the documented default model/dim for a known profile.

type Registry

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

Registry maps deployment Profile keys to Embedder implementations (read-only after New).

func NewRegistry

func NewRegistry(byProfile map[Profile]Embedder) (*Registry, error)

NewRegistry constructs a registry from profile → impl.

func (*Registry) ForProfile

func (r *Registry) ForProfile(profile Profile) (Embedder, error)

ForProfile returns the embedder for profile or ErrUnknownProfile.

func (*Registry) Profiles

func (r *Registry) Profiles() []Profile

Profiles returns sorted profile keys present in the registry.

type Stub

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

Stub is a deterministic, L2-normalized embedder for tests and local contract checks. It is not a production inference backend (Name returns "stub").

func NewStub

func NewStub(profile Profile, modelID string, dim int) (*Stub, error)

NewStub constructs a stub embedder for the given profile geometry.

func NewStubForProfile

func NewStubForProfile(profile Profile) (*Stub, error)

NewStubForProfile builds a stub using DefaultGeometry for the profile.

func (*Stub) Dimensions

func (s *Stub) Dimensions() int

func (*Stub) Embed

func (s *Stub) Embed(ctx context.Context, texts []string) ([][]float32, error)

Embed returns deterministic L2-normalized vectors derived from text hashes.

func (*Stub) ModelID

func (s *Stub) ModelID() string

func (*Stub) Name

func (s *Stub) Name() string

func (*Stub) Profile

func (s *Stub) Profile() Profile