myAi/Apis/cv-matcher-api/Services/Contracts/ICvMatcherService.cs

using CvMatcher.Models.Requests;
using CvMatcher.Models.Responses;

namespace Api.Services.Contracts;

/// <summary>
/// Orchestrates CV indexing, job matching, and job discovery operations.
/// </summary>
public interface ICvMatcherService
{
    /// <summary>
    /// Indexes a CV PDF into the RAG system and returns document metadata.
    /// Returns cached metadata without re-indexing when the same text hash already exists.
    /// </summary>
    /// <param name="file">Uploaded CV PDF file.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Upload response with document ID, hash, and indexing statistics.</returns>
    Task<CvUploadResponse> UploadCvAsync(IFormFile file, CancellationToken ct);

    /// <summary>
    /// Scores a CV against a specific job posting URL or pasted description using the LLM.
    /// Caches the result so repeat requests for the same (CV, job, language) triple are served instantly.
    /// </summary>
    /// <param name="request">Match request containing CV document ID, job URL or description, and language preference.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Structured match response with score, summary, strengths, gaps, and recommendations.</returns>
    Task<JobMatchResponse> MatchJobAsync(MatchJobRequest request, CancellationToken ct);

    /// <summary>
    /// Searches the RAG index for job documents most similar to the given CV and scores the top candidates.
    /// </summary>
    /// <param name="request">Request containing the CV document ID and optional result count limit.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Response with the CV document ID and a list of ranked match results.</returns>
    Task<FindJobsResponse> FindJobsAsync(FindJobsRequest request, CancellationToken ct);
}