1use crate::image_input::DecodedImage;
11use std::path::PathBuf;
12
13pub 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#[derive(Debug, Clone, PartialEq, Eq)]
22pub enum OcrError {
23 BinaryMissing,
25 WeightsMissing {
27 model: PathBuf,
28 mmproj: PathBuf,
29 auto_download: bool,
30 },
31 SpawnFailed(String),
33 NotReady(String),
36 RequestFailed(String),
38 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
91pub trait OcrEngine {
93 fn describe(&mut self, image: &DecodedImage, prompt: &str) -> Result<String, OcrError>;
99}
100
101pub struct StubOcr {
103 reply: Result<String, OcrError>,
104 pub last_prompt: Option<String>,
106}
107
108impl StubOcr {
109 #[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 #[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 #[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 #[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}