diff --git a/Cargo.lock b/Cargo.lock index 96e76ea..f595476 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -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" diff --git a/crates/kebab-config/src/lib.rs b/crates/kebab-config/src/lib.rs index 9452efb..f9a737c 100644 --- a/crates/kebab-config/src/lib.rs +++ b/crates/kebab-config/src/lib.rs @@ -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, + /// BCP-47 language hints (e.g. `["eng", "kor"]`). The adapter + /// renders them into the prompt; the LLM honours them probabilistically. + pub languages: Vec, + /// 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::() { + 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. diff --git a/crates/kebab-parse-image/Cargo.toml b/crates/kebab-parse-image/Cargo.toml index 5767807..e596d6c 100644 --- a/crates/kebab-parse-image/Cargo.toml +++ b/crates/kebab-parse-image/Cargo.toml @@ -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" diff --git a/crates/kebab-parse-image/src/lib.rs b/crates/kebab-parse-image/src/lib.rs index e357c28..b5d826b 100644 --- a/crates/kebab-parse-image/src/lib.rs +++ b/crates/kebab-parse-image/src/lib.rs @@ -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::{ diff --git a/crates/kebab-parse-image/src/ocr.rs b/crates/kebab-parse-image/src/ocr.rs new file mode 100644 index 0000000..8d7f88a --- /dev/null +++ b/crates/kebab-parse-image/src/ocr.rs @@ -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; +} + +/// 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, +) -> 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 +/// `/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, + 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 { + 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, + model: impl Into, + languages: Vec, + max_pixels: u32, + ) -> Result { + 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, + requested_max_pixels: u32, + ) -> Result { + 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 { + 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, 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, + #[serde(default)] + error: Option, +} + +#[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); + } +} diff --git a/crates/kebab-parse-image/tests/common/mod.rs b/crates/kebab-parse-image/tests/common/mod.rs index 37aee23..7c8e8e0 100644 --- a/crates/kebab-parse-image/tests/common/mod.rs +++ b/crates/kebab-parse-image/tests/common/mod.rs @@ -43,6 +43,65 @@ pub fn no_exif_png() -> Vec { 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 { + let img: ImageBuffer, _> = + 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> { + use ab_glyph::{Font, FontRef, ScaleFont}; + use anyhow::Context; + + let mut img: ImageBuffer, _> = + 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 diff --git a/crates/kebab-parse-image/tests/ocr.rs b/crates/kebab-parse-image/tests/ocr.rs new file mode 100644 index 0000000..f6c0d9b --- /dev/null +++ b/crates/kebab-parse-image/tests/ocr.rs @@ -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, + lang_hint: Option, +) -> anyhow::Result { + 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 = 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 = 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>>> = 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 + ); +} diff --git a/tasks/HOTFIXES.md b/tasks/HOTFIXES.md index 9e63261..e11346a 100644 --- a/tasks/HOTFIXES.md +++ b/tasks/HOTFIXES.md @@ -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 `/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/`. diff --git a/tasks/p6/p6-2-ocr-adapter.md b/tasks/p6/p6-2-ocr-adapter.md index f349773..d11a3ab 100644 --- a/tasks/p6/p6-2-ocr-adapter.md +++ b/tasks/p6/p6-2-ocr-adapter.md @@ -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