using Rag.Models.Requests;
using Rag.Models.Responses;

namespace Api.Services.Contracts;

/// <summary>
/// Core RAG (Retrieval-Augmented Generation) operations: document indexing, vector search, and retrieval.
/// </summary>
public interface IRagService
{
    /// <summary>
    /// Indexes a plain-text document by classifying it, chunking the text, generating embeddings,
    /// and persisting the document and its chunks. Returns cached metadata when the text hash already exists.
    /// </summary>
    /// <param name="request">Indexing request with text, optional document type, title, and source URL.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Response with document ID, hash, type, and chunk/character counts.</returns>
    Task<IndexDocumentResponse> IndexTextAsync(IndexDocumentRequest request, CancellationToken ct);

    /// <summary>
    /// Extracts text from a PDF file, then indexes it the same way as <see cref="IndexTextAsync"/>.
    /// Returns cached metadata when the extracted text hash already exists.
    /// </summary>
    /// <param name="file">Uploaded PDF file (must be ≤ configured max size).</param>
    /// <param name="documentType">Optional document type hint; if omitted the classifier is used.</param>
    /// <param name="title">Optional title override; if omitted the title is extracted from the text.</param>
    /// <param name="sourceUrl">Optional source URL to associate with the document.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Response with document ID, hash, type, and chunk/character counts.</returns>
    Task<IndexDocumentResponse> IndexPdfAsync(IFormFile file, string? documentType, string? title, string? sourceUrl, CancellationToken ct);

    /// <summary>
    /// Performs a vector similarity search over indexed document chunks, groups results by document,
    /// and returns the top-K documents with their best-matching chunks.
    /// </summary>
    /// <param name="request">Search request with query text, optional document type filter, and top-K limit.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Ranked list of matching documents with scored chunk excerpts.</returns>
    Task<SearchResponse> SearchAsync(SearchRequest request, CancellationToken ct);

    /// <summary>
    /// Retrieves full document details — including the original text — by document ID.
    /// </summary>
    /// <param name="documentId">The document's unique identifier.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Document details, or <c>null</c> if no document with that ID exists.</returns>
    Task<RagDocumentDetailsResponse?> GetDocumentAsync(string documentId, CancellationToken ct);
}