kreuzberg 3.14.1__py3-none-any.whl → 3.16.0__py3-none-any.whl

kreuzberg/_extractors/_pdf.py

@@ -1,38 +1,60 @@
 from __future__ import annotations
 
 import contextlib
+import io
+import logging
 import os
 import tempfile
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import asdict
+from itertools import count
 from multiprocessing import cpu_count
 from pathlib import Path
 from re import Pattern
 from re import compile as compile_regex
-from typing import TYPE_CHECKING, ClassVar, cast
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 import anyio
 import pypdfium2
 from anyio import Path as AsyncPath
 from playa import parse
+from playa.document import Document
+from playa.image import get_image_suffix_and_writer
 
+from kreuzberg._constants import PDF_POINTS_PER_INCH
 from kreuzberg._extractors._base import Extractor
 from kreuzberg._mime_types import PDF_MIME_TYPE, PLAIN_TEXT_MIME_TYPE
 from kreuzberg._ocr import get_ocr_backend
 from kreuzberg._playa import extract_pdf_metadata, extract_pdf_metadata_sync
-from kreuzberg._types import EasyOCRConfig, ExtractionResult, Metadata, OcrBackendType, PaddleOCRConfig, TesseractConfig
+from kreuzberg._types import (
+    EasyOCRConfig,
+    ExtractedImage,
+    ExtractionResult,
+    ImageOCRResult,
+    Metadata,
+    OcrBackendType,
+    PaddleOCRConfig,
+    TesseractConfig,
+)
 from kreuzberg._utils._errors import create_error_context, should_retry
 from kreuzberg._utils._image_preprocessing import calculate_optimal_dpi
-from kreuzberg._utils._pdf_lock import pypdfium_file_lock
+from kreuzberg._utils._resource_managers import pdf_document, pdf_document_sync, pdf_resources_sync
 from kreuzberg._utils._string import normalize_spaces
-from kreuzberg._utils._sync import run_sync, run_taskgroup_batched
+from kreuzberg._utils._sync import run_maybe_async, run_taskgroup, run_taskgroup_batched
 from kreuzberg._utils._table import generate_table_summary
-from kreuzberg._utils._tmp import create_temp_file
+from kreuzberg._utils._tmp import temporary_file, temporary_file_sync
 from kreuzberg.exceptions import ParsingError
 
 if TYPE_CHECKING:  # pragma: no cover
     from PIL.Image import Image
     from playa.document import Document
 
+logger = logging.getLogger(__name__)
+
+PDF_MAX_WORKERS = 8
+PDF_MAX_RETRY_ATTEMPTS = 3
+PDF_RETRY_DELAY_BASE = 0.5
+
 
 class PDFExtractor(Extractor):
     SUPPORTED_MIME_TYPES: ClassVar[set[str]] = {PDF_MIME_TYPE}
@@ -41,27 +63,26 @@ class PDFExtractor(Extractor):
     MINIMUM_CORRUPTED_RESULTS: ClassVar[int] = 2
 
     async def extract_bytes_async(self, content: bytes) -> ExtractionResult:
-        file_path, unlink = await create_temp_file(".pdf")
-        await AsyncPath(file_path).write_bytes(content)
-        try:
+        async with temporary_file(".pdf", content) as file_path:
             metadata = await self._extract_metadata_with_password_attempts(content)
             result = await self.extract_path_async(file_path)
-
             result.metadata = metadata
             return result
-        finally:
-            await unlink()
 
     async def extract_path_async(self, path: Path) -> ExtractionResult:
         content_bytes = await AsyncPath(path).read_bytes()
 
         result: ExtractionResult | None = None
 
+        document: Document | None = None
+        if self.config.extract_images or self.config.extract_tables:
+            document = self._parse_with_password_attempts(content_bytes)
+
         if not self.config.force_ocr:
             try:
                 content = await self._extract_pdf_searchable_text(path)
                 if self._validate_extracted_text(content):
-                    result = ExtractionResult(content=content, mime_type=PLAIN_TEXT_MIME_TYPE, metadata={}, chunks=[])
+                    result = ExtractionResult(content=content, mime_type=PLAIN_TEXT_MIME_TYPE, metadata={})
             except ParsingError:
                 pass
 
@@ -69,16 +90,18 @@ class PDFExtractor(Extractor):
             result = await self._extract_pdf_text_with_ocr(path, self.config.ocr_backend)
 
         if not result:
