embeddings

type Cache interface {
	Get(ctx context.Context, text string) ([]float64, bool)
	Put(ctx context.Context, text string, embedding []float64)
}

type CacheConfig struct {
	// Type is the cache to be used.
	// Options: Blank (Disabled), memory, sql
	Type string `json:"type"`

	// Size is the maximum number of embeddings to cache in memory.
	// This value is ignored for sql
	Size int `json:"cacheSize"`
}

type CacheStats struct {
	Size     int
	Capacity int
}

type Config struct {
	// Enabled determines if embedding-based search is active.
	// When false, the service returns nil and falls back to Jaro-Winkler.
	Enabled bool `json:"enabled"`

	// Provider configuration for the embedding API.
	Provider ProviderConfig `json:"provider"`

	// Cache stores embeddings for the specified model
	Cache CacheConfig `json:"cache"`

	// CrossScriptOnly when true, embeddings are only used for non-Latin queries.
	// Latin-only queries fall back to Jaro-Winkler for better performance.
	CrossScriptOnly bool `json:"crossScriptOnly"`

	// SimilarityThreshold is the minimum cosine similarity to consider a match.
	// Range: 0.0 to 1.0
	SimilarityThreshold float64 `json:"similarityThreshold"`

	// BatchSize is the number of texts to encode in a single API call.
	// Larger batches are more efficient but use more memory.
	BatchSize int `json:"batchSize"`

	// IndexBuildTimeout is the maximum time allowed for building the index.
	IndexBuildTimeout time.Duration `json:"indexBuildTimeout"`
}

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

type MockProviderOption func(*MockProvider)

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

type Provider interface {
	// Embed generates embeddings for a batch of texts.
	// Returns L2-normalized vectors suitable for cosine similarity.
	// The returned vectors MUST be L2-normalized.
	Embed(ctx context.Context, texts []string) ([][]float64, error)

	// Dimension returns the embedding dimension for this provider.
	Dimension() int

	// Name returns the provider name for logging/telemetry.
	Name() string

	// Close releases any resources held by the provider.
	Close() error
}

type ProviderConfig struct {
	// Name of the provider: "openai", "ollama", "openrouter", "azure"
	// All providers use OpenAI-compatible API format.
	// Default: "ollama"
	Name string `json:"name"`

	// BaseURL is the API endpoint.
	// Examples:
	//   - Ollama: "http://localhost:11434/v1"
	//   - OpenAI: "https://api.openai.com/v1"
	//   - OpenRouter: "https://openrouter.ai/api/v1"
	//   - Azure: "https://{resource}.openai.azure.com/openai/deployments/{deployment}"
	BaseURL string `json:"baseURL"`

	// APIKey for authentication. Optional for local providers (Ollama).
	// Can also be set via EMBEDDINGS_API_KEY environment variable.
	APIKey string `json:"apiKey,omitempty"`

	// Model name to use for embeddings.
	// Examples:
	//   - Ollama: "nomic-embed-text", "mxbai-embed-large"
	//   - OpenAI: "text-embedding-3-small", "text-embedding-3-large"
	//   - OpenRouter: "openai/text-embedding-3-small"
	Model string `json:"model"`

	// Dimension of the embedding vectors.
	// Must match the model's output dimension.
	// Common values: 384 (MiniLM), 768 (nomic-embed-text), 1536 (OpenAI small), 3072 (OpenAI large)
	Dimension int `json:"dimension"`

	// NormalizeVectors determines if vectors should be L2-normalized after API response.
	// Set to false if the API already returns normalized vectors (e.g., OpenAI).
	// Set to true for providers that return unnormalized vectors (e.g., some Ollama models).
	NormalizeVectors bool `json:"normalizeVectors"`

	// Timeout for API requests. Default: 30s
	Timeout time.Duration `json:"timeout"`

	// RateLimit configuration for the embedding API.
	RateLimit RateLimitConfig `json:"rateLimit"`

	// Retry configuration for failed requests.
	Retry RetryConfig `json:"retry"`

	// Headers allows adding custom HTTP headers to requests.
	// Useful for authentication or routing (e.g., OpenRouter HTTP-Referer).
	Headers map[string]string `json:"headers,omitempty"`
}

type RateLimitConfig struct {
	// RequestsPerSecond defines the sustained request rate.
	// Default: 10
	RequestsPerSecond float64 `json:"requestsPerSecond"`

	// Burst allows temporary exceeding of the rate limit.
	// Default: 20
	Burst int `json:"burst"`
}

type RetryConfig struct {
	// MaxRetries is the maximum number of retry attempts.
	// Default: 3
	MaxRetries int `json:"maxRetries"`

	// InitialBackoff is the initial backoff duration.
	// Default: 1s
	InitialBackoff time.Duration `json:"initialBackoff"`

	// MaxBackoff is the maximum backoff duration.
	// Default: 30s
	MaxBackoff time.Duration `json:"maxBackoff"`
}

type Script string

type SearchResult struct {
	ID    string  // Entity ID from the sanctions list
	Name  string  // Original name that was indexed
	Score float64 // Cosine similarity score (0.0 to 1.0)
}

type Service interface {
	// Encode converts text to a normalized embedding vector.
	// The returned vector has dimensions matching the configured provider.
	Encode(ctx context.Context, text string) ([]float64, error)

	// EncodeBatch encodes multiple texts efficiently in a single API call.
	EncodeBatch(ctx context.Context, texts []string) ([][]float64, error)

	// BuildIndex creates a searchable index from entity names.
	// This must be called before Search() can be used.
	// ids and names must have the same length.
	BuildIndex(ctx context.Context, names []string, ids []string) error

	// Search finds similar names using vector similarity.
	// Returns up to k results sorted by similarity score (highest first).
	Search(ctx context.Context, query string, k int) ([]SearchResult, error)

	// Similarity computes cosine similarity between two texts.
	// Returns a value between 0.0 (dissimilar) and 1.0 (identical).
	Similarity(ctx context.Context, text1, text2 string) (float64, error)

	// ShouldUseEmbeddings determines if a query should use embeddings vs Jaro-Winkler.
	// When CrossScriptOnly is enabled, returns true only for non-Latin queries.
	ShouldUseEmbeddings(query string) bool

	// IndexSize returns the number of items in the search index.
	IndexSize() int

	// Shutdown releases resources held by the service.
	Shutdown()
}