OA2023/OASystem/OASystem.Api/OAMethodLib/TokenHubAI/Models/ChatRequest.cs

namespace OASystem.API.OAMethodLib.TokenHubAI.Models;

/// <summary>
/// TokenHub AI 聊天请求参数
/// </summary>
/// <remarks>
/// 用于配置发送到 TokenHub API 的聊天请求，支持所有 OpenAI 兼容参数
/// </remarks>
public class ChatRequest
{
    // ============ 基础参数 ============

    /// <summary>
    /// 模型名称
    /// </summary>
    /// <remarks>
    /// 可用模型：
    /// - 混元系列：Hy3 preview 
    /// - 智谱系列：glm-5.1, glm-5.1-s
    /// - DeepSeek：deepseek-v3, deepseek-r1
    /// - MiniMax：minimax-m2.7, minimax-m2.7-s
    /// - 通义千问：qwen-2.5-72b, qwen-2.5-32b
    /// </remarks>
    public string Model { get; set; } = "Hy3 preview ";

    /// <summary>
    /// 消息列表
    /// </summary>
    public List<ChatMessage> Messages { get; set; } = new();

    // ============ 生成控制参数 ============

    /// <summary>
    /// 最大输出 Token 数
    /// </summary>
    /// <remarks>
    /// 范围：1-8192，默认 1024
    /// 控制响应长度，影响费用
    /// </remarks>
    public int MaxTokens { get; set; } = 2048;

    /// <summary>
    /// 温度参数，控制随机性
    /// </summary>
    /// <remarks>
    /// 范围：0.0-2.0，默认 0.7
    /// - 0.0-0.3：确定性输出（代码生成、事实问答）
    /// - 0.4-0.6：平衡模式（通用对话）
    /// - 0.7-1.0：创造性（创意写作）
    /// - 1.0-2.0：高随机性（头脑风暴）
    /// </remarks>
    public double Temperature { get; set; } = 0.7;

    /// <summary>
    /// Top-P 核采样
    /// </summary>
    /// <remarks>
    /// 范围：0.0-1.0，默认 null
    /// 控制词汇选择多样性，值越小越集中
    /// 建议与 Temperature 二选一
    /// </remarks>
    public double? TopP { get; set; }

    /// <summary>
    /// 频率惩罚
    /// </summary>
    /// <remarks>
    /// 范围：-2.0 到 2.0，默认 null
    /// 正值：减少重复，负值：鼓励重复
    /// 推荐：0.0-0.5
    /// </remarks>
    public double? FrequencyPenalty { get; set; }

    /// <summary>
    /// 存在惩罚
    /// </summary>
    /// <remarks>
    /// 范围：-2.0 到 2.0，默认 null
    /// 正值：鼓励新话题，负值：保持当前话题
    /// 推荐：0.0-0.3
    /// </remarks>
    public double? PresencePenalty { get; set; }

    /// <summary>
    /// 停止词列表
    /// </summary>
    /// <remarks>
    /// 遇到停止词时停止生成
    /// 示例：["\n\n", "###", "END"]
    /// </remarks>
    public List<string>? Stop { get; set; }

    /// <summary>
    /// 种子值，用于确定性输出
    /// </summary>
    /// <remarks>
    /// 相同种子 + 相同参数 = 相同结果
    /// 用于可复现场景
    /// </remarks>
    public int? Seed { get; set; }

    // ============ 高级参数 ============

    /// <summary>
    /// 是否启用流式响应
    /// </summary>
    /// <remarks>
    /// true：逐字输出（实时对话）
    /// false：完整响应（批处理）
    /// </remarks>
    public bool Stream { get; set; } = false;

    /// <summary>
    /// 系统提示词（快捷设置）
    /// </summary>
    /// <remarks>
    /// 设定 AI 的角色和行为
    /// 会在 Messages 中添加 system 消息
    /// </remarks>
    public string? SystemPrompt { get; set; }

    /// <summary>
    /// 响应格式
    /// </summary>
    /// <remarks>
    /// - 默认：text
    /// - json_object：强制 JSON 输出（部分模型支持）
    /// </remarks>
    public object? ResponseFormat { get; set; }

    /// <summary>
    /// 用户标识
    /// </summary>
    /// <remarks>
    /// 用于监控和跟踪
    /// </remarks>
    public string? User { get; set; }

    // ============ Function Calling 参数 ============

    /// <summary>
    /// 工具列表（Function Calling）
    /// </summary>
    public List<Tool>? Tools { get; set; }

    /// <summary>
    /// 工具选择模式
    /// </summary>
    /// <remarks>
    /// - none：不调用工具
    /// - auto：自动决定
    /// - required：必须调用
    /// - 或指定工具名称
    /// </remarks>
    public object? ToolChoice { get; set; }

    // ============ 调试参数 ============

    /// <summary>
    /// 是否返回日志概率
    /// </summary>
    public int? LogProbs { get; set; }

    /// <summary>
    /// 是否回显
    /// </summary>
    public bool? Echo { get; set; }

    // ============ 工厂方法 ============

    /// <summary>
    /// 从用户消息创建请求
    /// </summary>
    public static ChatRequest FromUserMessage(string userMessage, string? model = null)
    {
        return new ChatRequest
        {
            Model = model ?? "hunyuan-2.0-instruct-20251111",
            Messages = new List<ChatMessage>
            {
                ChatMessage.User(userMessage)
            }
        };
    }

    /// <summary>
    /// 从系统提示和用户消息创建请求
    /// </summary>
    public static ChatRequest FromSystemAndUser(string systemPrompt, string userMessage, string? model = null)
    {
        return new ChatRequest
        {
            Model = model ?? "hunyuan-2.0-instruct-20251111",
            SystemPrompt = systemPrompt,
            Messages = new List<ChatMessage>
            {
                ChatMessage.System(systemPrompt),
                ChatMessage.User(userMessage)
            }
        };
    }

    /// <summary>
    /// 从对话历史创建请求
    /// </summary>
    public static ChatRequest FromHistory(List<ChatMessage> messages, string? model = null)
    {
        return new ChatRequest
        {
            Model = model ?? "hunyuan-2.0-instruct-20251111",
            Messages = messages
        };
    }

    /// <summary>
    /// 设置系统提示
    /// </summary>
    public ChatRequest WithSystemPrompt(string systemPrompt)
    {
        SystemPrompt = systemPrompt;
        // 如果 Messages 中还没有 system 消息，添加一个
        if (!Messages.Any(m => m.Role == "system"))
        {
            Messages.Insert(0, ChatMessage.System(systemPrompt));
        }
        return this;
    }

    /// <summary>
    /// 添加用户消息
    /// </summary>
    public ChatRequest AddUserMessage(string content)
    {
        Messages.Add(ChatMessage.User(content));
        return this;
    }

    /// <summary>
    /// 添加助手消息
    /// </summary>
    public ChatRequest AddAssistantMessage(string content)
    {
        Messages.Add(ChatMessage.Assistant(content));
        return this;
    }

    /// <summary>
    /// 设置温度
    /// </summary>
    public ChatRequest WithTemperature(double temperature)
    {
        Temperature = temperature;
        return this;
    }

    /// <summary>
    /// 设置最大 Token 数
    /// </summary>
    public ChatRequest WithMaxTokens(int maxTokens)
    {
        MaxTokens = maxTokens;
        return this;
    }

    /// <summary>
    /// 开启流式
    /// </summary>
    public ChatRequest WithStream(bool stream = true)
    {
        Stream = stream;
        return this;
    }
}