Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 가 생각만 하다 출력 상한에 닿으면 한 번 더 부른다
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
99 changes: 94 additions & 5 deletions src/xgen_agent_runtime/tools/built_in/parse_document_tool.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@

- 본문 글, 페이지·슬라이드·시트 구분 표식(``[Page Number: N]`` · ``[Slide Number: N]`` · ``[Sheet: …]``)
- 표는 글로 옮긴 모양(HTML ``<table>`` 이나 마크다운), 차트는 ``[chart]…[/chart]`` 글
- 이미지는 ``[Image]`` 자리표시뿐(그림 내용은 없다, OCR 도 하지 않는다)
- 이미지는 ``[Image]`` 자리표시. 호스트가 그림 읽기 함수(``ToolContext.extras["image_reader"]``)를 주면
그 자리에 그림에서 읽은 글과 설명이 들어간다(4.104.0, XGEN 은 파일 저장소 그림 처리와 같은 VLM · 같은 결과)
- 문서 메타데이터(제목·작성자·날짜 등, 있으면)

**원본의 전체 구조가 아니다** — 글꼴·서식·위치·레이아웃·병합 규칙·도형·주석 등은 담지 않는다.
Expand All @@ -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

Expand All @@ -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"})
Expand All @@ -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):
Expand All @@ -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."
Expand Down Expand Up @@ -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:
Expand All @@ -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),
Expand Down
1 change: 1 addition & 0 deletions tests/unit/test_no_direct_file_io.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down
65 changes: 65 additions & 0 deletions tests/unit/test_parse_document_lock.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading