Agent Zero AI framework
fix(document_query): isolate LiteParse parsing
Alessandrob2ead06a4eef
diff --git a/plugins/_document_query/README.md b/plugins/_document_query/README.mdindex 898e7a613..62655189c 100644--- a/plugins/_document_query/README.md+++ b/plugins/_document_query/README.md@@ -8,7 +8,7 @@ timeouts and thread-safe parsers.- **Strategy-pattern parsers** - MIME-type routing to dedicated parser classes- **Centralized fetching** - local and HTTP(S) resources are fetched once, size-checked, then passed to parsers- **LiteParse first path** - fast local parsing for PDFs and supported document/image formats, with legacy fallbacks-- **Thread-safe execution** - all sync parsers offloaded to asyncio.to_thread+- **Bounded parser execution** - sync parsers are offloaded to asyncio.to_thread and globally capped across chats- **Configurable timeouts** - per-document and gather-level timeouts- **Expanded format support** - PDF, HTML, text, YAML, XML, TOML, JS, TS, images, and catch-all Unstructured@@ -23,10 +23,14 @@ See default_config.yaml for all options. Key settings:| max_remote_bytes | 52428800 | Max remote document size || per_document_timeout | 60 | Max time for a single document parse || gather_timeout | 120 | Max time for all documents combined |+| parser_concurrency | 1 | Max parser jobs running across all chats in one process |+| context_intro_chunks | 2 | Leading chunks included per document for title/abstract grounding || chunk_size | 1000 | Text splitter chunk size || chunk_overlap | 100 | Text splitter overlap || search_threshold | 0.5 | Similarity search threshold || liteparse_enabled | true | Prefer LiteParse before legacy parser fallbacks |+| liteparse_num_workers | 1 | Max LiteParse OCR workers per parser job |+| liteparse_subprocess | true | Run LiteParse in a child process so native crashes fall back safely || thread_offload | true | Offload sync parsers to thread pool |LiteParse is installed into the Agent Zero framework runtime from hooks.py duringdiff --git a/plugins/_document_query/default_config.yaml b/plugins/_document_query/default_config.yamlindex 27f831e7a..a850016cc 100644--- a/plugins/_document_query/default_config.yaml+++ b/plugins/_document_query/default_config.yaml@@ -9,6 +9,8 @@ per_document_timeout: 60 # max time for a single document parsegather_timeout: 120 # max time for all documents combined in one call# --- Parser settings ---+parser_concurrency: 1 # max parser jobs running across all chats in this process+context_intro_chunks: 2 # always include leading chunks per document for title/abstract groundingchunk_size: 1000chunk_overlap: 100search_threshold: 0.5@@ -26,6 +28,7 @@ liteparse_target_pages:liteparse_dpi: 150liteparse_preserve_very_small_text: falseliteparse_output_format: text-liteparse_num_workers:+liteparse_num_workers: 1 # LiteParse defaults to CPU cores - 1; cap it for web runtime stability+liteparse_subprocess: true # isolate LiteParse native runtime crashes from the Web UI processpdf_ocr_fallback: true # enable legacy Tesseract fallback after PyMuPDFthread_offload: true # offload sync parsers to thread pooldiff --git a/plugins/_document_query/helpers/document_query.py b/plugins/_document_query/helpers/document_query.pyindex d74feacca..e1553c872 100644--- a/plugins/_document_query/helpers/document_query.py+++ b/plugins/_document_query/helpers/document_query.py@@ -7,8 +7,9 @@ a thread pool and bounded by configurable timeouts.import asyncioimport json+import threadingfrom datetime import datetime-from typing import Callable, List, Optional, Sequence, Tuple+from typing import Any, Callable, List, Optional, Sequence, Tuplefrom urllib.parse import urlparsefrom langchain.schema import SystemMessage, HumanMessage@@ -25,6 +26,33 @@ from plugins._document_query.helpers.parsers import BaseParser, get_parsers_for_DEFAULT_SEARCH_THRESHOLD = 0.5+DEFAULT_PARSER_CONCURRENCY = 1+SMALL_DOCUMENT_FALLBACK_MAX_CHARS = 12000+_PARSER_SEMAPHORES: dict[tuple[int, int], asyncio.Semaphore] = {}+_PARSER_SEMAPHORES_LOCK = threading.Lock()+++def _positive_int(value: Any, default: int) -> int:+ try:+ parsed = int(value)+ except (TypeError, ValueError):+ return default+ return parsed if parsed > 0 else default+++def _parser_semaphore(config: dict) -> asyncio.Semaphore:+ concurrency = _positive_int(+ config.get("parser_concurrency"),+ DEFAULT_PARSER_CONCURRENCY,+ )+ loop = asyncio.get_running_loop()+ key = (id(loop), concurrency)+ with _PARSER_SEMAPHORES_LOCK:+ semaphore = _PARSER_SEMAPHORES.get(key)+ if semaphore is None:+ semaphore = asyncio.Semaphore(concurrency)+ _PARSER_SEMAPHORES[key] = semaphore+ return semaphoredef _load_config(agent: Agent) -> dict:@@ -207,7 +235,7 @@ class DocumentQueryHelper:gather_timeout = self.config.get("gather_timeout", 120)try:- await asyncio.wait_for(+ document_contents = await asyncio.wait_for(asyncio.gather(*[self.document_get_content(uri, True) for uri in document_uris]),@@ -220,6 +248,14 @@ class DocumentQueryHelper:search_threshold = self.config.get("search_threshold", DEFAULT_SEARCH_THRESHOLD)search_limit = self.config.get("search_limit", 100)selected_chunks = {}+ normalized_uris = [self.store.normalize_uri(uri) for uri in document_uris]+ intro_chunk_count = _positive_int(+ self.config.get("context_intro_chunks"),+ 2,+ )+ for uri in normalized_uris:+ for chunk in await self._get_document_intro_chunks(uri, intro_chunk_count):+ selected_chunks[chunk.metadata["id"]] = chunkfor question in questions:self.progress_callback(f"Optimizing query: {question}")@@ -233,7 +269,6 @@ class DocumentQueryHelper:await self.agent.handle_intervention()self.progress_callback(f"Searching documents with query: {optimized_query}")- normalized_uris = [self.store.normalize_uri(uri) for uri in document_uris]doc_filter = " or ".join([f"document_uri == '{uri}'" for uri in normalized_uris])@@ -246,18 +281,48 @@ class DocumentQueryHelper:selected_chunks[chunk.metadata["id"]] = chunkif not selected_chunks:+ fallback_content = self._small_document_fallback_content(+ document_uris,+ document_contents,+ )+ if fallback_content:+ self.progress_callback(+ "No matching chunks found; using extracted document content"+ )+ ai_response = await self._answer_questions_from_content(+ fallback_content,+ questions,+ "extracted document content",+ )+ self.progress_callback(f"Q&A process completed")+ return True, ai_response+self.progress_callback("No relevant content found in the documents")content = f"!!! No content found for documents: {json.dumps(document_uris)} matching queries: {json.dumps(questions)}"return False, content+ content = "\n\n----\n\n".join(+ [chunk.page_content for chunk in selected_chunks.values()]+ )+ ai_response = await self._answer_questions_from_content(+ content,+ questions,+ f"{len(selected_chunks)} chunks",+ )+ self.progress_callback(f"Q&A process completed")+ return True, ai_response++ async def _answer_questions_from_content(+ self,+ content: str,+ questions: Sequence[str],+ context_label: str,+ ) -> str:self.progress_callback(- f"Processing {len(questions)} questions in context of {len(selected_chunks)} chunks"+ f"Processing {len(questions)} questions in context of {context_label}")await self.agent.handle_intervention()questions_str = "\n".join([f" * {question}" for question in questions])- content = "\n\n----\n\n".join(- [chunk.page_content for chunk in selected_chunks.values()]- )qa_system_message = self.agent.parse_prompt("fw.document_query.system_prompt.md")qa_user_message = f"# Document:\n{content}\n\n# Queries:\n{questions_str}"ai_response, _reasoning = await self.agent.call_chat_model(@@ -267,8 +332,41 @@ class DocumentQueryHelper:],explicit_caching=False,)- self.progress_callback(f"Q&A process completed")- return True, str(ai_response)+ return str(ai_response)++ @staticmethod+ def _small_document_fallback_content(+ document_uris: Sequence[str],+ document_contents: Sequence[str],+ max_chars: int = SMALL_DOCUMENT_FALLBACK_MAX_CHARS,+ ) -> str:+ blocks = []+ for document_uri, document_content in zip(document_uris, document_contents):+ text = (document_content or "").strip()+ if text:+ blocks.append(f"# Source: {document_uri}\n\n{text}")++ if not blocks:+ return ""++ content = "\n\n----\n\n".join(blocks)+ if len(content) > max_chars:+ return ""+ return content++ async def _get_document_intro_chunks(+ self,+ document_uri: str,+ limit: int,+ ) -> list[Document]:+ if limit <= 0:+ return []+ if not hasattr(self.store, "_get_document_chunks"):+ return []+ chunks = await self.store._get_document_chunks(document_uri)+ return sorted(chunks, key=lambda chunk: chunk.metadata.get("chunk_index", 0))[+ :limit+ ]async def document_get_content(self, document_uri: str, add_to_db: bool = False@@ -328,15 +426,17 @@ class DocumentQueryHelper:thread_offload: bool,) -> str:errors_seen = []+ semaphore = _parser_semaphore(self.config)for parser in parsers:try:- self.progress_callback("Parsing document content")- content = await parser.parse(- document=document,- config=self.config,- timeout=timeout,- thread_offload=thread_offload,- )+ async with semaphore:+ self.progress_callback("Parsing document content")+ content = await parser.parse(+ document=document,+ config=self.config,+ timeout=timeout,+ thread_offload=thread_offload,+ )if content:return contenterrors_seen.append(f"{parser.__class__.__name__}: no content")diff --git a/plugins/_document_query/helpers/parsers/liteparse.py b/plugins/_document_query/helpers/parsers/liteparse.pyindex e2f9e7165..110b10f4d 100644--- a/plugins/_document_query/helpers/parsers/liteparse.py+++ b/plugins/_document_query/helpers/parsers/liteparse.py@@ -2,7 +2,10 @@from __future__ import annotations+import jsonimport os+import subprocess+import sysfrom pathlib import Pathfrom plugins._document_query.helpers.fetch import FetchedDocument@@ -12,6 +15,8 @@ from .base import BaseParserclass LiteParseParser(BaseParser):"""Fast parser powered by run-llama/liteparse when available."""+ DEFAULT_NUM_WORKERS = 1+mimetypes = ["application/pdf","application/msword",@@ -30,6 +35,11 @@ class LiteParseParser(BaseParser):return bool(config.get("liteparse_enabled", True))def _parse_sync(self, document: FetchedDocument, config: dict) -> str:+ if config.get("liteparse_subprocess", True):+ return self._parse_subprocess(document, config)+ return self._parse_in_process(document, config)++ def _parse_in_process(self, document: FetchedDocument, config: dict) -> str:try:from liteparse import LiteParseexcept Exception as e:@@ -44,6 +54,56 @@ class LiteParseParser(BaseParser):raise ValueError("LiteParse returned no text")return text+ def _parse_subprocess(self, document: FetchedDocument, config: dict) -> str:+ with document.local_file() as file_path:+ payload = {+ "file_path": file_path,+ "kwargs": self._liteparse_kwargs(config),+ }+ env = os.environ.copy()+ project_root = str(Path(__file__).resolve().parents[4])+ python_path = env.get("PYTHONPATH", "")+ env["PYTHONPATH"] = (+ f"{project_root}{os.pathsep}{python_path}"+ if python_path+ else project_root+ )+ timeout = float(config.get("per_document_timeout", 60))+ result = subprocess.run(+ [+ sys.executable,+ "-m",+ "plugins._document_query.helpers.parsers.liteparse_worker",+ ],+ input=json.dumps(payload),+ text=True,+ capture_output=True,+ cwd=project_root,+ env=env,+ timeout=timeout,+ check=False,+ )++ if result.returncode != 0:+ detail = (result.stderr or result.stdout or "").strip()+ raise RuntimeError(+ "LiteParse subprocess failed"+ f" with exit code {result.returncode}: {detail[-2000:]}"+ )++ try:+ response = json.loads(result.stdout)+ except json.JSONDecodeError as e:+ raise RuntimeError(+ "LiteParse subprocess returned invalid output: "+ f"{result.stdout[-2000:]}"+ ) from e++ text = response.get("text", "") or ""+ if not text.strip():+ raise ValueError("LiteParse returned no text")+ return text+def _liteparse_kwargs(self, config: dict) -> dict:kwargs = {"ocr_enabled": bool(config.get("liteparse_ocr_enabled", True)),@@ -67,9 +127,10 @@ class LiteParseParser(BaseParser):if value not in (None, ""):kwargs[liteparse_key] = value- num_workers = config.get("liteparse_num_workers")- if num_workers not in (None, ""):- kwargs["num_workers"] = int(num_workers)+ kwargs["num_workers"] = _positive_int(+ config.get("liteparse_num_workers"),+ self.DEFAULT_NUM_WORKERS,+ )tessdata_path = config.get("liteparse_tessdata_path") or _detect_tessdata_path()if tessdata_path:@@ -91,3 +152,11 @@ def _detect_tessdata_path() -> str:if candidate and (Path(candidate) / "eng.traineddata").is_file():return candidatereturn ""+++def _positive_int(value, default: int) -> int:+ try:+ parsed = int(value)+ except (TypeError, ValueError):+ return default+ return parsed if parsed > 0 else defaultdiff --git a/plugins/_document_query/helpers/parsers/liteparse_worker.py b/plugins/_document_query/helpers/parsers/liteparse_worker.pynew file mode 100644index 000000000..67c50b288--- /dev/null+++ b/plugins/_document_query/helpers/parsers/liteparse_worker.py@@ -0,0 +1,24 @@+"""Subprocess entry point for isolating LiteParse native runtime crashes."""++from __future__ import annotations++import json+import sys+++def main() -> int:+ payload = json.load(sys.stdin)+ file_path = payload["file_path"]+ kwargs = payload.get("kwargs") or {}++ from liteparse import LiteParse++ parser = LiteParse(**kwargs)+ result = parser.parse(file_path)+ text = getattr(result, "text", "") or ""+ json.dump({"text": text}, sys.stdout)+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/tests/test_document_query_fallback.py b/tests/test_document_query_fallback.pyindex 3473fd0a2..10f926450 100644--- a/tests/test_document_query_fallback.py+++ b/tests/test_document_query_fallback.py@@ -44,6 +44,7 @@ def test_document_qa_uses_small_document_content_when_search_finds_no_chunks():helper = object.__new__(DocumentQueryHelper)helper.agent = agenthelper.store = FakeStore()+ helper.config = {}helper.progress_callback = progress.appendasync def document_get_content(uri, add_to_db=False):diff --git a/tests/test_document_query_plugin.py b/tests/test_document_query_plugin.pyindex 16f4114f6..a342471c5 100644--- a/tests/test_document_query_plugin.py+++ b/tests/test_document_query_plugin.py@@ -9,6 +9,7 @@ from plugins._document_query.helpers.fetch import FetchedDocument, fetch_public_from plugins._document_query.helpers.document_query import DocumentQueryHelperfrom plugins._document_query.helpers.parsers.base import BaseParserfrom plugins._document_query.helpers.parsers import get_parsers_for_mimetype+from plugins._document_query.helpers.parsers.liteparse import LiteParseParserfrom plugins._document_query.helpers.parsers.text import TextParser@@ -27,6 +28,24 @@ class ParserNameShouldNotLeak(BaseParser):return "parsed"+class CountingAsyncParser(BaseParser):+ mimetypes = ["text/plain"]+ active = 0+ max_active = 0++ async def _parse_async(self, document: FetchedDocument, config: dict) -> str:+ type(self).active += 1+ type(self).max_active = max(type(self).max_active, type(self).active)+ try:+ await asyncio.sleep(0.02)+ return document.uri+ finally:+ type(self).active -= 1++ def _parse_sync(self, document: FetchedDocument, config: dict) -> str:+ return document.uri++def test_fetch_file_detects_mimetype_and_reads_once(tmp_path):document = tmp_path / "notes.txt"document.write_text("hello\nworld\n", encoding="utf-8")@@ -92,6 +111,25 @@ def test_liteparse_is_installed_by_docker_and_plugin_hook_requirements():assert plugin_requirements.strip().splitlines() == ["liteparse>=2.0.0,<3.0.0"]+def test_default_config_bounds_liteparse_runtime_concurrency():+ default_config = (+ ROOT / "plugins" / "_document_query" / "default_config.yaml"+ ).read_text(encoding="utf-8")++ assert "parser_concurrency: 1" in default_config+ assert "context_intro_chunks: 2" in default_config+ assert "liteparse_num_workers: 1" in default_config+ assert "liteparse_subprocess: true" in default_config+++def test_liteparse_parser_caps_workers_by_default():+ parser = LiteParseParser()++ assert parser._liteparse_kwargs({})["num_workers"] == 1+ assert parser._liteparse_kwargs({"liteparse_num_workers": "3"})["num_workers"] == 3+ assert parser._liteparse_kwargs({"liteparse_num_workers": ""})["num_workers"] == 1++def test_query_optimize_prompt_filename_is_spelled_correctly():prompt_dir = ROOT / "plugins" / "_document_query" / "prompts"helper_source = (@@ -129,6 +167,52 @@ def test_parser_progress_is_user_facing_and_generic():assert progress == ["Parsing document content"]+def test_parse_document_limits_parser_concurrency_across_helpers():+ CountingAsyncParser.active = 0+ CountingAsyncParser.max_active = 0+ fetched_a = FetchedDocument(+ uri="/tmp/a.txt",+ source_uri="/tmp/a.txt",+ scheme="file",+ mimetype="text/plain",+ content=b"a",+ local_path=None,+ )+ fetched_b = FetchedDocument(+ uri="/tmp/b.txt",+ source_uri="/tmp/b.txt",+ scheme="file",+ mimetype="text/plain",+ content=b"b",+ local_path=None,+ )+ helper_a = object.__new__(DocumentQueryHelper)+ helper_a.config = {"parser_concurrency": 1}+ helper_a.progress_callback = lambda _msg: None+ helper_b = object.__new__(DocumentQueryHelper)+ helper_b.config = {"parser_concurrency": 1}+ helper_b.progress_callback = lambda _msg: None++ async def parse_both():+ return await asyncio.gather(+ helper_a._parse_document(+ document=fetched_a,+ parsers=[CountingAsyncParser()],+ timeout=1,+ thread_offload=False,+ ),+ helper_b._parse_document(+ document=fetched_b,+ parsers=[CountingAsyncParser()],+ timeout=1,+ thread_offload=False,+ ),+ )++ assert sorted(run_async(parse_both())) == ["/tmp/a.txt", "/tmp/b.txt"]+ assert CountingAsyncParser.max_active == 1++def test_document_query_prompt_uses_progressive_skill_disclosure():from helpers.skills import find_skill