fix: render PDF pages for vision extraction

Author: Florian Wunderlich

models/ai_document.py

@@ -5,6 +5,7 @@
 These are not Odoo models — they are imported by account_move.py.
 """
 
+import base64
 import io
 import logging
 import re
@@ -44,6 +45,17 @@
     _pdfplumber = None
     PDFPLUMBER_AVAILABLE = False
 
+# ---------------------------------------------------------------------------
+# PyMuPDF -- optional dependency for rendering PDF pages in vision mode
+# ---------------------------------------------------------------------------
+try:
+    import fitz as _fitz
+
+    PYMUPDF_AVAILABLE = True
+except ImportError:
+    _fitz = None
+    PYMUPDF_AVAILABLE = False
+
 # ---------------------------------------------------------------------------
 # Supported image MIME types for vision mode
 # ---------------------------------------------------------------------------
@@ -82,6 +94,39 @@ def is_image(mimetype):
     return mimetype in IMAGE_MIMES
 
 
+def render_pdf_pages_for_vision(pdf_bytes, max_pages=3, dpi=144):
+    """Render PDF pages to PNG images for vision-capable AI providers.
+
+    Returns a list of base64-encoded image payloads suitable for ``user_content``
+    image blocks. Empty list means rendering is unavailable or failed.
+    """
+    if not PYMUPDF_AVAILABLE or _fitz is None:
+        _logger.warning('No PDF renderer available for vision mode (PyMuPDF not installed)')
+        return []
+
+    doc = None
+    try:
+        doc = _fitz.open(stream=pdf_bytes, filetype='pdf')
+        matrix = _fitz.Matrix(dpi / 72.0, dpi / 72.0)
+        rendered_pages = []
+        for page_index in range(min(doc.page_count, max_pages)):
+            page = doc.load_page(page_index)
+            pixmap = page.get_pixmap(matrix=matrix, alpha=False)
+            rendered_pages.append(
+                {
+                    'media_type': 'image/png',
+                    'data': base64.b64encode(pixmap.tobytes('png')).decode('ascii'),
+                }
+            )
+        return rendered_pages
+    except Exception:
+        _logger.exception('Failed to render PDF pages for vision mode')
+        return []
+    finally:
+        if doc is not None:
+            doc.close()
+
+
 def extract_text_from_pdf(pdf_bytes):
     """Extract text from a PDF using PyPDF2/pypdf.
 

models/ai_document_builder.py

@@ -206,20 +206,35 @@ def _ai_build_content(self, doc_info, raw_data, mimetype, vendor, company, extra
 
         # Build content blocks for the provider
         if doc_info.get('is_vision'):
-            media_type = ai_document.IMAGE_MIMES.get(mimetype, 'image/png')
+            user_content = []
             if ai_document.is_pdf(mimetype):
-                media_type = 'image/png'
-            user_content = [
-                {
-                    'type': 'image',
-                    'source': {
-                        'type': 'base64',
-                        'media_type': media_type,
-                        'data': base64.b64encode(raw_data).decode('ascii'),
-                    },
-                },
-                {'type': 'text', 'text': user_prompt},
-            ]
+                rendered_pages = ai_document.render_pdf_pages_for_vision(raw_data)
+                if not rendered_pages:
+                    return SYSTEM_PROMPT, [], user_prompt
+                for rendered_page in rendered_pages:
+                    user_content.append(
+                        {
+                            'type': 'image',
+                            'source': {
+                                'type': 'base64',
+                                'media_type': rendered_page['media_type'],
+                                'data': rendered_page['data'],
+                            },
+                        }
+                    )
+            else:
+                user_content.append(
+                    {
+                        'type': 'image',
+                        'source': {
+                            'type': 'base64',
+                            'media_type': ai_document.IMAGE_MIMES.get(mimetype, 'image/png'),
+                            'data': base64.b64encode(raw_data).decode('ascii'),
+                        },
+                    }
+                )
+            if user_content:
+                user_content.append({'type': 'text', 'text': user_prompt})
         else:
             doc_section = 'Document text:\n' + doc_info['text']
             if doc_info.get('table_markdown'):

models/ai_extraction_engine.py

@@ -155,6 +155,17 @@ def _ai_run_pipeline(self, api_key, cfg, raw_data, mimetype):
             preprocess_context=preprocess_context,
             cfg=cfg,
         )
+        if doc_info.get('is_vision') and not any(
+            isinstance(block, dict) and block.get('type') == 'image'
+            for block in user_content
+        ):
+            _logger.warning(
+                'Vision extraction unavailable: no rendered image content could be built '
+                'from invoice %s',
+                self.id,
+            )
+            self.ai_extraction_status = 'failed'
+            return None
 
         # --- 4b. Prompt size estimation -----------------------------------
         estimated_tokens = self._ai_estimate_prompt_tokens(system_prompt, user_prompt)
@@ -288,6 +299,10 @@ def _ai_retry_vision(self, api_key, cfg, raw_data):
             cfg['extract_lines'],
         )
 
