Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(parse): implement OCR text extraction for image parser (#942)

Matt Van Horn485e6df9d03b
diff --git a/openviking/parse/parsers/media/image.py b/openviking/parse/parsers/media/image.py
index 277f23316..b35e7ed66 100644
--- a/openviking/parse/parsers/media/image.py
+++ b/openviking/parse/parsers/media/image.py
@@ -10,6 +10,8 @@ They serve as a design reference for future media parsing capabilities.
For current document parsing (PDF, Markdown, HTML, Text), see other parser modules.
"""
+import asyncio
+import io
from pathlib import Path
from typing import List, Optional, Union
@@ -191,19 +193,31 @@ class ImageParser(BaseParser):
async def _ocr_extract(self, image_bytes: bytes, lang: str) -> Optional[str]:
"""
- Extract text from image using OCR.
+ Extract text from image using OCR via Tesseract.
Args:
image_bytes: Image binary data
- lang: OCR language code
+ lang: OCR language code (e.g., "eng", "chi_sim")
Returns:
- Extracted text in markdown format, or None if no text found
-
- TODO: Integrate with OCR API (Tesseract, PaddleOCR, etc.)
+ Extracted text as a string, or None if no text found
"""
- # Not implemented - return None
- return None
+ try:
+ import pytesseract
+ except ImportError:
+ logger.warning("pytesseract not installed. Install with: pip install openviking[ocr]")
+ return None
+
+ def _sync_ocr() -> Optional[str]:
+ img = Image.open(io.BytesIO(image_bytes))
+ text = pytesseract.image_to_string(img, lang=lang).strip()
+ return text if text else None
+
+ try:
+ return await asyncio.get_event_loop().run_in_executor(None, _sync_ocr)
+ except Exception as e:
+ logger.error(f"[ImageParser._ocr_extract] OCR extraction failed: {e}", exc_info=True)
+ return None
async def _generate_semantic_info(
self, node: ResourceNode, description: str, viking_fs, has_ocr: bool, root_dir_uri: str
diff --git a/pyproject.toml b/pyproject.toml
index b5e9ffca0..e8d58a7fb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -109,6 +109,9 @@ gemini-async = [
"google-genai>=1.0.0",
"anyio>=4.0.0",
]
+ocr = [
+ "pytesseract>=0.3.10",
+]
build = [
"setuptools>=61.0",
"setuptools-scm>=8.0",
diff --git a/tests/parse/test_image_ocr.py b/tests/parse/test_image_ocr.py
new file mode 100644
index 000000000..5883ec0c8
--- /dev/null
+++ b/tests/parse/test_image_ocr.py
@@ -0,0 +1,99 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for OCR text extraction in ImageParser."""
+
+import io
+from unittest.mock import MagicMock, patch
+
+import pytest
+from PIL import Image
+
+from openviking.parse.parsers.media.image import ImageParser
+from openviking_cli.utils.config.parser_config import ImageConfig
+
+
+def _create_test_image(width: int = 100, height: int = 50) -> bytes:
+ """Create a simple test image and return as bytes."""
+ img = Image.new("RGB", (width, height), color="white")
+ buf = io.BytesIO()
+ img.save(buf, format="PNG")
+ return buf.getvalue()
+
+
+async def test_ocr_extract_returns_text():
+ """OCR extraction returns text when pytesseract finds text in the image."""
+ parser = ImageParser(config=ImageConfig(enable_ocr=True))
+ image_bytes = _create_test_image()
+
+ with patch.dict("sys.modules", {"pytesseract": MagicMock()}):
+ import sys
+
+ mock_pytesseract = sys.modules["pytesseract"]
+ mock_pytesseract.image_to_string.return_value = "Hello World"
+
+ result = await parser._ocr_extract(image_bytes, lang="eng")
+ assert result == "Hello World"
+ mock_pytesseract.image_to_string.assert_called_once()
+
+
+async def test_ocr_extract_returns_none_for_empty_text():
+ """OCR extraction returns None when no text is found in the image."""
+ parser = ImageParser(config=ImageConfig(enable_ocr=True))
+ image_bytes = _create_test_image()
+
+ with patch.dict("sys.modules", {"pytesseract": MagicMock()}):
+ import sys
+
+ mock_pytesseract = sys.modules["pytesseract"]
+ mock_pytesseract.image_to_string.return_value = " "
+
+ result = await parser._ocr_extract(image_bytes, lang="eng")
+ assert result is None
+
+
+async def test_ocr_extract_returns_none_when_pytesseract_not_installed():
+ """OCR extraction returns None gracefully when pytesseract is not installed."""
+ parser = ImageParser(config=ImageConfig(enable_ocr=True))
+ image_bytes = _create_test_image()
+
+ # Ensure pytesseract is not importable
+ with patch.dict("sys.modules", {"pytesseract": None}):
+ result = await parser._ocr_extract(image_bytes, lang="eng")
+ assert result is None
+
+
+async def test_ocr_extract_handles_exception():
+ """OCR extraction returns None and logs error when pytesseract raises."""
+ parser = ImageParser(config=ImageConfig(enable_ocr=True))
+ image_bytes = _create_test_image()
+
+ with patch.dict("sys.modules", {"pytesseract": MagicMock()}):
+ import sys
+
+ mock_pytesseract = sys.modules["pytesseract"]
+ mock_pytesseract.image_to_string.side_effect = RuntimeError("Tesseract not found")
+
+ result = await parser._ocr_extract(image_bytes, lang="eng")
+ assert result is None
+
+
+async def test_ocr_extract_passes_language_parameter():
+ """OCR extraction passes the lang parameter to pytesseract."""
+ parser = ImageParser(config=ImageConfig(enable_ocr=True, ocr_lang="chi_sim"))
+ image_bytes = _create_test_image()
+
+ with patch.dict("sys.modules", {"pytesseract": MagicMock()}):
+ import sys
+
+ mock_pytesseract = sys.modules["pytesseract"]
+ mock_pytesseract.image_to_string.return_value = "你好世界"
+
+ result = await parser._ocr_extract(image_bytes, lang="chi_sim")
+ assert result == "你好世界"
+ call_args = mock_pytesseract.image_to_string.call_args
+ assert call_args[1]["lang"] == "chi_sim"