v0.20.2 7fbfec647d

kebab v0.20.2 — Ask 응답언어 rag-v3 + 검색 품질 eval baseline Stable

altair823 released this 2026-05-29 05:30:00 +00:00 | 127 commits to main since this release

kebab v0.20.2 — Ask 응답언어 자동 매칭 + 검색 품질 eval 인프라

v0.20.1 (한국어 형태소 검색, 2026-05-28) 후속 patch release. 도그푸딩 8-finding 라운드에서 발견·수정된 문서/스키마/UX 표면 정비 + rag-v3 응답언어 규칙 + eval --config facade 패치를 한 번에 묶어 cut.

핵심 변경

1. Ask 응답언어 자동 매칭 (rag-v3, Finding #1 + O-2)

변경 사실: SYSTEM_PROMPT_RAG_V3 신설. rag-v2 의 7규칙 위에 "답변 언어 = 질문 언어" 규칙 추가. config [rag] prompt_template_version 의 default 가 "rag-v2" → "rag-v3" 로 변경.

# v0.20.2 기본 동작
kebab ask "What is the tokenizer?"  # → 영어 답변
kebab ask "토크나이저가 뭐야?"          # → 한국어 답변

# 이전 v3 고정하려면 (이미 default, 명시 생략 가능)
# [rag] prompt_template_version = "rag-v3"

# rag-v2 로 pin 하면 legacy 동작 (query 언어 무시)
# [rag] prompt_template_version = "rag-v2"

도그푸딩 확인: 영어 query → 영어 답변, 한국어 corpus 를 영어로 물으면 근거를 영어로 번역해 답함 (trade-off — 원문 보존이 필요하면 큰따옴표 직접 인용 규칙이 적용됨).

trade-off: 한국어 corpus 를 영어로 물을 때 LLM 이 근거를 영어로 번역해 답하므로 원문 표현이 일부 달라질 수 있다. 원문 그대로 필요하면 큰따옴표 직접 인용 ([#번호] 앞에 chunk 속 원문) 이 v3 에서도 유지된다.

Finding O-2 — refusal 언어중립화: rag-v3 system prompt 의 refusal/hedge 규칙에서 한국어 리터럴 (근거가 부족하면 "근거가 부족하다"고 답한다) 을 언어중립 표현 (근거가 부족하면 답변 언어로 근거가 부족함을 밝히고 [#번호] 인용 없이 답한다) 으로 변경.

Known limitation: gemma4:e4b 같은 소형 모델은 refusal 메시지의 언어가 query 언어와 불일치할 수 있음 (영어 query → 한국어 refusal 가능). refusal 판정 자체는 답변의 citation marker ([#번호]) 유무 기반 — 유효 marker 가 없으면 LlmSelfJudge 로 refuse 판정 — 이라 문구 언어와 무관하게 정확함 (refusal 문구 텍스트는 판정에 쓰이지 않음).

mitigation:

refusal 판정은 LLM 출력 내 marker 기반으로 항상 정상 동작.
언어 불일치가 허용 불가한 경우 "rag-v2" 로 pin (이전 동작 보존).
소형 모델 대신 gemma4:26b 등 대형 모델은 불일치 빈도가 현저히 낮음.

upgrade 절차: 기존 config 에 prompt_template_version 미명시 시 자동으로 v3 적용. v2 를 명시적으로 유지하려면 [rag] prompt_template_version = "rag-v2" 추가.

2. Bulk search input schema 확정 (Finding #2)

변경 사실: docs/wire-schema/v1/bulk_search_input.schema.json 이 15필드 완전 명세로 확정. query 누락 시 error shape hint 가 error.v1.message 에 포함됨.

# query 필수, 나머지 optional (15필드 중 1필수 + 14선택)
printf '%s\n' \
  '{"query":"한국","mode":"lexical","k":3}' \
  '{"query":"tokenizer","mode":"hybrid"}' \
  '{}' \
  | kebab search --bulk --json
# 세 번째 줄 → error.v1 (code: invalid_input, message 에 schema hint 포함)

trade-off: query 만 required, 나머지는 전부 optional + 스키마 검증은 agent 측 부담. error shape hint 로 agent 가 retry 없이 즉시 수정 가능.

mitigation: bulk cap 100 건 초과 시 즉시 error.v1 (code: too_many_queries) 반환.

upgrade: 기존 {"query":"..."} 형태는 완전 호환. 신규 optional 필드는 점진 추가 가능.

3. List docs human-readable path 보강 (Finding #3)

변경 사실: kebab list docs human-readable 출력이 title \t doc_path 에서 doc_id \t title \t doc_path 로 변경. title 중복(예: README.md + README.md) 시 doc_id 로 구분 가능.

kebab list docs
# 출력 예:
# abc123  README.md  /path/to/java/README.md
# def456  README.md  /path/to/kotlin/README.md

--json 출력 (doc_summary.v1 array) 은 wire shape 변경 없음.

trade-off: human-readable 컬럼이 늘어나 좁은 터미널에서 wrap 가능. --json 으로 programmatic 처리 권장.

4. schema `index_version` 두 곳 구분 (Finding #7)

변경 사실: schema.v1.models.index_version 과 search_hit.v1.index_version 이 서로 다른 축임을 README 및 schema description 에 명시.

schema.v1.models.index_version = vector store (LanceDB) version.
search_hit.v1.index_version = lexical (FTS5) version.

cascade 에서 별도 추적 — 둘 중 하나가 변경돼도 나머지에 영향 없음.

upgrade: 기존 consumer 가 index_version 을 단일값으로 읽는 경우 fieldpath 확인 필요.

5. eval `--config` facade 패치 + 검색 품질 baseline 인프라

변경 사실: kebab eval run / aggregate / compare 가 --config <path> 를 honor. 이전에는 eval 이 XDG default config 만 읽어 dogfood KB (/build/dogfood/config.toml) 를 직접 평가할 수 없었음.

# v0.20.2: dogfood KB 에서 직접 eval
KEBAB_EVAL_GOLDEN=/build/dogfood/golden_queries.yaml \
  kebab --config /build/dogfood/config.toml eval run --mode hybrid --k 10

검색 품질 baseline (v0.20.2, /build/dogfood/golden_queries.yaml 10 query):

Mode	hit@1	hit@3	hit@10	MRR	recall@10	empty
hybrid	0.7	1.0	1.0	0.833	1.0	0
lexical	0.4	1.0	1.0	0.7	1.0	0

hybrid 가 vector 덕분에 top-1 정확도 우위. hit@3 이후는 두 모드 모두 완벽. 현재 ranking 조정 없이 달성 ([[project_ranking_deferred]] 결정 유효).

golden 큐레이션 교훈: 초기 dispatch.py 정답을 note 로만 한정한 것이 오류. eval 분해 시 vector 가 영어 docstring dispatch.py 를 top-1 으로 반환함을 발견, 정답에 추가 후 hit@3 0.9→1.0 개선. 교훈: golden answer 는 "note 의 intent" 뿐 아니라 "합리적으로 관련된 모든 doc" 을 포함해야 함.

trade-off: --config 패치가 facade rule (kebab-cli → kebab-app *_with_config) 의 eval 적용. 누락 시 dogfood KB 와 XDG KB 의 결과가 섞여 eval 결과 오염.

upgrade: 기존 kebab eval 호출은 동작 변경 없음 (config 미명시 → XDG default 그대로).

6. 기타 docs/schema 정비 (Finding #4 · #5/#6 · #8)

Finding #4 — doc.lang semantic 명시: lang = "und" 는 소스코드 doc 의 정상 상태임을 README + schema description 에 명시. lingua 가 자연어 감지 대상 아님을 lang_breakdown 해석 가이드에 추가.

Finding #5/#6 — fusion_score / score_kind: search_hit.v1 의 fusion_score / lexical_score / vector_score / lexical_rank / vector_rank 가 모두 retrieval object 내부에 있음 (top-level 아님) 을 README 및 schema description 에 명시. 단일 mode (lexical/vector) 에서 score == fusion_score == (lexical|vector)_score 가 같은 값인 이유도 설명.

Finding #8 — kebab init Ollama endpoint hint: kebab init 이 생성하는 config.toml 에 [models.llm] endpoint 의 default 주석에 remote Ollama host 예시 추가.

Version cascade 주의

Version field	v0.20.1	v0.20.2
`prompt_template_version` default	`"rag-v2"`	`"rag-v3"`
wire schema shape	unchanged	unchanged (additive description only)
`eval config_snapshot_json`	`prompt_template_version: "rag-v2"`	`prompt_template_version: "rag-v3"`

eval compare 주의: v0.20.1 eval run 과 v0.20.2 eval run 을 eval compare 할 때 prompt_template_version 이 다르므로 config_snapshot 이 다름. eval runner 가 snapshot 불일치를 경고하지 않으면 metric 변화의 원인이 rag 버전인지 corpus 변화인지 구분 불가. 정확한 비교는 [rag] prompt_template_version = "rag-v2" 로 pin 후 re-run.

Breaking changes / 사용자 영향

prompt_template_version default 변경 (rag-v2 → rag-v3): 영어로 묻는 경우 영어로 답함. config 에 prompt_template_version 미명시한 사용자는 자동 적용. 이전 동작 유지는 "rag-v2" 명시.
소형 모델 refusal 언어 불일치 known limitation: gemma4:e4b 사용자는 refusal 메시지 언어가 가끔 틀릴 수 있음. 정확도(판정)는 영향 없음.

Upgrade 절차

# 1. binary 교체
git fetch && git checkout v0.20.2
cargo build --release -p kebab-cli -j 4

# 2. rag-v3 동작 확인
kebab ask "What is the tokenizer?" --hide-citations  # 영어 응답 기대
kebab ask "토크나이저가 뭐야?" --hide-citations        # 한국어 응답 기대

# 3. eval baseline 측정 (선택)
KEBAB_EVAL_GOLDEN=/build/dogfood/golden_queries.yaml \
  kebab --config /build/dogfood/config.toml eval run --mode hybrid --k 10

References

HOTFIXES entry: tasks/HOTFIXES.md 2026-05-29
DOGFOOD scenarios: docs/DOGFOOD.md §3.6 + §10.2
eval --config facade: CLAUDE.md "The facade rule"
Golden queries: /build/dogfood/golden_queries.yaml
Eval logs: /build/dogfood/logs/eval-{hybrid,lexical}-v0.20.2.json

Downloads

v0.19.0 c1e82cca92

v0.19.0 Stable

altair823 released this 2026-05-26 23:31:49 +00:00 | 234 commits to main since this release

변경사항 (since v0.17.2)

#187 refactor(app): extract dispatch polymorphism — App.extract_for(...) + 11 Extractor registry
#186 refactor(parse-md): absorb kebab-normalize + kebab-parse-types — 24 → 22 crates + §3.7b 재작성
#185 refactor(source-fs): drop kebab-parse-code dep — 9 tree-sitter grammars drag 제거
#184 fix(rag): S3 NLI unavailable — hypothesis char budget + token-count fallback retry
#183 fix(mcp): HOTFIX #15 — MCP ask multi_hop dispatch-divergence assertion (fixture 보강)
#182 chore(release): bump version 0.17.2 → 0.18.0 + cut fb-41 multi-hop
#181 chore: workspace-wide cleanup — clippy::pedantic baseline + auto-fix
#180 feat(rag): fb-41 PR-9d — dogfood retest + HOTFIXES closure + corpus 보존
#179 feat(rag): fb-41 PR-9c-2 — pipeline integration + mock test + SKILL.md (★ NLI 실 활성화)
#178 feat(rag): fb-41 PR-9c-1 — core types + wire scaffolding (NLI verification)
#177 feat(nli): fb-41 PR-9b — OnnxNliVerifier ONNX inference + model download
#176 feat(nli): fb-41 PR-9a — kebab-nli crate skeleton + workspace deps
#175 fix(rag): fb-41 PR-8 multi-hop synthesize safety in depth (pool 15 + self-check rule)
#174 fix(rag): fb-41 PR-7 multi-hop pre-decompose score-gate (S7 hallucination 회귀 핀)
#173 feat(tui): fb-41 PR-6 TUI Ask multi-hop toggle + hop trace summary
#172 feat(mcp): fb-41 PR-5 MCP ask multi_hop arg + SKILL.md 안내
#171 feat(cli): fb-41 PR-4 CLI --multi-hop flag + answer.v1 / error.v1 wire
#170 feat(rag): fb-41 PR-3b-ii ScriptedLm + multi-hop tests + refusal hop trace
#169 feat(rag): fb-41 PR-3b-i dynamic decide loop + helpers
#168 feat(rag): fb-41 PR-3a HopRecord wire + RagCfg multi-hop knobs
#167 feat(rag): fb-41 PR-2 ask_multi_hop skeleton (fixed depth=2)
#166 feat(eval): fb-41 multi-hop golden set + spec/plan

개요

v0.19.0 은 internal refactor 위주 minor release — 사용자 visible CLI / TUI / MCP / --json 출력 / config / XDG path 변경 0. design contract kebab-final-form-design.md §3.7b 재작성 trigger 로 minor bump (0.18.0 → 0.19.0).

3 sub-item (PR #185 + #186 + #187 통합)

PR #185 — kebab-source-fs 의 kebab-parse-code dep 제거. 9 tree-sitter grammars drag 정리. code_lang_for_path / is_generated_file / is_oversized / BUILTIN_BLACKLIST 4 leaf helper 가 kebab-source-fs::code_meta 로 이전.
PR #186 — kebab-normalize + kebab-parse-types 흡수 → kebab-parse-md. 24 → 22 crates. design §3.7b 4-단락 재작성 (frozen contract — original intent + reality + 보존된 surface + future re-extraction trigger). tasks/INDEX.md "Future work / deferred" 섹션 신설.
PR #187 — Extractor dispatch polymorphism. App.extractors: Vec<Box<dyn Extractor + Send + Sync>> registry (11 entry — image + pdf + 9 AST) + App::extract_for(...) helper. 11 hardcoded callsite + 9 AST arm match → 1 callsite + 4 arm.

Bug fix

PR #183 — HOTFIX #15 MCP tools_call_ask_multi_hop dispatch divergence assertion (fixture 보강).
PR #184 — S3 NLI unavailable: mDeBERTa-v3 tokenizer 의 OnlyFirst strategy + 949-token hypothesis 의 root cause. hypothesis char budget + token-count fallback retry.

도그푸딩

통합 KB 1781 doc / 9050 chunks (기존 1770 + 새 fixture 11). 7 종 code AST extractor 모두 polymorphic dispatch routing 정확. multi-hop NLI gate (fb-41) 의 decompose → decide → synthesize → NLI verify 4-stage pipeline 동작 확인.

v0.20.0 future-work

image / pdf 의 미구현 부분 (PDF scanned OCR / multi-region image / PDF normalize integration / per-page figure-table extraction 등 8 TODO) 의 핸드오프 문서 — docs/superpowers/handoffs/2026-05-26-v0.20-image-pdf-normalize-handoff.md.

Wire schema

변경 0 (success path): ingest_report.v1 / search_response.v1 / answer.v1 / bulk_search_item.v1 / citation.v1 / chunk_inspection.v1 / doctor.v1 / schema.v1 모두 byte-identical
error.v1.message 의 internal context string wording 변경은 PR #187 의 spec §5.5 risk acceptance (error.v1.code + error.v1.schema_version 보존)

Binary

target/release/kebab (linux x86_64, ~274 MB)

Downloads

v0.18.0 08495eb425

v0.18.0 Stable

altair823 released this 2026-05-26 05:37:47 +00:00 | 245 commits to main since this release

v0.18.0 — fb-41 multi-hop RAG ship + NLI verification

post-PR-8 의 dogfood 에서 발견된 S7 caffeine hallucination 의 root cause = LLM-self-judge ceiling. 본 release 가 deterministic external verifier (mDeBERTa-v3 XNLI ONNX) 로 close. 학계 표준 (Self-RAG, CRAG, Auto-GDA, MedTrust-RAG) 정합.

새 surface

CLI: kebab ask --multi-hop <query> — multi-hop reasoning (decompose → decide → synthesize loop).
MCP: ask tool 의 multi_hop: true argument.
TUI: Ask 패널 의 F2 toggle + multi-hop badge + hops summary inline.

새 wire (additive minor — pre-v0.18 reader 무영향)

answer.v1.hops — multi-hop per-iter trace ({kind, iter, sub_queries, context_chunks_added, llm_call_ms, forced_stop} per element).
answer.v1.verification — NLI groundedness summary ({nli_score, nli_threshold, nli_passed}, present only when cfg.rag.nli_threshold > 0).
error.v1.code enum 확장: multi_hop_decompose_failed, nli_verification_failed, nli_model_unavailable.

새 config

[rag] nli_threshold (default 0.0 = disabled; production 권장 0.5).
[models.nli] model (default Xenova/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7).
[models.nli] provider (default onnx — only impl in v0.18; v0.19+ candle/remote candidate).
env override: KEBAB_RAG_NLI_THRESHOLD, KEBAB_MODELS_NLI_MODEL, KEBAB_MODELS_NLI_PROVIDER.

새 RefusalReason

multi_hop_decompose_failed (LLM decompose JSON parse fail).
nli_verification_failed (entailment < nli_threshold).
nli_model_unavailable (download / inference 실패 — fail-closed; 사용자 우회 = [rag] nli_threshold = 0).

권장 환경

LLM: gemma3:4b (CPU only, 16 GB RAM 권장).
NLI 활성화 시: ~280 MB first-run download to {data_dir}/models/nli/Xenova_mDeBERTa-v3-base-xnli-multilingual-nli-2mil7/.
RAM peak (NLI + Ollama 동시, gemma3:4b 기준): ~7-8 GB (dogfood 실측, ONNX session ~600 MB 추가). 16 GB 환경 안전.
8B+ Q4 모델 (gemma4:e4b 8B / gemma2:9b 등): 추정 peak ~10 GB — 16 GB 경계, OOM 위험.

Known limitations (v0.18.1+ priority)

single-pass ask 는 NLI 미적용 (LlmSelfJudge 유지). multi-hop 만 step 8.5 gate.
atomic claim split 미적용 — entire answer 가 1 NLI call (paraphrase / multi-claim 답변의 평균 entailment 사용).
GPU acceleration 미지원 (CPU ONNX runtime).
S3 류 query (특정 input dependent nli_model_unavailable) consistent fail — v0.18.1 follow-up (HOTFIXES 의 fb-41 PR-9 closure entry 의 S3 subsection 참조).

도그푸딩

docs/dogfood/v0.18.0/SUMMARY.md + 4 sample wire JSON (S7 / S1 / S3 / S10 multi-hop ask 결과). 핵심: S7 caffeine hallucination root cause 해결 확정 — PR-8 baseline grounded=true + Adam gradient hallucination (silent) → PR-9 refusal_reason=nli_verification_failed, nli_score=0.0035 (graceful).

Sub-PR sequence

PR #176 PR-9a — kebab-nli crate skeleton + workspace deps (ort 2.0-rc.9 / tokenizers 0.21 onig / hf-hub 0.4 / ndarray 0.16).
PR #177 PR-9b — OnnxNliVerifier ONNX inference + lazy hf-hub download.
PR #178 PR-9c-1 — core types + wire scaffolding (RefusalReason::Nli* + Answer.verification + RagPipeline.verifier + config knobs).
PR #179 PR-9c-2 — pipeline integration ★ NLI 실 활성화 (step 8.5 hook + App::open_with_config NLI verifier construction + 5 mock multi-hop tests + SKILL.md).
PR #180 PR-9d — dogfood retest + HOTFIXES closure + docs/dogfood/v0.18.0/ 보존.
PR #181 cleanup — workspace-wide clippy::pedantic baseline + post-PR9 refactor (H1 config wiring + 9 new tests).
PR #182 cut — version bump + cascading docs.

Cascade rule

v0.18.0 release 후 kebab.sqlite schema / wire schema 의 breaking 변경 없음 (additive minor only). 사용자 작업 불필요 — 기존 ingest / config 모두 호환.

Downloads

v0.17.2 1640ecf288

v0.17.2 Stable

altair823 released this 2026-05-25 05:56:21 +00:00 | 296 commits to main since this release

변경사항 (since v0.17.0)

#165 feat(search): heading_path FTS5 text column filter
#164 feat(ocr): request_timeout_secs config knob
#163 docs: sudo 없이 ollama 설치 + ask --stream 권장 (v0.17.0 post-dogfood)
#162 feat: [models.llm] request_timeout_secs config + 권장 모델 가이드

v0.17.2 — v0.17.1 post-dogfood polish

v0.17.1 (PR #162) 의 두 미진행 follow-up 을 한 patch release 로 묶음. additive only — 옛 config / wire 호환, 기존 사용자는 binary 만 교체.

변경

[image.ocr] request_timeout_secs config 노브 (PR #164) — crates/kebab-parse-image/src/ocr.rs::REQUEST_TIMEOUT hard 300s 제거. v0.17.1 의 [models.llm] request_timeout_secs 패턴을 OCR 어댑터에 동일 적용. 별 노브로 분리 한 이유 (사용자 결정): OCR 과 LLM 의 cold start / latency 패턴이 달라 16 GB / CPU only 환경에서 vision 모델만 다른 timeout 을 쓰기 편함. env override KEBAB_IMAGE_OCR_REQUEST_TIMEOUT_SECS. 0 은 disable 아닌 "즉시 timeout" (LlmCfg sister doc 과 일관). v0.17.1 의 첫 번째 미진행 항목 closure.
heading_path FTS5 column filter (PR #165) — chunks_fts 의 heading_path 컬럼 (V002/V007 트리거가 chunks.heading_path_json 을 그대로 INSERT) 의 JSON 표기 ([, ", ,) + path 세그먼트 (app, src) 가 trigram tokenizer 에서 색인되어 query 가 우연히 false positive hit 하던 문제. crates/kebab-search/src/lexical.rs::build_match_string 가 non-raw 분기 결과를 text : (<expr>) 로 wrap — heading 색인 V007 verbatim 그대로 유지 (디스크 크기 변화 없음), 매칭 대상만 text 컬럼 한정. 사용자가 heading 검색 의도시 raw mode 'heading_path : <token>' 로 opt-in (escape hatch). integrations/claude-code/kebab/SKILL.md 의 search 절에 안내 추가. 2026-05-24 v0.17.0 trigram tokenizer entry 의 heading_path_json JSON 노이즈 closure.

영향

config: 옛 config 의 [image.ocr] 섹션에 request_timeout_secs 가 없어도 그대로 파싱 + default 300s (#[serde(default)]).
wire schema: search_response.v1 의 shape 변경 없음. schema.v1 / error.v1 / ingest_report.v1 모두 v0.17.1 호환.
DB / re-ingest: 불필요. V008 migration 없음. heading_path 색인은 그대로, query 시점 매칭 범위만 변경. OCR timeout 은 client builder 단의 변경.
agent / Claude Code skill: SKILL.md 의 column scoping bullet 한 줄 추가로 heading 검색 escape hatch 안내. raw mode 가 이미 documented surface 라 신규 wire 호환성 문제 없음.

Cross-link

HOTFIXES 2026-05-25 v0.17.2 OCR timeout entry (PR #164)
HOTFIXES 2026-05-25 v0.17.2 heading text column filter entry (PR #165)
v0.17.0 release notes — 한국어 trigram tokenizer �� JSON 노이즈가 본 release 에서 closure
v0.17.1 release notes — LLM timeout 노브 + ollama 설치 가이드 (sister knob)

Downloads

v0.17.1 0c69b9621b

v0.17.1 Stable

altair823 released this 2026-05-25 03:34:49 +00:00 | 305 commits to main since this release

변경사항 (since v0.16.1)

#163 docs: sudo 없이 ollama 설치 + ask --stream 권장 (v0.17.0 post-dogfood)
#162 feat: [models.llm] request_timeout_secs config + 권장 모델 가이드
#161 feat: v0.17.0 PR-C — code_lang_chunk_breakdown additive wire field
#160 feat: v0.17.0 PR-B — C typedef-wrapped struct/enum/union → typedef alias unit
#159 feat: v0.17.0 한국어 trigram FTS tokenizer + lexical builder + hint surface

v0.17.1 — post-dogfood docs/config polish

v0.17.0 후 사용자 확장 도그푸딩 (16 GB CPU only 환경, gemma4:e4b 시도) 에서 발견된 두 follow-up 을 한 patch release 로 묶음. additive only — 기존 config / wire 호환, 기존 사용자는 binary 만 교체.

변경

[models.llm] request_timeout_secs config 노브 (PR #162) — 기존 hard-coded 300 s 한도 (crates/kebab-llm-local/src/ollama.rs::REQUEST_TIMEOUT) 를 config 로 빼냄. 옛 config 가 키 누락해도 그대로 파싱 + 동일 동작 (#[serde(default = "default_llm_request_timeout_secs")], default 300). env override KEBAB_MODELS_LLM_REQUEST_TIMEOUT_SECS. 큰 모델 시도 시 [models.llm] request_timeout_secs = 1200 같이 늘리면 됨. = 0 은 disable 이 아니라 "즉시 timeout" 이라 doc 에 명시 — "사실상 무제한" 의도면 u64::MAX 또는 86400 같이 큰 finite 값 사용.
권장 모델 가이드 + ollama 설치 + ask --stream (PR #162 + #163) — README 사전 요구 절 + docs/SMOKE.md ollama section 에 네 sub-bullet:
- CPU only / RAM ≤ 16 GB ⇒ ≤ 4B Q4 모델 권장 (gemma3:4b / qwen2.5:3b / phi3:mini). gemma4:e4b 같은 8B+ 는 5분 timeout 한도에 걸리기 쉽다는 사전 안내.
- request_timeout_secs 노브 사용법 + 0-edge 주의.
- sudo / systemd 없이 격리 디렉토리에 ollama 설치 (tarball + OLLAMA_MODELS env). 도그푸딩 머신에서 /build/cache/ollama 패턴으로 검증.
- cold start 가 긴 모델은 kebab ask --stream (fb-33) 권장 — progressive 토큰 surface 로 사용자 체감 개선.

Breaking / cascade

없음. config field 추가는 backward-compat (default 300), README/SMOKE 갱신은 docs only. v0.16.x → v0.17.1 도 그대로 (V007 자동 backfill 동일).

미진행 (next round)

crates/kebab-parse-image/src/ocr.rs 의 동일한 hard-coded 300 s — default config 가 LLM + OCR 둘 다 gemma 사용 시 OCR 도 한도. 다음 round 에 같은 노브 (또는 별 노브) 로 재검토.

Verification

신규 unit test 3 (default / env override / legacy config backward-compat) + workspace cargo test -j 1 + clippy green.
확장 도그푸딩 (HOTFIXES 2026-05-25) 의 운영 시나리오 그대로.

Downloads

v0.17.0 fa9f91ead4

v0.17.0 Stable

altair823 released this 2026-05-24 20:53:11 +00:00 | 313 commits to main since this release

변경사항 (since v0.16.0)

#161 feat: v0.17.0 PR-C — code_lang_chunk_breakdown additive wire field
#160 feat: v0.17.0 PR-B — C typedef-wrapped struct/enum/union → typedef alias unit
#159 feat: v0.17.0 한국어 trigram FTS tokenizer + lexical builder + hint surface
#158 fix(dogfood): k8s multi-resource YAML chunk_id collision
#157 chore(p10-1d-followup): reviewer nit cleanup — C extractor tests + HOTFIXES + cpp snapshot

v0.17.0 — Korean trigram + C typedef alias + chunk-count stats

P10 종합 도그푸딩 round 2 (2026-05-22) 의 세 follow-up 동시 cut.
PR-A (한국어 trigram) 가 본체, PR-B (C typedef) + PR-C (additive wire) 가 sister.

Breaking — release 트리거

FTS5 tokenizer unicode61 → trigram (V007 migration, 자동 backfill).
- 한국어 --mode lexical 가 3자 이상 substring 매칭으로 정상 동작 (이전엔 0 hit).
- 해시 충돌 같은 multi-token Korean query 가 lexical.rs::build_match_string trigram-aware 재설계로 whole-phrase 후보로 hit.
- 영어 lexical 도 substring 매칭 (token 이 tokenizer 도 hit) — recall ↑, 단어 경계 ↓.
- 2자 이하 query 는 0-hit + CLI stderr [hint] 3자 이상 키워드 권장 (trigram tokenizer 제약) + TUI status bar + wire search_response.v1.hint 필드. raw FTS5 single-quote mode ('...') 는 사용자 명시 의도이므로 hint 안 나옴.
- kebab.sqlite 파일 크기 ~2-5배 또는 수백 MB 증가 (trigram index).
- 사용자 작업 불필요 — v0.17.0 binary 가 기존 KB 를 열면 V007 자동 적용 (re-ingest 없음).
C parser_version code-c-v1 → code-c-v2 (typedef alias cascade).
- typedef struct {...} Foo; / typedef enum {...} Bar; / typedef union {...} Baz; 의 alias 가 Citation::Code.symbol 으로 search 노출.
- 같은 file 의 옛 doc/chunks/LanceDB vector 는 신규 same-workspace_path orphan purge cascade 가 자동 정리 (stale_chunk_ids_for_workspace_path_except_doc_id + purge_document_at_workspace_path_except_doc_id helper).
- 사용자 작업 불필요 — 다음 kebab ingest 가 자동 재처리.

Additive — wire breaking 아님

search_response.v1.hint: Option<String> — 위 한국어 안내가 wire 위에 라이드. MCP / agent 가 같은 query 재시도 대신 사용자에게 surface 가능.
schema.v1.stats.code_lang_chunk_breakdown: { <lang>: <chunk_count> } — 기존 code_lang_breakdown (doc count) 와 sister. indexing 압력 metric (한 PDF spec → 200 chunks vs 한 Rust file → 5 chunks).
기존 code_lang_breakdown / repo_breakdown JSON schema description 의 "code chunk count" 오기재 → "doc count" 로 정정 (실제 구현은 처음부터 doc count).

Doc surface

README 검색 명령 행: trigram 동작 + hint + 디스크 용량 1 줄.
HANDOFF 머지 후 발견 deviation 절: 2026-05-24 entry 3개 (trigram / typedef / additive).
HOTFIXES 2026-05-22 / 2026-05-21 typedef 항목 closure.
docs/SMOKE.md "한국어 trigram 검색 (v0.17.0)" 새 절.
integrations/claude-code/kebab/SKILL.md search 절에 hint 필드 안내 한 줄.

Verification

workspace test (-j 1, 모든 18 crate) + clippy (-D warnings) green.
격리 도그푸딩 (6 fixture / Korean MD ×2 + English MD ×1 + C/Rust/Python ×1 each) 에서 12 시나리오 0 오류 — 한국어 trigram 7 case + C typedef 8 block 분포 + schema additive + incremental ingest skip.

Closes HOTFIXES 2026-05-22 (한국어 lexical) + 2026-05-22 (code_lang_breakdown chunk granularity) + 2026-05-21 (C typedef-wrapped struct).

Downloads

v0.16.1 a0c0dca321

v0.16.1 Stable

altair823 released this 2026-05-21 23:58:19 +00:00 | 331 commits to main since this release

Patch: k8s multi-resource YAML chunk_id collision fix

P10 종합 도그푸딩에서 발견한 HIGH 우선순위 버그 fix.

Bug

한 파일에 2+ k8s document (예: Deployment + Service, --- 구분) 인 YAML 이 ingest 실패 — UNIQUE constraint failed: chunks.chunk_id. document row 는 생성되나 chunk 0개 → 검색 불가.

Root cause

tier2_shared::push_chunks_with_oversize 의 non-oversize 분기가 split_key = None 하드코딩. K8sManifestResourceV1Chunker 가 resource 마다 호출 — 같은 document 의 모든 resource 가 doc_id + chunker_version + base_policy_hash 공유 + split_key = None → 동일 id_hash → 동일 chunk_id. p10-3 의 code_text_paragraph_v1 가 같은 버그였고 df3c5b8 에서 fix 됐지만, 그건 build_chunk_no_symbol 직접 호출 경로 — push_chunks_with_oversize 경로는 미수정으로 남아 있었음.

Fix

push_chunks_with_oversize 에 base_split_key: Option<u32> 파라미터 추가. k8s chunker 가 Some(resource.line_start) 전달 → resource 별 distinct chunk_id. dockerfile / manifest 는 None (파일당 1 chunk, 충돌 없음, chunk_id 불변).

Deviation note (HOTFIXES 2026-05-21)

single-resource k8s YAML 의 chunk_id 도 None → Some(1) 으로 바뀜. chunker_version 은 의도적으로 bump 안 함 — p10-2 가 v0.14.0 (~~1주 전) 머지된 dogfood 단계라 prod KB 없음. v0.14.0~~v0.16.0 사이 single-resource k8s 색인 KB 는 re-ingest 시 old chunk 가 orphan 될 수 있으나 (UNIQUE 충돌 아님), kebab reset 또는 re-ingest sweep 으로 정리. 자세한 내용은 tasks/HOTFIXES.md 2026-05-21 entry.

Regression coverage

k8s_multi_doc_emits_one_chunk_per_resource 에 chunk_id distinctness assertion 추가.
신규 integration test tier2_k8s_multi_resource_yaml_ingests_without_collision — 실 2-document YAML end-to-end. git stash 로 fix 전 실제 fail 확인.

Stats

PR #158 — code-reviewer APPROVE → 머지 (a0c0dca).
cargo test -p kebab-chunk + code_ingest_smoke 19 tests PASS, clippy clean.
patch bump 0.16.0 → 0.16.1 (bug fix only — no wire schema change, no DB migration).

Downloads

v0.16.0 75a4207aa1

v0.16.0 Stable

altair823 released this 2026-05-21 15:49:22 +00:00 | 339 commits to main since this release

p10-1D: C + C++ AST chunkers + missing p10-3 fix

P10 Tier 1 chunker family complete (Rust + Python + TS + JS + Go + Java + Kotlin + C + C++). Tier 2 (k8s + dockerfile + manifest) + Tier 3 (paragraph fallback) 도 활성. P10 Phase 의 chunker 작업 일단락.

Surface changes (dogfood-visible)

code-c-ast-v1 — .c / .h AST chunker via tree-sitter-c 0.24.2. Top-level units: function_definition / struct_specifier / enum_specifier / union_specifier (named). C symbol = function name only (parse_record). 매크로 + typedef + global 변수는 <top-level> glue.
code-cpp-ast-v1 — .cpp / .cc / .cxx / .hpp / .hh / .hxx AST chunker via tree-sitter-cpp 0.23.4. Recursive namespace + class nesting. Symbol = namespace::Class::method (예: kebab::chunk::Foo::bar). Anonymous namespace → <anonymous>. Constructor (Class::Class) / destructor (Class::~Class) / operator overload (Class::operator+, Class::operator(), Class::operator bool) / template fn (params 미포함) / qualified_identifier out-of-class def (void Foo::bar(){}) 모두 정확히 처리.
.h → C dispatch (design §3.5). C++ syntax (namespace / template / class) 만나면 tree-sitter-c parse 실패 → Tier 3 fallback (code-text-paragraph-v1) 자동 picked up.
새 --code-lang 값: c / cpp.
새 Citation::Code.lang 값: c / cpp.
schema.v1.stats.code_lang_breakdown 에 c / cpp 카운트 자동 등장.

Critical: lands missing p10-3 try_skip_unchanged fix

v0.15.0 (p10-3) release notes 의 follow-up note 에 명시되어 있던 try_skip_unchanged fallback-aware fix 가 실제로 main 에 머지되지 못함 — PR #155 의 implementer 가 commit SHA (2a39513) 를 보고했지만 그 commit 이 actual git history 에 존재하지 않았음. v0.15.0 의 비-k8s YAML / invalid YAML / AST 실패 케이스가 매 ingest 마다 re-extract + re-chunk + re-embed 됐다 (idempotent re-ingest 가 깨짐).

이 PR 의 commit 1034de2 가 그 fix 를 verbatim 으로 land:

try_skip_unchanged 7th param fallback_chunker_version: Option<&ChunkerVersion> 추가.
stored_is_tier3_fallback detection (last_chunker_version == fbv && parser_version == "none-v1") → parser/chunker equality 우회, embedder check 만 유지, stored doc 의 version 으로 IngestItem::Unchanged 반환.
모든 call site (md / image / pdf 는 None, code 는 tier3_fallback_cv) 갱신.
2 regression test: tier3_yaml_fallback_reingest_is_unchanged + tier3_shell_reingest_is_unchanged 가 invariant 보장.

v0.16.0 부터 fallback path 의 reingest 가 정상으로 Unchanged 반환.

Wire schema

Additive — Citation::Code.lang 의 c / cpp 값 + chunker_version 의 code-c-ast-v1 / code-cpp-ast-v1 값. schema 본문 변경 0.

Frozen design

2026-04-27-kebab-final-form-design.md §10 활성화 로그 p10-1D entry 추가.
§3.4 / §3.5 의 C/C++ 행은 이미 본 결정과 일치 — 추가 변경 없음.

DB / migration

없음.

Followups (non-blocking, code-reviewer flagged)

C extractor 의 in-file unit test 부족 (snapshot test 가 hand-built doc 사용). 실 dogfood + 향후 별 PR 보강 검토.
typedef-wrapped struct/enum (typedef struct { ... } Foo;) — anonymous inner struct → glue 처리. spec/risks 와 일치하지만 일반적 C idiom 이라 향후 HOTFIXES 검토 후보.
C++ snapshot 의 hand-built fixed_doc() 가 actual extractor 출력 (~9 chunks) 보다 단순 (5 chunks). chunker 의 1:1 mapping 검증엔 충분하지만 weak proxy. integration smoke 가 일부 cover.
C/C++ chunker bodies 가 9 tier1 chunkers 와 동일 패턴의 322-line duplicate. shared helper 검토는 모든 9 chunker 동시 진행 시.

Branch / PR

PR: #156 — code-reviewer APPROVE → 머지 (merge commit 75a4207).
Spec: tasks/p10/p10-1d-c-cpp-ast-chunker.md. Plan: docs/superpowers/plans/2026-05-21-p10-1d-c-cpp-ast-chunker.md.

Stats

26 files changed, +4051 / -40.
cargo test --workspace --no-fail-fast -j 1 PASS. cargo clippy --workspace --all-targets -- -D warnings clean.
신규 테스트: kebab-parse-code 의 cpp.rs 15 in-file unit tests + kebab-chunk 의 c/cpp snapshot tests + kebab-app code_ingest_smoke 18 tests (16 + tier1_c + tier1_cpp).

Downloads

v0.15.0 7a90df1485

v0.15.0 Stable

altair823 released this 2026-05-21 12:28:05 +00:00 | 353 commits to main since this release

p10-3: Tier 3 paragraph + line-window fallback

New code-text-paragraph-v1 chunker — paragraph + line-window split for shell scripts and as a fallback for Tier 1/2 0-chunk / Err results.

Surface changes (dogfood-visible)

새 chunker code-text-paragraph-v1 — blank-line paragraph segmentation + 80-line / 20-overlap line-window split for paragraphs > 80 lines. symbol = None, lang preserved from input.
shell direct routing: .sh / .bash / .zsh 파일이 ingest_one_code_asset 의 새 "shell" arm 으로 Tier 3 chunker 에 직결.
Tier 1/2 → Tier 3 fallback wrapper: Tier 1/2 chunker 가 Ok(empty) (예: p10-2 의 비-k8s YAML / invalid YAML) 또는 Err 면 자동으로 Tier 3 retry. extract 가 Err (Tier 1 extractor 실패) 도 동일 fallback. retry 시 chunker_version → "code-text-paragraph-v1" + canonical.parser_version → "none-v1" swap 으로 downstream stamping 일관.
--code-lang shell filter 옵션 추가.
fallback path 의 try_skip_unchanged 정확성 (review fix): 동일 파일 re-ingest 시 Unchanged 정상 동작. 이전 fix 전에는 매 ingest 가 Updated 로 보고되어 embedder 가 매번 호출되는 잠재 비용 — 동일 PR fix 로 해결. tier3_yaml_fallback_reingest_is_unchanged regression test 가 invariant 보장.

Wire schema

Additive — Citation::Code.lang 의 "shell" 값 + Citation::Code.symbol = null 의 Tier 3 chunk 들이 새로 등장. chunker_version 의 "code-text-paragraph-v1" 값 등장. wire schema 본문 변경 0.

Frozen design

2026-04-27-kebab-final-form-design.md §10 활성화 로그에 p10-3 entry 추가.
code_lang_for_path (design §3.5) 의 shell 매핑은 1A-1 시점부터 이미 존재 — 변경 없음.

DB / migration

없음.

Followups (non-blocking, code-reviewer flagged)

tier3_fallback_cv 매핑이 explicit list (lang 추가 시 list 갱신 필요) — 미래 Tier 1/2 lang 추가 시 maintenance footgun. parser_version match 가 unknown lang 을 bail!하므로 live bug 는 아님.
Tier 3 chunker 의 policy_hash 가 paragraph 마다 재계산 (Tier 2 의 hoisted-once 패턴과 다름). 성능 영향 미미하지만 일관성 위해 별 PR 검토.
text_doc test helper 의 ParserVersion("code-text-paragraph-v1") 는 cosmetic 부정확 — 실제로는 "none-v1". 별 PR.

Branch / PR

PR: #155 — code-reviewer 가 critical issue 발견 → in-PR fix → APPROVE → 머지 (merge commit 7a90df1).
Spec: tasks/p10/p10-3-tier3-paragraph-fallback.md. Plan: docs/superpowers/plans/2026-05-21-p10-3-tier3-paragraph-fallback.md.

Stats

19 files (PR meta) — Tier 3 모듈 1개, helper 추가, ingest dispatch + fallback wrapper, 6 docs, frozen design, version bump.
cargo test --workspace --no-fail-fast -j 1 PASS, cargo clippy --workspace --all-targets -- -D warnings clean.
신규 테스트: kebab-chunk 4 unit (paragraph split / line-window / empty / lang preservation) + kebab-app code_ingest_smoke 4 integration (shell + yaml fallback + 2 reingest-unchanged regression). 14 + 2 추가 = 16 total smoke tests.

Downloads

v0.14.0 17ee400fd5

v0.14.0 Stable

altair823 released this 2026-05-20 14:23:56 +00:00 | 368 commits to main since this release

p10-2: Tier 2 resource-aware chunkers

3 new chunkers expand kebab ingest beyond AST source code to k8s manifests, Dockerfiles, and project manifest files.

Surface changes (dogfood-visible)

새 chunker 3종 activated in ingest_one_code_asset dispatch:
- k8s-manifest-resource-v1 — .yaml / .yml 중 apiVersion + kind 둘 다 있는 multi-document YAML. document 당 1 chunk, citation symbol = <Kind>/<namespace>/<name> (또는 <Kind>/<name> for cluster-scoped, <Kind>/<unnamed> if metadata.name missing).
- dockerfile-file-v1 — Dockerfile / Dockerfile.* / *.dockerfile 전체 1 chunk, symbol <dockerfile>.
- manifest-file-v1 — Cargo.toml / pyproject.toml / package.json / tsconfig.json / pom.xml / build.gradle / go.mod 전체 1 chunk, symbol <manifest>. 종류는 code_lang 으로 구분 (toml / json / xml / groovy / go-mod).
- 모든 Tier 2 chunker 가 AST_CHUNK_MAX_LINES = 200 oversize fallback 공유 (line-window split, symbol 보존).
새 --code-lang 값 (search filter): yaml / dockerfile / toml / json / xml / groovy / go-mod. 예: kebab search --code-lang yaml "replica".
새 Citation::Code.lang 값: 위 7종. schema.v1.stats.code_lang_breakdown 에 자동으로 카운트 등장.
code_lang_for_path 가 single source of truth: design §3.5 룰에 따라 kebab-source-fs/src/media.rs 의 1A-1 era inline 매칭 duplication 정리. basename 매칭이 확장자 매칭에 우선 (Dockerfile / Cargo.toml / go.mod 등).
비-k8s YAML / invalid YAML 은 본 phase 에선 skip. p10-3 의 paragraph fallback 이 머지되면 자동으로 wire 될 예정.

Wire schema

Additive minor — *.v2 major bump 없음.

Citation::Code.lang 에 7 새 값 (lang 필드는 Option<String> 이라 schema 변경 0).
schema.v1.stats.code_lang_breakdown 에 7 새 카운트 (dict 라 schema 변경 0).
3 새 chunker_version 라벨 (k8s-manifest-resource-v1 / dockerfile-file-v1 / manifest-file-v1).
새 parser_version sentinel "none-v1" (Tier 2 의 parse 단계 없음 표시).

Frozen design

§3.5 code_lang 매핑 표에 3 줄 추가: xml / groovy / go-mod.
§10.1 활성화 로그에 p10-2 entry 추가 (2026-05-20-kebab-final-form-design.md 와 2026-05-15-kebab-code-ingest-design.md 양쪽).

DB / migration

없음. V00X migration 불필요.

Followups (non-blocking)

Oversize fallback test coverage: tier2_shared::push_chunks_with_oversize 의 line-window 분기는 현재 fixture 가 200 줄 이내라 직접 테스트 안 됨. 거대 ConfigMap / aggregate pom.xml 같은 fixture 1개 + multi-chunk 테스트 권장 (별 PR).
README Mermaid 다이어그램 chunker_version 열거 stale (1C-JK 부터 누락 + p10-2 의 3종 미포함). docs follow-up.
synthesize_tier2_document path anchor 주석 misleading: RustAstExtractor 와 달리 workspace_root join 안 함. 현재 FsSourceConnector 가 absolute path 만 emit 하므로 latent 하지만 주석 정정 권장.

Branch / PR

PR: #153 — APPROVE 후 머지 (merge commit 17ee400).
Spec: tasks/p10/p10-2-tier2-resource-aware.md. Plan: docs/superpowers/plans/2026-05-20-p10-2-tier2-resource-aware.md.

Stats

31 files changed, +3168 / -59.
cargo test --workspace --no-fail-fast -j 1 PASS, cargo clippy --workspace --all-targets -- -D warnings clean.
신규 테스트: kebab-chunk 8 (k8s 3 + dockerfile 1 + manifest 4) + kebab-app/code_ingest_smoke 3 (yaml / Dockerfile / Cargo.toml). 총 12 Tier 2 testing surface.

Downloads

40 Releases 40 Tags

kebab v0.20.2 — Ask 응답언어 rag-v3 + 검색 품질 eval baseline Stable

kebab v0.20.2 — Ask 응답언어 자동 매칭 + 검색 품질 eval 인프라

핵심 변경

1. Ask 응답언어 자동 매칭 (rag-v3, Finding #1 + O-2)

2. Bulk search input schema 확정 (Finding #2)

3. List docs human-readable path 보강 (Finding #3)

4. schema index_version 두 곳 구분 (Finding #7)

5. eval --config facade 패치 + 검색 품질 baseline 인프라

6. 기타 docs/schema 정비 (Finding #4 · #5/#6 · #8)

Version cascade 주의

Breaking changes / 사용자 영향

Upgrade 절차

References

v0.19.0 Stable

변경사항 (since v0.17.2)

개요

3 sub-item (PR #185 + #186 + #187 통합)

Bug fix

도그푸딩

v0.20.0 future-work

Wire schema

Binary

v0.18.0 Stable

v0.18.0 — fb-41 multi-hop RAG ship + NLI verification

새 surface

새 wire (additive minor — pre-v0.18 reader 무영향)

새 config

새 RefusalReason

권장 환경

Known limitations (v0.18.1+ priority)

도그푸딩

Sub-PR sequence

Cascade rule

v0.17.2 Stable

변경사항 (since v0.17.0)

v0.17.2 — v0.17.1 post-dogfood polish

변경

영향

Cross-link

v0.17.1 Stable

변경사항 (since v0.16.1)

v0.17.1 — post-dogfood docs/config polish

변경

Breaking / cascade

미진행 (next round)

Verification

v0.17.0 Stable

변경사항 (since v0.16.0)

v0.17.0 — Korean trigram + C typedef alias + chunk-count stats

Breaking — release 트리거

Additive — wire breaking 아님

Doc surface

Verification

v0.16.1 Stable

Patch: k8s multi-resource YAML chunk_id collision fix

Bug

Root cause

Fix

Deviation note (HOTFIXES 2026-05-21)

Regression coverage

Stats

v0.16.0 Stable

p10-1D: C + C++ AST chunkers + missing p10-3 fix

Surface changes (dogfood-visible)

Critical: lands missing p10-3 try_skip_unchanged fix

Wire schema

Frozen design

DB / migration

Followups (non-blocking, code-reviewer flagged)

Branch / PR

Stats

v0.15.0 Stable

p10-3: Tier 3 paragraph + line-window fallback

Surface changes (dogfood-visible)

Wire schema

Frozen design

DB / migration

Followups (non-blocking, code-reviewer flagged)

Branch / PR

4. schema `index_version` 두 곳 구분 (Finding #7)

5. eval `--config` facade 패치 + 검색 품질 baseline 인프라