using Rag.Models;

namespace Api.Services.Contracts;

/// <summary>
/// Classifies a document into a known type (cv, job, contract, etc.) and extracts a title.
/// </summary>
public interface IDocumentClassifier
{
    /// <summary>
    /// Determines the document type and title from the provided text.
    /// Uses <paramref name="providedType"/> and <paramref name="providedTitle"/> directly when supplied;
    /// otherwise falls back to a keyword-frequency heuristic over the text.
    /// </summary>
    /// <param name="text">Full document text to classify.</param>
    /// <param name="providedType">Caller-supplied document type hint; skips heuristic when non-empty.</param>
    /// <param name="providedTitle">Caller-supplied document title; skips title extraction when non-empty.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A <see cref="DocumentClassification"/> with type, confidence score, and title.</returns>
    Task<DocumentClassification> ClassifyAsync(string text, string? providedType, string? providedTitle, CancellationToken ct);
}