-            result = ExtractionResult(content="", mime_type=PLAIN_TEXT_MIME_TYPE, metadata={}, chunks=[])
+            result = ExtractionResult(content="", mime_type=PLAIN_TEXT_MIME_TYPE, metadata={})
 
-        result.metadata = await self._extract_metadata_with_password_attempts(content_bytes)
+        metadata = await self._extract_metadata_with_password_attempts(content_bytes)
+        result.metadata = metadata
 
         if self.config.extract_tables:
             # GMFT is optional dependency ~keep
             try:
                 from kreuzberg._gmft import extract_tables  # noqa: PLC0415
 
-                result.tables = await extract_tables(path, self.config.gmft_config)
+                tables = await extract_tables(path, self.config.gmft_config)
+                result.tables = tables
             except ImportError:  # pragma: no cover
                 result.tables = []
 
@@ -91,25 +114,30 @@ class PDFExtractor(Extractor):
                     f"{table_summary['total_rows']} total rows",
                 }
 
+        if self.config.extract_images and document:
+            images = await self._extract_images_from_playa(document)
+            images = self._check_image_memory_limits(images)
+            result.images = images
+            if self.config.ocr_extracted_images:
+                image_ocr_results = await self._process_images_with_ocr(result.images)
+                result.image_ocr_results = image_ocr_results
+
         return self._apply_quality_processing(result)
 
     def extract_bytes_sync(self, content: bytes) -> ExtractionResult:
-        fd, temp_path = tempfile.mkstemp(suffix=".pdf")
-        try:
-            with os.fdopen(fd, "wb") as f:
-                f.write(content)
-
-            result = self.extract_path_sync(Path(temp_path))
-
+        with temporary_file_sync(".pdf", content) as temp_path:
+            result = self.extract_path_sync(temp_path)
             metadata = self._extract_metadata_with_password_attempts_sync(content)
             result.metadata = metadata
-
             return result
-        finally:
-            with contextlib.suppress(OSError):
-                Path(temp_path).unlink()
 
     def extract_path_sync(self, path: Path) -> ExtractionResult:
+        content_bytes = path.read_bytes()
+
+        document: Document | None = None
+        if self.config.extract_images or self.config.extract_tables:
+            document = self._parse_with_password_attempts(content_bytes)
+
         try:
             text = self._extract_pdf_searchable_text_sync(path)
         except ParsingError:
@@ -137,8 +165,7 @@ class PDFExtractor(Extractor):
             content=text,
             mime_type=PLAIN_TEXT_MIME_TYPE,
             metadata={},
-            tables=tables,
-            chunks=[],
+            tables=list(tables),
         )
 
         if tables:
@@ -150,6 +177,14 @@ class PDFExtractor(Extractor):
                 f"{table_summary['total_rows']} total rows",
             }
 
+        if self.config.extract_images and document:
+            images = self._extract_images_from_playa_sync(document)
+            images = self._check_image_memory_limits(images)
+            result.images = images
+            if self.config.ocr_extracted_images:
+                image_ocr_results: list[ImageOCRResult] = run_maybe_async(self._process_images_with_ocr, result.images)
+                result.image_ocr_results = image_ocr_results
+
         return self._apply_quality_processing(result)
 
     def _validate_extracted_text(self, text: str, corruption_threshold: float = 0.05) -> bool:
@@ -163,14 +198,95 @@ class PDFExtractor(Extractor):
 
         return (len(corruption_matches) / len(text)) < corruption_threshold
 
