using RealCV.Application.Models;

namespace RealCV.Application.Interfaces;

public interface ICompanyNameMatcherService
{
    /// <summary>
    /// Uses AI to semantically compare a company name from a CV against Companies House candidates.
    /// Returns the best match with confidence score and reasoning.
    /// </summary>
    /// <param name="cvCompanyName">The company name as written on the CV</param>
    /// <param name="candidates">List of potential matches from Companies House</param>
    /// <param name="industryHint">Optional industry context for well-known brands (e.g., "pharmacy/healthcare retail")</param>
    /// <param name="cancellationToken">Cancellation token</param>
    Task<SemanticMatchResult?> FindBestMatchAsync(
        string cvCompanyName,
        List<CompanyCandidate> candidates,
        string? industryHint = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Uses AI to detect if a company name contains multiple companies and extract them.
    /// Returns null or single-item list if it's a single company (e.g., "Ernst & Young").
    /// Returns multiple items if compound (e.g., "ASDA/WALMART" -> ["ASDA", "WALMART"]).
    /// </summary>
    Task<List<string>?> ExtractCompanyNamesAsync(
        string companyName,
        CancellationToken cancellationToken = default);
}
