create-entity-app-server 0.0.3

package/src/app/plugins/llm/docs/api.md

@@ -0,0 +1,250 @@
+# LLM API 레퍼런스
+
+기본 경로: `/api/v1/llm`
+
+---
+
+## 엔드포인트 목록
+
+| 메서드   | 경로                                               | 인증        | 설명                        |
+| -------- | -------------------------------------------------- | ----------- | --------------------------- |
+| `POST`   | [`/chat`](#post-chat)                              |             | 채팅                        |
+| `POST`   | [`/chat/stream`](#post-chatstream)                 |             | SSE 스트리밍 채팅           |
+| `POST`   | [`/conversations`](#post-conversations)            | 로그인 필요 | 대화 세션 생성              |
+| `GET`    | [`/conversations/:seq`](#get-conversations-seq)    | 로그인 필요 | 대화 세션 조회              |
+| `PATCH`  | [`/conversations/:seq`](#patch-conversations-seq)  | 로그인 필요 | 대화 세션 수정              |
+| `DELETE` | [`/conversations/:seq`](#delete-conversations-seq) | 로그인 필요 | 대화 세션 삭제              |
+| `POST`   | [`/rag/documents`](#post-ragdocuments)             | 로그인 필요 | 문서 업로드 및 임베딩       |
+| `GET`    | [`/rag/documents`](#get-ragdocuments)              | 로그인 필요 | 업로드된 문서 목록          |
+| `POST`   | [`/rag/search`](#post-ragsearch)                   | 로그인 필요 | 시맨틱 검색                 |
+| `POST`   | [`/rag/chat`](#post-ragchat)                       | 로그인 필요 | RAG 기반 채팅               |
+| `GET`    | [`/chatbots`](#get-chatbots)                       | 로그인 필요 | 챗봇 목록                   |
+| `POST`   | [`/chatbots`](#post-chatbots)                      | 로그인 필요 | 챗봇 생성                   |
+| `GET`    | [`/chatbots/:seq`](#get-chatbots-seq)              | 로그인 필요 | 챗봇 상세                   |
+| `PATCH`  | [`/chatbots/:seq`](#patch-chatbots-seq)            | 로그인 필요 | 챗봇 수정                   |
+| `DELETE` | [`/chatbots/:seq`](#delete-chatbots-seq)           | 로그인 필요 | 챗봇 삭제                   |
+| `POST`   | [`/chatbots/:seq/chat`](#post-chatbots-seq-chat)   |             | 챗봇과 대화                 |
+| `GET`    | [`/providers`](#get-providers)                     | 로그인 필요 | 프로바이더 목록             |
+| `GET`    | [`/usage`](#get-usage)                             | 로그인 필요 | 사용량 내역                 |
+| `GET`    | [`/usage/summary`](#get-usagesummary)              | 로그인 필요 | 프로바이더별 사용량 및 비용 |
+| `GET`    | [`/cache/stats`](#get-cachestats)                  | 로그인 필요 | 캐시 상태 조회              |
+| `DELETE` | [`/cache`](#delete-cache)                          | 로그인 필요 | 캐시 전체 초기화            |
+| `GET`    | [`/templates`](#get-templates)                     | 로그인 필요 | 시스템 프롬프트 템플릿 목록 |
+
+---
+
+## 채팅
+
+### POST /chat
+
+단일 요청/응답 형식으로 채팅합니다.
+
+**요청:**
+
+```json
+{
+    "message": "안녕하세요, 오늘 날씨는 어떤가요?",
+    "provider": "main",
+    "system_prompt": "당신은 친절한 AI 어시스턴트입니다.",
+    "temperature": 0.7,
+    "max_tokens": 2048
+}
+```
+
+**응답:**
+
+```json
+{
+    "ok": true,
+    "data": {
+        "content": "안녕하세요! 저는 실시간 날씨 정보에 접근할 수 없지만...",
+        "model": "gpt-4o-mini",
+        "usage": { "prompt_tokens": 45, "completion_tokens": 80 }
+    }
+}
+```
+
+---
+
+### POST /chat/stream
+
+SSE(Server-Sent Events) 스트리밍 방식으로 채팅합니다.
+
+**요청:** `/chat`과 동일  
+**응답:** `text/event-stream`
+
+```
+data: {"delta":"안녕"}
+data: {"delta":"하세요"}
+data: [DONE]
+```
+
+---
+
+## 대화 세션
+
+여러 턴의 대화 히스토리를 서버에 보관합니다.
+
+### POST /conversations
+
+대화 세션을 생성합니다.
+
+**요청:**
+
+```json
+{
+    "title": "여행 계획",
+    "provider": "main",
+    "system_prompt": "여행 전문 어시스턴트입니다."
+}
+```
+
+대화 세션 생성 후 동일 `:seq`에 `PATCH`로 메시지를 추가하며 대화를 이어갑니다.
+
+### GET /conversations/:seq
+
+대화 세션을 조회합니다.
+
+### PATCH /conversations/:seq
+
+대화 세션을 수정하거나 메시지를 추가합니다.
+
+### DELETE /conversations/:seq
+
+대화 세션을 삭제합니다.
+
+---
+
+## RAG (문서 검색 증강)
+
+문서를 업로드하고 임베딩하여 자연어 질의에 활용합니다.
+
+### POST /rag/documents
+
+문서를 업로드하고 임베딩합니다.
+
+**요청:**
+
+```json
+{
+    "title": "제품 매뉴얼",
+    "content": "본 제품의 사용 방법은...",
+    "provider": "main"
+}
+```
+
+### GET /rag/documents
+
+업로드된 문서 목록을 조회합니다.
+
+### POST /rag/search
+
+자연어로 문서를 시맨틱 검색합니다.
+
+### POST /rag/chat
+
+RAG 기반으로 채팅합니다.
+
+**요청:**
+
+```json
+{
+    "message": "제품 보증 기간은 얼마인가요?",
+    "provider": "main",
+    "top_k": 3
+}
+```
+
+---
+
+## 챗봇 관리
+
+커스텀 챗봇 설정을 DB에 저장하고 외부에 서비스합니다.
+
+### GET /chatbots
+
+챗봇 목록을 조회합니다.
+
+### POST /chatbots
+
+챗봇을 생성합니다.
+
+**요청:**
+
+```json
+{
+    "name": "고객지원 봇",
+    "provider": "main",
+    "system_prompt": "당신은 제품 고객지원 담당자입니다.",
+    "temperature": 0.5,
+    "max_tokens": 1024
+}
+```
+
+### GET /chatbots/:seq
+
+챗봇 상세를 조회합니다.
+
+### PATCH /chatbots/:seq
+
+챗봇을 수정합니다.
+
+### DELETE /chatbots/:seq
+
+챗봇을 삭제합니다.
+
+### POST /chatbots/:seq/chat
+
+챗봇과 대화를 나눕니다. 인증 없이 사용 가능합니다.
+
+---
+
+## 프로바이더 및 사용량
+
+### GET /providers
+
+설정된 프로바이더 목록을 조회합니다.
+
+### GET /usage
+
+API 사용량 내역을 조회합니다.
+
+### GET /usage/summary
+
+프로바이더별 사용량 및 비용을 조회합니다.
+
+**응답 예시:**
+
+```json
+{
+    "ok": true,
+    "data": {
+        "main": {
+            "model": "gpt-4o-mini",
+            "prompt_tokens": 12500,
+            "completion_tokens": 8300,
+            "estimated_cost_usd": 0.031
+        }
+    }
+}
+```
+
+---
+
+## 캐시
+
+### GET /cache/stats
+
+캐시 상태를 조회합니다.
+
+### DELETE /cache
+
+캐시를 전체 초기화합니다.
+
+---
+
+## 템플릿
+
+### GET /templates
+
+시스템 프롬프트 템플릿 목록을 조회합니다.

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

@@ -0,0 +1,318 @@
+/**
+ * RAG 문서 저장소 — 인메모리 벡터 인덱스 + Entity Server 어댑터
+ */
+
+import { entityServer } from "@gateway/api";
+import { logger } from "@gateway/api";
+import { Chunker } from "./chunker.ts";
+import type {
+    DocumentStore,
+    DocumentIngestInput,
+    DocumentIngestResult,
+    SearchInput,
+    SearchResult,
+    DocumentSummary,
+    DocumentFilter,
+    EmbedResponse,
+} from "./types/index.ts";
+
+/** LlmService에서 DocumentStore가 사용하는 메서드만 추출한 인터페이스 */
+interface LlmServiceLike {
+    defaultProviderName(): string;
+    embed(
+        providerName: string | undefined,
+        input: string[],
+    ): Promise<EmbedResponse>;
+    embedOne(providerName: string | undefined, text: string): Promise<number[]>;
+}
+
+// ─── Memory Vector Index ─────────────────────────────────────────────────────
+
+interface VectorChunk {
+    documentId: string;
+    chunkIndex: number;
+    title: string;
+    content: string;
+    metadata?: Record<string, string>;
+    tenantId?: string;
+    providerName: string;
+    vector: number[];
+}
+
+export class MemoryDocumentIndex {
+    private chunks: VectorChunk[] = [];
+
+    /** 벡터 청크를 인덱스에 추가한다 */
+    add(chunk: VectorChunk): void {
+        this.chunks.push(chunk);
+    }
+
+    /** 문서 ID로 청크를 삭제한다 */
+    deleteByDocumentId(documentId: string): void {
+        this.chunks = this.chunks.filter((c) => c.documentId !== documentId);
+    }
+
+    /** 쿼리 벡터로 유사 청크를 검색한다 */
+    search(
+        queryVec: number[],
+        topK: number,
+        minScore: number,
+        tenantId?: string,
+        metadata?: Record<string, string>,
+    ): SearchResult[] {
+        const scored: Array<{ chunk: VectorChunk; score: number }> = [];
+
+        for (const chunk of this.chunks) {
+            if (tenantId && chunk.tenantId !== tenantId) continue;
+            if (metadata && !matchesMetadata(chunk.metadata, metadata))
+                continue;
+
+            const score = cosineSimilarity(queryVec, chunk.vector);
+            if (score >= minScore) {
+                scored.push({ chunk, score });
+            }
+        }
+
+        scored.sort((a, b) => b.score - a.score);
+        const top = scored.slice(0, topK);
+
+        return top.map((r) => ({
+            documentId: r.chunk.documentId,
+            chunkIndex: r.chunk.chunkIndex,
+            content: r.chunk.content,
+            score: r.score,
+            title: r.chunk.title,
+            metadata: r.chunk.metadata,
+        }));
+    }
+
+    /** 인덱스를 비운다 */
+    clear(): void {
+        this.chunks = [];
+    }
+
+    /** 인덱스를 교체한다 */
+    replaceAll(chunks: VectorChunk[]): void {
+        this.chunks = chunks;
+    }
+}
+
+// ─── Document Entity Adapter ─────────────────────────────────────────────────
+
+export class DocumentEntityAdapter implements DocumentStore {
+    private readonly svc: LlmServiceLike;
+    private readonly index: MemoryDocumentIndex;
+
+    /** DocumentEntityAdapter 인스턴스를 초기화한다 */
+    constructor(svc: LlmServiceLike) {
+        this.svc = svc;
+        this.index = new MemoryDocumentIndex();
+    }
+
+    /** 문서를 청킹·임베딩하여 인제스트한다 */
+    async ingestDocument(
+        input: DocumentIngestInput,
+    ): Promise<DocumentIngestResult> {
+        const chunkSize = input.chunkSize || 500;
+        const chunkOverlap = input.chunkOverlap || 50;
+        const chunker = new Chunker(chunkSize, chunkOverlap);
+        const chunks = chunker.chunk(input.content, input.contentType);
+
+        if (chunks.length === 0) {
+            throw new Error("No chunks produced from document");
+        }
+
+        const providerName =
+            input.providerName || this.svc.defaultProviderName();
+        const metaJSON = JSON.stringify(input.metadata ?? {});
+        let totalTokens = 0;
+
+        for (let i = 0; i < chunks.length; i++) {
+            // 임베딩 생성
+            const embedResp = await this.svc.embed(providerName, [chunks[i]]);
+            totalTokens += embedResp.totalTokens;
+
+            const vector = embedResp.embeddings[0] ?? [];
+            const vectorJSON = JSON.stringify(vector);
+
+            // DB 저장
+            const data: Record<string, unknown> = {
+                document_id: input.documentId,
+                chunk_index: i,
+                title: input.title,
+                content: chunks[i],
+                content_type: input.contentType ?? "text/plain",
+                vector: vectorJSON,
+                vector_dim: vector.length,
+                metadata: metaJSON,
+                provider_name: providerName,
+                token_count: Math.floor(chunks[i].length / 4),
+            };
+            if (input.tenantId) data.tenant_id = input.tenantId;
+
+            await entityServer.submit("llm_document", data);
+
+            // 인메모리 인덱스에 추가
+            this.index.add({
+                documentId: input.documentId,
+                chunkIndex: i,
+                title: input.title,
+                content: chunks[i],
+                metadata: input.metadata,
+                tenantId: input.tenantId,
+                providerName,
+                vector,
+            });
+        }
+
+        return {
+            documentId: input.documentId,
+            chunkCount: chunks.length,
+            totalTokens,
+        };
+    }
+
+    /** 유사 문서를 검색한다 */
+    async searchSimilar(input: SearchInput): Promise<SearchResult[]> {
+        const provider = input.providerName || this.svc.defaultProviderName();
+        const queryVec = await this.svc.embedOne(provider, input.query);
+
+        const topK = input.topK || 5;
+        const minScore = input.minScore || 0.7;
+
+        return this.index.search(
+            queryVec,
+            topK,
+            minScore,
+            input.tenantId,
+            input.metadata,
+        );
+    }
+
+    /** 문서를 삭제한다 */
+    async deleteDocument(documentId: string): Promise<void> {
+        // DB에서 해당 문서의 청크 삭제 (소프트 삭제)
+        try {
+            const resp = await entityServer.list("llm_document", {
+                document_id: documentId,
+                limit: 1000,
+            } as any);
+            const rows = (resp.data as any)?.items ?? [];
+            for (const row of rows) {
+                const seq = Number(row.seq);
+                if (seq > 0) {
+                    await entityServer.submit("llm_document", {
+                        seq,
+                        status: "deleted",
+                    });
+                }
+            }
+        } catch (err) {
+            logger.error(
+                { err },
+                `Failed to delete document chunks: ${documentId}`,
+            );
+        }
+        this.index.deleteByDocumentId(documentId);
+    }
+
+    /** 문서 목록을 조회한다 */
+    async listDocuments(filter: DocumentFilter): Promise<DocumentSummary[]> {
+        const opts: Record<string, unknown> = {
+            chunk_index: 0, // 첫 번째 청크만 조회
+            page: Math.floor(filter.offset / Math.max(filter.limit, 1)) + 1,
+            limit: filter.limit || 50,
+        };
+        if (filter.tenantId) opts.tenant_id = filter.tenantId;
+        if (filter.contentType) opts.content_type = filter.contentType;
+
+        const resp = await entityServer.list("llm_document", opts);
+        const rows = (resp.data as any)?.items ?? [];
+
+        return rows.map((row: Record<string, unknown>) => {
+            let meta: Record<string, string> | undefined;
+            try {
+                if (row.metadata) meta = JSON.parse(String(row.metadata));
+            } catch {
+                /* empty */
+            }
+
+            return {
+                documentId: String(row.document_id ?? ""),
+                title: String(row.title ?? ""),
+                contentType: String(row.content_type ?? ""),
+                chunkCount: 0, // 간단화 — 별도 쿼리 필요 시 추후 보강
+                metadata: meta,
+                createdAt: String(row.created_time ?? ""),
+                updatedAt: String(row.updated_time ?? ""),
+            };
+        });
+    }
+
+    /** DB에서 인메모리 인덱스를 재구축한다 */
+    async rebuildIndex(): Promise<void> {
+        const resp = await entityServer.list("llm_document", { limit: 100000 });
+        const rows = (resp.data as any)?.items ?? [];
+
+        const newChunks: VectorChunk[] = [];
+        for (const row of rows) {
+            let vec: number[] = [];
+            let meta: Record<string, string> | undefined;
+            try {
+                if (row.vector) vec = JSON.parse(String(row.vector));
+            } catch {
+                /* empty */
+            }
+            try {
+                if (row.metadata) meta = JSON.parse(String(row.metadata));
+            } catch {
+                /* empty */
+            }
+
+            newChunks.push({
+                documentId: String(row.document_id ?? ""),
+                chunkIndex: Number(row.chunk_index ?? 0),
+                title: String(row.title ?? ""),
+                content: String(row.content ?? ""),
+                metadata: meta,
+                tenantId: String(row.tenant_id ?? ""),
+                providerName: String(row.provider_name ?? ""),
+                vector: vec,
+            });
+        }
+
+        this.index.replaceAll(newChunks);
+        logger.info(`RAG index rebuilt: ${newChunks.length} chunks`);
+    }
+}
+
+// ─── Utility ─────────────────────────────────────────────────────────────────
+
+/** 코사인 유사도를 계산한다 */
+function cosineSimilarity(a: number[], b: number[]): number {
+    if (a.length !== b.length || a.length === 0) return 0;
+
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+
+    if (normA === 0 || normB === 0) return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+/** 메타데이터 필터 일치 여부를 확인한다 */
+function matchesMetadata(
+    chunkMeta: Record<string, string> | undefined,
+    filterMeta: Record<string, string>,
+): boolean {
+    if (!chunkMeta) return false;
+    for (const [k, v] of Object.entries(filterMeta)) {
+        if (chunkMeta[k] !== v) return false;
+    }
+    return true;
+}

package/src/app/plugins/llm/entities/llm_chatbot.json

@@ -0,0 +1,66 @@
+{
+    "name": "llm_chatbot",
+    "description": "챗봇 정의. 페르소나·프로바이더·RAG 설정을 저장한다. 실제 대화는 llm_conversation에 chatbot_seq로 연결.",
+    "fields": {
+        "name": {
+            "index": true,
+            "comment": "챗봇 식별 이름 (URL에서 사용, 영문+숫자+하이픈)",
+            "type": "varchar(100)",
+            "required": true
+        },
+        "label": {
+            "comment": "사용자에게 표시할 이름",
+            "type": "varchar(200)",
+            "required": true
+        },
+        "system_msg": {
+            "type": "text",
+            "comment": "챗봇 페르소나 시스템 프롬프트 (RAG 컨텍스트가 이 뒤에 자동 삽입됨)",
+            "nullable": true
+        },
+        "welcome_message": {
+            "type": "text",
+            "comment": "대화 시작 시 첫 번째로 표시할 안내 메시지",
+            "nullable": true
+        },
+        "provider_name": {
+            "index": true,
+            "comment": "사용할 LLM 프로바이더 이름. 비어있으면 config.json default 사용",
+            "type": "varchar(50)",
+            "nullable": true
+        },
+        "rag_enabled": {
+            "index": true,
+            "comment": "RAG 기반 문서 검색 활성화 여부",
+            "type": "bool",
+            "default": false
+        },
+        "rag_tenant_id": {
+            "index": true,
+            "comment": "RAG 문서 격리용 테넌트 ID. 비어있으면 전체 문서 대상",
+            "type": "varchar(100)",
+            "nullable": true
+        },
+        "rag_top_k": {
+            "comment": "RAG 검색 시 가져올 문서 청크 수",
+            "type": "int",
+            "default": 5
+        },
+        "rag_min_score": {
+            "comment": "RAG 유사도 임계값 (0~1). 미만이면 미사용",
+            "type": "float",
+            "default": 0.7
+        },
+        "rag_metadata": {
+            "type": "json",
+            "comment": "RAG 검색 필터 메타데이터 ({category: '...', tags: '...'} 형식)",
+            "nullable": true
+        },
+        "status": {
+            "index": true,
+            "comment": "챗봇 상태",
+            "type": ["active", "inactive"],
+            "default": "active"
+        }
+    }
+}

package/src/app/plugins/llm/entities/llm_conversation.json

@@ -0,0 +1,61 @@
+{
+    "name": "llm_conversation",
+    "description": "LLM 멀티턴 대화 세션. 챗봇 히스토리 저장 및 복원용.",
+    "fields": {
+        "user_seq": {
+            "index": true,
+            "comment": "대화 소유 사용자",
+            "required": true
+        },
+        "provider_name": {
+            "index": true,
+            "comment": "LLM 프로바이더 이름 (llm.json 키)",
+            "type": "varchar(50)",
+            "required": true
+        },
+        "title": {
+            "index": true,
+            "comment": "대화 제목 (첫 메시지 요약 또는 사용자 지정)",
+            "type": "varchar(200)",
+            "required": true
+        },
+        "status": {
+            "index": true,
+            "comment": "대화 상태",
+            "type": ["active", "archived"],
+            "default": "active"
+        },
+        "message_count": {
+            "index": true,
+            "index_only": true,
+            "comment": "총 메시지 수 (user + assistant)",
+            "type": "int",
+            "default": 0
+        },
+        "total_tokens": {
+            "index": true,
+            "index_only": true,
+            "comment": "누적 토큰 사용량",
+            "type": "int",
+            "default": 0
+        },
+        "system_msg": {
+            "type": "text",
+            "nullable": true,
+            "comment": "세션 고정 시스템 프롬프트"
+        },
+        "messages": {
+            "type": "json",
+            "comment": "대화 메시지 배열 [{role, content}, ...]"
+        },
+        "last_message": {
+            "type": "string",
+            "nullable": true,
+            "comment": "마지막 메시지 요약 (목록 표시용)"
+        },
+        "model": {
+            "type": "varchar(100)",
+            "comment": "사용된 모델명"
+        }
+    }
+}