+    async def _extract_images_from_playa(self, doc: Document) -> list[ExtractedImage]:
+        async def extract_single_image(page_num: int, img_index: int, img_obj: Any) -> ExtractedImage | None:
+            try:
+                suffix, writer = get_image_suffix_and_writer(img_obj.stream)
+
+                buffer = io.BytesIO()
+                writer(buffer)
+
+                filename = f"page_{page_num}_image_{img_index}{suffix}"
+
+                return ExtractedImage(
+                    data=buffer.getvalue(),
+                    format=suffix[1:],
+                    filename=filename,
+                    page_number=page_num,
+                    dimensions=img_obj.srcsize,
+                    colorspace=img_obj.colorspace.name if img_obj.colorspace else None,
+                    bits_per_component=img_obj.bits,
+                    is_mask=img_obj.imagemask,
+                )
+            except Exception as e:  # noqa: BLE001
+                logger.warning("Failed to extract image on page %s: %s", page_num, e)
+                return None
+
+        tasks = []
+        img_counter = 1
+        for page_num, page in enumerate(doc.pages, 1):
+            for img_obj in page.images:
+                tasks.append(extract_single_image(page_num, img_counter, img_obj))
+                img_counter += 1
+
+        if tasks:
+            results = await run_taskgroup(*tasks)
+            return [img for img in results if img is not None]
+
+        return []
+
+    def _extract_images_from_playa_sync(self, doc: Document) -> list[ExtractedImage]:
+        def extract_single_image(page_num: int, img_index: int, img_obj: Any) -> ExtractedImage | None:
+            try:
+                suffix, writer = get_image_suffix_and_writer(img_obj.stream)
+
+                buffer = io.BytesIO()
+                writer(buffer)
+
+                filename = f"page_{page_num}_image_{img_index}{suffix}"
+
+                return ExtractedImage(
+                    data=buffer.getvalue(),
+                    format=suffix[1:],
+                    filename=filename,
+                    page_number=page_num,
+                    dimensions=img_obj.srcsize,
+                    colorspace=img_obj.colorspace.name if img_obj.colorspace else None,
+                    bits_per_component=img_obj.bits,
+                    is_mask=img_obj.imagemask,
+                )
+            except Exception as e:  # noqa: BLE001
+                logger.warning("Failed to extract image on page %s: %s", page_num, e)
+                return None
+
+        img_counter = count(1)
+        jobs = [
+            (page_num, next(img_counter), img_obj)
+            for page_num, page in enumerate(doc.pages, 1)
+            for img_obj in page.images
+        ]
+
+        if not jobs:
+            return []
+
+        images = []
+        max_workers = min(PDF_MAX_WORKERS, len(jobs))
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = {executor.submit(extract_single_image, *job): i for i, job in enumerate(jobs)}
+            for future in as_completed(futures):
+                result = future.result()
+                if result:
+                    images.append(result)
+
+        images.sort(key=lambda x: int((x.filename or "page_0_image_0.jpg").split("_")[-1].split(".")[0]))
+        return images
+
     async def _convert_pdf_to_images(self, input_file: Path) -> list[Image]:
-        document: pypdfium2.PdfDocument | None = None
         last_error = None
 
-        for attempt in range(3):  # Try up to 3 times  # ~keep
+        for attempt in range(PDF_MAX_RETRY_ATTEMPTS):  # ~keep
             try:
-                with pypdfium_file_lock(input_file):
-                    document = await run_sync(pypdfium2.PdfDocument, str(input_file))
+                async with pdf_document(input_file) as document:
                     images = []
                     for page in cast("pypdfium2.PdfDocument", document):
                         width, height = page.get_size()
@@ -187,9 +303,12 @@ class PDFExtractor(Extractor):
                         else:
                             optimal_dpi = self.config.target_dpi
 
-                        scale = optimal_dpi / 72.0
+                        scale = optimal_dpi / PDF_POINTS_PER_INCH
 
-                        images.append(page.render(scale=scale).to_pil())
+                        bitmap = page.render(scale=scale)
+                        image = bitmap.to_pil()
+                        with pdf_resources_sync(bitmap):
+                            images.append(image)
                     return images
             except pypdfium2.PdfiumError as e:  # noqa: PERF203
                 last_error = e
@@ -204,11 +323,7 @@ class PDFExtractor(Extractor):
                         ),
                     ) from e
                 # Wait before retry with exponential backoff  # ~keep
-                await anyio.sleep(0.5 * (attempt + 1))
-            finally:
-                if document:
-                    with pypdfium_file_lock(input_file), contextlib.suppress(Exception):
-                        await run_sync(document.close)
+                await anyio.sleep(PDF_RETRY_DELAY_BASE * (attempt + 1))
 
         # All retries failed  # ~keep
         raise ParsingError(
@@ -217,7 +332,7 @@ class PDFExtractor(Extractor):
                 operation="convert_pdf_to_images",
                 file_path=input_file,
                 error=last_error,
-                attempts=3,
+                attempts=PDF_MAX_RETRY_ATTEMPTS,
             ),
         ) from last_error
 
@@ -230,14 +345,12 @@ class PDFExtractor(Extractor):
         )
         content = "\n".join(result.content for result in ocr_results)
 
-        return ExtractionResult(content=content, mime_type=PLAIN_TEXT_MIME_TYPE, metadata={}, chunks=[])
+        return ExtractionResult(content=content, mime_type=PLAIN_TEXT_MIME_TYPE, metadata={})
 
     @staticmethod
     async def _extract_pdf_searchable_text(input_file: Path) -> str:
