stellavault 0.1.0

package/packages/cli/src/index.ts

@@ -0,0 +1,187 @@
+import { Command } from 'commander';
+import { indexCommand } from './commands/index-cmd.js';
+import { searchCommand } from './commands/search-cmd.js';
+import { serveCommand } from './commands/serve-cmd.js';
+import { statusCommand } from './commands/status-cmd.js';
+import { graphCommand } from './commands/graph-cmd.js';
+import { cardCommand } from './commands/card-cmd.js';
+import { packCreateCommand, packExportCommand, packImportCommand, packListCommand, packInfoCommand } from './commands/pack-cmd.js';
+import { decayCommand } from './commands/decay-cmd.js';
+import { syncCommand } from './commands/sync-cmd.js';
+import { reviewCommand } from './commands/review-cmd.js';
+import { duplicatesCommand } from './commands/duplicates-cmd.js';
+import { gapsCommand } from './commands/gaps-cmd.js';
+import { clipCommand } from './commands/clip-cmd.js';
+import { briefCommand } from './commands/brief-cmd.js';
+import { digestCommand } from './commands/digest-cmd.js';
+import { initCommand } from './commands/init-cmd.js';
+import { learnCommand } from './commands/learn-cmd.js';
+import { contradictionsCommand } from './commands/contradictions-cmd.js';
+import { federateJoinCommand, federateStatusCommand } from './commands/federate-cmd.js';
+import { cloudSyncCommand, cloudRestoreCommand, cloudStatusCommand } from './commands/cloud-cmd.js';
+import { vaultAddCommand, vaultListCommand, vaultRemoveCommand, vaultSearchAllCommand } from './commands/vault-cmd.js';
+import { captureCommand } from './commands/capture-cmd.js';
+
+const program = new Command();
+
+program
+  .name('stellavault')
+  .description('Stellavault — Turn your Obsidian vault into a 3D neural knowledge graph')
+  .version('0.1.0')
+  .option('--json', 'Output in JSON format (for scripting)')
+  .option('--quiet', 'Suppress non-essential output');
+
+program
+  .command('init')
+  .description('Interactive setup wizard — get started in 3 minutes')
+  .action(initCommand);
+
+program
+  .command('index [vault-path]')
+  .description('Obsidian vault를 벡터화하여 인덱싱합니다')
+  .action(indexCommand);
+
+program
+  .command('search <query>')
+  .description('지식 베이스에서 검색합니다')
+  .option('-l, --limit <n>', '결과 수', '5')
+  .action(searchCommand);
+
+program
+  .command('serve')
+  .description('MCP 서버를 시작합니다 (Claude Code 연동)')
+  .action(serveCommand);
+
+program
+  .command('status')
+  .description('인덱스 상태를 확인합니다')
+  .action(statusCommand);
+
+program
+  .command('graph')
+  .description('3D Knowledge Graph API 서버를 시작합니다')
+  .action(graphCommand);
+
+program
+  .command('card')
+  .description('SVG 프로필 카드를 생성합니다')
+  .option('-o, --output <path>', '출력 파일 경로', 'knowledge-card.svg')
+  .action(cardCommand);
+
+program
+  .command('learn')
+  .description('AI learning path — personalized recommendations based on decay + gaps')
+  .action(learnCommand);
+
+program
+  .command('contradictions')
+  .description('Detect contradicting statements across your notes')
+  .action(contradictionsCommand);
+
+program
+  .command('decay')
+  .description('지식 감쇠 리포트를 출력합니다 (잊어가는 노트 확인)')
+  .action(decayCommand);
+
+program
+  .command('brief')
+  .description('오늘의 지식 브리핑 (감쇠 + 갭 + 활동 요약)')
+  .action(briefCommand);
+
+program
+  .command('digest')
+  .description('주간 지식 활동 리포트')
+  .option('-d, --days <n>', '기간 (일)', '7')
+  .action(digestCommand);
+
+program
+  .command('clip <url>')
+  .description('웹 페이지/YouTube를 Obsidian에 클리핑')
+  .option('-f, --folder <path>', 'vault 내 저장 폴더', '06_Research/clips')
+  .action(clipCommand);
+
+program
+  .command('gaps')
+  .description('지식 갭을 탐지합니다 (클러스터 간 연결 부족 영역)')
+  .action(gapsCommand);
+
+program
+  .command('duplicates')
+  .description('중복/유사 노트를 탐지합니다')
+  .option('-t, --threshold <n>', '유사도 임계값 (0~1)', '0.88')
+  .action(duplicatesCommand);
+
+program
+  .command('review')
+  .description('일일 지식 리뷰 — 잊어가는 노트를 Obsidian에서 열어 리뷰')
+  .option('-n, --count <n>', '리뷰할 노트 수', '5')
+  .action(reviewCommand);
+
+program
+  .command('sync')
+  .description('Notion → Obsidian 동기화')
+  .option('--upload', 'PDCA 문서를 Notion에 업로드')
+  .option('--watch', '5분 간격 자동 동기화')
+  .action(syncCommand);
+
+const federate = program.command('federate').description('Federation — P2P knowledge network');
+
+federate.command('join')
+  .description('Join the federation network (interactive mode)')
+  .option('-n, --name <name>', 'Display name for this node')
+  .action(federateJoinCommand);
+
+federate.command('status')
+  .description('Show federation identity and status')
+  .action(federateStatusCommand);
+
+program
+  .command('capture <audio-file>')
+  .description('Voice capture — transcribe audio to knowledge note (requires Whisper)')
+  .option('-m, --model <model>', 'Whisper model (tiny/base/small/medium/large)', 'base')
+  .option('-l, --language <lang>', 'Language (auto-detect if omitted)')
+  .option('-t, --tags <tags>', 'Comma-separated tags')
+  .option('-f, --folder <folder>', 'Vault subfolder', '01_Knowledge/voice')
+  .action(captureCommand);
+
+const vault = program.command('vault').description('Multi-Vault — manage and search across vaults');
+vault.command('add <id> <path>').description('Register a vault').option('-n, --name <name>', 'Display name').option('-s, --shared', 'Allow federation sharing').action(vaultAddCommand);
+vault.command('list').description('List registered vaults').action(vaultListCommand);
+vault.command('remove <id>').description('Unregister a vault').action(vaultRemoveCommand);
+vault.command('search-all <query>').description('Search across all registered vaults').option('-l, --limit <n>', 'Max results', '10').action(vaultSearchAllCommand);
+
+const cloud = program.command('cloud').description('Cloud — E2E encrypted backup');
+cloud.command('sync').description('Upload encrypted DB to cloud').action(cloudSyncCommand);
+cloud.command('restore').description('Download and decrypt DB from cloud').action(cloudRestoreCommand);
+cloud.command('status').description('Show last sync status').action(cloudStatusCommand);
+
+const pack = program.command('pack').description('Knowledge Pack 관리');
+
+pack.command('create <name>')
+  .description('검색/클러스터 기반 Knowledge Pack 생성')
+  .option('--from-search <query>', '검색 쿼리에서 생성')
+  .option('--from-cluster <id>', '클러스터 ID에서 생성')
+  .option('--author <name>', '작성자', 'anonymous')
+  .option('--license <license>', '라이선스', 'CC-BY-4.0')
+  .option('--description <desc>', '설명')
+  .option('--limit <n>', '최대 청크 수', '100')
+  .action(packCreateCommand);
+
+pack.command('export <name>')
+  .description('.sv-pack 파일로 내보내기')
+  .option('-o, --output <path>', '출력 경로')
+  .action(packExportCommand);
+
+pack.command('import <file>')
+  .description('.sv-pack 파일 가져오기 → 벡터 DB 병합')
+  .action(packImportCommand);
+
+pack.command('list')
+  .description('설치된 팩 목록')
+  .action(packListCommand);
+
+pack.command('info <name>')
+  .description('팩 상세 정보')
+  .action(packInfoCommand);
+
+program.parse();

