Chris CoutinhoandClaude Opus 4.8
b779627fa6
Remaining items from the PR #831 Claude review: - processor span symmetry: add "vector_sync.total_chars" to the sparse embedding span (already on the dense span) and drop the redundant "embedding.batch_size" attribute from both spans — it always equalled vector_sync.chunk_count and would mislead once batching is split. - metrics: document the deliberate "throughput counts only on full success" contract in record_document_parse (partial extractions flagged success=False are counted as a parse-error but never inflate pages/chars/bytes throughput). - config: extract _detect_base_provider() -> (family, model) as the single source of truth for the provider-detection priority chain, shared by get_embedding_model_name() and get_embedding_provider_family(). Preserves the intentional gateway asymmetry (only the family method short-circuits). - base.py: Optional[...] -> PEP 604 `... | None`; drop now-unused import. Behavior unchanged (get_embedding_* outputs covered by test_config.py). Refs Deck #175, PR #831. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
139 lines
4.3 KiB
Python
139 lines
4.3 KiB
Python
"""Abstract base class for document processing plugins."""
|
|
|
|
from abc import ABC, abstractmethod
|
|
from collections.abc import Awaitable, Callable
|
|
from typing import Any
|
|
|
|
from pydantic import BaseModel
|
|
|
|
|
|
class ProcessingResult(BaseModel):
|
|
"""Standardized result from any document processor."""
|
|
|
|
text: str
|
|
"""Extracted text content"""
|
|
|
|
metadata: dict[str, Any]
|
|
"""Processor-specific metadata"""
|
|
|
|
processor: str
|
|
"""Name of processor that handled this (e.g., 'unstructured', 'tesseract')"""
|
|
|
|
success: bool = True
|
|
"""Whether processing succeeded"""
|
|
|
|
error: str | None = None
|
|
"""Error message if processing failed"""
|
|
|
|
|
|
class DocumentProcessor(ABC):
|
|
"""Abstract base class for document processing plugins.
|
|
|
|
Document processors extract text from various file formats (PDF, DOCX, images, etc.).
|
|
Each processor implements this interface and can be registered with the ProcessorRegistry.
|
|
|
|
Example:
|
|
class MyProcessor(DocumentProcessor):
|
|
@property
|
|
def name(self) -> str:
|
|
return "my_processor"
|
|
|
|
@property
|
|
def supported_mime_types(self) -> set[str]:
|
|
return {"application/pdf", "image/jpeg"}
|
|
|
|
async def process(self, content: bytes, content_type: str, **kwargs) -> ProcessingResult:
|
|
# Extract text from content
|
|
return ProcessingResult(text="...", metadata={}, processor=self.name)
|
|
|
|
async def health_check(self) -> bool:
|
|
return True
|
|
"""
|
|
|
|
@property
|
|
@abstractmethod
|
|
def name(self) -> str:
|
|
"""Unique identifier for this processor (e.g., 'unstructured', 'tesseract')."""
|
|
pass
|
|
|
|
@property
|
|
def tier(self) -> str:
|
|
"""Extraction tier this processor belongs to (escalation ladder).
|
|
|
|
Used as the ``tier`` label/attribute in observability so that adding new
|
|
extraction tiers later (docling, OCR, LLM) is purely additive. Vocabulary
|
|
(cheapest first): ``fast`` -> ``structured`` -> ``ocr`` -> ``llm``.
|
|
|
|
Defaults to ``"fast"``; override in processors that belong to a higher
|
|
tier.
|
|
"""
|
|
return "fast"
|
|
|
|
@property
|
|
@abstractmethod
|
|
def supported_mime_types(self) -> set[str]:
|
|
"""Set of MIME types this processor can handle.
|
|
|
|
Examples: {"application/pdf", "image/jpeg", "image/png"}
|
|
"""
|
|
pass
|
|
|
|
@abstractmethod
|
|
async def process(
|
|
self,
|
|
content: bytes,
|
|
content_type: str,
|
|
filename: str | None = None,
|
|
options: dict[str, Any] | None = None,
|
|
progress_callback: Callable[[float, float | None, str | None], Awaitable[None]]
|
|
| None = None,
|
|
) -> ProcessingResult:
|
|
"""Process a document and extract text.
|
|
|
|
Args:
|
|
content: Document bytes
|
|
content_type: MIME type of the document
|
|
filename: Optional filename for format detection
|
|
options: Processor-specific options (e.g., OCR language, strategy)
|
|
progress_callback: Optional async callback for progress updates.
|
|
Called as: await progress_callback(progress, total, message)
|
|
- progress: Current progress value (monotonically increasing)
|
|
- total: Optional total value (None if unknown)
|
|
- message: Optional human-readable status message
|
|
|
|
Returns:
|
|
ProcessingResult with extracted text and metadata
|
|
|
|
Raises:
|
|
ProcessorError: If processing fails
|
|
"""
|
|
pass
|
|
|
|
@abstractmethod
|
|
async def health_check(self) -> bool:
|
|
"""Check if processor is available and healthy.
|
|
|
|
Returns:
|
|
True if processor is ready to use, False otherwise
|
|
"""
|
|
pass
|
|
|
|
def supports(self, content_type: str) -> bool:
|
|
"""Check if this processor supports the given MIME type.
|
|
|
|
Args:
|
|
content_type: MIME type (may include parameters like "application/pdf; charset=utf-8")
|
|
|
|
Returns:
|
|
True if this processor can handle the type
|
|
"""
|
|
# Strip parameters from content type
|
|
base_type = content_type.split(";")[0].strip().lower()
|
|
return base_type in self.supported_mime_types
|
|
|
|
|
|
class ProcessorError(Exception):
|
|
"""Raised when document processing fails."""
|
|
|
|
pass
|