-        document: pypdfium2.PdfDocument | None = None
         try:
-            with pypdfium_file_lock(input_file):
-                document = await run_sync(pypdfium2.PdfDocument, str(input_file))
+            async with pdf_document(input_file) as document:
                 pages_content = []
                 page_errors = []
 
@@ -246,6 +359,8 @@ class PDFExtractor(Extractor):
                         text_page = page.get_textpage()
                         page_content = text_page.get_text_bounded()
                         pages_content.append(page_content)
+                        with pdf_resources_sync(text_page):
+                            pass
                     except Exception as e:  # noqa: PERF203, BLE001
                         page_errors.append({"page": i + 1, "error": str(e)})
                         pages_content.append(f"[Error extracting page {i + 1}]")
@@ -275,52 +390,67 @@ class PDFExtractor(Extractor):
                     error=e,
                 ),
             ) from e
-        finally:
-            if document:
-                with pypdfium_file_lock(input_file), contextlib.suppress(Exception):
-                    await run_sync(document.close)
 
     def _extract_pdf_searchable_text_sync(self, path: Path) -> str:
-        pdf = None
         try:
-            with pypdfium_file_lock(path):
-                pdf = pypdfium2.PdfDocument(str(path))
+            with pdf_document_sync(path) as pdf:
                 pages_text = []
                 for page in pdf:
                     text_page = page.get_textpage()
                     text = text_page.get_text_bounded()
                     pages_text.append(text)
-                    text_page.close()
-                    page.close()
+                    with pdf_resources_sync(text_page, page):
+                        pass
                 return "\n".join(pages_text)
         except Exception as e:
             raise ParsingError(f"Failed to extract PDF text: {e}") from e
-        finally:
-            if pdf:
-                with pypdfium_file_lock(path), contextlib.suppress(Exception):
-                    pdf.close()
 
     def _extract_pdf_with_ocr_sync(self, path: Path) -> str:
-        pdf = None
+        temp_files: list[Path] = []
         try:
-            images = []
-            with pypdfium_file_lock(path):
-                pdf = pypdfium2.PdfDocument(str(path))
+            with pdf_document_sync(path) as pdf:
                 for page in pdf:
-                    bitmap = page.render(scale=200 / 72)
+                    width, height = page.get_size()
+
+                    if self.config.auto_adjust_dpi:
+                        optimal_dpi = calculate_optimal_dpi(
+                            page_width=width,
+                            page_height=height,
+                            target_dpi=self.config.target_dpi,
+                            max_dimension=self.config.max_image_dimension,
+                            min_dpi=self.config.min_dpi,
+                            max_dpi=self.config.max_dpi,
+                        )
+                    else:
+                        optimal_dpi = self.config.target_dpi
+
+                    scale = optimal_dpi / PDF_POINTS_PER_INCH
+
+                    bitmap = page.render(scale=scale)
                     pil_image = bitmap.to_pil()
-                    images.append(pil_image)
-                    bitmap.close()
-                    page.close()
 
-            return self._process_pdf_images_with_ocr_direct(images)
+                    fd, tmp = tempfile.mkstemp(suffix=".png")
+                    try:
+                        os.close(fd)
+                        tmp_path = Path(tmp)
+                        pil_image.save(tmp_path)
+                        temp_files.append(tmp_path)
+                    except Exception:
+                        with contextlib.suppress(OSError):
+                            os.close(fd)
+                        raise
+                    finally:
+                        with pdf_resources_sync(bitmap, page):
+                            pil_image.close()
+
+            return self._process_pdf_images_with_ocr([str(p) for p in temp_files])
 
         except Exception as e:
             raise ParsingError(f"Failed to OCR PDF: {e}") from e
         finally:
-            if pdf:
-                with pypdfium_file_lock(path), contextlib.suppress(Exception):
-                    pdf.close()
+            for p in temp_files:
+                with contextlib.suppress(OSError):
+                    p.unlink()
 
     def _process_pdf_images_with_ocr(self, image_paths: list[str]) -> str:
         backend = get_ocr_backend(self.config.ocr_backend)
@@ -348,35 +478,12 @@ class PDFExtractor(Extractor):
         return "\n\n".join(result.content for result in results)
 
     def _process_pdf_images_with_ocr_direct(self, images: list[Image]) -> str:
+        if not self.config.ocr_backend:
+            raise ValueError("OCR backend must be specified")
         backend = get_ocr_backend(self.config.ocr_backend)
