using ROLAC.API.DTOs.Expense;

namespace ROLAC.API.Services.Ai;

/// <summary>
/// AI assistance for defining an expense category (大項/小項): refine the Chinese name, translate it
/// to English, and suggest the matching IRS Form 990 Part IX line.
/// </summary>
public interface IExpenseCategoryAiService
{
    /// <summary>
    /// Refine the entered name, translate it to concise accounting English, and choose the best Form 990
    /// line from the live catalog (biased by the group/sub context in <paramref name="request"/>).
    /// Never throws on an upstream/AI failure — returns a suggestion with null fields instead.
    /// </summary>
    Task<CategoryAiSuggestion> SuggestAsync(ExpenseCategoryAiRequest request, CancellationToken ct = default);
}