altair823
24e9f739dd
CLAUDE.md 에 새 절 \"User-facing docs (README)\" 추가: - Implementation PR 이 README 를 갱신, spec PR 은 안 건드림. - 3 surface (CLI / TUI / Configuration) 마다 README 의 어느 행을 손대야 하는지 명시. - Phase status table 갱신 의무 (⏳ → ✅). - HOTFIXES detail / version cascade / per-task spec rationale 는 README out of scope. 같은 PR 에서 README 의 stale 부분 한꺼번에 정리: - 상태 line: P0–P5 + P6 + P7 + P9-1 완료 + post-merge hotfix 다수 반영. - 명령 표: kebab tui 추가, ingest/search 가 markdown/image/PDF 모두 처리한다고 갱신, eval 상태 ✅. - 핵심 결정: OCR Tesseract → Ollama-vision (HOTFIXES P6-2), Image caption 추가, PDF parser lopdf + chunker_version per-medium 명시 (HOTFIXES P7-3), TUI/Desktop 진행 상태. - Phase 로드맵: P5/P6/P7 ✅ 완료, P8 ⏸ 보류, P9 🟡 진행 (1/5). - 디렉토리 구조: kebab-eval / kebab-parse-image / kebab-parse-pdf / kebab-tui crate 추가, p6/p7 task 카운트 갱신. - 빌드 + 실행: kebab tui 사용법 + 두 example 바이너리 (gen_smoke_pdf / gen_smoke_png) 안내 추가. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
234 lines
14 KiB
Markdown
234 lines
14 KiB
Markdown
# kebab — Local-first Knowledge Base
|
||
|
||
> **상태:** P0–P5 + P6 + P7 + P9-1 (Library 패널) 구현 완료 + post-merge hotfix 다수 (storage UNIQUE bug, vector store orphan cleanup, chunker_version per-medium 등). `kebab ingest` 가 markdown / image / PDF 모두 처리, `kebab search --mode {lexical,vector,hybrid}` / `kebab ask` 가 매체 가로질러 결과 + page citation 반환. `kebab tui` 가 Library 패널 제공 (search / ask / inspect 패널은 P9-2/3/4 예정). 다음 단계 = P9-2 (TUI search) 또는 P8 (audio — 시스템 dep brainstorm 필요해 보류). 자세한 진행 상황은 [tasks/INDEX.md](tasks/INDEX.md), 머지 후 발견된 버그와 fix는 [tasks/HOTFIXES.md](tasks/HOTFIXES.md).
|
||
|
||
`kebab` 는 개인용 로컬 knowledge base + RAG 도구다. Markdown / PDF / 이미지 / 음성을 한 곳에 색인하고, 의미 검색 + citation 포함 LLM 답변을 단일 binary 로 제공한다. 모든 추론은 로컬 (Ollama / fastembed / whisper.cpp) 에서 돌아간다.
|
||
|
||
대상 하드웨어: M4 48GB MacBook 1대, 사용자 1명.
|
||
|
||
---
|
||
|
||
## 무엇인가
|
||
|
||
| 명령 | 동작 | 상태 |
|
||
|------|------|------|
|
||
| `kebab init` | XDG 경로에 데이터 디렉토리 + config.toml 생성 | ✅ P0 |
|
||
| `kebab ingest [<path>]` | Markdown / 이미지 / PDF 색인 (idempotent). 음성은 P8 (보류). | ✅ P3-5 / P6-4 / P7-3 |
|
||
| `kebab search --mode {lexical,vector,hybrid} "<query>"` | 검색 — citation 포함, hybrid는 RRF fusion. PDF chunk 의 citation 은 page 단위. | ✅ P3-5 / P7-3 |
|
||
| `kebab list docs` | 색인된 문서 목록 | ✅ P3-5 |
|
||
| `kebab inspect doc <id>` / `kebab inspect chunk <id>` | raw record 보기 | ✅ P3-5 |
|
||
| `kebab ask "<query>"` | RAG 답변 + 근거 인용. 근거 부족 시 거절. Ollama 필요. | ✅ P4-3 |
|
||
| `kebab doctor` | 설정/모델/DB 헬스 체크 | ✅ P0 |
|
||
| `kebab tui` | Ratatui 셸 — Library 패널 (search/ask/inspect 패널은 P9-2/3/4 예정) | ✅ P9-1 |
|
||
| `kebab eval run / compare` | golden query 회귀 측정 | ✅ P5 |
|
||
|
||
기계 친화 모드: 모든 명령에 `--json` 플래그. 출력은 frozen wire schema v1 (`schema_version` 필드 항상 포함, 예: `ingest_report.v1`, `search_hit.v1`, `answer.v1`, `doctor.v1`).
|
||
|
||
---
|
||
|
||
## 핵심 결정 (lock 됨)
|
||
|
||
| 결정 | 값 |
|
||
|------|-----|
|
||
| 언어 | Rust 2024 (resolver=3, edition 2024) |
|
||
| repo | Cargo workspace (single repo, 함수 호출 기반 모듈러 모놀리스) |
|
||
| 원본 저장 | filesystem + blake3 content-addressable copy (대용량은 reference + checksum) |
|
||
| metadata | SQLite + FTS5 (lexical search) |
|
||
| vector | LanceDB (embedded, model 별 분리 table) |
|
||
| Markdown parser | `pulldown-cmark` |
|
||
| embedding | `fastembed-rs` (`multilingual-e5-small`, 384d) |
|
||
| LLM | Ollama HTTP (default `qwen2.5:7b-instruct` ─ 사용자 환경에 맞춰 `gemma4:26b` 등으로 교체 가능) |
|
||
| 음성 ASR | `whisper.cpp` (via `whisper-rs`) — P8 (보류, 시스템 dep brainstorm 후) |
|
||
| OCR | Ollama vision LM (default `gemma4:e4b`) — `OcrEngine` trait 으로 Tesseract / Apple Vision 등 future swap 가능 (HOTFIXES P6-2) |
|
||
| Image caption | Ollama vision LM, runtime gate `image.caption.enabled` (default OFF) — P6-3 |
|
||
| PDF parser | `lopdf` per-page 텍스트 추출, `chunker_version = "pdf-page-v1"` 가 PDF 자산에 하드코딩 (HOTFIXES P7-3) — P7-1/7-2/7-3 |
|
||
| TUI | Ratatui + crossterm — P9-1 (Library 패널), P9-2/3/4 진행 예정 |
|
||
| Desktop | Tauri 2 + `pdfjs-dist` (native PDF render backend 금지) — P9-5 |
|
||
| citation 형식 | URI fragment (`path#L12-L34`, W3C Media Fragments) |
|
||
| ID 생성 | `blake3(canonical_json(tuple))[..32]` hex |
|
||
| RRF fusion_score | `[0, 1]` 정규화 — `2 / (k_rrf + 1)` 로 나눠 mode 간 비교 가능 (post-merge hotfix) |
|
||
| layout | XDG (`~/.local/share/kebab/`, `~/.config/kebab/`, …) |
|
||
|
||
전체는 [docs/superpowers/specs/2026-04-27-kebab-final-form-design.md](docs/superpowers/specs/2026-04-27-kebab-final-form-design.md) 참조.
|
||
|
||
---
|
||
|
||
## 의존성 그래프
|
||
|
||
```text
|
||
kebab-cli, kebab-tui, kebab-desktop
|
||
└─> kebab-app
|
||
├─> kebab-source-fs
|
||
├─> kebab-parse-md / kebab-parse-pdf / kebab-parse-image / kebab-parse-audio
|
||
│ └─> kebab-parse-types
|
||
├─> kebab-normalize
|
||
│ └─> kebab-parse-types
|
||
├─> kebab-chunk
|
||
├─> kebab-store-sqlite
|
||
├─> kebab-store-vector
|
||
├─> kebab-embed-local (kebab-embed trait crate)
|
||
├─> kebab-search
|
||
├─> kebab-llm-local (kebab-llm trait crate)
|
||
├─> kebab-rag
|
||
├─> kebab-eval
|
||
└─> kebab-config
|
||
└─> kebab-core (모두 의존)
|
||
```
|
||
|
||
UI → store/llm/parse 직접 의존 금지. 모든 user-facing 진입은 `kebab-app` facade 만 통한다 (design §8). `kebab-cli` 가 `--config <path>` flag 를 honor 하려면 `kebab_app::*_with_config(cfg, …)` companion 을 통해 Config 을 명시적으로 thread 하는 패턴 — 자세한 이유는 [tasks/HOTFIXES.md](tasks/HOTFIXES.md) 의 `--config` 항목.
|
||
|
||
---
|
||
|
||
## Phase 로드맵
|
||
|
||
| Phase | 내용 | 핵심 산출 crate | 선행 | 상태 |
|
||
|-------|------|----------------|------|------|
|
||
| **P0** | Workspace 뼈대 + 도메인 계약 + ID recipe | `kebab-core`, `kebab-parse-types`, `kebab-config`, `kebab-app`, `kebab-cli` | – | ✅ 완료 |
|
||
| **P1** | Markdown ingestion (walk → parse → chunk → SQLite) | `kebab-source-fs`, `kebab-parse-md`, `kebab-normalize`, `kebab-chunk`, `kebab-store-sqlite` | P0 | ✅ 완료 |
|
||
| **P2** | SQLite FTS5 lexical 검색 + citation | `kebab-search` (lexical) | P1 | ✅ 완료 |
|
||
| **P3** | Local embedding + LanceDB + hybrid (RRF) + kebab-app wiring | `kebab-embed`, `kebab-embed-local`, `kebab-store-vector`, `kebab-search` | P2 | ✅ 완료 |
|
||
| **P4** | Local LLM + RAG + grounded answer | `kebab-llm`, `kebab-llm-local`, `kebab-rag` | P3 | ✅ 완료 |
|
||
| **P5** | Golden query / regression eval | `kebab-eval` | P4 | ✅ 완료 |
|
||
| **P6** | 이미지 ingestion (OCR + caption) | `kebab-parse-image` | P5 | ✅ 완료 (4/4 component, OCR/caption Ollama-vision) |
|
||
| **P7** | PDF text + page citation | `kebab-parse-pdf` | P5 | ✅ 완료 (3/3 component, page-level chunker + ingest wiring) |
|
||
| **P8** | 음성 transcription + timestamp citation | `kebab-parse-audio` | P5 | ⏸ 보류 (whisper-rs 시스템 dep brainstorm 필요) |
|
||
| **P9** | TUI + desktop app | `kebab-tui`, `kebab-desktop` | P5 | 🟡 진행 (1/5 component — P9-1 Library 완료, P9-2/3/4/5 예정) |
|
||
|
||
P0~P5 직렬. P6~P9 P5 이후 병렬 가능.
|
||
|
||
각 phase 는 component-level 단위로 더 분해되어 있다 (총 33 component task — P3-5 / P6-4 / P7-3 / 등 후속 추가 포함). 자세한 분해는 [tasks/INDEX.md](tasks/INDEX.md). 머지 후 발견된 버그/fix 의 dated 로그는 [tasks/HOTFIXES.md](tasks/HOTFIXES.md).
|
||
|
||
---
|
||
|
||
## 디렉토리 구조
|
||
|
||
```text
|
||
kebab/
|
||
├── README.md # 이 파일
|
||
├── kebab_local_rust_report.md # 최초 설계 보고서 (방향성 + 근거)
|
||
├── docs/
|
||
│ ├── superpowers/
|
||
│ │ ├── specs/
|
||
│ │ │ └── 2026-04-27-kebab-final-form-design.md # frozen design (12 sections)
|
||
│ │ └── plans/
|
||
│ │ └── 2026-04-27-task-decomposition.md # task 분해 implementation plan
|
||
│ ├── SMOKE.md # 로컬 워크스페이스에 직접 돌려보는 절차
|
||
│ └── wire-schema/v1/ # JSON Schema 7 (citation, search_hit, answer, …)
|
||
├── tasks/
|
||
│ ├── INDEX.md # phase 인덱스 + component task 트리
|
||
│ ├── HOTFIXES.md # post-merge dated fix 로그
|
||
│ ├── _template.md # task spec 작성 템플릿
|
||
│ ├── phase-0-skeleton.md … phase-9-ui.md # phase epic (high-level)
|
||
│ ├── p0/p0-1-skeleton.md # component task (1)
|
||
│ ├── p1/p1-1 … p1-6 # (6)
|
||
│ ├── p2/p2-1, p2-2 # (2)
|
||
│ ├── p3/p3-1 … p3-5 # (5 — p3-5 = app-wiring, post-spec 추가)
|
||
│ ├── p4/p4-1 … p4-3 # (3)
|
||
│ ├── p5/p5-1, p5-2 # (2)
|
||
│ ├── p6/p6-1 … p6-4 # (4 — p6-4 = image-ingest-wiring 후속 추가)
|
||
│ ├── p7/p7-1 … p7-3 # (3 — p7-3 = pdf-ingest-wiring 후속 추가)
|
||
│ ├── p8/p8-1, p8-2 # (2 — 보류)
|
||
│ └── p9/p9-1 … p9-5 # (5)
|
||
├── crates/
|
||
│ ├── kebab-core/ kebab-parse-types/ kebab-config/ # 도메인 + 설정 (P0)
|
||
│ ├── kebab-source-fs/ # 워크스페이스 walk + checksum (P1-1)
|
||
│ ├── kebab-parse-md/ # Markdown frontmatter + blocks (P1-2/3)
|
||
│ ├── kebab-normalize/ # ParsedBlock → CanonicalDocument (P1-4)
|
||
│ ├── kebab-chunk/ # heading-aware chunker (P1-5)
|
||
│ ├── kebab-store-sqlite/ # SQLite + FTS5 (V001/V002/V003) (P1-6, P2-1, P3-3)
|
||
│ ├── kebab-search/ # Lexical + Vector + Hybrid retriever (P2-2, P3-4)
|
||
│ ├── kebab-embed/ kebab-embed-local/ # Embedder trait + fastembed adapter (P3-1, P3-2)
|
||
│ ├── kebab-store-vector/ # LanceDB VectorStore (P3-3)
|
||
│ ├── kebab-llm/ kebab-llm-local/ # LanguageModel trait + Ollama adapter (P4-1, P4-2)
|
||
│ ├── kebab-rag/ # RAG pipeline (P4-3)
|
||
│ ├── kebab-eval/ # golden query runner + metrics (P5-1, P5-2)
|
||
│ ├── kebab-parse-image/ # ImageExtractor + Ollama OCR + caption (P6)
|
||
│ ├── kebab-parse-pdf/ # lopdf per-page text extractor (P7-1)
|
||
│ ├── kebab-app/ # facade (P0 시그니처 + P3-5/P6-4/P7-3 본체)
|
||
│ ├── kebab-tui/ # Ratatui shell + Library 패널 (P9-1)
|
||
│ └── kebab-cli/ # binary (P0 → 핫픽스로 --config flag wiring 강화)
|
||
├── migrations/ # SQLite refinery V001/V002/V003
|
||
└── fixtures/ # 테스트 fixture 트리
|
||
```
|
||
|
||
---
|
||
|
||
## 빌드 + 실행
|
||
|
||
```bash
|
||
# build
|
||
cargo build --release
|
||
|
||
# 첫 실행 — XDG 경로에 config.toml 생성
|
||
./target/release/kebab init
|
||
|
||
# config 손보고 — `[workspace] include` 에 *.md / *.png / *.pdf 등 추가, OCR 활성화 등
|
||
${EDITOR:-vi} ~/.config/kebab/config.toml
|
||
|
||
# 색인 (Markdown / 이미지 / PDF 모두 한 번에)
|
||
./target/release/kebab ingest
|
||
|
||
# 검색 (citation 의 source_span 이 매체별로 line / region / page)
|
||
./target/release/kebab search "Markdown chunking 규칙" --mode hybrid
|
||
|
||
# 질문 (Ollama 필요, PDF 인용 시 page 번호 surface)
|
||
./target/release/kebab ask "내 KB 설계에서 저장소 전략은?"
|
||
|
||
# Ratatui 셸 (Library 패널 — j/k 이동, f 필터, q 종료)
|
||
./target/release/kebab tui
|
||
```
|
||
|
||
워크스페이스를 격리해서 직접 돌려보는 패턴은 [docs/SMOKE.md](docs/SMOKE.md) 참조 — `--config <path>` 로 임시 디렉토리에 격리된 KB 를 만들 수 있다. 이미지 / PDF fixture 가 필요하면 두 example 바이너리 (`cargo run --release --example gen_smoke_pdf -p kebab-parse-pdf` / `gen_smoke_png -p kebab-parse-image`) 로 reportlab / qpdf 같은 시스템 dep 없이 in-tree 생성 가능.
|
||
|
||
---
|
||
|
||
## 비-목표 (frozen design §11 / §0)
|
||
|
||
- 다중 사용자 SaaS, K8s 배포, 원격 vector DB
|
||
- enterprise RBAC/ABAC, 실시간 협업
|
||
- 모든 파일 포맷의 완벽한 parsing
|
||
- agent 가 임의로 파일을 수정하는 자동화
|
||
- multi-workspace (P+ 후순위)
|
||
- LLM-as-judge eval (rule-based `must_contain` 만)
|
||
- visual embedding (CLIP) — P+
|
||
- desktop app `kebab://` protocol handler — P+
|
||
|
||
---
|
||
|
||
## 외부 AI 통합
|
||
|
||
`kebab` 의 `--json` 모드 + frozen wire schema v1 은 외부 자동화의 stable contract. 가능한 통합:
|
||
|
||
1. **Claude Code / Codex skill** — 얇은 wrapper (`kebab search --json` / `kebab ask --json` 호출). ~50 lines.
|
||
2. **MCP server** — `kebab-mcp` binary (stdio JSON-RPC) 가 `kebab-app` facade 를 1:1 노출. Claude Desktop / Cursor / Zed 등 공유.
|
||
3. **HTTP wrapper** — `kebab serve --bind 127.0.0.1:7711` (P+, local-only 가치 깨므로 신중).
|
||
|
||
---
|
||
|
||
## 기여 / 작업 흐름
|
||
|
||
이 repo 는 단일 사용자 프로젝트지만 spec 변경 절차는 명문화되어 있다.
|
||
|
||
1. **frozen design 변경** — `docs/superpowers/specs/2026-04-27-kebab-final-form-design.md` 가 단일 contract. 변경 시 영향 받는 component task 모두 동시 갱신 필요. PR 1개로 묶기.
|
||
2. **새 component task 추가** — `tasks/_template.md` 복사 후 `tasks/p<phase>/p<phase>-<n>-<name>.md` 생성. `contract_sections` 에 design doc 섹션 명시. `Allowed/Forbidden dependencies` 는 design §8 module-boundary 표 따름.
|
||
3. **구현** — component task 1개당 sub-agent 1세션 권장. `cargo test -p <crate>` + DoD 체크리스트 통과. PR 으로 머지.
|
||
4. **버전 변경** — `parser_version` / `chunker_version` / `embedding_version` 등 변경은 design §9 의 cascade rule 따름. 영향 받는 record 는 재처리 필요.
|
||
5. **post-merge 핫픽스** — 머지 후 발견된 버그는 [tasks/HOTFIXES.md](tasks/HOTFIXES.md) 에 dated entry 추가 + 영향 받는 task spec 의 `Risks/notes` 에 cross-link 한 줄 추가. 원래 spec 본문은 frozen 으로 두고 HOTFIXES.md 가 live source of truth.
|
||
|
||
---
|
||
|
||
## 라이선스
|
||
|
||
미정 (frozen design 에는 `MIT OR Apache-2.0` 가 workspace.package 의 license 필드로 권장됨; P0 lock 시 결정).
|
||
|
||
---
|
||
|
||
## 참고
|
||
|
||
- 최초 설계 보고서: [kebab_local_rust_report.md](kebab_local_rust_report.md)
|
||
- Frozen design: [docs/superpowers/specs/2026-04-27-kebab-final-form-design.md](docs/superpowers/specs/2026-04-27-kebab-final-form-design.md)
|
||
- Task 분해 plan: [docs/superpowers/plans/2026-04-27-task-decomposition.md](docs/superpowers/plans/2026-04-27-task-decomposition.md)
|
||
- Task 인덱스: [tasks/INDEX.md](tasks/INDEX.md)
|
||
- Post-merge 핫픽스 로그: [tasks/HOTFIXES.md](tasks/HOTFIXES.md)
|
||
- Smoke recipe: [docs/SMOKE.md](docs/SMOKE.md)
|