@open330/kiwimu 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jiunbae
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+<div align="center">
+
+<img src="assets/logos/logo_2_minimalist_icon_transparent.png" alt="Kiwi Mu" width="120">
+
+# Kiwi Mu
+
+**나만의 학습 위키를 만드세요**
+
+전공책, PDF, 웹 콘텐츠를 넣으면 — LLM이 챕터/개념별로 분석하여 상호 링크된 학습 위키를 자동 생성합니다.
+
+[![Bun](https://img.shields.io/badge/Bun-1.0+-fbf0df?style=flat-square&logo=bun&logoColor=black)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://typescriptlang.org)
+[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
+
+</div>
+
+---
+
+## Quickstart for Agents
+
+<div><img src="https://quickstart-for-agents.vercel.app/api/header.svg?theme=claude-code&logo=kiwimu&title=Set+up+a+learning+wiki+from+any+textbook+or+URL&lang=Agents&font=mono&mascot=hat" width="100%" /></div>
+
+```
+git clone https://github.com/Open330/kiwimu.git && cd kiwimu && bun install
+mkdir my-wiki && cd my-wiki
+bunx kiwimu init
+bunx kiwimu add "<YOUR_URL_OR_PDF>"
+bunx kiwimu serve
+```
+
+<div><img src="https://quickstart-for-agents.vercel.app/api/footer.svg?theme=claude-code&text=copy+this+prompt+%C2%B7+paste+into+your+agent+%C2%B7+get+a+learning+wiki&font=mono" width="100%" /></div>
+
+---
+
+## Why Kiwi Mu?
+
+교과서 한 권을 읽으면 수십 개의 개념이 서로 연결됩니다.
+Kiwi Mu는 LLM을 활용해 이 연결을 **자동으로** 만들어, 지식을 빠르게 탐색할 수 있는 위키로 변환합니다.
+
+- **LLM 기반 문서 분석** — 챕터/섹션 구조를 보존한 원본 페이지 + 핵심 개념별 자동 생성 페이지
+- **원본/개념 분리** — 📖 원본 문서와 📝 개념 문서를 시각적으로 구분
+- **자동 상호 링크** — 원본↔개념 간 유기적 cross-link + 외부 참고 자료 (Wikipedia 등)
+- **지식 그래프** — D3.js 인터랙티브 그래프 (원본: 파란색, 개념: 초록색)
+- **웹 UI** — 브라우저에서 문서 추가, 설정 변경, 빌드 실행
+- **다양한 파일 지원** — URL, PDF, DOCX, PPTX, PPT, DOC, KEY
+- **다중 LLM 프로바이더** — Google Gemini, Azure OpenAI, OpenAI, Anthropic
+- **토큰 사용량 추적** — API 호출 수, 토큰, 예상 비용을 웹에서 확인
+- **원클릭 배포** — GitHub Pages / Vercel
+
+## Quick Start
+
+### 설치
+
+```bash
+git clone https://github.com/Open330/kiwimu.git
+cd kiwimu && bun install
+```
+
+### 프로젝트 생성 (Interactive CLI)
+
+```bash
+mkdir my-wiki && cd my-wiki
+bunx kiwimu init
+```
+
+Interactive 프롬프트가 실행됩니다:
+
+```
+🥝 Kiwi Mu — 새 학습 위키 만들기
+
+◆ 위키 이름
+│  Radio Astronomy Wiki
+
+◆ LLM 프로바이더
+│  ● Google Gemini  (무료 API key: aistudio.google.com)
+│  ○ Azure OpenAI
+│  ○ OpenAI
+│  ○ Anthropic Claude
+
+◆ 모델명
+│  gemini-2.0-flash-lite
+
+◆ API Key
+│  ••••••••••••
+
+🥝 'Radio Astronomy Wiki' 위키가 생성되었습니다!
+```
+
+이름을 바로 지정할 수도 있습니다:
+
+```bash
+bunx kiwimu init "My Study Wiki"
+```
+
+### 문서 추가
+
+```bash
+# URL 추가
+bunx kiwimu add "https://www.cv.nrao.edu/~sransom/web/Ch1.html"
+
+# PDF 추가
+bunx kiwimu add textbook.pdf
+```
+
+LLM이 문서를 분석하여:
+1. 📖 **원본 페이지** — 원래 챕터/섹션 구조 보존
+2. 📝 **개념 페이지** — 핵심 용어·정의·법칙 자동 생성
+3. 🔗 **Cross-link** — 원본↔개념 간 유기적 연결
+
+### 빌드 및 서버
+
+```bash
+# 정적 사이트 빌드
+bunx kiwimu build
+
+# 로컬 서버 실행 (웹에서 문서 추가 가능)
+bunx kiwimu serve
+# → http://localhost:8000
+
+# 포트 변경
+bunx kiwimu serve -p 3000
+
+# 네트워크에 공개 (0.0.0.0)
+bunx kiwimu serve --host 0.0.0.0
+```
+
+### 웹 UI에서 문서 추가
+
+`kiwimu serve` 실행 후 http://localhost:8000 에서:
+- **🔗 URL 탭** — URL 입력 후 추가
+- **📄 파일 업로드 탭** — PDF, DOCX, PPTX 등 드래그앤드롭 업로드
+- 진행 상태 실시간 표시, 완료 시 자동 새로고침
+
+### 관리 페이지
+
+http://localhost:8000/admin 에서:
+- 위키 이름 변경
+- LLM 프로바이더/모델/API Key 설정
+- 토큰 사용량 및 예상 비용 확인
+- 등록된 소스 목록
+- 수동 빌드 실행
+
+### 배포
+
+```bash
+# GitHub Pages (기본)
+bunx kiwimu deploy
+
+# Vercel
+bunx kiwimu deploy --target vercel
+```
+
+## Commands
+
+| 명령 | 설명 |
+|------|------|
+| `kiwimu init [name]` | 새 위키 프로젝트 생성 (interactive CLI) |
+| `kiwimu add <source>` | URL 또는 파일 추가 (LLM 분석 + 링크 생성) |
+| `kiwimu build` | 정적 위키 사이트 빌드 |
+| `kiwimu serve [-p port] [--host host]` | 웹 서버 실행 (문서 추가/관리 가능) |
+| `kiwimu deploy` | GitHub Pages / Vercel에 배포 |
+| `kiwimu status` | 현재 위키 상태 표시 |
+
+## Supported File Formats
+
+| 형식 | 방법 |
+|------|------|
+| URL (HTTP/HTTPS) | Cheerio 웹 크롤링 |
+| PDF | pdf-parse |
+| DOCX | mammoth |
+| PPTX | ZIP/XML 파싱 |
+| DOC / PPT / RTF | macOS textutil |
+| KEY (Keynote) | 텍스트 추출 (제한적) |
+
+## Supported LLM Providers
+
+| 프로바이더 | 추천 모델 | 비고 |
+|-----------|----------|------|
+| **Google Gemini** | `gemini-2.0-flash-lite` | [무료 API key](https://aistudio.google.com/) |
+| Azure OpenAI | `gpt-5-nano` | Azure 구독 필요 |
+| OpenAI | `gpt-4o-mini` | API key 필요 |
+| Anthropic | `claude-sonnet-4-20250514` | API key 필요 |
+
+## Architecture
+
+```
+소스 (URL / PDF / DOCX / PPTX)
+    ↓
+[ Ingest ]    ── Cheerio / pdf-parse / mammoth / jszip
+    ↓
+[ Phase 1 ]   ── LLM: 원본 구조 추출 (📖 원본 페이지)
+    ↓
+[ Phase 2 ]   ── LLM: 개념 추출 (📝 개념 페이지)
+    ↓
+[ Phase 3 ]   ── [[wiki link]] 해석 + 원본↔개념 cross-link
+    ↓
+[ Build ]     ── 정적 HTML 생성 (탭 사이드바, KaTeX, 지식 그래프)
+    ↓
+[ Deploy ]    ── GitHub Pages / Vercel
+```
+
+```
+project-dir/
+├── kiwi.toml          # 프로젝트 + LLM 설정
+├── kiwi.db            # SQLite (문서, 링크, 사용량)
+├── uploads/           # 업로드된 파일
+└── _site/             # 빌드 결과
+    ├── index.html     # 홈 (문서 추가 UI + 사용량 대시보드)
+    ├── graph.html     # 지식 그래프
+    ├── wiki/          # 각 문서 페이지
+    ├── static/        # CSS, JS, 로고
+    └── search-index.json
+```
+
+## Tech Stack
+
+- **Bun** — 런타임, 패키지 매니저, 빌트인 SQLite
+- **TypeScript** — 타입 안전한 파이프라인
+- **@clack/prompts** — Interactive CLI
+- **Cheerio** — 웹 페이지 파싱
+- **Mammoth** — DOCX 파싱
+- **JSZip** — PPTX 파싱
+- **Marked** — Markdown → HTML
+- **D3.js** — 지식 그래프
+- **KaTeX** — 수학 수식 렌더링
+- **gh-pages** — GitHub Pages 배포
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@open330/kiwimu",
+  "version": "0.3.0",
+  "description": "Turn textbooks, PDFs, and web content into your own interlinked learning wiki powered by LLM",
+  "type": "module",
+  "bin": {
+    "kiwimu": "./src/index.ts"
+  },
+  "files": [
+    "src/**/*",
+    "assets/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "wiki",
+    "learning",
+    "study",
+    "textbook",
+    "pdf",
+    "llm",
+    "gemini",
+    "knowledge-graph",
+    "education",
+    "bun"
+  ],
+  "author": "jiunbae",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Open330/kiwimu.git"
+  },
+  "homepage": "https://github.com/Open330/kiwimu",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "cheerio": "^1.0.0",
+    "commander": "^12.1.0",
+    "gh-pages": "^6.3.0",
+    "jszip": "^3.10.1",
+    "mammoth": "^1.12.0",
+    "marked": "^15.0.0",
+    "pdf-parse": "1.1.1",
+    "smol-toml": "^1.3.1",
+    "turndown": "^7.2.0"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^0.79.0",
+    "openai": "^6.31.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/pdf-parse": "^1.1.5",
+    "@types/turndown": "^5.0.5"
+  }
+}

package/src/build/renderer.ts

@@ -0,0 +1,128 @@
+import { mkdirSync, rmSync, cpSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { marked } from "marked";
+import type { KiwiConfig } from "../config";
+import type { Store } from "../store";
+import { buildGraphData } from "../pipeline/graph";
+import { renderPage, renderIndex, renderGraph } from "./templates";
+
+// Fix internal wiki links: /wiki/slug → /wiki/slug.html
+function fixWikiLinks(html: string): string {
+  return html.replace(/href="\/wiki\/([^"]+?)"/g, (match, slug) => {
+    if (slug.endsWith(".html")) return match;
+    return `href="/wiki/${slug}.html"`;
+  });
+}
+
+// Separate external reference links from body content
+function extractExternalRefs(html: string): { body: string; externalRefs: string } {
+  const marker = '<h2 id="external-references">External References</h2>';
+  const idx = html.indexOf(marker);
+  if (idx === -1) return { body: html, externalRefs: "" };
+
+  const body = html.slice(0, idx);
+  const refSection = html.slice(idx + marker.length);
+  return { body, externalRefs: refSection };
+}
+
+function generateToc(markdown: string): string {
+  const headings: Array<{ level: number; text: string; id: string }> = [];
+  const headingRegex = /^(#{2,4})\s+(.+)$/gm;
+  let match;
+  while ((match = headingRegex.exec(markdown)) !== null) {
+    const text = match[2].trim();
+    if (text === "External References") continue;
+    const id = text.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-");
+    headings.push({ level: match[1].length, text, id });
+  }
+  if (!headings.length) return "";
+
+  return `<div class="toc"><ul>${headings
+    .map((h) => `<li style="margin-left:${(h.level - 2) * 16}px"><a href="#${h.id}">${h.text}</a></li>`)
+    .join("")}</ul></div>`;
+}
+
+export async function buildSite(store: Store, config: KiwiConfig, projectRoot: string): Promise<number> {
+  const outputDir = join(projectRoot, config.build.output_dir);
+  const wikiDir = join(outputDir, "wiki");
+  const staticDir = join(outputDir, "static");
+
+  if (existsSync(outputDir)) rmSync(outputDir, { recursive: true });
+  mkdirSync(wikiDir, { recursive: true });
+  mkdirSync(staticDir, { recursive: true });
+
+  const assetsDir = join(dirname(import.meta.path), "static");
+  if (existsSync(assetsDir)) {
+    cpSync(assetsDir, staticDir, { recursive: true });
+  }
+
+  // Copy logo
+  const logoSrc = join(projectRoot, "..", "assets", "logos", "logo_2_minimalist_icon_transparent.png");
+  const logoSrc2 = join(projectRoot, "assets", "logos", "logo_2_minimalist_icon_transparent.png");
+  const logoFile = existsSync(logoSrc) ? logoSrc : existsSync(logoSrc2) ? logoSrc2 : null;
+  if (logoFile) {
+    cpSync(logoFile, join(staticDir, "logo.png"));
+  }
+
+  const pages = store.listPages();
+  const sourcePages = store.listSourcePages();
+  const conceptPages = store.listConceptPages();
+  const wikiName = config.project.name;
+
+  for (const page of pages) {
+    let htmlContent = await marked(page.content);
+    htmlContent = fixWikiLinks(htmlContent);
+
+    const { body, externalRefs } = extractExternalRefs(htmlContent);
+    const toc = generateToc(page.content);
+    const backlinks = store.getBacklinks(page.id).map((bl) => ({
+      slug: bl.slug,
+      title: bl.title,
+      pageType: bl.page_type,
+    }));
+
+    const html = renderPage({
+      wikiName,
+      pageTitle: page.title,
+      pageSlug: page.slug,
+      pageType: page.page_type,
+      content: body,
+      externalRefs,
+      toc,
+      backlinks,
+      sourcePages: sourcePages.map((p) => ({ slug: p.slug, title: p.title })),
+      conceptPages: conceptPages.map((p) => ({ slug: p.slug, title: p.title })),
+    });
+
+    await Bun.write(join(wikiDir, `${page.slug}.html`), html);
+  }
+
+  const indexHtml = renderIndex({
+    wikiName,
+    sourcePages: sourcePages.map((p) => ({ slug: p.slug, title: p.title })),
+    conceptPages: conceptPages.map((p) => ({ slug: p.slug, title: p.title })),
+    sourceCount: store.listSources().length,
+  });
+  await Bun.write(join(outputDir, "index.html"), indexHtml);
+
+  const graphData = buildGraphData(store);
+  await Bun.write(join(outputDir, "graph-data.json"), JSON.stringify(graphData));
+  await Bun.write(
+    join(outputDir, "graph.html"),
+    renderGraph({
+      wikiName,
+      sourcePages: sourcePages.map((p) => ({ slug: p.slug, title: p.title })),
+      conceptPages: conceptPages.map((p) => ({ slug: p.slug, title: p.title })),
+    })
+  );
+
+  const searchData = pages.map((p) => ({
+    slug: p.slug,
+    title: p.title,
+    preview: p.content.slice(0, 200),
+    type: p.page_type,
+  }));
+  await Bun.write(join(outputDir, "search-index.json"), JSON.stringify(searchData));
+
+  return pages.length;
+}

package/src/build/static/graph.js

@@ -0,0 +1,114 @@
+// Knowledge graph visualization using D3.js force-directed layout
+document.addEventListener("DOMContentLoaded", async () => {
+    const container = document.getElementById("graph-container");
+    if (!container) return;
+
+    const resp = await fetch("/graph-data.json");
+    const data = await resp.json();
+
+    if (!data.nodes.length) {
+        container.innerHTML = '<p style="padding:40px;color:#6c757d;">문서를 추가하면 지식 그래프가 표시됩니다.</p>';
+        return;
+    }
+
+    const colors = {
+        source: "#2196f3",
+        sourceHover: "#1565c0",
+        concept: "#4caf50",
+        conceptHover: "#2e7d32",
+    };
+
+    const width = container.clientWidth;
+    const height = container.clientHeight;
+
+    const svg = d3.select(container)
+        .append("svg")
+        .attr("viewBox", [0, 0, width, height]);
+
+    const g = svg.append("g");
+    svg.call(d3.zoom()
+        .scaleExtent([0.3, 4])
+        .on("zoom", (event) => g.attr("transform", event.transform)));
+
+    const simulation = d3.forceSimulation(data.nodes)
+        .force("link", d3.forceLink(data.links).id(d => d.id).distance(100))
+        .force("charge", d3.forceManyBody().strength(-300))
+        .force("center", d3.forceCenter(width / 2, height / 2))
+        .force("collision", d3.forceCollide().radius(30));
+
+    const link = g.append("g")
+        .selectAll("line")
+        .data(data.links)
+        .join("line")
+        .attr("stroke", "#dee2e6")
+        .attr("stroke-width", 1.5)
+        .attr("stroke-opacity", 0.6);
+
+    const node = g.append("g")
+        .selectAll("g")
+        .data(data.nodes)
+        .join("g")
+        .style("cursor", "pointer")
+        .call(d3.drag()
+            .on("start", dragstarted)
+            .on("drag", dragged)
+            .on("end", dragended));
+
+    node.append("circle")
+        .attr("r", d => Math.max(6, Math.min(20, 4 + d.degree * 2)))
+        .attr("fill", d => d.type === "source" ? colors.source : colors.concept)
+        .attr("stroke", "#fff")
+        .attr("stroke-width", 2);
+
+    node.append("text")
+        .text(d => d.title)
+        .attr("dx", d => Math.max(8, 6 + d.degree * 2) + 4)
+        .attr("dy", 4)
+        .attr("font-size", "12px")
+        .attr("fill", "#212529");
+
+    node.on("click", (event, d) => {
+        window.location.href = `/wiki/${d.id}.html`;
+    });
+
+    node.on("mouseenter", function(event, d) {
+        const hoverColor = d.type === "source" ? colors.sourceHover : colors.conceptHover;
+        const baseColor = d.type === "source" ? colors.source : colors.concept;
+        d3.select(this).select("circle").attr("fill", hoverColor);
+        link.attr("stroke", l =>
+            l.source.id === d.id || l.target.id === d.id ? baseColor : "#dee2e6"
+        ).attr("stroke-width", l =>
+            l.source.id === d.id || l.target.id === d.id ? 2.5 : 1.5
+        );
+    }).on("mouseleave", function(event, d) {
+        const baseColor = d.type === "source" ? colors.source : colors.concept;
+        d3.select(this).select("circle").attr("fill", baseColor);
+        link.attr("stroke", "#dee2e6").attr("stroke-width", 1.5);
+    });
+
+    simulation.on("tick", () => {
+        link
+            .attr("x1", d => d.source.x)
+            .attr("y1", d => d.source.y)
+            .attr("x2", d => d.target.x)
+            .attr("y2", d => d.target.y);
+        node.attr("transform", d => `translate(${d.x},${d.y})`);
+    });
+
+    function dragstarted(event) {
+        if (!event.active) simulation.alphaTarget(0.3).restart();
+        event.subject.fx = event.subject.x;
+        event.subject.fy = event.subject.y;
+    }
+
+    function dragged(event) {
+        event.subject.fx = event.x;
+        event.subject.fy = event.y;
+    }
+
+    function dragended(event) {
+        if (!event.active) simulation.alphaTarget(0);
+        event.subject.fx = null;
+        event.subject.fy = null;
+    }
+});

package/src/build/static/search.js

@@ -0,0 +1,66 @@
+// Client-side fuzzy search
+document.addEventListener("DOMContentLoaded", async () => {
+    const input = document.getElementById("search-input");
+    const dropdown = document.getElementById("search-results");
+    if (!input || !dropdown) return;
+
+    let searchData = [];
+    try {
+        const resp = await fetch("/search-index.json");
+        searchData = await resp.json();
+    } catch (e) {
+        return;
+    }
+
+    function fuzzyMatch(query, text) {
+        query = query.toLowerCase();
+        text = text.toLowerCase();
+        if (text.includes(query)) return true;
+        let qi = 0;
+        for (let i = 0; i < text.length && qi < query.length; i++) {
+            if (text[i] === query[qi]) qi++;
+        }
+        return qi === query.length;
+    }
+
+    function search(query) {
+        if (!query.trim()) return [];
+        return searchData
+            .filter(item => fuzzyMatch(query, item.title) || fuzzyMatch(query, item.preview))
+            .slice(0, 8);
+    }
+
+    input.addEventListener("input", () => {
+        const results = search(input.value);
+        if (results.length === 0) {
+            dropdown.classList.remove("active");
+            dropdown.innerHTML = "";
+            return;
+        }
+        dropdown.innerHTML = results.map(r =>
+            `<a href="/wiki/${r.slug}.html">
+                <strong>${r.title}</strong>
+                <div style="font-size:12px;color:#6c757d;margin-top:2px;">${r.preview.slice(0, 80)}...</div>
+            </a>`
+        ).join("");
+        dropdown.classList.add("active");
+    });
+
+    input.addEventListener("blur", () => {
+        setTimeout(() => dropdown.classList.remove("active"), 200);
+    });
+
+    input.addEventListener("focus", () => {
+        if (input.value.trim() && dropdown.innerHTML) {
+            dropdown.classList.add("active");
+        }
+    });
+
+    // Keyboard navigation
+    input.addEventListener("keydown", (e) => {
+        if (e.key === "Escape") {
+            dropdown.classList.remove("active");
+            input.blur();
+        }
+    });
+});