altair823-org/kebab
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 40 Wiki Activity

Merge pull request 'feat(kebab-parse-image): P6-2 OCR adapter — Ollama-vision default' (#33) from feat/p6-2-ocr-adapter into main

Browse Source 
Reviewed-on: #33
This commit was merged in pull request #33.
This commit is contained in:
altair823
2026-05-02 05:54:23 +00:00
parent ac267b7e85 1539367692
commit e43d3bc697
9 changed files with 1259 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
Cargo.lock generated
View File

@@ -2,6 +2,22 @@
# It is not intended for manual editing.
version = 4
[[package]]
name = "ab_glyph"
version = "0.2.32"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "01c0457472c38ea5bd1c3b5ada5e368271cb550be7a4ca4a0b4634e9913f6cc2"
dependencies = [
"ab_glyph_rasterizer",
"owned_ttf_parser",
]
[[package]]
name = "ab_glyph_rasterizer"
version = "0.1.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "366ffbaa4442f4684d91e2cd7c5ea7c4ed8add41959a31447066e279e432b618"
[[package]]
name = "adler2"
version = "2.0.1"
@@ -3552,15 +3568,22 @@ dependencies = [
name = "kebab-parse-image"
version = "0.1.0"
dependencies = [
"ab_glyph",
"anyhow",
"base64 0.22.1",
"blake3",
"image",
"kamadak-exif",
"kebab-config",
"kebab-core",
"reqwest",
"serde",
"serde_json",
"tempfile",
"time",
"tokio",
"tracing",
"wiremock",
]
[[package]]
@@ -5128,6 +5151,15 @@ dependencies = [
"ureq",
]
[[package]]
name = "owned_ttf_parser"
version = "0.25.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "36820e9051aca1014ddc75770aab4d68bc1e9e632f0f5627c4086bc216fb583b"
dependencies = [
"ttf-parser",
]
[[package]]
name = "ownedbytes"
version = "0.9.0"
@@ -7450,6 +7482,12 @@ version = "0.2.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
[[package]]
name = "ttf-parser"
version = "0.25.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d2df906b07856748fa3f6e0ad0cbaa047052d4a7dd609e231c4f72cee8c36f31"
[[package]]
name = "twox-hash"
version = "2.1.2"

210
crates/kebab-config/src/lib.rs
View File

@@ -21,6 +21,12 @@ pub struct Config {
pub models: ModelsCfg,
pub search: SearchCfg,
pub rag: RagCfg,
/// Image-pipeline settings (P6: OCR, captioning). Tagged
/// `#[serde(default)]` so pre-P6 config files that predate the
/// `[image]` section still load — defaults disable OCR / caption
/// (they cost a model call per asset).
#[serde(default = "ImageCfg::defaults")]
pub image: ImageCfg,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -98,6 +104,64 @@ pub struct RagCfg {
pub max_context_tokens: usize,
}
/// Settings for the image ingest pipeline (P6). `ocr` controls OCR
/// behaviour; future fields (e.g. `caption`) will join here as P6-3
/// lands.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct ImageCfg {
#[serde(default = "OcrCfg::defaults")]
pub ocr: OcrCfg,
}
impl ImageCfg {
pub fn defaults() -> Self {
Self {
ocr: OcrCfg::defaults(),
}
}
}
/// OCR settings (P6-2). v1 ships a single Ollama-vision adapter; the
/// `OcrEngine` trait in `kebab-parse-image` keeps the door open for
/// Tesseract / Apple Vision / PaddleOCR engines as feature-gated
/// alternatives in P+. See `tasks/HOTFIXES.md` (2026-05-02) for the
/// rationale on dropping the original Tesseract default.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct OcrCfg {
/// Run OCR on every image during ingest. Default `false` because
/// OCR adds one model call per asset.
pub enabled: bool,
/// Engine identifier. v1 only ships `"ollama-vision"`.
pub engine: String,
/// Model id passed to the engine (e.g. `"gemma4:e4b"` for
/// Ollama-vision).
pub model: String,
/// HTTP endpoint for the OCR engine. `None` (or a missing key in
/// TOML) means "fall back to `models.llm.endpoint`" — convenient
/// when the same Ollama host serves both LLM and vision.
#[serde(default)]
pub endpoint: Option<String>,
/// BCP-47 language hints (e.g. `["eng", "kor"]`). The adapter
/// renders them into the prompt; the LLM honours them probabilistically.
pub languages: Vec<String>,
/// Cap the long edge of the image (in pixels) before sending. Larger
/// images bloat prompt cost. Default `1600`.
pub max_pixels: u32,
}
impl OcrCfg {
pub fn defaults() -> Self {
Self {
enabled: false,
engine: "ollama-vision".to_string(),
model: "gemma4:e4b".to_string(),
endpoint: None,
languages: vec!["eng".to_string(), "kor".to_string()],
max_pixels: 1600,
}
}
}
impl Config {
/// Defaults per design §6.4.
pub fn defaults() -> Self {
@@ -162,6 +226,7 @@ impl Config {
explain_default: false,
max_context_tokens: 8000,
},
image: ImageCfg::defaults(),
}
}
@@ -323,6 +388,35 @@ impl Config {
}
}
// image.ocr
"KEBAB_IMAGE_OCR_ENABLED" => {
self.image.ocr.enabled = parse_bool(v);
}
"KEBAB_IMAGE_OCR_ENGINE" => self.image.ocr.engine = v.clone(),
"KEBAB_IMAGE_OCR_MODEL" => self.image.ocr.model = v.clone(),
"KEBAB_IMAGE_OCR_ENDPOINT" => {
// Empty env value is treated the same as "fall back
// to models.llm.endpoint" — i.e. set None.
self.image.ocr.endpoint = if v.is_empty() {
None
} else {
Some(v.clone())
};
}
"KEBAB_IMAGE_OCR_LANGUAGES" => {
// Comma-separated list, e.g. "eng,kor".
self.image.ocr.languages = v
.split(',')
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect();
}
"KEBAB_IMAGE_OCR_MAX_PIXELS" => {
if let Ok(n) = v.parse::<u32>() {
self.image.ocr.max_pixels = n;
}
}
// Unknown KEBAB_* keys are silently ignored — see
// `env_unknown_key_is_ignored` test.
_ => {}
@@ -471,6 +565,122 @@ mod tests {
assert!(c.indexing.watch_filesystem);
}
#[test]
fn image_ocr_defaults_disabled_with_ollama_vision() {
let c = Config::defaults();
assert!(!c.image.ocr.enabled);
assert_eq!(c.image.ocr.engine, "ollama-vision");
assert_eq!(c.image.ocr.model, "gemma4:e4b");
assert_eq!(c.image.ocr.languages, vec!["eng", "kor"]);
assert_eq!(c.image.ocr.max_pixels, 1600);
}
#[test]
fn image_ocr_env_overrides() {
let mut env = HashMap::new();
env.insert("KEBAB_IMAGE_OCR_ENABLED".to_string(), "true".to_string());
env.insert(
"KEBAB_IMAGE_OCR_MODEL".to_string(),
"gemma4:31b".to_string(),
);
env.insert(
"KEBAB_IMAGE_OCR_ENDPOINT".to_string(),
"http://192.168.0.47:11434".to_string(),
);
// Empty env value should map to None (= fall back to llm.endpoint).
// We exercise that branch in a separate test.
env.insert(
"KEBAB_IMAGE_OCR_LANGUAGES".to_string(),
"eng, kor, jpn".to_string(),
);
env.insert("KEBAB_IMAGE_OCR_MAX_PIXELS".to_string(), "2048".to_string());
let c = Config::defaults().apply_env(&env);
assert!(c.image.ocr.enabled);
assert_eq!(c.image.ocr.model, "gemma4:31b");
assert_eq!(
c.image.ocr.endpoint.as_deref(),
Some("http://192.168.0.47:11434")
);
assert_eq!(c.image.ocr.languages, vec!["eng", "kor", "jpn"]);
assert_eq!(c.image.ocr.max_pixels, 2048);
}
/// Pre-P6 config files don't have an `[image]` section. The
/// `#[serde(default)]` attribute on `Config::image` must let those
/// files load with `ImageCfg::defaults()` instead of erroring.
/// `KEBAB_IMAGE_OCR_ENDPOINT=""` (empty value) should map to `None`
/// rather than to `Some("")` so the fallback to `models.llm.endpoint`
/// kicks in. Covers the env-equivalent of a missing TOML key.
#[test]
fn image_ocr_endpoint_empty_env_value_is_none() {
let mut env = HashMap::new();
env.insert("KEBAB_IMAGE_OCR_ENDPOINT".to_string(), String::new());
let c = Config::defaults().apply_env(&env);
assert_eq!(c.image.ocr.endpoint, None);
}
#[test]
fn pre_p6_config_without_image_section_loads_with_defaults() {
let toml_text = r#"
schema_version = 1
[workspace]
root = "/tmp/x"
include = ["**/*.md"]
exclude = []
[storage]
data_dir = "/tmp/d"
sqlite = "{data_dir}/x.sqlite"
vector_dir = "{data_dir}/v"
asset_dir = "{data_dir}/a"
artifact_dir = "{data_dir}/r"
model_dir = "{data_dir}/m"
runs_dir = "{data_dir}/u"
copy_threshold_mb = 100
[indexing]
max_parallel_extractors = 2
max_parallel_embeddings = 1
watch_filesystem = false
[chunking]
target_tokens = 500
overlap_tokens = 80
respect_markdown_headings = true
chunker_version = "md-heading-v1"
[models.embedding]
provider = "fastembed"
model = "multilingual-e5-small"
version = "v1"
dimensions = 384
batch_size = 64
[models.llm]
provider = "ollama"
model = "qwen2.5:14b-instruct"
context_tokens = 32768
endpoint = "http://127.0.0.1:11434"
temperature = 0.0
seed = 0
[search]
default_k = 10
hybrid_fusion = "rrf"
rrf_k = 60
snippet_chars = 220
[rag]
prompt_template_version = "rag-v1"
score_gate = 0.30
explain_default = false
max_context_tokens = 8000
"#;
let c: Config = toml::from_str(toml_text).expect("pre-P6 TOML must still parse");
assert_eq!(c.image, ImageCfg::defaults());
}
#[test]
fn xdg_paths_honor_env() {
// Must restore env after the test to avoid polluting other tests.

19
crates/kebab-parse-image/Cargo.toml
View File

@@ -5,11 +5,13 @@ edition = { workspace = true }
rust-version = { workspace = true }
license = { workspace = true }
repository = { workspace = true }
description = "Image extractor — produces a single-block CanonicalDocument with EXIF metadata (P6-1)"
description = "Image extractor + EXIF + OCR (Ollama-vision) for the kebab pipeline (P6-1, P6-2)"
[dependencies]
kebab-core = { path = "../kebab-core" }
kebab-config = { path = "../kebab-config" }
anyhow = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
time = { workspace = true }
tracing = { workspace = true }
@@ -21,7 +23,22 @@ image = { version = "0.25", default-features = false, features = ["png", "jpeg",
# kamadak-exif: pure-Rust EXIF reader. Used for the whitelisted tag
# extraction (DateTimeOriginal, GPS, Make, Model, Orientation, Software).
kamadak-exif = "0.6"
# Ollama-vision OCR adapter (P6-2) talks HTTP directly. We keep the
# feature surface identical to `kebab-llm-local` (blocking + json +
# rustls-tls) so both crates share the same TLS backend and the
# transitive tokio runtime is brought in once.
reqwest = { version = "0.12", default-features = false, features = ["blocking", "json", "rustls-tls"] }
base64 = "0.22"
[dev-dependencies]
tempfile = { workspace = true }
blake3 = { workspace = true }
# Shared test infrastructure with `kebab-llm-local`: wiremock under
# tokio for HTTP fixtures.
wiremock = { workspace = true }
tokio = { workspace = true, features = ["rt-multi-thread"] }
# Used by `tests/common/mod.rs` to render the opt-in OCR integration
# fixture. Only loaded for tests; the production crate doesn't need
# font rendering.
ab_glyph = "0.2"
base64 = "0.22"

26
crates/kebab-parse-image/src/lib.rs
View File

@@ -1,17 +1,27 @@
//! `kebab-parse-image` — image extractor (P6-1).
//! `kebab-parse-image` — image extractor (P6-1) + OCR adapter (P6-2).
//!
//! Implements [`kebab_core::Extractor`] for `MediaType::Image(_)`. One asset
//! produces one [`CanonicalDocument`] with a single
//! [`Block::ImageRef`](kebab_core::Block::ImageRef). EXIF is captured into
//! `metadata.user["exif"]`, dimensions into `metadata.user["dimensions"]`.
//! OCR / caption fields stay `None`; later tasks (P6-2 / P6-3) populate
//! them.
//! P6-1 implements [`kebab_core::Extractor`] for `MediaType::Image(_)`,
//! producing a single-block [`CanonicalDocument`] (`ImageRefBlock` with
//! EXIF + dimensions in `metadata.user`). OCR / caption fields stay
//! `None` until populated by the OCR / caption adapters.
//!
//! P6-2 adds the [`ocr`] module: an [`OcrEngine`] trait and an
//! [`OllamaVisionOcr`] default adapter that talks to a vision-capable
//! Ollama model. [`apply_ocr`] is the helper that mutates an
//! [`ImageRefBlock`] in place. Trust note — the LLM-driven default
//! can hallucinate; `OcrText.engine` carries the source identity so
//! consumers can branch trust by engine (Tesseract / Apple Vision
//! adapters, when added, will write a different `engine` string).
//!
//! Per design §3.4 (Block::ImageRef + ImageRefBlock), §3.7a (OcrText /
//! ModelCaption stubs), §9.1 (image extraction policy), §9 (versioning).
//! ModelCaption stubs), §9.1 (image extraction policy / OCR vs caption
//! provenance), §9 (versioning).
mod dims;
mod exif_extract;
pub mod ocr;
pub use ocr::{OcrEngine, OllamaVisionOcr, apply_ocr};
use anyhow::{Context, Result};
use kebab_core::{

502
crates/kebab-parse-image/src/ocr.rs Normal file
View File

@@ -0,0 +1,502 @@
//! OCR adapter (P6-2).
//!
//! [`OcrEngine`] is a small trait for "image bytes → [`OcrText`]". v1 ships
//! a single implementation, [`OllamaVisionOcr`], which delegates to a
//! vision-capable Ollama model (`gemma4:e4b` by default).
//!
//! ## Spec deviation (Tesseract → Ollama-vision)
//!
//! The original P6-2 spec named Tesseract as the default engine. The dev
//! / CI environment intentionally avoids system-package installs, so the
//! Tesseract Rust crate (which links `libtesseract`) is impractical
//! today. We keep the [`OcrEngine`] trait as the abstraction the spec
//! demanded — Tesseract / Apple Vision / PaddleOCR plug in as future
//! feature-gated alternatives without touching the extractor or
//! chunker. See `tasks/HOTFIXES.md` (2026-05-02) for the full
//! rationale.
//!
//! ## Trust note
//!
//! The original spec marked `OcrText` as "observed text (high trust)"
//! to distinguish it from `ModelCaption`. With an LLM-driven OCR engine
//! the line blurs — the model can hallucinate. Downstream consumers
//! that surface OCR text should still treat it as a hint, not ground
//! truth, and prefer the asset bytes when verifying. The `engine`
//! field on [`OcrText`] makes the source explicit, so a caller can
//! decide whether to trust based on which engine produced the text.
use std::io::Cursor;
use std::time::Duration;
use anyhow::{Context, Result};
use base64::Engine as _;
use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
use image::{ImageFormat, ImageReader};
use kebab_core::{ImageRefBlock, Lang, OcrRegion, OcrText, ProvenanceEvent, ProvenanceKind};
use serde::{Deserialize, Serialize};
use time::OffsetDateTime;
/// Engine name written into `OcrText.engine` for the Ollama-vision adapter.
pub const OLLAMA_VISION_ENGINE: &str = "ollama-vision";
/// Hard ceiling on the OCR HTTP exchange. Cold-loading a vision model on
/// first call can take ~30s; 5 minutes is generous without being open-ended.
const REQUEST_TIMEOUT: Duration = Duration::from_secs(300);
/// Lower bound on `config.image.ocr.max_pixels`. Anything below this is
/// silently bumped to keep the model from receiving an unreadable thumbnail.
const MIN_LONG_EDGE: u32 = 256;
/// Hard cap on `max_pixels` — the spec mentions "downscale aggressively"
/// for vision LMs because input dimension translates directly into
/// prompt cost. 4096 is generous for legibility and still bounded.
const MAX_LONG_EDGE: u32 = 4096;
/// Image-bytes → [`OcrText`] interface. Implementations may shell out
/// (Apple Vision sidecar), call a local library (Tesseract), or — in v1
/// — talk HTTP to a vision LM (Ollama).
pub trait OcrEngine: Send + Sync {
/// Stable identifier written into `OcrText.engine`. Used by callers
/// to decide trust level (observed vs. generated).
fn engine_name(&self) -> &'static str;
/// Engine version string written into `OcrText.engine_version`.
/// Adapters that depend on a remote service may include the model
/// id / version here.
fn engine_version(&self) -> String;
/// Run OCR on `image_bytes`. `lang_hint` (BCP-47) can be passed
/// through to engines that benefit from it (Tesseract languages,
/// LLM prompt steering); ignore otherwise.
fn recognize(
&self,
image_bytes: &[u8],
lang_hint: Option<&Lang>,
) -> Result<OcrText>;
}
/// Mutate `block.ocr` in place by running `engine` over `image_bytes`,
/// then append a [`ProvenanceKind::OcrApplied`] event to `events` so the
/// caller (which owns the `CanonicalDocument`) can splice it into
/// `provenance.events`.
///
/// Returns the engine error verbatim on failure so the caller can decide
/// whether to skip the asset or surface it. `block.ocr` is left
/// untouched on error — partial state is never written.
pub fn apply_ocr(
engine: &dyn OcrEngine,
image_bytes: &[u8],
block: &mut ImageRefBlock,
lang_hint: Option<&Lang>,
events: &mut Vec<ProvenanceEvent>,
) -> Result<()> {
let text = engine.recognize(image_bytes, lang_hint).with_context(|| {
format!(
"OCR failed (engine={}, version={})",
engine.engine_name(),
engine.engine_version()
)
})?;
let region_count = text.regions.len();
block.ocr = Some(text);
events.push(ProvenanceEvent {
at: OffsetDateTime::now_utc(),
agent: "kb-parse-image".to_string(),
kind: ProvenanceKind::OcrApplied,
note: Some(format!(
"engine={} version={} regions={}",
engine.engine_name(),
engine.engine_version(),
region_count
)),
});
Ok(())
}
/// Ollama-vision OCR adapter — POSTs the image (base64) to
/// `<endpoint>/api/generate` with a transcription prompt and reads the
/// non-streaming response.
#[derive(Debug)]
pub struct OllamaVisionOcr {
client: reqwest::blocking::Client,
endpoint: String,
model: String,
languages: Vec<String>,
max_pixels: u32,
}
impl OllamaVisionOcr {
/// Build an adapter from a workspace [`kebab_config::Config`].
/// Reads `config.image.ocr.{model, endpoint, languages, max_pixels}`;
/// when `endpoint` is empty falls back to `config.models.llm.endpoint`
/// so the same Ollama host serves both LLM and OCR by default.
///
/// Construction does NOT touch the network — the first HTTP call
/// happens inside [`OcrEngine::recognize`].
pub fn new(config: &kebab_config::Config) -> Result<Self> {
let ocr = &config.image.ocr;
let endpoint = match ocr.endpoint.as_deref() {
Some(s) if !s.is_empty() => s.to_string(),
_ => config.models.llm.endpoint.clone(),
};
Self::build(endpoint, ocr.model.clone(), ocr.languages.clone(), ocr.max_pixels)
}
/// Build directly from explicit fields. Useful for tests that need
/// to point at a wiremock host without going through `Config`.
/// Shares the same input validation as [`Self::new`] so the two
/// constructors agree on what counts as a legal `OllamaVisionOcr` —
/// callers cannot smuggle an empty endpoint or empty model id past
/// `from_parts`.
pub fn from_parts(
endpoint: impl Into<String>,
model: impl Into<String>,
languages: Vec<String>,
max_pixels: u32,
) -> Result<Self> {
Self::build(endpoint.into(), model.into(), languages, max_pixels)
}
/// Shared validation + construction. Centralised so `new` and
/// `from_parts` cannot drift on what they accept.
fn build(
endpoint: String,
model: String,
languages: Vec<String>,
requested_max_pixels: u32,
) -> Result<Self> {
if endpoint.is_empty() {
anyhow::bail!(
"OllamaVisionOcr: endpoint is empty (set image.ocr.endpoint or models.llm.endpoint)"
);
}
let model = model.trim().to_string();
if model.is_empty() {
anyhow::bail!("OllamaVisionOcr: model is empty");
}
let max_pixels = requested_max_pixels.clamp(MIN_LONG_EDGE, MAX_LONG_EDGE);
if max_pixels != requested_max_pixels {
tracing::warn!(
target: "kebab-parse-image",
"image.ocr.max_pixels = {requested_max_pixels} clamped to {max_pixels} \
(legal range [{MIN_LONG_EDGE}, {MAX_LONG_EDGE}])"
);
}
let client = reqwest::blocking::Client::builder()
.timeout(REQUEST_TIMEOUT)
.build()
.context("building OCR HTTP client")?;
Ok(Self {
client,
endpoint,
model,
languages,
max_pixels,
})
}
/// Effective `max_pixels` after the `[MIN_LONG_EDGE, MAX_LONG_EDGE]`
/// clamp. Exposed so tests can verify the clamp result without
/// reaching into the private field; production callers don't need
/// it.
pub fn max_pixels(&self) -> u32 {
self.max_pixels
}
fn build_prompt(&self, lang_hint: Option<&Lang>) -> String {
let langs = if self.languages.is_empty() {
"any".to_string()
} else {
self.languages.join(", ")
};
let hint = match lang_hint.map(|l| l.0.as_str()) {
Some(h) if !h.is_empty() && h != "und" => format!(" (hint: dominant language is {h})"),
_ => String::new(),
};
format!(
"You are an OCR engine. Transcribe ALL text visible in the image, \
preserving line breaks. Output only the transcription, no commentary, \
no markdown fences, no quotes. Expected languages: {langs}{hint}. \
If the image contains no text, output an empty line."
)
}
}
impl OcrEngine for OllamaVisionOcr {
fn engine_name(&self) -> &'static str {
OLLAMA_VISION_ENGINE
}
fn engine_version(&self) -> String {
// Compose engine + model id so the wire form is self-describing
// ("ollama-vision/gemma4:e4b") — the Ollama daemon does not
// expose a stable per-model revision string we could pin.
format!("ollama/{}", self.model)
}
fn recognize(
&self,
image_bytes: &[u8],
lang_hint: Option<&Lang>,
) -> Result<OcrText> {
let (prepared, w, h) = downscale_to_long_edge(image_bytes, self.max_pixels)
.context("preparing image for OCR")?;
let b64 = BASE64_STANDARD.encode(&prepared);
let prompt = self.build_prompt(lang_hint);
let body = OllamaGenerateRequest {
model: &self.model,
prompt: &prompt,
images: [b64.as_str()],
stream: false,
options: OllamaOptions {
temperature: 0.0,
seed: 0,
},
};
let url = format!("{}/api/generate", self.endpoint.trim_end_matches('/'));
let resp = self
.client
.post(&url)
.json(&body)
.send()
.with_context(|| format!("POST {url}"))?;
let status = resp.status();
if !status.is_success() {
let body_text = resp.text().unwrap_or_default();
anyhow::bail!(
"OllamaVisionOcr: {status} from {url} — body={}",
truncate(&body_text, 512)
);
}
let parsed: OllamaGenerateResponse = resp
.json()
.context("parsing Ollama OCR response as JSON")?;
if let Some(err) = parsed.error {
anyhow::bail!("OllamaVisionOcr: server error — {}", truncate(&err, 512));
}
let raw = parsed.response.unwrap_or_default();
let joined = raw.trim().to_string();
let regions = if joined.is_empty() {
Vec::new()
} else {
// Ollama-vision returns prose, not bbox-annotated regions.
// We synthesize a single region covering the whole prepared
// image (post-downscale dimensions) so the `OcrText` shape
// remains compatible with consumers that expect at least
// one region. Confidence is left at 1.0 — there's no
// per-token score available from the LM.
vec![OcrRegion {
bbox: (0, 0, w, h),
text: joined.clone(),
confidence: 1.0,
}]
};
tracing::debug!(
target: "kebab-parse-image",
"ollama-vision OCR ok (model={}, dims={w}x{h}, chars={})",
self.model,
joined.chars().count()
);
Ok(OcrText {
joined,
regions,
engine: self.engine_name().to_string(),
engine_version: self.engine_version(),
})
}
}
// ── Image preparation ─────────────────────────────────────────────────────
/// Decode `bytes`, downscale so the long edge is at most `max_long_edge`,
/// and re-encode as PNG. Returns `(png_bytes, final_w, final_h)`.
///
/// PNG sources that already fit the cap are passthrough (zero decodes,
/// just a `Vec` clone). Every other path decodes the image exactly
/// once: the cheap header sniff peeks at the format / dimensions before
/// committing to a decode, so non-PNG passthrough and downscale share
/// the same `decode → optionally resize → re-encode` tail.
fn downscale_to_long_edge(bytes: &[u8], max_long_edge: u32) -> Result<(Vec<u8>, u32, u32)> {
let reader = ImageReader::new(Cursor::new(bytes))
.with_guessed_format()
.context("reading image header for OCR")?;
let format = reader.format();
let (w, h) = reader
.into_dimensions()
.context("reading image dimensions for OCR")?;
let long = w.max(h);
// Hot path — PNG within budget already matches the wire format we
// send Ollama, so we ship the bytes verbatim without paying for a
// decode + re-encode round-trip.
if long <= max_long_edge && format == Some(ImageFormat::Png) {
return Ok((bytes.to_vec(), w, h));
}
// Every remaining branch needs the pixels — either to re-encode as
// PNG (non-PNG within budget) or to resize first (over budget).
// One decode covers both.
let img = ImageReader::new(Cursor::new(bytes))
.with_guessed_format()
.context("re-reading image for OCR decode")?
.decode()
.context("decoding image for OCR")?;
let (final_w, final_h, final_img) = if long <= max_long_edge {
(w, h, img)
} else {
let scale = max_long_edge as f32 / long as f32;
let mut new_w = ((w as f32) * scale).round().max(1.0) as u32;
let mut new_h = ((h as f32) * scale).round().max(1.0) as u32;
// Independent rounding of the two axes can let `f32`'s nearest
// round push the long axis one pixel past `max_long_edge` for
// irrational scales (e.g. `max=1601, long=4001`). Pin the long
// axis to exactly `max_long_edge` so the doc-comment's
// "long edge is at most max_long_edge" stays a strict bound.
if w >= h {
new_w = new_w.min(max_long_edge);
} else {
new_h = new_h.min(max_long_edge);
}
let resized =
img.resize_exact(new_w, new_h, image::imageops::FilterType::Triangle);
(new_w, new_h, resized)
};
let mut out = Cursor::new(Vec::new());
final_img
.write_to(&mut out, ImageFormat::Png)
.context("encoding image as PNG for OCR")?;
Ok((out.into_inner(), final_w, final_h))
}
fn truncate(s: &str, n: usize) -> String {
if s.chars().count() <= n {
return s.to_string();
}
let mut out: String = s.chars().take(n).collect();
out.push_str(&format!("... (truncated, original {} chars)", s.chars().count()));
out
}
// ── Wire types ────────────────────────────────────────────────────────────
#[derive(Serialize)]
struct OllamaGenerateRequest<'a> {
model: &'a str,
prompt: &'a str,
/// Always exactly one image — the `OcrEngine` trait takes a single
/// `&[u8]`, so multi-image batching is out of scope until a future
/// trait extension. Fixed-size array avoids the `vec![]`
/// allocation per call.
images: [&'a str; 1],
stream: bool,
options: OllamaOptions,
}
#[derive(Serialize)]
struct OllamaOptions {
temperature: f32,
seed: u64,
}
#[derive(Deserialize)]
struct OllamaGenerateResponse {
#[serde(default)]
response: Option<String>,
#[serde(default)]
error: Option<String>,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn truncate_under_cap_unchanged() {
assert_eq!(truncate("abc", 5), "abc");
}
#[test]
fn truncate_over_cap_appends_marker() {
let big = "x".repeat(20);
let out = truncate(&big, 5);
assert!(out.starts_with("xxxxx"));
assert!(out.contains("(truncated, original 20 chars)"));
}
/// Build prompt mentions the configured languages and the hint when
/// supplied.
#[test]
fn build_prompt_lists_languages_and_hint() {
let engine = OllamaVisionOcr::from_parts(
"http://x",
"m",
vec!["eng".into(), "kor".into()],
1024,
)
.unwrap();
let p = engine.build_prompt(Some(&Lang("ko".into())));
assert!(p.contains("eng, kor"));
assert!(p.contains("hint: dominant language is ko"));
}
#[test]
fn build_prompt_omits_hint_when_lang_und() {
let engine = OllamaVisionOcr::from_parts(
"http://x",
"m",
vec!["eng".into()],
1024,
)
.unwrap();
let p = engine.build_prompt(Some(&Lang("und".into())));
assert!(!p.contains("hint:"));
}
/// `from_parts` (and by extension `new`) must reject an empty
/// endpoint string. Pinned so the bail message stays grep-able and
/// the constructor cannot drift to "silently accept a bad config".
#[test]
fn build_rejects_empty_endpoint() {
let r = OllamaVisionOcr::from_parts("", "m", vec![], 1024);
let err = r.expect_err("empty endpoint must bail").to_string();
assert!(
err.contains("endpoint is empty"),
"bail message missing 'endpoint is empty': {err}"
);
}
/// Whitespace-only model id trims to empty and must be rejected —
/// both `new` and `from_parts` route through the shared `build`,
/// so testing `from_parts` covers both.
#[test]
fn build_rejects_empty_model_after_trim() {
let r = OllamaVisionOcr::from_parts("http://x", " ", vec![], 1024);
let err = r.expect_err("empty model must bail").to_string();
assert!(
err.contains("model is empty"),
"bail message missing 'model is empty': {err}"
);
}
/// Out-of-range `max_pixels` is silently clamped (not rejected) so
/// a bad config can't kill ingest. The accessor exposes the clamped
/// value so tests can verify the bound; the warning side-effect is
/// tested implicitly (no panic, no error).
#[test]
fn build_clamps_max_pixels_outside_legal_range() {
let too_small =
OllamaVisionOcr::from_parts("http://x", "m", vec![], 1).unwrap();
assert_eq!(too_small.max_pixels(), MIN_LONG_EDGE);
let too_big =
OllamaVisionOcr::from_parts("http://x", "m", vec![], u32::MAX).unwrap();
assert_eq!(too_big.max_pixels(), MAX_LONG_EDGE);
}
}

59
crates/kebab-parse-image/tests/common/mod.rs
View File

@@ -43,6 +43,65 @@ pub fn no_exif_png() -> Vec<u8> {
buf.into_inner()
}
/// 4000×3000 solid-blue PNG (long edge 4000) used to exercise the OCR
/// adapter's downscale path. Solid-colour PNGs compress aggressively, so
/// the on-disk size stays well under 1 MB despite the large dimensions.
pub fn large_blue_4000x3000_png() -> Vec<u8> {
let img: ImageBuffer<Rgb<u8>, _> =
ImageBuffer::from_fn(4000, 3000, |_, _| Rgb([0, 0, 255]));
let mut buf = Cursor::new(Vec::new());
img.write_to(&mut buf, image::ImageFormat::Png)
.expect("encoding 4000x3000 PNG must not fail");
buf.into_inner()
}
/// PNG with the literal text `"Hello World 2026"` rendered in black
/// against a white background. Used by the opt-in
/// `ocr_integration_real_ollama_transcribes_text` integration test —
/// regular hermetic tests never call it.
///
/// Returns `Err` (not panic) if the DejaVu Sans Bold font is missing
/// from the standard Linux path, so dev boxes without the font can
/// gracefully skip the integration test rather than crashing the
/// process.
pub fn hello_world_png() -> anyhow::Result<Vec<u8>> {
use ab_glyph::{Font, FontRef, ScaleFont};
use anyhow::Context;
let mut img: ImageBuffer<Rgb<u8>, _> =
ImageBuffer::from_fn(400, 100, |_, _| Rgb([255, 255, 255]));
let font_path = "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf";
let font_bytes = std::fs::read(font_path).with_context(|| {
format!(
"{font_path} not found — only the opt-in OCR integration fixture needs this font"
)
})?;
let font = FontRef::try_from_slice(&font_bytes).context("DejaVu font parses")?;
let scaled = font.as_scaled(40.0);
let text = "Hello World 2026";
let mut x = 10.0_f32;
let y = 60.0_f32;
for ch in text.chars() {
let glyph = scaled.scaled_glyph(ch);
if let Some(outlined) = scaled.outline_glyph(glyph.clone()) {
let bb = outlined.px_bounds();
outlined.draw(|gx, gy, c| {
let px = (x + bb.min.x + gx as f32) as i32;
let py = (y + bb.min.y + gy as f32) as i32;
if px >= 0 && py >= 0 && (px as u32) < 400 && (py as u32) < 100 {
let v = ((1.0 - c) * 255.0) as u8;
img.put_pixel(px as u32, py as u32, Rgb([v, v, v]));
}
});
}
x += scaled.h_advance(scaled.glyph_id(ch));
}
let mut buf = Cursor::new(Vec::new());
img.write_to(&mut buf, image::ImageFormat::Png)
.context("encoding hello-world PNG")?;
Ok(buf.into_inner())
}
/// JPEG with embedded EXIF APP1 segment carrying GPS + Make + Model +
/// DateTimeOriginal + Orientation + Software. The base image is a 4×4
/// solid white square — pixel content is irrelevant; the test cares about

395
crates/kebab-parse-image/tests/ocr.rs Normal file
View File

@@ -0,0 +1,395 @@
//! Integration tests for the OCR adapter (P6-2).
//!
//! Pattern mirrors `kebab-llm-local/tests/streaming.rs` — `wiremock` is
//! async, so test fns are `#[tokio::test]` and the sync adapter is
//! invoked from `spawn_blocking`.
mod common;
use kebab_config::Config;
use kebab_core::{
AssetId, BlockId, CommonBlock, ImageRefBlock, Lang, ProvenanceEvent, ProvenanceKind,
SourceSpan,
};
use kebab_parse_image::{OcrEngine, OllamaVisionOcr, apply_ocr};
use serde_json::json;
use wiremock::matchers::{method, path};
use wiremock::{Mock, MockServer, ResponseTemplate};
use crate::common::red_100x50_png;
fn cfg_for_endpoint(endpoint: &str) -> Config {
let mut cfg = Config::defaults();
cfg.image.ocr.endpoint = Some(endpoint.to_string());
cfg.image.ocr.model = "gemma4:e4b".to_string();
cfg.image.ocr.languages = vec!["eng".to_string(), "kor".to_string()];
cfg.image.ocr.max_pixels = 1024;
cfg
}
fn run_recognize(
cfg: Config,
bytes: Vec<u8>,
lang_hint: Option<Lang>,
) -> anyhow::Result<kebab_core::OcrText> {
let engine = OllamaVisionOcr::new(&cfg)?;
engine.recognize(&bytes, lang_hint.as_ref())
}
fn empty_image_block() -> ImageRefBlock {
ImageRefBlock {
common: CommonBlock {
block_id: BlockId("0".repeat(32)),
heading_path: Vec::new(),
source_span: SourceSpan::Region {
x: 0,
y: 0,
w: 100,
h: 50,
},
},
asset_id: Some(AssetId("a".repeat(32))),
src: "img/x.png".to_string(),
alt: "x.png".to_string(),
ocr: None,
caption: None,
}
}
// ── Happy path ────────────────────────────────────────────────────────────
#[tokio::test]
async fn ocr_recognize_decodes_response_into_ocr_text() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/api/generate"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"model": "gemma4:e4b",
"response": "Hello World 2026",
"done": true,
"done_reason": "stop"
})))
.mount(&server)
.await;
let bytes = red_100x50_png();
let cfg = cfg_for_endpoint(&server.uri());
let text = tokio::task::spawn_blocking(move || run_recognize(cfg, bytes, None))
.await
.expect("blocking task panicked")
.expect("recognize must succeed");
assert_eq!(text.joined, "Hello World 2026");
assert_eq!(text.engine, "ollama-vision");
assert!(text.engine_version.starts_with("ollama/gemma4:e4b"));
assert_eq!(text.regions.len(), 1, "non-empty joined → exactly one region");
assert_eq!(text.regions[0].text, "Hello World 2026");
assert!((text.regions[0].confidence - 1.0).abs() < 1e-6);
// Region bbox covers prepared image dimensions (100×50 < max_pixels
// 1024 so no downscale, dims preserved).
assert_eq!(text.regions[0].bbox, (0, 0, 100, 50));
}
// ── Empty response ────────────────────────────────────────────────────────
#[tokio::test]
async fn ocr_recognize_empty_response_yields_empty_regions() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/api/generate"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"response": "",
"done": true
})))
.mount(&server)
.await;
let bytes = red_100x50_png();
let cfg = cfg_for_endpoint(&server.uri());
let text = tokio::task::spawn_blocking(move || run_recognize(cfg, bytes, None))
.await
.expect("blocking task panicked")
.expect("recognize on empty response must succeed");
assert_eq!(text.joined, "");
assert!(text.regions.is_empty(), "empty joined → no regions");
assert_eq!(text.engine, "ollama-vision");
}
// ── Server error mapping ──────────────────────────────────────────────────
#[tokio::test]
async fn ocr_recognize_500_response_returns_error() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/api/generate"))
.respond_with(ResponseTemplate::new(500).set_body_string("boom"))
.mount(&server)
.await;
let bytes = red_100x50_png();
let cfg = cfg_for_endpoint(&server.uri());
let r = tokio::task::spawn_blocking(move || run_recognize(cfg, bytes, None))
.await
.expect("blocking task panicked");
assert!(r.is_err(), "5xx must surface as Err");
let msg = format!("{:#}", r.unwrap_err());
assert!(
msg.contains("500") && msg.contains("boom"),
"error must include status + body: {msg}"
);
}
// ── error envelope on 200 stream ─────────────────────────────────────────
#[tokio::test]
async fn ocr_recognize_error_envelope_on_200_returns_error() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/api/generate"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"error": "model 'gemma4:e4b' not found"
})))
.mount(&server)
.await;
let bytes = red_100x50_png();
let cfg = cfg_for_endpoint(&server.uri());
let r = tokio::task::spawn_blocking(move || run_recognize(cfg, bytes, None))
.await
.expect("blocking task panicked");
assert!(r.is_err(), "server error envelope must surface");
let msg = format!("{:#}", r.unwrap_err());
assert!(
msg.contains("not found"),
"error must include server message: {msg}"
);
}
// ── apply_ocr mutates block + appends provenance ─────────────────────────
#[tokio::test]
async fn apply_ocr_sets_block_ocr_and_appends_provenance() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/api/generate"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"response": "안녕 2026",
"done": true
})))
.mount(&server)
.await;
let bytes = red_100x50_png();
let cfg = cfg_for_endpoint(&server.uri());
let (block, events) =
tokio::task::spawn_blocking(move || -> anyhow::Result<_> {
let engine = OllamaVisionOcr::new(&cfg)?;
let mut block = empty_image_block();
let mut events: Vec<ProvenanceEvent> = Vec::new();
apply_ocr(
&engine,
&bytes,
&mut block,
Some(&Lang("ko".to_string())),
&mut events,
)?;
Ok((block, events))
})
.await
.expect("blocking task panicked")
.expect("apply_ocr must succeed");
let ocr = block.ocr.as_ref().expect("ocr Some after apply_ocr");
assert_eq!(ocr.joined, "안녕 2026");
assert_eq!(events.len(), 1);
assert_eq!(events[0].kind, ProvenanceKind::OcrApplied);
assert_eq!(events[0].agent, "kb-parse-image");
let note = events[0].note.as_deref().unwrap_or("");
assert!(
note.contains("engine=ollama-vision") && note.contains("regions=1"),
"provenance note must describe engine + region count: {note}"
);
}
// ── apply_ocr error leaves block untouched ───────────────────────────────
#[tokio::test]
async fn apply_ocr_error_leaves_block_untouched() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/api/generate"))
.respond_with(ResponseTemplate::new(503))
.mount(&server)
.await;
let bytes = red_100x50_png();
let cfg = cfg_for_endpoint(&server.uri());
let (block, events, err) = tokio::task::spawn_blocking(move || {
let engine = OllamaVisionOcr::new(&cfg).expect("engine");
let mut block = empty_image_block();
let mut events: Vec<ProvenanceEvent> = Vec::new();
let res = apply_ocr(&engine, &bytes, &mut block, None, &mut events);
(block, events, res.err())
})
.await
.expect("blocking task panicked");
assert!(err.is_some(), "503 must propagate as Err");
assert!(
block.ocr.is_none(),
"block.ocr stays None when apply_ocr fails — partial state must not leak"
);
assert!(
events.is_empty(),
"no Provenance event when OCR fails — kb-normalize would otherwise lie about success"
);
}
// ── Downscale: large input shrinks before sending ─────────────────────────
#[tokio::test]
async fn ocr_downscales_large_image_before_sending() {
use std::sync::{Arc, Mutex};
// Capture the request body so we can pull out the base64 image and
// measure its dimensions.
let captured: Arc<Mutex<Option<Vec<u8>>>> = Arc::new(Mutex::new(None));
let server = MockServer::start().await;
let cap = captured.clone();
Mock::given(method("POST"))
.and(path("/api/generate"))
.respond_with(move |req: &wiremock::Request| {
let body = req.body.clone();
*cap.lock().unwrap() = Some(body);
ResponseTemplate::new(200).set_body_json(json!({
"response": "ok",
"done": true
}))
})
.mount(&server)
.await;
// 4000×3000 PNG (long edge 4000) — well above the cfg max 1024.
let big = common::large_blue_4000x3000_png();
let cfg = cfg_for_endpoint(&server.uri());
let _ = tokio::task::spawn_blocking({
let cfg = cfg.clone();
move || run_recognize(cfg, big, None)
})
.await
.expect("blocking task panicked")
.expect("recognize succeeds");
// Pull the request body, parse JSON, base64-decode the image, and
// verify the long edge is at most max_pixels (1024).
let raw = captured.lock().unwrap().clone().expect("request captured");
let value: serde_json::Value =
serde_json::from_slice(&raw).expect("request body is JSON");
let imgs = value
.get("images")
.and_then(|v| v.as_array())
.expect("images field present");
assert_eq!(imgs.len(), 1, "exactly one image sent");
let b64 = imgs[0].as_str().expect("image is base64 string");
use base64::Engine as _;
let decoded = base64::engine::general_purpose::STANDARD
.decode(b64)
.expect("base64 decodes");
let reader = image::ImageReader::new(std::io::Cursor::new(decoded))
.with_guessed_format()
.expect("guess format");
let (w, h) = reader.into_dimensions().expect("dims");
let long = w.max(h);
assert!(
long <= 1024,
"long edge after downscale must be <= max_pixels (got {long})"
);
// Aspect ratio preserved within rounding.
let ratio_in = 4000.0 / 3000.0;
let ratio_out = w as f32 / h as f32;
assert!(
(ratio_in - ratio_out).abs() < 0.02,
"aspect ratio drift: in={ratio_in} out={ratio_out}"
);
}
// ── from_parts construction ──────────────────────────────────────────────
#[test]
fn from_parts_clamps_max_pixels_into_legal_range() {
// Below MIN_LONG_EDGE — bumped up to the floor.
let too_small = OllamaVisionOcr::from_parts("http://x", "m", vec![], 10).unwrap();
assert_eq!(
too_small.max_pixels(),
256,
"max_pixels must be raised to MIN_LONG_EDGE"
);
// Above MAX_LONG_EDGE — capped at the ceiling.
let too_big =
OllamaVisionOcr::from_parts("http://x", "m", vec![], 99_999).unwrap();
assert_eq!(
too_big.max_pixels(),
4096,
"max_pixels must be capped at MAX_LONG_EDGE"
);
// Inside the legal range — pass through untouched.
let in_range = OllamaVisionOcr::from_parts("http://x", "m", vec![], 1024).unwrap();
assert_eq!(in_range.max_pixels(), 1024);
}
// ── Integration test against real Ollama (opt-in) ────────────────────────
/// End-to-end OCR against the workspace's real Ollama daemon. Skipped
/// by default via `#[ignore]` (matching the `kebab-llm-local`
/// convention); a developer who explicitly opts in via `--ignored` is
/// signalling they want the network call. Endpoint / model can still
/// be overridden via env to point at a non-default Ollama host.
///
/// Run with:
///
/// ```sh
/// KEBAB_IMAGE_OCR_ENDPOINT=http://192.168.0.47:11434 \
/// cargo test -p kebab-parse-image --test ocr ocr_integration -- --ignored
/// ```
#[tokio::test]
#[ignore = "hits a real Ollama daemon; opt in via `cargo test -- --ignored`"]
async fn ocr_integration_real_ollama_transcribes_text() {
let endpoint = std::env::var("KEBAB_IMAGE_OCR_ENDPOINT")
.unwrap_or_else(|_| "http://192.168.0.47:11434".to_string());
let model =
std::env::var("KEBAB_IMAGE_OCR_MODEL").unwrap_or_else(|_| "gemma4:e4b".to_string());
// Generate a fixture with known text. If the DejaVu font is
// missing from this dev box, skip rather than crash.
let bytes = match common::hello_world_png() {
Ok(b) => b,
Err(e) => {
eprintln!("skipping ocr_integration: {e:#}");
return;
}
};
let cfg = {
let mut c = Config::defaults();
c.image.ocr.endpoint = Some(endpoint);
c.image.ocr.model = model;
c.image.ocr.max_pixels = 1024;
c
};
let text = tokio::task::spawn_blocking(move || run_recognize(cfg, bytes, None))
.await
.expect("blocking task panicked")
.expect("real Ollama OCR must succeed");
eprintln!("integration OCR result: {:?}", text.joined);
let normalized = text.joined.to_lowercase().replace(",", "").replace(".", "");
assert!(
normalized.contains("hello") && normalized.contains("world"),
"integration OCR did not capture expected text: {:?}",
text.joined
);
}

