create-entity-app-server 0.0.3

package/src/app/plugins/llm/template-loader.ts

@@ -0,0 +1,135 @@
+/**
+ * LLM 프롬프트 템플릿 로더
+ *
+ * templates/llm/prompts/*.json 을 읽어 캐시하고,
+ * {{variable}} 패턴을 변수 맵으로 치환해 렌더링한다.
+ */
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ─── 타입 ──────────────────────────────────────────────────────────────────
+
+export interface LlmPromptTemplate {
+    /** 식별자 (파일명 기준, 확장자 제외) */
+    name: string;
+    /** 사람이 읽기 좋은 이름 */
+    label?: string;
+    /** 시스템 프롬프트. {{var}} 치환 지원 */
+    system_msg: string;
+    /**
+     * 사용자 메시지 템플릿. {{var}} 치환 지원.
+     * 없으면 클라이언트가 직접 messages를 전달해야 한다.
+     */
+    user_msg?: string;
+    /** 필수 변수 이름 목록 */
+    variables?: string[];
+    /** 변수 기본값 */
+    defaults?: Record<string, string>;
+    /** 최대 출력 토큰 (템플릿 오버라이드) */
+    max_tokens?: number;
+    /** temperature (템플릿 오버라이드) */
+    temperature?: number;
+}
+
+export interface RenderedTemplate {
+    system: string;
+    userMsg: string | null;
+    maxTokens?: number;
+    temperature?: number;
+}
+
+// ─── 캐시 ──────────────────────────────────────────────────────────────────
+
+const cache = new Map<string, LlmPromptTemplate>();
+
+function templateDir(): string {
+    return join(__dirname, "templates", "prompts");
+}
+
+// ─── 공개 API ──────────────────────────────────────────────────────────────
+
+/**
+ * 템플릿을 이름으로 로드한다. 서버 재시작 없이 파일 변경을 반영하려면
+ * `reload = true`를 전달한다.
+ */
+export function loadTemplate(
+    name: string,
+    reload = false,
+): LlmPromptTemplate | null {
+    if (!reload) {
+        const cached = cache.get(name);
+        if (cached) return cached;
+    }
+
+    // 경로 검증 (path traversal 방지)
+    if (!/^[\w\-./]+$/.test(name)) return null;
+
+    const filePath = resolve(templateDir(), `${name}.json`);
+    if (!existsSync(filePath)) return null;
+
+    try {
+        const tpl = JSON.parse(
+            readFileSync(filePath, "utf-8"),
+        ) as LlmPromptTemplate;
+        cache.set(name, tpl);
+        return tpl;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * 등록된 모든 템플릿 이름 목록을 반환한다.
+ * (templates/llm/prompts/*.json 스캔)
+ */
+export function listTemplates(): string[] {
+    const dir = templateDir();
+    if (!existsSync(dir)) return [];
+    try {
+        return readdirSync(dir)
+            .filter((f) => f.endsWith(".json"))
+            .map((f) => f.slice(0, -5));
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * 템플릿의 `system_msg`와 `user_msg`에 변수를 주입해 렌더링한다.
+ *
+ * @param tpl    로드된 템플릿
+ * @param vars   클라이언트가 전달한 변수 맵
+ */
+export function renderTemplate(
+    tpl: LlmPromptTemplate,
+    vars: Record<string, string>,
+): RenderedTemplate {
+    const merged = { ...(tpl.defaults ?? {}), ...vars };
+
+    const render = (s: string): string =>
+        s.replace(/\{\{(\w+)\}\}/g, (_, key) => merged[key] ?? "");
+
+    return {
+        system: render(tpl.system_msg),
+        userMsg: tpl.user_msg ? render(tpl.user_msg) : null,
+        maxTokens: tpl.max_tokens,
+        temperature: tpl.temperature,
+    };
+}
+
+/**
+ * 필수 변수 누락 여부를 검사한다.
+ * 누락된 변수 이름 배열을 반환한다. 비어있으면 OK.
+ */
+export function validateVars(
+    tpl: LlmPromptTemplate,
+    vars: Record<string, string>,
+): string[] {
+    if (!tpl.variables?.length) return [];
+    const merged = { ...(tpl.defaults ?? {}), ...vars };
+    return tpl.variables.filter((v) => !merged[v]);
+}

package/src/app/plugins/llm/templates/prompts/extract_json.json

@@ -0,0 +1,8 @@
+{
+    "name": "extract_json",
+    "label": "JSON 추출",
+    "system_msg": "당신은 비정형 텍스트에서 구조화된 데이터를 추출하는 AI입니다. 주어진 JSON 스키마에 정확히 맞는 JSON만 출력하세요. 찾을 수 없는 필드는 빈 문자열로 반환하세요.",
+    "user_msg": "아래 텍스트에서 정보를 추출하여 다음 JSON 스키마에 맞게 응답하세요.\n\n[텍스트]\n{{text}}\n\n[출력 스키마]\n{{schema}}\n\nJSON만 출력하세요.",
+    "variables": ["text", "schema"],
+    "defaults": {}
+}

package/src/app/plugins/llm/templates/prompts/summarize.json

@@ -0,0 +1,10 @@
+{
+    "name": "summarize",
+    "label": "텍스트 요약",
+    "system_msg": "당신은 전문 텍스트 요약 AI입니다. 핵심 정보만 간결하게 요약하세요.",
+    "user_msg": "아래 텍스트를 {{max_sentences}}문장 이내로 요약하세요.\n\n[텍스트]\n{{text}}\n\n요약만 출력하세요.",
+    "variables": ["text", "max_sentences"],
+    "defaults": {
+        "max_sentences": "3"
+    }
+}

package/src/app/plugins/llm/templates/prompts/translate.json

@@ -0,0 +1,10 @@
+{
+    "name": "translate",
+    "label": "번역",
+    "system_msg": "당신은 전문 번역 AI입니다. 원문의 의미를 정확하게 보존하면서 자연스럽게 번역하세요.",
+    "user_msg": "아래 텍스트를 {{target_lang}}로 번역하세요.\n\n[원문]\n{{text}}\n\n번역문만 출력하세요.",
+    "variables": ["text", "target_lang"],
+    "defaults": {
+        "target_lang": "한국어"
+    }
+}

package/src/app/plugins/llm/types/chat.ts

@@ -0,0 +1,96 @@
+import type { LlmProviderConfig } from "./config.ts";
+
+export interface Message {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+
+export interface ChatRequest {
+    messages: Message[];
+    system?: string;
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    jsonMode?: boolean;
+    stop?: string[];
+}
+
+export interface ChatResponse {
+    content: string;
+    finishReason: string;
+    model: string;
+    usage?: TokenUsage;
+    cached?: boolean;
+}
+
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+
+export interface StreamChunk {
+    content: string;
+    done: boolean;
+    finishReason?: string;
+    usage?: TokenUsage;
+}
+
+export interface EmbedRequest {
+    input: string[];
+    model?: string;
+}
+
+export interface EmbedResponse {
+    embeddings: number[][];
+    model: string;
+    totalTokens: number;
+}
+
+export interface LlmClient {
+    name(): string;
+    chat(req: ChatRequest, signal?: AbortSignal): Promise<ChatResponse>;
+    chatStream(
+        req: ChatRequest,
+        signal?: AbortSignal,
+    ): AsyncGenerator<StreamChunk>;
+    embed(req: EmbedRequest, signal?: AbortSignal): Promise<EmbedResponse>;
+    close(): void;
+}
+
+export interface Provider {
+    name: string;
+    client: LlmClient;
+    config: LlmProviderConfig;
+    rateLimiter: RateLimiter;
+}
+
+export interface RateLimiter {
+    tryAcquire(): boolean;
+}
+
+export type ChatOption = (req: ChatRequest) => void;
+
+export function withSystem(system: string): ChatOption {
+    return (req) => {
+        req.system = system;
+    };
+}
+
+export function withTemperature(temp: number): ChatOption {
+    return (req) => {
+        req.temperature = temp;
+    };
+}
+
+export function withMaxTokens(n: number): ChatOption {
+    return (req) => {
+        req.maxTokens = n;
+    };
+}
+
+export function withJsonMode(): ChatOption {
+    return (req) => {
+        req.jsonMode = true;
+    };
+}

package/src/app/plugins/llm/types/chatbot.ts

@@ -0,0 +1,143 @@
+import type { Message, TokenUsage } from "./chat.ts";
+import type { SearchResult } from "./conversation.ts";
+
+// ─── Chatbot 정의 ─────────────────────────────────────────────────────────────
+
+export interface Chatbot {
+    seq: number;
+    name: string;
+    label: string;
+    systemMsg?: string;
+    welcomeMessage?: string;
+    /** 지정 없으면 LlmConfig.default 사용 */
+    providerName?: string;
+    ragEnabled: boolean;
+    ragTenantId?: string;
+    ragTopK: number;
+    ragMinScore: number;
+    ragMetadata?: Record<string, string>;
+    status: "active" | "inactive";
+    createdAt: string;
+}
+
+export interface ChatbotSummary {
+    seq: number;
+    name: string;
+    label: string;
+    ragEnabled: boolean;
+    status: string;
+    createdAt: string;
+}
+
+export interface ChatbotCreateInput {
+    name: string;
+    label: string;
+    systemMsg?: string;
+    welcomeMessage?: string;
+    providerName?: string;
+    ragEnabled?: boolean;
+    ragTenantId?: string;
+    ragTopK?: number;
+    ragMinScore?: number;
+    ragMetadata?: Record<string, string>;
+}
+
+export interface ChatbotUpdateInput {
+    label?: string;
+    systemMsg?: string;
+    welcomeMessage?: string;
+    providerName?: string;
+    ragEnabled?: boolean;
+    ragTenantId?: string;
+    ragTopK?: number;
+    ragMinScore?: number;
+    ragMetadata?: Record<string, string>;
+    status?: "active" | "inactive";
+}
+
+// ─── Chatbot 세션 ─────────────────────────────────────────────────────────────
+
+/** 챗봇에 귀속된 대화 세션 요약 (llm_conversation 기반) */
+export interface ChatbotSessionSummary {
+    sessionSeq: number;
+    chatbotSeq: number;
+    title: string;
+    messageCount: number;
+    totalTokens: number;
+    lastMessage: string;
+    updatedAt: string;
+}
+
+export interface ChatbotSessionFilter {
+    chatbotSeq: number;
+    userSeq?: number;
+    sessionId?: string;
+    limit: number;
+    offset: number;
+}
+
+// ─── Chat 요청/응답 ────────────────────────────────────────────────────────────
+
+export interface ChatbotChatInput {
+    chatbotSeq: number;
+    /** 0 또는 미지정이면 새 세션 생성 */
+    sessionSeq?: number;
+    message: string;
+    userSeq?: number;
+    /** 비로그인 사용자 추적용 임의 ID */
+    sessionId?: string;
+}
+
+export interface ChatbotChatResponse {
+    sessionSeq: number;
+    content: string;
+    /** RAG 검색 결과 (rag_enabled=true 일 때만 포함) */
+    sources?: SearchResult[];
+    model: string;
+    usage?: TokenUsage;
+    /** 이번 요청으로 새 세션이 생성됐는지 여부 */
+    isNewSession: boolean;
+}
+
+// ─── Store 인터페이스 ──────────────────────────────────────────────────────────
+
+export interface ChatbotStore {
+    /** 챗봇 정의를 seq로 조회한다 */
+    getChatbot(seq: number): Promise<Chatbot>;
+    /** 챗봇 정의를 name으로 조회한다 */
+    getChatbotByName(name: string): Promise<Chatbot | null>;
+    /** 챗봇 목록을 조회한다 */
+    listChatbots(): Promise<ChatbotSummary[]>;
+    /** 챗봇을 생성한다 */
+    createChatbot(input: ChatbotCreateInput): Promise<number>;
+    /** 챗봇 설정을 수정한다 */
+    updateChatbot(seq: number, input: ChatbotUpdateInput): Promise<void>;
+    /** 챗봇을 삭제한다 */
+    deleteChatbot(seq: number): Promise<void>;
+
+    /** 챗봇 세션을 생성한다 (llm_conversation 기반) */
+    createSession(
+        chatbotSeq: number,
+        providerName: string,
+        title: string,
+        userSeq?: number,
+        sessionId?: string,
+        systemMsg?: string,
+    ): Promise<number>;
+    /** 세션의 메시지 배열과 시스템 메시지를 포함해 조회한다 */
+    getSessionMessages(
+        sessionSeq: number,
+    ): Promise<{ messages: Message[]; systemMsg: string }>;
+    /** 세션에 메시지를 추가하고 토큰 누계를 업데이트한다 */
+    appendSessionMessages(
+        sessionSeq: number,
+        messages: Message[],
+        usage?: { totalTokens?: number },
+    ): Promise<void>;
+    /** 챗봇에 귀속된 세션 목록을 조회한다 */
+    listSessions(
+        filter: ChatbotSessionFilter,
+    ): Promise<ChatbotSessionSummary[]>;
+    /** 세션을 삭제한다 */
+    deleteSession(sessionSeq: number): Promise<void>;
+}

package/src/app/plugins/llm/types/config.ts

@@ -0,0 +1,47 @@
+export interface LlmConfig {
+    enabled?: boolean;
+    default: string;
+    usage_tracking: boolean;
+    providers: Record<string, LlmProviderConfig>;
+    quota?: LlmQuotaConfig;
+    rag?: LlmRAGConfig;
+    cache?: LlmCacheConfig;
+}
+
+export interface LlmProviderConfig {
+    driver: string; // LLM 드라이버 종류: cloud=openai|anthropic|gemini|azure_openai|groq|together|deepseek|mistral|perplexity, local=ollama|vllm|localai|lmstudio|llamacpp|koboldcpp|text_generation_webui|jan|xinference|tabbyapi|openwebui
+    api_key?: string;
+    base_url?: string;
+    api_version?: string; // Azure OpenAI 전용: API 버전 (예: "2024-12-01-preview")
+    model: string;
+    max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    json_mode?: boolean;
+    timeout_sec?: number;
+    rate_limit_rpm?: number;
+    embed_model?: string;
+    description?: string;
+}
+
+export interface LlmQuotaConfig {
+    daily_token_limit?: number;
+    monthly_token_limit?: number;
+    notify?: string[]; // log | smtp | alimtalk
+}
+
+export interface LlmRAGConfig {
+    enabled?: boolean;
+    embed_provider?: string;
+    default_chunk_size?: number;
+    default_chunk_overlap?: number;
+    default_top_k?: number;
+    default_min_score?: number;
+}
+
+export interface LlmCacheConfig {
+    enabled: boolean;
+    ttl_seconds: number;
+    max_entries?: number;
+    exclude_providers?: string[];
+}

package/src/app/plugins/llm/types/conversation.ts

@@ -0,0 +1,116 @@
+import type { Message, TokenUsage } from "./chat.ts";
+
+export interface Conversation {
+    seq: number;
+    providerName: string;
+    title: string;
+    systemMsg?: string;
+    messages: Message[];
+    totalTokens: number;
+    userSeq?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface ConversationSummary {
+    seq: number;
+    title: string;
+    providerName: string;
+    messageCount: number;
+    totalTokens: number;
+    lastMessage: string;
+    updatedAt: string;
+}
+
+export interface ConversationCreateInput {
+    providerName: string;
+    title: string;
+    systemMsg?: string;
+    userSeq?: number;
+}
+
+export interface ConversationFilter {
+    userSeq?: number;
+    providerName?: string;
+    limit: number;
+    offset: number;
+}
+
+export interface ConversationResponse {
+    conversationSeq: number;
+    content: string;
+    finishReason: string;
+    usage?: TokenUsage;
+    model: string;
+}
+
+export interface RAGOptions {
+    systemMsg?: string;
+    embedProvider?: string;
+    topK?: number;
+    minScore?: number;
+    metadata?: Record<string, string>;
+    tenantId?: string;
+}
+
+export interface RAGResponse {
+    content: string;
+    finishReason: string;
+    usage?: TokenUsage;
+    model: string;
+    sources: SearchResult[];
+}
+
+export interface DocumentIngestInput {
+    documentId: string;
+    title: string;
+    content: string;
+    contentType?: string;
+    metadata?: Record<string, string>;
+    providerName?: string;
+    chunkSize?: number;
+    chunkOverlap?: number;
+    tenantId?: string;
+}
+
+export interface DocumentIngestResult {
+    documentId: string;
+    chunkCount: number;
+    totalTokens: number;
+}
+
+export interface SearchInput {
+    query: string;
+    providerName?: string;
+    topK?: number;
+    minScore?: number;
+    metadata?: Record<string, string>;
+    tenantId?: string;
+}
+
+export interface SearchResult {
+    documentId: string;
+    chunkIndex: number;
+    content: string;
+    score: number;
+    title: string;
+    metadata?: Record<string, string>;
+}
+
+export interface DocumentSummary {
+    documentId: string;
+    title: string;
+    contentType?: string;
+    chunkCount: number;
+    metadata?: Record<string, string>;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface DocumentFilter {
+    tenantId?: string;
+    contentType?: string;
+    metadata?: Record<string, string>;
+    limit: number;
+    offset: number;
+}

package/src/app/plugins/llm/types/index.ts

@@ -0,0 +1,7 @@
+export * from "./config.ts";
+export * from "./chat.ts";
+export * from "./conversation.ts";
+export * from "./chatbot.ts";
+export * from "./usage.ts";
+export * from "./store.ts";
+export * from "./profile.ts";

package/src/app/plugins/llm/types/profile.ts

@@ -0,0 +1,48 @@
+// ─── Profile Memory 타입 ────────────────────────────────────────────────────
+
+export interface UserProfileEntry {
+    seq: number;
+    userSeq: number;
+    scope: string;
+    chatbotSeq?: number;
+    key: string;
+    value: string;
+    source: "manual" | "extracted";
+    status: "active" | "inactive";
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface UserProfileUpsertInput {
+    userSeq: number;
+    key: string;
+    value: string;
+    scope?: string;
+    chatbotSeq?: number;
+    source?: "manual" | "extracted";
+}
+
+export interface UserProfileFilter {
+    userSeq: number;
+    scope?: string;
+    chatbotSeq?: number;
+    /** inactive 포함 여부 (기본: false) */
+    includeInactive?: boolean;
+}
+
+export interface ProfileStore {
+    /** 특정 사용자의 활성 메모리 항목을 조회한다 */
+    getProfiles(filter: UserProfileFilter): Promise<UserProfileEntry[]>;
+
+    /** 메모리 항목을 upsert한다 (user_seq + scope + key 기준) */
+    upsertProfile(input: UserProfileUpsertInput): Promise<number>;
+
+    /** 메모리 항목을 비활성화(soft-delete)한다 */
+    deactivateProfile(seq: number, userSeq: number): Promise<void>;
+
+    /** 메모리 항목을 삭제한다 */
+    deleteProfile(seq: number, userSeq: number): Promise<void>;
+
+    /** 사용자의 활성 메모리를 system prompt 삽입용 문자열로 포맷한다 */
+    formatForPrompt(filter: UserProfileFilter): Promise<string>;
+}

package/src/app/plugins/llm/types/store.ts

@@ -0,0 +1,50 @@
+import type {
+    Message,
+    TokenUsage,
+    ChatRequest,
+    ChatResponse,
+    StreamChunk,
+    EmbedRequest,
+    EmbedResponse,
+} from "./chat.ts";
+import type {
+    Conversation,
+    ConversationSummary,
+    ConversationCreateInput,
+    ConversationFilter,
+    DocumentIngestInput,
+    DocumentIngestResult,
+    SearchInput,
+    SearchResult,
+    DocumentSummary,
+    DocumentFilter,
+} from "./conversation.ts";
+import type { LlmUsageRecord, UsageFilter, UsageSummary } from "./usage.ts";
+
+export interface ConversationStore {
+    createConversation(input: ConversationCreateInput): Promise<number>;
+    getConversation(conversationSeq: number): Promise<Conversation>;
+    appendMessages(
+        conversationSeq: number,
+        messages: Message[],
+        usage?: TokenUsage,
+    ): Promise<void>;
+    listConversations(
+        filter: ConversationFilter,
+    ): Promise<ConversationSummary[]>;
+    deleteConversation(conversationSeq: number): Promise<void>;
+    updateTitle(conversationSeq: number, title: string): Promise<void>;
+}
+
+export interface DocumentStore {
+    ingestDocument(input: DocumentIngestInput): Promise<DocumentIngestResult>;
+    searchSimilar(input: SearchInput): Promise<SearchResult[]>;
+    deleteDocument(documentId: string): Promise<void>;
+    listDocuments(filter: DocumentFilter): Promise<DocumentSummary[]>;
+    rebuildIndex(): Promise<void>;
+}
+
+export interface UsageQuerier {
+    recordUsage(record: LlmUsageRecord): Promise<void>;
+    getUsageSummary(filter: UsageFilter): Promise<UsageSummary>;
+}