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// Embedder turns text into a fixed-dimension, L2-normalized embedding. 31// Implementations MUST be deterministic for a given input where feasible (the fake one always is). 32type Embedder interface { 33 Embed(ctx context.Context, text string) ([]float32, error) 34 EmbedBatch(ctx context.Context, texts []string) ([][]float32, error) 35 Dimension() int 36} 37 38// New selects an Embedder from config. The bedrock/azure_openai managed adapters that require cloud 39// SDKs are intentionally not compiled into the core module yet; they are wired at deploy time behind 40// this same interface (STACK_DECISIONS.md §9). 41func New(cfg config.Embeddings) (Embedder, error) { 42 switch cfg.Provider { 43 case config.ProviderFake: 44 return NewDeterministic(cfg.Dimension), nil 45 case config.ProviderOpenAI, config.ProviderAzureOpenAI: 46 return NewHTTP(cfg.Endpoint, cfg.Model, cfg.APIKey, cfg.Dimension, nil), nil 47 case config.ProviderBedrock: 48 return nil, fmt.Errorf("embeddings: provider %q adapter not wired into core build; add the AWS SDK adapter at deploy", cfg.Provider) 49 default: 50 return nil, fmt.Errorf("embeddings: unknown provider %q", cfg.Provider) 51 } 52} 53 54// ---------- deterministic offline provider ---------- 55 56type deterministicEmbedder struct{ dim int } 57 58// NewDeterministic returns an offline Embedder that maps text to a stable, L2-normalized vector. 59// Same text => same vector; different text => (almost surely) different vector. Good for dev, tests, 60// and as the engine's offline semantic backend. 61func NewDeterministic(dim int) Embedder { return deterministicEmbedder{dim: dim} } 62 63func (d deterministicEmbedder) Dimension() int { return d.dim } 64 65func (d deterministicEmbedder) Embed(_ context.Context, text string) ([]float32, error) { 66 return deterministicVector(text, d.dim), nil 67} 68 69func (d deterministicEmbedder) EmbedBatch(_ context.Context, texts []string) ([][]float32, error) { 70 out := make([][]float32, len(texts)) 71 for i, t := range texts { 72 out[i] = deterministicVector(t, d.dim) 73 } 74 return out, nil 75} 76 77func deterministicVector(text string, dim int) []float32 { 78 v := make([]float32, dim) 79 sum := sha256.Sum256([]byte(strings.ToLower(strings.TrimSpace(text)))) 80 var x uint64 81 for i := 0; i < 8; i++ { 82 x = x<<8 | uint64(sum[i]) 83 } 84 if x == 0 { 85 x = 0x9e3779b97f4a7c15 86 } 87 for i := range v { 88 // xorshift64, deterministic, well-spread. 89 x ^= x << 13 90 x ^= x >> 7 91 x ^= x << 17 92 v[i] = float32(int64(x%2000)-1000) / 1000.0 93 } 94 normalize(v) 95 return v 96} 97 98// ---------- OpenAI-compatible HTTP provider ---------- 99 100type httpEmbedder struct { 101 endpoint string // full embeddings URL, e.g. https://host/v1/embeddings 102 model string 103 apiKey string 104 dim int 105 client *http.Client 106} 107 108// NewHTTP returns an Embedder for any OpenAI-compatible embeddings endpoint. endpoint is the full 109// URL. A nil client gets a sensible default with a timeout. 110func NewHTTP(endpoint, model, apiKey string, dim int, client *http.Client) Embedder { 111 if client == nil { 112 client = &http.Client{Timeout: 30 * time.Second} 113 } 114 return &httpEmbedder{endpoint: endpoint, model: model, apiKey: [credential removed], dim: dim, client: client} 115} 116 117func (h *httpEmbedder) Dimension() int { return h.dim } 118 119func (h *httpEmbedder) Embed(ctx context.Context, text string) ([]float32, error) { 120 out, err := h.EmbedBatch(ctx, []string{text}) 121 if err != nil { 122 return nil, err 123 } 124 return out[0], nil 125} 126 127type embedRequest struct { 128 Model string `json:"model"` 129 Input []string `json:"input"` 130} 131 132type embedResponse struct { 133 Data []struct { 134 Index int `json:"index"` 135 Embedding []float32 `json:"embedding"` 136 } `json:"data"` 137} 138 139func (h *httpEmbedder) EmbedBatch(ctx context.Context, texts []string) ([][]float32, error) { 140 if len(texts) == 0 { 141 return nil, nil 142 } 143 body, err := json.Marshal(embedRequest{Model: h.model, Input: texts}) 144 if err != nil { 145 return nil, fmt.Errorf("embeddings: marshal request: %w", err) 146 } 147 req, err := http.NewRequestWithContext(ctx, http.MethodPost, h.endpoint, bytes.NewReader(body)) 148 if err != nil { 149 return nil, fmt.Errorf("embeddings: new request: %w", err) 150 } 151 req.Header.Set("Content-Type", "application/json") 152 if h.apiKey != "" { 153 req.Header.Set("Authorization", "Bearer "+h.apiKey) 154 req.Header.Set("api-key", h.apiKey) // Azure OpenAI uses this header 155 } 156 157 resp, err := h.client.Do(req) 158 if err != nil { 159 return nil, fmt.Errorf("embeddings: request failed: %w", err) 160 } 161 defer resp.Body.Close() 162 if resp.StatusCode != http.StatusOK { 163 return nil, fmt.Errorf("embeddings: provider returned %s", resp.Status) 164 } 165 166 var parsed embedResponse 167 if err := json.NewDecoder(resp.Body).Decode(&parsed); err != nil { 168 return nil, fmt.Errorf("embeddings: decode response: %w", err) 169 } 170 if len(parsed.Data) != len(texts) { 171 return nil, fmt.Errorf("embeddings: expected %d vectors, got %d", len(texts), len(parsed.Data)) 172 } 173 // Order by index, providers may return out of order. 174 sort.Slice(parsed.Data, func(i, j int) bool { return parsed.Data[i].Index < parsed.Data[j].Index }) 175 176 out := make([][]float32, len(parsed.Data)) 177 for i, d := range parsed.Data { 178 if h.dim > 0 && len(d.Embedding) != h.dim { 179 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) 180 } 181 vec := d.Embedding 182 normalize(vec) 183 out[i] = vec 184 } 185 return out, nil 186} 187 188// ---------- shared ---------- 189 190func normalize(v []float32) { 191 var ss float64 192 for _, f := range v { 193 ss += float64(f) * float64(f) 194 } 195 if ss == 0 { 196 return 197 } 198 inv := float32(1.0 / math.Sqrt(ss)) 199 for i := range v { 200 v[i] *= inv 201 } 202} 203 204// ErrEmpty is returned by helpers that refuse empty input. 205var ErrEmpty = errors.New("embeddings: empty input") 206