create-entity-app-server 0.0.3

package/src/app/plugins/llm/cache.ts

@@ -0,0 +1,138 @@
+/**
+ * LLM 응답 캐시 — 키 생성 + 인메모리 TTL 스토어 + 통계
+ */
+
+import { createHash } from "crypto";
+import type { Message } from "./types/index.ts";
+
+// ─── Cache Key ───────────────────────────────────────────────────────────────
+
+export interface CacheKeyInput {
+    provider: string;
+    model: string;
+    messages: Message[];
+    system?: string;
+    temperature?: number;
+    maxTokens?: number;
+    jsonMode?: boolean;
+}
+
+/**
+ * SHA-256 기반 캐시 키를 생성합니다.
+ * 동일한 요청은 항상 동일한 키를 반환합니다.
+ */
+export function generateCacheKey(input: CacheKeyInput): string {
+    const data = JSON.stringify({
+        p: input.provider,
+        m: input.model,
+        ms: input.messages,
+        s: input.system,
+        t: input.temperature,
+        mt: input.maxTokens,
+        j: input.jsonMode,
+    });
+    const hash = createHash("sha256").update(data).digest("hex");
+    return `llm:resp:${hash}`;
+}
+
+// ─── Cache Stats ─────────────────────────────────────────────────────────────
+
+export class CacheStats {
+    hits = 0;
+    misses = 0;
+
+    /** 캐시 히트를 기록한다 */
+    recordHit(): void {
+        this.hits++;
+    }
+
+    /** 캐시 미스를 기록한다 */
+    recordMiss(): void {
+        this.misses++;
+    }
+
+    /** 캐시 히트율을 반환한다 */
+    hitRate(): number {
+        const total = this.hits + this.misses;
+        return total === 0 ? 0 : this.hits / total;
+    }
+
+    /** 통계를 초기화한다 */
+    reset(): void {
+        this.hits = 0;
+        this.misses = 0;
+    }
+}
+
+// ─── In‑Memory TTL Cache Store ───────────────────────────────────────────────
+
+interface CacheEntry {
+    value: string;
+    expiresAt: number;
+}
+
+/**
+ * 간단한 인메모리 TTL 캐시.
+ * maxEntries를 초과하면 가장 오래된 항목을 제거합니다.
+ */
+export class MemoryCacheStore {
+    private readonly store = new Map<string, CacheEntry>();
+    private readonly maxEntries: number;
+
+    /** MemoryCacheStore 인스턴스를 초기화한다 */
+    constructor(maxEntries = 10000) {
+        this.maxEntries = maxEntries;
+    }
+
+    /** 키로 캐시 항목을 조회한다 */
+    get(key: string): { value: string; found: boolean } {
+        const entry = this.store.get(key);
+        if (!entry) return { value: "", found: false };
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return { value: "", found: false };
+        }
+        return { value: entry.value, found: true };
+    }
+
+    /** 캐시 항목을 저장한다 */
+    set(key: string, value: string, ttlMs: number): void {
+        // 용량 초과 시 정리
+        if (this.store.size >= this.maxEntries) {
+            this.evict();
+        }
+        this.store.set(key, {
+            value,
+            expiresAt: Date.now() + ttlMs,
+        });
+    }
+
+    /** 모든 캐시 항목을 삭제한다 */
+    flush(): void {
+        this.store.clear();
+    }
+
+    get size(): number {
+        return this.store.size;
+    }
+
+    /** 만료된 항목 + 가장 오래된 20% 제거 */
+    private evict(): void {
+        const now = Date.now();
+        for (const [key, entry] of this.store) {
+            if (now > entry.expiresAt) {
+                this.store.delete(key);
+            }
+        }
+        // 여전히 초과하면 가장 오래된 항목 제거
+        const excess = this.store.size - Math.floor(this.maxEntries * 0.8);
+        if (excess > 0) {
+            let count = 0;
+            for (const key of this.store.keys()) {
+                if (count >= excess) break;
+                this.store.delete(key);
+                count++;
+            }
+        }
+    }
+}

package/src/app/plugins/llm/chatbot-store.ts

