viruagent 1.0.1 → 1.2.0

package/docs/hybrid-db-agent-guide.md

@@ -0,0 +1,484 @@
+# 하이브리드 DB 에이전트 설계 가이드
+
+자연어로 데이터베이스를 조회하는 AI 에이전트의 스키마 관리 전략.
+
+**캐싱(부팅 시 스키마 로드)** + **도구(상세 조회)**를 조합하여 정확도와 성능을 모두 확보한다.
+
+---
+
+## 1. 전체 아키텍처
+
+```
+[서버 부팅]
+  └── DB에서 스키마 캐싱 (테이블, 컬럼, FK 관계)
+        ↓
+[사용자 요청] "이번 달 매출 상위 고객 보여줘"
+        ↓
+[시스템 프롬프트]
+  ├── 캐싱된 스키마 요약 (항상 포함)
+  └── "상세 정보가 필요하면 get_schema 도구를 사용하라"
+        ↓
+[에이전트 루프]
+  ├── AI가 캐싱된 스키마로 충분하면 → 바로 query_database 호출
+  └── 컬럼 타입, 제약조건 등 상세 필요하면 → get_schema 먼저 호출
+        ↓
+[결과 반환] "매출 상위 고객은 ..."
+```
+
+---
+
+## 2. 스키마 캐싱 (서버 부팅 시)
+
+서버가 시작될 때 한 번 DB에서 스키마 정보를 읽어 메모리에 저장한다.
+
+### 2-1. 캐싱 쿼리
+
+```js
+const loadSchema = async (client) => {
+  // 테이블 + 컬럼 정보
+  const columns = await client.query(`
+    SELECT table_name, column_name, data_type, is_nullable,
+           column_default
+    FROM information_schema.columns
+    WHERE table_schema = 'public'
+    ORDER BY table_name, ordinal_position
+  `);
+
+  // FK 관계
+  const fks = await client.query(`
+    SELECT
+      tc.table_name  AS from_table,
+      kcu.column_name AS from_column,
+      ccu.table_name  AS to_table,
+      ccu.column_name AS to_column
+    FROM information_schema.table_constraints tc
+    JOIN information_schema.key_column_usage kcu
+      ON tc.constraint_name = kcu.constraint_name
+    JOIN information_schema.constraint_column_usage ccu
+      ON tc.constraint_name = ccu.constraint_name
+    WHERE tc.constraint_type = 'FOREIGN KEY'
+      AND tc.table_schema = 'public'
+  `);
+
+  // 테이블별 그룹핑
+  const grouped = {};
+  for (const row of columns.rows) {
+    if (!grouped[row.table_name]) grouped[row.table_name] = [];
+    grouped[row.table_name].push(`${row.column_name} (${row.data_type})`);
+  }
+
+  // 텍스트로 변환
+  let schema = '## 테이블 스키마\n';
+  schema += Object.entries(grouped)
+    .map(([table, cols]) => `- ${table}: ${cols.join(', ')}`)
+    .join('\n');
+
+  if (fks.rows.length > 0) {
+    schema += '\n\n## 관계 (FK)\n';
+    schema += fks.rows
+      .map(r => `- ${r.from_table}.${r.from_column} → ${r.to_table}.${r.to_column}`)
+      .join('\n');
+  }
+
+  return schema;
+};
+```
+
+### 2-2. 캐싱 결과 예시
+
+```
+## 테이블 스키마
+- users: id (integer), email (varchar), name (varchar), role (varchar), created_at (timestamp)
+- orders: id (integer), user_id (integer), total (numeric), status (varchar), created_at (timestamp)
+- products: id (integer), name (varchar), price (numeric), category (varchar), stock (integer)
+- order_items: id (integer), order_id (integer), product_id (integer), quantity (integer), price (numeric)
+
+## 관계 (FK)
+- orders.user_id → users.id
+- order_items.order_id → orders.id
+- order_items.product_id → products.id
+```
+
+AI는 이것만 보고도 대부분의 JOIN 쿼리를 정확하게 생성할 수 있다.
+
+### 2-3. 캐시 갱신
+
+```js
+// 서버 시작 시
+let schemaCache = await loadSchema(client);
+
+// 주기적 갱신 (선택)
+setInterval(async () => {
+  schemaCache = await loadSchema(client);
+}, 1000 * 60 * 30); // 30분마다
+
+// 수동 갱신 API (어드민용)
+app.post('/api/admin/refresh-schema', async (req, res) => {
+  schemaCache = await loadSchema(client);
+  res.json({ success: true });
+});
+```
+
+---
+
+## 3. 도구 정의
+
+### 3-1. tools 배열
+
+```js
+const tools = [
+  {
+    type: 'function',
+    function: {
+      name: 'query_database',
+      description: 'PostgreSQL에 SELECT 쿼리를 실행합니다. READ ONLY. 결과는 최대 100행.',
+      parameters: {
+        type: 'object',
+        properties: {
+          sql: { type: 'string', description: 'SELECT 쿼리문' },
+        },
+        required: ['sql'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'get_schema',
+      description: '특정 테이블의 상세 스키마를 조회합니다. 컬럼 타입, 기본값, NOT NULL, 인덱스, 코멘트 등 캐싱된 요약보다 상세한 정보가 필요할 때 사용하세요.',
+      parameters: {
+        type: 'object',
+        properties: {
+          table_name: { type: 'string', description: '조회할 테이블명' },
+        },
+        required: ['table_name'],
+      },
+    },
+  },
+];
+```
+
+### 3-2. AI의 판단 기준
+
+| 상황 | AI 행동 |
+|------|---------|
+| "주문 많은 고객 보여줘" | 캐시에 users, orders, FK 있음 → 바로 `query_database` |
+| "users 테이블에 soft delete 있어?" | 캐시만으론 모름 → `get_schema("users")` 먼저 |
+| "인덱스 걸린 컬럼이 뭐야?" | 캐시에 없음 → `get_schema` 호출 |
+
+---
+
+## 4. Tool Executor
+
+### 4-1. query_database
+
+```js
+const executeQuery = async (sql, client) => {
+  // 1차: SQL 파싱 검증
+  const normalized = sql.trim().toUpperCase();
+  if (!normalized.startsWith('SELECT') && !normalized.startsWith('WITH')) {
+    return { error: 'SELECT / WITH 쿼리만 허용됩니다.' };
+  }
+
+  const blocked = ['INSERT', 'UPDATE', 'DELETE', 'DROP', 'ALTER', 'TRUNCATE', 'CREATE', 'GRANT', 'REVOKE'];
+  for (const kw of blocked) {
+    // SELECT 뒤에 나오는 서브쿼리 내 키워드도 체크
+    if (normalized.includes(kw + ' ')) {
+      return { error: `${kw} 키워드가 포함된 쿼리는 실행할 수 없습니다.` };
+    }
+  }
+
+  // 2차: read-only 트랜잭션
+  try {
+    await client.query('BEGIN READ ONLY');
+    const result = await client.query(sql);
+    await client.query('COMMIT');
+
+    return {
+      columns: result.fields.map(f => f.name),
+      rows: result.rows.slice(0, 100),
+      totalRows: result.rowCount,
+      truncated: result.rowCount > 100,
+    };
+  } catch (e) {
+    await client.query('ROLLBACK');
+    return { error: `쿼리 실행 오류: ${e.message}` };
+  }
+};
+```
+
+### 4-2. get_schema (상세 조회)
+
+```js
+const getDetailedSchema = async (tableName, client) => {
+  // 컬럼 상세
+  const columns = await client.query(`
+    SELECT
+      c.column_name,
+      c.data_type,
+      c.character_maximum_length,
+      c.is_nullable,
+      c.column_default,
+      pgd.description AS comment
+    FROM information_schema.columns c
+    LEFT JOIN pg_catalog.pg_description pgd
+      ON pgd.objsubid = c.ordinal_position
+      AND pgd.objoid = (SELECT oid FROM pg_class WHERE relname = $1)
+    WHERE c.table_name = $1 AND c.table_schema = 'public'
+    ORDER BY c.ordinal_position
+  `, [tableName]);
+
+  // 인덱스
+  const indexes = await client.query(`
+    SELECT indexname, indexdef
+    FROM pg_indexes
+    WHERE tablename = $1 AND schemaname = 'public'
+  `, [tableName]);
+
+  // FK (이 테이블에서 나가는)
+  const fksOut = await client.query(`
+    SELECT kcu.column_name, ccu.table_name AS ref_table, ccu.column_name AS ref_column
+    FROM information_schema.table_constraints tc
+    JOIN information_schema.key_column_usage kcu
+      ON tc.constraint_name = kcu.constraint_name
+    JOIN information_schema.constraint_column_usage ccu
+      ON tc.constraint_name = ccu.constraint_name
+    WHERE tc.constraint_type = 'FOREIGN KEY'
+      AND tc.table_name = $1
+  `, [tableName]);
+
+  // FK (이 테이블로 들어오는)
+  const fksIn = await client.query(`
+    SELECT tc.table_name AS from_table, kcu.column_name AS from_column
+    FROM information_schema.table_constraints tc
+    JOIN information_schema.key_column_usage kcu
+      ON tc.constraint_name = kcu.constraint_name
+    JOIN information_schema.constraint_column_usage ccu
+      ON tc.constraint_name = ccu.constraint_name
+    WHERE tc.constraint_type = 'FOREIGN KEY'
+      AND ccu.table_name = $1
+  `, [tableName]);
+
+  return {
+    table: tableName,
+    columns: columns.rows,
+    indexes: indexes.rows,
+    foreignKeysOut: fksOut.rows,
+    foreignKeysIn: fksIn.rows,
+  };
+};
+```
+
+---
+
+## 5. 시스템 프롬프트
+
+```js
+const buildSystemPrompt = (schemaCache) => `
+당신은 데이터베이스 조회 어시스턴트입니다.
+사용자의 자연어 질문을 SQL SELECT 쿼리로 변환하여 실행합니다.
+
+## 규칙
+- SELECT 쿼리만 생성하세요. 데이터 변경은 불가합니다.
+- 결과가 많을 수 있으니 LIMIT을 적절히 사용하세요.
+- 날짜 필터가 모호하면 사용자에게 확인하세요.
+- 쿼리 결과를 사용자가 이해하기 쉽게 요약해서 설명하세요.
+- 상세 스키마 정보(인덱스, 코멘트 등)가 필요하면 get_schema 도구를 사용하세요.
+
+${schemaCache}
+`;
+```
+
+---
+
+## 6. 에이전트 루프
+
+ViruAgent의 `runAgent`와 동일한 구조:
+
+```js
+const runDbAgent = async (userMessage, { schemaCache, client, chatHistory }) => {
+  chatHistory.push({ role: 'user', content: userMessage });
+
+  const messages = [
+    { role: 'system', content: buildSystemPrompt(schemaCache) },
+    ...chatHistory,
+  ];
+
+  const MAX_LOOPS = 10;
+
+  for (let i = 0; i < MAX_LOOPS; i++) {
+    const res = await openai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages,
+      tools,
+      temperature: 0,  // SQL 생성은 정확도 우선
+    });
+
+    const msg = res.choices[0].message;
+    messages.push(msg);
+
+    if (!msg.tool_calls?.length) {
+      chatHistory.push({ role: 'assistant', content: msg.content });
+      return msg.content;
+    }
+
+    for (const tc of msg.tool_calls) {
+      const args = JSON.parse(tc.function.arguments);
+      let result;
+
+      switch (tc.function.name) {
+        case 'query_database':
+          result = await executeQuery(args.sql, client);
+          break;
+        case 'get_schema':
+          result = await getDetailedSchema(args.table_name, client);
+          break;
+        default:
+          result = { error: `알 수 없는 도구: ${tc.function.name}` };
+      }
+
+      messages.push({
+        role: 'tool',
+        tool_call_id: tc.id,
+        content: JSON.stringify(result),
+      });
+    }
+  }
+
+  return '쿼리가 너무 복잡합니다. 질문을 나눠서 요청해주세요.';
+};
+```
+
+---
+
+## 7. 실전 흐름 추적
+
+### 시나리오 1: 단순 조회 (캐시만으로 해결)
+
+```
+사용자: "이번 달 주문 건수 알려줘"
+
+[루프 1]
+  시스템 프롬프트에 캐시된 스키마 포함
+  → AI: orders 테이블에 created_at 있네 → 바로 SQL 생성
+  → tool_calls: query_database
+    sql: "SELECT COUNT(*) as cnt FROM orders WHERE created_at >= '2026-02-01'"
+  → 결과: [{ cnt: 1847 }]
+
+[루프 2]
+  → AI: "이번 달 주문은 총 1,847건입니다."
+  → 루프 종료
+
+총 루프: 2회, get_schema 호출: 0회
+```
+
+### 시나리오 2: 복잡한 조회 (상세 스키마 필요)
+
+```
+사용자: "soft delete된 사용자 중에 주문 있는 사람 보여줘"
+
+[루프 1]
+  → AI: 캐시에 users 테이블은 있지만 soft delete 컬럼이 뭔지 모르겠다
+  → tool_calls: get_schema("users")
+  → 결과: { columns: [..., { column_name: "deleted_at", data_type: "timestamp", is_nullable: "YES" }] }
+
+[루프 2]
+  → AI: deleted_at이 NOT NULL이면 soft delete구나
+  → tool_calls: query_database
+    sql: "SELECT u.name, u.email, COUNT(o.id) as order_count
+          FROM users u
+          JOIN orders o ON o.user_id = u.id
+          WHERE u.deleted_at IS NOT NULL
+          GROUP BY u.id, u.name, u.email"
+  → 결과: [{ name: "김철수", email: "...", order_count: 5 }, ...]
+
+[루프 3]
+  → AI: "soft delete된 사용자 중 주문이 있는 분은 3명입니다: ..."
+  → 루프 종료
+
+총 루프: 3회, get_schema 호출: 1회
+```
+
+---
+
+## 8. 안전장치 요약
+
+```
+┌─────────────────────────────────────────────┐
+│ Layer 1: 시스템 프롬프트                      │
+│  → "SELECT만 생성하라"                        │
+├─────────────────────────────────────────────┤
+│ Layer 2: Tool Executor (SQL 파싱)             │
+│  → SELECT/WITH 외 차단                        │
+│  → INSERT/UPDATE/DELETE/DROP 키워드 감지       │
+├─────────────────────────────────────────────┤
+│ Layer 3: DB 연결                              │
+│  → BEGIN READ ONLY 트랜잭션                   │
+│  → 또는 read replica 연결                     │
+├─────────────────────────────────────────────┤
+│ Layer 4: 결과 제한                            │
+│  → 최대 100행 반환                            │
+│  → 타임아웃 설정 (statement_timeout)           │
+└─────────────────────────────────────────────┘
+```
+
+### DB 레벨 추가 보호 (권장)
+
+```sql
+-- 전용 read-only 유저 생성
+CREATE USER db_agent_readonly WITH PASSWORD '...';
+GRANT CONNECT ON DATABASE mydb TO db_agent_readonly;
+GRANT USAGE ON SCHEMA public TO db_agent_readonly;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO db_agent_readonly;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+  GRANT SELECT ON TABLES TO db_agent_readonly;
+
+-- 쿼리 타임아웃 (느린 쿼리 방지)
+ALTER USER db_agent_readonly SET statement_timeout = '10s';
+```
+
+---
+
+## 9. 토큰 비용
+
+| 항목 | 토큰 수 |
+|------|---------|
+| 시스템 프롬프트 (규칙) | ~200 |
+| 캐싱된 스키마 (10개 테이블) | ~400 |
+| 캐싱된 스키마 (50개 테이블) | ~2,000 |
+| tools 정의 (2개) | ~300 |
+| get_schema 결과 (1회) | ~500 |
+| query_database 결과 (50행) | ~1,000 |
+
+### 테이블이 많을 때 최적화
+
+```js
+// 50개 이상이면 테이블명만 캐싱, 컬럼은 get_schema로
+const loadLightSchema = async (client) => {
+  const tables = await client.query(`
+    SELECT table_name,
+           obj_description(('"' || table_name || '"')::regclass) AS comment
+    FROM information_schema.tables
+    WHERE table_schema = 'public'
+  `);
+
+  return '## 테이블 목록\n' +
+    tables.rows.map(t =>
+      `- ${t.table_name}${t.comment ? ` (${t.comment})` : ''}`
+    ).join('\n') +
+    '\n\n컬럼 정보가 필요하면 get_schema 도구를 사용하세요.';
+};
+```
+
+---
+
+## 10. 하이브리드 방식을 선택한 이유
+
+| 방식 | 장점 | 단점 |
+|------|------|------|
+| 하드코딩 | 빠름, 정확 | 스키마 변경 시 코드 수정 |
+| 도구만 (MCP 방식) | 항상 최신 | 매번 1~2루프 낭비 |
+| 캐싱만 | 빠름, 자동 | 상세 정보 부족 |
+| **하이브리드** | **빠름 + 자동 + 상세** | 구현 약간 복잡 |
+
+하이브리드는 **90%의 쿼리는 캐시로 즉시 처리**하고, **10%의 복잡한 케이스만 도구로 상세 조회**한다. 토큰 절약과 정확도를 동시에 달성하는 최적의 전략이다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viruagent",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "AI 기반 티스토리 블로그 자동 발행 CLI 도구",
   "main": "src/agent.js",
   "bin": {
@@ -30,7 +30,6 @@
   "type": "commonjs",
   "dependencies": {
     "chalk": "^4.1.2",
-    "dotenv": "^16.4.7",
     "oh-my-logo": "^0.4.0",
     "openai": "^4.77.0",
     "playwright": "^1.58.2"