Janady13/missionmatch / internal/platform/embeddings/embeddings.go

1// Package embeddings is the cloud-agnostic embedding provider port. 2// 3// The core app NEVER depends on a native ML stack, it calls a provider over HTTP, or uses the 4// deterministic offline provider for dev/tests (CLAUDE.md). Selecting a provider is configuration: 5// - fake : deterministic, offline (dev/tests) 6// - openai : any OpenAI-compatible /v1/embeddings endpoint, self-hosted vLLM (the 7// production CUI path) or OpenAI 8// - azure_openai : Azure Government OpenAI (OpenAI-compatible; full adapter wired at deploy) 9// - bedrock : AWS GovCloud Bedrock (InvokeModel; adapter wired at deploy, needs the AWS SDK) 10// 11// All vectors are L2-normalized so cosine distance (the schema's vector_cosine_ops / <=>) is meaningful. 12package embeddings 13 14import ( 15 "bytes" 16 "context" 17 "crypto/sha256" 18 "encoding/json" 19 "errors" 20 "fmt" 21 "math" 22 "net/http" 23 "sort" 24 "strings" 25 "time" 26 27 "github.com/missionworkforce/missionmatch/internal/platform/config" 28) 29 30// SkillEmbedText is the canonical text to embed for one skill: the name, with the category in 31// parentheses when present. The backfill (the writer of skills.embedding) and the boot vector model 32// check (the verifier that re embeds a stored skill to confirm the model) MUST embed the SAME text, or 33// the check would see a false mismatch on every categorized skill. This function is that single source. 34func SkillEmbedText(name, category string) string { 35 if category != "" { 36 return name + " (" + category + ")" 37 } 38 return name 39} 40 41// Embedder turns text into a fixed-dimension, L2-normalized embedding. 42// Implementations MUST be deterministic for a given input where feasible (the fake one always is). 43type Embedder interface { 44 Embed(ctx context.Context, text string) ([]float32, error) 45 EmbedBatch(ctx context.Context, texts []string) ([][]float32, error) 46 Dimension() int 47} 48 49// New selects an Embedder from config. The bedrock/azure_openai managed adapters that require cloud 50// SDKs are intentionally not compiled into the core module yet; they are wired at deploy time behind 51// this same interface (STACK_DECISIONS.md §9). 52func New(cfg config.Embeddings) (Embedder, error) { 53 switch cfg.Provider { 54 case config.ProviderFake: 55 return NewDeterministic(cfg.Dimension), nil 56 case config.ProviderOpenAI, config.ProviderAzureOpenAI: 57 return NewHTTP(cfg.Endpoint, cfg.Model, cfg.APIKey, cfg.Dimension, nil), nil 58 case config.ProviderMegamind: 59 return newMegamind(cfg) 60 case config.ProviderBedrock: 61 return nil, fmt.Errorf("embeddings: provider %q adapter not wired into core build; add the AWS SDK adapter at deploy", cfg.Provider) 62 default: 63 return nil, fmt.Errorf("embeddings: unknown provider %q", cfg.Provider) 64 } 65} 66 67// ---------- deterministic offline provider ---------- 68 69type deterministicEmbedder struct{ dim int } 70 71// NewDeterministic returns an offline Embedder that maps text to a stable, L2-normalized vector. 72// Same text => same vector; different text => (almost surely) different vector. Good for dev, tests, 73// and as the engine's offline semantic backend. 74func NewDeterministic(dim int) Embedder { return deterministicEmbedder{dim: dim} } 75 76func (d deterministicEmbedder) Dimension() int { return d.dim } 77 78func (d deterministicEmbedder) Embed(_ context.Context, text string) ([]float32, error) { 79 return deterministicVector(text, d.dim), nil 80} 81 82func (d deterministicEmbedder) EmbedBatch(_ context.Context, texts []string) ([][]float32, error) { 83 out := make([][]float32, len(texts)) 84 for i, t := range texts { 85 out[i] = deterministicVector(t, d.dim) 86 } 87 return out, nil 88} 89 90func deterministicVector(text string, dim int) []float32 { 91 v := make([]float32, dim) 92 sum := sha256.Sum256([]byte(strings.ToLower(strings.TrimSpace(text)))) 93 var x uint64 94 for i := 0; i < 8; i++ { 95 x = x<<8 | uint64(sum[i]) 96 } 97 if x == 0 { 98 x = 0x9e3779b97f4a7c15 99 } 100 for i := range v { 101 // xorshift64, deterministic, well-spread. 102 x ^= x << 13 103 x ^= x >> 7 104 x ^= x << 17 105 v[i] = float32(int64(x%2000)-1000) / 1000.0 106 } 107 normalize(v) 108 return v 109} 110 111// ---------- OpenAI-compatible HTTP provider ---------- 112 113type httpEmbedder struct { 114 endpoint string // full embeddings URL, e.g. https://host/v1/embeddings 115 model string 116 apiKey string 117 dim int 118 client *http.Client 119} 120 121// NewHTTP returns an Embedder for any OpenAI-compatible embeddings endpoint. endpoint is the full 122// URL. A nil client gets a sensible default with a timeout. 123func NewHTTP(endpoint, model, apiKey string, dim int, client *http.Client) Embedder { 124 if client == nil { 125 client = &http.Client{Timeout: 30 * time.Second} 126 } 127 return &httpEmbedder{endpoint: endpoint, model: model, apiKey: [credential removed], dim: dim, client: client} 128} 129 130func (h *httpEmbedder) Dimension() int { return h.dim } 131 132func (h *httpEmbedder) Embed(ctx context.Context, text string) ([]float32, error) { 133 out, err := h.EmbedBatch(ctx, []string{text}) 134 if err != nil { 135 return nil, err 136 } 137 return out[0], nil 138} 139 140type embedRequest struct { 141 Model string `json:"model"` 142 Input []string `json:"input"` 143} 144 145type embedResponse struct { 146 Data []struct { 147 Index int `json:"index"` 148 Embedding []float32 `json:"embedding"` 149 } `json:"data"` 150} 151 152func (h *httpEmbedder) EmbedBatch(ctx context.Context, texts []string) ([][]float32, error) { 153 if len(texts) == 0 { 154 return nil, nil 155 } 156 body, err := json.Marshal(embedRequest{Model: h.model, Input: texts}) 157 if err != nil { 158 return nil, fmt.Errorf("embeddings: marshal request: %w", err) 159 } 160 req, err := http.NewRequestWithContext(ctx, http.MethodPost, h.endpoint, bytes.NewReader(body)) 161 if err != nil { 162 return nil, fmt.Errorf("embeddings: new request: %w", err) 163 } 164 req.Header.Set("Content-Type", "application/json") 165 if h.apiKey != "" { 166 req.Header.Set("Authorization", "Bearer "+h.apiKey) 167 req.Header.Set("api-key", h.apiKey) // Azure OpenAI uses this header 168 } 169 170 resp, err := h.client.Do(req) 171 if err != nil { 172 return nil, fmt.Errorf("embeddings: request failed: %w", err) 173 } 174 defer resp.Body.Close() 175 if resp.StatusCode != http.StatusOK { 176 return nil, fmt.Errorf("embeddings: provider returned %s", resp.Status) 177 } 178 179 var parsed embedResponse 180 if err := json.NewDecoder(resp.Body).Decode(&parsed); err != nil { 181 return nil, fmt.Errorf("embeddings: decode response: %w", err) 182 } 183 if len(parsed.Data) != len(texts) { 184 return nil, fmt.Errorf("embeddings: expected %d vectors, got %d", len(texts), len(parsed.Data)) 185 } 186 // Order by index, providers may return out of order. 187 sort.Slice(parsed.Data, func(i, j int) bool { return parsed.Data[i].Index < parsed.Data[j].Index }) 188 189 out := make([][]float32, len(parsed.Data)) 190 for i, d := range parsed.Data { 191 if h.dim > 0 && len(d.Embedding) != h.dim { 192 return nil, fmt.Errorf("embeddings: vector %d has dim %d, want %d (check MM_EMBED_DIMENSION vs the model)", i, len(d.Embedding), h.dim) 193 } 194 vec := d.Embedding 195 normalize(vec) 196 out[i] = vec 197 } 198 return out, nil 199} 200 201// ---------- shared ---------- 202 203func normalize(v []float32) { 204 var ss float64 205 for _, f := range v { 206 ss += float64(f) * float64(f) 207 } 208 if ss == 0 { 209 return 210 } 211 inv := float32(1.0 / math.Sqrt(ss)) 212 for i := range v { 213 v[i] *= inv 214 } 215} 216 217// ErrEmpty is returned by helpers that refuse empty input. 218var ErrEmpty = errors.New("embeddings: empty input") 219