18
tasks/HOTFIXES.md
View File

@@ -14,6 +14,24 @@ historical contract that was implemented; this file accumulates the
deltas so phase 5+ readers can find the live behavior without diffing
git history.
## 2026-05-02 — P6-2 default OCR engine: Tesseract → Ollama-vision
**Discovered**: P6-2 implementation start.
**Symptom**: The original `tasks/p6/p6-2-ocr-adapter.md` spec lists Tesseract as the default OCR engine (`tesseract = "0.13"`, feature `tesseract`, default ON). Bringing Tesseract online requires installing `libtesseract-dev` (and `tesseract-ocr-kor` for the spec-default Korean languages set) on every dev / CI host. The kebab dev environment intentionally avoids system-package installs, so the Tesseract Rust bindings can't link.
**Root cause**: Spec was written assuming a Linux host with `apt install tesseract-ocr-*` available. The reality of single-developer local-first KB is that the same box also runs the Ollama vision endpoint already wired by P4-2 — using it for OCR adds zero new system dependencies.
**Fix** (PR #33, feat/p6-2-ocr-adapter):
- New `OllamaVisionOcr` adapter under `crates/kebab-parse-image/src/ocr.rs`. Implements the spec's `OcrEngine` trait by POSTing the image (base64) to `<endpoint>/api/generate` with a transcription prompt against `gemma4:e4b` (default) or any other vision-capable Ollama model.
- New `kebab-config::ImageCfg.ocr` block (`enabled`, `engine`, `model`, `endpoint`, `languages`, `max_pixels`). `enabled` defaults to `false` because OCR adds a model call per asset; `engine` defaults to `"ollama-vision"`. `endpoint` falls back to `models.llm.endpoint` when empty so the same Ollama host serves both LLM and OCR.
- The `OcrEngine` trait is unchanged from the spec — Tesseract / Apple Vision / PaddleOCR engines plug in as future feature-gated alternatives without touching the extractor or chunker. The trait abstraction is the part the spec actually demanded; only the choice of default implementation changes.
- Tests cover wiremock unit paths (200 happy / 5xx / 200 error envelope / empty response / downscale honours `max_pixels`), `apply_ocr` provenance + error handling, and an opt-in `KEBAB_OCR_INTEGRATION=1` integration test that hits a real Ollama endpoint with a generated `"Hello World 2026"` PNG. Tesseract feature-gated tests from the original spec are deferred to whenever someone is willing to bring `libtesseract` to CI.
**Trust note**: The original spec marked `OcrText` as "observed text (high trust)" to distinguish it from `ModelCaption`. With an LLM-driven default the line blurs — vision LMs can hallucinate. We kept `OcrText.engine = "ollama-vision"` so consumers can decide trust by engine identity. Future Tesseract / Apple Vision adapters write a different `engine` string and downstream code can branch.
**Amends**: tasks/p6/p6-2-ocr-adapter.md (default engine; "Allowed dependencies" list — `reqwest` + `base64` replace `tesseract`; "Apple Vision" feature gate deferred; `min_confidence` config field dropped because the LM doesn't expose per-region confidence).
## 2026-05-01 — `--config` flag silently ignored across all kebab-cli subcommands
**Discovered**: post-P3-5 manual smoke at `/tmp/kebab-smoke/`.

2
tasks/p6/p6-2-ocr-adapter.md
View File

@@ -3,7 +3,7 @@ phase: P6
component: kebab-parse-image (OCR adapter)
task_id: p6-2
title: "OcrEngine trait + Tesseract adapter (Apple Vision feature-gated)"
status: planned
status: completed
depends_on: [p6-1]
unblocks: [p6-3]
contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md