Skip to main content

ocr_mcp/
ocr.rs

1// Copyright (c) 2026 Enzo Lombardi
2// SPDX-License-Identifier: MIT
3
4//! The inference boundary.
5//!
6//! `OcrEngine` exists for the same reason plank's `Engine` trait does: it lets
7//! the JSON-RPC layer be driven end to end in CI, where no GGUF and no
8//! `llama-server` exist. `StubOcr` is this crate's `EchoEngine`.
9
10use crate::image_input::DecodedImage;
11use std::path::PathBuf;
12
13/// The default instruction when the caller supplies no question.
14///
15/// It asks for transcription and layout only. At 0.9B, an instruction that
16/// invites reasoning yields confident fiction instead of characters, so the
17/// wording deliberately never asks the model to explain, diagnose, or judge.
18pub const DEFAULT_PROMPT: &str = "Transcribe every piece of text visible in this image, verbatim and in reading order, preserving line breaks. Then describe the layout in one short paragraph: what regions exist and where. Do not explain, interpret, or guess at anything that is not legible; write [illegible] instead.";
19
20/// Everything that can go wrong between a tool call and a transcription.
21#[derive(Debug, Clone, PartialEq, Eq)]
22pub enum OcrError {
23    /// No `llama-server` on `PATH` and none configured.
24    BinaryMissing,
25    /// Model and/or projector are absent from disk.
26    WeightsMissing {
27        model: PathBuf,
28        mmproj: PathBuf,
29        auto_download: bool,
30    },
31    /// The child process could not be started.
32    SpawnFailed(String),
33    /// The child started but never answered `/health` in time; carries the
34    /// tail of its captured stderr.
35    NotReady(String),
36    /// The HTTP request itself failed or timed out.
37    RequestFailed(String),
38    /// A response arrived but was not usable.
39    BadResponse(String),
40}
41
42impl std::fmt::Display for OcrError {
43    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
44        match self {
45            Self::BinaryMissing => write!(
46                f,
47                "llama-server was not found on PATH. Install it with `brew install llama.cpp`, \
48                 or set OCR_MCP_BINARY to its full path."
49            ),
50            Self::WeightsMissing {
51                model,
52                mmproj,
53                auto_download,
54            } => {
55                write!(
56                    f,
57                    "the GLM-OCR weights are not installed. Expected:\n  {}\n  {}\n",
58                    model.display(),
59                    mmproj.display()
60                )?;
61                if *auto_download {
62                    write!(
63                        f,
64                        "The automatic download failed; fetch both files by hand."
65                    )
66                } else {
67                    write!(
68                        f,
69                        "Set OCR_MCP_AUTO_DOWNLOAD=1 in this server's env to fetch them \
70                         (about 1.34 GiB, once — on the first transcription), or download \
71                         both files by hand."
72                    )
73                }
74            }
75            Self::SpawnFailed(e) => write!(f, "could not start llama-server: {e}"),
76            Self::NotReady(tail) => write!(
77                f,
78                "llama-server did not become ready in time. Its last output was:\n{tail}"
79            ),
80            Self::RequestFailed(e) => write!(f, "the transcription request failed: {e}"),
81            Self::BadResponse(e) => write!(
82                f,
83                "the model returned nothing usable ({e}). If the image is a light-on-dark \
84                 terminal capture, try a light background: OCR accuracy at this model size \
85                 degrades measurably on inverted contrast."
86            ),
87        }
88    }
89}
90
91/// Turns one image into text.
92pub trait OcrEngine {
93    /// Transcribes or answers a question about `image`.
94    ///
95    /// # Errors
96    /// Returns the variant of [`OcrError`] describing the failure; its
97    /// `Display` text is what the caller sees.
98    fn describe(&mut self, image: &DecodedImage, prompt: &str) -> Result<String, OcrError>;
99}
100
101/// A backend that needs no model, no binary, and no network.
102pub struct StubOcr {
103    reply: Result<String, OcrError>,
104    /// The prompt from the most recent call, for assertions.
105    pub last_prompt: Option<String>,
106}
107
108impl StubOcr {
109    /// A stub that always succeeds with `reply`.
110    #[must_use]
111    pub fn new(reply: &str) -> Self {
112        Self {
113            reply: Ok(reply.to_string()),
114            last_prompt: None,
115        }
116    }
117
118    /// A stub that always fails with `err`.
119    #[must_use]
120    pub fn failing(err: OcrError) -> Self {
121        Self {
122            reply: Err(err),
123            last_prompt: None,
124        }
125    }
126}
127
128impl OcrEngine for StubOcr {
129    fn describe(&mut self, _image: &DecodedImage, prompt: &str) -> Result<String, OcrError> {
130        self.last_prompt = Some(prompt.to_string());
131        self.reply.clone()
132    }
133}
134
135#[cfg(test)]
136mod tests {
137    use super::*;
138
139    fn img() -> DecodedImage {
140        DecodedImage {
141            media_type: "image/png",
142            bytes: vec![0x89, b'P', b'N', b'G'],
143        }
144    }
145
146    #[test]
147    fn stub_returns_its_canned_reply() {
148        let mut e = StubOcr::new("error: index out of range");
149        assert_eq!(
150            e.describe(&img(), DEFAULT_PROMPT).unwrap(),
151            "error: index out of range"
152        );
153    }
154
155    #[test]
156    fn stub_records_the_prompt_it_was_given() {
157        let mut e = StubOcr::new("ok");
158        let _ = e.describe(&img(), "What is the exit code?");
159        assert_eq!(e.last_prompt.as_deref(), Some("What is the exit code?"));
160    }
161
162    #[test]
163    fn stub_can_be_made_to_fail() {
164        let mut e = StubOcr::failing(OcrError::BinaryMissing);
165        assert!(e.describe(&img(), DEFAULT_PROMPT).is_err());
166    }
167
168    /// Error text is a product surface: each variant must name the fix.
169    #[test]
170    fn error_text_names_the_fix() {
171        assert!(
172            OcrError::BinaryMissing
173                .to_string()
174                .contains("brew install llama.cpp")
175        );
176
177        let missing = OcrError::WeightsMissing {
178            model: PathBuf::from("/w/glm-ocr.gguf"),
179            mmproj: PathBuf::from("/w/glm-ocr-mmproj.gguf"),
180            auto_download: false,
181        };
182        let text = missing.to_string();
183        assert!(text.contains("/w/glm-ocr.gguf"));
184        assert!(text.contains("/w/glm-ocr-mmproj.gguf"));
185        assert!(text.contains("OCR_MCP_AUTO_DOWNLOAD"));
186
187        assert!(
188            OcrError::NotReady("boom".into())
189                .to_string()
190                .contains("boom")
191        );
192    }
193
194    /// Light-on-dark degrades OCR at this size; the hint belongs in the text
195    /// the user actually reads, not in a comment.
196    #[test]
197    fn request_failure_mentions_the_contrast_caveat() {
198        let text = OcrError::BadResponse("empty".into()).to_string();
199        assert!(text.contains("light-on-dark"), "got: {text}");
200    }
201}