embedding

type BM25Config struct {
	// Dimensions is the output embedding dimension (default: 384 for compatibility)
	Dimensions int

	// K1 controls term frequency saturation (default: 1.5)
	// Higher values give more weight to term frequency
	K1 float64

	// B controls length normalization (default: 0.75)
	// B=1.0 means full normalization, B=0.0 means no normalization
	B float64
}

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

type Cache interface {
	// Get retrieves a cached embedding for the given content hash.
	//
	// Returns an error if the embedding is not found in the cache.
	Get(ctx context.Context, contentHash string) ([]float32, error)

	// Put stores an embedding in the cache with the given content hash.
	//
	// The cache should be content-addressed using a cryptographic hash
	// (e.g., SHA-256) of the text content.
	Put(ctx context.Context, contentHash string, embedding []float32) error
}

type DedupRecord struct {
	Vector         []float32 `json:"vector"`
	EntityIDs      []string  `json:"entity_ids"` // Entities sharing this content
	FirstGenerated time.Time `json:"first_generated"`
}

type Embedder interface {
	// Generate creates embeddings for the given texts (the DOCUMENT side — what is
	// embedded at ingest).
	//
	// This is the primary method - batch operations are natural for all providers.
	// For single text, pass a slice with one element.
	// Returns a slice of float32 slices, where each inner slice is an embedding vector.
	Generate(ctx context.Context, texts []string) ([][]float32, error)

	// GenerateQuery creates embeddings for QUERY-side text (semantic search),
	// as opposed to Generate which embeds documents at ingest. Asymmetric retrieval
	// models (Snowflake arctic-embed, BGE, E5) are trained to embed a query with an
	// instruction prefix while documents are embedded raw; omitting the query prefix
	// is a measured retrieval-quality cliff, not a rounding error (gh#438). Symmetric
	// embedders (BM25) implement this identically to Generate.
	GenerateQuery(ctx context.Context, texts []string) ([][]float32, error)

	// Dimensions returns the dimensionality of embeddings produced by this embedder.
	//
	// For example, all-MiniLM-L6-v2 produces 384-dimensional vectors.
	Dimensions() int

	// Model returns the model identifier used by this embedder.
	//
	// This is useful for debugging and logging which model is being used.
	Model() string

	// Close releases any resources held by the embedder.
	//
	// Must be called when the embedder is no longer needed. For HTTP providers
	// this is typically a no-op, but for local ONNX models this releases GPU/CPU resources.
	Close() error
}

type GeneratedCallback func(entityID string, embedding []float32)

type HTTPConfig struct {
	// BaseURL is the base URL of the embedding service.
	// Examples:
	//   - "http://localhost:8082" (TEI - Hugging Face Text Embeddings Inference)
	//   - "http://tei:8082" (TEI container by name)
	//   - "http://localhost:8080" (LocalAI)
	//   - "https://api.openai.com/v1" (OpenAI cloud)
	BaseURL string

	// Model is the embedding model to use.
	// Examples:
	//   - "all-MiniLM-L6-v2" (TEI default - 384 dims, fast)
	//   - "all-mpnet-base-v2" (TEI - 768 dims, higher quality)
	//   - "text-embedding-ada-002" (OpenAI)
	Model string

	// APIKey for authentication (optional for local services).
	// Required for OpenAI, optional for TEI/LocalAI.
	APIKey string

	// QueryPrefix is prepended to query-side text only (GenerateQuery), never to
	// documents. Set it to the model's query instruction for asymmetric retrieval
	// models — e.g. "Represent this sentence for searching relevant passages: " for
	// Snowflake arctic-embed / E5 (gh#438). Empty disables the prefix (symmetric use).
	QueryPrefix string

	// Timeout for HTTP requests (default: 30s).
	Timeout time.Duration

	// Cache for embedding results (optional but recommended).
	Cache Cache

	// Logger for error logging (optional, defaults to slog.Default()).
	Logger *slog.Logger

	// IdleConnTimeout, ResponseHeaderTimeout, and DisableKeepAlives
	// mirror the same fields on model.EndpointConfig and graph/llm's
	// OpenAIConfig — operator overrides for connection-hygiene
	// behaviour. Empty/false selects the framework default (see
	// model.NewHTTPClient).
	IdleConnTimeout       string
	ResponseHeaderTimeout string
	DisableKeepAlives     bool
}

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

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

type Record struct {
	EntityID    string    `json:"entity_id"`
	Vector      []float32 `json:"vector,omitempty"`
	ContentHash string    `json:"content_hash"`
	SourceText  string    `json:"source_text,omitempty"` // Stored for pending records (legacy)
	Model       string    `json:"model,omitempty"`
	Dimensions  int       `json:"dimensions,omitempty"`
	GeneratedAt time.Time `json:"generated_at,omitempty"`
	Status      Status    `json:"status"`
	ErrorMsg    string    `json:"error_msg,omitempty"` // If status=failed

	// SourceRevision is the ENTITY_STATES stream revision that produced this pending
	// record. It is threaded from the hop-1 watcher so hop-2 can complete the
	// embedding readiness watermark at the terminal transition (ADR-066 §3). Only
	// meaningful on pending records; SaveGenerated/SaveFailed rebuild the record and
	// drop it (those records only ever hit hop-2's not-pending skip). 0 means
	// "unknown" (a legacy record written before this field existed) — the watermark
	// completion treats 0 as a no-op.
	SourceRevision uint64 `json:"source_revision,omitempty"`

	// ContentStorable support (Feature 008)
	// When StorageRef is set, Worker fetches content from ObjectStore
	// and uses ContentFields to extract text for embedding.
	StorageRef    *StorageRef       `json:"storage_ref,omitempty"`
	ContentFields map[string]string `json:"content_fields,omitempty"` // Role → field name
}

type ScoredEntity struct {
	EntityID   string
	Similarity float64
}

type Status string

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

type StorageRef struct {
	StorageInstance string `json:"storage_instance"`
	Key             string `json:"key"`
}

type StoreResolver interface {
	Streamable(instance string) (storage.StreamableStore, bool)
}

type TerminalCallback func(entityID string, sourceRevision uint64)

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

type WorkerMetrics interface {
	// IncDedupHits increments the deduplication hits counter
	IncDedupHits()
	// IncFailed increments the failed embeddings counter
	IncFailed()
	// SetPending sets the current pending embeddings gauge
	SetPending(count float64)
	// IncContentResolveError counts a body fetch that FAILED after a store was
	// resolved (an infra fault: read error, deleted bucket) — distinct from the
	// component-side content_unresolved (no store wired at all). Preserves the
	// gh#414 diagnosability the ADR-063 resolver would otherwise blur (M1).
	IncContentResolveError()
	// IncContentResolved counts a body successfully fetched from a resolved store.
	// This is the POSITIVE observable for the ADR-063 H2 behavior change: offloaded
	// bodies that configs without a store-read port previously excluded now embed —
	// a rising value is that inclusion happening, not merely content_unresolved
	// falling (the cost-ledger "make the delta observable" discipline).
	IncContentResolved()
}