ChatRAG/Services/Contracts/IVectorSearchService.cs

using ChatRAG.Models;
using Microsoft.Extensions.VectorData;

namespace ChatRAG.Contracts.VectorSearch
{
    /// <summary>
    /// Interface unificada para operações de busca vetorial.
    /// Pode ser implementada por MongoDB, Qdrant, Pinecone, etc.
    /// </summary>
    public interface IVectorSearchService
    {
        // ========================================
        // BUSCA VETORIAL
        // ========================================

        /// <summary>
        /// Busca documentos similares usando embedding vetorial
        /// </summary>
        /// <param name="queryEmbedding">Embedding da query (ex: 1536 dimensões para OpenAI)</param>
        /// <param name="projectId">Filtrar por projeto específico (opcional)</param>
        /// <param name="threshold">Score mínimo de similaridade (0.0 a 1.0)</param>
        /// <param name="limit">Número máximo de resultados</param>
        /// <param name="filters">Filtros adicionais (metadata, data, etc.)</param>
        /// <returns>Lista de documentos ordenados por similaridade</returns>
        Task<List<VectorSearchResult>> SearchSimilarAsync(
            double[] queryEmbedding,
            string? projectId = null,
            double threshold = 0.3,
            int limit = 5,
            Dictionary<string, object>? filters = null);

        /// <summary>
        /// Busca adaptativa - relaxa threshold se não encontrar resultados suficientes
        /// (Implementa a mesma lógica do seu ResponseRAGService atual)
        /// </summary>
        /// <param name="queryEmbedding">Embedding da query</param>
        /// <param name="projectId">ID do projeto</param>
        /// <param name="minThreshold">Threshold inicial (será reduzido se necessário)</param>
        /// <param name="limit">Número máximo de resultados</param>
        /// <returns>Lista de documentos com busca adaptativa</returns>
        Task<List<VectorSearchResult>> SearchSimilarDynamicAsync(
            double[] queryEmbedding,
            string projectId,
            double minThreshold = 0.5,
            int limit = 5);

        // ========================================
        // CRUD DE DOCUMENTOS
        // ========================================

        /// <summary>
        /// Adiciona um novo documento com embedding
        /// </summary>
        /// <param name="title">Título do documento</param>
        /// <param name="content">Conteúdo do documento</param>
        /// <param name="projectId">ID do projeto</param>
        /// <param name="embedding">Embedding pré-calculado</param>
        /// <param name="metadata">Metadados adicionais (tags, data, autor, etc.)</param>
        /// <returns>ID do documento criado</returns>
        Task<string> AddDocumentAsync(
            string title,
            string content,
            string projectId,
            double[] embedding,
            Dictionary<string, object>? metadata = null);

        /// <summary>
        /// Atualiza um documento existente
        /// </summary>
        /// <param name="id">ID do documento</param>
        /// <param name="title">Novo título</param>
        /// <param name="content">Novo conteúdo</param>
        /// <param name="projectId">ID do projeto</param>
        /// <param name="embedding">Novo embedding</param>
        /// <param name="metadata">Novos metadados</param>
        Task UpdateDocumentAsync(
            string id,
            string title,
            string content,
            string projectId,
            double[] embedding,
            Dictionary<string, object>? metadata = null);

        /// <summary>
        /// Remove um documento
        /// </summary>
        /// <param name="id">ID do documento</param>
        Task DeleteDocumentAsync(string id);

        // ========================================
        // CONSULTAS AUXILIARES
        // ========================================

        /// <summary>
        /// Verifica se um documento existe
        /// </summary>
        /// <param name="id">ID do documento</param>
        /// <returns>True se existe, False caso contrário</returns>
        Task<bool> DocumentExistsAsync(string id);

        /// <summary>
        /// Recupera um documento específico por ID
        /// </summary>
        /// <param name="id">ID do documento</param>
        /// <returns>Documento ou null se não encontrado</returns>
        Task<VectorSearchResult?> GetDocumentAsync(string id);

        /// <summary>
        /// Lista todos os documentos de um projeto
        /// </summary>
        /// <param name="projectId">ID do projeto</param>
        /// <returns>Lista de documentos do projeto</returns>
        Task<List<VectorSearchResult>> GetDocumentsByProjectAsync(string projectId);

        /// <summary>
        /// Conta total de documentos
        /// </summary>
        /// <param name="projectId">Filtrar por projeto (opcional)</param>
        /// <returns>Número de documentos</returns>
        Task<int> GetDocumentCountAsync(string? projectId = null);

        // ========================================
        // HEALTH CHECK E MÉTRICAS
        // ========================================

        /// <summary>
        /// Verifica se o serviço está saudável
        /// </summary>
        /// <returns>True se está funcionando, False caso contrário</returns>
        Task<bool> IsHealthyAsync();

        /// <summary>
        /// Retorna estatísticas e métricas do provider
        /// </summary>
        /// <returns>Dicionário com estatísticas (documentos, performance, etc.)</returns>
        Task<Dictionary<string, object>> GetStatsAsync();
    }
}