Help us shape the future of Go! Take the 2026 Go Developer Survey

semantic

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 27, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package semantic observes possible completed-answer reuse. Shadow decisions are advisory: they never serve text, change claims, or authorize generation.

Index

Constants

View Source 
const (
	DefaultMinSimilarity = 0.9
	DefaultTopK          = 3
	DefaultMaxScan       = 1000
	DefaultMaxEntries    = 1000
	DefaultMaxInputBytes = 8192
	DefaultTimeoutMS     = 10000
	MaxTopK              = 10
	MaxScan              = 10000
	MaxEntries           = 10000
	MaxInputBytes        = 32768
	MaxTimeoutMS         = 60000
	MaxDimensions        = 4096
)

Variables

This section is empty.

Functions

func Cosine 

func Cosine(a, b []float32) (float64, error)

Cosine compares finite, nonzero vectors with matching bounded dimensions. float64 accumulation avoids overflowing when finite float32 values are large.

func EntryID 

func EntryID(e Entry) string

EntryID binds an entry to its exact source snapshot within one embedding partition. Vectors and expiry do not create duplicate copies of that snapshot.

func ValidatePut 

func ValidatePut(p PutRequest) error

ValidatePut verifies identities, bounded vectors and the short-lived source pointer. The source artifact itself must also be checked by the index owner.

func ValidateQuery 

func ValidateQuery(q Query) error

ValidateQuery checks the fully specified wire request; defaults belong to NormalizeConfig and are deliberately not inferred at the broker boundary.

Types

type Candidate 

type Candidate struct {
	Source     Source    `json:"source"`
	Similarity float64   `json:"similarity"`
	CreatedAt  time.Time `json:"created_at"`
	ExpiresAt  time.Time `json:"expires_at"`
}

type Config 

type Config struct {
	Mode             string            `json:"mode"`
	Family           string            `json:"family"`
	Domain           string            `json:"domain"`
	EvidenceRevision string            `json:"evidence_revision"`
	Bindings         map[string]string `json:"bindings,omitempty"`
	EmbeddingModel   string            `json:"embedding_model"`
	MinSimilarity    float64           `json:"min_similarity,omitempty"`
	TopK             int               `json:"top_k,omitempty"`
	MaxScan          int               `json:"max_scan,omitempty"`
	MaxEntries       int               `json:"max_entries,omitempty"`
	MaxInputBytes    int               `json:"max_input_bytes,omitempty"`
	TimeoutMS        int               `json:"timeout_ms,omitempty"`
}

Config is opt-in. Mode accepts only "shadow" in this release.

func NormalizeConfig 

func NormalizeConfig(c Config) (Config, error)

NormalizeConfig fills bounded defaults and rejects modes that could serve an answer. The returned bindings are a copy so later caller edits cannot alter it.

type Embedder 

type Embedder interface {
	Embed(context.Context, string) (Embedding, error)
}

type Embedding 

type Embedding struct {
	ModelID     string    `json:"model_id"`
	Vector      []float32 `json:"-"`
	InputTokens *int64    `json:"input_tokens"`
	DurationMS  float64   `json:"duration_ms"`
}

type Entry 

type Entry struct {
	ID        string    `json:"id"`
	Partition string    `json:"partition"`
	ModelID   string    `json:"model_id"`
	Vector    []float32 `json:"vector"`
	Source    Source    `json:"source"`
	CreatedAt time.Time `json:"created_at"`
	ExpiresAt time.Time `json:"expires_at"`
}

type Index 

type Index interface {
	QuerySemantic(context.Context, Query) (SearchResult, error)
	PutSemantic(context.Context, PutRequest) error
}

type Observation 

type Observation struct {
	Mode                 string        `json:"mode"`
	Status               string        `json:"status"`
	Partition            string        `json:"partition,omitempty"`
	EmbeddingModelID     string        `json:"embedding_model_id,omitempty"`
	EmbeddingInputTokens *int64        `json:"embedding_input_tokens"`
	EmbeddingMS          float64       `json:"embedding_ms,omitempty"`
	TotalMS              float64       `json:"total_ms"`
	Search               *SearchResult `json:"search,omitempty"`
	Indexed              bool          `json:"indexed"`
	GenerationAvoided    bool          `json:"generation_avoided"`
}

Observation deliberately has no reused/avoided tokens or alternative answer.

type OllamaEmbedder 

type OllamaEmbedder struct {
	// contains filtered or unexported fields
}

OllamaEmbedder captures already-installed local weights and the Ollama runtime version. It never pulls models, follows redirects, or uses environment proxies. Its methods are safe for concurrent use; its pinned identity is immutable.

func NewOllamaEmbedder 

func NewOllamaEmbedder(baseURL, model string, maxInputBytes int) (*OllamaEmbedder, error)

NewOllamaEmbedder validates the installed model without generating a vector. The empty origin selects http://127.0.0.1:11434. Discovery is capped at 10s.

func NewOllamaEmbedderContext 

func NewOllamaEmbedderContext(ctx context.Context, baseURL, model string, maxInputBytes int) (*OllamaEmbedder, error)

NewOllamaEmbedderContext also includes metadata discovery in caller's deadline.

func (*OllamaEmbedder) Close 

func (p *OllamaEmbedder) Close()

Close releases idle local connections. It does not unload model weights.

func (*OllamaEmbedder) Embed 

func (p *OllamaEmbedder) Embed(ctx context.Context, text string) (Embedding, error)

Embed sends one bounded text input with truncation disabled. Both sides of inference recheck the model digest, embedding capability and runtime version. A failed or changed snapshot never returns a usable vector or token count.

type PutRequest 

type PutRequest struct {
	Entry      Entry `json:"entry"`
	MaxEntries int   `json:"max_entries"`
}

type Query 

type Query struct {
	Partition     string    `json:"partition"`
	ModelID       string    `json:"model_id"`
	Vector        []float32 `json:"vector"`
	MinSimilarity float64   `json:"min_similarity"`
	TopK          int       `json:"top_k"`
	MaxScan       int       `json:"max_scan"`
}

type SearchResult 

type SearchResult struct {
	Candidates []Candidate `json:"candidates"`
	Scanned    int         `json:"scanned"`
	Truncated  bool        `json:"truncated"`
}

type Source 

type Source struct {
	Key          string `json:"key"`
	Version      int64  `json:"version"`
	SHA256       string `json:"sha256"`
	OutputSHA256 string `json:"output_sha256"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.