refactor: Transform document parsing into pluggable processor architecture
Refactors PR #190's hardcoded Unstructured.io integration into a flexible, extensible plugin system supporting multiple text extraction engines. - **`DocumentProcessor` ABC**: Abstract interface for all processors - **`ProcessorRegistry`**: Central registry for discovery and routing - **`ProcessingResult`**: Standardized output format across processors - **`UnstructuredProcessor`**: Refactored from `UnstructuredClient` - **`TesseractProcessor`**: Local OCR for images (lightweight alternative) - **`CustomHTTPProcessor`**: Generic wrapper for custom HTTP APIs - New `get_document_processor_config()` returns structured config - Supports enabling/disabling individual processors - Per-processor configuration via environment variables - **Breaking Change**: `ENABLE_UNSTRUCTURED_PARSING` replaced with: - `ENABLE_DOCUMENT_PROCESSING=true/false` (master switch) - `ENABLE_UNSTRUCTURED=true/false` (per-processor) - `ENABLE_TESSERACT=true/false` - `ENABLE_CUSTOM_PROCESSOR=true/false` - `parse_document()` now uses `ProcessorRegistry` - Auto-selects appropriate processor based on MIME type - Processor priority system (Unstructured=10, Tesseract=5, Custom=1) - `initialize_document_processors()` registers processors at startup - Integrated into both BasicAuth and OAuth lifespans - Graceful degradation if processors fail to initialize ```env ENABLE_DOCUMENT_PROCESSING=false ENABLE_UNSTRUCTURED=false UNSTRUCTURED_API_URL=http://unstructured:8000 UNSTRUCTURED_STRATEGY=auto # auto|fast|hi_res UNSTRUCTURED_LANGUAGES=eng,deu ENABLE_TESSERACT=false TESSERACT_LANG=eng ENABLE_CUSTOM_PROCESSOR=false CUSTOM_PROCESSOR_URL=http://localhost:9000/process CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg ``` - **Removed**: `tests/test_unstructured_config.py` (legacy tests) - **Added**: `tests/unit/test_document_processor_config.py` - 7 unit tests for new config system - Tests individual and multi-processor configurations - **Added**: - `nextcloud_mcp_server/document_processors/__init__.py` - `nextcloud_mcp_server/document_processors/base.py` - `nextcloud_mcp_server/document_processors/registry.py` - `nextcloud_mcp_server/document_processors/unstructured.py` - `nextcloud_mcp_server/document_processors/tesseract.py` - `nextcloud_mcp_server/document_processors/custom_http.py` - `tests/unit/test_document_processor_config.py` - **Modified**: - `nextcloud_mcp_server/config.py` - New plugin config system - `nextcloud_mcp_server/app.py` - Processor initialization - `nextcloud_mcp_server/utils/document_parser.py` - Uses registry - `nextcloud_mcp_server/server/webdav.py` - Import updates - `env.sample` - New configuration format - `docker-compose.yml` - (profile changes from previous work) - **Removed**: - `nextcloud_mcp_server/client/unstructured_client.py` - Replaced by UnstructuredProcessor - `tests/test_unstructured_config.py` - Replaced with new tests ✅ **Extensible**: Add processors without modifying core code ✅ **Testable**: Mock processors for unit tests ✅ **Configurable**: Enable only needed processors ✅ **Flexible**: Choose fast (Tesseract) vs accurate (Unstructured) ✅ **Opt-in**: Disabled by default, no mandatory dependencies Users upgrading from PR #190 need to update environment variables: ```bash ENABLE_UNSTRUCTURED_PARSING=true ENABLE_DOCUMENT_PROCESSING=true ENABLE_UNSTRUCTURED=true ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
@@ -1,170 +0,0 @@
|
||||
"""HTTP client for Unstructured API."""
|
||||
|
||||
import io
|
||||
import logging
|
||||
from typing import Optional, Tuple
|
||||
|
||||
import httpx
|
||||
|
||||
from nextcloud_mcp_server.config import (
|
||||
get_unstructured_api_url,
|
||||
get_unstructured_languages,
|
||||
get_unstructured_strategy,
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class UnstructuredClient:
|
||||
"""Client for interacting with the Unstructured API.
|
||||
|
||||
The Unstructured API provides document parsing capabilities for various formats
|
||||
including PDF, DOCX, images with OCR, and more.
|
||||
|
||||
API Documentation: https://docs.unstructured.io/api-reference/api-services/api-parameters
|
||||
"""
|
||||
|
||||
def __init__(self, api_url: Optional[str] = None, timeout: int = 120):
|
||||
"""Initialize the Unstructured API client.
|
||||
|
||||
Args:
|
||||
api_url: Base URL of the Unstructured API. If None, will use config.
|
||||
timeout: Request timeout in seconds (default: 120 for large documents)
|
||||
"""
|
||||
self.api_url = api_url or get_unstructured_api_url()
|
||||
self.timeout = timeout
|
||||
|
||||
if not self.api_url:
|
||||
raise ValueError(
|
||||
"Unstructured API URL not configured. "
|
||||
"Set ENABLE_UNSTRUCTURED_PARSING=true and UNSTRUCTURED_API_URL in environment."
|
||||
)
|
||||
|
||||
logger.info(f"Initialized UnstructuredClient with API URL: {self.api_url}")
|
||||
|
||||
async def partition_document(
|
||||
self,
|
||||
content: bytes,
|
||||
filename: str,
|
||||
content_type: Optional[str] = None,
|
||||
strategy: Optional[str] = None,
|
||||
languages: Optional[list[str]] = None,
|
||||
extract_image_block_types: Optional[list[str]] = None,
|
||||
) -> Tuple[str, dict]:
|
||||
"""Parse a document using the Unstructured API.
|
||||
|
||||
Args:
|
||||
content: The document content as bytes
|
||||
filename: The filename (used for format detection)
|
||||
content_type: Optional MIME type
|
||||
strategy: Parsing strategy - "auto", "fast", or "hi_res" (OCR-based).
|
||||
If None, uses the value from UNSTRUCTURED_STRATEGY env var.
|
||||
languages: List of language codes for OCR (e.g., ["eng", "deu"]).
|
||||
If None, uses the value from UNSTRUCTURED_LANGUAGES env var.
|
||||
extract_image_block_types: Types of elements to extract from images
|
||||
|
||||
Returns:
|
||||
Tuple of (parsed_text, metadata) where:
|
||||
- parsed_text: The extracted text content
|
||||
- metadata: Additional metadata about the parsing
|
||||
|
||||
Raises:
|
||||
httpx.HTTPError: If the API request fails
|
||||
Exception: If parsing fails
|
||||
"""
|
||||
# Use environment configuration as defaults
|
||||
if strategy is None:
|
||||
strategy = get_unstructured_strategy()
|
||||
|
||||
if languages is None:
|
||||
languages = get_unstructured_languages()
|
||||
|
||||
# Prepare the multipart form data
|
||||
files = {
|
||||
"files": (
|
||||
filename,
|
||||
io.BytesIO(content),
|
||||
content_type or "application/octet-stream",
|
||||
)
|
||||
}
|
||||
|
||||
# Prepare the request data
|
||||
data = {
|
||||
"strategy": strategy,
|
||||
"languages": ",".join(languages),
|
||||
}
|
||||
|
||||
if extract_image_block_types:
|
||||
data["extract_image_block_types"] = ",".join(extract_image_block_types)
|
||||
|
||||
logger.debug(
|
||||
f"Partitioning document '{filename}' with strategy '{strategy}', "
|
||||
f"languages: {languages}"
|
||||
)
|
||||
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=self.timeout) as client:
|
||||
response = await client.post(
|
||||
f"{self.api_url}/general/v0/general",
|
||||
files=files,
|
||||
data=data,
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
# Parse the response
|
||||
elements = response.json()
|
||||
|
||||
# Extract text from elements
|
||||
# Each element has a "text" field
|
||||
texts = []
|
||||
element_types = {}
|
||||
|
||||
for element in elements:
|
||||
if "text" in element and element["text"]:
|
||||
texts.append(element["text"])
|
||||
|
||||
# Track element types
|
||||
el_type = element.get("type", "unknown")
|
||||
element_types[el_type] = element_types.get(el_type, 0) + 1
|
||||
|
||||
parsed_text = "\n\n".join(texts)
|
||||
|
||||
# Collect metadata
|
||||
metadata = {
|
||||
"element_count": len(elements),
|
||||
"text_length": len(parsed_text),
|
||||
"element_types": element_types,
|
||||
"strategy": strategy,
|
||||
"languages": languages,
|
||||
"parsing_method": "unstructured_api",
|
||||
}
|
||||
|
||||
logger.debug(
|
||||
f"Successfully parsed document: {len(elements)} elements, "
|
||||
f"{len(parsed_text)} characters"
|
||||
)
|
||||
|
||||
return parsed_text, metadata
|
||||
|
||||
except httpx.HTTPError as e:
|
||||
logger.error(f"HTTP error calling Unstructured API: {e}")
|
||||
raise Exception(
|
||||
f"Failed to parse document via Unstructured API: {str(e)}"
|
||||
) from e
|
||||
except Exception as e:
|
||||
logger.error(f"Unexpected error parsing document: {e}")
|
||||
raise Exception(f"Failed to parse document: {str(e)}") from e
|
||||
|
||||
async def health_check(self) -> bool:
|
||||
"""Check if the Unstructured API is available.
|
||||
|
||||
Returns:
|
||||
True if the API is healthy, False otherwise.
|
||||
"""
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=5) as client:
|
||||
response = await client.get(f"{self.api_url}/healthcheck")
|
||||
return response.status_code == 200
|
||||
except Exception as e:
|
||||
logger.warning(f"Unstructured API health check failed: {e}")
|
||||
return False
|
||||
Reference in New Issue
Block a user