+        config = self._prepare_ocr_config(self.config.ocr_backend)
 
-        match self.config.ocr_backend:
-            case "tesseract":
-                config = (
-                    self.config.ocr_config if isinstance(self.config.ocr_config, TesseractConfig) else TesseractConfig()
-                )
-                results = []
-                for image in images:
-                    result = backend.process_image_sync(image, **asdict(config))
-                    results.append(result)
-            case "paddleocr":
-                paddle_config = (
-                    self.config.ocr_config if isinstance(self.config.ocr_config, PaddleOCRConfig) else PaddleOCRConfig()
-                )
-                results = []
-                for image in images:
-                    result = backend.process_image_sync(image, **asdict(paddle_config))
-                    results.append(result)
-            case "easyocr":
-                easy_config = (
-                    self.config.ocr_config if isinstance(self.config.ocr_config, EasyOCRConfig) else EasyOCRConfig()
-                )
-                results = []
-                for image in images:
-                    result = backend.process_image_sync(image, **asdict(easy_config))
-                    results.append(result)
-            case _:
-                raise NotImplementedError(f"Direct image OCR not implemented for {self.config.ocr_backend}")
+        results = [backend.process_image_sync(image, **config) for image in images]
 
         return "\n\n".join(result.content for result in results)
 
@@ -390,9 +497,11 @@ class PDFExtractor(Extractor):
         for password in passwords:
             try:
                 return parse(content, max_workers=1, password=password)
-            except Exception as e:  # noqa: PERF203, BLE001
+            except (ValueError, TypeError, KeyError, RuntimeError) as e:  # noqa: PERF203
                 last_exception = e
                 continue
+            except OSError as e:
+                raise ParsingError(f"Failed to parse PDF: {e}") from e
 
         if last_exception:
             raise last_exception from None
@@ -411,7 +520,7 @@ class PDFExtractor(Extractor):
         for password in passwords:
             try:
                 return await extract_pdf_metadata(content, password=password)
-            except Exception as e:  # noqa: PERF203, BLE001
+            except (ParsingError, ValueError, TypeError, OSError) as e:  # noqa: PERF203
                 last_exception = e
                 continue
 
@@ -429,7 +538,7 @@ class PDFExtractor(Extractor):
         for password in passwords:
             try:
                 return extract_pdf_metadata_sync(content, password=password)
-            except Exception as e:  # noqa: PERF203, BLE001
+            except (ParsingError, ValueError, TypeError, OSError) as e:  # noqa: PERF203
                 last_exception = e
                 continue
 

kreuzberg/_extractors/_presentation.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
+import logging
 import re
 from contextlib import suppress
 from html import escape
 from io import BytesIO
 from pathlib import Path
-from typing import TYPE_CHECKING, ClassVar
+from typing import TYPE_CHECKING, Any, ClassVar
 
 import pptx
 from anyio import Path as AsyncPath
@@ -13,8 +14,9 @@ from pptx.enum.shapes import MSO_SHAPE_TYPE
 
 from kreuzberg._extractors._base import Extractor
 from kreuzberg._mime_types import MARKDOWN_MIME_TYPE, POWER_POINT_MIME_TYPE
-from kreuzberg._types import ExtractionResult
+from kreuzberg._types import ExtractedImage, ExtractionResult, ImageOCRResult
 from kreuzberg._utils._string import normalize_spaces
+from kreuzberg._utils._sync import run_maybe_async
 
 if TYPE_CHECKING:  # pragma: no cover
     from pptx.presentation import Presentation
@@ -23,23 +25,41 @@ if TYPE_CHECKING:  # pragma: no cover
 
 _NON_WORD_PATTERN = re.compile(r"\W")
 
+logger = logging.getLogger(__name__)
+
 
 class PresentationExtractor(Extractor):
     SUPPORTED_MIME_TYPES: ClassVar[set[str]] = {POWER_POINT_MIME_TYPE}
 
     async def extract_bytes_async(self, content: bytes) -> ExtractionResult:
-        return self._extract_pptx(content)
+        result = self._extract_pptx(content)
+        if self.config.extract_images and self.config.ocr_extracted_images and result.images:
+            image_ocr_results = await self._process_images_with_ocr(result.images)
+            result.image_ocr_results = image_ocr_results
+        return result
 
     async def extract_path_async(self, path: Path) -> ExtractionResult:
         content = await AsyncPath(path).read_bytes()
