[fel] implement memory for recent N histories

Author: loveTsong

framework/fel/java/fel-core/src/main/java/modelengine/fel/core/memory/support/RecentMemory.java

@@ -0,0 +1,96 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) 2025 Huawei Technologies Co., Ltd. All rights reserved.
+ *  This file is a part of the ModelEngine Project.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+package modelengine.fel.core.memory.support;
+
+import modelengine.fel.core.chat.ChatMessage;
+import modelengine.fel.core.memory.Memory;
+import modelengine.fel.core.template.BulkStringTemplate;
+import modelengine.fel.core.template.support.DefaultBulkStringTemplate;
+import modelengine.fitframework.inspection.Validation;
+import modelengine.fitframework.util.MapBuilder;
+
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.LinkedBlockingQueue;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+import static modelengine.fitframework.inspection.Validation.notNull;
+
+/**
+ * 表示使用最近一定次数历史记录的实现。
+ *
+ * @author 宋永坦
+ * @since 2025-07-04
+ */
+public class RecentMemory implements Memory {
+    private final LinkedBlockingQueue<ChatMessage> records;
+    private final BulkStringTemplate bulkTemplate;
+    private final Function<ChatMessage, Map<String, String>> extractor;
+
+    /**
+     * 指定最大保留历史记录数量的构造方法。
+     *
+     * @param maxCount 表示最大保留历史记录数量的 {@code int}。
+     * @throws IllegalArgumentException 当 {@code maxCount < 0} 时。
+     */
+    public RecentMemory(int maxCount) {
+        this(maxCount,
+                new DefaultBulkStringTemplate("{{type}}:{{text}}", "\n"),
+                message -> MapBuilder.<String, String>get()
+                        .put("type", message.type().getRole())
+                        .put("text", message.text())
+                        .build());
+    }
+
+    /**
+     * 指定最大保留历史记录数量、渲染模板、抽取方法的构造方法。
+     *
+     * @param maxCount 表示最大保留历史记录数量的 {@code int}。
+     * @param bulkTemplate 表示批量字符串模板的 {@link BulkStringTemplate}。
+     * @param extractor 表示将 {@link ChatMessage} 转换成
+     * {@link Map}{@code <}{@link String}, {@link String}{@code >} 的处理函数。
+     * @throws IllegalArgumentException 当 {@code maxCount < 0}、{@code bulkTemplate}、{@code extractor} 为 {@code null} 时。
+     */
+    public RecentMemory(int maxCount, BulkStringTemplate bulkTemplate,
+            Function<ChatMessage, Map<String, String>> extractor) {
+        Validation.greaterThanOrEquals(maxCount, 0, "The max count should >= 0.");
+        this.records = new LinkedBlockingQueue<>(maxCount);
+        this.bulkTemplate = notNull(bulkTemplate, "The bulkTemplate cannot be null.");
+        this.extractor = notNull(extractor, "The extractor cannot be null.");
+    }
+
+    @Override
+    public void add(ChatMessage message) {
+        if (!this.records.offer(message)) {
+            this.records.poll();
+            this.records.offer(message);
+        }
+    }
+
+    @Override
+    public void set(List<ChatMessage> messages) {
+        messages.forEach(this::add);
+    }
+
+    @Override
+    public void clear() {
+        this.records.clear();
+    }
+
+    @Override
+    public List<ChatMessage> messages() {
+        return this.records.stream().toList();
+    }
+
+    @Override
+    public String text() {
+        return this.records.stream()
+                .map(this.extractor)
+                .collect(Collectors.collectingAndThen(Collectors.toList(), this.bulkTemplate::render));
+    }
+}

framework/fel/java/fel-core/src/test/java/modelengine/fel/core/memory/support/RecentMemoryTest.java

@@ -0,0 +1,62 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) 2025 Huawei Technologies Co., Ltd. All rights reserved.
+ *  This file is a part of the ModelEngine Project.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+package modelengine.fel.core.memory.support;
+
+import modelengine.fel.core.chat.ChatMessage;
+import modelengine.fel.core.chat.support.AiMessage;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 表示 {@link RecentMemory} 的测试。
+ *
+ * @author 宋永坦
+ * @since 2025-07-04
+ */
+class RecentMemoryTest {
+    private final List<ChatMessage> inputChatMessages =
+            Arrays.asList(new AiMessage("1"), new AiMessage("2"), new AiMessage("3"));
+
+    @Test
+    void shouldKeepAllMessagesWhenAddGivenLessMessage() {
+        RecentMemory recentMemory = new RecentMemory(4);
+        this.inputChatMessages.forEach(recentMemory::add);
+        List<ChatMessage> messages = recentMemory.messages();
+
+        assertEquals(inputChatMessages.size(), messages.size());
+        for (int i = 0; i < inputChatMessages.size(); ++i) {
+            assertEquals(inputChatMessages.get(i).text(), messages.get(i).text());
+        }
+    }
+
+    @Test
+    void shouldKeepMaxCountMessagesWhenAddGivenOverMaxCountMessages() {
+        RecentMemory recentMemory = new RecentMemory(2);
+        this.inputChatMessages.forEach(recentMemory::add);
+        List<ChatMessage> messages = recentMemory.messages();
+
+        assertEquals(2, messages.size());
+        assertEquals(inputChatMessages.get(1).text(), messages.get(0).text());
+        assertEquals(inputChatMessages.get(2).text(), messages.get(1).text());
+    }
+
+    @Test
+    void shouldKeepMaxCountMessagesWhenSetGivenOverMaxCountMessages() {
+        RecentMemory recentMemory = new RecentMemory(2);
+        recentMemory.set(this.inputChatMessages);
+        List<ChatMessage> messages = recentMemory.messages();
+
+        assertEquals(2, messages.size());
+        assertEquals(inputChatMessages.get(1).text(), messages.get(0).text());
+        assertEquals(inputChatMessages.get(2).text(), messages.get(1).text());
+    }
+}