DuffyCoder Image / PDF OCR (SophNet API)
Extract text and tables from images or PDF using the SophNet API. Supports local image/PDF files and direct URLs, returning Markdown-formatted output.
- PDF：多页 PDF 按页转成图片（低 DPI 以节省内存），逐页调用 OCR 后合并结果，并自动删除缓存的临时图片。
Image Path Resolution
Important: When users upload images via webchat or other channels, Moltbot saves them to media/inbound/images/ in the workspace. The system prompt includes media understanding logs that show the resolved absolute path.
Look for logs like:
[Media Understanding] Resolved relative path: "media/inbound/images/xxx.jpg" -> "/absolute/path/to/workspace/media/inbound/images/xxx.jpg"
Quick Start
Run OCR on an image or PDF:
uv run {baseDir}/scripts/ocr.py <image-or-pdf-path-or-url>
This will:
- Image：Convert local images to base64, call PaddleOCR-VL API, output Markdown.
- PDF：Create a temp dir → render each page to PNG (150 DPI, low resource) → OCR each page → merge text with page markers → delete temp images and temp dir.
Usage Examples
Local image file:
uv run {baseDir}/scripts/ocr.py /path/to/image.jpg
uv run {baseDir}/scripts/ocr.py media/inbound/images/uploaded_image.png
Local PDF (multi-page supported):
uv run {baseDir}/scripts/ocr.py /path/to/document.pdf
URL (image or PDF):
uv run {baseDir}/scripts/ocr.py https://example.com/image.jpg
uv run {baseDir}/scripts/ocr.py https://example.com/doc.pdf
Custom options:
uv run {baseDir}/scripts/ocr.py <image> \
--model PaddleOCR-VL-0.9B \
--no-prettify-markdown \
--show-formula-number
Script Options
<image-or-pdf-path-or-url>(required): Local image/PDF path or HTTP/HTTPS URL--model(optional): Model to use. Default:PaddleOCR-VL-0.9B--prettify-markdown/--no-prettify-markdown(optional): Format output as Markdown. Default: enabled--show-formula-number/--no-show-formula-number(optional): Show formula numbering. Default: disabled
Output Contract
The script outputs:
- Success: Markdown-formatted text with tables (stdout)
- Error: Error message to stderr
Workflow
Image：
- Input validation (file path or URL)
- Convert local files to base64 data URLs
- Call SophNet OCR API (timeout: 60s)
- Parse and return Markdown output
PDF：
- Detect PDF (by path/URL extension)
- Create temp directory；若为 URL 则先下载 PDF 到 temp
- 使用 PyMuPDF 按页渲染为 PNG（150 DPI，低内存），逐页：OCR → 追加结果 → 删除该页临时图
- 合并各页文本（带「第 N 页」分隔），删除 temp 目录
- 输出合并后的 Markdown
Agent Usage
When extracting text/tables from images or PDF for users:
- Run the OCR script:
uv run {baseDir}/scripts/ocr.py <image-or-pdf-path> - Capture the stdout output
- Present the extracted text/tables to the user
- If the file is a Moltbot-uploaded image, check
media/inbound/images/for the path - PDF 会逐页识别并合并输出，临时图片会在完成后自动删除
Common Errors
Unsupported file type: ...→ Ensure the file is a valid image format (PDF 单独支持，不经过此检查)文件不存在/ 下载 PDF 失败 → 检查路径或 URL 是否可访问PDF 处理错误→ 确认已安装 pymupdf、PDF 未损坏
API Details
Endpoint: https://www.sophnet.com/api/open-apis/projects/easyllms/image-ocr
Model: PaddleOCR-VL-0.9B
Request timeout: 60 seconds
PDF 依赖： 需安装 pymupdf（pyproject.toml 已声明）；PDF 按 150 DPI 转图以兼顾清晰度与低内存。
Supported Input Formats
- PDF：本地
.pdf或 URL 指向的 PDF；多页时按页转图（150 DPI）后识别，结果合并，临时图片自动删除 - Image：JPEG/JPG、PNG、GIF、WebP、BMP 及其他
image/*MIME 类型
Real Example
Image:
uv run {baseDir}/scripts/ocr.py /path/to/document_with_tables.jpg
PDF（多页会带页码分隔）：
uv run {baseDir}/scripts/ocr.py /path/to/report.pdf
Output (Markdown，PDF 多页示例):
--- 第 1 页 ---
| Name | Age | Occupation |
|------|-----|------------|
| John | 30 | Engineer |
--- 第 2 页 ---
This document contains important information about the team structure...
Request timeout: Check your network connection. The script uses a 60-second timeout.
Empty output: Verify the image contains readable text. Some images may not have extractable content.
Base64 conversion issues: Ensure local file paths are correct and the file exists.