Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.pynew file mode 100644index 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""++ 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_countdiff --git a/openviking/parse/parsers/html.py b/openviking/parse/parsers/html.pyindex 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 inforesult.parse_time = time.time() - start_timediff --git a/openviking/parse/parsers/markdown.py b/openviking/parse/parsers/markdown.pyindex 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 asyncioimport hashlib+import ioimport osimport reimport time@@ -132,6 +134,14 @@ class MarkdownParser(BaseParser):DEFAULT_MIN_SECTION_TOKENS = 512 # Minimum tokens to create a separate sectionMAX_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 pathinstruction: 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 andenable_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_timelogger.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.pyindex 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 ioimport reimport timefrom collections import Counter, defaultdict@@ -128,11 +129,16 @@ class PDFParser(BaseParser):# Step 2: Parse Markdown using MarkdownParser, pass through resource namemd_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""@@ -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 objectimg_info: Image metadata from page.imagesReturns:- 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.pyindex 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) lookuptable_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 positionsfrom docx.oxml.ns import qn@@ -89,6 +106,15 @@ class WordParser(BaseParser):from docx.text.paragraph import Paragraphparagraph = 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"")+ 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.pyindex 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_urisfrom 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 diffawait 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.pyindex 16c5c9078..4633b47be 100644--- a/openviking/utils/resource_processor.py+++ b/openviking/utils/resource_processor.py@@ -12,6 +12,7 @@ import timefrom collections.abc import Callablefrom typing import TYPE_CHECKING, Any, Dict, List, Optional+from openviking.parse.image_rewrite import rewrite_image_urisfrom openviking.parse.tree_builder import TreeBuilderfrom openviking.server.identity import RequestContextfrom 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_urisource_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.pyindex 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.pyindex 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 Nonediff --git a/web-studio/src/routes/resources/-components/file-preview.tsx b/web-studio/src/routes/resources/-components/file-preview.tsxindex 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"><ReactMarkdownremarkPlugins={[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)