namespace WebClientTpos.Server.AiChat;

/// <summary>
/// EN: Provider interface for AI chat completions. Each LLM vendor implements this.
/// VI: Interface provider cho AI chat completions. Moi LLM vendor implement interface nay.
/// </summary>
public interface IAiChatProvider
{
    /// <summary>
    /// EN: Send a chat request to the AI provider and return the response.
    /// VI: Gui chat request den AI provider va tra ve response.
    /// </summary>
    Task<AiChatResponse> SendAsync(AiChatRequest request, CancellationToken cancellationToken = default);
}

// ═══════════════════════════════════════════════════════════════════════════════
// EN: Shared DTOs for AI chat communication
// VI: Cac DTO dung chung cho giao tiep AI chat
// ═══════════════════════════════════════════════════════════════════════════════

/// <summary>
/// EN: Request payload sent to an AI chat provider.
/// VI: Payload request gui den AI chat provider.
/// </summary>
/// <param name="Model">EN: Model identifier (e.g. gpt-4o, claude-sonnet-4-20250514). VI: Dinh danh model.</param>
/// <param name="ApiKey">EN: API key for authentication. VI: API key de xac thuc.</param>
/// <param name="BaseUrl">EN: Base URL of the provider API. VI: Base URL cua provider API.</param>
/// <param name="Messages">EN: Conversation messages. VI: Cac tin nhan hoi thoai.</param>
/// <param name="SystemPrompt">EN: Optional system prompt. VI: System prompt tuy chon.</param>
/// <param name="Tools">EN: Optional tool definitions for function calling. VI: Cac dinh nghia tool cho function calling.</param>
public record AiChatRequest(
    string Model,
    string ApiKey,
    string BaseUrl,
    List<AiChatMessage> Messages,
    string? SystemPrompt = null,
    List<AiToolDefinition>? Tools = null);

/// <summary>
/// EN: A single message in the AI chat conversation.
/// VI: Mot tin nhan trong cuoc hoi thoai AI chat.
/// </summary>
/// <param name="Role">EN: Message role (system, user, assistant, tool). VI: Vai tro tin nhan.</param>
/// <param name="Content">EN: Text content of the message. VI: Noi dung van ban cua tin nhan.</param>
/// <param name="ToolCalls">EN: Tool calls requested by the assistant. VI: Cac tool call do assistant yeu cau.</param>
/// <param name="ToolCallId">EN: ID of the tool call this message responds to. VI: ID cua tool call ma tin nhan nay tra loi.</param>
/// <param name="Name">EN: Optional name for tool result messages. VI: Ten tuy chon cho tin nhan ket qua tool.</param>
public record AiChatMessage(
    string Role,
    string Content,
    List<AiToolCall>? ToolCalls = null,
    string? ToolCallId = null,
    string? Name = null);

/// <summary>
/// EN: A tool/function call requested by the AI model.
/// VI: Mot tool/function call do AI model yeu cau.
/// </summary>
/// <param name="Id">EN: Unique identifier of the tool call. VI: Dinh danh duy nhat cua tool call.</param>
/// <param name="Name">EN: Name of the tool to invoke. VI: Ten cua tool can goi.</param>
/// <param name="ArgumentsJson">EN: JSON string of the tool arguments. VI: Chuoi JSON cua cac tham so tool.</param>
public record AiToolCall(string Id, string Name, string ArgumentsJson);

/// <summary>
/// EN: Definition of a tool that the AI model can call.
/// VI: Dinh nghia mot tool ma AI model co the goi.
/// </summary>
/// <param name="Name">EN: Tool name. VI: Ten tool.</param>
/// <param name="Description">EN: Human-readable description. VI: Mo ta de doc.</param>
/// <param name="Parameters">EN: JSON Schema object describing the parameters. VI: JSON Schema object mo ta cac tham so.</param>
public record AiToolDefinition(string Name, string Description, object Parameters);

/// <summary>
/// EN: Response from an AI chat provider.
/// VI: Response tu AI chat provider.
/// </summary>
/// <param name="Content">EN: Text content of the response. VI: Noi dung van ban cua response.</param>
/// <param name="ToolCalls">EN: Tool calls the model wants to execute. VI: Cac tool call ma model muon thuc thi.</param>
/// <param name="RequiresToolExecution">EN: Whether tool calls need to be executed before responding. VI: Co can thuc thi tool truoc khi tra loi khong.</param>
public record AiChatResponse(
    string Content,
    List<AiToolCall>? ToolCalls,
    bool RequiresToolExecution);
