/**
 * VectorStore interface — abstraction over pgvector that allows future
 * swap to Qdrant, Pinecone, etc.
 */
export interface VectorStore {
  /** Store an embedding with an associated document ID. */
  store(documentId: string, embedding: number[], metadata?: Record<string, unknown>): Promise<void>;

  /** Search for similar embeddings, returning document IDs and distances. */
  search(
    queryEmbedding: number[],
    limit?: number,
    filter?: Record<string, unknown>,
  ): Promise<VectorSearchResult[]>;

  /** Delete an embedding by document ID. */
  remove(documentId: string): Promise<void>;
}

export interface VectorSearchResult {
  documentId: string;
  distance: number;
  metadata?: Record<string, unknown>;
}

/**
 * EmbeddingProvider interface — generates embeddings from text.
 * Implemented by the gateway using the configured LLM provider.
 */
export interface EmbeddingProvider {
  /** Generate an embedding vector for the given text. */
  embed(text: string): Promise<number[]>;

  /** Generate embeddings for multiple texts in batch. */
  embedBatch(texts: string[]): Promise<number[][]>;

  /** The dimensionality of the embeddings this provider generates. */
  dimensions: number;
}