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. Implementations reject explicit options they cannot represent and return responses that pass Validate. Defaults, identity, batching, and dimension discovery are independent concerns.
type Options ¶
type Options struct {
Model string `json:"model"`
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 contains reported numeric coordinates; JSON null is not a zero coordinate.
Embedding []float64 `json:"embedding"`
Metadata metadata.Map `json:"metadata,omitzero"`
}
func (Output) MarshalJSON ¶
func (*Output) UnmarshalJSON ¶
type Request ¶
type Request struct {
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 is nil when 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
type Usage ¶
type Usage struct {
InputTokens int64 `json:"input_tokens"`
}
Usage contains input tokens only; provider totals map to InputTokens. JSON requires input_tokens even when zero; unreported usage belongs to a nil ResponseMetadata.Usage.
Source Files