diff --git a/CHANGELOG.md b/CHANGELOG.md
index dfa3a0e..06c1eb3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,18 @@ All notable changes to `xgen-agent-runtime` are recorded here. The format
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
this project adheres to [Semantic Versioning](https://semver.org/).
+## [4.104.0] - 2026-10-26
+
+### Added: ParseDocument 가 호스트의 그림 읽기 함수로 문서 속 그림을 글로 바꾼다
+
+ParseDocument 는 문서 속 그림을 `[Image]` 자리표시로만 남겨, 그림을 볼 수 없는 모델은 스캔 페이지 · 차트 · 도해의 내용을
+전혀 받지 못했다. 호스트가 `ToolContext.extras["image_reader"]` 로 그림 읽기 함수(`(바이트, 이름) -> 글 | None`)를 주면
+그림 자리에 그 결과를 넣는다. XGEN 은 파일 저장소 그림 처리와 같은 VLM · 같은 결과(그림 바이트마다 한 번 읽어 저장)를 준다.
+
+- 같은 그림(같은 바이트)은 한 번만 읽고, 그림 번호는 문서에 처음 나온 순서다. 한 번에 서로 다른 그림 최대 30장, 20 MiB 넘는 그림은 읽지 않는다.
+- 읽지 못한 그림과 함수가 없을 때는 예전처럼 `[Image]`. 임시 그림 경로는 결과에 남기지 않는다.
+- `_extract` 는 예전 그대로 글만 돌려준다(그림까지 받는 것은 `_extract_with_images`).
+
## [4.103.2] - 2026-10-26
### Fixed: Chat Completions 가 생각만 하다 출력 상한에 닿으면 한 번 더 부른다
diff --git a/pyproject.toml b/pyproject.toml
index e82b72a..1a1fb6a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "xgen-agent-runtime"
-version = "4.103.2"
+version = "4.104.0"
description = "Harness-engineered agent pipeline library with 21-stage dual-abstraction architecture, built on the Anthropic API"
readme = "README.md"
license = "Apache-2.0"
diff --git a/src/xgen_agent_runtime/tools/built_in/parse_document_tool.py b/src/xgen_agent_runtime/tools/built_in/parse_document_tool.py
index 7ef523f..de4439d 100644
--- a/src/xgen_agent_runtime/tools/built_in/parse_document_tool.py
+++ b/src/xgen_agent_runtime/tools/built_in/parse_document_tool.py
@@ -10,7 +10,8 @@
- 본문 글, 페이지·슬라이드·시트 구분 표식(``[Page Number: N]`` · ``[Slide Number: N]`` · ``[Sheet: …]``)
- 표는 글로 옮긴 모양(HTML ``
`` 이나 마크다운), 차트는 ``[chart]…[/chart]`` 글
-- 이미지는 ``[Image]`` 자리표시뿐(그림 내용은 없다, OCR 도 하지 않는다)
+- 이미지는 ``[Image]`` 자리표시. 호스트가 그림 읽기 함수(``ToolContext.extras["image_reader"]``)를 주면
+ 그 자리에 그림에서 읽은 글과 설명이 들어간다(4.104.0, XGEN 은 파일 저장소 그림 처리와 같은 VLM · 같은 결과)
- 문서 메타데이터(제목·작성자·날짜 등, 있으면)
**원본의 전체 구조가 아니다** — 글꼴·서식·위치·레이아웃·병합 규칙·도형·주석 등은 담지 않는다.
@@ -24,11 +25,13 @@
from __future__ import annotations
import asyncio
+import hashlib
+import os
import re
import tempfile
import threading
from pathlib import PurePosixPath
-from typing import Any, Dict, Optional, Tuple
+from typing import Any, Callable, Dict, List, Optional, Tuple
from xgen_agent_runtime.tools.base import Tool, ToolCapabilities, ToolContext, ToolResult
@@ -38,6 +41,15 @@
#: doc2chunk 가 이미지 자리에 남기는 표식 — 경로는 이 호출의 임시 폴더라 호출이 끝나면 없다.
_IMAGE_TAG = re.compile(r"\[Image:[^\]]*\]")
+#: 경로를 꺼내는 꼴(``_IMAGE_TAG`` 와 같은 표식).
+_IMAGE_PATH = re.compile(r"\[Image:([^\]]*)\]")
+
+#: 한 번에 읽는 그림 수(같은 그림은 하나로 센다). 넘은 그림은 ``[Image]`` 로 둔다.
+MAX_IMAGES = 30
+#: 그림 하나의 크기 상한. 넘으면 읽지 않는다.
+MAX_IMAGE_BYTES = 20 * 1024 * 1024
+#: 동시에 부르는 그림 읽기 수.
+_READ_CONCURRENCY = 4
#: 문서 형식이 아닌데 이 도구로 오면 Read 가 낫다고 알려 줄 확장자.
_PLAIN_TEXT = frozenset({"txt", "md", "markdown", "log"})
@@ -60,16 +72,86 @@ def _load_processor(image_directory: str) -> Any:
def _extract(local_path: str, extension: str) -> str:
"""doc2chunk 추출 — 청크 없이 글만. 지원하지 않는 형식이면 ValueError."""
+ return _extract_with_images(local_path, extension, keep_images=False)[0]
+
+
+def _extract_with_images(
+ local_path: str, extension: str, keep_images: bool = True
+) -> Tuple[str, Dict[str, bytes]]:
+ """``_extract`` 와 같고, ``keep_images`` 면 그림 표식의 그림 바이트를 임시 폴더가 지워지기 전에 읽어
+ 함께 돌려준다(``{표식 경로: 바이트}``, 서로 다른 그림 최대 ``MAX_IMAGES``)."""
with _EXTRACT_LOCK, tempfile.TemporaryDirectory(prefix="xgen-parse-img-") as image_dir:
processor = _load_processor(image_dir)
if not processor.is_supported(extension):
raise ValueError(f"unsupported file type: .{extension}")
- return processor.extract_text(
+ text = processor.extract_text(
local_path,
file_extension=extension,
extract_metadata=True,
ocr_processing=False,
)
+ images: Dict[str, bytes] = {}
+ if keep_images and text:
+ seen = set()
+ for path in _IMAGE_PATH.findall(text):
+ if path in images or len(seen) >= MAX_IMAGES:
+ continue
+ try:
+ if os.path.getsize(path) > MAX_IMAGE_BYTES:
+ continue
+ with open(path, "rb") as handle:
+ data = handle.read()
+ except OSError:
+ continue
+ digest = hashlib.sha256(data).hexdigest()
+ if digest in seen:
+ images[path] = data
+ continue
+ seen.add(digest)
+ images[path] = data
+ return text, images
+
+
+async def _read_images(
+ text: str, images: Dict[str, bytes], reader: Callable[..., Optional[str]]
+) -> str:
+ """그림 표식 자리에 그림 읽기 결과를 넣는다. 읽지 못한 그림은 ``[Image]`` 로 둔다.
+
+ 같은 그림(같은 바이트)은 한 번만 읽는다. 그림 번호는 문서에 처음 나온 순서다.
+ """
+ order: List[str] = []
+ by_digest: Dict[str, str] = {}
+ path_digest: Dict[str, str] = {}
+ for path, data in images.items():
+ digest = hashlib.sha256(data).hexdigest()
+ path_digest[path] = digest
+ if digest not in by_digest:
+ by_digest[digest] = path
+ order.append(digest)
+ gate = asyncio.Semaphore(_READ_CONCURRENCY)
+ results: Dict[str, Optional[str]] = {}
+
+ async def one(digest: str) -> None:
+ path = by_digest[digest]
+ async with gate:
+ try:
+ results[digest] = await asyncio.to_thread(
+ reader, images[path], PurePosixPath(path).name
+ )
+ except Exception: # noqa: BLE001 - 그림 하나의 실패는 그 자리를 [Image] 로 둔다
+ results[digest] = None
+
+ await asyncio.gather(*(one(digest) for digest in order))
+ numbers = {digest: n for n, digest in enumerate(order, 1)}
+
+ def place(match: "re.Match[str]") -> str:
+ digest = path_digest.get(match.group(1))
+ found = results.get(digest) if digest else None
+ if not found:
+ return "[Image]"
+ return str(found).replace("[그림 1", f"[그림 {numbers[digest]}", 1)
+
+ return _IMAGE_PATH.sub(place, text)
class ParseDocumentTool(Tool):
@@ -85,7 +167,8 @@ def description(self) -> str:
"Extract the TEXT of a document file — PDF, Word (docx/doc), PowerPoint (pptx/ppt), "
"Excel (xlsx/xls), HWP/HWPX, RTF, CSV/TSV, HTML and similar. Returns text-centric "
"content only: the body text with page/slide/sheet markers, tables rendered as text "
- "(HTML or markdown), chart data as text, [Image] placeholders and document metadata. "
+ "(HTML or markdown), chart data as text, [Image] placeholders (or, when the server can read "
+ "images, each image's text and description) and document metadata. "
"It is NOT the full document structure: fonts, formatting, positions, layout, shapes "
"and images are not returned, so the result cannot be used to rebuild or edit the file. "
"Long results come in parts: pass offset to continue. For plain text or code files use Read."
@@ -142,9 +225,13 @@ async def execute(self, input: Dict[str, Any], context: ToolContext) -> ToolResu
return ToolResult(
content=f"{name} has no file extension, so its format is unknown.", is_error=True
)
+ reader = (context.extras or {}).get("image_reader") if context is not None else None
+ reader = reader if callable(reader) else None
try:
async with fs.materialize(raw) as local:
- text = await asyncio.to_thread(_extract, str(local), extension)
+ text, images = await asyncio.to_thread(
+ _extract_with_images, str(local), extension, reader is not None
+ )
except FileNotFoundError:
return ToolResult(content=f"File not found: {resolved}", is_error=True)
except IsADirectoryError:
@@ -159,6 +246,8 @@ async def execute(self, input: Dict[str, Any], context: ToolContext) -> ToolResu
return ToolResult(
content=f"Could not parse {name}: {type(exc).__name__}: {exc}", is_error=True
)
+ if reader is not None and images:
+ text = await _read_images(text or "", images, reader)
text = _IMAGE_TAG.sub("[Image]", text or "")
return ToolResult(
content=_page(name, text, offset, limit, extension),
diff --git a/tests/unit/test_no_direct_file_io.py b/tests/unit/test_no_direct_file_io.py
index 53367b8..7861484 100644
--- a/tests/unit/test_no_direct_file_io.py
+++ b/tests/unit/test_no_direct_file_io.py
@@ -38,6 +38,7 @@
"audio_tools.py": "파드 거주 가족(STT 어댑터) — 4단계에서 materialize/commit 으로",
"worktree_tools.py": "로컬 git 체크아웃 전용(geny-cli). Geny 서버 표면에 노출되지 않는다",
"tool_result_read_tool.py": "잘린 도구 결과의 원본 — 에이전트 작업 공간이 아니라 executor 저장소(storage_path)",
+ "parse_document_tool.py": "doc2chunk 가 이 호출의 임시 폴더에 꺼낸 그림(4.104.0). 작업 공간 파일이 아니라 추출 중의 임시 파일",
}
_PATH_METHODS = {
diff --git a/tests/unit/test_parse_document_lock.py b/tests/unit/test_parse_document_lock.py
index 79058a9..b779ba0 100644
--- a/tests/unit/test_parse_document_lock.py
+++ b/tests/unit/test_parse_document_lock.py
@@ -44,3 +44,68 @@ def extract_text(self, path, **kwargs):
t.join()
assert sorted(out) == sorted(f"text of /tmp/{i}.pdf" for i in range(6))
assert state["peak"] == 1
+
+
+# ── 그림 읽기 함수(4.104.0) ──────────────────────────────────────────────────
+#
+# 호스트가 ``extras["image_reader"]`` 를 주면 그림 자리에 그림에서 읽은 글이 들어간다. XGEN 은 파일
+# 저장소 그림 처리와 같은 VLM · 같은 결과를 준다. 없으면 예전처럼 ``[Image]``.
+
+
+def _fake_document(monkeypatch, tmp_path, images):
+ from xgen_agent_runtime.tools.built_in import parse_document_tool as m
+
+ class _Processor:
+ def __init__(self, image_directory):
+ self.dir = image_directory
+
+ def is_supported(self, extension):
+ return True
+
+ def extract_text(self, path, **kwargs):
+ parts = ["[Page Number: 1]", "본문"]
+ for n, data in enumerate(images):
+ where = f"{self.dir}/img{n}.png"
+ with open(where, "wb") as handle:
+ handle.write(data)
+ parts.append(f"[Image:{where}]")
+ return "\n".join(parts)
+
+ monkeypatch.setattr(m, "_load_processor", lambda image_directory: _Processor(image_directory))
+ (tmp_path / "doc.pdf").write_bytes(b"%PDF")
+ return m
+
+
+def _run(tmp_path, extras):
+ import asyncio
+
+ from xgen_agent_runtime.tools.base import ToolContext
+ from xgen_agent_runtime.tools.built_in.parse_document_tool import ParseDocumentTool
+ from xgen_agent_runtime.tools.fs import LocalFS
+
+ ctx = ToolContext(session_id="s", working_dir=str(tmp_path), fs=LocalFS(str(tmp_path), [str(tmp_path)]),
+ extras=extras)
+ return asyncio.run(ParseDocumentTool().execute({"file_path": "doc.pdf"}, ctx))
+
+
+def test_with_an_image_reader_each_image_is_read_once_and_numbered(monkeypatch, tmp_path):
+ _fake_document(monkeypatch, tmp_path, [b"chart", b"logo", b"chart"])
+ calls = []
+
+ def reader(data, name):
+ calls.append(data)
+ if data == b"logo":
+ return None # 읽지 못한 그림은 [Image] 로 남는다
+ return "[그림 1 · 차트]\n받아 적은 글: Q3 12.5"
+
+ out = _run(tmp_path, {"image_reader": reader})
+ assert not out.is_error, out.content
+ assert sorted(calls) == [b"chart", b"logo"] # 같은 그림은 한 번만
+ assert out.content.count("받아 적은 글: Q3 12.5") == 2 and "[Image]" in out.content
+ assert "/img" not in out.content # 임시 경로는 남기지 않는다
+
+
+def test_without_an_image_reader_images_stay_placeholders(monkeypatch, tmp_path):
+ _fake_document(monkeypatch, tmp_path, [b"chart"])
+ out = _run(tmp_path, {})
+ assert "[Image]" in out.content and "받아 적은" not in out.content