@@ -0,0 +1,270 @@
+/**
+ * 챗봇 저장소 — Entity Server 어댑터
+ *
+ * llm_chatbot 엔티티: 챗봇 정의 CRUD
+ * llm_conversation 엔티티: 챗봇 대화 세션 (chatbot_seq 컬럼으로 연결)
+ */
+
+import { entityServer, logger } from "@gateway/api";
+import type { Message } from "./types/index.ts";
+import type {
+    ChatbotStore,
+    Chatbot,
+    ChatbotSummary,
+    ChatbotCreateInput,
+    ChatbotUpdateInput,
+    ChatbotSessionSummary,
+    ChatbotSessionFilter,
+} from "./types/chatbot.ts";
+
+function truncate(s: string, max: number): string {
+    const arr = [...s];
+    return arr.length <= max ? s : arr.slice(0, max).join("") + "…";
+}
+
+function parseMessages(raw: unknown): Message[] {
+    try {
+        const s = typeof raw === "string" ? raw : JSON.stringify(raw ?? []);
+        return JSON.parse(s) as Message[];
+    } catch {
+        return [];
+    }
+}
+
+// ─── Chatbot 정의 어댑터 ─────────────────────────────────────────────────────
+
+export class ChatbotEntityAdapter implements ChatbotStore {
+    // ── 챗봇 CRUD ──────────────────────────────────────────────────────────
+
+    /** 챗봇 정의를 seq로 조회한다 */
+    async getChatbot(seq: number): Promise<Chatbot> {
+        const resp = await entityServer.get<Record<string, unknown>>(
+            "llm_chatbot",
+            seq,
+        );
+        const row = resp.data as Record<string, unknown>;
+        if (!row) throw new Error(`Chatbot seq=${seq} not found`);
+        return rowToChatbot(seq, row);
+    }
+
+    /** 챗봇 정의를 name으로 조회한다 */
+    async getChatbotByName(name: string): Promise<Chatbot | null> {
+        const resp = await entityServer.list<Record<string, unknown>>(
+            "llm_chatbot",
+            { conditions: { name }, limit: 1 },
+        );
+        const items = resp?.data?.items ?? [];
+        if (!items.length) return null;
+        const row = items[0];
+        return rowToChatbot(Number(row.seq), row);
+    }
+
+    /** 챗봇 목록을 조회한다 */
+    async listChatbots(): Promise<ChatbotSummary[]> {
+        const resp = await entityServer.list<Record<string, unknown>>(
+            "llm_chatbot",
+            { limit: 200 },
+        );
+        const items = resp?.data?.items ?? [];
+        return items.map((row) => ({
+            seq: Number(row.seq),
+            name: String(row.name ?? ""),
+            label: String(row.label ?? ""),
+            ragEnabled: Boolean(row.rag_enabled),
+            status: String(row.status ?? "active"),
+            createdAt: String(row.created_time ?? ""),
+        }));
+    }
+
+    /** 챗봇을 생성한다 */
+    async createChatbot(input: ChatbotCreateInput): Promise<number> {
+        const data: Record<string, unknown> = {
+            name: input.name,
+            label: input.label,
+            rag_enabled: input.ragEnabled ?? false,
+            status: "active",
+        };
+        if (input.systemMsg) data.system_msg = input.systemMsg;
+        if (input.welcomeMessage) data.welcome_message = input.welcomeMessage;
+        if (input.providerName) data.provider_name = input.providerName;
+        if (input.ragTenantId) data.rag_tenant_id = input.ragTenantId;
+        if (input.ragTopK != null) data.rag_top_k = input.ragTopK;
+        if (input.ragMinScore != null) data.rag_min_score = input.ragMinScore;
+        if (input.ragMetadata)
+            data.rag_metadata = JSON.stringify(input.ragMetadata);
+
+        const resp = await entityServer.submit("llm_chatbot", data);
+        return resp.seq ?? 0;
+    }
+
+    /** 챗봇 설정을 수정한다 */
+    async updateChatbot(seq: number, input: ChatbotUpdateInput): Promise<void> {
+        const data: Record<string, unknown> = { seq };
+        if (input.label != null) data.label = input.label;
+        if (input.systemMsg != null) data.system_msg = input.systemMsg;
+        if (input.welcomeMessage != null)
+            data.welcome_message = input.welcomeMessage;
+        if (input.providerName != null) data.provider_name = input.providerName;
+        if (input.ragEnabled != null) data.rag_enabled = input.ragEnabled;
+        if (input.ragTenantId != null) data.rag_tenant_id = input.ragTenantId;
+        if (input.ragTopK != null) data.rag_top_k = input.ragTopK;
+        if (input.ragMinScore != null) data.rag_min_score = input.ragMinScore;
+        if (input.ragMetadata != null)
+            data.rag_metadata = JSON.stringify(input.ragMetadata);
+        if (input.status != null) data.status = input.status;
+
+        await entityServer.submit("llm_chatbot", data);
+    }
+
+    /** 챗봇을 삭제한다 */
+    async deleteChatbot(seq: number): Promise<void> {
+        await entityServer.delete("llm_chatbot", seq);
+    }
+
+    // ── 세션 관리 ──────────────────────────────────────────────────────────
+
+    /** 챗봇 대화 세션을 생성한다 (llm_conversation + chatbot_seq) */
+    async createSession(
+        chatbotSeq: number,
+        providerName: string,
+        title: string,
+        userSeq?: number,
+        sessionId?: string,
+        systemMsg?: string,
+    ): Promise<number> {
+        const data: Record<string, unknown> = {
+            chatbot_seq: chatbotSeq,
+            provider_name: providerName,
+            title,
+            messages: JSON.stringify([]),
+            message_count: 0,
+            total_tokens: 0,
+            status: "active",
+        };
+        if (userSeq) data.user_seq = userSeq;
+        if (sessionId) data.session_id = sessionId;
+        if (systemMsg) data.system_msg = systemMsg;
+
+        const resp = await entityServer.submit("llm_conversation", data);
+        return resp.seq ?? 0;
+    }
+
+    /** 세션의 메시지 배열과 시스템 메시지를 조회한다 */
+    async getSessionMessages(
+        sessionSeq: number,
+    ): Promise<{ messages: Message[]; systemMsg: string }> {
+        const resp = await entityServer.get<Record<string, unknown>>(
+            "llm_conversation",
+            sessionSeq,
+        );
+        const row = resp.data as Record<string, unknown>;
+        if (!row) throw new Error(`Session seq=${sessionSeq} not found`);
+
+        return {
+            messages: parseMessages(row.messages),
+            systemMsg: String(row.system_msg ?? ""),
+        };
+    }
+
+    /** 세션에 메시지를 추가하고 누계 토큰을 업데이트한다 */
+    async appendSessionMessages(
+        sessionSeq: number,
+        messages: Message[],
+        usage?: { totalTokens?: number },
+    ): Promise<void> {
+        // 현재 메시지 로드
+        const { messages: existing } =
+            await this.getSessionMessages(sessionSeq);
+        const all = [...existing, ...messages];
+        const lastMsg =
+            all.length > 0 ? truncate(all[all.length - 1].content, 200) : "";
+
+        const data: Record<string, unknown> = {
+            seq: sessionSeq,
+            messages: JSON.stringify(all),
+            message_count: all.length,
+            last_message: lastMsg,
+        };
+        if (usage?.totalTokens) {
+            // 누계 위해 기존 값 가져오기
+            const resp = await entityServer.get<Record<string, unknown>>(
+                "llm_conversation",
+                sessionSeq,
+            );
+            const row = resp.data as Record<string, unknown>;
+            data.total_tokens =
+                Number(row?.total_tokens ?? 0) + (usage.totalTokens ?? 0);
+        }
+
+        await entityServer.submit("llm_conversation", data);
+    }
+
+    /** 챗봇에 귀속된 세션 목록을 조회한다 */
+    async listSessions(
+        filter: ChatbotSessionFilter,
+    ): Promise<ChatbotSessionSummary[]> {
+        const conditions: Record<string, unknown> = {
+            chatbot_seq: filter.chatbotSeq,
+        };
+        if (filter.userSeq) conditions.user_seq = filter.userSeq;
+        if (filter.sessionId) conditions.session_id = filter.sessionId;
+
+        const resp = await entityServer.list<Record<string, unknown>>(
+            "llm_conversation",
+            {
+                conditions,
+                page: Math.floor(filter.offset / filter.limit) + 1,
+                limit: filter.limit,
+            },
+        );
+        const items = resp?.data?.items ?? [];
+        return items.map((row) => ({
+            sessionSeq: Number(row.seq),
+            chatbotSeq: Number(row.chatbot_seq ?? filter.chatbotSeq),
+            title: String(row.title ?? ""),
+            messageCount: Number(row.message_count ?? 0),
+            totalTokens: Number(row.total_tokens ?? 0),
+            lastMessage: String(row.last_message ?? ""),
+            updatedAt: String(row.updated_time ?? ""),
+        }));
+    }
+
+    /** 세션을 삭제한다 */
+    async deleteSession(sessionSeq: number): Promise<void> {
+        await entityServer.delete("llm_conversation", sessionSeq);
+    }
+}
+
+// ─── 변환 헬퍼 ───────────────────────────────────────────────────────────────
+
+function rowToChatbot(seq: number, row: Record<string, unknown>): Chatbot {
+    let ragMetadata: Record<string, string> | undefined;
+    if (row.rag_metadata) {
+        try {
+            ragMetadata =
+                typeof row.rag_metadata === "string"
+                    ? JSON.parse(row.rag_metadata)
+                    : (row.rag_metadata as Record<string, string>);
+        } catch {
+            /* ignore */
+        }
+    }
+
+    return {
+        seq,
+        name: String(row.name ?? ""),
+        label: String(row.label ?? ""),
+        systemMsg: row.system_msg ? String(row.system_msg) : undefined,
+        welcomeMessage: row.welcome_message
+            ? String(row.welcome_message)
+            : undefined,
+        providerName: row.provider_name ? String(row.provider_name) : undefined,
+        ragEnabled: Boolean(row.rag_enabled),
+        ragTenantId: row.rag_tenant_id ? String(row.rag_tenant_id) : undefined,
+        ragTopK: Number(row.rag_top_k ?? 5),
+        ragMinScore: Number(row.rag_min_score ?? 0.7),
+        ragMetadata,
+        status: (row.status as "active" | "inactive") ?? "active",
+        createdAt: String(row.created_time ?? ""),
+    };
+}

