Documentation
¶
Overview ¶
Package embedding defines the provider-neutral boundary between a generated Golem semantic index and an application-selected embedding service.
Providers translate canonical text into finite float32 vectors. They do not receive model names, database identities, actors, policies, or raw records. Golem owns durable indexing, storage, authorization, and similarity queries.
Index ¶
- Constants
- func Failf(code Code, cause error, format string, arguments ...any) error
- func NewError(code Code, cause error) error
- func ValidateResult(specification Specification, inputs []Input, vectors []Vector) error
- type Code
- type Error
- type Input
- type Provider
- type Registry
- type Specification
- func (value Specification) Dimensions() int
- func (value Specification) FingerprintInput() string
- func (value Specification) MaximumBatch() int
- func (value Specification) Model() string
- func (value Specification) Provider() string
- func (value Specification) Revision() string
- func (value Specification) Validate() error
- type Vector
Constants ¶
const ( // MaximumDimensions is the portable v1 ceiling. PostgreSQL pgvector's // single-precision vector type has the same indexed dimension ceiling. MaximumDimensions = 2000 MaximumBatchSize = 2048 MaximumInputBytes = 16 << 20 )
Variables ¶
This section is empty.
Functions ¶
func Failf ¶ added in v0.3.0
Failf builds a closed embedding failure that names what was refused. The formatted detail is printed, so it must carry only fields, bounds, and lengths; cause stays available to errors.Is and errors.As but is never printed, because application providers may put credentials, request bodies, model names, or remote payloads in it.
func ValidateResult ¶
func ValidateResult(specification Specification, inputs []Input, vectors []Vector) error
ValidateResult verifies the closed positional batch contract without exposing provider errors or input contents in the returned diagnostic.
Types ¶
type Input ¶
type Input struct {
// contains filtered or unexported fields
}
Input is one canonical document. Key is an opaque job-local correlation key; providers must not interpret or retain it.
type Provider ¶
type Provider interface {
Specification() Specification
Embed(ctx context.Context, inputs []Input) ([]Vector, error)
}
Provider embeds one ordered batch. Results must preserve input order and contain exactly Specification.Dimensions finite values each. Embed may be called concurrently and must honor context cancellation; implementations own any concurrency limiting required by their upstream service.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is an immutable application-owned mapping from schema space names to embedding providers. The zero value is a valid empty registry.
func (Registry) Specification ¶
func (registry Registry) Specification(name string) (Specification, bool)
type Specification ¶
type Specification struct {
// contains filtered or unexported fields
}
Specification is the immutable identity of an embedding space. Changing any value creates a different space and makes existing projections stale.
func NewSpecification ¶
func NewSpecification(provider, model, revision string, dimensions, maximumBatch int) (Specification, error)
func (Specification) Dimensions ¶
func (value Specification) Dimensions() int
func (Specification) FingerprintInput ¶
func (value Specification) FingerprintInput() string
FingerprintInput is a length-delimited, stable description suitable for a caller-owned hash. It deliberately does not choose a hashing algorithm.
func (Specification) MaximumBatch ¶
func (value Specification) MaximumBatch() int
func (Specification) Model ¶
func (value Specification) Model() string
func (Specification) Provider ¶
func (value Specification) Provider() string
func (Specification) Revision ¶
func (value Specification) Revision() string
func (Specification) Validate ¶
func (value Specification) Validate() error
type Vector ¶
type Vector struct {
// contains filtered or unexported fields
}
Vector is an immutable finite single-precision embedding.
Source Files