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.SetExtension 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 ¶
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 is the provider model identifier
// (e.g. "text-embedding-3-small").
Model string `json:"model"`
// Dimensions requests an explicit output vector size. nil leaves it
// up to the provider's default.
Dimensions *int64 `json:"dimensions,omitempty"`
// Extensions carries JSON-safe provider-specific options unknown to this
// struct.
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 is the vector representation of the input.
Embedding []float64 `json:"embedding"`
// Metadata carries provider-specific per-output extras.
Metadata metadata.Map `json:"metadata,omitzero"`
}
Output is one embedding plus its metadata.
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"`
}
Request is one embedding call: the input texts and explicit options.
func NewRequest ¶
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,omitempty"`
}
Response is the full embedding output: one *Output per input plus shared response metadata.
func NewResponse ¶
func NewResponse(outputs []*Output, metadata *ResponseMetadata) (*Response, error)
func (Response) MarshalJSON ¶
func (*Response) UnmarshalJSON ¶
type ResponseMetadata ¶
type ResponseMetadata struct {
// Model is the model name actually served.
Model string `json:"model"`
// Usage breaks down token consumption. nil means the provider did not
// report usage.
Usage *Usage `json:"usage,omitempty"`
// Created is the provider-reported creation time, Unix seconds.
Created int64 `json:"created"`
// Extra carries JSON-safe provider-specific metadata.
Extra metadata.Map `json:"extra,omitzero"`
}
ResponseMetadata holds response-level metadata: the model actually used, token usage, creation time, and provider extras.
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 are tokens consumed embedding the inputs.
InputTokens int64 `json:"input_tokens"`
}
Usage records the token consumption an embedding request reported back. Embedding is input-only — there is no completion, reasoning, or cache dimension — so a single count is the whole story. Providers that report a "total" figure map it here: for embeddings every token is input.
Source Files