feat(kebab-parse-image): P6-3 caption adapter — vision LM via trait #34

Merged

altair823 merged 3 commits from feat/p6-3-caption-adapter into main

2026-05-02 06:22:19 +00:00

Author	SHA1	Message	Date
altair823	b40b0b3992	review(p6-3): 회차 2 — image_prep 회귀 테스트 + doc 일반화 - src/image_prep.rs: • 신규 unit 테스트 6건 — PNG passthrough (zero-decode + 바이트 동일성), JPEG → PNG 재인코딩, 1px 후행 클램프 (max=1601 / long=4001 irrational scale), aspect ratio (4:3 보존, 2% 이내), 손상 PNG Err, 인식 불가 바이트 Err. • 모듈 doc-comment 의 \"send to vision models\" 표현을 \"image-to-LM pipeline / channel\" 으로 일반화. 미래 PDF / video keyframe 등 호출자가 doc 만 보고 호출 의도 파악 가능. cargo test -p kebab-parse-image — 48 pass + 2 ignored (19 unit (+6 image_prep) + 12 P6-1 + 8 P6-2 + 9 P6-3). cargo clippy -p kebab-parse-image --all-targets -- -D warnings — pass.	2026-05-02 06:14:27 +00:00
altair823	9c644245fb	review(p6-3): 회차 1 지적 반영 - 새 모듈 `crates/kebab-parse-image/src/image_prep.rs` — OCR + caption + 향후 PDF/video 가 공유할 단일 다운스케일 헬퍼 (`downscale_to_png`) 추출. 기존 ocr.rs / caption.rs 의 거의 동일 알고리즘 두 벌을 한 곳으로 통합. 1px 후행 클램프 / PNG passthrough hot path / 에러 메시지 패턴이 한 곳에서 관리됨. - src/ocr.rs: `downscale_to_long_edge` 제거 → `image_prep::downscale_to_png` 호출. `image::ImageReader / ImageFormat / Cursor` import 도 정리. - src/caption.rs: • `caption_image` / `apply_caption` 의 disabled 처리 비대칭 해소. `caption_image` 는 raw 연산 (gate 없음), `apply_caption` 만 `cfg.image.caption.enabled` 게이트 검사. 호출자가 같은 함수에서 같은 의미를 얻음. • `apply_caption` 의 caption.model / model_version `String::clone` 2회 → 0회. caption move 전에 ProvenanceEvent.note 를 먼저 빌드. • 다운스케일 로직 통째로 image_prep 위임. • `MIN_CAPTION_LONG_EDGE` / `MAX_CAPTION_LONG_EDGE` 를 `pub const` 로 노출 (P6-2 의 `MAX_DECODE_DIM` 가시성 컨벤션과 일관). - tests/caption.rs: • `caption_image_errors_when_feature_disabled` 를 `caption_image_runs_regardless_of_enabled_flag` 로 교체 — 새 책임 분리 의미 검증. • `caption_image_clamps_oversized_max_pixels` 가 literal 1536 대신 `kebab_parse_image::caption::MAX_CAPTION_LONG_EDGE` 상수 참조. - tasks/HOTFIXES.md: `model_version` 형태 deviation 한 단락 추가 (spec literal `provider` → `<provider>/<prompt_template_version>` 확장 + 사유). cargo test -p kebab-parse-image — 42 pass + 2 ignored (13 unit + 12 P6-1 + 8 P6-2 + 9 P6-3). cargo clippy --workspace --all-targets -- -D warnings — pass.	2026-05-02 06:11:56 +00:00
altair823	cd2213e48d	feat(kebab-parse-image): P6-3 caption adapter — vision LM via trait - 신규 모듈 `crates/kebab-parse-image/src/caption.rs` 추가: • `caption_image(llm, bytes, lang_hint, cfg)` — `&dyn LanguageModel` 위에서 동작. 비전 LM (예: gemma4:e4b) 이 한 문장 객관 설명 출력. temperature=0 / seed=0 결정성. • `apply_caption(llm, bytes, block, lang_hint, cfg, events)` — `block.caption = Some(...)` 으로 채우고 ProvenanceKind::CaptionApplied 이벤트 1건 추가. `image.caption.enabled = false` 면 클린 no-op (Ok(())). LM 실패 시 block.caption None 그대로 + events 미기록. • 다운스케일 long-edge `[128, 1536]` 클램프. PNG passthrough hot path 보존, 그 외는 단일 디코드 + PNG 재인코딩. • 한국어 / 영어 프롬프트 분기 (lang_hint=\"ko\"/\"kor\" → 한국어). • `ModelCaption.model_version = \"<provider>/<prompt_template_version>\"` (예: \"ollama/caption-v1\") — prompt 또는 모델 회귀 감사 가능. ## kebab-core / kebab-llm-local 변경 - `kebab_core::GenerateRequest` 에 `images: Vec<String>` 필드 추가. `#[serde(default)]` 으로 기존 wire 페이로드 / snapshot 호환. - `kebab-llm-local::OllamaLanguageModel` 가 req.images 를 Ollama `images: [base64, ...]` 와이어 필드로 라우팅. `#[serde(skip_serializing_if = is_empty)]` 로 비어 있을 때 wire shape 가 pre-P6-3 와 byte-identical. ## kebab-config - 신규 `ImageCfg.caption: CaptionCfg`: - `enabled: bool` (default false) - `max_pixels: u32` (default 768, 클램프 [128, 1536]) - `prompt_template_version: String` (default \"caption-v1\") - `KEBAB_IMAGE_CAPTION_{ENABLED,MAX_PIXELS,PROMPT_TEMPLATE_VERSION}` 3종 환경변수 추가. ## Spec deviations `tasks/HOTFIXES.md` 2026-05-02 항목 추가: - Symptom 1: spec p6-3 시그니처가 `&dyn LanguageModel` 인데 frozen trait + GenerateRequest 가 vision 미지원. → trait 확장. - Symptom 2: spec 의 cargo feature `caption` (default OFF at compile time) → runtime gate 1개로 통합. base64/image/kebab-llm 외 추가 deps 없어 cargo feature 의 binary 절감 가치 미미. p4-1 / p4-2 / p6-3 spec 의 amends 명시. ## 테스트 `cargo test -p kebab-parse-image --test caption` — 9건 + 1 ignored: - feature gate (disabled → no-op / Err on direct call) - happy path (block.caption Some + Provenance CaptionApplied) - 빈 토큰 stream → empty text + caption.is_some() - CapturingMock 으로 req.images 라우팅 검증 (base64 1개, decode 가능) - 한국어 / 영어 프롬프트 분기 (CapturingMock 의 system 캡처) - LM Err → block.caption None 유지 + events 미기록 - 결정성 (동일 mock 입력 → 동일 caption) - max_pixels 클램프 (99999 → 1536, 4000×3000 PNG 다운스케일 검증) - opt-in 통합 (실 192.168.0.47 Ollama / gemma4:e4b → \"The image is a solid red color.\" 검증 완료, 4.3초) `cargo test --workspace --no-fail-fast -j 1` 전체 pass. `cargo clippy --workspace --all-targets -- -D warnings` pass. ## 의존성 경계 - 추가 deps: `kebab-llm` (trait 만), `base64` (이미 P6-2 에서 추가). - dev-deps: `kebab-llm/mock` 으로 `MockLanguageModel`, `kebab-llm-local` (통합 테스트 전용 — 런타임 deps 에는 없음). - forbidden 침범 없음: `kebab-source-fs / parse-md / normalize / chunk / store-* / embed* / search / rag / UI` 미참조. contract: docs/superpowers/specs/2026-04-27-kebab-final-form-design.md sections: §3.4 ImageRefBlock.caption, §3.7a ModelCaption, §9.1 caption (model-generated, low trust).	2026-05-02 06:05:39 +00:00

Author

SHA1

Message

Date

altair823

b40b0b3992

review(p6-3): 회차 2 — image_prep 회귀 테스트 + doc 일반화

- src/image_prep.rs:
  • 신규 unit 테스트 6건 — PNG passthrough (zero-decode + 바이트
    동일성), JPEG → PNG 재인코딩, 1px 후행 클램프 (max=1601 / long=4001
    irrational scale), aspect ratio (4:3 보존, 2% 이내), 손상 PNG
    Err, 인식 불가 바이트 Err.
  • 모듈 doc-comment 의 \"send to vision models\" 표현을 \"image-to-LM
    pipeline / channel\" 으로 일반화. 미래 PDF / video keyframe 등
    호출자가 doc 만 보고 호출 의도 파악 가능.

cargo test -p kebab-parse-image — 48 pass + 2 ignored
  (19 unit (+6 image_prep) + 12 P6-1 + 8 P6-2 + 9 P6-3).
cargo clippy -p kebab-parse-image --all-targets -- -D warnings — pass.

2026-05-02 06:14:27 +00:00

altair823

9c644245fb

review(p6-3): 회차 1 지적 반영

- 새 모듈 `crates/kebab-parse-image/src/image_prep.rs` — OCR + caption
  + 향후 PDF/video 가 공유할 단일 다운스케일 헬퍼 (`downscale_to_png`)
  추출. 기존 ocr.rs / caption.rs 의 거의 동일 알고리즘 두 벌을 한
  곳으로 통합. 1px 후행 클램프 / PNG passthrough hot path / 에러
  메시지 패턴이 한 곳에서 관리됨.
- src/ocr.rs: `downscale_to_long_edge` 제거 → `image_prep::downscale_to_png`
  호출. `image::ImageReader / ImageFormat / Cursor` import 도 정리.
- src/caption.rs:
  • `caption_image` / `apply_caption` 의 disabled 처리 비대칭 해소.
    `caption_image` 는 raw 연산 (gate 없음), `apply_caption` 만
    `cfg.image.caption.enabled` 게이트 검사. 호출자가 같은 함수에서
    같은 의미를 얻음.
  • `apply_caption` 의 caption.model / model_version `String::clone`
    2회 → 0회. caption move 전에 ProvenanceEvent.note 를 먼저 빌드.
  • 다운스케일 로직 통째로 image_prep 위임.
  • `MIN_CAPTION_LONG_EDGE` / `MAX_CAPTION_LONG_EDGE` 를 `pub const`
    로 노출 (P6-2 의 `MAX_DECODE_DIM` 가시성 컨벤션과 일관).
- tests/caption.rs:
  • `caption_image_errors_when_feature_disabled` 를
    `caption_image_runs_regardless_of_enabled_flag` 로 교체 — 새
    책임 분리 의미 검증.
  • `caption_image_clamps_oversized_max_pixels` 가 literal 1536 대신
    `kebab_parse_image::caption::MAX_CAPTION_LONG_EDGE` 상수 참조.
- tasks/HOTFIXES.md: `model_version` 형태 deviation 한 단락 추가
  (spec literal `provider` → `<provider>/<prompt_template_version>`
  확장 + 사유).

cargo test -p kebab-parse-image — 42 pass + 2 ignored
  (13 unit + 12 P6-1 + 8 P6-2 + 9 P6-3).
cargo clippy --workspace --all-targets -- -D warnings — pass.

2026-05-02 06:11:56 +00:00

altair823

cd2213e48d

feat(kebab-parse-image): P6-3 caption adapter — vision LM via trait

- 신규 모듈 `crates/kebab-parse-image/src/caption.rs` 추가:
  • `caption_image(llm, bytes, lang_hint, cfg)` — `&dyn LanguageModel`
    위에서 동작. 비전 LM (예: gemma4:e4b) 이 한 문장 객관 설명
    출력. temperature=0 / seed=0 결정성.
  • `apply_caption(llm, bytes, block, lang_hint, cfg, events)` —
    `block.caption = Some(...)` 으로 채우고 ProvenanceKind::CaptionApplied
    이벤트 1건 추가. `image.caption.enabled = false` 면 클린 no-op
    (Ok(())). LM 실패 시 block.caption None 그대로 + events 미기록.
  • 다운스케일 long-edge `[128, 1536]` 클램프. PNG passthrough hot
    path 보존, 그 외는 단일 디코드 + PNG 재인코딩.
  • 한국어 / 영어 프롬프트 분기 (lang_hint=\"ko\"/\"kor\" → 한국어).
  • `ModelCaption.model_version = \"<provider>/<prompt_template_version>\"`
    (예: \"ollama/caption-v1\") — prompt 또는 모델 회귀 감사 가능.

## kebab-core / kebab-llm-local 변경

- `kebab_core::GenerateRequest` 에 `images: Vec<String>` 필드 추가.
  `#[serde(default)]` 으로 기존 wire 페이로드 / snapshot 호환.
- `kebab-llm-local::OllamaLanguageModel` 가 req.images 를 Ollama
  `images: [base64, ...]` 와이어 필드로 라우팅.
  `#[serde(skip_serializing_if = is_empty)]` 로 비어 있을 때 wire
  shape 가 pre-P6-3 와 byte-identical.

## kebab-config

- 신규 `ImageCfg.caption: CaptionCfg`:
  - `enabled: bool` (default false)
  - `max_pixels: u32` (default 768, 클램프 [128, 1536])
  - `prompt_template_version: String` (default \"caption-v1\")
- `KEBAB_IMAGE_CAPTION_{ENABLED,MAX_PIXELS,PROMPT_TEMPLATE_VERSION}`
  3종 환경변수 추가.

## Spec deviations

`tasks/HOTFIXES.md` 2026-05-02 항목 추가:
- Symptom 1: spec p6-3 시그니처가 `&dyn LanguageModel` 인데 frozen
  trait + GenerateRequest 가 vision 미지원. → trait 확장.
- Symptom 2: spec 의 cargo feature `caption` (default OFF at compile
  time) → runtime gate 1개로 통합. base64/image/kebab-llm 외 추가
  deps 없어 cargo feature 의 binary 절감 가치 미미.

p4-1 / p4-2 / p6-3 spec 의 amends 명시.

## 테스트

`cargo test -p kebab-parse-image --test caption` — 9건 + 1 ignored:
- feature gate (disabled → no-op / Err on direct call)
- happy path (block.caption Some + Provenance CaptionApplied)
- 빈 토큰 stream → empty text + caption.is_some()
- CapturingMock 으로 req.images 라우팅 검증 (base64 1개, decode 가능)
- 한국어 / 영어 프롬프트 분기 (CapturingMock 의 system 캡처)
- LM Err → block.caption None 유지 + events 미기록
- 결정성 (동일 mock 입력 → 동일 caption)
- max_pixels 클램프 (99999 → 1536, 4000×3000 PNG 다운스케일 검증)
- opt-in 통합 (실 192.168.0.47 Ollama / gemma4:e4b → \"The image is
  a solid red color.\" 검증 완료, 4.3초)

`cargo test --workspace --no-fail-fast -j 1` 전체 pass.
`cargo clippy --workspace --all-targets -- -D warnings` pass.

## 의존성 경계

- 추가 deps: `kebab-llm` (trait 만), `base64` (이미 P6-2 에서 추가).
- dev-deps: `kebab-llm/mock` 으로 `MockLanguageModel`,
  `kebab-llm-local` (통합 테스트 전용 — 런타임 deps 에는 없음).
- forbidden 침범 없음: `kebab-source-fs / parse-md / normalize /
  chunk / store-* / embed* / search / rag / UI` 미참조.

contract: docs/superpowers/specs/2026-04-27-kebab-final-form-design.md
sections: §3.4 ImageRefBlock.caption, §3.7a ModelCaption, §9.1
caption (model-generated, low trust).

2026-05-02 06:05:39 +00:00

feat(kebab-parse-image): P6-3 caption adapter — vision LM via trait #34

3 Commits