Documentation
¶
Overview ¶
Package embedding defines the stable text-to-vector protocol and its single-method provider SPI.
Build input with NewRequest and attach Options only for per-call overrides. Provider defaults and identity are fixed when constructing an implementation, not exposed through Model. Dimension discovery belongs to the consuming workflow because it requires an actual embedding request. Float32Vector bridges the protocol's float64 representation to storage SDKs that require float32. Provider options use Options.Extensions.Set so Extensions remains JSON-safe; Request has no arbitrary parameter bag.
Example ¶
package main
import (
"fmt"
"github.com/Tangerg/scope/core/embedding"
)
func main() {
request, err := embedding.NewRequest([]string{"scope", "wild cat"})
if err != nil {
panic(err)
}
options := embedding.Options{Model: "text-embedding-model"}
err = options.Validate()
if err != nil {
panic(err)
}
dimensions := int64(3)
options.Dimensions = &dimensions
request.Options = options
fmt.Println(len(request.Texts), request.Options.Model, *request.Options.Dimensions)
}
Output: 2 text-embedding-model 3
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
Functions ¶
func Float32Vector ¶
Float32Vector narrows Core's canonical vector representation for stores that index in single precision. Conversion belongs at that store boundary rather than in providers that cannot know the eventual index format.
func PlaceOutput ¶ added in v0.16.0
func PlaceOutput(outputs []*Output, index int, embedding []float64, outputMetadata metadata.Map) error
PlaceOutput restores input order for indexed provider results. outputs must be sized to the input count. Out-of-range and duplicate indices are rejected; unfilled positions fail when the Response is built.
Types ¶
type Model ¶
type Model interface {
// Call performs one embedding request after validating the complete batch.
// It must not retain or mutate request, returns outputs in input order, and
// transfers ownership of the response to the caller. Context cancellation
// remains identifiable through errors.Is.
Call(ctx context.Context, request *Request) (*Response, error)
}
Model is the complete provider-neutral embedding SPI. Call implementations validate requests before I/O, reject explicit options they cannot represent, preserve context error identity, and return responses that pass Validate. Defaults, identity, observability, batching, and dimension discovery are independent concerns.
type Options ¶
type Options struct {
Model string `json:"model"`
// Dimensions requests an explicit output vector size. nil leaves it
// up to the provider's default.
Dimensions *int64 `json:"dimensions,omitzero"`
Extensions metadata.Extensions `json:"extensions,omitzero"`
}
Options holds per-request configuration for an embedding call. Pointer fields use nil to preserve the distinction between an override and a provider default. Resolve snapshots mutable values and overlays only fields explicitly supplied by the request.
func (Options) MarshalJSON ¶
func (*Options) UnmarshalJSON ¶
type Output ¶
type Output struct {
Embedding []float64 `json:"embedding"`
Metadata metadata.Map `json:"metadata,omitzero"`
}
func (Output) MarshalJSON ¶
func (*Output) UnmarshalJSON ¶
type Request ¶
type Request struct {
// Texts is the input list. Each entry produces one embedding.
Texts []string `json:"texts,omitzero"`
Options Options `json:"options,omitzero"`
}
func NewRequest ¶
NewRequest snapshots the caller's input texts.
func (Request) MarshalJSON ¶
func (*Request) UnmarshalJSON ¶
type Response ¶
type Response struct {
// Outputs holds one entry per input text, in the same order.
Outputs []*Output `json:"outputs,omitzero"`
Metadata *ResponseMetadata `json:"metadata,omitzero"`
}
func NewResponse ¶
func NewResponse(outputs []*Output, responseMetadata *ResponseMetadata) (*Response, error)
func (Response) MarshalJSON ¶
func (*Response) UnmarshalJSON ¶
func (*Response) ValidateFor ¶ added in v0.16.0
ValidateFor checks input/output correspondence and any explicitly requested dimensions.
type ResponseMetadata ¶
type ResponseMetadata struct {
Model string `json:"model"`
// Usage breaks down token consumption. nil means the provider did not
// report usage.
Usage *Usage `json:"usage,omitzero"`
CreatedAt time.Time `json:"created_at,omitzero"`
Extra metadata.Map `json:"extra,omitzero"`
}
func (ResponseMetadata) MarshalJSON ¶
func (r ResponseMetadata) MarshalJSON() ([]byte, error)
func (*ResponseMetadata) UnmarshalJSON ¶
func (r *ResponseMetadata) UnmarshalJSON(data []byte) error
Source Files