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 ¶
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 stores one provider result at the position it belongs to.
outputs must already be sized to the input count. Providers that tag each embedding with its own index may answer out of order, so placing by index is what restores the correspondence Response.Outputs declares; appending in arrival order silently pairs texts with the wrong vectors. An index outside the request and a position claimed twice are both rejected, and a position left unfilled fails 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 ModelFunc ¶
ModelFunc lets an ordinary function satisfy Model without declaring a named type, which is what keeps middleware and test doubles from each inventing their own adapter.
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 ¶
NewRequest preserves the provider-neutral batch shape and clones the input, so later caller mutation cannot change a request already in flight.
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, responseMetadata *ResponseMetadata) (*Response, error)
NewResponse validates a complete provider result at the protocol boundary.
func (Response) MarshalJSON ¶
func (*Response) UnmarshalJSON ¶
func (*Response) ValidateFor ¶ added in v0.16.0
ValidateFor checks a provider result against the request it answers.
Outputs declares one entry per input text in the same order, and that correspondence is the whole basis for using an embedding: a response one vector short leaves every later text paired with its neighbor's vector, and nothing downstream can notice. Validate alone cannot see it, because the input count is not part of the response, so this is the check that makes the declared correspondence enforceable rather than aspirational.
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"`
// CreatedAt is the provider-reported creation timestamp.
CreatedAt time.Time `json:"created_at,omitzero"`
// 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