// The embedding-engine interface: hides the platform-specific sentence-embedding
// backend (transformers.js feature-extraction on web; a follow-up native impl)
// behind one contract, mirroring TranscriptionEngine. Used for on-device
// semantic search (ROADMAP Phase 1) — vectors never leave the device.

export interface EmbeddingEngine {
  readonly platform: 'web' | 'native';
  /** Vector dimensionality (must match EMBED_DIM). */
  readonly dim: number;

  /** Synchronous check: is the model loaded in memory? */
  isLoaded(): boolean;

  /** Ensure the model is loaded. `onProgress` (0..1) fires during download. */
  loadModel(onProgress?: (p: number) => void): Promise<void>;

  /**
   * Embed texts into unit-normalized, mean-pooled vectors. `kind` adds the
   * asymmetric prefix the model expects (e5: "query:" for search text,
   * "passage:" for stored segments) so retrieval is well-calibrated.
   */
  embed(texts: string[], kind: 'query' | 'passage'): Promise<Float32Array[]>;
}

/** Embedding model id — also stored alongside vectors to detect model changes. */
export const EMBED_MODEL = 'Xenova/multilingual-e5-small';
/** Output dimensionality of EMBED_MODEL. */
export const EMBED_DIM = 384;
