pi-ocr 1.0.0

package/extensions/mineru.ts

@@ -0,0 +1,276 @@
+/**
+ * pi-minimodel-ocr — MinerU API backend
+ *
+ * Uses the free Agent Lightweight API (no token required):
+ *   - File ≤10MB, ≤20 pages → one free request
+ *   - File ≤10MB, >20 pages → auto-splits into ≤20-page chunks (if mineruSplitPdf enabled)
+ *   - File >10MB → warns and suggests compression at ilovepdf.com
+ *
+ * API flow (file mode) — each chunk is a SEPARATE request (not batch):
+ *   1. POST /api/v1/agent/parse/file → task_id + signed OSS upload URL
+ *   2. PUT file bytes to signed URL
+ *   3. Poll GET /api/v1/agent/parse/{task_id} until state=done
+ *   4. GET markdown_url → download final Markdown
+ *
+ * PDF splitting uses pypdfium2 (same dep as Pix2Text backend).
+ */
+
+import { readFileSync, mkdtempSync, unlinkSync, rmdirSync, readdirSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { stat } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import type { Task, OcrResult, OcrProgressCallback } from "./types";
+
+const BASE_URL = "https://mineru.net/api/v1/agent";
+
+// ── Python PDF splitter (uses pypdfium2) ─────────────────────────────────────
+
+const PDF_SPLIT_SCRIPT = `
+import sys, json, os
+import pypdfium2 as pdfium
+
+input_path = sys.argv[1]
+chunk_size = int(sys.argv[2])
+output_dir = sys.argv[3]
+
+src = pdfium.PdfDocument(input_path)
+total = len(src)
+
+results = []
+for start in range(0, total, chunk_size):
+    end = min(start + chunk_size, total)
+
+    # Create a new PDF with pages [start, end)
+    dst = pdfium.PdfDocument.new()
+    dst.import_pages(src, list(range(start, end)))
+    out_path = os.path.join(output_dir, f"chunk_{start // chunk_size + 1}.pdf")
+    dst.save(out_path)
+    dst.close()
+
+    results.append({"path": out_path, "firstPage": start + 1, "lastPage": end})
+
+src.close()
+print(json.dumps({"total": total, "chunks": results}))
+`;
+
+async function execPy(code: string, args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("python3", ["-c", code, ...args], { stdio: ["ignore", "pipe", "pipe"] });
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    child.stdout.on("data", (d) => out.push(d));
+    child.stderr.on("data", (d) => err.push(d));
+    child.on("error", () => reject(new Error(
+      "python3 not found. Install Python 3 and pypdfium2:\n  pip install pypdfium2"
+    )));
+    child.on("close", (code) => {
+      if (code === 0) resolve(Buffer.concat(out).toString("utf8").trim());
+      else reject(new Error(Buffer.concat(err).toString("utf8").trim() || `python3 exited with code ${code}`));
+    });
+  });
+}
+
+function rmdirSafe(dir: string) {
+  try {
+    for (const f of readdirSync(dir)) unlinkSync(join(dir, f));
+    rmdirSync(dir);
+  } catch { /* best effort */ }
+}
+
+// ── MinerU API helpers ───────────────────────────────────────────────────────
+
+async function apiPost(url: string, body: Record<string, unknown>): Promise<{ task_id: string; file_url?: string }> {
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(30_000),
+  });
+
+  if (resp.status === 429) throw new Error("MinerU rate limit (429). Wait a minute and retry, or switch backend with /ocr.");
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw new Error(`MinerU API error ${resp.status}: ${text.slice(0, 200)}`);
+  }
+
+  const data = (await resp.json()) as { code: number; msg: string; data: { task_id: string; file_url?: string } };
+  if (data.code !== 0 || !data.data?.task_id) {
+    throw new Error(`MinerU API error: ${data.msg || "no task_id returned"}`);
+  }
+
+  return { task_id: data.data.task_id, file_url: data.data.file_url };
+}
+
+async function putFile(uploadUrl: string, filePath: string): Promise<void> {
+  const fileData = readFileSync(filePath);
+  const resp = await fetch(uploadUrl, {
+    method: "PUT",
+    body: fileData,
+    signal: AbortSignal.timeout(60_000),
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw new Error(`File upload failed (${resp.status}): ${text.slice(0, 200)}`);
+  }
+}
+
+async function pollTask(taskId: string, timeoutMs: number, progressPrefix: string, onProgress: OcrProgressCallback): Promise<string> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const resp = await fetch(`${BASE_URL}/parse/${taskId}`, {
+      signal: AbortSignal.timeout(10_000),
+    });
+    const data = (await resp.json()) as {
+      code: number;
+      data: { state: string; markdown_url?: string; err_msg?: string; err_code?: number };
+    };
+
+    const state = data.data?.state || "unknown";
+
+    if (state === "done") {
+      const markdownUrl = data.data.markdown_url;
+      if (!markdownUrl) throw new Error("MinerU returned done state but no markdown_url");
+      const mdResp = await fetch(markdownUrl, { signal: AbortSignal.timeout(60_000) });
+      if (!mdResp.ok) throw new Error(`Failed to download markdown: ${mdResp.status}`);
+      return mdResp.text();
+    }
+
+    if (state === "failed") {
+      throw new Error(`MinerU parsing failed: ${data.data.err_msg || "unknown error"} (code: ${data.data.err_code})`);
+    }
+
+    const elapsed = Math.floor((Date.now() - start) / 1000);
+    onProgress(`${progressPrefix} ${state} (${elapsed}s)`);
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+  throw new Error(`MinerU task ${taskId} timed out after ${timeoutMs / 1000}s`);
+}
+
+// ── Single-file processing (one individual request, NOT batch) ───────────────
+
+async function mineruProcessFile(
+  filePath: string, fileName: string, progressPrefix: string,
+  onProgress: OcrProgressCallback,
+): Promise<string> {
+  const stats = await stat(filePath);
+  const sizeMB = stats.size / (1024 * 1024);
+  if (sizeMB > 10) {
+    throw new Error(
+      `File too large for free MinerU API: ${sizeMB.toFixed(1)}MB (limit: 10MB).\n` +
+      `Compress at https://ilovepdf.com/compress_pdf or switch to Ollama/Pix2Text backend with /ocr.`
+    );
+  }
+
+  // Step 1: Get signed upload URL
+  onProgress(`${progressPrefix} uploading…`);
+  const { task_id, file_url } = await apiPost(`${BASE_URL}/parse/file`, {
+    file_name: fileName,
+    language: "en",
+    enable_table: true,
+    enable_formula: true,
+    is_ocr: false,
+  });
+
+  if (!file_url) {
+    throw new Error("MinerU did not return a file upload URL — this endpoint may have changed.");
+  }
+
+  // Step 2: Upload file bytes
+  await putFile(file_url, filePath);
+
+  // Step 3 + 4: Poll for result and download markdown
+  onProgress(`${progressPrefix} pending…`);
+  const markdown = await pollTask(task_id, 300_000, progressPrefix, onProgress);
+  onProgress(`${progressPrefix} done`);
+  return markdown;
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+export async function mineruOcr(
+  filePath: string, task: Task, splitPdf: boolean,
+  signal: AbortSignal | undefined, onProgress: OcrProgressCallback,
+): Promise<OcrResult> {
+  const ext = extname(filePath).toLowerCase();
+  const fileName = basename(filePath);
+
+  // For images (non-PDF): process as a single individual request
+  if (ext !== ".pdf") {
+    if (![".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif"].includes(ext)) {
+      throw new Error(`MinerU does not support this file type: ${ext}. Use PDF, PNG, JPG, Docx, PPTx, or Xlsx.`);
+    }
+    const markdown = await mineruProcessFile(filePath, fileName, "[1/1]", onProgress);
+    return { text: markdown, details: { backend: "mineru", fileName, pages: 1 } };
+  }
+
+  // ── PDF handling ──
+  const { getPdfPageCount } = await import("./ollama");
+  const pageCount = await getPdfPageCount(filePath);
+
+  const totalStats = await stat(filePath);
+  const totalMB = totalStats.size / (1024 * 1024);
+
+  if (totalMB > 10) {
+    onProgress(
+      `⚠️ PDF is ${totalMB.toFixed(1)}MB — MinerU free tier limit is 10MB.\n` +
+      `💡 Compress at https://ilovepdf.com/compress_pdf first, or switch backend with /ocr.`
+    );
+  }
+
+  // Single chunk case: one individual request
+  if (pageCount <= 20) {
+    const markdown = await mineruProcessFile(filePath, fileName, "[1/1]", onProgress);
+    return { text: markdown, details: { backend: "mineru", fileName, pages: pageCount } };
+  }
+
+  // ── Multi-chunk: split PDF and process each chunk as SEPARATE requests ──
+  if (!splitPdf) {
+    onProgress(
+      `⚠️ PDF has ${pageCount} pages but splitting is disabled.\n` +
+      `Enable in /ocr settings → "MinerU: Split PDF >20 pages: ON"`
+    );
+    try {
+      const markdown = await mineruProcessFile(filePath, fileName, "[1/1]", onProgress);
+      return { text: markdown, details: { backend: "mineru", fileName, pages: pageCount } };
+    } catch (e: any) {
+      throw new Error(
+        `${e.message}\n\n💡 Enable PDF splitting in /ocr settings.`
+      );
+    }
+  }
+
+  onProgress(`Splitting ${pageCount}-page PDF into ≤20-page chunks…`);
+
+  const splitDir = mkdtempSync(join(tmpdir(), "pi-mineru-split-"));
+  try {
+    const raw = await execPy(PDF_SPLIT_SCRIPT, [filePath, "20", splitDir]);
+    const { chunks } = JSON.parse(raw) as {
+      total: number;
+      chunks: Array<{ path: string; firstPage: number; lastPage: number }>;
+    };
+
+    const results: string[] = [];
+    for (let i = 0; i < chunks.length; i++) {
+      if (signal?.aborted) throw new Error("Aborted");
+      const chunk = chunks[i];
+      const prefix = `[${i + 1}/${chunks.length}]`;
+
+      if (i > 0) {
+        onProgress(`${prefix} waiting rate limit…`);
+        await new Promise((r) => setTimeout(r, 3_000));
+      }
+
+      const chunkName = `${fileName.replace(/\.pdf$/i, "")}_p${chunk.firstPage}-${chunk.lastPage}.pdf`;
+      const markdown = await mineruProcessFile(chunk.path, chunkName, prefix, onProgress);
+      results.push(`## Pages ${chunk.firstPage}-${chunk.lastPage}\n\n${markdown}`);
+    }
+
+    return {
+      text: results.join("\n\n"),
+      details: { backend: "mineru", fileName, pages: pageCount, chunks: chunks.length },
+    };
+  } finally {
+    rmdirSafe(splitDir);
+  }
+}

package/extensions/ollama.ts

@@ -0,0 +1,226 @@
+/**
+ * pi-minimodel-ocr — Ollama backend
+ *
+ * Uses any locally-running Ollama vision model (default: glm-ocr) to OCR
+ * images and PDFs. Converts PDF pages to PNG before sending to Ollama.
+ */
+
+import { readFileSync, existsSync, mkdtempSync, readdirSync, unlinkSync, rmdirSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
+import type { Task, OcrResult, OcrProgressCallback } from "./types";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+export function isImage(filePath: string): boolean {
+  const ext = extname(filePath).toLowerCase();
+  return [".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif"].includes(ext);
+}
+
+export function isPdf(filePath: string): boolean {
+  const ext = extname(filePath).toLowerCase();
+  if (ext === ".pdf") return true;
+  try {
+    const buf = readFileSync(filePath).subarray(0, 4);
+    return buf.toString() === "%PDF";
+  } catch {
+    return false;
+  }
+}
+
+function execCmdCapture(cmd: string, args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const outChunks: Buffer[] = [];
+    const errChunks: Buffer[] = [];
+    child.stdout.on("data", (d) => outChunks.push(d));
+    child.stderr.on("data", (d) => errChunks.push(d));
+    child.on("error", (e) => {
+      reject(new Error(`${cmd}: ${(e as any).code === "ENOENT" ? "command not found" : e.message}`));
+    });
+    child.on("close", (code) => {
+      const stderr = Buffer.concat(errChunks).toString("utf8").trim();
+      if (code === 0) {
+        resolve(Buffer.concat(outChunks).toString("utf8"));
+      } else {
+        reject(new Error(`${cmd} exited with code ${code}${stderr ? ": " + stderr : ""}`));
+      }
+    });
+  });
+}
+
+function cleanupDir(dir: string) {
+  try {
+    for (const f of readdirSync(dir)) unlinkSync(join(dir, f));
+    rmdirSync(dir);
+  } catch { /* best effort */ }
+}
+
+function buildPrompt(task: Task): string {
+  switch (task) {
+    case "text": return "Text Recognition";
+    case "formula": return "Formula Recognition";
+    case "table": return "Table Recognition";
+    case "figure": return "Figure Recognition";
+    case "auto":
+      return "Recognize all text, formulas, tables, and figures in this document. Output formulas in LaTeX format, tables in Markdown format.";
+  }
+}
+
+// ── PDF helpers ──────────────────────────────────────────────────────────────
+
+export async function getPdfPageCount(pdfPath: string): Promise<number> {
+  if (process.platform === "darwin") {
+    try {
+      const out = await execCmdCapture("mdls", ["-name", "kMDItemNumberOfPages", "-raw", pdfPath]);
+      const n = parseInt(out.trim(), 10);
+      if (!isNaN(n) && n > 0) return n;
+    } catch { /* fall through */ }
+  }
+  if (process.platform === "linux") {
+    try {
+      const out = await execCmdCapture("pdfinfo", [pdfPath]);
+      const m = out.match(/Pages:\s+(\d+)/);
+      if (m) return parseInt(m[1], 10) || 1;
+    } catch { /* fall through */ }
+  }
+  return 1;
+}
+
+async function convertPdfPageMac(pdfPath: string, pageIndex: number, outPath: string): Promise<void> {
+  if (pageIndex === 0) {
+    try {
+      await execCmdCapture("sips", ["-s", "format", "png", pdfPath, "--out", outPath]);
+      return;
+    } catch (e: any) {
+      throw new Error(`sips PDF conversion failed: ${e.message}`);
+    }
+  }
+  try {
+    await execCmdCapture("pdftoppm", [
+      "-png", "-r", "150", "-f", String(pageIndex + 1), "-l", String(pageIndex + 1),
+      "-singlefile", pdfPath, outPath.replace(/\.png$/, ""),
+    ]);
+    if (!existsSync(outPath) || readFileSync(outPath).length === 0) {
+      throw new Error(`pdftoppm produced no output for page ${pageIndex + 1}`);
+    }
+    return;
+  } catch (e: any) {
+    const msg = e.message || String(e);
+    if (msg.includes("command not found") || msg.includes("ENOENT")) {
+      throw new Error(`pdftoppm not found. Install with: brew install poppler. Only page 1 was processed with sips.`);
+    }
+    throw new Error(`PDF page ${pageIndex + 1} conversion failed: ${msg}`);
+  }
+}
+
+async function convertPdfPage(pdfPath: string, pageIndex: number, outPath: string): Promise<void> {
+  if (process.platform === "darwin") {
+    await convertPdfPageMac(pdfPath, pageIndex, outPath);
+  } else {
+    await execCmdCapture("pdftoppm", [
+      "-png", "-r", "150", "-f", String(pageIndex + 1), "-l", String(pageIndex + 1),
+      "-singlefile", pdfPath, outPath.replace(/\.png$/, ""),
+    ]);
+  }
+}
+
+// ── Ollama API call ──────────────────────────────────────────────────────────
+
+async function callOllama(
+  host: string, imagePath: string, task: Task, signal: AbortSignal | undefined, model: string,
+): Promise<string> {
+  const imageBase64 = readFileSync(imagePath).toString("base64");
+  const prompt = buildPrompt(task);
+
+  const body = JSON.stringify({ model, prompt, images: [imageBase64], stream: false });
+
+  const response = await fetch(`${host}/api/generate`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body,
+    signal,
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`Ollama API error ${response.status}: ${text.slice(0, 200)}. Is Ollama running and is the ${model} model pulled?`);
+  }
+
+  const data = (await response.json()) as { response?: string; error?: string };
+  if (data.error) throw new Error(`OCR error: ${data.error}`);
+  return data.response?.trim() || "";
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+export async function ollamaOcr(
+  filePath: string, task: Task, ollamaHost: string, model: string,
+  signal: AbortSignal | undefined, onProgress: OcrProgressCallback,
+): Promise<OcrResult> {
+  let resultText = "";
+  let tmpDir: string | null = null;
+
+  try {
+    if (isPdf(filePath)) {
+      onProgress("📄 Converting PDF pages to images…");
+      tmpDir = mkdtempSync(join(tmpdir(), "pi-ocr-"));
+      const pageCount = await getPdfPageCount(filePath);
+
+      // Proactive check for multi-page PDF on macOS without pdftoppm
+      if (pageCount > 1 && process.platform === "darwin") {
+        try { await execCmdCapture("pdftoppm", ["-v"]); } catch {
+          onProgress(`⚠️ Multi-page PDF (${pageCount} pages) but pdftoppm is not installed. Only page 1 will be processed.\nInstall: brew install poppler`);
+        }
+      }
+
+      const pageResults: string[] = [];
+      for (let i = 0; i < pageCount; i++) {
+        if (signal?.aborted) throw new Error("Aborted");
+        const pageOut = join(tmpDir, `page_${i + 1}.png`);
+
+        try {
+          await convertPdfPage(filePath, i, pageOut);
+        } catch (e: any) {
+          pageResults.push(`## Page ${i + 1}\n\n> ⚠️ Skipped: ${e.message}`);
+          continue;
+        }
+
+        onProgress(`🔍 OCR page ${i + 1}/${pageCount}…`);
+        const pageText = await callOllama(ollamaHost, pageOut, task, signal, model);
+        if (!pageText.trim()) {
+          pageResults.push(`## Page ${i + 1}\n\n> ⚠️ OCR returned empty result for this page.`);
+        } else {
+          pageResults.push(`## Page ${i + 1}\n\n${pageText}`);
+        }
+      }
+      resultText = pageResults.join("\n\n");
+    } else {
+      resultText = await callOllama(ollamaHost, filePath, task, signal, model);
+    }
+
+    return { text: resultText, details: { backend: "ollama", model, task } };
+  } finally {
+    if (tmpDir) cleanupDir(tmpDir);
+  }
+}
+
+/** Check if a model exists locally via Ollama API */
+export async function ollamaCheckModel(host: string, model: string): Promise<boolean> {
+  try {
+    const resp = await fetch(`${host}/api/show`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: model }),
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** Pull a model via ollama pull */
+export function ollamaPullModel(model: string): Promise<void> {
+  return execCmdCapture("ollama", ["pull", model]).then(() => {});
+}

package/extensions/pix2text.ts

@@ -0,0 +1,189 @@
+/**
+ * pi-minimodel-ocr — Pix2Text backend
+ *
+ * Uses Pix2Text (https://github.com/breezedeus/Pix2Text) — an open-source
+ * Python alternative to Mathpix. Recognizes layouts, text, math formulas (LaTeX),
+ * and tables, outputting Markdown directly. SMALL ONNX models, CPU-friendly.
+ *
+ * Prerequisites:
+ *   pip install pix2text
+ *
+ * First run downloads ONNX models (~50MB) to ~/.pix2text/1.1/.
+ *
+ * Progress reporting: for multi-page PDFs, processes pages individually
+ * and sends per-page progress via stderr (JSON lines), final result via stdout.
+ */
+
+import { spawn } from "node:child_process";
+import { basename } from "node:path";
+import type { Task, OcrResult, OcrProgressCallback } from "./types";
+import { isImage, isPdf } from "./ollama";
+
+// ── Embedded Python OCR engine ───────────────────────────────────────────────
+//
+// For PDFs: extracts pages via PyMuPDF, runs Pix2Text on each page individually,
+//           printing progress JSON to stderr so TypeScript can relay it.
+// For images: single call to p2t.recognize().
+//
+// Usage: python3 -c SCRIPT <file_path> <task>
+//   stdout → final Markdown result
+//   stderr → progress lines: {"page": 1, "total": 10} / {"status": "loading"} / errors
+
+const PIX2TEXT_ENGINE = `
+import sys, os, json, io
+from pathlib import Path
+
+file_path = sys.argv[1]
+task = sys.argv[2]
+ext = Path(file_path).suffix.lower()
+
+# Suppress noisy library output
+os.environ.setdefault("DISABLE_TQDM", "1")
+
+# Progress helper — JSON lines to stderr
+def progress(payload):
+    print(json.dumps(payload), file=sys.stderr, flush=True)
+
+progress({"status": "loading", "message": "Initializing Pix2Text models..."})
+
+from pix2text import Pix2Text
+p2t = Pix2Text.from_config(enable_formula=True, enable_table=False)
+
+if ext == ".pdf":
+    import fitz  # PyMuPDF — already a pix2text dependency
+
+    progress({"status": "loading", "message": "Opening PDF..."})
+    doc = fitz.open(file_path)
+    total = len(doc)
+    progress({"status": "started", "pages": total})
+
+    results = []
+    for i in range(total):
+        progress({"status": "page", "page": i + 1, "total": total})
+
+        # Render page to PNG at 200 DPI
+        page = doc[i]
+        pix = page.get_pixmap(dpi=200)
+        img_bytes = pix.tobytes("png")
+
+        # Write to temp file (Pix2Text needs a file path)
+        tmp_path = f"/tmp/pi-p2t-page-{os.getpid()}-{i}.png"
+        with open(tmp_path, "wb") as f:
+            f.write(img_bytes)
+
+        try:
+            text = p2t.recognize(tmp_path)
+            if text:
+                results.append(f"## Page {i + 1}\\n\\n{text}")
+            else:
+                results.append(f"## Page {i + 1}\\n\\n> ⚠️ No text detected")
+        except Exception as e:
+            results.append(f"## Page {i + 1}\\n\\n> ⚠️ Error: {e}")
+        finally:
+            try:
+                os.unlink(tmp_path)
+            except:
+                pass
+
+    doc.close()
+    progress({"status": "done", "pages": total})
+    print("\\n\\n".join(results))
+
+elif ext in (".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif"):
+    progress({"status": "recognizing"})
+    result = p2t.recognize(file_path)
+    progress({"status": "done", "pages": 1})
+    print(result if result else "")
+
+else:
+    progress({"status": "error", "message": f"Unsupported file type: {ext}"})
+    print(f"ERROR: unsupported file type {ext}")
+    sys.exit(1)
+`;
+
+// ── Subprocess runner with progress streaming ────────────────────────────────
+
+async function execPythonWithProgress(
+  code: string, args: string[], onProgress: OcrProgressCallback,
+): Promise<{ stdout: string; exitCode: number }> {
+  return new Promise((resolve) => {
+    const child = spawn("python3", ["-c", code, ...args], { stdio: ["ignore", "pipe", "pipe"] });
+    const outChunks: Buffer[] = [];
+    let lastPageReported = 0;
+
+    child.stdout.on("data", (d) => outChunks.push(d));
+
+    child.stderr.on("data", (d) => {
+      const text = d.toString("utf8").trim();
+      // Parse JSON progress lines, ignore noisy library output
+      for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("{")) continue;
+        try {
+          const p = JSON.parse(trimmed);
+          if (p.status === "page" && p.page && p.total) {
+            // Only report every 5th page or first/last to avoid spam
+            if (p.page !== lastPageReported) {
+              lastPageReported = p.page;
+              onProgress(`📄 Page ${p.page}/${p.total}`);
+            }
+          } else if (p.status === "loading" && p.message) {
+            onProgress(`⏳ ${p.message}`);
+          } else if (p.status === "started" && p.pages) {
+            onProgress(`📄 Processing ${p.pages} page(s) with Pix2Text…`);
+          } else if (p.status === "done") {
+            onProgress(`✅ Pix2Text complete (${p.pages} page(s))`);
+          } else if (p.status === "error") {
+            // Error will be handled by exit code
+          }
+        } catch {
+          // Not JSON — library noise, ignore
+        }
+      }
+    });
+
+    child.on("error", () => resolve({
+      stdout: "",
+      exitCode: 1,
+    }));
+
+    child.on("close", (code) => {
+      resolve({
+        stdout: Buffer.concat(outChunks).toString("utf8").trim(),
+        exitCode: code ?? 1,
+      });
+    });
+  });
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+export async function pix2textOcr(
+  filePath: string, task: Task,
+  signal: AbortSignal | undefined, onProgress: OcrProgressCallback,
+): Promise<OcrResult> {
+  if (!isImage(filePath) && !isPdf(filePath)) {
+    throw new Error(`Unsupported file type: ${basename(filePath)}`);
+  }
+
+  const { stdout, exitCode } = await execPythonWithProgress(
+    PIX2TEXT_ENGINE, [filePath, task], onProgress,
+  );
+
+  if (exitCode !== 0) {
+    const msg = stdout || "Pix2Text failed";
+    if (msg.includes("ModuleNotFoundError") || msg.includes("No module named")) {
+      throw new Error("Pix2Text not installed. Run:\n  pip install pix2text");
+    }
+    if (msg.includes("table-rec") || msg.includes("pytorch_model")) {
+      throw new Error("Pix2Text model download incomplete. Try:\n  pip install pix2text --upgrade");
+    }
+    throw new Error(msg.slice(0, 1000));
+  }
+
+  if (!stdout || stdout.startsWith("ERROR:")) {
+    return { text: "", details: { backend: "pix2text", task, warning: stdout || "no text detected" } };
+  }
+
+  return { text: stdout, details: { backend: "pix2text", task } };
+}