create-entity-app-server 0.0.3

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

@@ -0,0 +1,965 @@
+/**
+ * LLM Service — 프로바이더 풀 관리 + Chat/Stream/Embed/Session/RAG
+ *
+ * Go entity-server internal/llm/service.go + chat.go + session.go + embed.go + rag.go 기반 포팅
+ */
+
+import { logger } from "@gateway/api";
+import type {
+    LlmConfig,
+    LlmProviderConfig,
+    Provider,
+    RateLimiter,
+    LlmClient,
+    ChatRequest,
+    ChatResponse,
+    ChatOption,
+    StreamChunk,
+    TokenUsage,
+    EmbedResponse,
+    Message,
+    ConversationStore,
+    ConversationResponse,
+    DocumentStore,
+    RAGOptions,
+    RAGResponse,
+    SearchResult,
+    UsageQuerier,
+    LlmUsageRecord,
+    ProfileStore,
+} from "./types/index.ts";
+import type { ChatbotStore, ChatbotChatResponse } from "./types/chatbot.ts";
+import { createClient } from "./providers/index.ts";
+import {
+    CacheStats,
+    MemoryCacheStore,
+    generateCacheKey,
+    type CacheKeyInput,
+} from "./cache.ts";
+import {
+    loadTemplate,
+    listTemplates,
+    renderTemplate,
+    validateVars,
+    type LlmPromptTemplate,
+    type RenderedTemplate,
+} from "./template-loader.ts";
+
+// ─── Token-Bucket Rate Limiter ───────────────────────────────────────────────
+
+class TokenBucketLimiter implements RateLimiter {
+    private tokens: number;
+    private lastRefill: number;
+    private readonly maxTokens: number;
+    private readonly refillRate: number; // tokens per ms
+
+    /** TokenBucketLimiter를 초기화한다 */
+    constructor(rpm: number) {
+        this.maxTokens = rpm;
+        this.tokens = rpm;
+        this.refillRate = rpm / 60_000;
+        this.lastRefill = Date.now();
+    }
+
+    /** 토큰 확보를 시도한다 */
+    tryAcquire(): boolean {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return true;
+        }
+        return false;
+    }
+
+    /** 토큰을 보충한다 */
+    private refill(): void {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        this.tokens = Math.min(
+            this.maxTokens,
+            this.tokens + elapsed * this.refillRate,
+        );
+        this.lastRefill = now;
+    }
+}
+
+class InfiniteRateLimiter implements RateLimiter {
+    /** 항상 허용하는 무제한 리밋터 */
+    tryAcquire(): boolean {
+        return true;
+    }
+}
+
+// ─── Service ─────────────────────────────────────────────────────────────────
+
+export class LlmService {
+    private readonly config: LlmConfig;
+    private readonly providers: Map<string, Provider>;
+    private cache: MemoryCacheStore | null = null;
+    private readonly cacheStats = new CacheStats();
+
+    /** 외부에서 주입 */
+    convStore: ConversationStore | null = null;
+    docStore: DocumentStore | null = null;
+    usageQuerier: UsageQuerier | null = null;
+    chatbotStore: ChatbotStore | null = null;
+    profileStore: ProfileStore | null = null;
+
+    /** LlmService를 설정과 프로바이더 클라이언트로 초기화한다 */
+    constructor(config: LlmConfig) {
+        this.config = config;
+        this.providers = new Map();
+
+        // 프로바이더 초기화
+        for (const [name, cfg] of Object.entries(config.providers)) {
+            try {
+                const client = createClient(cfg);
+                const rpm = cfg.rate_limit_rpm ?? 0;
+                const limiter: RateLimiter =
+                    rpm > 0
+                        ? new TokenBucketLimiter(rpm)
+                        : new InfiniteRateLimiter();
+
+                this.providers.set(name, {
+                    name,
+                    client,
+                    config: cfg,
+                    rateLimiter: limiter,
+                });
+                logger.info(
+                    `LLM provider registered: ${name} (${cfg.driver}/${cfg.model})`,
+                );
+            } catch (err) {
+                logger.error({ err }, `Failed to create LLM provider: ${name}`);
+            }
+        }
+
+        // 캐시 초기화
+        if (config.cache?.enabled) {
+            this.cache = new MemoryCacheStore(config.cache.max_entries);
+            logger.info(
+                "LLM response cache enabled (TTL=%ds)",
+                config.cache.ttl_seconds,
+            );
+        }
+    }
+
+    // ─── Getters ─────────────────────────────────────────────────────────
+
+    /** LLM 설정을 반환한다 */
+    getConfig(): LlmConfig {
+        return this.config;
+    }
+
+    /** 등록된 프로바이더 맵을 반환한다 */
+    getProviders(): Map<string, Provider> {
+        return this.providers;
+    }
+
+    /** 기본 프로바이더 이름을 반환한다 */
+    defaultProviderName(): string {
+        return this.config.default;
+    }
+
+    /** 이름으로 프로바이더를 조회한다 */
+    private getProvider(name?: string): Provider {
+        const key = name || this.config.default;
+        const p = this.providers.get(key);
+        if (!p) throw new Error(`LLM provider "${key}" not found`);
+        return p;
+    }
+
+    // ─── Chat ────────────────────────────────────────────────────────────
+
+    /** 채팅 완성을 실행한다 */
+    async chat(
+        providerName: string | undefined,
+        req: ChatRequest,
+        ...opts: ChatOption[]
+    ): Promise<ChatResponse> {
+        for (const o of opts) o(req);
+
+        const provider = this.getProvider(providerName);
+
+        // 캐시 조회
+        let cacheKey: string | null = null;
+        if (this.cache && this.config.cache?.enabled) {
+            const excluded = this.config.cache.exclude_providers?.includes(
+                provider.name,
+            );
+            if (!excluded) {
+                cacheKey = generateCacheKey({
+                    provider: provider.name,
+                    model: provider.config.model,
+                    messages: req.messages,
+                    system: req.system,
+                    temperature: req.temperature,
+                    maxTokens: req.maxTokens,
+                    jsonMode: req.jsonMode,
+                });
+
+                const cached = this.cache.get(cacheKey);
+                if (cached.found) {
+                    try {
+                        const resp: ChatResponse = JSON.parse(cached.value);
+                        resp.cached = true;
+                        this.cacheStats.recordHit();
+                        return resp;
+                    } catch {
+                        /* parse 실패 → 캐시 미스 처리 */
+                    }
+                }
+                this.cacheStats.recordMiss();
+            }
+        }
+
+        // Rate limit
+        if (!provider.rateLimiter.tryAcquire()) {
+            throw new Error(
+                `LLM rate limit exceeded for provider "${provider.name}"`,
+            );
+        }
+
+        const start = Date.now();
+        try {
+            const resp = await provider.client.chat(req);
+            const elapsed = Date.now() - start;
+
+            // 비동기 사용량 기록
+            this.recordUsageAsync(
+                provider.name,
+                provider.config.model,
+                resp,
+                elapsed,
+                "success",
+            );
+
+            // 캐시 저장
+            if (cacheKey && resp.finishReason === "stop") {
+                const ttlMs = (this.config.cache?.ttl_seconds ?? 3600) * 1000;
+                this.cache!.set(cacheKey, JSON.stringify(resp), ttlMs);
+            }
+
+            return resp;
+        } catch (err) {
+            const elapsed = Date.now() - start;
+            this.recordUsageAsync(
+                provider.name,
+                provider.config.model,
+                null,
+                elapsed,
+                "error",
+            );
+            throw err;
+        }
+    }
+
+    // ─── Chat Stream ─────────────────────────────────────────────────────
+
+    /** 스트리밍 채팅을 실행한다 */
+    async *chatStream(
+        providerName: string | undefined,
+        req: ChatRequest,
+        ...opts: ChatOption[]
+    ): AsyncGenerator<StreamChunk> {
+        for (const o of opts) o(req);
+
+        const provider = this.getProvider(providerName);
+
+        if (!provider.rateLimiter.tryAcquire()) {
+            throw new Error(
+                `LLM rate limit exceeded for provider "${provider.name}"`,
+            );
+        }
+
+        const stream = provider.client.chatStream(req);
+        let lastUsage: TokenUsage | undefined;
+
+        for await (const chunk of stream) {
+            if (chunk.usage) lastUsage = chunk.usage;
+            yield chunk;
+            if (chunk.done) break;
+        }
+
+        // 스트리밍 완료 후 사용량 기록
+        if (lastUsage) {
+            this.recordUsageFromTokensAsync(
+                provider.name,
+                provider.config.model,
+                lastUsage,
+                "success",
+            );
+        }
+    }
+
+    // ─── Simple Chat ─────────────────────────────────────────────────────
+
+    /** 단일 메시지로 간편 채팅한다 */
+    async simpleChat(
+        providerName: string | undefined,
+        system: string,
+        user: string,
+        ...opts: ChatOption[]
+    ): Promise<string> {
+        const req: ChatRequest = {
+            system,
+            messages: [{ role: "user", content: user }],
+        };
+        const resp = await this.chat(providerName, req, ...opts);
+        return resp.content;
+    }
+
+    // ─── Template Chat ────────────────────────────────────────────────────
+
+    /**
+     * 프롬프트 템플릿을 로드해 변수를 주입하고 chat을 실행한다.
+     *
+     * @param templateName  templates/llm/prompts/{name}.json 의 name
+     * @param vars          {{variable}} 치환에 사용할 변수 맵
+     * @param providerName  사용할 LLM 프로바이더 (생략 시 default)
+     * @param userMessage   user_msg 템플릿을 무시하고 직접 전달할 사용자 메시지 (선택)
+     */
+    async chatWithTemplate(
+        templateName: string,
+        vars: Record<string, string>,
+        providerName?: string,
+        userMessage?: string,
+    ): Promise<{
+        content: string;
+        model: string;
+        template: string;
+        missing?: string[];
+    }> {
+        const tpl = loadTemplate(templateName);
+        if (!tpl) throw new Error(`LLM template "${templateName}" not found`);
+
+        const missing = validateVars(tpl, vars);
+        const rendered = renderTemplate(tpl, vars);
+
+        const userContent = userMessage ?? rendered.userMsg;
+        if (!userContent) {
+            throw new Error(
+                `Template "${templateName}" has no user_msg — provide "message" in request body`,
+            );
+        }
+
+        const req: ChatRequest = {
+            system: rendered.system,
+            messages: [{ role: "user", content: userContent }],
+            maxTokens: rendered.maxTokens,
+            temperature: rendered.temperature,
+        };
+
+        const resp = await this.chat(providerName, req);
+        return {
+            content: resp.content,
+            model: resp.model ?? "",
+            template: templateName,
+            missing: missing.length > 0 ? missing : undefined,
+        };
+    }
+
+    /**
+     * 프롬프트 템플릿 기반 스트리밍 채팅을 실행한다.
+     */
+    async *chatStreamWithTemplate(
+        templateName: string,
+        vars: Record<string, string>,
+        providerName?: string,
+        userMessage?: string,
+    ): AsyncGenerator<StreamChunk> {
+        const tpl = loadTemplate(templateName);
+        if (!tpl) throw new Error(`LLM template "${templateName}" not found`);
+
+        const rendered = renderTemplate(tpl, vars);
+        const userContent = userMessage ?? rendered.userMsg;
+        if (!userContent) {
+            throw new Error(
+                `Template "${templateName}" has no user_msg — provide "message" in request body`,
+            );
+        }
+
+        const req: ChatRequest = {
+            system: rendered.system,
+            messages: [{ role: "user", content: userContent }],
+            maxTokens: rendered.maxTokens,
+            temperature: rendered.temperature,
+        };
+
+        yield* this.chatStream(providerName, req);
+    }
+
+    /**
+     * 사용 가능한 템플릿 목록을 반환한다.
+     */
+    getTemplateList(): Array<{
+        name: string;
+        label?: string;
+        variables?: string[];
+    }> {
+        return listTemplates().map((name) => {
+            const tpl = loadTemplate(name);
+            return {
+                name,
+                label: tpl?.label,
+                variables: tpl?.variables,
+            };
+        });
+    }
+
+    // ─── Embed ───────────────────────────────────────────────────────────
+
+    /** 텍스트 임베딩을 실행한다 */
+    async embed(
+        providerName: string | undefined,
+        input: string[],
+    ): Promise<EmbedResponse> {
+        const provider = this.getProvider(providerName);
+        if (!provider.rateLimiter.tryAcquire()) {
+            throw new Error(
+                `LLM rate limit exceeded for provider "${provider.name}"`,
+            );
+        }
+
+        return provider.client.embed({
+            input,
+            model: provider.config.embed_model || provider.config.model,
+        });
+    }
+
+    /** 단일 텍스트의 임베딩 벡터를 반환한다 */
+    async embedOne(
+        providerName: string | undefined,
+        text: string,
+    ): Promise<number[]> {
+        const resp = await this.embed(providerName, [text]);
+        if (resp.embeddings.length === 0)
+            throw new Error("No embedding returned");
+        return resp.embeddings[0];
+    }
+
+    // ─── Session Chat ────────────────────────────────────────────────────
+
+    /** 대화 세션 컨텍스트로 채팅한다 */
+    async chatInSession(
+        providerName: string | undefined,
+        conversationSeq: number,
+        userMsg: string,
+        userSeq?: number,
+        ...opts: ChatOption[]
+    ): Promise<ConversationResponse> {
+        if (!this.convStore)
+            throw new Error("Conversation store not configured");
+
+        const provider = this.getProvider(providerName);
+        if (!provider.rateLimiter.tryAcquire()) {
+            throw new Error(
+                `LLM rate limit exceeded for provider "${provider.name}"`,
+            );
+        }
+
+        let messages: Message[] = [];
+        let systemMsg = "";
+        let convSeq = conversationSeq;
+
+        if (conversationSeq > 0) {
+            // 기존 세션: 히스토리 로드
+            const conv = await this.convStore.getConversation(conversationSeq);
+            messages = conv.messages;
+            systemMsg = conv.systemMsg ?? "";
+        } else {
+            // 새 세션 생성
+            convSeq = await this.convStore.createConversation({
+                providerName: provider.name,
+                title: truncate(userMsg, 100),
+                userSeq,
+            });
+        }
+
+        messages.push({ role: "user", content: userMsg });
+
+        // Profile Memory 주입
+        if (this.profileStore && userSeq) {
+            const profileText = await this.profileStore
+                .formatForPrompt({ userSeq })
+                .catch(() => "");
+            if (profileText) {
+                systemMsg = systemMsg
+                    ? `${systemMsg}\n\n${profileText}`
+                    : profileText;
+            }
+        }
+
+        const req: ChatRequest = {
+            system: systemMsg,
+            messages,
+            maxTokens: provider.config.max_tokens,
+            temperature: provider.config.temperature,
+        };
+        for (const o of opts) o(req);
+
+        const start = Date.now();
+        const resp = await provider.client.chat(req);
+        const elapsed = Date.now() - start;
+
+        const newMessages: Message[] = [
+            { role: "user", content: userMsg },
+            { role: "assistant", content: resp.content },
+        ];
+
+        // 비동기 히스토리 저장
+        this.convStore
+            .appendMessages(convSeq, newMessages, resp.usage)
+            .catch((err) =>
+                logger.error({ err }, "Failed to append conversation messages"),
+            );
+
+        // 비동기 사용량 기록
+        this.recordUsageAsync(
+            provider.name,
+            provider.config.model,
+            resp,
+            elapsed,
+            "success",
+        );
+
+        return {
+            conversationSeq: convSeq,
+            content: resp.content,
+            finishReason: resp.finishReason,
+            usage: resp.usage,
+            model: resp.model,
+        };
+    }
+
+    // ─── RAG Chat ────────────────────────────────────────────────────────
+
+    /** RAG 기반 채팅을 실행한다 */
+    async chatWithRAG(
+        providerName: string | undefined,
+        userMsg: string,
+        opts?: RAGOptions,
+    ): Promise<RAGResponse> {
+        if (!this.docStore) throw new Error("Document store not configured");
+
+        const _opts = opts ?? {};
+        const embedProvider = _opts.embedProvider || providerName;
+        const topK = _opts.topK || 5;
+        const minScore = _opts.minScore || 0.7;
+
+        // 유사 문서 검색
+        const results = await this.docStore.searchSimilar({
+            query: userMsg,
+            providerName: embedProvider,
+            topK,
+            minScore,
+            tenantId: _opts.tenantId,
+            metadata: _opts.metadata,
+        });
+
+        // 시스템 프롬프트 조립
+        let systemMsg = _opts.systemMsg || DEFAULT_RAG_SYSTEM_PROMPT;
+        if (results.length > 0) {
+            systemMsg += "\n\n[참고 자료]\n" + buildRAGContext(results);
+        }
+
+        const req: ChatRequest = {
+            system: systemMsg,
+            messages: [{ role: "user", content: userMsg }],
+        };
+
+        const resp = await this.chat(providerName, req);
+
+        return {
+            content: resp.content,
+            finishReason: resp.finishReason,
+            usage: resp.usage,
+            model: resp.model,
+            sources: results,
+        };
+    }
+
+    // ─── Chatbot Chat ─────────────────────────────────────────────────────
+
+    /**
+     * 챗봇과 대화한다 (RAG + 히스토리 통합).
+     *
+     * @param chatbotSeq  llm_chatbot.seq
+     * @param userMsg     사용자 메시지
+     * @param sessionSeq  기존 세션 seq (0이면 신규 생성)
+     * @param userSeq     로그인 사용자 seq (선택)
+     * @param sessionId   비로그인 세션 식별자 (선택)
+     */
+    async chatWithBot(
+        chatbotSeq: number,
+        userMsg: string,
+        sessionSeq: number,
+        userSeq?: number,
+        sessionId?: string,
+    ): Promise<ChatbotChatResponse> {
+        if (!this.chatbotStore) throw new Error("Chatbot store not configured");
+
+        const bot = await this.chatbotStore.getChatbot(chatbotSeq);
+        if (bot.status !== "active")
+            throw new Error(`Chatbot "${bot.name}" is not active`);
+
+        const providerName = bot.providerName || undefined;
+        const provider = this.getProvider(providerName);
+
+        // Rate limit
+        if (!provider.rateLimiter.tryAcquire()) {
+            throw new Error(
+                `LLM rate limit exceeded for provider "${provider.name}"`,
+            );
+        }
+
+        // 세션 로드 또는 신규 생성
+        let curSessionSeq = sessionSeq;
+        let history: Message[] = [];
+        const isNewSession = sessionSeq <= 0;
+
+        if (!isNewSession) {
+            const session =
+                await this.chatbotStore.getSessionMessages(curSessionSeq);
+            history = session.messages;
+        } else {
+            curSessionSeq = await this.chatbotStore.createSession(
+                chatbotSeq,
+                provider.name,
+                truncate(userMsg, 80),
+                userSeq,
+                sessionId,
+                bot.systemMsg ?? undefined,
+            );
+        }
+
+        // Profile Memory 주입
+        let profileInjection = "";
+        if (this.profileStore && userSeq) {
+            profileInjection = await this.profileStore
+                .formatForPrompt({
+                    userSeq,
+                    chatbotSeq,
+                    scope: `chatbot_${chatbotSeq}`,
+                })
+                .catch(() => "");
+            if (!profileInjection) {
+                profileInjection = await this.profileStore
+                    .formatForPrompt({ userSeq })
+                    .catch(() => "");
+            }
+        }
+
+        // RAG 컨텍스트 조립
+        let systemMsg = bot.systemMsg ?? "";
+        if (profileInjection) {
+            systemMsg = systemMsg
+                ? `${systemMsg}\n\n${profileInjection}`
+                : profileInjection;
+        }
+        let ragSources: SearchResult[] | undefined;
+        if (bot.ragEnabled && this.docStore) {
+            ragSources = await this.docStore.searchSimilar({
+                query: userMsg,
+                providerName,
+                topK: bot.ragTopK ?? 5,
+                minScore: bot.ragMinScore ?? 0.7,
+                tenantId: bot.ragTenantId ?? undefined,
+                metadata: bot.ragMetadata ?? undefined,
+            });
+            if (ragSources.length > 0) {
+                systemMsg += "\n\n[참고 자료]\n" + buildRAGContext(ragSources);
+            }
+        }
+
+        const messages: Message[] = [
+            ...history,
+            { role: "user", content: userMsg },
+        ];
+
+        const req: ChatRequest = {
+            system: systemMsg,
+            messages,
+            maxTokens: provider.config.max_tokens,
+            temperature: provider.config.temperature,
+        };
+
+        const start = Date.now();
+        const resp = await provider.client.chat(req);
+        const elapsed = Date.now() - start;
+
+        // 히스토리 저장 (비동기)
+        const newMessages: Message[] = [
+            { role: "user", content: userMsg },
+            { role: "assistant", content: resp.content },
+        ];
+        this.chatbotStore
+            .appendSessionMessages(curSessionSeq, newMessages, resp.usage)
+            .catch((err) =>
+                logger.error(
+                    { err },
+                    "Failed to append chatbot session messages",
+                ),
+            );
+
+        // 사용량 기록 (비동기)
+        this.recordUsageAsync(
+            provider.name,
+            provider.config.model,
+            resp,
+            elapsed,
+            "success",
+        );
+
+        return {
+            sessionSeq: curSessionSeq,
+            content: resp.content,
+            sources: ragSources?.length ? ragSources : undefined,
+            usage: resp.usage,
+            model: resp.model ?? "",
+            isNewSession,
+        };
+    }
+
+    /**
+     * 챗봇과 스트리밍 대화한다 (RAG + 히스토리 통합).
+     *
+     * 반환: { sessionSeq, stream }
+     */
+    async chatStreamWithBot(
+        chatbotSeq: number,
+        userMsg: string,
+        sessionSeq: number,
+        userSeq?: number,
+        sessionId?: string,
+    ): Promise<{ sessionSeq: number; stream: AsyncGenerator<StreamChunk> }> {
+        if (!this.chatbotStore) throw new Error("Chatbot store not configured");
+
+        const bot = await this.chatbotStore.getChatbot(chatbotSeq);
+        if (bot.status !== "active")
+            throw new Error(`Chatbot "${bot.name}" is not active`);
+
+        const providerName = bot.providerName || undefined;
+        const provider = this.getProvider(providerName);
+
+        if (!provider.rateLimiter.tryAcquire()) {
+            throw new Error(
+                `LLM rate limit exceeded for provider "${provider.name}"`,
+            );
+        }
+
+        let curSessionSeq = sessionSeq;
+        let history: Message[] = [];
+
+        if (curSessionSeq > 0) {
+            const session =
+                await this.chatbotStore.getSessionMessages(curSessionSeq);
+            history = session.messages;
+        } else {
+            curSessionSeq = await this.chatbotStore.createSession(
+                chatbotSeq,
+                provider.name,
+                truncate(userMsg, 80),
+                userSeq,
+                sessionId,
+                bot.systemMsg ?? undefined,
+            );
+        }
+
+        // Profile Memory 주입 (스트리밍)
+        let streamProfileInjection = "";
+        if (this.profileStore && userSeq) {
+            streamProfileInjection = await this.profileStore
+                .formatForPrompt({
+                    userSeq,
+                    chatbotSeq,
+                    scope: `chatbot_${chatbotSeq}`,
+                })
+                .catch(() => "");
+            if (!streamProfileInjection) {
+                streamProfileInjection = await this.profileStore
+                    .formatForPrompt({ userSeq })
+                    .catch(() => "");
+            }
+        }
+
+        let systemMsg = bot.systemMsg ?? "";
+        if (streamProfileInjection) {
+            systemMsg = systemMsg
+                ? `${systemMsg}\n\n${streamProfileInjection}`
+                : streamProfileInjection;
+        }
+        if (bot.ragEnabled && this.docStore) {
+            const results = await this.docStore.searchSimilar({
+                query: userMsg,
+                providerName,
+                topK: bot.ragTopK ?? 5,
+                minScore: bot.ragMinScore ?? 0.7,
+                tenantId: bot.ragTenantId ?? undefined,
+                metadata: bot.ragMetadata ?? undefined,
+            });
+            if (results.length > 0) {
+                systemMsg += "\n\n[참고 자료]\n" + buildRAGContext(results);
+            }
+        }
+
+        const messages: Message[] = [
+            ...history,
+            { role: "user", content: userMsg },
+        ];
+
+        const req: ChatRequest = {
+            system: systemMsg,
+            messages,
+            maxTokens: provider.config.max_tokens,
+            temperature: provider.config.temperature,
+        };
+
+        const self = this;
+        const store = this.chatbotStore;
+
+        async function* gen(): AsyncGenerator<StreamChunk> {
+            let fullContent = "";
+            let lastUsage: import("./types/index.ts").TokenUsage | undefined;
+
+            for await (const chunk of provider.client.chatStream(req)) {
+                if (chunk.content) fullContent += chunk.content;
+                if (chunk.usage) lastUsage = chunk.usage;
+                yield chunk;
+                if (chunk.done) break;
+            }
+
+            // 히스토리 저장
+            const newMessages: Message[] = [
+                { role: "user", content: userMsg },
+                { role: "assistant", content: fullContent },
+            ];
+            store
+                .appendSessionMessages(curSessionSeq, newMessages, lastUsage)
+                .catch((err) =>
+                    logger.error(
+                        { err },
+                        "Failed to append chatbot stream messages",
+                    ),
+                );
+
+            // 사용량 기록
+            if (lastUsage) {
+                self.recordUsageFromTokensAsync(
+                    provider.name,
+                    provider.config.model,
+                    lastUsage,
+                    "success",
+                );
+            }
+        }
+
+        return { sessionSeq: curSessionSeq, stream: gen() };
+    }
+
+    // ─── Cache Stats ─────────────────────────────────────────────────────
+
+    /** 캐시 통계를 반환한다 */
+    getCacheStats(): Record<string, unknown> {
+        const enabled = this.config.cache?.enabled ?? false;
+        return {
+            enabled,
+            hits: this.cacheStats.hits,
+            misses: this.cacheStats.misses,
+            hit_rate: this.cacheStats.hitRate(),
+            ttl_seconds: this.config.cache?.ttl_seconds ?? 0,
+        };
+    }
+
+    /** 캐시를 비운다 */
+    clearCache(): void {
+        this.cache?.flush();
+    }
+
+    // ─── Cleanup ─────────────────────────────────────────────────────────
+
+    /** 모든 프로바이더 클라이언트를 정리한다 */
+    close(): void {
+        for (const p of this.providers.values()) {
+            p.client.close();
+        }
+    }
+
+    // ─── Private: Usage Recording ────────────────────────────────────────
+
+    /** 비동기로 사용량을 기록한다 */
+    private recordUsageAsync(
+        providerName: string,
+        model: string,
+        resp: ChatResponse | null,
+        elapsedMs: number,
+        status: string,
+    ): void {
+        if (!this.usageQuerier || !this.config.usage_tracking) return;
+
+        const record: LlmUsageRecord = {
+            providerName,
+            model,
+            promptTokens: resp?.usage?.promptTokens ?? 0,
+            completionTokens: resp?.usage?.completionTokens ?? 0,
+            totalTokens: resp?.usage?.totalTokens ?? 0,
+            requestTimeMs: elapsedMs,
+            status: status as LlmUsageRecord["status"],
+            requestedAt: new Date().toISOString(),
+        };
+
+        this.usageQuerier
+            .recordUsage(record)
+            .catch((err) => logger.error({ err }, "LLM usage record error"));
+    }
+
+    /** 토큰 사용량을 비동기로 기록한다 */
+    private recordUsageFromTokensAsync(
+        providerName: string,
+        model: string,
+        usage: TokenUsage,
+        status: string,
+    ): void {
+        if (!this.usageQuerier || !this.config.usage_tracking) return;
+
+        const record: LlmUsageRecord = {
+            providerName,
+            model,
+            promptTokens: usage.promptTokens,
+            completionTokens: usage.completionTokens,
+            totalTokens: usage.totalTokens,
+            requestTimeMs: 0,
+            status: status as LlmUsageRecord["status"],
+            requestedAt: new Date().toISOString(),
+        };
+
+        this.usageQuerier
+            .recordUsage(record)
+            .catch((err) => logger.error({ err }, "LLM usage record error"));
+    }
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const DEFAULT_RAG_SYSTEM_PROMPT = `당신은 제공된 참고 자료를 기반으로 정확하게 답변하는 AI 어시스턴트입니다.
+
+[규칙]
+1. 참고 자료에 있는 정보만 사용하여 답변합니다.
+2. 참고 자료에 해당 정보가 없으면 솔직하게 "제공된 자료에서 해당 정보를 찾을 수 없습니다"라고 안내합니다.
+3. 한국어로 친절하게 답변합니다.`;
+
+/** RAG 컨텍스트 문자열을 생성한다 */
+function buildRAGContext(results: SearchResult[]): string {
+    return results
+        .map(
+            (r, i) =>
+                `--- 문서 ${i + 1}: ${r.title} (score: ${r.score.toFixed(2)}) ---\n${r.content}\n`,
+        )
+        .join("\n");
+}
+
+/** 문자열을 최대 길이로 자른다 */
+function truncate(s: string, maxLen: number): string {
+    const arr = [...s];
+    return arr.length <= maxLen ? s : arr.slice(0, maxLen).join("");
+}