+        if not any(isinstance(block, dict) and block.get('type') == 'image' for block in user_content):
+            _logger.warning('Vision retry unavailable: no rendered image content could be built from the PDF')
+            return None
+
         result = self._ai_call_provider(
             api_key, cfg, system_prompt, user_content, user_prompt, mode='vision',
         )

tests/test_extraction_modes.py

@@ -127,6 +127,53 @@ def test_free_mode_sends_no_context(self, mock_build_ctx):
 
         mock_build_ctx.assert_not_called()
 
+    @patch('odoo.addons.account_invoice_digitize_ai.models.ai_document.render_pdf_pages_for_vision')
+    @patch('odoo.addons.account_invoice_digitize_ai.models.ai_fiscal_context.build_fiscal_context')
+    def test_vision_pdf_uses_rendered_pages(self, mock_build_ctx, mock_render_pdf):
+        """Vision mode for PDFs should send rendered page images, not raw PDF bytes."""
+        self._set_mode('guided')
+        mock_build_ctx.return_value = 'full context'
+        mock_render_pdf.return_value = [
+            {'media_type': 'image/png', 'data': 'page-one'},
+            {'media_type': 'image/png', 'data': 'page-two'},
+        ]
+
+        doc_info = {'text': '', 'is_vision': True}
+        _system_prompt, user_content, _user_prompt = self.move._ai_build_content(
+            doc_info,
+            b'%PDF-1.7 fake',
+            'application/pdf',
+            self.partner,
+            self.company,
+            False,
+        )
+
+        image_blocks = [block for block in user_content if block.get('type') == 'image']
+        self.assertEqual(len(image_blocks), 2)
+        self.assertEqual(image_blocks[0]['source']['data'], 'page-one')
+        self.assertEqual(image_blocks[1]['source']['data'], 'page-two')
+        self.assertEqual(user_content[-1]['type'], 'text')
+
+    @patch('odoo.addons.account_invoice_digitize_ai.models.ai_document.render_pdf_pages_for_vision')
+    @patch('odoo.addons.account_invoice_digitize_ai.models.ai_fiscal_context.build_fiscal_context')
+    def test_vision_pdf_without_rendered_pages_returns_no_content(self, mock_build_ctx, mock_render_pdf):
+        """Vision mode should not build a prompt-only payload when PDF rendering fails."""
+        self._set_mode('guided')
+        mock_build_ctx.return_value = 'full context'
+        mock_render_pdf.return_value = []
+
+        doc_info = {'text': '', 'is_vision': True}
+        _system_prompt, user_content, _user_prompt = self.move._ai_build_content(
+            doc_info,
+            b'%PDF-1.7 fake',
+            'application/pdf',
+            self.partner,
+            self.company,
+            False,
+        )
+
+        self.assertEqual(user_content, [])
+
     # ---------------------------------------------------------------
     # Vendor memory in prompt
     # ---------------------------------------------------------------

tests/test_vision_retry.py

@@ -174,3 +174,47 @@ def test_retry_keeps_original_on_failure(self, _cv):
                 'user prompt', doc_info,
             )
         self.assertEqual(result['vendor']['name'], 'Test')
+
+    def test_retry_skips_when_pdf_cannot_be_rendered(self):
+        """Vision retry should bail out before the provider call if no page images are available."""
+        with (
+            patch(f'{_MODULE}.models.ai_document.extract_pdf_metadata', return_value={}),
+            patch(f'{_MODULE}.models.ai_document.extract_text_from_pdf', return_value='some text'),
+            patch.object(type(self.move), '_ai_extract_qr_data'),
+            patch.object(type(self.move), '_ai_pre_identify_vendor', return_value=None),
+            patch.object(
+                type(self.move),
+                '_ai_build_content',
+                return_value=('system', [{'type': 'text', 'text': 'prompt only'}], 'user prompt'),
+            ),
+            patch.object(type(self.move), '_ai_call_provider') as mock_call_provider,
+        ):
+            result = self.move._ai_retry_vision('test-key', _CFG, b'fake-pdf')
+        self.assertIsNone(result)
+        mock_call_provider.assert_not_called()
+
+    def test_initial_vision_skips_when_pdf_cannot_be_rendered(self):
+        """The primary vision path should also fail before the provider call if no page images are available."""
+        with (
+            patch.object(type(self.move), '_ai_try_facturx', return_value=None),
+            patch.object(
+                type(self.move),
+                '_ai_preprocess_or_prepare',
+                return_value=(None, {
+                    'text': '',
+                    'is_vision': True,
+                    'pdf_metadata': {},
+                    'detected_number_format': None,
+                    'table_markdown': '',
+                    'is_proforma': False,
+                    'unsupported': False,
+                    'qr_data': [],
+                }, ''),
+            ),
+            patch.object(type(self.move), '_ai_build_content', return_value=('system', [], 'user prompt')),
+            patch.object(type(self.move), '_ai_call_provider') as mock_call_provider,
+        ):
+            result = self.move._ai_run_pipeline('test-key', _CFG, b'fake-pdf', 'application/pdf')
+        self.assertIsNone(result)
+        self.assertEqual(self.move.ai_extraction_status, 'failed')
+        mock_call_provider.assert_not_called()