package/packages/core/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@stellavault/core",
+  "version": "0.1.0",
+  "description": "Stellavault core engine — indexer, hybrid search, vector store, MCP server",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "@xenova/transformers": "^2.17.2",
+    "b4a": "^1.8.0",
+    "better-sqlite3": "^12.8.0",
+    "chokidar": "^5.0.0",
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
+    "gray-matter": "^4.0.3",
+    "hyperswarm": "^4.17.0",
+    "sqlite-vec": "^0.1.7"
+  }
+}

package/packages/core/src/api/dashboard.ts

@@ -0,0 +1,138 @@
+// Web Dashboard (P3-F26) — Express에 HTML 대시보드 추가
+// http://localhost:3333/dashboard
+
+import type { Express } from 'express';
+
+export function mountDashboard(app: Express) {
+  app.get('/dashboard', (_req, res) => {
+    res.setHeader('Content-Type', 'text/html');
+    res.send(getDashboardHTML());
+  });
+}
+
+function getDashboardHTML(): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Stellavault Dashboard</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: system-ui, -apple-system, sans-serif; background: #050510; color: #c0c0f0; min-height: 100vh; }
+    .header { padding: 16px 24px; border-bottom: 1px solid rgba(100,120,255,0.1); display: flex; align-items: center; gap: 12px; }
+    .header h1 { font-size: 18px; font-weight: 600; }
+    .header .subtitle { color: #556; font-size: 12px; }
+    .container { max-width: 1200px; margin: 0 auto; padding: 24px; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 16px; margin-bottom: 24px; }
+    .card { background: rgba(100,120,255,0.04); border: 1px solid rgba(100,120,255,0.1); border-radius: 12px; padding: 16px; }
+    .card h3 { font-size: 11px; text-transform: uppercase; letter-spacing: 0.5px; color: #556; margin-bottom: 8px; }
+    .card .value { font-size: 28px; font-weight: 700; }
+    .card .sub { font-size: 11px; color: #556; margin-top: 4px; }
+    .search-box { width: 100%; padding: 10px 16px; background: rgba(100,120,255,0.06); border: 1px solid rgba(100,120,255,0.15); border-radius: 8px; color: #c0c0f0; font-size: 14px; outline: none; margin-bottom: 16px; }
+    .search-box::placeholder { color: #445; }
+    .results { display: flex; flex-direction: column; gap: 8px; }
+    .result { padding: 12px; background: rgba(255,255,255,0.02); border-radius: 8px; cursor: pointer; }
+    .result:hover { background: rgba(100,120,255,0.06); }
+    .result .title { font-weight: 600; font-size: 13px; }
+    .result .meta { font-size: 11px; color: #556; margin-top: 4px; }
+    .section { margin-bottom: 24px; }
+    .section h2 { font-size: 14px; margin-bottom: 12px; color: #88aaff; }
+    .bar { height: 6px; background: rgba(100,120,255,0.1); border-radius: 3px; overflow: hidden; margin-top: 6px; }
+    .bar-fill { height: 100%; border-radius: 3px; transition: width 0.3s; }
+    .links { display: flex; gap: 12px; margin-top: 16px; }
+    .links a { color: #88aaff; text-decoration: none; font-size: 12px; padding: 6px 12px; border: 1px solid rgba(100,120,255,0.15); border-radius: 6px; }
+    .links a:hover { background: rgba(100,120,255,0.1); }
+    #loading { color: #556; font-size: 12px; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>Stellavault</h1>
+    <span class="subtitle">Dashboard</span>
+    <div style="margin-left:auto" class="links">
+      <a href="/api/stats" target="_blank">API Stats</a>
+      <a href="http://localhost:5173" target="_blank">3D Graph</a>
+    </div>
+  </div>
+
+  <div class="container">
+    <!-- Stats -->
+    <div class="grid" id="stats-grid">
+      <div class="card"><h3>Documents</h3><div class="value" id="doc-count">-</div></div>
+      <div class="card"><h3>Chunks</h3><div class="value" id="chunk-count">-</div></div>
+      <div class="card"><h3>Health Score</h3><div class="value" id="health-score">-</div><div class="bar"><div class="bar-fill" id="health-bar" style="width:0%;background:#10b981"></div></div></div>
+      <div class="card"><h3>Knowledge Gaps</h3><div class="value" id="gap-count">-</div></div>
+    </div>
+
+    <!-- Search -->
+    <div class="section">
+      <h2>Search</h2>
+      <input class="search-box" id="search-input" placeholder="Search your knowledge..." />
+      <div class="results" id="search-results"></div>
+    </div>
+
+    <!-- Decay -->
+    <div class="section">
+      <h2>Fading Knowledge</h2>
+      <div id="decay-list"><span id="loading">Loading...</span></div>
+    </div>
+  </div>
+
+  <script>
+    const API = '/api';
+    // HIGH-06: XSS 방지 — HTML 이스케이프
+    function esc(s) { const d = document.createElement('div'); d.textContent = s; return d.innerHTML; }
+
+    async function loadStats() {
+      try {
+        const [stats, health] = await Promise.all([
+          fetch(API + '/stats').then(r => r.json()),
+          fetch(API + '/health').then(r => r.json()).catch(() => null),
+        ]);
+        document.getElementById('doc-count').textContent = stats.documentCount ?? 0;
+        document.getElementById('chunk-count').textContent = stats.chunkCount ?? 0;
+        if (health) {
+          const score = health.decay?.averageR ? Math.round(health.decay.averageR * 100) : 100;
+          document.getElementById('health-score').textContent = score + '%';
+          document.getElementById('health-bar').style.width = score + '%';
+          document.getElementById('health-bar').style.background = score > 70 ? '#10b981' : score > 40 ? '#f59e0b' : '#ef4444';
+          document.getElementById('gap-count').textContent = health.gaps?.gapCount ?? 0;
+
+          // Decay list
+          const decayEl = document.getElementById('decay-list');
+          if (health.decay?.topDecaying?.length) {
+            decayEl.innerHTML = health.decay.topDecaying.slice(0, 8).map(d => {
+              const r = Math.round((d.retrievability ?? 0) * 100);
+              const color = r > 50 ? '#10b981' : r > 30 ? '#f59e0b' : '#ef4444';
+              return '<div class="result"><div class="title">' + esc(d.title) + '</div><div class="bar"><div class="bar-fill" style="width:' + r + '%;background:' + color + '"></div></div><div class="meta">' + r + '% retrievability</div></div>';
+            }).join('');
+          } else {
+            decayEl.innerHTML = '<div style="color:#556;font-size:12px">All knowledge healthy!</div>';
+          }
+        }
+      } catch (e) { console.error(e); }
+    }
+
+    let searchTimer;
+    document.getElementById('search-input').addEventListener('input', (e) => {
+      clearTimeout(searchTimer);
+      searchTimer = setTimeout(async () => {
+        const q = e.target.value.trim();
+        const el = document.getElementById('search-results');
+        if (!q) { el.innerHTML = ''; return; }
+        try {
+          const res = await fetch(API + '/search?q=' + encodeURIComponent(q) + '&limit=10').then(r => r.json());
+          el.innerHTML = (res.results || []).map(r =>
+            '<div class="result"><div class="title">' + esc(r.title) + ' <span style="color:#556;font-size:11px">(' + Math.round(r.score * 100) + '%)</span></div>' +
+            '<div class="meta">' + esc((r.highlights?.[0] || '').slice(0, 100)) + '</div></div>'
+          ).join('') || '<div style="color:#556;font-size:12px">No results</div>';
+        } catch { el.innerHTML = '<div style="color:#ef4444;font-size:12px">Search error</div>'; }
+      }, 300);
+    });
+
+    loadStats();
+  </script>
+</body>
+</html>`;
+}

package/packages/core/src/api/graph-data.ts

@@ -0,0 +1,286 @@
+// Design Ref: §4.2 — Graph Data 생성 알고리즘
+// Design Ref: §6.2 — K-Means 클러스터링
+
+import type { VectorStore } from '../store/types.js';
+import type { GraphNode, GraphEdge, Cluster, GraphData } from '../types/graph.js';
+import { createHash } from 'node:crypto';
+
+const CLUSTER_COLORS = [
+  '#6366f1', '#ec4899', '#f59e0b', '#10b981', '#3b82f6',
+  '#8b5cf6', '#ef4444', '#14b8a6', '#f97316', '#06b6d4',
+  '#84cc16', '#e879f9', '#22d3ee', '#a3e635', '#fb923c',
+];
+
+export type GraphMode = 'semantic' | 'folder';
+
+export interface BuildGraphOptions {
+  mode?: GraphMode;            // default: 'semantic'
+  edgeThreshold?: number;      // default: 0.15
+  maxEdgesPerNode?: number;    // default: 5
+  clusterCount?: number;       // 0 = auto (Elbow)
+}
+
+export async function buildGraphData(
+  store: VectorStore,
+  options: BuildGraphOptions = {},
+): Promise<GraphData> {
+  const {
+    edgeThreshold = 0.15,
+    maxEdgesPerNode = 5,
+  } = options;
+
+  // 1. 모든 문서 + 임베딩 로드
+  const [docs, embeddings] = await Promise.all([
+    store.getAllDocuments(),
+    store.getDocumentEmbeddings(),
+  ]);
+
+  // 2. k-NN으로 엣지 생성
+  const edges: GraphEdge[] = [];
+  const edgeCounts = new Map<string, number>();
+
+  for (const doc of docs) {
+    const vec = embeddings.get(doc.id);
+    if (!vec) continue;
+
+    // 모든 다른 문서와 코사인 유사도 계산
+    const similarities: Array<{ id: string; sim: number }> = [];
+    for (const other of docs) {
+      if (other.id === doc.id) continue;
+      const otherVec = embeddings.get(other.id);
+      if (!otherVec) continue;
+      const sim = cosineSimilarity(vec, otherVec);
+      if (sim >= edgeThreshold) {
+        similarities.push({ id: other.id, sim });
+      }
+    }
+
+    // 상위 k개만
+    similarities.sort((a, b) => b.sim - a.sim);
+    const topK = similarities.slice(0, maxEdgesPerNode);
+
+    for (const { id: targetId, sim } of topK) {
+      // 중복 엣지 방지 (A→B, B→A)
+      const edgeKey = [doc.id, targetId].sort().join(':');
+      if (!edgeCounts.has(edgeKey)) {
+        edges.push({ source: doc.id, target: targetId, weight: sim });
+        edgeCounts.set(edgeKey, 1);
+      }
+    }
+  }
+
+  // 3. 클러스터링 — 모드에 따라 분기
+  const mode = options.mode ?? 'semantic';
+  let assignmentMap: Map<string, number>;
+  let clusters: Cluster[];
+
+  if (mode === 'folder') {
+    // 폴더 기반: 최상위 폴더를 클러스터로 사용
+    const folderMap = new Map<string, number>();
+    const folderNames: string[] = [];
+
+    for (const doc of docs) {
+      const topFolder = doc.filePath.split('/')[0] ?? 'root';
+      if (!folderMap.has(topFolder)) {
+        folderMap.set(topFolder, folderNames.length);
+        folderNames.push(topFolder);
+      }
+    }
+
+    assignmentMap = new Map<string, number>();
+    for (const doc of docs) {
+      const topFolder = doc.filePath.split('/')[0] ?? 'root';
+      assignmentMap.set(doc.id, folderMap.get(topFolder)!);
+    }
+
+    // 폴더별 클러스터
+    const folderCounts = new Map<number, number>();
+    for (const [, cId] of assignmentMap) {
+      folderCounts.set(cId, (folderCounts.get(cId) ?? 0) + 1);
+    }
+
+    clusters = folderNames.map((name, i) => ({
+      id: i,
+      label: name.replace(/^\d+_/, ''),  // "04_Projects" → "Projects"
+      color: CLUSTER_COLORS[i % CLUSTER_COLORS.length],
+      nodeCount: folderCounts.get(i) ?? 0,
+    }));
+  } else {
+    // 시맨틱 기반: K-means
+    const docIds = docs.filter(d => embeddings.has(d.id)).map(d => d.id);
+    const vectors = docIds.map(id => embeddings.get(id)!);
+    const k = Math.min(Math.max(5, Math.round(Math.sqrt(docIds.length / 5))), 10);
+    const assignments = kMeans(vectors, k);
+
+    // 클러스터별 문서 수집 (id + title)
+    const clusterDocInfos = new Map<number, Array<{ id: string; title: string }>>();
+    for (let i = 0; i < docIds.length; i++) {
+      const cId = assignments[i];
+      if (!clusterDocInfos.has(cId)) clusterDocInfos.set(cId, []);
+      const doc = docs.find(d => d.id === docIds[i]);
+      if (doc) clusterDocInfos.get(cId)!.push({ id: doc.id, title: doc.title });
+    }
+
+    // 엣지 기반 연결 수 계산 (대표 노드 선정용)
+    const connCounts = new Map<string, number>();
+    for (const e of edges) {
+      connCounts.set(e.source, (connCounts.get(e.source) ?? 0) + 1);
+      connCounts.set(e.target, (connCounts.get(e.target) ?? 0) + 1);
+    }
+
+    clusters = [];
+    for (const [cId, docInfos] of clusterDocInfos) {
+      // 가장 연결이 많은 노드 = 대표 노드
+      const sorted = [...docInfos].sort((a, b) =>
+        (connCounts.get(b.id) ?? 0) - (connCounts.get(a.id) ?? 0)
+      );
+      const representative = sorted[0]?.title ?? 'Cluster';
+      clusters.push({
+        id: cId,
+        label: `${representative} (${docInfos.length})`,
+        color: CLUSTER_COLORS[cId % CLUSTER_COLORS.length],
+        nodeCount: docInfos.length,
+      });
+    }
+
+    assignmentMap = new Map<string, number>();
+    for (let i = 0; i < docIds.length; i++) {
+      assignmentMap.set(docIds[i], assignments[i]);
+    }
+  }
+
+  // 4. 노드 생성
+
+  const connectionCounts = new Map<string, number>();
+  for (const edge of edges) {
+    connectionCounts.set(edge.source, (connectionCounts.get(edge.source) ?? 0) + 1);
+    connectionCounts.set(edge.target, (connectionCounts.get(edge.target) ?? 0) + 1);
+  }
+  const maxConnections = Math.max(1, ...connectionCounts.values());
+
+  const nodes: GraphNode[] = docs.map(doc => {
+    const conns = connectionCounts.get(doc.id) ?? 0;
+    const ratio = conns / maxConnections; // 0~1
+    // 지수 스케일: 상위 노드만 극적으로 커짐 (ratio^0.5 → 중심부 강조)
+    const size = 1 + 6 * Math.pow(ratio, 0.5);
+    return {
+      id: doc.id,
+      label: doc.title.slice(0, 40),
+      filePath: doc.filePath,
+      tags: doc.tags,
+      clusterId: assignmentMap.get(doc.id) ?? 0,
+      size,
+      source: doc.source ?? 'local',
+      type: doc.type ?? 'note',
+      lastModified: doc.lastModified,
+    };
+  });
+
+  // 5. cache key
+  const cacheKey = createHash('md5')
+    .update(JSON.stringify({ nodeCount: nodes.length, edgeCount: edges.length }))
+    .digest('hex')
+    .slice(0, 8);
+
+  return {
+    nodes,
+    edges,
+    clusters,
+    stats: {
+      nodeCount: nodes.length,
+      edgeCount: edges.length,
+      clusterCount: clusters.length,
+    },
+  };
+}
+
+// --- 유틸리티 ---
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  let dot = 0, normA = 0, 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];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+function kMeans(vectors: number[][], k: number, maxIter: number = 50): number[] {
+  if (vectors.length === 0) return [];
+  const dims = vectors[0].length;
+
+  // K-means++ 초기화
+  const centroids: number[][] = [vectors[Math.floor(Math.random() * vectors.length)].slice()];
+  for (let c = 1; c < k; c++) {
+    const dists = vectors.map(v => {
+      let minD = Infinity;
+      for (const cent of centroids) {
+        const d = euclideanDist(v, cent);
+        if (d < minD) minD = d;
+      }
+      return minD;
+    });
+    const totalDist = dists.reduce((a, b) => a + b, 0);
+    let r = Math.random() * totalDist;
+    for (let i = 0; i < dists.length; i++) {
+      r -= dists[i];
+      if (r <= 0) { centroids.push(vectors[i].slice()); break; }
+    }
+    if (centroids.length <= c) centroids.push(vectors[Math.floor(Math.random() * vectors.length)].slice());
+  }
+
+  const assignments = new Array<number>(vectors.length).fill(0);
+
+  for (let iter = 0; iter < maxIter; iter++) {
+    let changed = false;
+
+    // Assign
+    for (let i = 0; i < vectors.length; i++) {
+      let bestC = 0, bestD = Infinity;
+      for (let c = 0; c < k; c++) {
+        const d = euclideanDist(vectors[i], centroids[c]);
+        if (d < bestD) { bestD = d; bestC = c; }
+      }
+      if (assignments[i] !== bestC) { assignments[i] = bestC; changed = true; }
+    }
+
+    if (!changed) break;
+
+    // Update centroids
+    for (let c = 0; c < k; c++) {
+      const members = vectors.filter((_, i) => assignments[i] === c);
+      if (members.length === 0) continue;
+      for (let d = 0; d < dims; d++) {
+        centroids[c][d] = members.reduce((sum, v) => sum + v[d], 0) / members.length;
+      }
+    }
+  }
+
+  return assignments;
+}
+
+function euclideanDist(a: number[], b: number[]): number {
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) {
+    const diff = a[i] - b[i];
+    sum += diff * diff;
+  }
+  return Math.sqrt(sum);
+}
+
+function extractClusterLabel(titles: string[]): string {
+  // 제목에서 빈출 단어 추출 (2글자 이상)
+  const wordCounts = new Map<string, number>();
+  const stopWords = new Set(['the', 'a', 'an', 'in', 'on', 'at', 'to', 'for', 'of', 'and', 'or', 'is', 'are', 'was', 'be']);
+  for (const title of titles) {
+    const words = title.replace(/[^\w가-힣\s]/g, '').split(/\s+/).filter(w => w.length >= 2 && !stopWords.has(w.toLowerCase()));
+    const seen = new Set<string>();
+    for (const w of words) {
+      if (!seen.has(w)) { wordCounts.set(w, (wordCounts.get(w) ?? 0) + 1); seen.add(w); }
+    }
+  }
+  const sorted = [...wordCounts.entries()].sort((a, b) => b[1] - a[1]);
+  return sorted.slice(0, 3).map(([w]) => w).join(', ') || `Cluster`;
+}