Skip to content

Agent Zero AI framework

feat: extract document_query into _document_query plugin with parser strategy pattern

Deimos Agent5fd7a6a79e5a
diff --git a/helpers/document_query.py b/helpers/document_query._py.bak
similarity index 100%
rename from helpers/document_query.py
rename to helpers/document_query._py.bak
diff --git a/plugins/_document_query/README.md b/plugins/_document_query/README.md
new file mode 100644
index 000000000..1152a2173
--- /dev/null
+++ b/plugins/_document_query/README.md
@@ -0,0 +1,42 @@
+# Document Query Plugin
+
+Load, parse, index, and Q&A over local and remote documents with configurable
+timeouts and thread-safe parsers.
+
+## Features
+
+- **Strategy-pattern parsers** - MIME-type routing to dedicated parser classes
+- **Thread-safe execution** - all sync parsers offloaded to asyncio.to_thread
+- **Configurable timeouts** - per-document and gather-level timeouts
+- **Expanded format support** - PDF, HTML, text, YAML, XML, TOML, JS, TS, images, and catch-all Unstructured
+
+## Configuration
+
+See default_config.yaml for all options. Key settings:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| fetch_timeout | 30 | HTTP fetch timeout (seconds) |
+| per_document_timeout | 60 | Max time for a single document parse |
+| gather_timeout | 120 | Max time for all documents combined |
+| chunk_size | 1000 | Text splitter chunk size |
+| chunk_overlap | 100 | Text splitter overlap |
+| search_threshold | 0.5 | Similarity search threshold |
+| thread_offload | true | Offload sync parsers to thread pool |
+
+## Parsers
+
+| Parser | MIME Types | Backend |
+|--------|-----------|---------|
+| PdfParser | application/pdf | PyMuPDF + Tesseract OCR fallback |
+| HtmlParser | text/html | Markdownify transformer |
+| TextParser | text/*, application/json, YAML, XML, TOML, JS, TS, shell | Direct read |
+| ImageParser | image/* | UnstructuredLoader |
+| UnstructuredParser | * (catch-all) | UnstructuredLoader hi-res |
+
+## Adding a new parser
+
+1. Create helpers/parsers/<format>.py extending BaseParser
+2. Set mimetypes class attribute
+3. Implement _parse_sync(document_uri, scheme)
+4. Register in helpers/parsers/__init__.py
diff --git a/plugins/_document_query/default_config.yaml b/plugins/_document_query/default_config.yaml
new file mode 100644
index 000000000..bfc9cfa92
--- /dev/null
+++ b/plugins/_document_query/default_config.yaml
@@ -0,0 +1,18 @@
+# Document Query Plugin Configuration
+# All timeout values in seconds
+
+# --- Timeouts ---
+fetch_timeout: 30 # HTTP fetch connect/read timeout
+per_document_timeout: 60 # max time for a single document parse
+gather_timeout: 120 # max time for all documents combined in one call
+
+# --- Parser settings ---
+chunk_size: 1000
+chunk_overlap: 100
+search_threshold: 0.5
+search_limit: 100
+max_remote_bytes: 52428800 # 50 MB
+
+# --- Feature flags ---
+pdf_ocr_fallback: true # enable Tesseract fallback for PDFs
+thread_offload: true # offload sync parsers to thread pool
diff --git a/plugins/_document_query/helpers/__init__.py b/plugins/_document_query/helpers/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/plugins/_document_query/helpers/document_query.py b/plugins/_document_query/helpers/document_query.py
new file mode 100644
index 000000000..4ae63734c
--- /dev/null
+++ b/plugins/_document_query/helpers/document_query.py
@@ -0,0 +1,355 @@
+"""Document query helper with thread-safe parsers and configurable timeouts.
+
+Extracted from the monolithic helpers/document_query.py into a plugin
+with parser strategy pattern where every document parser is offloaded to
+a thread pool and bounded by configurable timeouts.
+"""
+
+import asyncio
+import json
+import mimetypes
+import os
+from datetime import datetime
+from typing import Callable, List, Optional, Sequence, Tuple
+from urllib.parse import urlparse
+
+import aiohttp
+from langchain.schema import SystemMessage, HumanMessage
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain_core.documents import Document
+
+from helpers import files, errors
+from helpers.print_style import PrintStyle
+from helpers.vector_db import VectorDB
+from agent import Agent
+
+from plugins._document_query.helpers.parsers import get_parser_for_mimetype
+
+
+DEFAULT_SEARCH_THRESHOLD = 0.5
+
+
+def _load_config(agent: Agent) -> dict:
+ """Load plugin config with fallback to defaults."""
+ from helpers.plugins import get_plugin_config
+ return get_plugin_config("_document_query", agent=agent) or {}
+
+
+class DocumentQueryStore:
+ """FAISS Store for document query results."""
+
+ DEFAULT_CHUNK_SIZE = 1000
+ DEFAULT_CHUNK_OVERLAP = 100
+
+ @staticmethod
+ def get(agent: Agent):
+ if not agent or not agent.config:
+ raise ValueError("Agent and agent config must be provided")
+ return DocumentQueryStore(agent)
+
+ def __init__(self, agent: Agent):
+ self.agent = agent
+ self.vector_db: VectorDB | None = None
+ self.config = _load_config(agent)
+
+ @staticmethod
+ def normalize_uri(uri: str) -> str:
+ normalized = uri.strip()
+ parsed = urlparse(normalized)
+ scheme = parsed.scheme or "file"
+ if scheme == "file":
+ path = files.fix_dev_path(
+ normalized.removeprefix("file://").removeprefix("file:")
+ )
+ normalized = f"file://{path}"
+ elif scheme in ["http", "https"]:
+ normalized = normalized.replace("http://", "https://")
+ return normalized
+
+ def init_vector_db(self):
+ return VectorDB(self.agent, cache=True)
+
+ async def add_document(
+ self, text: str, document_uri: str, metadata: dict | None = None
+ ) -> tuple[bool, list[str]]:
+ document_uri = self.normalize_uri(document_uri)
+ await self.delete_document(document_uri)
+ doc_metadata = metadata or {}
+ doc_metadata["document_uri"] = document_uri
+ doc_metadata["timestamp"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+ chunk_size = self.config.get("chunk_size", self.DEFAULT_CHUNK_SIZE)
+ chunk_overlap = self.config.get("chunk_overlap", self.DEFAULT_CHUNK_OVERLAP)
+ text_splitter = RecursiveCharacterTextSplitter(
+ chunk_size=chunk_size, chunk_overlap=chunk_overlap
+ )
+ chunks = text_splitter.split_text(text)
+ docs = []
+ for i, chunk in enumerate(chunks):
+ chunk_metadata = doc_metadata.copy()
+ chunk_metadata["chunk_index"] = i
+ chunk_metadata["total_chunks"] = len(chunks)
+ docs.append(Document(page_content=chunk, metadata=chunk_metadata))
+ if not docs:
+ PrintStyle.error(f"No chunks created for document: {document_uri}")
+ return False, []
+ try:
+ if not self.vector_db:
+ self.vector_db = self.init_vector_db()
+ ids = await self.vector_db.insert_documents(docs)
+ PrintStyle.standard(f"Added document '{document_uri}' with {len(docs)} chunks")
+ return True, ids
+ except Exception as e:
+ err_text = errors.format_error(e)
+ PrintStyle.error(f"Error adding document '{document_uri}': {err_text}")
+ return False, []
+
+ async def get_document(self, document_uri: str) -> Optional[Document]:
+ if not self.vector_db:
+ return None
+ document_uri = self.normalize_uri(document_uri)
+ docs = await self._get_document_chunks(document_uri)
+ if not docs:
+ return None
+ chunks = sorted(docs, key=lambda x: x.metadata.get("chunk_index", 0))
+ full_content = "\n".join(chunk.page_content for chunk in chunks)
+ metadata = chunks[0].metadata.copy()
+ metadata.pop("chunk_index", None)
+ metadata.pop("total_chunks", None)
+ return Document(page_content=full_content, metadata=metadata)
+
+ async def _get_document_chunks(self, document_uri: str) -> List[Document]:
+ if not self.vector_db:
+ return []
+ document_uri = self.normalize_uri(document_uri)
+ chunks = await self.vector_db.search_by_metadata(
+ filter=f"document_uri == '{document_uri}'",
+ )
+ PrintStyle.standard(f"Found {len(chunks)} chunks for document: {document_uri}")
+ return chunks
+
+ async def document_exists(self, document_uri: str) -> bool:
+ if not self.vector_db:
+ return False
+ document_uri = self.normalize_uri(document_uri)
+ chunks = await self._get_document_chunks(document_uri)
+ return len(chunks) > 0
+
+ async def delete_document(self, document_uri: str) -> bool:
+ if not self.vector_db:
+ return False
+ document_uri = self.normalize_uri(document_uri)
+ chunks = await self.vector_db.search_by_metadata(
+ filter=f"document_uri == '{document_uri}'",
+ )
+ if not chunks:
+ return False
+ ids_to_delete = [chunk.metadata["id"] for chunk in chunks]
+ if ids_to_delete:
+ dels = await self.vector_db.delete_documents_by_ids(ids_to_delete)
+ PrintStyle.standard(f"Deleted document '{document_uri}' with {len(dels)} chunks")
+ return True
+ return False
+
+ async def search_documents(
+ self, query: str, limit: int = 10, threshold: float = 0.5, filter: str = ""
+ ) -> List[Document]:
+ if not self.vector_db:
+ return []
+ if not query:
+ return []
+ try:
+ results = await self.vector_db.search_by_similarity_threshold(
+ query=query, limit=limit, threshold=threshold, filter=filter
+ )
+ PrintStyle.standard(f"Search '{query}' returned {len(results)} results")
+ return results
+ except Exception as e:
+ PrintStyle.error(f"Error searching documents: {str(e)}")
+ return []
+
+ async def search_document(
+ self, document_uri: str, query: str, limit: int = 10, threshold: float = 0.5
+ ) -> List[Document]:
+ return await self.search_documents(
+ query, limit, threshold, f"document_uri == '{document_uri}'"
+ )
+
+ async def list_documents(self) -> List[str]:
+ if not self.vector_db:
+ return []
+ uris = set()
+ for doc in self.vector_db.db.get_all_docs().values():
+ if isinstance(doc.metadata, dict):
+ uri = doc.metadata.get("document_uri")
+ if uri:
+ uris.add(uri)
+ return sorted(list(uris))
+
+
+class DocumentQueryHelper:
+
+ def __init__(
+ self, agent: Agent, progress_callback: Callable[[str], None] | None = None
+ ):
+ self.agent = agent
+ self.store = DocumentQueryStore.get(agent)
+ self.progress_callback = progress_callback or (lambda x: None)
+ self.store_lock = asyncio.Lock()
+ self.config = _load_config(agent)
+
+ async def document_qa(
+ self, document_uris: List[str], questions: Sequence[str]
+ ) -> Tuple[bool, str]:
+ self.progress_callback(f"Starting Q&A process for {len(document_uris)} documents")
+ await self.agent.handle_intervention()
+
+ gather_timeout = self.config.get("gather_timeout", 120)
+ try:
+ await asyncio.wait_for(
+ asyncio.gather(
+ *[self.document_get_content(uri, True) for uri in document_uris]
+ ),
+ timeout=gather_timeout,
+ )
+ except asyncio.TimeoutError:
+ raise ValueError(f"Document indexing timed out after {gather_timeout}s")
+
+ await self.agent.handle_intervention()
+ search_threshold = self.config.get("search_threshold", DEFAULT_SEARCH_THRESHOLD)
+ search_limit = self.config.get("search_limit", 100)
+ selected_chunks = {}
+
+ for question in questions:
+ self.progress_callback(f"Optimizing query: {question}")
+ await self.agent.handle_intervention()
+ system_content = self.agent.parse_prompt("fw.document_query.optmimize_query.md")
+ optimized_query = (
+ await self.agent.call_utility_model(
+ system=system_content, message=f'Search Query: "{question}"',
+ )
+ ).strip()
+
+ 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]
+ )
+ chunks = await self.store.search_documents(
+ query=optimized_query, limit=search_limit,
+ threshold=search_threshold, filter=doc_filter,
+ )
+ self.progress_callback(f"Found {len(chunks)} chunks")
+ for chunk in chunks:
+ selected_chunks[chunk.metadata["id"]] = chunk
+
+ if not selected_chunks:
+ 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
+
+ self.progress_callback(
+ f"Processing {len(questions)} questions in context of {len(selected_chunks)} chunks"
+ )
+ 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(
+ messages=[
+ SystemMessage(content=qa_system_message),
+ HumanMessage(content=qa_user_message),
+ ],
+ explicit_caching=False,
+ )
+ self.progress_callback(f"Q&A process completed")
+ return True, str(ai_response)
+
+ async def document_get_content(
+ self, document_uri: str, add_to_db: bool = False
+ ) -> str:
+ self.progress_callback(f"Fetching document content")
+ await self.agent.handle_intervention()
+ url = urlparse(document_uri)
+ scheme = url.scheme or "file"
+ mimetype, encoding = mimetypes.guess_type(document_uri)
+ mimetype = mimetype or "application/octet-stream"
+
+ if mimetype == "application/octet-stream":
+ if url.scheme in ["http", "https"]:
+ response = None
+ retries = 0
+ last_error = ""
+ while not response and retries < 3:
+ try:
+ async with aiohttp.ClientSession() as session:
+ response = await session.head(
+ document_uri,
+ timeout=aiohttp.ClientTimeout(total=2.0),
+ allow_redirects=True,
+ )
+ if response.status > 399:
+ raise Exception(response.status)
+ break
+ except Exception as e:
+ await asyncio.sleep(1)
+ last_error = str(e)
+ retries += 1
+ await self.agent.handle_intervention()
+ if not response:
+ raise ValueError(f"Document fetch error: {document_uri} ({last_error})")
+ mimetype = response.headers["content-type"]
+ if "content-length" in response.headers:
+ content_length = float(response.headers["content-length"]) / 1024 / 1024
+ if content_length > 50.0:
+ raise ValueError(f"Document exceeds max 50MB: {content_length} MB ({document_uri})")
+ if mimetype and "; charset=" in mimetype:
+ mimetype = mimetype.split("; charset=")[0]
+
+ if scheme == "file":
+ try:
+ document_uri = files.fix_dev_path(url.path)
+ except Exception as e:
+ raise ValueError(f"Invalid document path '{url.path}'") from e
+
+ if encoding:
+ raise ValueError(f"Compressed documents are unsupported '{encoding}' ({document_uri})")
+ if mimetype == "application/octet-stream":
+ raise ValueError(f"Unsupported document mimetype '{mimetype}' ({document_uri})")
+
+ document_uri_norm = self.store.normalize_uri(document_uri)
+ await self.agent.handle_intervention()
+ exists = await self.store.document_exists(document_uri_norm)
+ document_content = ""
+
+ if not exists:
+ await self.agent.handle_intervention()
+ parser = get_parser_for_mimetype(mimetype)
+ if parser is None:
+ raise ValueError(f"No parser found for mimetype '{mimetype}' ({document_uri})")
+ per_doc_timeout = self.config.get("per_document_timeout", 60)
+ thread_offload = self.config.get("thread_offload", True)
+ document_content = await parser.parse(
+ document_uri=document_uri, scheme=scheme,
+ timeout=per_doc_timeout, thread_offload=thread_offload,
+ )
+ if add_to_db:
+ self.progress_callback(f"Indexing document")
+ await self.agent.handle_intervention()
+ async with self.store_lock:
+ success, ids = await self.store.add_document(document_content, document_uri_norm)
+ if not success:
+ self.progress_callback(f"Failed to index document")
+ raise ValueError(f"Failed to index document: {document_uri_norm}")
+ self.progress_callback(f"Indexed {len(ids)} chunks")
+ else:
+ await self.agent.handle_intervention()
+ doc = await self.store.get_document(document_uri_norm)
+ if doc:
+ document_content = doc.page_content
+ else:
+ raise ValueError(f"Document not found: {document_uri_norm}")
+ return document_content
diff --git a/plugins/_document_query/helpers/parsers/__init__.py b/plugins/_document_query/helpers/parsers/__init__.py
new file mode 100644
index 000000000..5a4476c89
--- /dev/null
+++ b/plugins/_document_query/helpers/parsers/__init__.py
@@ -0,0 +1,17 @@
+"""Document parser registry."""
+from .base import BaseParser
+from .pdf import PdfParser
+from .html import HtmlParser
+from .text import TextParser
+from .image import ImageParser
+from .unstructured import UnstructuredParser
+
+_PARSERS = [PdfParser(), HtmlParser(), TextParser(), ImageParser(), UnstructuredParser()]
+
+def get_parser_for_mimetype(mimetype: str) -> BaseParser | None:
+ for parser in _PARSERS:
+ if parser.can_handle(mimetype):
+ return parser
+ return None
+
+__all__ = ["BaseParser", "PdfParser", "HtmlParser", "TextParser", "ImageParser", "UnstructuredParser", "get_parser_for_mimetype"]
diff --git a/plugins/_document_query/helpers/parsers/base.py b/plugins/_document_query/helpers/parsers/base.py
new file mode 100644
index 000000000..3e1211f03
--- /dev/null
+++ b/plugins/_document_query/helpers/parsers/base.py
@@ -0,0 +1,62 @@
+"""Base parser with built-in thread offload and timeout."""
+
+import asyncio
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from helpers.print_style import PrintStyle
+
+
+class BaseParser(ABC):
+ """Abstract base for document parsers.
+
+ Every parser runs synchronously but is automatically offloaded to a
+ thread pool and bounded by a configurable timeout when called through
+ parse(). This prevents any single parser from blocking the asyncio
+ event loop.
+ """
+
+ mimetypes: list[str] = []
+
+ def can_handle(self, mimetype: str) -> bool:
+ """Return True if this parser supports *mimetype*."""
+ for pattern in self.mimetypes:
+ if pattern == "*":
+ return True
+ if pattern.endswith("/"):
+ if mimetype.startswith(pattern):
+ return True
+ elif mimetype == pattern:
+ return True
+ return False
+
+ async def parse(
+ self,
+ document_uri: str,
+ scheme: str,
+ timeout: float = 60.0,
+ thread_offload: bool = True,
+ ) -> str:
+ try:
+ if thread_offload:
+ return await asyncio.wait_for(
+ asyncio.to_thread(self._parse_sync, document_uri, scheme),
+ timeout=timeout,
+ )
+ else:
+ return await asyncio.wait_for(
+ self._parse_async(document_uri, scheme),
+ timeout=timeout,
+ )
+ except asyncio.TimeoutError:
+ PrintStyle.error(
+ f"Parser {self.__class__.__name__} timed out after {timeout}s on {document_uri}"
+ )
+ raise ValueError(f"Document parsing timed out after {timeout}s: {document_uri}")
+
+ async def _parse_async(self, document_uri: str, scheme: str) -> str:
+ return self._parse_sync(document_uri, scheme)
+
+ @abstractmethod
+ def _parse_sync(self, document_uri: str, scheme: str) -> str:
+ ...
diff --git a/plugins/_document_query/helpers/parsers/html.py b/plugins/_document_query/helpers/parsers/html.py
new file mode 100644
index 000000000..12fdfed58
--- /dev/null
+++ b/plugins/_document_query/helpers/parsers/html.py
@@ -0,0 +1,22 @@
+"""HTML parser using Markdownify transformer."""
+
+from langchain_community.document_loaders import AsyncHtmlLoader
+from langchain_community.document_transformers import MarkdownifyTransformer
+from langchain_core.documents import Document
+
+from helpers import files
+from .base import BaseParser
+
+
+class HtmlParser(BaseParser):
+ mimetypes = ["text/html"]
+
+ def _parse_sync(self, document_uri: str, scheme: str) -> str:
+ if scheme in ["http", "https"]:
+ parts = AsyncHtmlLoader(web_path=document_uri).load()
+ elif scheme == "file":
+ content = files.read_file_bin(document_uri).decode("utf-8")
+ parts = [Document(page_content=content, metadata={"source": document_uri})]
+ else:
+ raise ValueError(f"Unsupported scheme: {scheme}")
+ return "\n".join(e.page_content for e in MarkdownifyTransformer().transform_documents(parts))
diff --git a/plugins/_document_query/helpers/parsers/image.py b/plugins/_document_query/helpers/parsers/image.py
new file mode 100644
index 000000000..aa564232e
--- /dev/null
+++ b/plugins/_document_query/helpers/parsers/image.py
@@ -0,0 +1,9 @@
+"""Image parser — delegates to UnstructuredLoader."""
+from .base import BaseParser
+from .unstructured import UnstructuredParser
+
+
+class ImageParser(BaseParser):
+ mimetypes = ["image/"]
+ def _parse_sync(self, document_uri: str, scheme: str) -> str:
+ return UnstructuredParser()._parse_sync(document_uri, scheme)
diff --git a/plugins/_document_query/helpers/parsers/pdf.py b/plugins/_document_query/helpers/parsers/pdf.py
new file mode 100644
index 000000000..613f58717
--- /dev/null
+++ b/plugins/_document_query/helpers/parsers/pdf.py
@@ -0,0 +1,63 @@
+"""PDF parser with PyMuPDF primary and Tesseract OCR fallback."""
+
+import os
+import tempfile
+
+from langchain_community.document_loaders.pdf import PyMuPDFLoader
+from langchain_community.document_loaders.parsers.images import TesseractBlobParser
+from langchain_core.documents import Document
+
+from helpers import files
+from helpers.print_style import PrintStyle
+
+from .base import BaseParser
+
+
+class PdfParser(BaseParser):
+ mimetypes = ["application/pdf"]
+
+ def _parse_sync(self, document_uri: str, scheme: str) -> str:
+ temp_file_path = ""
+ if scheme == "file":
+ file_content_bytes = files.read_file_bin(document_uri)
+ with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as f:
+ f.write(file_content_bytes)
+ temp_file_path = f.name
+ elif scheme in ["http", "https"]:
+ import requests
+ with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as f:
+ resp = requests.get(document_uri, timeout=10.0)
+ if resp.status_code != 200:
+ raise ValueError(f"Failed to download PDF: {resp.status_code}")
+ f.write(resp.content)
+ temp_file_path = f.name
+ else:
+ raise ValueError(f"Unsupported scheme: {scheme}")
+
+ if not os.path.exists(temp_file_path):
+ raise ValueError(f"Temporary file not found: {temp_file_path}")
+ try:
+ contents = self._parse_with_pymupdf(temp_file_path)
+ if not contents:
+ contents = self._parse_with_ocr(temp_file_path)
+ return contents
+ finally:
+ os.unlink(temp_file_path)
+
+ def _parse_with_pymupdf(self, file_path: str) -> str:
+ try:
+ loader = PyMuPDFLoader(
+ file_path, mode="single", extract_tables="markdown",
+ extract_images=True, images_inner_format="text",
+ images_parser=TesseractBlobParser(), pages_delimiter="\n",
+ )
+ return "\n".join(e.page_content for e in loader.load())
+ except Exception as e:
+ PrintStyle.error(f"PyMuPDF parsing failed: {e}")
+ return ""
+
+ def _parse_with_ocr(self, file_path: str) -> str:
+ import pdf2image, pytesseract
+ PrintStyle.debug(f"FALLBACK: OCR for {file_path}")
+ pages = pdf2image.convert_from_path(file_path)
+ return "\n\n".join(pytesseract.image_to_string(p) for p in pages)
diff --git a/plugins/_document_query/helpers/parsers/text.py b/plugins/_document_query/helpers/parsers/text.py
new file mode 100644
index 000000000..618735f07
--- /dev/null
+++ b/plugins/_document_query/helpers/parsers/text.py
@@ -0,0 +1,26 @@
+"""Plain text and config document parser."""
+
+from langchain_community.document_loaders import AsyncHtmlLoader
+from langchain_core.documents import Document
+
+from helpers import files
+from .base import BaseParser
+
+
+class TextParser(BaseParser):
+ mimetypes = [
+ "text/", "application/json", "application/yaml", "application/x-yaml",
+ "application/xml", "application/toml", "application/x-toml",
+ "application/javascript", "application/typescript",
+ "application/x-sh", "application/x-shellscript",
+ ]
+
+ def _parse_sync(self, document_uri: str, scheme: str) -> str:
+ if scheme in ["http", "https"]:
+ elements = AsyncHtmlLoader(web_path=document_uri).load()
+ elif scheme == "file":
+ content = files.read_file_bin(document_uri).decode("utf-8")
+ elements = [Document(page_content=content, metadata={"source": document_uri})]
+ else:
+ raise ValueError(f"Unsupported scheme: {scheme}")
+ return "\n".join(e.page_content for e in elements)
diff --git a/plugins/_document_query/helpers/parsers/unstructured.py b/plugins/_document_query/helpers/parsers/unstructured.py
new file mode 100644
index 000000000..8e72dad41
--- /dev/null
+++ b/plugins/_document_query/helpers/parsers/unstructured.py
@@ -0,0 +1,33 @@
+"""Catch-all parser using UnstructuredLoader."""
+
+import os
+import tempfile
+
+from helpers import files
+from .base import BaseParser
+
+os.environ.setdefault("USER_AGENT", "@mixedbread-ai/unstructured")
+from langchain_unstructured import UnstructuredLoader
+
+
+class UnstructuredParser(BaseParser):
+ mimetypes = ["*"]
+
+ def _parse_sync(self, document_uri: str, scheme: str) -> str:
+ if scheme in ["http", "https"]:
+ loader = UnstructuredLoader(web_url=document_uri, mode="single", partition_via_api=False, strategy="hi_res")
+ elements = loader.load()
+ elif scheme == "file":
+ content = files.read_file_bin(document_uri)
+ _, ext = os.path.splitext(document_uri)
+ with tempfile.NamedTemporaryFile(delete=False, suffix=ext) as f:
+ f.write(content)
+ tmp = f.name
+ try:
+ loader = UnstructuredLoader(file_path=tmp, mode="single", partition_via_api=False, strategy="hi_res")
+ elements = loader.load()
+ finally:
+ if os.path.exists(tmp): os.unlink(tmp)
+ else:
+ raise ValueError(f"Unsupported scheme: {scheme}")
+ return "\n".join(e.page_content for e in elements)
diff --git a/plugins/_document_query/plugin.yaml b/plugins/_document_query/plugin.yaml
new file mode 100644
index 000000000..d6b9d9f7e
--- /dev/null
+++ b/plugins/_document_query/plugin.yaml
@@ -0,0 +1,8 @@
+name: _document_query
+title: Document Query
+description: Load, parse, index, and Q&A over local and remote documents with configurable timeouts and thread-safe parsers.
+version: 1.0.0
+settings_sections:
+ - agent
+per_project_config: true
+per_agent_config: false
diff --git a/plugins/_document_query/prompts/agent.system.tool.document_query.md b/plugins/_document_query/prompts/agent.system.tool.document_query.md
new file mode 100644
index 000000000..4d2850d87
--- /dev/null
+++ b/plugins/_document_query/prompts/agent.system.tool.document_query.md
@@ -0,0 +1,8 @@
+### document_query
+read local or remote documents or answer questions about them
+args:
+- `document`: url path or list of them
+- `queries`: optional list of questions
+- `query`: optional single-question alias
+without `query` or `queries` it returns document content
+for local files use full path; for web documents use full urls
diff --git a/prompts/fw.document_query.optmimize_query.md b/plugins/_document_query/prompts/fw.document_query.optmimize_query.md
similarity index 100%
rename from prompts/fw.document_query.optmimize_query.md
rename to plugins/_document_query/prompts/fw.document_query.optmimize_query.md
diff --git a/prompts/fw.document_query.system_prompt.md b/plugins/_document_query/prompts/fw.document_query.system_prompt.md
similarity index 100%
rename from prompts/fw.document_query.system_prompt.md
rename to plugins/_document_query/prompts/fw.document_query.system_prompt.md
diff --git a/plugins/_document_query/tools/document_query.py b/plugins/_document_query/tools/document_query.py
new file mode 100644
index 000000000..5a37bcbf2
--- /dev/null
+++ b/plugins/_document_query/tools/document_query.py
@@ -0,0 +1,55 @@
+import asyncio
+
+from helpers.tool import Tool, Response
+from plugins._document_query.helpers.document_query import DocumentQueryHelper
+
+
+class DocumentQueryTool(Tool):
+
+ async def execute(self, **kwargs):
+ document_uri = kwargs.get("document")
+ document_uris = []
+
+ if isinstance(document_uri, list):
+ document_uris = document_uri
+ elif isinstance(document_uri, str):
+ document_uris = [document_uri]
+
+ if not document_uris:
+ return Response(message="Error: no document provided", break_loop=False)
+
+ queries = (
+ kwargs["queries"]
+ if "queries" in kwargs
+ else [kwargs["query"]]
+ if ("query" in kwargs and kwargs["query"])
+ else []
+ )
+ try:
+ progress = []
+
+ def progress_callback(msg):
+ progress.append(msg)
+ self.log.update(progress="\n".join(progress))
+
+ helper = DocumentQueryHelper(self.agent, progress_callback)
+ if not queries:
+ gather_timeout = helper.config.get("gather_timeout", 120)
+ try:
+ contents = await asyncio.wait_for(
+ asyncio.gather(
+ *[helper.document_get_content(uri) for uri in document_uris]
+ ),
+ timeout=gather_timeout,
+ )
+ except asyncio.TimeoutError:
+ return Response(
+ message=f"Error: document processing timed out after {gather_timeout}s",
+ break_loop=False,
+ )
+ content = "\n\n---\n\n".join(contents)
+ else:
+ _, content = await helper.document_qa(document_uris, queries)
+ return Response(message=content, break_loop=False)
+ except Exception as e: # pylint: disable=broad-exception-caught
+ return Response(message=f"Error processing document: {e}", break_loop=False)
diff --git a/prompts/agent.system.tool.document_query.md b/prompts/agent.system.tool.document_query._md.bak
similarity index 100%
rename from prompts/agent.system.tool.document_query.md
rename to prompts/agent.system.tool.document_query._md.bak
diff --git a/prompts/fw.document_query.optmimize_query._md.bak b/prompts/fw.document_query.optmimize_query._md.bak
new file mode 100644
index 000000000..7251a14b4
--- /dev/null
+++ b/prompts/fw.document_query.optmimize_query._md.bak
@@ -0,0 +1,28 @@
+# AI role
+- You are an AI assistant being part of a larger RAG system based on vector similarity search
+- Your job is to take a human written question and convert it into a concise vector store search query
+- The goal is to yield as many correct results and as few false positives as possible
+
+# Input
+- you are provided with original search query as user message
+
+# Response rules !!!
+- respond only with optimized result query text
+- no text before or after
+- no conversation, you are a tool agent, not a conversational agent
+
+# Optimized query
+- optimized query is consise, short and to the point
+- contains only keywords and phrases, no full sentences
+- include alternatives and variations for better coverage
+
+
+# Examples
+User: What is the capital of France?
+Agent: france capital city
+
+User: What does it say about transmission?
+Agent: transmission gearbox automatic manual
+
+User: What did John ask Monica on Tuesday?
+Agent: john monica conversation dialogue question ask tuesday
diff --git a/prompts/fw.document_query.system_prompt._md.bak b/prompts/fw.document_query.system_prompt._md.bak
new file mode 100644
index 000000000..f8b3b0722
--- /dev/null
+++ b/prompts/fw.document_query.system_prompt._md.bak
@@ -0,0 +1,5 @@
+You are an AI assistant who can answer questions about a given document text.
+The assistant is part of a larger application that is used to answer questions about a document.
+The assistant is given a document and a list of queries and the assistant must answer the quries based on the document.
+!! The response should be in markdown format.
+!! The response should only include the queries as headings and the answers to the queries. The markdown should contain paragraphs with "#### <Query>" as headings (<Query> being the original query) followed by the query answer as the paragraph text content.
diff --git a/tools/document_query.py b/tools/document_query._py.bak
similarity index 100%
rename from tools/document_query.py
rename to tools/document_query._py.bak
diff --git a/tools/knowledge_tool._py b/tools/knowledge_tool._py
index 8102eb848..ac0dde3e9 100644
--- a/tools/knowledge_tool._py
+++ b/tools/knowledge_tool._py
@@ -4,7 +4,7 @@ from plugins._memory.helpers.memory import Memory
from plugins._memory.tools.memory_load import DEFAULT_THRESHOLD as DEFAULT_MEMORY_THRESHOLD
from helpers.tool import Tool, Response
-from helpers.document_query import DocumentQueryHelper
+from plugins._document_query.helpers.document_query import DocumentQueryHelper
SEARCH_ENGINE_RESULTS = 10