feat: Metadata as input for MistalOCRDocumentConverter (#2457)

Hansehart · anakin87 · web-flow · commit 347781af80b4 · 2025-10-27T12:35:43.000+01:00
* Revise MCPTool usage example for Streamable HTTP Updated example usage in MCPTool documentation to reflect Streamable HTTP usage and mentioned deprecated SSE. * Clarify connection types in MCPToolset documentation Updated documentation to reflect changes in connection types for MCPToolset. * fix: Align with hatch run fmt requirements * add: MistralOCRDocumentConverter * add: project files * fix: example lib usage * move: ocr document converter into child /mistral * add: example usage with annotations * add: hatch run fmt * add: mistralai * fix: python3.9 compatibility with using Union, List, Optional * add: new comments and their position * add: moved schemas from init into run to bypass problems with serializing * add: docstring convention * add: process mutliple documents * add: robust api handling with catching mistral errors * add: Union[str, Path, ByteStream] as input * add: comment for new inputs * add: pipeline example * fix: example ocr component * fix: mistral file upload and pydantic v2 models * add: pipeline example * add: hint on document annotation page limit * add: mistralai as project dependency * fix: hatch run fmt * fix: hatch run docs * add: exlcuse mistral from compliance workflow (its apache 2.0) * add: 3 initialization tests * add: 4 se test * add: test w/ proper mocking * add: real api test when env is set * add: delete files by default from mistral if uploaded * fix: mock file deletion * fix: hatch run fmt * Apply suggestion from @anakin87 Co-authored-by: Stefano Fiorucci <stefanofiorucci@gmail.com> * Update integrations/mistral/src/haystack_integrations/components/converters/mistral/ocr_document_converter.py Co-authored-by: Stefano Fiorucci <stefanofiorucci@gmail.com> * fix: nested try excepts * add: mention file upload * Update integrations/mistral/tests/test_ocr_document_converter.py Co-authored-by: Stefano Fiorucci <stefanofiorucci@gmail.com> * Update integrations/mistral/tests/test_ocr_document_converter.py Co-authored-by: Stefano Fiorucci <stefanofiorucci@gmail.com> * add: less test code due to pytest.mark..parametrize * add: less tests and const class type * fix: format * add: ocr document converter to docusaurus * add: converter to mistral * add: metadata handling in run method following other converters * fix(mistral): hatch run fmt * Update integrations/mistral/src/haystack_integrations/components/converters/mistral/ocr_document_converter.py Co-authored-by: Stefano Fiorucci <stefanofiorucci@gmail.com> --------- Co-authored-by: Stefano Fiorucci <stefanofiorucci@gmail.com>
diff --git a/integrations/mistral/src/haystack_integrations/components/converters/mistral/ocr_document_converter.py b/integrations/mistral/src/haystack_integrations/components/converters/mistral/ocr_document_converter.py
@@ -4,7 +4,10 @@
 from typing import Any, Dict, List, Optional, Type, Union
 
 from haystack import Document, component, default_from_dict, default_to_dict, logging
-from haystack.components.converters.utils import get_bytestream_from_source
+from haystack.components.converters.utils import (
+    get_bytestream_from_source,
+    normalize_metadata,
+)
 from haystack.dataclasses import ByteStream
 from haystack.utils import Secret, deserialize_secrets_inplace
 from mistralai import Mistral
@@ -173,6 +176,7 @@ def from_dict(cls, data: Dict[str, Any]) -> "MistralOCRDocumentConverter":
     def run(
         self,
         sources: List[Union[str, Path, ByteStream, DocumentURLChunk, FileChunk, ImageURLChunk]],
+        meta: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = None,
         bbox_annotation_schema: Optional[Type[BaseModel]] = None,
         document_annotation_schema: Optional[Type[BaseModel]] = None,
     ) -> Dict[str, Any]:
@@ -187,6 +191,11 @@ def run(
             - DocumentURLChunk: Mistral chunk for document URLs (signed or public URLs to PDFs, etc.)
             - ImageURLChunk: Mistral chunk for image URLs (signed or public URLs to images)
             - FileChunk: Mistral chunk for file IDs (files previously uploaded to Mistral)
+        :param meta:
+            Optional metadata to attach to the Documents.
+            This value can be either a list of dictionaries or a single dictionary.
+            If it's a single dictionary, its content is added to the metadata of all produced Documents.
+            If it's a list, the length of the list must match the number of sources, because they will be zipped.
         :param bbox_annotation_schema:
             Optional Pydantic model for structured annotations per bounding box.
             When provided, a Vision LLM analyzes each image region and returns structured data.
@@ -217,14 +226,18 @@ def run(
             response_format_from_pydantic_model(document_annotation_schema) if document_annotation_schema else None
         )
 
+        # Normalize metadata
+        meta_list = normalize_metadata(meta, sources_count=len(sources))
+
         # Process each source
         documents = []
         raw_responses = []
         uploaded_file_ids = []
 
-        for source in sources:
+        for source, user_metadata in zip(sources, meta_list):
             document, raw_response, uploaded_file_id = self._process_single_source(
                 source,
+                user_metadata,
                 bbox_annotation_format,
                 document_annotation_format,
                 document_annotation_schema,
@@ -247,6 +260,7 @@ def run(
     def _process_single_source(
         self,
         source: Union[str, Path, ByteStream, DocumentURLChunk, FileChunk, ImageURLChunk],
+        user_metadata: Dict[str, Any],
         bbox_annotation_format: Optional[Any],
         document_annotation_format: Optional[Any],
         document_annotation_schema: Optional[Type[BaseModel]],
@@ -256,6 +270,8 @@ def _process_single_source(
 
         :param source:
             The source to process.
+        :param user_metadata:
+            User-provided metadata to attach to the document.
         :param bbox_annotation_format:
             Optional response format for bounding box annotations.
         :param document_annotation_format:
@@ -286,7 +302,7 @@ def _process_single_source(
                 document_annotation_format=document_annotation_format,
             )
 
-            document = self._process_ocr_response(ocr_response, document_annotation_schema)
+            document = self._process_ocr_response(ocr_response, user_metadata, document_annotation_schema)
             return (document, ocr_response.model_dump(), uploaded_file_id)
         except Exception as e:
             logger.warning(
@@ -354,13 +370,16 @@ def _convert_source_to_chunk(
     def _process_ocr_response(
         self,
         ocr_response: OCRResponse,
+        user_metadata: Dict[str, Any],
         document_annotation_schema: Optional[Type[BaseModel]],
     ) -> Document:
         """
         Convert an OCR response from Mistral API into a single Haystack Document.
 
         :param ocr_response:
             The OCR response object from Mistral API.
+        :param user_metadata:
+            User-provided metadata to attach to the document.
         :param document_annotation_schema:
             Optional Pydantic model for document-level annotations.
 
@@ -402,9 +421,12 @@ def _process_ocr_response(
         document = Document(
             content=all_content,
             meta={
+                # User metadata (lowest priority - can be overridden)
+                **user_metadata,
+                # Automatic metadata (medium priority)
                 "source_page_count": len(ocr_response.pages),
                 "source_total_images": total_images,
-                # Unpack document annotation
+                # Document annotation (highest priority - overrides all)
                 **doc_annotation_meta,
             },
         )
diff --git a/integrations/mistral/tests/test_ocr_document_converter.py b/integrations/mistral/tests/test_ocr_document_converter.py
@@ -419,12 +419,84 @@ def test_run_handles_api_error(self, mock_ocr_response):
             assert len(result["documents"]) == 2
             assert len(result["raw_mistral_response"]) == 2
 
+    def test_run_with_meta_single_dict(self, mock_ocr_response):
+        """Test that meta parameter with single dict is applied to all documents"""
+        converter = MistralOCRDocumentConverter(api_key=Secret.from_token("test-api-key"))
+
+        with patch.object(converter.client.ocr, "process", return_value=mock_ocr_response):
+            sources = [
+                DocumentURLChunk(document_url="https://example.com/doc1.pdf"),
+                DocumentURLChunk(document_url="https://example.com/doc2.pdf"),
+            ]
+            result = converter.run(sources=sources, meta={"department": "engineering", "year": 2024})
+
+            assert len(result["documents"]) == 2
+            # Both documents should have the same metadata
+            for doc in result["documents"]:
+                assert doc.meta["department"] == "engineering"
+                assert doc.meta["year"] == 2024
+                # Automatic metadata should still be present
+                assert "source_page_count" in doc.meta
+                assert "source_total_images" in doc.meta
+
+    def test_run_with_meta_list_of_dicts(self, mock_ocr_response):
+        """Test that meta parameter with list of dicts applies each dict to corresponding document"""
+        converter = MistralOCRDocumentConverter(api_key=Secret.from_token("test-api-key"))
+
+        with patch.object(converter.client.ocr, "process", return_value=mock_ocr_response):
+            sources = [
+                DocumentURLChunk(document_url="https://example.com/doc1.pdf"),
+                DocumentURLChunk(document_url="https://example.com/doc2.pdf"),
+            ]
+            result = converter.run(
+                sources=sources,
+                meta=[
+                    {"author": "Alice", "category": "report"},
+                    {"author": "Bob", "category": "invoice"},
+                ],
+            )
+
+            assert len(result["documents"]) == 2
+            # First document
+            assert result["documents"][0].meta["author"] == "Alice"
+            assert result["documents"][0].meta["category"] == "report"
+            # Second document
+            assert result["documents"][1].meta["author"] == "Bob"
+            assert result["documents"][1].meta["category"] == "invoice"
+            # Automatic metadata should still be present in both
+            assert "source_page_count" in result["documents"][0].meta
+            assert "source_page_count" in result["documents"][1].meta
+
+    def test_run_with_meta_none(self, mock_ocr_response):
+        """Test that meta parameter with None works correctly"""
+        converter = MistralOCRDocumentConverter(api_key=Secret.from_token("test-api-key"))
+
+        with patch.object(converter.client.ocr, "process", return_value=mock_ocr_response):
+            sources = [DocumentURLChunk(document_url="https://example.com/doc.pdf")]
+            result = converter.run(sources=sources, meta=None)
+
+            assert len(result["documents"]) == 1
+            # Only automatic metadata should be present
+            assert "source_page_count" in result["documents"][0].meta
+            assert "source_total_images" in result["documents"][0].meta
+
+    def test_run_with_meta_list_length_mismatch(self):
+        """Test that meta parameter with list length mismatch raises ValueError"""
+        converter = MistralOCRDocumentConverter(api_key=Secret.from_token("test-api-key"))
+
+        with pytest.raises(ValueError, match="length of the metadata list must match"):
+            sources = [
+                DocumentURLChunk(document_url="https://example.com/doc1.pdf"),
+                DocumentURLChunk(document_url="https://example.com/doc2.pdf"),
+            ]
+            converter.run(sources=sources, meta=[{"author": "Alice"}])  # Only 1 dict for 2 sources
+
     def test_process_ocr_response_multiple_pages(self, mock_ocr_response_with_multiple_pages):
         """Test multi-page document with form feed separator"""
         converter = MistralOCRDocumentConverter(api_key=Secret.from_token("test-api-key"))
 
         document = converter._process_ocr_response(
-            mock_ocr_response_with_multiple_pages, document_annotation_schema=None
+            mock_ocr_response_with_multiple_pages, user_metadata={}, document_annotation_schema=None
         )
 
         assert isinstance(document, Document)
@@ -454,7 +526,7 @@ def test_process_ocr_response_with_images(self):
         mock_response.pages = [mock_page]
         mock_response.document_annotation = None
 
-        document = converter._process_ocr_response(mock_response, document_annotation_schema=None)
+        document = converter._process_ocr_response(mock_response, user_metadata={}, document_annotation_schema=None)
 
         assert document.meta["source_page_count"] == 1
         assert document.meta["source_total_images"] == 2