-        return self._extract_pptx(content)
+        result = self._extract_pptx(content)
+        if self.config.extract_images and self.config.ocr_extracted_images and result.images:
+            image_ocr_results = await self._process_images_with_ocr(result.images)
+            result.image_ocr_results = image_ocr_results
+        return result
 
     def extract_bytes_sync(self, content: bytes) -> ExtractionResult:
-        return self._extract_pptx(content)
+        result = self._extract_pptx(content)
+        if self.config.extract_images and self.config.ocr_extracted_images and result.images:
+            image_ocr_results: list[ImageOCRResult] = run_maybe_async(self._process_images_with_ocr, result.images)
+            result.image_ocr_results = image_ocr_results
+        return result
 
     def extract_path_sync(self, path: Path) -> ExtractionResult:
         content = Path(path).read_bytes()
-        return self._extract_pptx(content)
+        result = self._extract_pptx(content)
+        if self.config.extract_images and self.config.ocr_extracted_images and result.images:
+            image_ocr_results: list[ImageOCRResult] = run_maybe_async(self._process_images_with_ocr, result.images)
+            result.image_ocr_results = image_ocr_results
+        return result
 
     def _extract_pptx(self, file_contents: bytes) -> ExtractionResult:
         md_content = ""
@@ -63,8 +83,10 @@ class PresentationExtractor(Extractor):
                     with suppress(AttributeError):
                         alt_text = shape._element._nvXxPr.cNvPr.attrib.get("descr", "")  # noqa: SLF001
 
-                    filename = _NON_WORD_PATTERN.sub("", shape.name) + ".jpg"
-                    md_content += f"\n![{alt_text if alt_text else shape.name}]({filename})\n"
+                    name_val = shape.name if isinstance(getattr(shape, "name", None), str) else "image"
+                    filename = _NON_WORD_PATTERN.sub("", name_val) + ".jpg"
+                    label = alt_text if alt_text else name_val
+                    md_content += f"\n![{label}]({filename})\n"
 
                 elif shape.shape_type == MSO_SHAPE_TYPE.TABLE:
                     html_table = "<table>"
@@ -106,8 +128,54 @@ class PresentationExtractor(Extractor):
             chunks=[],
         )
 
+        if self.config.extract_images:
+            images = self._extract_images_from_pptx(presentation)
+            result.images = images
+
         return self._apply_quality_processing(result)
 
+    def _extract_images_from_pptx(self, presentation: Presentation) -> list[ExtractedImage]:
+        images: list[ExtractedImage] = []
+
+        for slide_num, slide in enumerate(presentation.slides, 1):
+            for shape in slide.shapes:
+                if shape.shape_type == MSO_SHAPE_TYPE.PICTURE:
+                    try:
+                        image = shape.image
+                        if not image.blob or not isinstance(image.blob, bytes):
+                            continue
+                        filename = f"slide_{slide_num}_image_{len(images) + 1}.{image.ext}"
+
+                        images.append(
+                            ExtractedImage(data=image.blob, format=image.ext, filename=filename, page_number=slide_num)
+                        )
+                    except Exception as e:  # noqa: BLE001
+                        logger.warning("Failed to extract image from slide %s: %s", slide_num, e)
+                        continue
+
+                elif shape.shape_type == MSO_SHAPE_TYPE.GROUP:
+                    images.extend(self._extract_from_grouped_shapes(shape, slide_num, len(images)))
+
+        return images
+
+    def _extract_from_grouped_shapes(self, group_shape: Any, slide_num: int, image_count: int) -> list[ExtractedImage]:
+        images: list[ExtractedImage] = []
+        for shape in group_shape.shapes:
+            if shape.shape_type == MSO_SHAPE_TYPE.PICTURE:
+                try:
+                    image = shape.image
+                    if not image.blob or not isinstance(image.blob, bytes):
+                        continue
+                    filename = f"slide_{slide_num}_group_image_{image_count + len(images) + 1}.{image.ext}"
+                    images.append(
+                        ExtractedImage(data=image.blob, format=image.ext, filename=filename, page_number=slide_num)
+                    )
+                except Exception as e:  # noqa: BLE001
+                    logger.warning("Failed to extract grouped image: %s", e)
+            elif shape.shape_type == MSO_SHAPE_TYPE.GROUP:
+                images.extend(self._extract_from_grouped_shapes(shape, slide_num, image_count + len(images)))
+        return images
+
     @staticmethod
     def _extract_presentation_metadata(presentation: Presentation) -> Metadata:
         metadata: Metadata = {}