package/src/app/plugins/llm/chunker.ts

@@ -0,0 +1,96 @@
+/**
+ * 텍스트 청킹 로직 (plain / markdown 지원)
+ *
+ * Go entity-server internal/llm/chunker.go 기반 TypeScript 포팅
+ */
+
+export class Chunker {
+    readonly chunkSize: number;
+    readonly chunkOverlap: number;
+
+    /** Chunker 인스턴스를 초기화한다 */
+    constructor(chunkSize = 500, chunkOverlap = 50) {
+        if (chunkSize <= 0) chunkSize = 500;
+        if (chunkOverlap < 0) chunkOverlap = 0;
+        if (chunkOverlap >= chunkSize) chunkOverlap = Math.floor(chunkSize / 5);
+
+        this.chunkSize = chunkSize;
+        this.chunkOverlap = chunkOverlap;
+    }
+
+    /**
+     * contentType에 따라 적절한 방식으로 텍스트를 분할합니다.
+     * "text/markdown" → 마크다운 헤더 기준 분할
+     * 그 외 → 슬라이딩 윈도우 분할
+     */
+    chunk(text: string, contentType?: string): string[] {
+        text = text.trim();
+        if (!text) return [];
+
+        if (contentType?.includes("markdown")) {
+            return this.chunkMarkdown(text);
+        }
+        return this.chunkPlain(text);
+    }
+
+    /** 일반 텍스트를 슬라이딩 윈도우 방식으로 분할 */
+    private chunkPlain(text: string): string[] {
+        const chars = [...text]; // Unicode safe
+        const total = chars.length;
+        if (total === 0) return [];
+
+        const chunks: string[] = [];
+        const step = Math.max(this.chunkSize - this.chunkOverlap, 1);
+
+        for (let start = 0; start < total; start += step) {
+            const end = Math.min(start + this.chunkSize, total);
+            const chunk = chars.slice(start, end).join("").trim();
+            if (chunk) chunks.push(chunk);
+            if (end === total) break;
+        }
+
+        return chunks;
+    }
+
+    /** 마크다운 문서를 헤더(#, ##, ###, ####) 기준으로 분할 */
+    private chunkMarkdown(text: string): string[] {
+        const lines = text.split("\n");
+        const sections: string[] = [];
+        let current: string[] = [];
+
+        for (const line of lines) {
+            if (isMarkdownHeader(line) && current.length > 0) {
+                sections.push(current.join("\n").trim());
+                current = [];
+            }
+            current.push(line);
+        }
+        if (current.length > 0) {
+            sections.push(current.join("\n").trim());
+        }
+
+        const chunks: string[] = [];
+        for (const sec of sections) {
+            const runeLen = [...sec].length;
+            if (runeLen <= this.chunkSize) {
+                if (sec) chunks.push(sec);
+            } else {
+                // 긴 섹션은 plain 방식으로 추가 분할
+                chunks.push(...this.chunkPlain(sec));
+            }
+        }
+
+        return chunks;
+    }
+}
+
+/** 마크다운 헤더 여부를 판별한다 */
+function isMarkdownHeader(line: string): boolean {
+    const trimmed = line.trim();
+    return (
+        trimmed.startsWith("# ") ||
+        trimmed.startsWith("## ") ||
+        trimmed.startsWith("### ") ||
+        trimmed.startsWith("#### ")
+    );
+}