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