namespace MktXService.Infrastructure.ExternalServices.OpenAI;

/// <summary>
/// EN: Interface for AI/LLM service client operations.
/// VI: Interface cho các thao tác client dịch vụ AI/LLM.
/// </summary>
/// <remarks>
/// EN: Abstracts OpenAI API for chat completions and embeddings.
/// VI: Trừu tượng hóa OpenAI API cho chat completions và embeddings.
/// </remarks>
public interface IAIServiceClient
{
    #region Chat Completions

    /// <summary>
    /// EN: Generate a chat completion response.
    /// VI: Tạo phản hồi chat completion.
    /// </summary>
    Task<ChatCompletionResult> GenerateChatResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatCompletionOptions? options = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Generate a chat completion with function calling.
    /// VI: Tạo chat completion với function calling.
    /// </summary>
    Task<ChatCompletionResult> GenerateChatWithFunctionsAsync(
        IEnumerable<ChatMessage> messages,
        IEnumerable<FunctionDefinition> functions,
        ChatCompletionOptions? options = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Stream chat completion response.
    /// VI: Stream phản hồi chat completion.
    /// </summary>
    IAsyncEnumerable<string> StreamChatResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatCompletionOptions? options = null,
        CancellationToken cancellationToken = default);

    #endregion

    #region Intent Detection

    /// <summary>
    /// EN: Detect intent from user message.
    /// VI: Phát hiện ý định từ tin nhắn người dùng.
    /// </summary>
    Task<IntentDetectionResult> DetectIntentAsync(
        string message,
        IEnumerable<string> possibleIntents,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Extract entities/slots from user message.
    /// VI: Trích xuất entities/slots từ tin nhắn người dùng.
    /// </summary>
    Task<Dictionary<string, object>> ExtractEntitiesAsync(
        string message,
        IEnumerable<EntityDefinition> entityDefinitions,
        CancellationToken cancellationToken = default);

    #endregion

    #region Embeddings

    /// <summary>
    /// EN: Generate embeddings for text.
    /// VI: Tạo embeddings cho văn bản.
    /// </summary>
    Task<float[]> GenerateEmbeddingAsync(
        string text,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Generate embeddings for multiple texts.
    /// VI: Tạo embeddings cho nhiều văn bản.
    /// </summary>
    Task<IEnumerable<float[]>> GenerateEmbeddingsAsync(
        IEnumerable<string> texts,
        CancellationToken cancellationToken = default);

    #endregion

    #region Moderation

    /// <summary>
    /// EN: Check if content violates usage policies.
    /// VI: Kiểm tra xem nội dung có vi phạm chính sách sử dụng không.
    /// </summary>
    Task<ModerationResult> ModerateContentAsync(
        string content,
        CancellationToken cancellationToken = default);

    #endregion
}

#region DTOs

/// <summary>
/// EN: Chat message for conversation context.
/// VI: Tin nhắn chat cho ngữ cảnh hội thoại.
/// </summary>
public record ChatMessage(
    string Role,      // "system", "user", "assistant", "function"
    string Content,
    string? Name = null,
    string? FunctionCall = null);

/// <summary>
/// EN: Options for chat completion.
/// VI: Tùy chọn cho chat completion.
/// </summary>
public record ChatCompletionOptions(
    string Model = "gpt-4o-mini",
    double Temperature = 0.7,
    int MaxTokens = 1000,
    double TopP = 1.0,
    double FrequencyPenalty = 0,
    double PresencePenalty = 0,
    string? SystemPrompt = null);

/// <summary>
/// EN: Result of chat completion.
/// VI: Kết quả của chat completion.
/// </summary>
public record ChatCompletionResult(
    bool Success,
    string? Content,
    string? FunctionName,
    string? FunctionArguments,
    string? Error,
    int TokensUsed,
    string? FinishReason);

/// <summary>
/// EN: Function definition for function calling.
/// VI: Định nghĩa function cho function calling.
/// </summary>
public record FunctionDefinition(
    string Name,
    string Description,
    Dictionary<string, object> Parameters);

/// <summary>
/// EN: Entity definition for extraction.
/// VI: Định nghĩa entity để trích xuất.
/// </summary>
public record EntityDefinition(
    string Name,
    string Type,
    string Description,
    bool Required = false);

/// <summary>
/// EN: Result of intent detection.
/// VI: Kết quả phát hiện ý định.
/// </summary>
public record IntentDetectionResult(
    string Intent,
    double Confidence,
    Dictionary<string, object>? ExtractedEntities = null);

/// <summary>
/// EN: Result of content moderation.
/// VI: Kết quả kiểm duyệt nội dung.
/// </summary>
public record ModerationResult(
    bool Flagged,
    Dictionary<string, bool> Categories,
    Dictionary<string, double> CategoryScores);

#endregion
