001/*
002 * Copyright (c) 2023-2026, Agents-Flex (fuhai999@gmail.com).
003 * <p>
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 * <p>
008 * http://www.apache.org/licenses/LICENSE-2.0
009 * <p>
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package com.agentsflex.core.model.client;
017
018import com.agentsflex.core.message.Message;
019import com.agentsflex.core.model.chat.ChatConfig;
020import com.agentsflex.core.model.chat.tool.Tool;
021import com.agentsflex.core.prompt.Prompt;
022
023import java.util.List;
024import java.util.Map;
025
026/**
027 * 将内部消息模型序列化为大模型（如 OpenAI）可识别的请求格式。
028 * 虽然名为 ChatMessageSerializer，但同时也支持序列化工具/函数定义，
029 * 因为这些通常是聊天请求的一部分（如 tools 或 functions 字段）。
030 */
031public interface ChatMessageSerializer {
032
033    /**
034     * 将消息列表序列化为模型所需的聊天消息数组格式。
035     * 例如 OpenAI 的 [{"role": "user", "content": "..."}, ...]
036     *
037     * @param messages 消息列表，不可为 null
038     * @return 序列化后的消息数组，若输入为空则返回空列表
039     */
040    List<Map<String, Object>> serializeMessages(List<Message> messages, ChatConfig config);
041
042    /**
043     * 将函数定义列表序列化为模型所需的工具（tools）或函数（functions）格式。
044     * 例如 OpenAI 的 [{"type": "function", "function": {...}}, ...]
045     *
046     * @param tools 函数定义列表，可能为 null 或空
047     * @return 序列化后的函数定义数组，若输入为空则返回空列表
048     */
049    List<Map<String, Object>> serializeTools(List<Tool> tools, ChatConfig config);
050
051    default List<Map<String, Object>> serializeTools(Prompt prompt, ChatConfig config) {
052        return serializeTools(prompt == null ? null : prompt.getTools(), config);
053    }
054}