Skip to content

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

feat: save images from pdf and doc to vikingfs (#2429)

Haoyu Zhangbbed0c422a2e
diff --git a/openviking/parse/image_rewrite.py b/openviking/parse/image_rewrite.py
new file mode 100644
index 000000000..018fc974b
--- /dev/null
+++ b/openviking/parse/image_rewrite.py
@@ -0,0 +1,296 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Post-commit image URI rewriting for OpenViking.
+
+Scans markdown files in VikingFS after source commit and rewrites local
+image references to viking:// URIs based on images stored in the ./images/
+directory.
+"""
+
+import json
+import re
+from pathlib import PurePath
+from typing import TYPE_CHECKING, Dict, Optional, Set
+
+from openviking.server.identity import RequestContext
+from openviking.storage.viking_fs import get_viking_fs
+from openviking_cli.utils import get_logger
+
+if TYPE_CHECKING:
+ from openviking.storage.transaction.lock_handle import LockHandle
+
+logger = get_logger(__name__)
+
+_IMAGE_PATTERN = re.compile(r"!\[([^\]]*)\]\(([^)]+)\)")
+_REMOTE_PREFIXES = ("http://", "https://", "viking://", "data:", "ftp://")
+_FENCE_PATTERN = re.compile(r"^(\s{0,3})(`{3,}|~{3,})")
+_LIST_ITEM_PATTERN = re.compile(r"^(\s{0,3})([-*+]|\d{1,9}[.)])(\s+)")
+
+
+def _is_remote_uri(path: str) -> bool:
+ return any(path.startswith(p) for p in _REMOTE_PREFIXES)
+
+
+def _inline_code_ranges(line: str):
+ """Yield (start, end) offsets of inline code spans within a single line.
+
+ A code span is a run of N backticks closed by another run of exactly N
+ backticks. Unterminated runs are not treated as code.
+ """
+ i = 0
+ n = len(line)
+ while i < n:
+ if line[i] != "`":
+ i += 1
+ continue
+ j = i
+ while j < n and line[j] == "`":
+ j += 1
+ run = j - i
+ k = j
+ closed = False
+ while k < n:
+ if line[k] != "`":
+ k += 1
+ continue
+ m = k
+ while m < n and line[m] == "`":
+ m += 1
+ if m - k == run:
+ yield (i, m)
+ i = m
+ closed = True
+ break
+ k = m
+ if not closed:
+ i = j
+
+
+def _protected_ranges(content: str):
+ """Compute character ranges that must not be rewritten.
+
+ Covers fenced code blocks, indented code blocks and inline code spans so
+ that Markdown image examples inside code are left untouched.
+ """
+ ranges = []
+ offset = 0
+ in_fence = False
+ fence_char = ""
+ fence_len = 0
+ in_indent_code = False
+ in_list = False
+ prev_blank = True # start of document behaves like "after a blank line"
+
+ for line in content.splitlines(keepends=True):
+ start = offset
+ end = offset + len(line)
+ offset = end
+
+ line_content = line.rstrip("\n").rstrip("\r")
+ stripped = line_content.strip()
+ is_blank = stripped == ""
+
+ if in_fence:
+ ranges.append((start, end))
+ m = _FENCE_PATTERN.match(line_content)
+ if m and m.group(2)[0] == fence_char and len(m.group(2)) >= fence_len and stripped == m.group(2):
+ in_fence = False
+ prev_blank = is_blank
+ continue
+
+ m = _FENCE_PATTERN.match(line_content)
+ if m:
+ in_fence = True
+ in_indent_code = False
+ fence_char = m.group(2)[0]
+ fence_len = len(m.group(2))
+ ranges.append((start, end))
+ prev_blank = is_blank
+ continue
+
+ indent_width = 0
+ for ch in line_content:
+ if ch == " ":
+ indent_width += 1
+ elif ch == "\t":
+ indent_width += 4
+ else:
+ break
+
+ # Track list scope: a list item opens a list; it stays open across
+ # blank lines and indented continuation, and closes when a non-blank,
+ # non-list line returns to the left margin.
+ if _LIST_ITEM_PATTERN.match(line_content):
+ in_list = True
+ elif in_list and not is_blank and indent_width == 0:
+ in_list = False
+
+ if in_indent_code:
+ if is_blank or indent_width >= 4:
+ ranges.append((start, end))
+ prev_blank = is_blank
+ continue
+ in_indent_code = False
+ elif not in_list and not is_blank and indent_width >= 4 and prev_blank:
+ in_indent_code = True
+ ranges.append((start, end))
+ prev_blank = is_blank
+ continue
+
+ for s, e in _inline_code_ranges(line_content):
+ ranges.append((start + s, start + e))
+
+ prev_blank = is_blank
+
+ return ranges
+
+
+async def rewrite_image_uris(
+ root_uri: str,
+ ctx: Optional[RequestContext] = None,
+ lock_handle: Optional["LockHandle"] = None,
+) -> Dict[str, int]:
+ """Rewrite local image references in markdown files to viking:// URIs.
+
+ After ``persist_temp_tree`` copies content to the final VikingFS location,
+ this function scans all ``.md`` files under *root_uri* for image references
+ pointing to local paths. For each one, it looks for a corresponding file
+ in ``{root_uri}/.images/`` and replaces the path with the full viking:// URI.
+
+ Args:
+ root_uri: The final VikingFS root URI (e.g. ``viking://resources/doc``)
+ ctx: Optional request context for permissions
+ lock_handle: Optional lock handle held by the caller. When the caller
+ already owns a TREE lock over *root_uri*, forwarding it lets the
+ cleanup ``rm`` reuse that lock instead of conflicting with it.
+
+ Returns:
+ Dict with ``files_processed`` and ``references_rewritten`` counts.
+ """
+ viking_fs = get_viking_fs()
+
+ root_prefix = root_uri.rstrip("/")
+
+ # Find all .md files recursively
+ glob_result = await viking_fs.glob("*.md", uri=root_uri, ctx=ctx)
+ md_uris = glob_result.get("matches", [])
+
+ if not md_uris:
+ return {"files_processed": 0, "references_rewritten": 0}
+
+ # Load mapping file from _ingest_local_images:
+ # {rel_md_path -> {original_path_str -> image_filename}}
+ # The mapping file lives at the root directory and images are stored next to
+ # their referencing markdown file.
+ file_mappings: Dict[str, Dict[str, str]] = {}
+ try:
+ mapping_content = await viking_fs.read_file(f"{root_prefix}/.image_mappings.json", ctx=ctx)
+ file_mappings = json.loads(mapping_content)
+ except Exception:
+ pass
+
+ files_processed = 0
+ references_rewritten = 0
+
+ for md_uri in md_uris:
+ # Resolve this markdown file's mapping and its containing directory
+ rel_md_path = md_uri[len(root_prefix) + 1 :] if md_uri.startswith(root_prefix) else md_uri
+ path_to_image_name = file_mappings.get(rel_md_path, {})
+ if not path_to_image_name:
+ continue
+
+ md_dir = md_uri.rsplit("/", 1)[0]
+
+ # Build the set of available images that sit beside this markdown file
+ available_images: Set[str] = set()
+ try:
+ entries = await viking_fs.ls(md_dir, ctx=ctx)
+ available_images = {
+ e["name"] for e in entries
+ if not e.get("isDir") and not e["name"].startswith(".")
+ }
+ except Exception:
+ logger.debug(f"[image_rewrite] Failed to list directory {md_dir}")
+
+ try:
+ content = await viking_fs.read_file(md_uri, ctx=ctx)
+ except Exception:
+ logger.warning(f"[image_rewrite] Failed to read {md_uri}, skipping")
+ continue
+
+ new_content, rewrite_count = _rewrite_content(content, md_dir, available_images, path_to_image_name)
+
+ if rewrite_count > 0:
+ try:
+ await viking_fs.write_file(md_uri, new_content, ctx=ctx)
+ files_processed += 1
+ references_rewritten += rewrite_count
+ logger.debug(
+ f"[image_rewrite] Rewrote {rewrite_count} image ref(s) in {md_uri}"
+ )
+ except Exception:
+ logger.warning(f"[image_rewrite] Failed to write {md_uri}")
+
+ # Clean up mapping file — no longer needed after rewrite
+ if file_mappings:
+ try:
+ await viking_fs.rm(f"{root_prefix}/.image_mappings.json", ctx=ctx, lock_handle=lock_handle)
+ except Exception as e:
+ logger.warning(f"[image_rewrite] Failed to delete .image_mappings.json: {e}")
+
+ logger.info(
+ f"[image_rewrite] Processed {len(md_uris)} .md files, "
+ f"rewrote {references_rewritten} image reference(s) in {files_processed} file(s)"
+ )
+
+ return {"files_processed": files_processed, "references_rewritten": references_rewritten}
+
+
+def _rewrite_content(
+ content: str,
+ image_dir: str,
+ available_images: Set[str],
+ path_to_image_name: Optional[Dict[str, str]] = None,
+) -> tuple[str, int]:
+ """Rewrite local image references in markdown content.
+
+ Returns (new_content, rewrite_count).
+ """
+ rewrite_count = 0
+ mappings = path_to_image_name or {}
+
+ protected = _protected_ranges(content)
+
+ def _in_protected(pos: int) -> bool:
+ for s, e in protected:
+ if s <= pos < e:
+ return True
+ return False
+
+ def replacer(match: re.Match) -> str:
+ nonlocal rewrite_count
+ alt_text = match.group(1)
+ path = match.group(2)
+
+ # Skip image references that live inside code blocks / inline code.
+ if _in_protected(match.start()):
+ return match.group(0)
+
+ if _is_remote_uri(path):
+ return match.group(0)
+
+ # Prefer exact path mapping from .image_mappings.json
+ if path in mappings:
+ image_name = mappings[path]
+ if image_name in available_images:
+ rewrite_count += 1
+ return f"![{alt_text}]({image_dir}/{image_name})"
+
+ logger.warning(
+ f"[image_rewrite] Image not found in VikingFS: path = {path}, "
+ f"image_dir = {image_dir}, leaving reference unchanged"
+ )
+ return match.group(0)
+
+ new_content = _IMAGE_PATTERN.sub(replacer, content)
+ return new_content, rewrite_count
diff --git a/openviking/parse/parsers/html.py b/openviking/parse/parsers/html.py
index fd249db17..4988b5b3f 100644
--- a/openviking/parse/parsers/html.py
+++ b/openviking/parse/parsers/html.py
@@ -156,7 +156,9 @@ class HTMLParser(BaseParser):
try:
content = self._read_file(path)
- result = await self.parse_content(content, source_path=str(path), **kwargs)
+ result = await self.parse_content(
+ content, source_path=str(path), base_dir=path.parent, **kwargs
+ )
# Add timing info
result.parse_time = time.time() - start_time
diff --git a/openviking/parse/parsers/markdown.py b/openviking/parse/parsers/markdown.py
index f0d1539c4..2d84e432d 100644
--- a/openviking/parse/parsers/markdown.py
+++ b/openviking/parse/parsers/markdown.py
@@ -17,7 +17,9 @@ The parser handles scenarios:
5. Oversized sections without subsections → split by paragraphs
"""
+import asyncio
import hashlib
+import io
import os
import re
import time
@@ -132,6 +134,14 @@ class MarkdownParser(BaseParser):
DEFAULT_MIN_SECTION_TOKENS = 512 # Minimum tokens to create a separate section
MAX_MERGED_FILENAME_LENGTH = 32 # Maximum length for merged section filenames
+ # Image validation constants
+ IMAGE_MIN_SIDE = 14 # Minimum width/height in pixels (exclusive)
+ IMAGE_MIN_PIXELS = 196 # Minimum width * height
+ IMAGE_MAX_PIXELS = 36000000 # Maximum width * height
+ IMAGE_MIN_ASPECT_RATIO = 1 / 150 # Minimum width/height ratio
+ IMAGE_MAX_ASPECT_RATIO = 150 # Maximum width/height ratio
+ IMAGE_MAX_FILE_BYTES = 10 * 1024 * 1024 # Local file path limit: 10 MB
+
def __init__(
self,
extract_frontmatter: bool = True,
@@ -204,6 +214,7 @@ class MarkdownParser(BaseParser):
source_path: Optional[str] = None,
instruction: str = "",
base_dir: Optional[Path] = None,
+ allowed_media_dirs: Optional[List[Path]] = None,
**kwargs,
) -> ParseResult:
"""
@@ -219,6 +230,10 @@ class MarkdownParser(BaseParser):
source_path: Optional source file path
instruction: Processing instruction (unused in v5.0)
base_dir: Base directory for relative paths
+ allowed_media_dirs: Additional directories from which derived media
+ (e.g. images extracted by the PDF/DOC parser) may be read. The
+ caller is responsible for ensuring these belong to the current
+ input resource's lifecycle.
**kwargs: Additional runtime options, incl. resource_name/source_name and
enable_link_rewrite/link_rewrite_root (the latter set by DirectoryParser)
@@ -302,6 +317,10 @@ class MarkdownParser(BaseParser):
doc_name=self._sanitize_for_path(doc_title),
)
+ # Ingest local image files, placing each image next to the
+ # markdown file that references it.
+ await self._ingest_local_images(root_dir, base_dir, allowed_media_dirs)
+
parse_time = time.time() - start_time
logger.info(f"[MarkdownParser] Parse completed in {parse_time:.2f}s")
@@ -470,6 +489,287 @@ class MarkdownParser(BaseParser):
return parts if parts else [content]
+ async def _ingest_local_images(
+ self,
+ root_dir: str,
+ base_dir: Optional[Path] = None,
+ allowed_media_dirs: Optional[List[Path]] = None,
+ ) -> None:
+ """
+ Scan every processed markdown file under ``root_dir`` and copy the local
+ images they reference into VikingFS, next to the markdown file itself.
+
+ Images are processed file by file: for each markdown file, the local
+ image references it contains are resolved and copied into the same
+ directory as that markdown file. A single ``.image_mappings.json`` file,
+ keyed by the markdown file's path relative to ``root_dir``, is written at
+ ``root_dir`` for ``rewrite_image_uris`` to consume.
+
+ Args:
+ root_dir: Root directory URI in VikingFS containing the markdown files
+ base_dir: Base directory for resolving relative paths
+ allowed_media_dirs: Additional directories from which derived media
+ may be read (passed through to ``_resolve_image_path``)
+ """
+ viking_fs = self._get_viking_fs()
+
+ # Find all processed markdown files under the root directory
+ glob_result = await viking_fs.glob("*.md", uri=root_dir)
+ md_uris = glob_result.get("matches", [])
+ if not md_uris:
+ return
+
+ root_prefix = root_dir.rstrip("/")
+
+ # mapping: rel_md_path -> {original_path_str -> unique_filename}
+ mappings: Dict[str, Dict[str, str]] = {}
+
+ for md_uri in md_uris:
+ try:
+ content = await viking_fs.read_file(md_uri)
+ except Exception:
+ logger.warning(f"[MarkdownParser] Failed to read markdown file: {md_uri}")
+ continue
+
+ # Collect all image references in this markdown file
+ images = list(self._image_pattern.finditer(content))
+ if not images:
+ continue
+
+ # Resolve local image paths, skipping remote URIs and duplicates
+ local_images = []
+ origin_images_links = []
+ seen_paths = set()
+
+ for match in images:
+ path_str = match.group(2)
+
+ # Skip remote URIs
+ if self._is_remote_uri(path_str):
+ continue
+
+ resolved_path = self._resolve_image_path(path_str, base_dir, allowed_media_dirs)
+ if resolved_path is None:
+ logger.warning(f"[MarkdownParser] Image file not found: {path_str}")
+ continue
+
+ # Skip duplicates within the same markdown file
+ if resolved_path in seen_paths:
+ continue
+ seen_paths.add(resolved_path)
+ origin_images_links.append(path_str)
+ local_images.append(resolved_path)
+
+ if not local_images:
+ continue
+
+ # Target directory is the directory containing the markdown file
+ md_dir = md_uri.rsplit("/", 1)[0]
+
+ # Copy each local image next to the markdown file, deduplicating names
+ used_names: set[str] = set()
+ file_mappings: Dict[str, str] = {} # original_path_str -> unique_filename
+ for origin_link, resolved_path in zip(origin_images_links, local_images):
+ try:
+ if not await asyncio.to_thread(resolved_path.exists):
+ logger.warning(f"[MarkdownParser] Image file not found: {resolved_path}")
+ continue
+
+ # Read image bytes
+ image_bytes = await asyncio.to_thread(resolved_path.read_bytes)
+
+ # Validate pixel size and file size; skip non-compliant images
+ if not await asyncio.to_thread(self._is_valid_image, image_bytes, resolved_path):
+ continue
+
+ # Get filename and deduplicate
+ filename = resolved_path.name
+ unique_filename = self._deduplicate_filename(filename, used_names)
+ used_names.add(unique_filename)
+
+ # Write next to the markdown file
+ viking_path = f"{md_dir}/{unique_filename}"
+ await viking_fs.write_file_bytes(viking_path, image_bytes)
+ logger.debug(f"[MarkdownParser] Copied image to VikingFS: {viking_path}")
+
+ # Record mapping for post-commit rewrite
+ file_mappings[origin_link] = unique_filename
+
+ except Exception as e:
+ logger.warning(f"[MarkdownParser] Failed to ingest image {resolved_path}: {e}")
+
+ if file_mappings:
+ rel_md_path = md_uri[len(root_prefix) + 1 :] if md_uri.startswith(root_prefix) else md_uri
+ mappings[rel_md_path] = file_mappings
+
+ # Write a single mapping file at the root directory for rewrite_image_uris
+ if mappings:
+ import json
+ await viking_fs.write_file(
+ f"{root_prefix}/.image_mappings.json",
+ json.dumps(mappings, ensure_ascii=False),
+ )
+
+ def _resolve_image_path(
+ self,
+ path_str: str,
+ base_dir: Optional[Path],
+ allowed_media_dirs: Optional[List[Path]] = None,
+ ) -> Optional[Path]:
+ """
+ Resolve a local image reference to an existing filesystem path.
+
+ Args:
+ path_str: Raw image path from the markdown reference
+ base_dir: Base directory for resolving relative paths
+ allowed_media_dirs: Additional directories that belong to the current
+ input resource's lifecycle (e.g. media extracted by the PDF/DOC
+ parser).
+
+ Returns:
+ Resolved absolute Path if the file exists and stays within an
+ allowed root, otherwise None
+ """
+ try:
+ path = Path(path_str)
+
+ # Reject absolute paths: they can point anywhere on the host
+ if path.is_absolute():
+ logger.warning(
+ f"[MarkdownParser] Rejected absolute image path: {path_str}"
+ )
+ return None
+
+ # Build the list of allowed roots to confine resolution to.
+ allowed_roots: list[Path] = []
+ if base_dir:
+ allowed_roots.append(base_dir)
+ if allowed_media_dirs:
+ allowed_roots.extend(allowed_media_dirs)
+
+ if not allowed_roots:
+ return None
+
+ for root in allowed_roots:
+ candidate = (root / path).resolve()
+
+ # Verify the resolved candidate stays under the allowed root,
+ # rejecting traversal attempts such as ../../private.png.
+ try:
+ candidate.relative_to(root.resolve())
+ except ValueError:
+ logger.warning(
+ f"[MarkdownParser] Rejected image path outside base dir: {path_str}"
+ )
+ continue
+
+ if candidate.exists():
+ return candidate
+
+ return None
+ except Exception:
+ logger.warning(f"[MarkdownParser] Cannot resolve image path: {path_str}")
+ return None
+
+ def _is_valid_image(self, image_bytes: bytes, source_path: Path) -> bool:
+ """
+ Validate an image's pixel dimensions and file size.
+
+ Requirements:
+ - Width > 14px and height > 14px
+ - Width * height within [196, 36000000]
+ - Aspect ratio (width/height) within [1/150, 150]
+ - File size (local path) <= 10 MB
+
+ Args:
+ image_bytes: Raw image bytes
+ source_path: Original image path (for logging)
+
+ Returns:
+ True if the image satisfies all requirements, otherwise False
+ """
+ # File size check (local file path limit: 10 MB)
+ if len(image_bytes) > self.IMAGE_MAX_FILE_BYTES:
+ logger.warning(
+ f"[MarkdownParser] Image exceeds 10MB, skipping: {source_path}"
+ )
+ return False
+
+ # Pixel size check
+ try:
+ from PIL import Image
+
+ with Image.open(io.BytesIO(image_bytes)) as img:
+ width, height = img.size
+ except Exception as e:
+ logger.warning(
+ f"[MarkdownParser] Cannot read image dimensions, skipping {source_path}: {e}"
+ )
+ return False
+
+ if width <= self.IMAGE_MIN_SIDE or height <= self.IMAGE_MIN_SIDE:
+ logger.warning(
+ f"[MarkdownParser] Image side too small ({width}x{height}), skipping: {source_path}"
+ )
+ return False
+
+ pixels = width * height
+ if pixels < self.IMAGE_MIN_PIXELS or pixels > self.IMAGE_MAX_PIXELS:
+ logger.warning(
+ f"[MarkdownParser] Image pixel count out of range ({pixels}), skipping: {source_path}"
+ )
+ return False
+
+ aspect_ratio = width / height
+ if aspect_ratio < self.IMAGE_MIN_ASPECT_RATIO or aspect_ratio > self.IMAGE_MAX_ASPECT_RATIO:
+ logger.warning(
+ f"[MarkdownParser] Image aspect ratio out of range ({aspect_ratio:.4f}), "
+ f"skipping: {source_path}"
+ )
+ return False
+
+ return True
+
+ @staticmethod
+ def _is_remote_uri(path: str) -> bool:
+ """
+ Check if a path is a remote URI.
+
+ Args:
+ path: Path to check
+
+ Returns:
+ True if path starts with http://, https://, viking://, data:, or ftp://
+ """
+ remote_prefixes = ("http://", "https://", "viking://", "data:", "ftp://")
+ return path.startswith(remote_prefixes)
+
+ @staticmethod
+ def _deduplicate_filename(filename: str, used_names: set[str]) -> str:
+ """
+ Generate a unique filename by appending _1, _2, etc. when collision occurs.
+
+ Args:
+ filename: Original filename
+ used_names: Set of already used filenames
+
+ Returns:
+ Unique filename
+ """
+ if filename not in used_names:
+ return filename
+
+ path_obj = Path(filename)
+ stem = path_obj.stem
+ suffix = path_obj.suffix
+ counter = 1
+
+ while True:
+ new_filename = f"{stem}_{counter}{suffix}"
+ if new_filename not in used_names:
+ return new_filename
+ counter += 1
+
def _sanitize_for_path(self, text: str, max_length: int = 50) -> str:
safe = re.sub(
r"[^\w\u0080-\u02af\u0400-\u052f\u0600-\u077f\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af\u3400-\u4dbf\U00020000-\U0002a6df\s.-]",
diff --git a/openviking/parse/parsers/pdf.py b/openviking/parse/parsers/pdf.py
index b5b2def6d..cebea827c 100644
--- a/openviking/parse/parsers/pdf.py
+++ b/openviking/parse/parsers/pdf.py
@@ -13,6 +13,7 @@ to the MarkdownParser after conversion.
"""
import asyncio
+import io
import re
import time
from collections import Counter, defaultdict
@@ -128,11 +129,16 @@ class PDFParser(BaseParser):
# Step 2: Parse Markdown using MarkdownParser, pass through resource name
md_parser = self._get_markdown_parser()
+ from openviking_cli.utils.storage import get_storage
+
+ storage = get_storage()
result = await md_parser.parse_content(
markdown_content,
source_path=str(pdf_path),
resource_name=resource_name,
source_name=resource_name,
+ base_dir=pdf_path.parent,
+ allowed_media_dirs=[storage.media_dir],
)
# Step 3: Update metadata for PDF origin
@@ -336,8 +342,8 @@ class PDFParser(BaseParser):
resource_name, image_obj, filename=filename
)
- # Generate relative path for markdown
- rel_path = image_path.relative_to(Path.cwd())
+ # Generate path relative to the media root.
+ rel_path = image_path.relative_to(storage.media_dir)
parts.append(
f"<!-- Page {page_num} Image {img_idx + 1} -->\n"
f"![Page {page_num} Image {img_idx + 1}]({rel_path})"
@@ -600,35 +606,38 @@ class PDFParser(BaseParser):
def _extract_image_from_page(self, page, img_info: dict) -> Optional[bytes]:
"""
- Extract image data from PDF page.
+ Extract a PDF image as valid PNG bytes.
+
+ Renders the image's bounding box on the page to a raster PNG via
+ pdfplumber's ``crop().to_image()`` instead of returning the raw decoded
+ XObject stream (which is not a valid image file and cannot be opened).
Args:
page: pdfplumber page object
img_info: Image metadata from page.images
Returns:
- Image bytes or None if extraction fails
+ PNG-encoded image bytes or None if extraction fails
"""
try:
- if hasattr(page, "page_obj") and hasattr(page.page_obj, "resources"):
- resources = page.page_obj.resources
- if resources and "XObject" in resources:
- xobjects = resources["XObject"]
- target_name = img_info.get("name") if isinstance(img_info, dict) else None
- normalized_target = str(target_name).lstrip("/") if target_name else None
- for obj_name, obj in xobjects.items():
- if normalized_target and str(obj_name).lstrip("/") != normalized_target:
- continue
- if hasattr(obj, "resolve"):
- resolved = obj.resolve()
- if resolved.get("Subtype") and resolved["Subtype"].name == "Image":
- if hasattr(resolved, "get_data"):
- return resolved.get_data()
- data = resolved.get("stream")
- if data and hasattr(data, "get_data"):
- return data.get_data()
+ # pdfplumber coordinates: ``top`` is measured from the top of the page.
+ bbox = (
+ max(0, img_info["x0"]),
+ max(0, img_info["top"]),
+ min(page.width, img_info["x1"]),
+ min(page.height, img_info["bottom"]),
+ )
- return None
+ # Skip degenerate / zero-area boxes that cannot be cropped.
+ if bbox[2] <= bbox[0] or bbox[3] <= bbox[1]:
+ return None
+
+ cropped = page.crop(bbox)
+ page_image = cropped.to_image(resolution=self.config.image_resolution)
+
+ buffer = io.BytesIO()
+ page_image.save(buffer, format="PNG")
+ return buffer.getvalue()
except Exception as e:
logger.debug(f"Image extraction error: {e}")
diff --git a/openviking/parse/parsers/word.py b/openviking/parse/parsers/word.py
index 044e9277c..0dd4752c1 100644
--- a/openviking/parse/parsers/word.py
+++ b/openviking/parse/parsers/word.py
@@ -47,9 +47,21 @@ class WordParser(BaseParser):
if path.exists():
import docx
- markdown_content = await asyncio.to_thread(self._convert_to_markdown, path, docx)
+ from openviking_cli.utils.storage import get_storage
+
+ storage = get_storage()
+ resource_name = kwargs.get("resource_name") or kwargs.get("source_name") or path.stem
+
+ markdown_content = await asyncio.to_thread(
+ self._convert_to_markdown, path, docx, resource_name, storage
+ )
result = await self._md_parser.parse_content(
- markdown_content, source_path=str(path), instruction=instruction, **kwargs
+ markdown_content,
+ source_path=str(path),
+ instruction=instruction,
+ base_dir=path.parent,
+ allowed_media_dirs=[storage.media_dir],
+ **kwargs,
)
else:
result = await self._md_parser.parse_content(
@@ -68,11 +80,13 @@ class WordParser(BaseParser):
result.parser_name = "WordParser"
return result
- def _convert_to_markdown(self, path: Path, docx) -> str:
+ def _convert_to_markdown(self, path: Path, docx, resource_name=None, storage=None) -> str:
"""Convert Word document to Markdown string.
Iterates the document body in order so that tables appear in their
- original position rather than being appended at the end.
+ original position rather than being appended at the end. Embedded
+ images are extracted to local storage and referenced inline so the
+ MarkdownParser can ingest them into VikingFS.
"""
doc = docx.Document(path)
markdown_parts = []
@@ -80,6 +94,9 @@ class WordParser(BaseParser):
# Map XML table elements to python-docx Table objects for O(1) lookup
table_by_element = {table._tbl: table for table in doc.tables}
+ # Track extracted images to deduplicate and number sequentially
+ image_counter = [0]
+
# Walk the document body in order to preserve table positions
from docx.oxml.ns import qn
@@ -89,6 +106,15 @@ class WordParser(BaseParser):
from docx.text.paragraph import Paragraph
paragraph = Paragraph(child, doc)
+
+ # Extract any embedded images in this paragraph first so they
+ # keep their original document position.
+ image_md = self._convert_paragraph_images(
+ paragraph, doc, qn, resource_name, storage, image_counter
+ )
+ if image_md:
+ markdown_parts.append(image_md)
+
if not paragraph.text.strip():
continue
@@ -108,6 +134,48 @@ class WordParser(BaseParser):
return "\n\n".join(markdown_parts)
+ def _convert_paragraph_images(
+ self, paragraph, doc, qn, resource_name, storage, image_counter
+ ) -> str:
+ """Extract embedded images from a paragraph and return markdown references.
+
+ Images in .docx are stored as relationship parts (``word/media/*``)
+ referenced by ``r:embed`` ids inside ``w:drawing`` elements. We pull the
+ binary blob for each and persist it via the shared storage helper so the
+ MarkdownParser's image ingestion can pick it up.
+ """
+ if storage is None:
+ return ""
+
+ parts = []
+ # Each <a:blip r:embed="rId"> inside the paragraph references an image part
+ for blip in paragraph._p.findall(".//" + qn("a:blip")):
+ rid = blip.get(qn("r:embed"))
+ if not rid:
+ continue
+ try:
+ image_part = doc.part.related_parts[rid]
+ image_bytes = image_part.blob
+ except Exception as e:
+ logger.warning(f"[WordParser] Failed to read embedded image {rid}: {e}")
+ continue
+
+ try:
+ extension = Path(image_part.partname).suffix or ".png"
+ image_counter[0] += 1
+ filename = f"image{image_counter[0]}"
+ image_path = storage.save_image(
+ resource_name, image_bytes, filename=filename, extension=extension
+ )
+ # Reference relative to the media root so the MarkdownParser can
+ # resolve it within the resource's media lifecycle (never cwd).
+ rel_path = image_path.relative_to(storage.media_dir)
+ parts.append(f"![{filename}]({rel_path})")
+ except Exception as e:
+ logger.warning(f"[WordParser] Failed to save embedded image {rid}: {e}")
+
+ return "\n\n".join(parts)
+
def _extract_heading_level(self, style_name: str) -> int:
"""Extract heading level from style name."""
try:
diff --git a/openviking/storage/queuefs/semantic_processor.py b/openviking/storage/queuefs/semantic_processor.py
index e04dda453..fa3bf5f28 100644
--- a/openviking/storage/queuefs/semantic_processor.py
+++ b/openviking/storage/queuefs/semantic_processor.py
@@ -19,6 +19,7 @@ from openviking.parse.parsers.constants import (
FILE_TYPE_DOCUMENTATION,
FILE_TYPE_OTHER,
)
+from openviking.parse.image_rewrite import rewrite_image_uris
from openviking.parse.parsers.media.utils import (
generate_audio_summary,
generate_image_summary,
@@ -923,15 +924,66 @@ class SemanticProcessor(DequeueHandlerBase):
await viking_fs.mkdir(parent_uri.uri, exist_ok=True, ctx=ctx)
diff.added_dirs.append(target_uri)
await viking_fs.mv(root_uri, target_uri, ctx=ctx, lock_handle=lock_handle)
+ # The whole temp tree (including the hidden .image_mappings.json
+ # sidecar) was moved into the target; rewrite local image paths now.
+ await self._rewrite_target_image_uris(root_uri, target_uri, ctx=ctx, lock=lock)
return diff
await sync_dir(root_uri, target_uri)
+ # sync_dir skips hidden files, so the .image_mappings.json sidecar is
+ # still at the temp root. Carry it over and rewrite the synced markdown
+ # before the temp tree is deleted below.
+ await self._rewrite_target_image_uris(root_uri, target_uri, ctx=ctx, lock=lock)
try:
await viking_fs.delete_temp(root_uri, ctx=ctx)
except Exception as e:
logger.error(f"[SyncDiff] Failed to delete root directory {root_uri}: {e}")
return diff
+ async def _rewrite_target_image_uris(
+ self,
+ root_uri: str,
+ target_uri: str,
+ ctx: Optional[RequestContext] = None,
+ lock: LockLease = NO_LOCK,
+ ) -> None:
+ """Rewrite local image refs in the target after a temp-to-target sync.
+
+ ``_sync_topdown_recursive`` skips hidden files, so the
+ ``.image_mappings.json`` sidecar written by the parser at the temp root
+ is not copied into the target. Carry it over (when missing) so
+ :func:`rewrite_image_uris` can resolve local image paths against the
+ images that were synced into the final target.
+ """
+ viking_fs = get_viking_fs()
+ root_prefix = root_uri.rstrip("/")
+ target_prefix = target_uri.rstrip("/")
+ mapping_name = ".image_mappings.json"
+
+ if root_prefix != target_prefix:
+ try:
+ await viking_fs.stat(f"{target_prefix}/{mapping_name}", ctx=ctx)
+ target_has_mapping = True
+ except Exception:
+ target_has_mapping = False
+
+ if not target_has_mapping:
+ try:
+ mapping_content = await viking_fs.read_file(
+ f"{root_prefix}/{mapping_name}", ctx=ctx
+ )
+ await viking_fs.write_file(
+ f"{target_prefix}/{mapping_name}", mapping_content, ctx=ctx
+ )
+ except Exception:
+ # No sidecar to carry over (e.g. no local images ingested).
+ pass
+
+ try:
+ await rewrite_image_uris(target_uri, ctx=ctx, lock_handle=lock.handle)
+ except Exception as e:
+ logger.error(f"[SyncDiff] Failed to rewrite image URIs for {target_uri}: {e}")
+
async def _collect_children_abstracts(
self, children_uris: List[str], ctx: Optional[RequestContext] = None
) -> List[Dict[str, str]]:
diff --git a/openviking/utils/resource_processor.py b/openviking/utils/resource_processor.py
index 16c5c9078..4633b47be 100644
--- a/openviking/utils/resource_processor.py
+++ b/openviking/utils/resource_processor.py
@@ -12,6 +12,7 @@ import time
from collections.abc import Callable
from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from openviking.parse.image_rewrite import rewrite_image_uris
from openviking.parse.tree_builder import TreeBuilder
from openviking.server.identity import RequestContext
from openviking.storage import VikingDBManager
@@ -304,6 +305,7 @@ class ResourceProcessor:
)
if not target_preexisting:
await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)
+ await rewrite_image_uris(root_uri, ctx=ctx, lock_handle=resource_lock.handle)
await viking_fs.delete_temp(parse_result.temp_dir_path, ctx=ctx)
temp_uri = root_uri
source_committed = True
@@ -368,6 +370,7 @@ class ResourceProcessor:
if not should_summarize and temp_uri and not source_committed:
viking_fs = get_viking_fs()
await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)
+ await rewrite_image_uris(root_uri, ctx=ctx, lock_handle=resource_lock.handle)
await viking_fs.delete_temp(parse_result.temp_dir_path, ctx=ctx)
await resource_lock.close()
diff --git a/openviking_cli/utils/config/parser_config.py b/openviking_cli/utils/config/parser_config.py
index e4589671e..d48bddafa 100644
--- a/openviking_cli/utils/config/parser_config.py
+++ b/openviking_cli/utils/config/parser_config.py
@@ -162,6 +162,9 @@ class PDFConfig(ParserConfig):
font_heading_min_delta: float = 1.5 # Minimum font size delta from body text (pt)
max_heading_levels: int = 4 # Maximum heading levels for font analysis
+ # Image extraction configuration
+ image_resolution: int = 300 # Rendering DPI for extracted image regions
+
def validate(self) -> None:
"""
Validate configuration.
diff --git a/tests/parse/test_pdf_bookmark_extraction.py b/tests/parse/test_pdf_bookmark_extraction.py
index 5347b57fa..49b18c46a 100644
--- a/tests/parse/test_pdf_bookmark_extraction.py
+++ b/tests/parse/test_pdf_bookmark_extraction.py
@@ -51,6 +51,43 @@ def _make_image_page(xobjects):
return SimpleNamespace(page_obj=SimpleNamespace(resources={"XObject": xobjects}))
+class _FakeRenderedImage:
+ """Minimal rendered image stub that writes deterministic PNG bytes."""
+
+ def __init__(self, data: bytes):
+ self._data = data
+
+ def save(self, buffer, format: str):
+ assert format == "PNG"
+ buffer.write(self._data)
+
+
+class _FakeCroppedPage:
+ """Minimal cropped page stub for image extraction tests."""
+
+ def __init__(self, rendered_image: _FakeRenderedImage):
+ self._rendered_image = rendered_image
+ self.resolution_calls = []
+
+ def to_image(self, resolution: int):
+ self.resolution_calls.append(resolution)
+ return self._rendered_image
+
+
+class _FakeImagePage:
+ """Minimal pdfplumber page stub for _extract_image_from_page tests."""
+
+ def __init__(self, *, width: int = 100, height: int = 200, image_bytes: bytes = b"png-bytes"):
+ self.width = width
+ self.height = height
+ self.crop_calls = []
+ self.cropped_page = _FakeCroppedPage(_FakeRenderedImage(image_bytes))
+
+ def crop(self, bbox):
+ self.crop_calls.append(bbox)
+ return self.cropped_page
+
+
class _FakePage:
"""Minimal pdfplumber page stub for _convert_local tests."""
@@ -350,39 +387,48 @@ class TestExtractImages:
def setup_method(self):
self.parser = PDFParser()
- def test_extract_image_reads_resolved_pdfstream_data(self):
- page = _make_image_page(
- {
- "Im1": _FakePDFObjectRef(_FakePDFStream(b"first-image")),
- }
+ def test_extract_image_renders_cropped_bbox_as_png(self):
+ page = _FakeImagePage(image_bytes=b"rendered-png")
+
+ image_data = self.parser._extract_image_from_page(
+ page,
+ {"x0": 10, "top": 20, "x1": 40, "bottom": 60},
)
- assert self.parser._extract_image_from_page(page, {"name": "Im1"}) == b"first-image"
+ assert image_data == b"rendered-png"
+ assert page.crop_calls == [(10, 20, 40, 60)]
+ assert page.cropped_page.resolution_calls == [self.parser.config.image_resolution]
- def test_extract_image_matches_requested_xobject_name(self):
- page = _make_image_page(
- {
- "Im1": _FakePDFObjectRef(_FakePDFStream(b"first-image")),
- "Im2": _FakePDFObjectRef(_FakePDFStream(b"second-image")),
- }
+ def test_extract_image_clamps_bbox_to_page_bounds(self):
+ page = _FakeImagePage()
+
+ self.parser._extract_image_from_page(
+ page,
+ {"x0": -5, "top": -10, "x1": 150, "bottom": 250},
)
- assert self.parser._extract_image_from_page(page, {"name": "Im2"}) == b"second-image"
+ assert page.crop_calls == [(0, 0, page.width, page.height)]
+
+ def test_extract_image_returns_none_for_zero_area_bbox(self):
+ page = _FakeImagePage()
- def test_extract_image_allows_leading_slash_name_variants(self):
- page = _make_image_page(
- {
- "/Im1": _FakePDFObjectRef(_FakePDFStream(b"slash-image")),
- }
+ assert (
+ self.parser._extract_image_from_page(
+ page,
+ {"x0": 30, "top": 40, "x1": 30, "bottom": 60},
+ )
+ is None
)
+ assert page.crop_calls == []
- assert self.parser._extract_image_from_page(page, {"name": "Im1"}) == b"slash-image"
+ def test_extract_image_returns_none_when_crop_fails(self):
+ page = MagicMock(width=100, height=200)
+ page.crop.side_effect = RuntimeError("crop failed")
- def test_extract_image_returns_none_for_non_image_xobject(self):
- page = _make_image_page(
- {
- "Form1": _FakePDFObjectRef(_FakePDFStream(b"form-data", subtype="Form")),
- }
+ assert (
+ self.parser._extract_image_from_page(
+ page,
+ {"x0": 10, "top": 20, "x1": 40, "bottom": 60},
+ )
+ is None
)
-
- assert self.parser._extract_image_from_page(page, {"name": "Form1"}) is None
diff --git a/web-studio/src/routes/resources/-components/file-preview.tsx b/web-studio/src/routes/resources/-components/file-preview.tsx
index c7343941d..e1ec33dd6 100644
--- a/web-studio/src/routes/resources/-components/file-preview.tsx
+++ b/web-studio/src/routes/resources/-components/file-preview.tsx
@@ -11,6 +11,7 @@ import { Button } from '#/components/ui/button'
import { ScrollArea } from '#/components/ui/scroll-area'
import { client } from '#/gen/ov-client/client.gen'
import { getContentDownload, ovClient } from '#/lib/ov-client'
+import { fileNameFromUri } from '#/lib/viking-uri'
import type { GetContentDownloadData } from '#/gen/ov-client/types.gen'
import type { ContentDownloadQuery } from '@ov-server/api/v1/content'
@@ -274,22 +275,132 @@ function resolveRelativeVikingUri(
return `${resolved}${suffix}`
}
-function resolveMarkdownAssetUrl(assetPath: string, fileUri: string): string {
+type MarkdownAssetTarget =
+ | { kind: 'external'; value: string }
+ | { kind: 'raw'; value: string }
+ | { kind: 'viking'; value: string }
+
+function safeDecodeUri(value: string): string {
+ try {
+ return decodeURIComponent(value)
+ } catch {
+ return value
+ }
+}
+
+function resolveMarkdownAssetTarget(
+ assetPath: string,
+ fileUri: string,
+): MarkdownAssetTarget {
const trimmed = assetPath.trim()
if (!trimmed || trimmed.startsWith('#')) {
- return trimmed
+ return { kind: 'raw', value: trimmed }
}
if (/^(https?:|data:|blob:|mailto:|tel:)/i.test(trimmed)) {
- return trimmed
+ return { kind: 'external', value: trimmed }
+ }
+
+ // react-markdown percent-encodes the URL it passes via `src`/`href`
+ // (e.g. Chinese characters become %E4%BA%92). Decode it back to the literal
+ // form so the API client's query serializer encodes it exactly once and we
+ // avoid a double-encoded URI that the backend rejects with HTTP 400.
+ const decoded = safeDecodeUri(trimmed)
+
+ const vikingUri = decoded.startsWith(vikingPrefix)
+ ? decoded
+ : resolveRelativeVikingUri(fileUri, decoded)
+ return { kind: 'viking', value: vikingUri }
+}
+
+function resolveMarkdownAssetUrl(assetPath: string, fileUri: string): string {
+ const target = resolveMarkdownAssetTarget(assetPath, fileUri)
+ if (target.kind === 'viking') {
+ return toDownloadUrl(target.value)
}
+ return target.value
+}
+
+function MarkdownImage({
+ src,
+ alt,
+ fileUri,
+}: {
+ src?: string
+ alt?: string
+ fileUri: string
+}) {
+ const target = useMemo(
+ () => (src ? resolveMarkdownAssetTarget(String(src), fileUri) : null),
+ [src, fileUri],
+ )
+ const [objectUrl, setObjectUrl] = useState<string | null>(null)
+ const [failed, setFailed] = useState(false)
+
+ useEffect(() => {
+ if (!target || target.kind !== 'viking') {
+ return
+ }
+
+ let alive = true
+ let created: string | null = null
+ setObjectUrl(null)
+ setFailed(false)
+
+ const run = async () => {
+ try {
+ const response = await getContentDownload({
+ query: { uri: target.value },
+ responseType: 'blob',
+ throwOnError: true,
+ })
+ if (!alive) return
+ const blob = response.data as Blob
+ if (blob.size === 0) {
+ throw new Error('empty blob')
+ }
+ created = URL.createObjectURL(blob)
+ setObjectUrl(created)
+ } catch {
+ if (alive) setFailed(true)
+ }
+ }
- if (trimmed.startsWith(vikingPrefix)) {
- return toDownloadUrl(trimmed)
+ void run()
+ return () => {
+ alive = false
+ if (created) {
+ URL.revokeObjectURL(created)
+ }
+ }
+ }, [target])
+
+ const resolvedSrc =
+ target?.kind === 'viking'
+ ? objectUrl || ''
+ : target
+ ? target.value
+ : String(src || '')
+
+ if (target?.kind === 'viking' && !resolvedSrc) {
+ if (failed) {
+ return (
+ <span className="text-xs text-muted-foreground">
+ [{alt || fileNameFromUri(target.value)}]
+ </span>
+ )
+ }
+ return null
}
- const vikingUri = resolveRelativeVikingUri(fileUri, trimmed)
- return toDownloadUrl(vikingUri)
+ return (
+ <img
+ src={resolvedSrc}
+ alt={alt || ''}
+ loading="lazy"
+ className="max-w-full rounded-md outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10"
+ />
+ )
}
function detectCodeLanguage(filename: string): string | null {
@@ -1339,21 +1450,16 @@ export function FilePreview({
<article className="prose prose-sm max-w-none break-words dark:prose-invert dark:prose-pre:bg-muted-foreground/20">
<ReactMarkdown
remarkPlugins={[remarkGfm]}
+ urlTransform={(url) => url}
components={{
...markdownComponents,
- img: ({ src, alt }) => {
- const resolvedSrc = src
- ? resolveMarkdownAssetUrl(String(src), file.uri)
- : String(src || '')
- return (
- <img
- src={resolvedSrc}
- alt={alt || ''}
- loading="lazy"
- className="max-w-full rounded-md outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10"
- />
- )
- },
+ img: ({ src, alt }) => (
+ <MarkdownImage
+ src={src ? String(src) : undefined}
+ alt={alt}
+ fileUri={file.uri}
+ />
+ ),
a: ({ href, children }) => {
const resolvedHref = href
? resolveMarkdownAssetUrl(String(href), file.uri)